使用 create-factory 快速搭建 Mastra Factory编码 Agent 驱动的软件开发环境【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra Factory 是 Mastra 开源生态中面向用编码 Agent 构建软件的运行环境连接你的代码仓库即可把 GitHub Issue 转化为实现计划、代码实现与可评审的 Pull Request。create-factory正是官方推荐的脚手架 CLI一条命令即可完成模板克隆、依赖安装、平台资源开通与 Git 仓库初始化。本文以 mastracode/mastra-factory/README.md 为主线结合该包的源码实现完整讲解安装、交互式配置、命令行参数、平台资源自动开通原理以及部署与排障实践。前置条件与安装create-factory要求本机已安装Node.js 22.13.0 或更高版本与包的engines声明一致见 package.json。无需手动全局安装直接通过包管理器运行最新版本即可。使用 npmnpx create-factorylatest使用 Yarnyarn dlx create-factorylatest使用 pnpmpnpm create factorylatest三种方式最终都会执行同一个 CLI 入口包的bin字段指向./dist/index.js即 src/index.ts。无论你使用哪种包管理器脚手架内部都会依据npm_config_user_agent/npm_execpath自动识别当前包管理器并用它来安装新项目的依赖见 src/utils/pm.ts。交互式初始化流程运行create-factory后进入交互式向导。整个过程大致分为四步与 src/create.ts 中create()函数的执行顺序一一对应项目命名提示输入项目名默认占位my-mastra-factory。名称不能为空若同名目录已存在会直接报错。克隆模板从默认模板仓库mastra-ai/softwarefactory-template拉取项目骨架。实现上优先使用degit浅层拉取失败时回退到git clone并移除.git目录随后把生成的package.json中的name改写为你的项目名见 src/utils/clone.ts。模板拉取成功后template/.env.example会被复制为.env并收紧文件权限为0600。安装依赖在项目目录中调用检测到的包管理器执行installnpm 额外附加--no-audit --no-fund。平台资源配置默认情况下向导会登录 Mastra 平台自动开通一系列云资源详见下一节。Git 初始化先确保.env已被.gitignore覆盖再执行git init、git add -A与首次提交提交信息为Initial commit from create-factory。完成后终端会输出后续步骤cd 项目名后运行npm run devFactory UI 默认地址为http://localhost:4111。一个值得注意的安全细节脚手架在初始化 Git 仓库之前会主动检查.gitignore是否已包含.env或.env*。如果无法写入.gitignore它会跳过整个 git init 流程避免把刚写入的平台密钥提交进历史并提示你手动添加.env后再初始化见 src/create.ts 中ensureEnvGitignored的实现。平台资源自动开通脚手架做了什么这是create-factory最有价值的部分。除非你显式跳过向导会在初始化时完成一整条平台开通链路实现见 src/platform.ts 与 src/create.ts 的runPlatformProvisioning认证若本机没有缓存的登录凭证也没有设置MASTRA_API_TOKEN会先打开浏览器完成 Mastra 平台登录。组织选择默认每次都会弹出组织选择器若传入--org id 或名称则跳过交互按 id 或精确名称匹配非子串匹配找不到会列出可用组织并报错。创建平台项目调用POST /v1/server/projects创建服务器项目请求体中包含factoryEnabled: true。铸造 API Key调用POST /v1/auth/tokens铸造一把sk_开头的 WorkOS 组织级密钥。平台只展示一次明文因此脚手架会立刻把它记入待写入.env的缓冲区。生产环境查询项目的production环境不存在则自动创建。Neon 数据库调用POST /v1/server/projects/:id/databases挂载 Neon Postgres区域与项目区域联动eu → aws-eu-central-1、us → aws-us-west-2随后以默认 2 秒间隔轮询状态最长等待 60 秒直至数据库ready后拉取连接串。写入.env把上述MASTRA_ORGANIZATION_ID、MASTRA_PROJECT_ID、MASTRA_PLATFORM_SECRET_KEY、MASTRA_ENVIRONMENT_ID、DATABASE_URL等键值幂等地写入.env——已存在的键会被替换缺失的键追加到文件末尾见 src/env.ts 的upsertEnvFile。即使中途某个步骤失败finally块也会把已成功铸造的凭据先写入.env避免sk_密钥因流程中断而永久丢失。注意挂载 Neon 数据库需要组织内的admin 角色非管理员成员会收到 403 提示需请组织管理员执行脚手架或改从控制台挂载数据库。由于平台只展示一次密钥明文脚手架在向分析系统上报错误时会对错误信息做脱敏[redacted]过滤掉自定义模板 URL、--org/--region等敏感值及 URL 中可能内嵌的凭据但用户终端仍能看到完整错误见 src/utils/redact.ts。CLI 参数参考参数说明[project-name]项目目录名位置参数省略时进入交互式命名--template template-name指定模板仓库公开 GitHub URL默认mastra-ai/softwarefactory-template--no-platform跳过平台登录、项目创建与 Neon 数据库开通适合本地/自托管或离线脚手架场景--org orgMastra 组织 id 或名称跳过交互式组织选择器--region region平台项目区域仅接受eu或us省略时交互式询问-v, --version输出版本号--help查看全部选项通过--help可随时查看完整选项列表npx create-factorylatest --help若你希望完全在本地运行不使用平台云能力推荐使用--no-platformnpx create-factorylatest -- --no-platform注意在 npm 下需要用--分隔确保--no-platform传给 CLI 而不是被 npm 自身消费。该模式下模板的.env.example会原样保留你需要手动配置.env后再启动。启动 Factory 服务器与首次运行脚手架生成的项目即Factory Server其使用说明完整记录在 mastracode/mastra-factory/template/README.md 中要点如下。1. 检查凭据加密密钥连接模型提供商之前请确认.env中存在FACTORY_CREDENTIAL_ENCRYPTION_KEY。若缺失为该项目生成一次并保存openssl rand -base64 32把输出写入.env的FACTORY_CREDENTIAL_ENCRYPTION_KEY。该密钥用于加密存储的凭据必须跨重启与部署保持一致并妥善备份。2. 启动本地服务器npm run dev默认配置下打开终端打印的本地地址Factory UI 为http://localhost:4111通过 Mastra 平台登录。一个服务器同时提供 Factory UI 与 API。登录后会看到引导向导选择编码 Agent 将要改动的仓库若仓库缺失通过Manage GitHub connection授权 GitHub App 访问可选接入 Linear用 API Key 或支持的订阅连接一个模型提供商并选择 Factory 模型。3. 运行第一个 Issue打开Settings → Work Intake → GitHub issues开启Sync GitHub issues并选择你的仓库每个成员可各自选择自己的 Issue 来源。创建一个小的 GitHub Issue例如为仓库 README 添加贡献指南。在Work → Intake中找到该 Issue选择Investigate打开其会话跟踪 Agent 的工作过程。随后可继续走Issue 到 Pull Request的完整流程评审 Agent 生成的实现计划审阅代码实现最终进入 Pull Request 评审。组件级配置Auth、Storage 与 Sandbox 独立替换Mastra Factory 的架构理念是各组件可独立替换认证、存储与沙箱彼此解耦模型提供商与 Issue 来源在 Factory UI 中配置而服务器级设置集中在.env改动后需重启服务器。配置项可修改内容Models提供商访问、个人或组织凭据、默认模型GitHub仓库访问与个人 Issue 摄入Linear工作区连接、项目选择、把 Issue 路由到 FactorySlackApp 设置、账号关联、从 Slack 发起会话AuthMastra 平台登录或其他支持 Server 与 Studio 的提供商Storage数据库连接或 Factory 存储适配器SandboxesMastra 平台沙箱、本地执行或其他 Mastra 沙箱提供商几个关键.env变量生成的项目使用DATABASE_URL指向带 pgvector 的 PostgreSQL。项目自带的本地数据库可通过npm run db:up启动docker-compose.yml中包含连接配置再把DATABASE_URL指向其连接串。平台沙箱使用MASTRA_PLATFORM_ACCESS_TOKEN或MASTRA_PLATFORM_SECRET_KEY配合MASTRA_PROJECT_ID与MASTRA_ENVIRONMENT_ID。若想让沙箱命令直接在 Factory Server 本机执行例如开发环境调试在.env中设置覆盖项FACTORY_SANDBOX_PROVIDERlocal此时需在该机器上安装 Git 及仓库所需的构建工具认证与存储仍可继续使用 Mastra 平台。注意这是独立的FACTORY_SANDBOX_PROVIDER覆盖项与平台沙箱后端使用的SANDBOX_PROVIDER是两回事。部署选项部署到 Mastra 平台npm run deployCLI 会输出部署后的 Factory URL。自托管将 Factory 作为常驻 Node.js 服务运行在虚拟机或容器中npm run build npm run start自托管需注意配置持久化存储设置MASTRACODE_PUBLIC_URL为公网 HTTPS 来源通过部署环境注入各提供商凭据保留生成项目所需的 CLI 依赖。可以服务器自托管 平台服务混用——即自托管 Factory Server同时继续使用 Mastra 平台提供的认证、存储与沙箱能力。生成项目内置脚本速查模板项目见 mastracode/mastra-factory/template/README.md提供以下脚本脚本作用npm run dev启动本地 Factory Server含 UI 与 APInpm run check对 Factory Server 做类型检查npm run build构建服务器与 Factory UI输出到.mastra/outputnpm run start运行生产构建产物npm run deploy构建并部署到 Mastra 平台npm run db:up/npm run db:down启动/停止可选的本地 PostgreSQL 与 Redis 服务故障排查要点运行时版本使用与本项目package.json中engines.node匹配的 Node.js 版本即 22.13.0。端口变更修改PORT后须同步更新MASTRACO_PUBLIC_URL并更新你所管理的认证/集成 App 的回调 URL。Issue 缺失检查仓库访问权限与Work Intake中的选择是否正确。数据库/沙箱错误确认组织内 admin 角色、.env中DATABASE_URL与沙箱相关变量是否齐全平台开通中途失败时已铸造的凭据会保留在.env中可修复后重跑create-factory或手工补齐其余配置。小结create-factory把从零到可运行的 Mastra Factory压缩成一条命令模板骨架、依赖安装、平台项目与 Neon 数据库开通、密钥安全落盘、Git 仓库初始化全部自动化完成同时通过--no-platform、--org、--region等参数保留了对自托管、多组织与区域选择的控制权。其源码实现src/index.ts、src/create.ts、src/platform.ts也提供了不错的工程参考幂等的.env更新、失败时部分落盘的凭据保护、上报前错误脱敏以及密钥绝不进 Git 历史的安全设计都值得在类似脚手架类工具中借鉴。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考