Multi-Agent Governor

一个轻量、可解释的自适应控制层：先跑单 Agent 基线，只有可观察证据表明边际收益值得时才增加同构 Agent，并在收益平台期或预算耗尽时强制停止。

它不是新的通用 Agent 框架。它提供两层能力：

• plan：不接管执行，只回答三个治理问题；
• run：通过可替换的 Agent Runtime 适配器实际拥有扩容权限，每次只准入一个新 Agent，再验证和决定是否继续。

三个治理问题是：

1. 要不要从 1 个 Agent 扩到多个？
2. 应采用中心协调还是独立协作？
3. 何时停止继续增加 Agent？

决策闭环

任务 → Controller → 单 Agent 基线 → 外部验证 → Governor
           ↑                                  ↓
           └── 聚合 ← 新 Agent ← 准入 / 停止 ─┘

Governor 先使用硬门槛排除明显不适合多 Agent 的任务，再逐个估计新增 Agent 的边际质量收益、延迟收益、成本、协调压力和错误传播风险。只有净边际效用超过阈值，才允许增加下一个 Agent。

快速运行

项目只需要 Python 3.10+，核心没有第三方依赖：

python3 --version
cd multi-agent-governor
PYTHONPATH=src python3 -m magov.cli examples/research_task.json
PYTHONPATH=src python3 -m magov.cli examples/coupled_task.json
PYTHONPATH=src python3 -m magov.cli plan examples/research_task.json
PYTHONPATH=src python3 -m magov.cli run \
  examples/runtime_review_scripted.json \
  --events /tmp/magov-demo.events.jsonl
PYTHONPATH=src python3 -m unittest discover -s tests -v

旧的 magov INPUT.json 仍兼容，等价于 magov plan INPUT.json。 runtime_review_scripted.json 不调用模型，用固定结果演示 baseline、扩容、验证和提前停止的完整状态机。

如果版本低于 3.10，请先安装较新的 Python，再继续下面的安装步骤。

也可以安装为本地命令：

python3 -m pip install .
magov examples/research_task.json

作为 Codex 插件或 Skill 使用

仓库包含可安装的 multi-agent-governor 插件，插件内部包含一个 multi-agent-governor Skill。 插件支持两种模式：普通任务默认只生成建议；用户明确要求执行结构化代码审查时，可以调用 magov run，由控制器通过 Codex CLI 启动隔离 Agent、记录真实用量并强制停止。目前可执行模式不适用于任意类型的软件开发任务。

推荐以插件形式安装。克隆仓库后，在仓库根目录运行：

python3 -m pip install .
codex plugin marketplace add "$PWD"
codex plugin add multi-agent-governor@multi-agent-governor

如果只想安装 Skill，也可以运行：

python3 -m pip install .
mkdir -p ~/.codex/skills
cp -R plugins/multi-agent-governor/skills/multi-agent-governor ~/.codex/skills/

安装后请新建一个 Codex 会话，再这样使用：

Use $multi-agent-governor to decide whether this task should use more agents and when to stop.

当前 Skill、策略与 Codex CLI Runtime 均为实验性 v0.2。可执行闭环已经存在，但不代表已经证明多 Agent 在所有任务上都能无损节省成本。

实际执行：结构化代码审查

第一种可执行场景限定为只读代码审查。运行 JSON 必须声明：

• 隔离的 Agent 工作目录；
• 固定审查提示词与结构化输出 schema；
• 变更文件与至少需要双重检查的高风险文件；
• 结构信号、Agent 上限、Token、耗时和工具调用预算；
• codex-cli 或仅用于测试的 scripted runtime。

无模型示意配置见 [`runtime_review_scripted.js