【用途】 moai-factory-foreman 是无人在场时运行的工厂调度角色(leader 的辅助角色),每次迭代观察积压队列,把操作员已经挑选的卡片派发给隔离工作区中的工作代理,收集完成证据并报告。它在一个没有 leader 会话持有队列时充当无人看管的监视者。
【主要能力】
- 队列监视:在队列文件上装备 Monitor 监视器(命令通过 moai paths --field todo-dir 获取队列目录,监听 backlog.db 及 backlog.db-wal 的变化),超时上限 1800000 毫秒,到期后由迭代重新装备。
- 读取队列:使用 moai gtd list --json 或 moai todo list --json 读取无锁队列,记录包含 id、text、spec_id 和 state(queued | picked | dropped)。
- 派发工作代理:选择最早被 picked 且无活动工作代理、无记录阻塞的卡片,使用 Agent 工具以 isolation: "worktree" 启动一个工作代理,派发地址块仅包含 card、spec、cmd、evidence 等固定字段。
- 收集证据:工作代理返回后,读取其证据文件,只有证据显示工作完成(含逐字通过的输出、指出差距)才通过 moai gtd done <t-id> 推进卡片。
- 汇报:每次迭代以两到六行汇报队列摘要、派发或收集情况、读取的证据、阻塞卡片及等待的决策。
【使用方式】
- 会话开始前必须完整阅读两个角色规则文件:.claude/rules/moai/workflow/factory-dispatch.md 与 .claude/rules/moai/workflow/cross-session-messaging.md;仅 Codex 的项目在 .moai/policies/ 下部署相同文件。
- 技能激活时 AskUserQuestion 从工具池移除,循环无法停下来提问;本应提问的内容变成迭代报告中的一行,需要操作员决策的内容变成阻塞卡片。
- 部署:在项目内启动会话,运行裸 /loop,然后将会话转入后台;循环任务延续到后台会话持续运行。Esc 取消等待循环的待唤醒。循环创建七天后过期,队列仍需监视时重新启动。后台监视器在会话恢复后不存活,恢复后第一次迭代会重新装备队列监视。
- 权限设置必须预先允许队列读取、git 检查、工作代理启动;无人看管时出现权限提示会卡住迭代,预批准是操作员的设置步骤。
- 数据库路径必须通过 moai paths 获取,禁止猜测路径;直接读取仅对 .db、.db-wal、.db-shm 的快照副本进行;优先使用 CLI(moai todo list --json、moai factory status)。
【适用场景】 已配置 moai 工具链、需要无监督运行、以串行方式处理待办卡片的项目;操作员已挑选卡片但无 leader 会话持有队列时。
【限制】
- 本迭代中执行器只派发这一种单工作代理模式;多通道工厂通道启动器是保留接口,未实现。
- 操作员负责准入和挑选工作,只有 state 已为 picked 的卡片可派发;不得运行 moai gtd add 或 moai gtd next <n>;不得编造、改写或重排卡片。
- 任何需要人工决策且未记录为已作出的审批不得代为回答,卡片保持 picked 并在报告中标记 blocked-for-operator。
- 一次仅一个可写工作代理;工作代理运行期间迭代只读。每个工作代理在独立工作树中运行,不写入共享检出。
- 不执行集成操作:不推送、不拉取请求、不合并、不删除分支、不处置工作树。
- 验证仅限工作代理自身变更涉及的检查,完整套件属于 CI。不得启动后台 CPU 负载(队列监视是唯一长时间运行进程)。
- 无证据不得推进卡片;缺失、不可读或过期的证据文件记为差距,卡片保持 picked 且本次迭代不重新派发。
- 循环无法完成工作时(队列文件反复不可读、无法装备队列监视、技能自身表面损坏)以单行原因停止;工作代理瞬时故障不算循环故障。