Mastra Software Factory 规则配置实战从 defineBoard 到集成构造器的全链路治理【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本指南以 Mastra Software Factorymastra/factory的规则配置为主题系统讲解 Factory 规则的所有权模型、生命周期处理器、板迁移策略、阶段语义、工具结果规则、GitHub/Linear 集成事件规则以及configVersion版本标签的完整配置方法。读完本文你将掌握在类型化部署配置中安全修改 Factory 策略的正确姿势知道每一类规则应该写在哪个构造器上、如何迁移旧版全局rules配置、如何执行一个自定义板并理解运行时校验、幂等与审计的底层机制。规则所有权模型一条规则只有一个主人Mastra Software Factory 的规则体系遵循一个核心原则不存在全局规则树。旧版的new MastraFactory({ rules })配置方式已被移除任何传入rules的构造都会在构造阶段直接抛错错误信息会指向替代方案。取而代之的是“每条规则都有且只有一个所有者”的模型规则类型所有者配置位置生命周期处理器onEnter/onExit已安装的板定义defineBoard()的phases.phase板迁移策略transitionPolicy已安装的板定义defineBoard()的transitionPolicy阶段语义kind/role已安装的板定义defineBoard()的phases.phase工具结果规则tools.toolName.onResult已安装的板定义defineBoard()的toolsGitHub / Linear 事件规则集成实例GithubIntegration/PlatformGithubIntegration/LinearIntegration/PlatformLinearIntegration构造器的rules[event]运行时只负责执行规则不持有任何规则声明。这一点在仓库 README.md 中有明确表述“There is no global rules object. Every rule has one owner: boards own lifecycle handlers, transition policy, phase semantics, and tool-result rules; integrations own their event handlers. The runtime only executes rules.”理解这个所有权模型是配置 Factory 规则的起点凡是板相关的规则全部写在defineBoard()的板定义里凡是 GitHub/Linear 事件相关的规则全部写在对应集成构造器上。不要在 skill 文件、仓库指令、浏览器端代码或任何并行操作系统中放置部署策略——Factory 规则是被信任的服务器端代码。找到配置入口不猜路径由于 Factory 部署可以从不同的入口组装MastraFactory本 skill 明确要求不要猜测文件路径而是通过搜索以下符号定位实际的配置点new MastraFactory及其boards、includeDefaultBoards选项defineBoard与configVersion已安装的GithubIntegration、PlatformGithubIntegration、LinearIntegration、PlatformLinearIntegration构造器及其rules选项。找到配置后在修改前先通读现有规则配置及其测试。规则助手与类型必须从部署实际使用的同一个本地 Factory 模块导入避免因导入路径错位导致类型或运行时行为不一致。在仓库中宿主应用的标准组装序列是调用MastraFactory.prepare()→ 构造Mastra实例 → 调用MastraFactory.finalize()。规范宿主示例位于 mastracode/web/src/mastra/index.ts该文件路径在 README 中作为 canonical host example 被引用。new Mastra(...)表达式必须留在宿主入口文件中以便 Mastra 的部署器能够检测并打包。保留公开形状在 defineBoard 中配置生命周期处理器已安装的板定义独占阶段进入/退出处理器的所有权。配置语法为phases: { phase: { onEnter: { source: handler }, onExit: { source: handler }, }, }支持的来源source共有四种见 rules/types.ts 中的FACTORY_RULE_SOURCESissueGitHub issue 触发的进入/退出pullRequestGitHub pull request 触发的进入/退出linearIssueLinear issue 触发的进入/退出manual人工创建的工作项触发的进入/退出。Work 与 Review 两个内置板会自动以 Mastra 的优选默认值安装无需任何规则配置。自定义板通过MastraFactory的boards选项安装设置includeDefaultBoards: false支持纯自定义板的安装不安装 Work 与 Review。移除旧版全局规则从旧配置迁移时必须删除此前的全局rules.work与rules.review配置。内置板的自定义化被明确推迟不要发明板覆盖overrideAPI不要派生替代实现work与review这两个 ID 是保留 ID不能用于替换内置板。new MastraFactory({ rules })会抛错configVersion设置在MastraFactory上作为审计标签详见后文“configVersion 版本标签”一节。工具结果规则的解析边界工具结果规则只从工作项所属的已安装板解析Work 声明了submit_planReview 未声明任何工具结果规则自定义板即使复用了 Work 的阶段名也不继承任何工具结果规则。解析是 fail-closed 的——若卡片所属的板未安装、或该板未声明对应工具则不触发任何规则。运行时解析逻辑见 semantics.ts 的resolveBoardToolRule。Work 自动接单的两道闸门Work 的自动接单automatic intake有两个缺一不可的前置条件进入原因cause必须是linked_item_materialized链接项已物化元数据中的autoStartCandidate必须为true。这一点在 Work 板定义 work.ts 的onArrival包装器中可以看到具体实现两个条件不满足时直接返回undefined不产生任何决策。GitHub 集成通过actor 信任度与issue 创建时间晚于项目创建时间两个因素来盖autoStartCandidate印章见 default-rules.ts 的createdAfterFactory与issueOpened处理器。迁移时必须保留这两道闸门不要为了复刻 Web 部署旧版的无条件接单覆盖而移除它们。非候选noncandidate与人工manual到达的工作项仅仅进入 Intake 不会自动开工显式的 issue 分诊triage路径和既有的人工审批保障仍然保留。Linear 的 Intake 与 Review 保留其既有默认行为与闸门Linear 不会自动调查进入 Triage 时才触发既有调查行为Review 保留受保护的自动首轮审查与显式审查行为。配置 GitHub / Linear 集成事件规则GitHub 与 Linear 的集成独占各自的事件处理器所有权。不要再使用全局 Factory 规则树来配置它们而应直接在集成构造器上配置new PlatformGithubIntegration({ rules: { issueCommentCreated: null } }); new PlatformLinearIntegration({ rules: { issueClosed: null } });GitHub 事件清单GithubIntegration与PlatformGithubIntegration支持 13 个事件见 rules/types.ts 的FACTORY_GITHUB_EVENTS事件名默认行为摘要issueOpened创建链接工作项并盖autoStartCandidate印章issueEdited重新分诊retriageissueClosed关闭链接工作项issueCommentCreated/issueCommentEdited/issueCommentDeleted根据评论变更重新分诊pullRequestOpened创建链接工作项pullRequestUpdated对已审 PR 触发 re-reviewpullRequestCommentCreated回应 PR 评论pullRequestReviewRequested触发 re-reviewpullRequestReviewSubmitted处理审查反馈pullRequestMerged关闭工作项pullRequestClosed关闭工作项完整默认处理器映射定义在 default-rules.ts 的defaultGithubRules中全部事件默认自动启用。Linear 事件清单Linear 支持两个事件见 rules/types.tsissueObserved观察到 open 的 issue创建摄入项与issueClosed将已链接的非终态工作项关闭为 Done 或 Canceled未链接的已关闭 issue 不会创建新项。三种取值语义函数替换该事件的默认处理器不与被替换的处理器组合null禁用该事件的处理器——但不会禁用鉴权、webhook 摄入ingestion或对账簿记reconciliation bookkeeping省略或undefined保留默认处理器。每个内置处理器默认自动启用永远不需要为了安装集成而导入或展开默认值。构造器校验与冻结集成构造器会校验事件名与处理器值然后为每个实例复制并冻结解析后的有效映射。以 GitHub 为例resolveGithubRulesdefault-rules.ts的实现要点覆盖值必须是对象null/数组/非对象直接抛错未知事件名直接抛错Unknown GitHub rule event处理器值必须是函数、null或undefined否则抛错结果映射通过Object.freeze冻结。关键语义禁用处理器 ≠ 禁用能力禁用某个事件的处理器不会关闭该事件对应的鉴权、webhook 摄入或对账簿记。此外Linear 抓取fetch、平台轮询platform polling与对账reconciliation都使用持有该实例的处理器——也就是说Linear 的默认issueClosed处理器负责将链接工作项按状态关闭如果你用自定义函数替换它抓取/轮询/对账路径也会走你的自定义实现。每个事件处理器返回一个类型化的FactoryRuleDecision或undefined。不要创建actions配置也不要在 React 中执行权威策略——前端factory-ui只做展示与调用所有权威策略判断都在服务器端。迁移示例// 之前全局 Factory 规则覆盖 const overrides { github: { issueCommentCreated: { onEvent: null } } }; // 之后GitHub 集成构造器选项 const github new PlatformGithubIntegration({ rules: { issueCommentCreated: null } }); // 之前 const overrides { linear: { issueClosed: { onEvent: null } } }; // 之后 const linear new PlatformLinearIntegration({ rules: { issueClosed: null } });把旧的rules.linear[event].onEvent值迁移到 Linear 构造器的rules[event]即可。自定义处理器接收现有的类型化 GitHub/Linear 上下文并返回一个决策或undefined外部标题、正文、评论在 webhook 鉴权之后仍应视为不可信数据自定义处理器必须显式保留所需的 actor 权限检查详见“安全规则”一节。配置板迁移策略transitionPolicy板的三个关注点严格分离拓扑topology声明哪些迁移是允许的next/outcomes迁移策略transitionPolicy在拓扑之上增加业务限制生命周期处理器lifecycle handlers返回进入/退出的效果effects。自定义限制应加到板定义上而不是通用迁移服务或全局规则中import type { BoardTransitionPolicy } from mastra/factory/boards; const transitionPolicy: BoardTransitionPolicy context { if (context.toStage shipped !context.isHumanTransition) { return { type: reject, code: approval_required, reason: A person must approve this release. }; } }; // 将 transitionPolicy 传给已安装的自定义 defineBoard() 定义策略契约定义在 transition-policy.ts策略接收BoardTransitionPolicyContext包含board、fromStage、toStage、source、initialEntry、reenter、itemRevision、isHumanTransition、requestedTriageType与工作项快照返回undefined不加额外限制{ type: allow, triageType?, accept?: true }放行可携带分类意图与接受意图{ type: reject, code, reason }拒绝code必须是受支持的拒绝码reason长度限制为 1–512 字符。策略永远不能返回 skill 调用、迁移、consent 覆盖或任意补丁。快照、校验与原子提交策略收到的是深度只读快照日期已转换为 ISO 字符串immutablePolicySnapshot的实现见 transition-policy.tsDate 转 ISO、数组/对象递归冻结、函数/符号直接抛错。运行时使用 transition-policy.ts 中的boardTransitionPolicyResultSchema校验返回值。**分类意图triageType**必须走既有的 triage-agent 路径且必须与 triage agent 请求的分类一致**接受意图accept: true**要求同时满足“人类 actor”与“人类 ingress”两个条件——一个由人类 actor 发起的延迟规则不算人类迁移运行时在校验结果后仅在所有生命周期处理器评估成功之后才在事务中原子提交意图。策略评估的时机语义初始进入、重新进入reentry、同阶段请求都会评估策略已完成的回放replay不评估并发尝试可能被评估多次策略超时不会取消回调已启动的工作策略与生命周期评估共享同一个超时预算。策略不能绕过的边界返回allow不是授权覆盖。策略放行不能绕过拓扑、板所有权、ingress 授权、外部作者安全external-author safety、修订检查revision checks、回放、决策校验。阶段含义必须在阶段上声明kind而不是在策略中声明。不要发明内置替代 API。Work 内置迁移策略剖析Work 自动提供分类要求、非 bug 人工审批门与接受决策实现在 work-transition-policy.ts 中。其逻辑要点triage agent 必须报告结构化分类若 actor 是triage角色且未提供requestedTriageType拒绝invalid_transition已持久化的分类不可被后续迁移改写若工作项已有triageType且与请求的不一致拒绝forbidden非 bug 进入工作区需要人工审批当分类存在且不是bug、目标阶段是planning或execute、且不是人类迁移、且没有acceptedAt记录时拒绝approval_required提示语要求维护者在 Factory UI 中移动。经过 Review 阶段不构成审批证据通过时返回allow并按需携带triageType来自 triage agent与accept: true人类迁移且尚未接受。Review 没有额外策略。没有策略的自定义板不会因为使用了 Work 的阶段名或名为triage的角色而继承 Work 的分类要求或接受盖章行为。配置板阶段语义kind 与 roledefineBoard()中每个阶段都必须声明kind取值三种resting卡片停靠。人类移出 resting 阶段会启动arm自主性移回则解除。initialPhase必须是 resting——卡片不能“到达即已入座或已完成”workingagent 座位seat承载卡片。必须声明role与决策角色相同的标识符规则role指明人类 kickoff 打开的座位以及规则启动的 run 离开休息区时进入的车道。两个 working 阶段可以共享同一rolephaseForRole返回声明顺序中的第一个terminal卡片完成。进入 terminal 会释放沙箱并允许 sweep 让过期的决策失效、撤销 run 绑定。terminal 阶段不允许声明role。校验逻辑见 define-board.ts缺失kind、非法kind、working 阶段缺少合法role、非 working 阶段声明了role都会在定义期抛出BoardDefinitionError。initialPhase必须是已定义的 resting 阶段define-board.ts。运行时如何解读阶段运行时读取已安装板的声明来驱动consent 武装consent arming、外部作者守卫、kickoff 入座、run 启动车道、终态清理、sweep、supervisor findings。没有任何逻辑按阶段名匹配——自定义板复用 Work 的阶段名得到的只是自己声明的行为。semantics.ts中的resolvePhaseSemantics与boardForWorkItem负责解析板的归属与阶段含义持久化的board字段是权威没有该字段的行按 pull request 归 Review、否则归 Work向后兼容旧分配。未知板或未知阶段一律 fail closedconsent 被请求、不做任何清理、不启动或撤销任何座位。修改阶段语义的正确姿势想让自定义阶段成为终态或在该阶段安置 agent直接改定义中的kind/role不要在迁移服务、dispatcher、sweep 或 supervisor 中新增按阶段名的检查绑定迁移工具bound transition tools接受自定义阶段标识符并在工作项所属的已安装板上校验实时成员关系live membership与拓扑。Work 板声明了intakeresting、triage/planning/execute/reviewworking角色分别为triage/plan/work/work、done/canceledterminal见 work.tsReview 声明了intakeresting、reviewworking角色review、done/canceledterminal见 review.ts。defineBoard()暴露派生助手phaseKind、isWorking、isTerminal、roleForPhase、phaseForRoledefine-board.ts。迁移注意旧版defineBoard()调用必须为每个阶段补上kind、为 working 阶段补上role。执行一个自定义板发布排练完整示例仓库 README 提供了完整的自定义板执行示例README.md演示queued → preparing → shipping → shipped的发布排练流程应作为自定义板执行的配置模式。前置条件配置好的存储、GitHub 集成、已连接的项目仓库、沙箱、组织级模型凭据并为项目开启自动运行automatic runs仓库需包含release:check包脚本。import { MastraFactory } from mastra/factory; import type { MastraFactoryConfig } from mastra/factory; import { defineBoard } from mastra/factory/boards; import type { BoardPhaseDefinition } from mastra/factory/boards; type ReleasePhase queued | preparing | shipping | shipped; const releaseBoard defineBoardrelease, RecordReleasePhase, BoardPhaseDefinitionReleasePhase({ id: release, title: Release, initialPhase: queued, transitionPolicy: context { if (context.fromStage queued context.toStage preparing !context.isHumanTransition) { return { type: reject, code: approval_required, reason: A person must start the release rehearsal., }; } }, phases: { queued: { title: Queued, kind: resting, next: preparing }, preparing: { title: Preparing, kind: working, role: release-preparer, next: shipping, onEnter: { issue: context ({ type: invokeSkill, idempotencyKey: ${context.ingress.id}:prepare, role: release-preparer, prompt: Inspect the release changes. When ready, call factory_transition_work_item with stage shipping and the current expectedRevision from the Factory phase signal., }), }, }, shipping: { title: Shipping, kind: working, role: release-publisher, next: shipped, onEnter: { issue: context ({ type: invokeSkill, idempotencyKey: ${context.ingress.id}:check, role: release-publisher, prompt: Run npm run release:check printf RELEASE_CHECK_PASSED\\n with execute_command. This is a rehearsal; do not publish anything., }), }, }, shipped: { title: Shipped, kind: terminal }, }, tools: { execute_command: { onResult: context { if ( context.item.stages[0] ! shipping || context.result.status ! success || typeof context.result.value ! string || !context.result.value.trimEnd().endsWith(RELEASE_CHECK_PASSED) ) { return; } return { type: transition, idempotencyKey: ${context.ingress.id}:checked, board: release, stage: shipped, }; }, }, }, }); export function createFactory(config: OmitMastraFactoryConfig, boards | includeDefaultBoards) { return new MastraFactory({ ...config, boards: [releaseBoard], includeDefaultBoards: true }); }标识符规则板与阶段标识符大小写敏感长度为 1–128 个字母、数字、下划线或连字符以字母或数字开头不含首尾空白。实现见 validation.ts 的IDENTIFIER_RE /^[a-z0-9][a-z0-9_-]*$/i与MAX_BOARD_IDENTIFIER_LENGTH 128角色长度上限为 32MAX_ROLE_LENGTH。生命周期、工具结果与集成决策可以指向已安装的自定义阶段但必须在该目标板上校验成员关系绝不能对着所有已安装阶段名的并集校验。决策的目标语义transition决策停留在工作项所分配的板上不能将卡片改派到其他板upsertLinkedWorkItem决策可以指向另一块已安装板物化materialization先进入该板声明的初始阶段再移动到请求的目标阶段两种决策都不能重新指派已有卡片不能改变卡片归属目标在“接受”之前与“未提交的延迟效果执行”之前都会被检查已提交的回放committed replay保留其原始记录结果与原始configVersion即使安装配置后来发生了变化。座位与角色绑定Working 角色标识的是共享 Code Agent 上的绑定bindings不是独立配置的 agent——Factory 没有 per-role agent 注册选项。invokeSkill决策使用 working 角色与板自有的提示词prompt或可用 skill不要发明agents配置。自动会话准备需要验证部署的 GitHub 集成、项目连接与链接仓库、沙箱、组织模型凭据与项目自动运行设置。当需要审批时通过公开迁移路由以授权人类身份进入 working 阶段。验证完整旅程实际执行时要验证初始进入 → 生命周期 kickoff → 声明角色的阶段信号与绑定 → 绑定迁移工具 → 角色交接 → 完成的工具结果摄入 → 延迟迁移 → 终态清理。轮询与持久化消息摄入通过已安装板解析单个当前阶段实时绑定、改派、修订、拓扑、审批与外部作者检查仍然生效。名为triage的自定义角色不继承 Work 的分类要求。工具结果处理器接收归一化后的result.status与result.value不接收原始工具参数。要按板的策略所需的结果载荷来判断业务成功而不是把每一次完成的工具调用都当作业务成功对比 Work 的submit_plan处理器 work-tool-rules.ts它要求status success、卡片恰好在planning阶段、actor 是plan角色的 agent且结果文本以Plan approved.开头才会发出到execute的迁移。保留的限制factory-ui仍使用内置阶段与角色渲染完成度指标仍按 Work 的done阶段统计held-waiting是 Work 专属的 supervisor finding内置板替换/自定义化不支持既有集成默认值不会自动把事件路由到自定义板——摄入绑定是显式的Linear 项目绑定与 GitHub 标签路由都需要在设置中显式配置。修改内置处理器步骤与约束两类内置处理器的修改方式不同集成覆盖rules[event]只替换对应事件的那一个处理器不与被替换的内置处理器组合兄弟事件保持不变板内处理器包括 Work 的submit_plan工具结果规则没有覆盖机制。要改变行为只能直接修改已安装的定义本身Work 在 work.ts 与 work-tool-rules.ts或安装一个声明自己tools的自定义板。修改内置处理器之前按以下五步操作找到并阅读它GitHub 处理器在 mastracode/factory/src/integrations/github/default-rules.tsLinear 处理器在 mastracode/factory/src/integrations/linear/default-rules.tsWork 的工具结果处理器在 mastracode/factory/src/boards/work-tool-rules.tsWork/Review 的生命周期与策略默认值在 mastracode/factory/src/boards/work.ts 与 mastracode/factory/src/boards/review.ts。自定义处理器位于其安装定义中。判断替换实现是否必须显式保留原行为的某一部分。只使用类型化上下文暴露的字段不要伸手进 Factory 存储或原始 webhook 载荷。返回undefined以允许 ingress 且不产生决策或返回类型化的拒绝或受约束的结构化决策。每个效果决策都要有稳定的idempotencyKey由不可变的 ingress 身份派生例如${context.ingress.id}:factory-triage。configVersion 版本标签在MastraFactory上设置显式的、部署自有的configVersion并在规则行为变化时更新它new MastraFactory({ storage, configVersion: deployment-v2 });它的职责与边界职责为持久化的评估与审计记录打标签存储在rule_set_version列也盖在会话 kickoff 头部Config: …。没有任何逻辑按它分支——它存在的意义是让审计行能追溯到产生它的部署默认值factory-config-v1必须是非空的受限字符串长度上限 128见 validation.ts禁止不能用它作为事件身份event identity也不能加入 ingress 去重键。安全规则配置与编写 Factory 规则时必须遵守以下安全约束将处理器的工作量控制在五秒评估预算内将规则回调视为受信任的部署代码而不是仓库提供的代码拒绝原因保持简短且安全地持久化与展示永远不要向处理器暴露凭据、存储句柄、工作树路径或原始 webhook 载荷只有在服务端权限解析之后才信任 GitHub actor只有write与admin受信任失败一律视为不受信任fail closed后续迁移通过FactoryRuleDecision请求绝不直接改写阶段存储skill、消息、通知与链接项效果一律延迟执行绝不在评估内部执行保持因果迁移有界因果链深度上限为 8见 validation.ts 的MAX_FACTORY_RULE_CAUSAL_DEPTH并携带稳定的幂等键。Work 与 Review 的卡片独立移动不要镜像它们的阶段也不要仅仅因为一个 pull request 合并了就标记 Work Done——Work 完成由 Work 板的done阶段决定Review 完成由 Review 板的done阶段决定两者各自沿自己的板拓扑推进。验证变更测试与构建每次修改后按以下流程验证为被替换的叶子处理器及其未受影响的兄弟处理器添加或更新聚焦测试测试与源码同目录以*.test.ts命名适用时覆盖undefined、接受与拒绝三条路径运行聚焦的 Factory 规则测试与包级类型检查运行 Web 构建确认 skill 与部署输出被打包总结被替换的叶子、保留或移除的行为、版本变更、运行的命令。不要为了凑合而削弱测试也不要绕过迁移服务让策略生效。从仓库根目录可运行以下命令验证mastra/factory包见 README.mdpnpm --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总结Mastra Software Factory 的规则体系通过“单所有权”模型把复杂度收敛到了两个明确的位置板的生命周期、迁移策略、阶段语义与工具结果规则写在defineBoard()的板定义里GitHub/Linear 事件规则写在对应集成构造器的rules[event]上。配合configVersion审计标签、五秒评估预算、稳定的幂等键与 fail-closed 的运行时校验这套体系既保证了部署策略的可追溯性也守住了鉴权、拓扑、修订与外部作者安全的底线。掌握本文中的配置模式与安全边界你就能安全地把 Factory 从内置的 Work/Review 扩展到任意自定义板的自动化工作流。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考