MastraCode 贡献者指南：从零搭建 Mastra Software Factory 本地开发环境-迪斯科星球

MastraCode 贡献者指南：从零搭建 Mastra Software Factory 本地开发环境

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

这篇指南围绕 Mastra 仓库中mastracode目录展开，帮助你在本地完整运行Mastra Factory（Mastra 软件工厂，一个用编码智能体把 issue 变成计划、实现和已评审 Pull Request 的开源环境）。读完本文，你将掌握六个包各自的职责分工、从仓库根目录完成环境初始化的标准步骤、两种本地运行模式（集成模式与分离 UI 模式）的差异与选择，以及后端核心机制（Board 生命周期、configVersion 与规则迁移）的底层原理。

MastraCode 是什么：一个包级视角

MastraCode 是 Mastra 项目中承载**编码智能体（coding agent）与软件工厂（Software Factory）**能力的目录。它不是一个单一包，而是六个各司其职的包组成的工程集合，mastracode/README.md 用一张表清晰地划分了各自的边界：

包	职责
factory	Factory 后端：存储、路由、规则与集成
factory-ui	Factory React 应用与浏览器测试
web	本地与可部署的 Factory 宿主（host）
sdk	共享的编码智能体运行时
tui	终端界面（`mastracode`CLI）
mastra-factory	`create-factory`脚手架

理解这套分工是本地开发的第一步：后端逻辑在factory，React 代码在factory-ui，环境与部署接线在web，共享的 agent-controller 行为在sdk。正如 web/README.md 所述，mastracode/web负责把环境相关的存储、认证、集成、事件总线与沙箱接线到@mastra/factory，React 代码则必须放在factory-ui中。

环境初始化：从仓库根目录开始

mastracode/web是一个独立的 pnpm 工程，拥有自己的 lockfile，并通过link:依赖指向 monorepo 中的包。因此在仓库根目录执行以下三步（原文档原样继承）：

pnpm install pnpm --dir mastracode/web install pnpm --dir mastracode/web run prebuild

其中prebuild会构建 web host 所链接的本地包。从 mastracode/web/package.json 的脚本定义可以看到，它实际执行的是根目录下的 turbo 构建，目标包括./mastracode/sdk、./mastracode/factory、./auth/workos、./client-sdks/client-js、./stores/libsql、./stores/pg、./server-adapters/hono、./workspaces/platform-workspace、./pubsub/redis-streams、./workspaces/e2b与./packages/cli——也就是说，web host 依赖了存储（LibSQL/PG）、认证（WorkOS）、HTTP 适配器（Hono）、沙箱（E2B）与 CLI 等多条链路，初次构建耗时较长属正常现象。

另外注意版本前提：tui/README.md 要求Node.js 22.19.0 或更高，mastra-factory/README.md 的脚手架要求Node.js 22.13.0 或更高，web 工程的engines字段同样声明了>=22.19.0。

前置配置：本地 GitHub App

运行 Factory 之前，必须先完成本地 GitHub App 的配置（web README 中的 "Configure local onboarding" 章节）。在 GitHub 的 App 创建页面新建一个 App，其 URL 必须与你要运行的模式严格匹配：

设置项	集成模式（Integrated）	分离 UI 模式（Split UI）
Homepage URL	`http://localhost:5873`	`http://localhost:5173`
Callback URL	`http://localhost:5873/auth/github/callback`	`http://localhost:5173/auth/github/callback`
Setup URL	`http://localhost:5873/auth/github/callback`	`http://localhost:5173/auth/github/callback`

⚠️ 不要混用两种模式：集成模式下 5173 端口不会有任何服务在运行。

随后按以下步骤完成 App 配置：

授予Contents、Issues、Pull requests的读写权限，以及Metadata的只读权限。
本地开发时清除 Webhook → Active勾选。
生成 client secret 与 private key。
将这些值写入mastracode/web/.env：

GITHUB_APP_ID= GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----" GITHUB_APP_CLIENT_ID= GITHUB_APP_CLIENT_SECRET= GITHUB_APP_SLUG= GITHUB_APP_WEBHOOK_SECRET=

关键细节（来自 web/README.md）：

用openssl rand -hex 32生成状态签名密钥，填入GITHUB_APP_WEBHOOK_SECRET；
private key 中必须使用转义的\n换行符；
修改.env后必须重启服务端才生效；
其他环境变量可参考 mastracode/web/.env.schema（注：该文件未被包含在仓库列表中时，以实际目录为准）。

两种本地运行模式

本地开发使用 LibSQL 与本地沙箱，onboarding 需要登录和 GitHub App。根据工作内容选择模式：

集成模式（Integrated mode）——后端工作首选

后端开发与接近生产的检查用这种模式，API 与打包后的 UI 一起运行：

pnpm --dir mastracode/web dev

然后打开http://localhost:5873。从 package.json 可以看到，该命令通过varlock run包装mastra factory dev --dir src/mastra，并预设PORT=5873与MASTRACODE_PUBLIC_URL。

分离 UI 模式（Split UI mode）——带热更新的前端开发

UI 开发需要热模块替换（HMR）时使用。一条命令会依次：启动 Docker 服务 → 构建 UI 依赖的工作区包 → 在:4111运行 API → 在:5173运行 Vite dev server：

pnpm --dir mastracode/web dev:ui

打开http://localhost:5173。若希望两个终端分别运行而不互相干扰：

pnpm --dir mastracode/web db:up

然后分别执行pnpm --dir mastracode/web api（API）与pnpm --filter ./mastracode/factory-ui dev（Vite）即可。

可选本地服务：PostgreSQL 与 Redis

要测试 PostgreSQL 和 Redis 场景：

pnpm --dir mastracode/web db:up

并在mastracode/web/.env中加入以下值后重启：

DATABASE_URL=postgres://user:pass@localhost:54329/mastracode_web REDIS_URL=redis://localhost:63799

对应 docker-compose.yml 中的映射端口（54329 / 63799）。

可选：接入 Slack 频道

Slack 只向公开 HTTPS 来源发送事件，因此本地服务需要隧道。以下步骤假设集成模式（服务监听 5873）：

启动隧道：安装cloudflared后运行cloudflared tunnel --url http://127.0.0.1:5873，它会启动一个无需账号与配置文件的临时 Quick Tunnel，将输出的trycloudflare.com主机名保存下来（该主机名在命令停止前有效）。若有 Cloudflare 账号和域名，也可改用命名隧道以获得稳定主机名，避免每次重启都要更新 Slack manifest。
创建 Slack App：为隧道 URL 生成 manifest 并复制到剪贴板：

pnpm --dir mastracode/web slack:manifest \ --url https://your-tunnel-hostname \ --name "Mastra Factory (dev)" \ --copy

在 Slack 的 App 管理页面选择Create New App → From a manifest粘贴生成的内容，安装到工作区后，将Basic Information → App Credentials的凭据与OAuth & Permissions中的 bot token 填入.env：

MASTRACODE_CHANNELS_PUBLIC_URL=https://your-tunnel-hostname SLACK_APP_SIGNING_SECRET= SLACK_APP_CLIENT_ID= SLACK_APP_CLIENT_SECRET= SLACK_APP_BOT_TOKEN=

重启 dev server——varlock会在启动时读取.env。

关联账号：给 bot 发私信，它会回复一张 Connect 卡片；完成该流程后，你的 Slack 身份即绑定到 Mastra 用户，之后 Slack 中的消息将以你的身份执行。

注意：Quick Tunnel 每次运行都会获得新主机名，更换后需要同步更新MASTRACODE_CHANNELS_PUBLIC_URL以及 Slack App 的Event Subscriptions、Interactivity & Shortcuts、OAuth & Permissions设置。

后端核心机制：Factory 的架构与规则模型

prepare → finalize 生命周期

factory/README.md 说明了宿主应用的接入方式：宿主调用MastraFactory.prepare()初始化 Factory 自有资源，构造Mastra实例，再调用MastraFactory.finalize()把路由、集成、存储驱动行为与 agent-controller 能力连接到宿主。关键约束是new Mastra(...)必须保留在宿主入口文件中，以便 Mastra 的部署器能检测并打包它；mastracode/web/src/mastra/index.ts 就是规范宿主示例。最简用法如下：

import { MastraFactory } from '@mastra/factory'; import type { MastraFactoryConfig } from '@mastra/factory'; export function createFactory(storage: MastraFactoryConfig['storage']) { return new MastraFactory({ storage }); }

Board：规则的新一代归属模型

从源码结构看，Factory 的规则体系已从"全局 rules 对象"迁移到Board 定义：Board 拥有生命周期处理器（onEnter/onExit）、转移策略（transitionPolicy）、阶段语义（kind）与工具结果规则（tools）；集成（integration）拥有自己的事件处理器；运行时只负责执行规则，不再存在全局 rules 对象。Work 与 Review 两个内置 Board 会自动安装默认配置，无需任何规则配置。

阶段kind的语义为：

resting——卡片停靠，人类移出时武装自主性、移回时解除；initialPhase必须是 resting；
working——由 agent 座位承载卡片，必须声明role；
terminal——卡片完成，进入后释放沙箱、允许 sweeps 淘汰过期决策。

此外configVersion取代了旧rules选项与ruleSetVersion，作为操作员维护的部署标签盖在审计记录上（存储列名保持为rule_set_version），默认值为factory-config-v1。旧 API 已移除：传递rules会在构造时抛错，并指向替代方案：

// 迁移前 new MastraFactory({ storage, rules: defaultFactoryRules({ version: 'v2', overrides: { tools: { my_tool: { onResult } } } }) }); // 迁移后 new MastraFactory({ storage, configVersion: 'v2', boards: [defineBoard({ ..., tools: { my_tool: { onResult } } })] });

自定义 Board 通过defineBoard()声明，示例可见 factory/README.md 中完整的 release 彩排 Board（queued → preparing → shipping → shipped四阶段，含transitionPolicy人类审批闸门、invokeSkill进入处理器与execute_command工具结果规则）。Board 与阶段标识符为 1–128 个字母、数字、下划线或连字符，区分大小写且不能含首尾空白；work与review两个 ID 保持保留，不可用于替换内置 Board。

集成事件规则与更多 intake 来源

GitHub：GithubIntegration与PlatformGithubIntegration均可在构造时通过rules选项替换或禁用默认事件处理器（函数替换、null禁用，undefined保留默认）；事件名与处理器值非法会在构造期被拒绝。仓库维护者还可以在 PR 评论中发@<factory-app> review或@<factory-app> re-review直接启动一次 Factory review。
Linear：LinearIntegration/PlatformLinearIntegration自动安装issueObserved与issueClosed内置处理器，无需任何默认规则导入。
incident.io：IncidentioIntegration（读取INCIDENT_IO_API_KEY）与平台版PlatformIncidentioIntegration（通过/v2/connections/{connectionId}/proxy代理）可把活跃 incident 与遗留 follow-up 作为 Intake 源导入任意已安装 Board；默认每五分钟由 reconciliation worker 轮询刷新一次状态，可用MASTRACODE_INCIDENT_IO_RECONCILE_ENABLED与MASTRACODE_INCIDENT_IO_RECONCILE_INTERVAL_MS控制。
Intake 路由：GitHub 通过GET/PUT /web/intake/label-routes将 label 映射到 Board（不区分大小写，未路由的 issue 进入 Work）；Linear 项目绑定则在 Settings › Intake › Linear routing 中选择一个 Board。

产品遥测

Factory 会在 Mastra 现有的 PostHog 项目中记录factory_web_activity事件，浏览器只把已知的页面类别与活动类型发给已认证的/web/telemetry/activity端点，由服务端补充已验证的账号与部署上下文。事件属性包括activity（page_view/interaction）、page（有界类别如work/review/settings，绝不发送 URL）、platform_user_id/platform_org_id、platform_project_id（来自MASTRA_PROJECT_ID）、platform_hosted（是否存在非空MASTRA_DEPLOYMENT_ID）等，schema_version为1。交互事件每个挂载的浏览器应用每分钟最多一次，服务端按账号/组织每进程每分钟上限 60 次，隐藏标签页不采集。可通过设置MASTRA_TELEMETRY_DISABLED=true关闭（接受1/true/yes，忽略大小写与空白）。该事件不采集姓名、邮箱、token、提示词、输入值、原始 URL、会话回放或匿名浏览器身份。

测试、构建与部署

测试与质量检查

web 宿主的测试命令：

pnpm --dir mastracode/web test pnpm --dir mastracode/web check

按包划分：UI 测试在factory-ui，后端测试在factory。Factory 包的聚焦检查（从仓库根目录运行）：

pnpm --filter ./mastracode/factory test pnpm --filter ./mastracode/factory check pnpm --filter ./mastracode/factory lint pnpm --filter ./mastracode/factory build:lib pnpm --filter ./mastracode/factory smoke:dist

测试与源码同目录存放为*.test.ts；构建后建议运行smoke:dist验证发布入口可被正常导入。factory-ui 的测试约定还包括单元测试（test:unit）与 MSW 页面测试（test:msw），参见 mastracode/factory-ui/AGENTS.md。

构建、运行与部署

pnpm --dir mastracode/web build pnpm --dir mastracode/web start

构建会通过scripts/monorepo-deps.mjs先行处理 monorepo 依赖，再执行mastra build --dir src/mastra。部署需要先登录 Mastra 平台：

mastra auth login pnpm --dir mastracode/web deploy

deploy会先执行 build 与scripts/validate-output.mjs输出校验，再以mastra deploy --skip-build发布。

快速上手的另一条路径：脚手架

如果你不是要开发 MastraCode 本身，而是想使用Mastra Factory，官方推荐用create-factory脚手架（mastra-factory/README.md）：

npx create-factory@latest

也支持 Yarn（yarn dlx create-factory@latest）与 pnpm（pnpm create factory@latest）。默认情况下，交互式向导会在 setup 期间预置 Mastra 平台资源，使你可以在平台上或"本地 + 云端能力"的方式完整运行 Factory；若想完全自托管，加上--no-platform标志：

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

所有选项可通过npx create-factory@latest --help查看。

结语

从包结构到两种运行模式，再到 Board 规则模型与部署链路，mastracode目录展示了一套完整的"可复用后端 + React 前端 + 独立宿主 + 共享 SDK"工程形态。后端工作走集成模式（5873 端口），UI 工作走分离模式（5173 端口 + Docker 服务），并牢记"策略、校验与持久化留在@mastra/factory，React 里不放业务规则"的边界原则，即可高效地在本地贡献 MastraCode。各包的 CHANGELOG.md 记录了版本历史与迁移细节，值得在升级时同步查阅。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析