agent-overseers

把容易被主执行流程忽略的质量职责配置成长期存在、低频唤醒、独立观察和有界干预的 Role，并通过具名 Profile 接入 agent-delegator。

overseer profiles --cwd /path/to/project
delegate start "重构鉴权边界并补回归测试" --cwd /path/to/project --verify "npm test" --oversee quality

启用后，Observer 会在有意义的执行检查点按配置低频审查；发现具体问题时会在 Worker 下一次模型调用前提交纠偏，配置了终审的任务还会在完成前基于真实 diff 和 verify 结果决定通过、修正或阻止完成。

oversight quality   status passed   cost $0.0081
roles 3   activations 4   findings 1   corrections 1   terminal cycles 2

安装

需要 Node >= 20.10、已安装并完成鉴权的 Pi，以及 agent-delegator。

npm install --global agent-delegator agent-overseers
delegate doctor
overseer doctor --cwd /path/to/project

agent-overseers 是 agent-delegator 的可选组件；任务没有传 --oversee 时不会发现或启动 Overseer，也不会产生监督模型费用。

快速配置

项目配置适合随仓库提交，个人通用配置适合放在全局目录：

your-project/.agents/overseers/
├── roles/
│   └── evidence-before-done.md
└── profiles/
    └── quality.yaml

~/.agent-overseers/
├── roles/
└── profiles/

项目中存在同 ID 定义时使用项目版本，否则回退到全局版本；同名定义按完整文件选择，不会隐式合并字段。

定义一个 Role

Role 是一个长期质量职责，由 YAML frontmatter 和 Markdown 正文组成。

---
id: evidence-before-done
name: Evidence before done
enabled: true
activation_probability: 0.25
run_with_model: openai-codex/gpt-5.6-luna
thinking_level: low
timeout_seconds: 90
cooldown_checkpoints: 3
max_runs_per_attempt: 2
tools: [read, grep, find, ls]
---

独立检查 Worker 是否拥有足够证据证明任务已经完成。

核对用户要求、真实改动和已经运行的验证，不要把 Worker 的完成声明当作证据；没有具体遗漏时保持沉默。

| 字段 | 含义 | |---|---| | id | 稳定标识，只能使用小写字母、数字、下划线和连字符 | | name | 展示名称，默认使用 id | | enabled | 是否允许 Profile 引用，默认 true | | activation_probability | 普通检查点下的独立激活概率，范围 0 到 1，默认 0.3 | | run_with_model | Observer 模型，格式为 provider/model；省略时使用 Profile 默认模型，再回退到 Worker 模型 | | thinking_level | Observer thinking level；省略时使用 Profile 默认值 | | timeout_seconds | 单次普通审查超时；省略时使用 Profile 默认值 | | cooldown_checkpoints | 同一 Role 两次普通激活之间至少间隔的检查点数，默认 3 | | max_runs_per_attempt | 每次 start、run 或 follow 的普通激活上限，默认 2 | | tools | 可用只读工具，只能从 read、grep、find、ls 中选择 |

Markdown 正文应只描述稳定职责、证据要求和干预边界，不要写入某次任务的运行状态或历史结论。

组合一个 Profile

Profile 用一个具名 YAML 文件组合普通 Role、调度预算和可选终审 Role。

id: quality
description: General implementation quality review

default_model: openai-codex/gpt-5.6-luna
default_thinking_level: low
default_timeout_seconds: 90

roles:
  - evidence-before-done

scheduling:
  checkpoint_probability: 0.5
  max_parallel: 1
  max_total_runs_per_attempt: 5
  random_seed: null

terminal_review:
  enabled: true
  roles:
    - evidence-before-done
  timeout_seconds: 90
  max_revision_cycles: 1

| 字段 | 含义 | |---|---| | id | Profile 的稳定名称，也是 --oversee 接收的值 | | default_model | Role 未指定模型时使用的 Observer 模型；省略时回退到 Worker 模型 | | default_thinking_level | Role 未指定 thinking level 时使用的值，默认 low | | default_timeout_seconds | 普通审查默认超时，默认 90 | | roles | 参与普通低频审查的 Role，可以为空 | | scheduling.checkpoint_probability | 有意义检查点触发普通调度的概率，范围 0 到 1，默认 0.5 | | scheduling.max_parallel | 同时运行的普通 Observer 上限，默认 1 | | scheduling.max_total_runs_per_attempt | 每个 attempt 的普通 Observer 总激活上限，默认 5 | | scheduling.random_seed | 可选的 32 位非负整数，用于复现相同调度序列 | | terminal_review.enabled | 是否在 Worker 完成前进入强制终审，默认 false | | terminal_review.roles | 每个终审周期都必须明确报告的 Role；启用终审时不能为空 | | terminal_review.timeout_seconds | 整个终审周期的超时 | | terminal_review.max_revision_cycles | 最多允许的 Worker 修正轮数，默认 1 |

普通 Role 的实际激活概率是 checkpoint_probability × activation_probability；终审 Role 不参与随机抽样，每个终审周期都会运行。

Role 可以只用于终审而不出现在普通 roles 中，这适合“证据完整性”“发布门禁”等只需要在完成前检查的职责。

示例中的模型名应替换为本机 Pi 已配置并完成鉴权的 provider/model；如果 Role 不需要单独选模型，可以省略 run_with_model 并统一使用 Profile 的 default_model。

检查配置

# 列出当前项目最终可见的 Profile
overseer profiles --cwd /path/to/project

# 展开并验证一个 Profile，输出冻结后的 JSON snapshot
overseer resolve --profile quality --cwd /path/to/project --json

# 检查目录、定义引用和基础环境
overseer doctor --cwd /path/to/project

# 额外预检 Profile 使用的 Observer 模型和凭据，不发送模型 Prompt
overseer doctor --cwd /path/to/project --profile quality --worker-model openai-codex/gpt-5.6-luna --json

profiles 会同时报告可用定义和无效文件；resolve 在 Profile 或 Role 无效时显式失败，不会输出一个看似可用的 snapshot。

如果要使用其他全局配置目录，可设置 AGENT_OVERSEERS_HOME；生产默认值是 ~/.agent-overseers。

在 Delegator 中使用

主 Agent 决定当前任务是否需要监督，并显式选择一个具名 Profile：

delegate start "实现支付回调幂等并补并发测试" \
  --cwd /path/to/project \
  --verify "npm test" \
  --oversee quality

Profile 会按任务实际 cwd 解析；使用 --worktree 时，解析的是 worktree 中可见的项目配置。

解析结果会随任务冻结，后续 delegate follow 复用同一 snapshot 并开启新的监督 attempt，不能临时换 Profile。

普通审查只在工具执行、工作区真实变化和验证结果等有意义的检查点低频触发；静默审查不会增加 Worker 模型轮次，finding 会在 Worker 下一次模型调用前作为内部纠偏送达。

启用 terminal_review 后，Worker 第一次结束不会直接完成任务；Overseer 会先查看 Delegator 计算的真实 diff 和 verify，必要时要求 Worker 在同一 Session 中修正，然后重新验证和终审，直到通过、阻止完成或达到修正上限。

运行时可用 Delegator 查看监督状态：

delegate status <taskId>
delegate wait <taskId>

最终状态含义：

| 状态 | 含义 | |---|---| | disabled | 调用方没有启用监督 | | observed | 普通低频观察完整结束，但 Profile 没有启用终审 | | passed | 配置的终审 Role 完整 approve | | blocked | 存在未解决的 revise 或 block finding | | incomplete | 监督环境或必需终审没有完整收口 | | cancelled | 任务停止或 Worker 超时导致监督取消 |

命令

| 命令 | 说明 | |---|---| | overseer profiles [--cwd DIR] [--json] | 列出最终可见的具名 Profile | | overseer resolve --profile ID [--cwd DIR] [--json] | 校验并输出不可变 Profile snapshot | | overseer doctor [--cwd DIR] [--profile ID --worker-model PROVIDER/MODEL] [--json] | 检查配置、Pi 版本和可选模型鉴权 | | overseer supervise [--pi PATH] | 由 agent-delegator 管理的内部 sidecar 命令，通常不手动运行 |

所有命令都支持 --help 和 --version。

安全与成本

• Observer 只允许使用 Role 声明的 read、grep、find、ls，不能使用 bash、edit 或 write。
• Observer 只接收净化后的 Worker 轨迹和有界机械事实，不接收 Worker reasoning、完整工具结果或原始命令。
• Profile、Role、Pi 版本或模型鉴权预检失败时，显式启用监督的任务会在首个 Worker Prompt 前失败，不会无监督继续。
• 普通 Role 超时只记录诊断，不阻塞 Worker；配置为必需的终审不完整时，任务不会被标记为通过。
• 每个 Observer 激活都是独立模型调用，会产生额外 token 和费用；请用概率、cooldown、attempt 预算和终审 Role 数量控制成本。
• API key 或 OAuth 凭据应通过 Pi 自身配置或环境变量提供，不要写进 Role、Profile 或仓库。

Artifacts

监督结果由 agent-delegator 保存到任务目录：

~/.delegate/tasks/<taskId>/oversight/
├── snapshot.json
├── findings.jsonl
├── diagnostics.jsonl
├── summary.json
└── attempts/<attempt>/
    ├── summary.json
    └── cycles/<cycle>/
        ├── diff-summary.json
        ├── verify.log
        ├── verify-summary.json
        └── decision.json

snapshot.json 是任务创建时冻结的配置；summary.json 是最近 attempt 的便捷摘要；每个 attempt 和终审 cycle 的历史都会独立保留。

开发

npm test
npm pack --dry-run

常规测试全部使用 fake Pi，不读取真实凭据，也不会调用模型 API。

发布前确认测试和 npm 文件清单通过，再执行：

npm publish

License

MIT