让 Codex 的多 Agent 协作变得可控、可验证、可复盘。
Decide → Bound → Dispatch → Verify → Accept
如果你曾经对 Agent 说过“你们几个分工完成这个任务”，然后遇到过文件互相覆盖、结果只停留在总结里、Agent 重复启动、任务做完却不知道能不能信，这个项目就是为这些问题设计的。
Subagent Supervisor 是一个面向 Codex 原生 Subagent 的治理层。它不增加一个新的 Agent Runtime，也不把每个任务都拆成多人协作；它负责在真正值得委派时，把一次协作变成有边界、有证据、有生命周期的工程流程。
普通的多 Agent 协作往往是：
“你们自己分工吧”
↓
多个 Agent 同时行动
↓
重复工作 / 写入冲突 / 结果难以验证
Subagent Supervisor 会把它变成：
先判断是否值得委派
↓
为每个任务写清目标、读范围、写范围和验收标准
↓
选择 explorer / worker / reviewer
↓
记录真实产物和验证证据
↓
由主 Agent 直接验收，再关闭 Agent
你可以把它理解为：
给多 Agent 协作增加了项目经理、变更审批、测试验收和审计日志。
| 你遇到的痛点 | Subagent Supervisor 的处理方式 |
|---|---|
| 任务一复杂就盲目启动多个 Agent | 默认保持 supervisor-only，只有并行、隔离或独立复核有明确收益时才委派 |
| 两个 Agent 修改同一个文件 | 每个任务声明 allowed_writes，系统拒绝重叠写入范围并发执行 |
| Agent 说“完成了”，但结果不可信 | 必须提交真实文件、命令退出码、发现和证据；主 Agent 还要直接检查产物 |
| 子 Agent 越权修改无关内容 | Explorer/Reviewer 只读，Worker 只能拥有明确的写入范围 |
| 一个 Agent 失败后不断复制替代者 | 记录失败类别、复用判断和重试预算，禁止无意义套娃 |
| Worker 自己审查自己的代码 | 可以启动独立的 ss_reviewer，并绑定到某一次具体返回结果 |
| Agent 超时后不知道它到底停没停 | 区分“停止等待”和“Agent 已停止”，不会把等待超时伪装成完成 |
| 迟到的旧结果覆盖新的取消决定 | 迟到结果只作为 late evidence 记录，不能重新打开终态任务 |
| 用了一堆 Agent 却不知道质量如何 | 统计分派模式、角色、返工率、失败率、证据覆盖率和运行时长 |
| Native Subagent 和 OMX 的职责混在一起 | Native 处理短期有界任务；OMX 只在明确要求持久化团队时进入 |
- 一个 Codex Skill；
- 一套原生 Agent 角色配置；
- 一组任务、分派、返回和验收契约；
- 一个标准库实现的治理 CLI；
- 一个可选的生命周期 Hook 插件；
- 一个项目本地的、可审计的协作账本。
- 不是新的大模型；
- 不是自动把所有任务拆给 Agent 的“群聊机器人”；
- 不是 tmux、邮件箱、Worktree 或持久化 Worker Runtime；
- 不是对 Codex 原生线程状态的替代品；
- 不是“Agent 说完成了就自动通过”的快捷按钮。
真正的 Agent 执行仍由 Codex 负责，Subagent Supervisor 负责让执行过程可控，让主 Agent 能够证明结果为什么可以接受。
假设你有一个需求：
先定位一个回归问题，再修改指定目录里的代码，最后让另一个 Agent 独立复核。
它会被组织成这样的流程：
┌──────────────┐
│ Main Agent │ 拆解任务、授权范围、最终验收
└──────┬───────┘
│
├── 1. ss_explorer 只读调查根因
│ └─ 返回文件路径、代码位置、可复现证据
│
├── 2. ss_worker 只修改明确目录
│ └─ 返回 changed files、测试命令和退出码
│
├── 3. ss_reviewer 只读独立复核
│ └─ 绑定这一次具体 return receipt
│
└── 4. Main Agent 直接检查产物、决定 pass/rework/fail、关闭 Agent
如果 Worker 返工，旧的 Reviewer 结论不会自动继续有效。新的返回凭证必须由新的复核任务重新确认。
| 角色 | 权限 | 适合做什么 | 明确不能做什么 |
|---|---|---|---|
| ss_explorer | 只读 | 查代码、查日志、定位根因、整理证据 | 修改文件、创建 Agent、最终验收 |
| ss_worker | workspace-write，但受任务范围限制 | 完成一个边界明确的实现任务并运行验证 | 越权扩展范围、创建子 Agent、最终验收 |
| ss_reviewer | 只读 | 独立检查正确性、回归、范围和证据 | 修复代码、替主 Agent 做最终决定、复核自己 |
Profile 模板位于 assets/agent-profiles/。
| 模式 | 直白解释 |
|---|---|
| supervisor-only | 主 Agent 自己完成，最适合简单任务 |
| reuse | 继续使用已经打开且范围匹配的 Agent |
| native-spawn | 启动一个受限的原生 Agent |
| native-parallel | 启动多个互不冲突的 Agent |
| omx-team | 用户明确要求时，交给可用的持久化 OMX 团队 |
| stop-waiting | 不再等待某个 Agent，但不假设它已停止 |
| close | 关闭已完成、过时、失败或不再安全的 Agent |
项目的默认原则很简单：
任务复杂，不等于一定要拆 Agent。只有协作带来的收益能被解释和验证时，才值得增加协调成本。
一个 Task Envelope 至少声明：
- 要完成什么；
- 可以读取哪些路径；
- 可以修改哪些路径；
- 明确禁止碰什么；
- 依赖哪些任务；
- 什么条件算完成；
- 什么情况必须停止；
- 预期产生什么文件；
- 超时时间和权限快照；
- 幂等键。
示意：
{
"role": "ss_worker",
"objective": "Implement one bounded change",
"allowed_reads": ["src", "tests"],
"allowed_writes": ["src/example.py"],
"forbidden_scope": ["Do not modify unrelated files"],
"acceptance_criteria": ["Focused tests pass"],
"stop_conditions": ["Stop if another file is required"]
}这解决的是 Agent 协作里最重要的一类问题：
大家都在努力做事，但没有人明确谁可以碰什么。
Agent 返回时需要提供：
- 实际检查过的文件；
- 实际修改过的文件；
- 执行过的命令及退出码；
- 发现和证据引用；
- 风险与阻塞项。
返回凭证只是 Agent 的声明，不等于验收。主 Agent 还必须：
- 直接检查真实文件；
- 对照验收标准；
- 检查测试或验证输出；
- 记录 pass、partial、rework 或 fail；
- 关闭不再需要的 Agent。
如果 Worker 任务设置 independent_review_required: true，它不能直接通过。
复核任务必须声明：
dependency_gate: returned
role: ss_reviewer
review_target:
task_id: <worker-task>
return_receipt_id: <exact-worker-return>
只有当 Reviewer 自己被验收为 accepted 后，Worker 才能通过最终验收。
这样可以避免两个常见误区：
- “审查过这个 Agent”不等于“审查过这一次具体结果”；
- “之前通过过”不等于“返工后的新结果仍然通过”。
任务会经过明确状态：
planned → ready → dispatched → active → returned → verifying
↓
accepted / partial / rework / failed
↓
closed
失败会被区分为合同错误、范围越权、验证失败、证据缺失、依赖变化、权限阻塞、Agent 停滞、基础设施故障和用户改向。
项目有有限重试预算：
- 合同格式错误：最多立即修正一次；
- 证据不足：最多补一次集中证据；
- 实现失败：最多两轮有新证据的返工；
- 权限问题、重复失败或用户取消：不会自动无限重试。
- 任务短期、边界清晰；
- 当前主 Agent 能够等待和验收；
- 不需要持久化邮箱；
- 不需要独立 Worktree；
- 不需要跨进程恢复。
- 用户明确要求 OMX；
- Worker 要跨较长时间持续运行；
- 需要共享状态、邮箱或 Worktree；
- 需要独立进程恢复；
- 本机 OMX Runtime 已经准备好。
仅仅因为机器上安装了 OMX，并不会自动启动 OMX。
Windows PowerShell：
$skillRoot = Join-Path $env:USERPROFILE '.codex/skills/subagent-supervisor'
git clone https://github.com/sitabanubanu/subagent-supervisor.git $skillRoot
python "$skillRoot/scripts/install_agent_profiles.py" installmacOS/Linux：
git clone https://github.com/sitabanubanu/subagent-supervisor.git ~/.codex/skills/subagent-supervisor
python ~/.codex/skills/subagent-supervisor/scripts/install_agent_profiles.py install重新打开 Codex 任务后，Skill 会按照入口描述参与路由。安装器会把三个受管理 Profile 写入 ~/.codex/agents/，并记录哈希；如果用户手动修改过 Profile，卸载时会保留用户修改。
plugin/ 是可选运行时组件，不安装它也不影响核心治理能力。
它只记录 SubagentStart 和 SubagentStop 的最小生命周期元数据，不保存 Prompt、聊天内容、Token、Cookie 或密钥。由于 Codex 对 Hook 有信任边界，安装后应在 Codex 的 Hook 审核界面检查并信任来源，不要绕过安全确认。
初始化一次治理 Run：
python scripts/supervisorctl.py init-run --workspace . --objective "Review and implement bounded changes"验证一个任务合同：
python scripts/supervisorctl.py validate --kind task-envelope --file tests/fixtures/task-worker.json --workspace .查看当前 Run：
python scripts/supervisorctl.py status --workspace . --run-id <run-id>查看近 30 天使用情况：
python scripts/usage_report.py --root . --since-days 30
python scripts/usage_report.py --root . --since-days 30 --json治理账本默认写入：
<workspace>/.codex-supervisor/
它记录的是：
- 角色、状态和时间；
- 分派模式和原因码；
- 任务合同中明确提供的字段；
- 文件路径和证据引用；
- 验收结论；
- 幂等事件。
它不会主动记录：
- 原始 Prompt；
- Assistant 回复；
- Transcript 内容或路径；
- 环境变量；
- Token、Cookie、Credential 或 Authorization 数据；
- 完整命令输出。
注意：任务目标和证据引用是你主动写入合同的内容，仍然可能包含敏感信息。公开项目或共享工作区时，应保持它们最小化。
.
├── SKILL.md # Codex 的触发规则和主流程
├── agents/openai.yaml # Skill 的 Agent 接口描述
├── assets/agent-profiles/ # explorer / worker / reviewer
├── assets/hooks/hooks.json # 可选 Hook 配置资产
├── references/ # 策略、契约、生命周期、失败和 OMX 文档
│ └── schemas/ # 五类 JSON Schema
├── scripts/
│ ├── supervisorctl.py # 治理状态、校验、事件账本
│ ├── install_agent_profiles.py # 安装/卸载原生 Agent Profile
│ └── usage_report.py # 隐私友好的使用统计
├── plugin/ # 可选 Codex 生命周期插件
└── tests/ # 契约、状态机、Windows、Hook 和 CLI 测试
项目核心只依赖 Python 标准库，运行测试：
python -m unittest discover -s tests -t . -v当前测试覆盖：
- 任务、分派、返回和验收契约；
- 路径安全与大小写冲突；
- 依赖和并发写入冲突；
- 独立复核硬门；
- 幂等事件和迟到结果；
- Windows 原子写入和锁恢复；
- Hook 脱敏；
- Profile 安装器；
- 完整 CLI 生命周期。
如果只是查一个文件、改一行代码、回答一个简单问题，直接让主 Agent 完成通常更好。这个项目的价值在于降低协作风险，而不是为所有任务增加流程。
它也不会替你决定业务正确性。它可以强制要求证据、范围和验收，但最终的业务判断仍然属于主 Agent 和用户。
欢迎提交 Issue 或 Pull Request。建议任何新增能力都同时补充：
- 对应的 Skill/参考文档；
- JSON Schema 或运行时契约；
- 正向测试和失败路径测试；
- Windows/macOS/Linux 兼容性说明；
- 对隐私和权限影响的说明。
MIT License，见 LICENSE。