MoAI-ADK：用验证驱动的 Harness 约束 Claude Code，Factory Mode 以「领队加多车道」拆分上下文

一、它是什么

MoAI-ADK 是 modu-ai 团队开源的一套「以验证为驱动的智能体编排框架」，业界常把这类东西叫作 harness（外壳或挽具）。它用 Go 编写，要求 Go 1.26 及以上，采用 Apache-2.0 许可证。

项目页面上标注的发布版本是 v3.1.3，同时在「What's New」一节预告了 v3.2 的 Factory Mode。它的目标不是再训练一个编码模型，而是给 Claude Code 这类编码智能体套上一层外部结构，让产出的代码值得信任。项目还提供英、韩、日、中四种语言的文档、一本配套的书《Practical Agentic Coding with Claude Code》，以及 Discord 社区，CI、CodeQL 与 Codecov 的徽章也都挂在首页。

二、核心论断：把三件事交给外部

项目开篇引用了一句判断：模型是逐 token 前进的随机性工作者，它无法在回合之间记住这一轮用了什么、用了多少，无法判断结果好不好，也不知道上一个会话推进到了哪里。对应到工程上，就是三类责任：预算、质量、进度。

MoAI-ADK 的设计立场是，这三件事不能指望模型自觉，必须由 harness 从外部强制执行。这与「提示词越写越长」的思路截然不同：它不是去劝模型，而是用确定性的代码去限制和检查模型。

三、Factory Mode 的架构

v3.2 的 Factory Mode 针对的是上下文窗口问题。一个会话只有一个上下文窗口。一份很长的 SPEC 会把窗口填满，之后每个任务都要背着前面所有内容。规划早已结束，却一直留在窗口里陪着评审，评审又一直留到写总结。常见的补救办法是 /clear，但它连有用的上下文也一并丢掉。

Factory Mode 的做法是把工作拆到「一个领队会话加若干编号车道会话」上。领队负责盯住队列，把任务卡派给空闲的车道。一张卡不会在各个阶段之间换会话，而是整张进入某一条车道，由这条车道在自己的会话里依次完成 plan、run、sync。每个阶段都以 Agent() 子代理的形式启动，车道本身只做编排。这里并没有突破任何上限，每个会话的限额依然存在。变化在于：一张卡的历史只会累积在持有它的车道里，所以同样的预算走得更远，车道处理完一张卡后会清空上下文，再接下一张。

四、运行机制与细节

入口只有两个参数。moai cc -f 打开领队，长写法是 --factory；moai cc -l 以车道身份加入正在运行的工厂，长写法是 --lane。两者都不带值，车道编号由系统自动分配，操作者不能自选。-f 与 -l 同时出现会报错，在其后附带数值（例如 moai cc -l lane-2）也会被拒绝，并给出一行指明正确用法的错误。旧的多会话看板模式的 -k 入口已被移除，moai cg 只会输出迁移提示（可用 moai migrate cg 预览）。moai gpt 并不存在，GPT 模型通过 moai codex 运行；moai codex 没有领队入口，只能作为车道加入。 后端按车道选择：moai cc -l 是 Claude 车道，moai glm -l 是 GLM 车道，moai codex -l 是 Codex 车道。文档的建议是，领队的位置不负责下判断，只负责看队列和搬运卡片，所以适合用等待成本低的 GLM（moai glm -f）。某个账号开始频繁返回 429 时，可以把车道分散到不同账号。文档也说明这只是示例，所有会话都用同一个后端同样可行。 要同时处理多张卡，就再执行一次 -l 增加一条车道。编号只在有存活会话占用时才被跳过；死亡车道的占位不再阻塞其编号，但自动分配总是取「现存最高编号加一」，因此不会回填中间的空缺。车道归属记录在 ~/.moai/db/<project-key>/factory/factory.db；当基础目录是临时目录且没有绝对路径的 MOAI_HOME 覆盖时，则记录在项目本地的 <base>/.moai/db/<project-key>/factory/ 之下，积压队列也遵循同一个例外。旧的 .moai/state/factory/workers.json 只会被导入一次，并作为回滚证据保留。

单条车道最多同时运行 10 个 Agent() 子代理，具备写权限的派生会被隔离在各自的 worktree 里。文档明确建议不要一次点亮所有车道：先起第一条，确认它确实在产出，再启动其余的；同一张卡永远不会被拆到多条车道上。此外，工厂运行会记录拥有它的会话的进程身份。领队已经死亡的运行，会在下一条车道加入时被自动退役，避免加入动作卡在 AMBIGUOUS_FACTORY 上；反过来，如果车道加入时运行记录缺失或已退役、却存在存活的领队会话，加入流程会用进程号加进程启动指纹去核验这位领队。

五、性能与成本：证据在哪里

需要坦率说明的是，所提供的 README 摘录里没有给出基准数据：没有吞吐量、没有 token 成本对比，也没有缺陷率的前后统计。文档只给出了结构性的论证：卡的历史只在所属车道内累积，所以相同预算能走得更远。

这是一个合理的机制性主张，但在没有公开度量之前，不应把它当作已验证的收益。评估时可以关注几个可测的指标：每张卡的平均上下文占用、车道清空后的复用效率、429 发生率，以及领队与车道之间的协调开销。

六、对开发者与团队的影响

对个人开发者，Factory Mode 提供了一个不需要自建调度器的并行方案：多开几个终端，各自运行 moai cc -l 即可。对团队，数据落在 SQLite 文件和项目键之下，便于审计和回溯。

多后端支持让团队可以按成本与额度灵活搭配，而不是押注单一供应商。更重要的是，它体现了一种趋势：编码智能体的竞争点正在从模型本身，转向包裹模型的流程与验证层。

七、局限与未来

第一，车道必须由人手动逐个启动，因为一个会话无法启动另一个会话，这限制了全自动化。第二，公开资料里缺少量化基准。第三，复杂的进程身份核验和历史状态导入说明系统已经为崩溃恢复付出了不小的复杂度，使用者需要理解这些边界情形。

第四，一张卡不拆分的原则，意味着单张超大任务仍然会撑满一条车道的窗口。可以期待的方向包括：公开的度量报告、更多后端的接入、以及更细粒度的卡片切分策略。总体而言，MoAI-ADK 值得关注，但在引入生产流程前，应先在小规模真实任务上自行测量。