多开会话还不算协作#

我第一次想象多 agent 协作时，也很容易想到“多开几个终端窗口”：这个改前端，那个改后端，另一个跑测试。看起来并发了，但很快会遇到几个问题：

• 多个会话都在读同一个模糊上下文。
• 分工没有被结构化记录。
• 某个会话完成后，结果只留在对话里。
• 汇总者不知道哪些结果可信。
• 失败路径没有统一归档。
• 用户很难在中途确认或阻止错误分派。

这些问题不是再开一个 agent 就能解决的。需要有人先把工作区状态、分工、会话启动、回传结果和日志放到一个地方看，否则并发越多，越容易乱。

codex-governance 做的就是这层控制面。

第一层是工作区报告#

README 里把 codex_governance.py 放在第一层：读取 Git 工作区，按路径规则输出治理报告。它不修改仓库文件，只给出三省职责视图、命中的部门、风险列表、建议验证命令和 portability preflight 摘要。

这一步很像开工前的诊断，也是我觉得这种工具最容易被低估的部分。

多 agent 不该在不了解当前 diff 的情况下直接执行。工作区里可能有未提交改动、跨模块修改、生成文件、敏感路径、验证缺口。先生成报告，至少能回答几个基础问题：

• 当前变更影响哪些区域。
• 哪些部门或角色应该参与。
• 哪些风险需要人工确认。
• 需要跑哪些验证命令。
• 有没有本机绝对路径或可移植性问题。

如果没有这份报告，分派就容易变成拍脑袋。

Launcher 必须有白名单范围#

codex_launcher.py 提供本地 HTTP API，负责启动中书省会话、部门会话、队列、并发控制、结果归档和计划确认。这里最要留意的是”本地”和”白名单”。

一个能启动 Codex 会话的 API，说白了有执行能力。它不该变成任意 shell 代理，更不该暴露到公网。README 里也强调 API 默认监听本机，目标是本机协作，不是云端控制面。

这种工具一旦能启动本地进程，设计时就要先限定它能做哪些事：

• 看板可以调用受控 API。
• API 只暴露有限动作。
• 终端执行层通过固定脚本处理任务输入。
• 浏览器终端也走本机 tokenized loopback URL。
• 具体 PTY 逻辑不直接塞进看板。

这比“前端按钮直接拼命令”稳得多。

分派计划要经过确认#

多 agent 工作流里，最危险的一步是分派。

如果总控会话生成一个计划后，系统立刻批量启动所有部门，很容易把错误理解放大成多个并发修改。codex-governance 的流程里有一个重要停顿：中书省先生成结构化分派方案，前端确认后再批量启动门下省或三部。

这个确认点不是摆设。它给用户一个机会在并发开始前检查：

• 部门是否选对。
• 范围是否过大。
• 是否遗漏只读审查。
• 是否需要先跑报告或测试。
• 是否有冲突任务不该并发。

所以这里慢一步是好事：计划可以自动生成，但启动前最好让人点一次确认。

Mailbox 让结果离开聊天窗口#

agent 的结果如果只停留在对话里，很难被后续流程稳定消费。

codex-governance 使用 mailbox 回传结果，并在 archive 中生成 handoff packet。这个设计很实用：部门完成后，结果会登记到可读取、可归档的位置，而不是只说一声做完了。

这样中书省汇总时，不需要靠聊天记录猜测状态。它可以轮询 inbox，看哪些部门已回传、哪些结果需要确认、哪些 next_action 冲突、哪些是 launcher 兜底结果。

对复杂协作来说，mailbox 是比对话更稳定的状态层。

看板负责观察，不负责越权#

dashboard.html 的角色也很清楚：展示报告、会话、分派方案和回传结果；启动中书省；确认计划；查看队列和状态。它访问本地 launcher API，但不直接执行任意 shell。

这是一种合理的前端范围。

看板要让人快速看到这些事，而不是堆按钮：

• 当前有哪些会话。
• 哪些部门在队列里。
• 并发是否达到上限。
• 哪些结果已经回传。
• 哪些步骤需要人工确认。
• 是否有心跳或 idle 风险。

对我来说，看板最大的用处就是少猜：哪些会话还在跑，哪些已经回传，哪里卡住了，一眼能看到。

输入文件比命令行参数更稳#

这个启动脚本用 UTF-8 文件调用 Codex CLI，以解决 Windows 控制台编码和长文本传递问题。

这个小设计很工程化，也很像真实使用里才会踩到的坑。

多 agent 分派里，任务输入往往很长，还可能包含中文、路径、Markdown、结构化要求。直接塞命令行参数，很容易遇到编码、转义、长度或换行问题。写入临时输入文件再启动 CLI，虽然多了一步，但更可控。

这个细节也挺现实：工作流工具先得把上下文稳定送到真实机器上，架构图再漂亮也替不了这一步。

本地优先是低资源方案#

这个项目没有追求云端控制面。它依赖本地文件、Git 工作区、PowerShell、Codex CLI 和本地 HTTP API。

这和博客平台的取舍类似：服务器性能有限时，能静态做的事情就静态做；能本地完成的编排就别搬到公网服务上。

多 agent 治理也一样。很多协作状态其实只需要在本机存在：

• 临时输入文件。
• mailbox inbox 和 archive。
• audit jsonl。
• 会话状态。
• 本地看板。

只要用户本人能审查和操作，就不一定需要一个重型后端。

已知范围写清楚，项目更可信#

README 里写了已知范围：偏 Windows / PowerShell / 本地 Codex CLI，API 默认监听本机，中文三省三部语义还需要社区化术语映射。

这段范围说明很有用。它直接告诉读者这个工具主要适合什么机器、什么工作流，迁移时哪里可能要改。

• 这个工具适合什么环境。
• 哪些地方需要迁移。
• 哪些概念是本地工作流特有的。
• 哪些能力还不该公网化。

公开项目不一定要一开始就通用，但必须说明自己在哪里有效。这个范围写清楚以后，读者反而更容易判断它能不能迁移到自己的机器上。

多开会话前先补状态#

看完这个项目，我最大的感受是：多 agent 协作要先把状态和回传补齐。工作区报告、分派确认、mailbox、看板、本地 API 限制，这些东西不炫，但能让多个会话在同一个仓库里少互相踩脚。