Mastra create-factory 脚手架深度解析基于 CHANGELOG 还原 Software Factory 项目的搭建全流程【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra Factory 是 Mastra 生态中用于用编码 Agent 构建软件的开源环境连接代码仓库后它可以把 Issue 转化为实现计划、代码实现乃至经过评审的 Pull Request。create-factory正是官方推荐的脚手架工具一条命令即可拉取 Software Factory 模板、安装依赖、初始化 git并在交互式向导中完成 Mastra 平台资源项目、Postgres 数据库、组织 API Key的自动预置。本文以该包在仓库中的 CHANGELOG.md 为主线结合 create.ts、platform.ts、env.ts 等源码实现完整还原 create-factory 的命令参数、平台预置链路、环境变量约定、沙箱提供商机制与安全设计读完即可独立完成一个可对接 Mastra 平台的本地 Factory 项目搭建。一、create-factory 是什么从版本时间线看工具定位mastracode/mastra-factory包从 0.0.1 的Initial public package name claim起步到 0.0.2 发布第一个真正可用的脚手架版本再到 0.1.0 引入create-factoryCLI其定位在 CHANGELOG 中非常清晰CHANGELOG.mdAdded thecreate-factoryCLI. It scaffolds a Mastra Software Factory project: enter a project name and the CLI clones the template, installs dependencies, and initializes git. Configuration (model providers, integrations, database) happens in the web UI on first load.即输入项目名 → 克隆模板 → 安装依赖 → 初始化 git而模型提供商、集成、数据库等配置在首次加载时的 Web UI 中完成。随后的版本不断给它叠加能力形成了一条清晰的演进脉络0.1.0加入 EU/US 区域选择--region标志、统一 Factory SPA 目录到src/mastra/public/factory/、UI 与 API 由单一 Mastra 开发服务器http://localhost:4111提供0.1.3Factory UI 改为随 Mastra CLI 捆绑分发不再把可编辑的浏览器源码及其构建依赖塞进生成的项目0.1.7CLI 引入与 create-mastra 一致的 PostHog 匿名遥测含MASTRA_TELEMETRY_DISABLED退出开关并移除了模板中无效的 Railway 沙箱设置0.1.11为 Factory 托管的 provider 凭据、GitHub PAT、集成 OAuth token 增加静态加密encryption at rest支持自动迁移与密钥轮换0.1.15修复生成的 Factory 项目未安装可选 E2B 沙箱依赖的问题同时从 npm 发布物中移除 CHANGELOG 以减小包体积0.1.16本地 Factory 初始化时预置 production 环境并写入MASTRA_ENVIRONMENT_ID新增FACTORY_SANDBOX_PROVIDERlocal模板覆盖项0.1.17改进 README直接给出各平台的 CLI 安装命令与环境准备指引0.1.18-alpha.x持续跟随mastra1.30.0-alpha的依赖更新。也就是说CHANGELOG 本身就是一个功能说明书每一次 Patch 描述的都是一个可观察的行为变化下文将把其中最有价值的变更逐条展开为可操作的技术内容。二、安装与快速上手安装前需要满足环境前提Node.js 22.13.0 或更高版本见 README.md 中的 IMPORTANT 提示。直接以包管理器运行最新版本即可无需先全局安装# npm npx create-factorylatest # Yarn yarn dlx create-factorylatest # pnpm pnpm create factorylatest交互式向导会依次询问项目名、组织、区域等信息。非交互式的核心用法在 CHANGELOG 的 0.1.0 条目中有最简洁的示范CHANGELOG.mdnpm create factory my-factory cd my-factory npm run dev默认情况下向导会在搭建过程中同步预置 Mastra 平台资源使本地跑起的 Factory 首次npm run dev就能直接与平台通信无需任何手工配置如果只想纯本地自托管则加--no-platformnpx create-factorylatest -- --no-platform查看全部可用选项npx create-factorylatest --help三、CLI 参数全景源码级参数说明create-factory的命令行定义位于 index.ts基于 commander 实现结合 create.ts 中的CreateArgs接口完整的参数清单如下参数类型默认值说明[project-name]位置参数交互式询问项目目录名为空时进入交互式输入且会校验目录不能为空、不能与现有目录重名create.ts--template name选项https://github.com/mastra-ai/softwarefactory-template指定模板来源接受公开 GitHub 仓库 URL自定义 URL 会被视为敏感信息不上报遥测index.ts--no-platform布尔false默认走平台跳过平台登录、项目创建与 Neon 数据库预置适合离线迭代模板--org org选项交互式选择组织 id 或名称精确匹配后跳过交互式组织选择器无匹配时报错并列出可用组织create.ts--region region选项交互式选择平台项目区域仅接受eu或us传其他值直接抛错create.ts-v, --version标志—输出版本号取自包自身 package.json区域与 Neon 数据库区域的映射关系在源码中写死create.tseu→aws-eu-central-1us→aws-us-west-2其中--no-platform、--org、--region三个参数在 0.1.0 条目中被称为New flagsCHANGELOG.md是平台预置能力引入时的第一批非交互式入口。四、平台资源自动预置从登录到写 .env 的八步链路0.1.0 条目完整列出了平台预置引入后 CLI 自动完成的动作CHANGELOG.md通过 Mastra 既有浏览器认证流程登录在所选组织下创建 Mastra 平台 server 项目铸造一把作用域于新 Factory 的sk_组织 API Key挂载并预置一个 Neon Postgres 数据库将MASTRA_SHARED_API_URL、MASTRA_ORGANIZATION_ID、MASTRA_PROJECT_ID、MASTRA_PLATFORM_SECRET_KEY、DATABASE_URL写入项目.env。对应到 create.ts 的runPlatformProvisioning实际执行的是一个八步、带失败补偿的流程认证检查当没有MASTRA_API_TOKEN环境变量且没有缓存凭据时先停顿提示Mastra account is required, press enter to continue...再打开浏览器认证流0.1.0 条目的 UX 改进浏览器打开后按任意键即可跳过平台预置CtrlC 仍是进程级取消信号组织解析有--org走resolveOrgFromFlagid 或名称精确匹配不子串匹配否则每次都用resolveCurrentOrg(token, { forcePrompt: true })强制弹出选择器让用户有意识地选择新 Factory 归属的组织区域选择--region未传时用 clack 的p.select弹出eu/us二选一创建项目POST /v1/server/projects请求体带{ name, region, factoryEnabled: true }——factoryEnabled: true对应 CHANGELOG 中Marked projects created by create-factory as factory-enabled on the Mastra platformCHANGELOG.md这条变更platform.ts铸造组织 API KeyPOST /v1/auth/tokensKey 名形如create-factory: projectName平台只展示一次明文源码注释明确要求 mint 成功后立即记入 env 累加器platform.ts确保 production 环境先GET /v1/projects/:id/environments查找type production的环境不存在则POST创建并写入MASTRA_ENVIRONMENT_ID对应 0.1.16 条目这正是让本地 Factory 无需部署应用即可使用 PlatformSandbox 的前提platform.tsNeon 数据库挂载与轮询POST /v1/server/projects/:id/databaseskind: neon返回status: provisioning随后以默认 2s 间隔、60s 总预算轮询GET .../databases/:dbId直到ready超时抛 504failed则带上后端错误信息抛出platform.ts写 .env从连接接口返回的envVars中取DATABASE_URL连同前面累加的所有键一次性写入幂等已有键替换、缺失键追加。第 7 步有两点值得注意的实现细节轮询的每次 HTTP 请求都会用剩余总预算构造AbortSignal.timeout避免某个挂起的请求拖垮整体超时源码注释 platform.ts挂载数据库要求组织 admin 角色非 admin 会收到 403 及明确的解决指引platform.ts。失败补偿机制绝不丢已铸造的凭据平台预置最重要的鲁棒性设计是env 累加器 finally 冲刷[create.ts](https://link.gitcode.com/i/af5b04697a4cb7126e820277fc587b39#L251-L258, L388-L392)每成功一步就把结果存入envAccumulatorflush()只在首次调用时执行即使后续步骤比如 Neon 还在 provision失败finally中也会把已经铸造的sk_Key、project id、org id 等写入.env——因为平台不会再次返回这把明文 Key。源码注释说得直白mid-flow 失败不能让刚签发的 Key 卡在平台侧孤悬。五、生成的 .env 环境变量约定综合 0.1.0 与 0.1.16 条目脚手架最终写入.env的平台相关键如下键来源/含义MASTRA_ORGANIZATION_ID所属组织 idMASTRA_PROJECT_ID平台 server 项目 idMASTRA_PLATFORM_SECRET_KEYsk_开头的组织 API Key作为平台密钥MASTRA_ENVIRONMENT_IDproduction 环境 id0.1.16 新增支撑 PlatformSandbox 本地运行DATABASE_URLNeon Postgres 连接串MASTRA_SHARED_API_URL0.1.0-alpha.5 起不再写入——平台消费者改用内置默认平台 URL避免在创建时把 API 端点写死CHANGELOG.md写入逻辑由 env.ts 的upsertEnvFile实现逐行用正则^(\s*#\s*)?([A-Z][A-Z0-9_]*)\s*匹配KEY...或注释形态的# KEY...并整体改写去掉注释标记剩余键追加到文件末尾并保证块前空行写入时以mode: 0o600创建文件并对已存在文件再显式chmodSync 0o600因为从.env.example复制过来默认是 0644。本地沙箱覆盖项FACTORY_SANDBOX_PROVIDERlocal0.1.16 条目给出了一个可直接使用的模板覆盖配置CHANGELOG.mdFACTORY_SANDBOX_PROVIDERlocal它的作用是在本地运行沙箱命令的同时保留云端凭据配置。也就是说在已配置云端凭据的前提下把 Factory 的沙箱执行从云端切回本地。这是 0.1.7 沙箱策略调整的自然延伸——当时移除了 Railway 沙箱设置RAILWAY_API_TOKEN之前静默无效项目实际一直跑在非隔离的本地沙箱中并删掉了模板从未读取的MASTRACODE_SANDBOX_PROVIDER与MASTRACODE_SANDBOX_IDLE_MINUTESCHANGELOG.md。CHANGELOG 明确云端沙箱统一由 Mastra Platform 提供部署的 code agent 会话运行在平台沙箱内这一信息也作为 bullet 出现在成功消息的资源清单中见 0.1.0 条目的简化说明。六、安全设计密钥防护的层层加固CHANGELOG 中安全相关的变更非常密集且全部有源码佐证是本文档最有干货的部分.env 权限收紧为 06000.1.0 条目要求.env创建即写入 0600 权限使MASTRA_PLATFORM_SECRET_KEY、DATABASE_URL等平台密钥仅属主可读CHANGELOG.md。create.ts在复制.env.example后立即chmodSync 0o600best-effortWindows 下容忍失败env.ts写入时同样双保险git 初始化前置 .gitignore 保护ensureEnvGitignored会在git add -A之前检查.gitignore是否已覆盖.env.env、.env*、/.env、/.env*四种形态忽略注释行未覆盖则追加# Added by create-factory to protect platform credentials与.envcreate.ts。如果.gitignore写不进去权限、磁盘满等则完全跳过git init并警告用户——否则git add -A会把刚生成的密钥永久写进首次提交的 git 历史静态加密encryption at rest0.1.11 条目为 Factory 托管的 provider 凭据、GitHub PAT、集成 OAuth token 引入静态加密支持自动迁移与密钥轮换CHANGELOG.md遥测脱敏redactError会在错误信息回显前剔除自定义模板 URL、--org值、非法 region 值、项目名等敏感内容避免私有仓库标识或凭据泄漏进分析事件index.ts遥测本身与 create-mastra 同源PostHog受MASTRA_TELEMETRY_DISABLED控制并使用共享的匿名 distinct idCHANGELOG.md。七、模板工程化同步脚本与版本锁定策略Factory 的模板来自独立仓库softwarefactory-template本地模板通过 scripts/sync-template.mjs 同步。CHANGELOG 记录了同步策略的两次反转读起来像一段发布工程的实战记录锁alpha0.1.0-alpha.4为了让模板可针对已发布包安装构建把每个同步的 Mastra 依赖钉到alpha并下发带legacy-peer-depstrue的.npmrc兼容预发布 peer 依赖图同时把 TypeScript 从 tsgo(v7) 降回经典编译器^5.9.2——因为mastra build经由typescript-paths传递加载 TypeScript依赖经典ts.sysAPI而 tsgo 不暴露该 APImonorepo 内 pnpm 提升恰好掩盖了这个问题独立模板没有提升就暴露了CHANGELOG.md改锁latest0.1.0、0.0.3-alpha.3随后又改为把所有 Mastra 依赖钉到latest与其余 create-mastra 模板保持一致并移除.npmrcsync-template.mjs不再调用npm view、不再需要--tag标志。同步工作流在一次性副本中验证模板避免npm install产物泄漏进发布模板仓库CHANGELOG.md。与模板工程化相关的还有生成的模板携带pnpm-workspace.yaml的allowBuilds配置防止 pnpm v10 在 install/build 时因ERR_PNPM_IGNORED_BUILDS退出CHANGELOG.md0.1.0 起模板的 build 脚本简化为单条命令{ build: mastra build --dir src/mastra }此前是build: npm run build:ui mastra build --dir src/mastramastra build现在会自动打包预构建的 UIFactory 资源在构建期落到src/mastra/public/factory/部署产物中出现在.mastra/output/factory/CHANGELOG.md。生成的单服务器 README 也统一说明Factory UI 与 API 都由http://localhost:4111提供OAuth 回调使用服务器源废弃的dev:prod/build:ui脚本不再被文档提及CHANGELOG.md。八、常见问题与故障处理速查从源码与 CHANGELOG 中整理出最常见的失败场景与处理方式场景表现处理非 admin 挂载数据库403提示Attaching a database requires the admin role请组织 admin 运行 create-factory或从平台 dashboard 挂载数据库platform.tsNeon 长时间 provision504 Neon database is still provisioning after 60s到 dashboard 查看状态或mastra login后重跑platform.ts平台预置中途失败已铸造的凭据已写入.envCLI 打印黄色警告修复后重跑npx create factory或从 platform 控制台补齐剩余项create.ts.gitignore写失败警告并跳过 git init手工把.env加入.gitignore后自行git init git add -Acreate.ts依赖安装失败Dependency install failed.按提示手动执行cd projectName 包管理器 installcreate.ts想离线/纯本地迭代—使用--no-platform稍后手工配置.env或设置FACTORY_SANDBOX_PROVIDERlocal保持云端凭据的同时本地跑沙箱另外包管理器是自动检测的优先解析npm_config_user_agent回退到npm_execpath最终兜底 npmpm.tsnpm 安装时会附加--no-audit --no-fund。依赖安装、git 操作均通过 tinyexec 子进程执行。九、进一步阅读包入口与参数定义index.ts脚手架主流程与平台预置编排create.ts平台 API 客户端项目/环境/Key/Neonplatform.ts.env 幂等写入与 0600 权限env.ts模板克隆与包名改写clone.ts模板同步脚本sync-template.mjs安装与使用说明README.md完整版本历史CHANGELOG.md【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Mastra create-factory 脚手架深度解析：基于 CHANGELOG 还原 Software Factory 项目的搭建全流程
Mastra create-factory 脚手架深度解析基于 CHANGELOG 还原 Software Factory 项目的搭建全流程【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra Factory 是 Mastra 生态中用于用编码 Agent 构建软件的开源环境连接代码仓库后它可以把 Issue 转化为实现计划、代码实现乃至经过评审的 Pull Request。create-factory正是官方推荐的脚手架工具一条命令即可拉取 Software Factory 模板、安装依赖、初始化 git并在交互式向导中完成 Mastra 平台资源项目、Postgres 数据库、组织 API Key的自动预置。本文以该包在仓库中的 CHANGELOG.md 为主线结合 create.ts、platform.ts、env.ts 等源码实现完整还原 create-factory 的命令参数、平台预置链路、环境变量约定、沙箱提供商机制与安全设计读完即可独立完成一个可对接 Mastra 平台的本地 Factory 项目搭建。一、create-factory 是什么从版本时间线看工具定位mastracode/mastra-factory包从 0.0.1 的Initial public package name claim起步到 0.0.2 发布第一个真正可用的脚手架版本再到 0.1.0 引入create-factoryCLI其定位在 CHANGELOG 中非常清晰CHANGELOG.mdAdded thecreate-factoryCLI. It scaffolds a Mastra Software Factory project: enter a project name and the CLI clones the template, installs dependencies, and initializes git. Configuration (model providers, integrations, database) happens in the web UI on first load.即输入项目名 → 克隆模板 → 安装依赖 → 初始化 git而模型提供商、集成、数据库等配置在首次加载时的 Web UI 中完成。随后的版本不断给它叠加能力形成了一条清晰的演进脉络0.1.0加入 EU/US 区域选择--region标志、统一 Factory SPA 目录到src/mastra/public/factory/、UI 与 API 由单一 Mastra 开发服务器http://localhost:4111提供0.1.3Factory UI 改为随 Mastra CLI 捆绑分发不再把可编辑的浏览器源码及其构建依赖塞进生成的项目0.1.7CLI 引入与 create-mastra 一致的 PostHog 匿名遥测含MASTRA_TELEMETRY_DISABLED退出开关并移除了模板中无效的 Railway 沙箱设置0.1.11为 Factory 托管的 provider 凭据、GitHub PAT、集成 OAuth token 增加静态加密encryption at rest支持自动迁移与密钥轮换0.1.15修复生成的 Factory 项目未安装可选 E2B 沙箱依赖的问题同时从 npm 发布物中移除 CHANGELOG 以减小包体积0.1.16本地 Factory 初始化时预置 production 环境并写入MASTRA_ENVIRONMENT_ID新增FACTORY_SANDBOX_PROVIDERlocal模板覆盖项0.1.17改进 README直接给出各平台的 CLI 安装命令与环境准备指引0.1.18-alpha.x持续跟随mastra1.30.0-alpha的依赖更新。也就是说CHANGELOG 本身就是一个功能说明书每一次 Patch 描述的都是一个可观察的行为变化下文将把其中最有价值的变更逐条展开为可操作的技术内容。二、安装与快速上手安装前需要满足环境前提Node.js 22.13.0 或更高版本见 README.md 中的 IMPORTANT 提示。直接以包管理器运行最新版本即可无需先全局安装# npm npx create-factorylatest # Yarn yarn dlx create-factorylatest # pnpm pnpm create factorylatest交互式向导会依次询问项目名、组织、区域等信息。非交互式的核心用法在 CHANGELOG 的 0.1.0 条目中有最简洁的示范CHANGELOG.mdnpm create factory my-factory cd my-factory npm run dev默认情况下向导会在搭建过程中同步预置 Mastra 平台资源使本地跑起的 Factory 首次npm run dev就能直接与平台通信无需任何手工配置如果只想纯本地自托管则加--no-platformnpx create-factorylatest -- --no-platform查看全部可用选项npx create-factorylatest --help三、CLI 参数全景源码级参数说明create-factory的命令行定义位于 index.ts基于 commander 实现结合 create.ts 中的CreateArgs接口完整的参数清单如下参数类型默认值说明[project-name]位置参数交互式询问项目目录名为空时进入交互式输入且会校验目录不能为空、不能与现有目录重名create.ts--template name选项https://github.com/mastra-ai/softwarefactory-template指定模板来源接受公开 GitHub 仓库 URL自定义 URL 会被视为敏感信息不上报遥测index.ts--no-platform布尔false默认走平台跳过平台登录、项目创建与 Neon 数据库预置适合离线迭代模板--org org选项交互式选择组织 id 或名称精确匹配后跳过交互式组织选择器无匹配时报错并列出可用组织create.ts--region region选项交互式选择平台项目区域仅接受eu或us传其他值直接抛错create.ts-v, --version标志—输出版本号取自包自身 package.json区域与 Neon 数据库区域的映射关系在源码中写死create.tseu→aws-eu-central-1us→aws-us-west-2其中--no-platform、--org、--region三个参数在 0.1.0 条目中被称为New flagsCHANGELOG.md是平台预置能力引入时的第一批非交互式入口。四、平台资源自动预置从登录到写 .env 的八步链路0.1.0 条目完整列出了平台预置引入后 CLI 自动完成的动作CHANGELOG.md通过 Mastra 既有浏览器认证流程登录在所选组织下创建 Mastra 平台 server 项目铸造一把作用域于新 Factory 的sk_组织 API Key挂载并预置一个 Neon Postgres 数据库将MASTRA_SHARED_API_URL、MASTRA_ORGANIZATION_ID、MASTRA_PROJECT_ID、MASTRA_PLATFORM_SECRET_KEY、DATABASE_URL写入项目.env。对应到 create.ts 的runPlatformProvisioning实际执行的是一个八步、带失败补偿的流程认证检查当没有MASTRA_API_TOKEN环境变量且没有缓存凭据时先停顿提示Mastra account is required, press enter to continue...再打开浏览器认证流0.1.0 条目的 UX 改进浏览器打开后按任意键即可跳过平台预置CtrlC 仍是进程级取消信号组织解析有--org走resolveOrgFromFlagid 或名称精确匹配不子串匹配否则每次都用resolveCurrentOrg(token, { forcePrompt: true })强制弹出选择器让用户有意识地选择新 Factory 归属的组织区域选择--region未传时用 clack 的p.select弹出eu/us二选一创建项目POST /v1/server/projects请求体带{ name, region, factoryEnabled: true }——factoryEnabled: true对应 CHANGELOG 中Marked projects created by create-factory as factory-enabled on the Mastra platformCHANGELOG.md这条变更platform.ts铸造组织 API KeyPOST /v1/auth/tokensKey 名形如create-factory: projectName平台只展示一次明文源码注释明确要求 mint 成功后立即记入 env 累加器platform.ts确保 production 环境先GET /v1/projects/:id/environments查找type production的环境不存在则POST创建并写入MASTRA_ENVIRONMENT_ID对应 0.1.16 条目这正是让本地 Factory 无需部署应用即可使用 PlatformSandbox 的前提platform.tsNeon 数据库挂载与轮询POST /v1/server/projects/:id/databaseskind: neon返回status: provisioning随后以默认 2s 间隔、60s 总预算轮询GET .../databases/:dbId直到ready超时抛 504failed则带上后端错误信息抛出platform.ts写 .env从连接接口返回的envVars中取DATABASE_URL连同前面累加的所有键一次性写入幂等已有键替换、缺失键追加。第 7 步有两点值得注意的实现细节轮询的每次 HTTP 请求都会用剩余总预算构造AbortSignal.timeout避免某个挂起的请求拖垮整体超时源码注释 platform.ts挂载数据库要求组织 admin 角色非 admin 会收到 403 及明确的解决指引platform.ts。失败补偿机制绝不丢已铸造的凭据平台预置最重要的鲁棒性设计是env 累加器 finally 冲刷[create.ts](https://link.gitcode.com/i/af5b04697a4cb7126e820277fc587b39#L251-L258, L388-L392)每成功一步就把结果存入envAccumulatorflush()只在首次调用时执行即使后续步骤比如 Neon 还在 provision失败finally中也会把已经铸造的sk_Key、project id、org id 等写入.env——因为平台不会再次返回这把明文 Key。源码注释说得直白mid-flow 失败不能让刚签发的 Key 卡在平台侧孤悬。五、生成的 .env 环境变量约定综合 0.1.0 与 0.1.16 条目脚手架最终写入.env的平台相关键如下键来源/含义MASTRA_ORGANIZATION_ID所属组织 idMASTRA_PROJECT_ID平台 server 项目 idMASTRA_PLATFORM_SECRET_KEYsk_开头的组织 API Key作为平台密钥MASTRA_ENVIRONMENT_IDproduction 环境 id0.1.16 新增支撑 PlatformSandbox 本地运行DATABASE_URLNeon Postgres 连接串MASTRA_SHARED_API_URL0.1.0-alpha.5 起不再写入——平台消费者改用内置默认平台 URL避免在创建时把 API 端点写死CHANGELOG.md写入逻辑由 env.ts 的upsertEnvFile实现逐行用正则^(\s*#\s*)?([A-Z][A-Z0-9_]*)\s*匹配KEY...或注释形态的# KEY...并整体改写去掉注释标记剩余键追加到文件末尾并保证块前空行写入时以mode: 0o600创建文件并对已存在文件再显式chmodSync 0o600因为从.env.example复制过来默认是 0644。本地沙箱覆盖项FACTORY_SANDBOX_PROVIDERlocal0.1.16 条目给出了一个可直接使用的模板覆盖配置CHANGELOG.mdFACTORY_SANDBOX_PROVIDERlocal它的作用是在本地运行沙箱命令的同时保留云端凭据配置。也就是说在已配置云端凭据的前提下把 Factory 的沙箱执行从云端切回本地。这是 0.1.7 沙箱策略调整的自然延伸——当时移除了 Railway 沙箱设置RAILWAY_API_TOKEN之前静默无效项目实际一直跑在非隔离的本地沙箱中并删掉了模板从未读取的MASTRACODE_SANDBOX_PROVIDER与MASTRACODE_SANDBOX_IDLE_MINUTESCHANGELOG.md。CHANGELOG 明确云端沙箱统一由 Mastra Platform 提供部署的 code agent 会话运行在平台沙箱内这一信息也作为 bullet 出现在成功消息的资源清单中见 0.1.0 条目的简化说明。六、安全设计密钥防护的层层加固CHANGELOG 中安全相关的变更非常密集且全部有源码佐证是本文档最有干货的部分.env 权限收紧为 06000.1.0 条目要求.env创建即写入 0600 权限使MASTRA_PLATFORM_SECRET_KEY、DATABASE_URL等平台密钥仅属主可读CHANGELOG.md。create.ts在复制.env.example后立即chmodSync 0o600best-effortWindows 下容忍失败env.ts写入时同样双保险git 初始化前置 .gitignore 保护ensureEnvGitignored会在git add -A之前检查.gitignore是否已覆盖.env.env、.env*、/.env、/.env*四种形态忽略注释行未覆盖则追加# Added by create-factory to protect platform credentials与.envcreate.ts。如果.gitignore写不进去权限、磁盘满等则完全跳过git init并警告用户——否则git add -A会把刚生成的密钥永久写进首次提交的 git 历史静态加密encryption at rest0.1.11 条目为 Factory 托管的 provider 凭据、GitHub PAT、集成 OAuth token 引入静态加密支持自动迁移与密钥轮换CHANGELOG.md遥测脱敏redactError会在错误信息回显前剔除自定义模板 URL、--org值、非法 region 值、项目名等敏感内容避免私有仓库标识或凭据泄漏进分析事件index.ts遥测本身与 create-mastra 同源PostHog受MASTRA_TELEMETRY_DISABLED控制并使用共享的匿名 distinct idCHANGELOG.md。七、模板工程化同步脚本与版本锁定策略Factory 的模板来自独立仓库softwarefactory-template本地模板通过 scripts/sync-template.mjs 同步。CHANGELOG 记录了同步策略的两次反转读起来像一段发布工程的实战记录锁alpha0.1.0-alpha.4为了让模板可针对已发布包安装构建把每个同步的 Mastra 依赖钉到alpha并下发带legacy-peer-depstrue的.npmrc兼容预发布 peer 依赖图同时把 TypeScript 从 tsgo(v7) 降回经典编译器^5.9.2——因为mastra build经由typescript-paths传递加载 TypeScript依赖经典ts.sysAPI而 tsgo 不暴露该 APImonorepo 内 pnpm 提升恰好掩盖了这个问题独立模板没有提升就暴露了CHANGELOG.md改锁latest0.1.0、0.0.3-alpha.3随后又改为把所有 Mastra 依赖钉到latest与其余 create-mastra 模板保持一致并移除.npmrcsync-template.mjs不再调用npm view、不再需要--tag标志。同步工作流在一次性副本中验证模板避免npm install产物泄漏进发布模板仓库CHANGELOG.md。与模板工程化相关的还有生成的模板携带pnpm-workspace.yaml的allowBuilds配置防止 pnpm v10 在 install/build 时因ERR_PNPM_IGNORED_BUILDS退出CHANGELOG.md0.1.0 起模板的 build 脚本简化为单条命令{ build: mastra build --dir src/mastra }此前是build: npm run build:ui mastra build --dir src/mastramastra build现在会自动打包预构建的 UIFactory 资源在构建期落到src/mastra/public/factory/部署产物中出现在.mastra/output/factory/CHANGELOG.md。生成的单服务器 README 也统一说明Factory UI 与 API 都由http://localhost:4111提供OAuth 回调使用服务器源废弃的dev:prod/build:ui脚本不再被文档提及CHANGELOG.md。八、常见问题与故障处理速查从源码与 CHANGELOG 中整理出最常见的失败场景与处理方式场景表现处理非 admin 挂载数据库403提示Attaching a database requires the admin role请组织 admin 运行 create-factory或从平台 dashboard 挂载数据库platform.tsNeon 长时间 provision504 Neon database is still provisioning after 60s到 dashboard 查看状态或mastra login后重跑platform.ts平台预置中途失败已铸造的凭据已写入.envCLI 打印黄色警告修复后重跑npx create factory或从 platform 控制台补齐剩余项create.ts.gitignore写失败警告并跳过 git init手工把.env加入.gitignore后自行git init git add -Acreate.ts依赖安装失败Dependency install failed.按提示手动执行cd projectName 包管理器 installcreate.ts想离线/纯本地迭代—使用--no-platform稍后手工配置.env或设置FACTORY_SANDBOX_PROVIDERlocal保持云端凭据的同时本地跑沙箱另外包管理器是自动检测的优先解析npm_config_user_agent回退到npm_execpath最终兜底 npmpm.tsnpm 安装时会附加--no-audit --no-fund。依赖安装、git 操作均通过 tinyexec 子进程执行。九、进一步阅读包入口与参数定义index.ts脚手架主流程与平台预置编排create.ts平台 API 客户端项目/环境/Key/Neonplatform.ts.env 幂等写入与 0600 权限env.ts模板克隆与包名改写clone.ts模板同步脚本sync-template.mjs安装与使用说明README.md完整版本历史CHANGELOG.md【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
