企业官网建设流程全解析

Mastra Factory 实战指南：从 Issue 到已评审 Pull Request 的编码 Agent 环境搭建

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

导读

Mastra Factory 是 Mastra 开源生态中一套面向编码 Agent（coding agents）的软件交付环境：把 GitHub 仓库接入后，一个 Issue 可以被自动转化为实现计划、代码实现，直至生成经过评审的 Pull Request。本文以create-factory脚手架生成的 Factory Server 项目（mastracode/mastra-factory/template/README.md）为主线，完整讲解项目初始化、凭据加密、启动登录、首个 Issue 全流程、逐项配置、两种部署方式、内置脚本与常见故障排查，并结合 mastracode/mastra-factory 与 mastracode/factory 的源码，带你看到脚手架背后的自动化供给（platform provisioning）与 Factory 后端的模块化设计。读完本文，你将能独立部署一套可运行、可定制、可上生产的 Mastra Factory 实例。

Mastra Factory 是什么

Mastra Factory 是一个开源的"用编码 Agent 构建软件"的环境。它的核心工作流是：

1. 连接你的代码仓库（GitHub）；
2. 把 Issue 变成计划（plan）——由 Agent 调查、理解并输出实施方案；
3. 把计划变成实现（implementation）——Agent 在沙箱中写代码；
4. 把实现变成已评审的 Pull Request（reviewed pull request）——自动创建 PR 并经历代码评审关卡。

整个项目由create-factory这个 npm 脚手架创建（包名create-factory，见 mastracode/mastra-factory/package.json）。生成的项目包含 Factory Server 与其配置，需要与你想让 Agent 修改的仓库分开存放——Factory 本身是一个独立运行的服务器，而不是嵌入到业务仓库中的代码。

从仓库结构看，Mastra Factory 由多个包协同组成：

• mastracode/mastra-factory：create-factory脚手架 CLI 与模板，负责项目生成；
• mastracode/factory：@mastra/factory可复用后端，拥有存储领域（storage domains）、路由（routes）、规则（rules）、集成（integrations）、沙箱（sandboxes）与 Factory 专属的 Agent 行为；
• mastracode/factory-ui：Factory 的 React 前端；
• mastracode/web：宿主（host）接线层，mastracode/web/src/mastra/index.ts是规范的宿主示例；
• mastracode/sdk：共享的 Agent 控制器行为。

创建 Factory 项目

环境要求与安装命令

脚手架要求Node.js 22.13.0 或更高版本（对应create-factory的engines.node字段，见 mastracode/mastra-factory/package.json）。使用任意主流包管理器均可：

# npm npx create-factory@latest # Yarn yarn dlx create-factory@latest # pnpm pnpm create factory@latest

交互式初始化到底做了什么

脚手架背后并不只是"拷一份模板"，mastracode/mastra-factory/src/create.ts 中的create()流程依次完成：

1. 询问项目名，并校验目录不存在；
2. 克隆模板：cloneTemplate()优先用npx degit拉取默认模板仓库，失败则回退git clone后移除.git（见 mastracode/mastra-factory/src/utils/clone.ts）；
3. 改名：把模板package.json的 name 改写为你的项目名（toPackageName会做合法 npm 包名清洗）；
4. 复制.env.example为.env并立即收紧为0600权限，为后续写入密钥做准备；
5. 安装依赖：自动探测包管理器（npm/pnpm/yarn/bun，见 mastracode/mastra-factory/src/utils/pm.ts）并执行 install；
6. 平台供给（platform provisioning）：默认开启（见下文）；
7. Git 初始化：先把.env追加进.gitignore（ensureEnvGitignored），再git init && git add -A && git commit。如果.gitignore写失败，脚手架宁可跳过 git init也不会把平台密钥提交进历史——这点在源码注释中被明确视为"必须 fatal"的边界。

默认的平台供给与 --no-platform

默认情况下，安装向导会调用 Mastra 平台服务，用于认证、存储与沙箱。供给流程（runPlatformProvisioning）完整走一遍浏览器登录 → 选择组织 → 选择区域（eu/us）→ 创建平台项目 → 铸造sk_组织级 API Key → 配置生产环境 → 挂载 Neon Postgres 并轮询就绪 → 回写.env：

• MASTRA_ORGANIZATION_ID
• MASTRA_PROJECT_ID
• MASTRA_PLATFORM_SECRET_KEY（sk_开头的密钥，平台只展示一次，所以脚手架把它先累积到内存再一次性刷入.env）
• MASTRA_ENVIRONMENT_ID
• DATABASE_URL（Neon 的 Postgres 连接串）

如果你希望完全自托管、不依赖平台，可以在创建时跳过平台供给：

npx create-factory@latest -- --no-platform

跳过平台后，认证、存储、沙箱三个服务都可以各自独立替换：本地自托管、或继续用平台、或混搭（例如存储与认证用平台、沙箱用本地）。这是 Factory 设计上刻意保持的灵活性——"Using Mastra platform services is optional"。

CLI 完整选项

运行npx create-factory@latest --help可以看到全部选项（对应 mastracode/mastra-factory/src/index.ts 中 commander 的定义）：

启动 Factory Server

第一步：准备凭据加密密钥

在连接模型提供商之前，先检查.env中是否存在FACTORY_CREDENTIAL_ENCRYPTION_KEY。若缺失，为本项目一次性生成一个密钥：

openssl rand -base64 32

把输出保存为.env中的FACTORY_CREDENTIAL_ENCRYPTION_KEY。这条密钥用于静态加密存储的模型提供商密钥、自定义提供商 API Key 与集成密钥，需要：

• 在每次重启和部署之间保持不变（否则已加密的凭据将无法解密）；
• 妥善备份并受保护存放。

从源码看，mastracode/factory/src/factory.ts 的prepare()中：当启用了认证但未提供secretEncryption时，会打印一条启动警告，说明持久化的模型凭据将以明文存储——因此FACTORY_CREDENTIAL_ENCRYPTION_KEY是生产环境的推荐配置，而不是可选项。

第二步：启动开发服务器

从 Factory 项目目录启动：

npm run dev

默认配置下，服务器会打印一个本地 URL，打开后通过 Mastra 平台登录。一个服务器同时提供 Factory UI 与 API（默认端口4111，对应publicUrl默认值http://localhost:4111，相关变更记录在 mastracode/factory/CHANGELOG.md）。

登录后你会看到引导向导（onboarding wizard），在其中选择 Agent 应修改的仓库。如果仓库未出现，用Manage GitHub connection授权 GitHub App 访问；可选地接入 Linear。随后连接模型提供商（用 API Key 或支持的订阅），并选择 Factory 使用的模型。

如果你在安装时跳过了平台设置，则参考官方 Get started 文档自行配置替代的认证、存储与沙箱提供商。

跑通你的第一个 Issue

以"Issue → 计划 → 实现 → 已评审 PR"的完整链路为目标，按下面三步走：

1. 打开Settings → Work Intake → GitHub issues，启用Sync GitHub issues并选择你的仓库。每个团队成员可以各自选择自己的 Issue 来源。
2. 创建一个小的 GitHub Issue，例如"为仓库 README 增加贡献指南（contribution guidance）"。
3. 在Work → Intake中找到该 Issue，选择Investigate（调查），打开其会话跟随 Agent 的工作过程。

之后继续官方提供的"issue-to-pull-request"演练，即可看到 Agent 输出计划、人工评审计划、进入实现、最终创建并走完 PR 评审。

从源码理解 Issue 的旅程

@mastra/factory的后端把这条链路实现为看板（Board）驱动的状态机。默认安装 Work 与 Review 两块板（见 mastracode/factory/src/boards/work.ts 与 mastracode/factory/src/boards/review.ts）：

• Work 板：intake（resting）→triage/planning/execute/review（working，角色分别为triage、plan、work、work）→done/canceled（terminal）；
• Review 板：intake（resting）→review（working，角色review）→done/canceled（terminal）。

Board 的三种阶段语义（见 mastracode/factory/README.md 的 "Board phase semantics" 一节）：

• resting：卡片停泊，人工将卡片移出 resting 阶段会"武装"自主权，移回则"解除"；
• working：Agent 座位（seat）持有卡片，必须声明role；
• terminal：卡片完成，进入该阶段会释放沙箱并允许清理机制取代过期决策。

GitHub 集成（mastracode/factory/src/integrations/github）负责事件驱动：Issue 打开、评论、label 变化等 webhook 会把卡片在 Work 与路由看板之间移动，并刷新标签元数据。Work 板还内置了submit_plan工具结果规则：当 Planning 座位上的 Agent 返回以Plan approved.开头的结果时，卡片自动流转到 Execute。

配置你的 Factory

配置总览

认证、存储、沙箱可以独立选择；模型提供商与 Issue 来源通过 Factory UI 配置；服务器设置都存放在.env中，修改后需要重启服务器生效。

存储：PostgreSQL + pgvector

生成的服务器使用DATABASE_URL连接PostgreSQL（带 pgvector）。要使用随项目附带的本地 PostgreSQL 服务，运行：

npm run db:up

然后在.env中把DATABASE_URL设为它的连接串。生成的docker-compose.yml里包含完整连接设置；不需要时用npm run db:down停止。

从后端看，MastraFactory的构造要求必须传入storage——一个FactoryStorage后端，例如PgFactoryStorage（部署用）或LibSQLFactoryStorage（本地开发用）。prepare()会在该存储上注册全部领域表：Intake、Audit、WorkItems、ModelCredentials、ModelPacks、MemorySettings、CustomProviders、QueueHealth、Integrations、FactoryProjects、Filesystem、SourceControl、ChannelIdentity、WorkItemComments 等（见 mastracode/factory/src/factory.ts 的prepare()）。

沙箱：平台、本地与 SANDBOX_PROVIDER

Mastra 平台沙箱使用MASTRA_PLATFORM_ACCESS_TOKEN或MASTRA_PLATFORM_SECRET_KEY，配合MASTRA_PROJECT_ID与MASTRA_ENVIRONMENT_ID。

如果希望命令直接运行在 Factory Server 所在机器上，在.env中加入这个覆盖项：

FACTORY_SANDBOX_PROVIDER=local

使用本地沙箱时，需要在该机器上安装 Git 和你的仓库构建工具。注意：认证与存储可以继续使用 Mastra 平台——这就是"每个服务独立替换"的体现。另外还有一个单独的SANDBOX_PROVIDER设置，它选择的是Mastra 平台沙箱所使用的后端，与FACTORY_SANDBOX_PROVIDER（Factory Server 自身如何执行命令）是两个不同的开关。

部署

方式一：部署到 Mastra 平台

将 Factory Server 部署到你的 Mastra 平台项目：

npm run deploy

CLI 会输出部署后的 Factory URL。平台部署适合不想维护服务器基础设施、且已在使用平台服务的团队。

方式二：自托管（Self-host）

在虚拟机或容器中把 Factory 作为持久化 Node.js 服务运行：

1. 配置持久化存储（如上述 Postgres）；
2. 设置MASTRACODE_PUBLIC_URL为公网HTTPS origin（注意与PORT保持一致，并同步更新任何认证/集成 App 的回调 URL）；
3. 通过部署环境提供你的提供商凭据；
4. 构建并启动：

npm run build npm run start

注意：npm run build/npm run start依赖生成项目自带的 CLI 依赖，需要保持其安装。自托管时依然可以使用 Mastra 平台服务（例如认证与沙箱走平台、服务器本体自己托管）。

关于MASTRACODE_PUBLIC_URL：它决定 OAuth 回调 URL 与认证重定向的 origin。默认值为http://localhost:4111（Factory 服务器同时服务 UI 与 API）；如果你把 SPA 部署在独立 origin（如 Vite 开发服务器的 5173 端口），必须显式设置它。

内置脚本速查

故障排查

• 运行时：使用与项目package.json中engines.node匹配的 Node.js 版本（当前要求 >= 22.13.0）。
• 端口变更：设置PORT并同步更新MASTRACODE_PUBLIC_URL，同时更新你管理的所有认证/集成 App 的回调 URL。
• Issue 缺失：检查仓库访问权限与Work Intake中的选择。GitHub 集成只有在仓库被绑定（routing）到某块看板后，才会作为候选 feed 提供；GitHub 上未路由的 Issue 默认进入 Work 板。也可以从 Intake 排障指南查看 intake 为空的相关处理。

其它登录、提供商访问与沙箱错误，参考官方的 Troubleshooting 与 Environment variables（服务器设置）文档页。

进阶：理解 Factory 的模块化架构

如果你打算深入定制，了解下面几个设计要点会很有帮助：

宿主接线模式：宿主应用调用MastraFactory.prepare()，然后构造Mastra实例（new Mastra(...)必须留在宿主入口文件中，Mastra 的 deployer 才能检测并打包它），最后调用MastraFactory.finalize()。mastracode/web/src/mastra/index.ts 是规范的宿主示例。

看板自定义：通过defineBoard()可以声明自定义看板，指定initialPhase（必须为 resting）、各 phase 的kind与 working phase 的role，以及transitionPolicy（转移策略，可要求人工批准）与onEnter/onExit生命周期处理器、tools.onResult工具结果规则。默认的 Work 与 Review 会自动安装；设置includeDefaultBoards: false可只安装自定义看板，但work与review两个 ID 是保留的。

集成事件规则：GitHub 与 Linear 集成的事件处理器（如issueOpened、issueCommentCreated、issueObserved、issueClosed）可以通过集成构造器的rules选项替换（函数替换默认处理器）或禁用（null），不再有全局 rules 对象——每个规则都有唯一所有者：看板拥有生命周期/转移策略/阶段语义/工具结果规则，集成拥有事件处理器。

配置版本：configVersion是运维维护的部署标签，盖在转移审计行、延迟决策与会话 kickoff 头上，用于把审计记录追溯到产生它的部署，默认值为factory-config-v1。

许可

Mastra Factory 模板项目以Apache-2.0协议开源（见 mastracode/mastra-factory/template/README.md 的 License 一节，以及 mastracode/mastra-factory/package.json 中的license字段）。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra