Jason's Blog

Advisor 实现：agent 编排层的只读审查能力

27分钟阅读

Advisor 实现：agent 编排层的只读审查能力

核心结论

Advisor 是 Claude Code 在 agent 编排层实现的只读审查能力。它让 executor 在复杂代码任务中获得一个旁路 reviewer，用于判断生产修复面、验证路径和停止条件。

Advisor 不直接改代码，也不替代 executor。它更适合在高风险、长链路、弱模型执行或验证路径不清楚的场景中触发。当前数据支持”局部正向、风险触发”，不支持默认全量开启。

设计思路

Anthropic 的 advisor strategy 更接近 LLM/API 层的原生能力：模型调用协议里支持 advisor 作为旁路角色介入，executor 可以在执行时获得模型内置的审查建议。这个方案的好处是集成深，触发、上下文和 advice 都更贴近模型自身能力。

但这条路径没有办法直接通用于当前评测里的多模型组合。原因很直接：原生 advisor 依赖 Anthropic 侧的模型能力和接口设计，不能自然复用到 DeepSeek、GPT、LongCat2、Haiku 等 executor，也不能假设所有 provider 都支持同一种 advisor 协议。

官方方案的触发机制

Anthropic 的 advisor 自带内置 system prompt，倾向于让 executor 在复杂任务开始阶段或遇到困难时调用。具体内部描述没有完整公开，但从官方文档和 developer guide 可以还原几个关键点。

system-prompt steering 是官方方案的核心控制手段。Anthropic 建议在 coding 场景中明确告诉 executor：

  • 做少量探索读取后、第一次实质工作前调用 advisor；
  • 遇到反复错误、不收敛或准备换方案时调用；
  • 长任务在确定方案前调用一次；
  • 困难任务完成修改和测试后再做一次最终咨询。

官方明确指出：如果没有 system-prompt steering，coding executor 往往会少调用 advisor。模型倾向于自己解决问题，不会主动请求旁路审查。这意味着 advisor 的收益高度依赖 prompt 工程，而不是模型自身会触发。

可选的程序控制方面，如果 executor 自主判断不稳定，可以在应用层增加：

  • 第一轮没调用 advisor 时，第二轮插入 reminder 提醒 executor；
  • 使用 tool_choice 强制本次调用 advisor；
  • 设置 max_uses 限制单次请求内的调用次数，防止过度调用。

这套机制的问题是：它绑定 Anthropic 的 tool 协议和 API 参数（tool_choice、max_uses），不能直接复用到其他 provider。而且 reminder 注入、强制调用这类控制都是 API 层行为，跨 provider 时需要各自重新实现。

所以这里选择从 agent 编排层实现 advisor：把 advisor 设计成一个外部只读审查工具，由 Claude Code 的执行流程在关键节点调用。这样 executor 仍然走原来的代码读取、编辑和验证链路，advisor 只拿到必要上下文，返回短建议。

这个选择背后有几个判断：

  • 先保证通用性：advisor 不绑定单一 LLM 原生能力，而是可以挂到不同 executor / advisor 组合上；
  • 先保证权限边界：advisor 只读，不拿文件编辑权，避免”审查者”变成第二个 executor；
  • 先保证触发质量：advisor 不做每题强制调用，只在生产链路不清、修复面不稳、验证路径不明确时介入；
  • 先保证结果可归因：advisor-mode 里如果没有真实 advisor 调用，只能算 no-call control，不能算 advisor 收益。

实验设计也围绕这个思路展开。我们不是只看 advisor-mode 是否跑得更快，而是拆开看三件事：advisor 是否真的被调用、调用后是否改变了修复面或验证判断、token/cost 是否有完整记录。这样能避免把 executor 自己跑出来的结果误写成 advisor 的效果。

实现流程

整体流程如下：

flowchart TD
  A["用户任务"] --> B["Executor 读取代码、定位问题、制定修改方案"]
  B --> C{"是否出现高风险判断点"}
  C -- "否" --> F["Executor 独立修改与验证"]
  C -- "是" --> D["Advisor 只读分析上下文"]
  D --> E["返回短建议：生产修复面 / 验证路径 / 停止条件"]
  E --> F
  F --> G["运行测试、检查 patch 与生产修复面"]
  G --> H{"验证是否闭合"}
  H -- "否" --> B
  H -- "是" --> I["交付结果，并记录 advisor 调用与用量数据"]

1. 任务进入执行链路

用户请求进入 Claude Code 后，由 executor 承担完整执行工作。executor 会按原有流程读取仓库上下文、定位相关文件、制定修改方案并执行验证。

2. 在高风险判断点触发 Advisor

Advisor 不是每个任务都强制调用，而是在执行过程中遇到高风险判断点时触发。典型触发点包括：

  • 生产代码入口不明确；
  • 多个文件都可能是修复面；
  • 修改可能影响跨模块调用；
  • executor 对根因判断不稳定；
  • 验证路径不清楚；
  • 已有尝试没有收敛，需要外部审查视角。

3. Advisor 只读分析上下文

Advisor 只能读取任务描述、相关代码片段、执行进展和必要的验证信息。它不具备编辑权限，也不会直接运行破坏性操作。

只读约束让 advisor 的职责保持清晰：它提供判断，不接管执行。

4. Advisor 返回短建议

Advisor 的输出被限制为短格式，重点回答 executor 当下最需要的判断：

  • 应优先查看或修改哪些生产文件；
  • 当前根因判断是否合理；
  • 哪些修改方向可能偏离任务；
  • 应使用什么验证路径；
  • 什么情况下应该停止继续扩散修改。

5. Executor 参考建议继续执行

Executor 会参考 advisor 的建议继续推进任务。如果源码、测试或实际运行结果与 advice 不一致，executor 可以以真实证据为准调整方案。

最终交付仍由 executor 完成，包括代码修改、验证命令、结果总结和风险说明。

6. 记录调用过程用于迭代

系统会记录 advisor 是否被触发、触发时机、建议内容摘要和执行结果。这些记录用于后续评测和策略迭代，不作为用户交互中的额外负担。

功能介绍

只读 Sideband Reviewer

Advisor 以旁路 reviewer 的方式接入主执行链路。它不会改变 executor 的权限模型，也不会绕过现有文件编辑、命令执行和权限控制。

跨模型组合

Advisor 能力在 agent 编排层实现，不绑定单一 provider。不同 executor 可以接入同一套 advisor 流程，例如使用一个模型执行任务，另一个模型提供审查建议。

这种方式便于按场景组合能力：强 executor 可以低频触发 advisor；弱 executor 或不稳定任务可以更积极地请求 advisor 审查。

风险触发

Advisor 的主要价值不是增加一次固定问答，而是在任务可能跑偏时提供第二视角。当前设计更适合按风险触发，而不是默认全量开启。

修复面约束

Advisor 会围绕生产修复面给出建议，避免把测试、文档、fixture、snapshot、生成文件或包元数据误当成主要修复对象。

这类约束有助于减少”为了通过验证而改错地方”的情况。

验证路径建议

Advisor 可以提醒 executor 使用更合适的验证方式，例如先跑聚焦测试，再根据改动范围选择更大的检查命令。它也可以指出当前验证信息不足，避免过早交付。

停止条件提醒

当任务出现反复尝试、修改范围扩大或证据不足时，advisor 可以提醒 executor 收束范围，回到最小可验证修改。

测试数据与效果

评测主要围绕真实 SWE 代码修复任务展开，对比 solo 执行和 advisor-mode 执行。这里的 valid 表示 scorecard 判定为有效结果；advisor-call valid 表示有效结果里 advisor 确实被调用。只有真实调用过 advisor 的行，才可以用于说明 advisor 介入后的效果。

实验线索

这轮评测按”先广度、再深度”的线索推进。第一步先确认 advisor 能不能跨 executor 接入；第二步把值得继续看的 executor 拆出来做 clean pair；第三步只对有完整 usage 的行看 token/cost；最后再决定下一轮该扩谁、停谁。

阶段做了什么得到什么下一步结论
广度筛查12 个 checkout-valid SWE 任务，覆盖 Haiku、Sonnet 4.6、LongCat2 Preview、DeepSeek，均包含 solo / GPT advisor / Opus advisoragent 层 advisor 能跨 executor 接入；但广度筛查里 no-call、invalid、usage 异常较多广度筛查只用于筛方向，不直接写 advisor 收益
强 executor 深挖对 Sonnet、DeepSeek 做同题 clean slice 和成本模式实验Sonnet+GPT 有单题真实 advisor-call 正向；DeepSeek 的强 executor 自解能力明显，advisor 真触发时有局部正向DeepSeek 继续做风险触发和 cost-mode 小样本；Sonnet+GPT 保留为真实 advisor-call 样本
Haiku / LongCat 分支对 Haiku 4.5、LongCat2 Preview 做 P0 first3 和非重复 Caddy3 小样本；LongCat-Flash-Chat 做兼容性筛查早期 P0 有 rescue 信号，但 Caddy3 复验里 Haiku advisor 负向，LongCat2 advisor 慢且不稳；LongCat-Flash-Chat 当前没有可用 patch 结果Haiku、LongCat2 不能作为默认正向结论，只能作为弱/慢 executor 的分层风险证据
成本链路验证DeepSeek Axios6 以及 Axios+Babel/Carbon12 cost-mode 关闭 validation early-stop，保留完整 usagetoken/cost 可以稳定统计；12 题合并表里 Opus/GPT advisor-mode 的 surface pass 高于 solo，但 Babel/Carbon6 暴露 timeout/rate_limit/checkout-lock 长尾后续比较 token/cost 只使用 usage_complete 行；大规模深跑要降并发或分层
分支切换后低并发复测babel__babel-15649 单题，CONCURRENCY=1，三臂均 valid 且 complete usage证明分支切换后 provider/runner 仍可跑通；低并发消除了同题上的 rate_limit/checkout-lock/no-json 污染该题 solo 也 surface pass，所以这是调度和成本信号，不是质量 rescue

DeepSeek 数据收拢

DeepSeek 相关实验可以放在一条线上看：先用 clean12 看强 executor 的自解能力，再用 Carbon 看 advisor 在高不确定任务上的价值，最后用 Axios6 与 Axios+Babel/Carbon12 cost-mode 验证完整 usage 下的成本表现和执行长尾。

数据集SoloAdvisor-mode结论
DeepSeek clean12, GPT advisor1/12 valid；median 165.8s / 477,787 tokens / $2.5346352/12 valid；median 71.1s / 104,860 tokens / $0.583367组合层更好，但有效胜出行没有调用 advisor，不能算 advisor 介入收益
DeepSeek Carbon, Opus advisor1,562,882 tokens / $8.2261981,464 tokens / $5.3344，真实 advisor call高不确定生产链路里 advisor 有明确价值，token 降约 37%，成本降约 35%
DeepSeek Axios6 cost-mode, Opus advisor6/6 valid；median 344.5s / 430,898 tokens / $2.3747006/6 valid；3 个 advisor-call valid；median 252.0s / 245,534 tokens / $1.382265完整 usage 下，小样本显示 Opus advisor 的时间、token、成本都下降
DeepSeek Axios+Babel/Carbon12 cost-mode7/12 valid；4/7 surface pass；median 347.8s / 513,764 tokens / $2.906680Opus: 9/12 valid、6/9 surface pass、3/9 advisor-call valid、median 290.8s / 255,803 / 2.98889812 题证明 cost-mode 可跑通，但 Babel/Carbon6 有 timeout/rate_limit/lock 污染。真 advisor-call surface rescue 只有 Opus axios-6539 和 GPT carbon-2665；no-call/combo 行不能算 advisor 收益

DeepSeek 的结论不是”advisor 应该强制开启”，而是”强 executor 自解能力强，advisor 应该在高风险点低频介入”。Carbon、Axios6 和 12 题 cost-mode 支持继续做风险触发，不支持每题强制调用；Babel/Carbon6 也说明深跑需要降并发，否则 rate limit 和 timeout 会污染结论。分支切换后的 CONCURRENCY=1 复测确认，低并发可以消掉同题上的 rate_limit/checkout-lock/no-json 噪音。新的 Caddy/Docusaurus12 复验进一步说明：advisor 能救个别 no-patch 题，但在 DeepSeek 上总体开销明显，不能默认开启。

Haiku / LongCat 单独说明

Haiku 和 LongCat 是另一条线：重点不是证明 token 更省，而是看 advisor 能不能提高完成稳定性，尤其是在弱或慢 executor 上。

Executor已有数据当前结论下一步
Haiku 4.5P0 first3 中 solo 1/3 valid；Haiku+Opus 3/3 valid，advisor 3/3 调用。Caddy clean pair 里 advisor 也命中 expected surface，但耗时、token、成本高于 solo有 completion rescue 信号；不能说 token/cost 稳定更优补 2-5 个 clean pair，只看有效行和真实 advisor-call 行，验证稳定性是否持续
LongCat2 PreviewP0 first3 中 solo 1/3 valid；LongCat2+Opus 2/3 valid，advisor 在 2/2 valid advisor 行里被调用。Caddy 是最清楚 rescue：advisor 以 313.2s / 162,330 tokens 完成 expected surface有有限的 completion rescue 信号，但 LongCat2 Preview 本身较慢、波动较大保留小批量 smoke，控制并发，不作为深跑主力
LongCat-Flash-Chat已做 provider/tool-protocol 筛查；当前表现为 text-form tool calls、no patch还没有可用于 advisor-effect 的质量或成本数据先解决 tool-call 协议兼容，再进入 advisor on/off 对照

Sonnet 补充样本

数据集SoloAdvisor-mode结论
Sonnet clean12, GPT advisor2/12 valid；median 389.9s / 474,262 tokens / $0.7227622/12 valid；2 个 advisor-call valid；median 305.1s / 1,098,040 tokens / $1.115779有真实介入样本，但整体 token/cost 更高，不适合默认开启
Sonnet babel__babel-15445296.9s / 466,769 tokens / $0.612594205.6s / 288,442 tokens / $0.376086，真实 advisor call清楚的单题正向样本：时间、token、成本都下降
Sonnet Caddy3, GPT advisor3/3 valid；3/3 surface pass；median 251.9s / 772,813 tokens / $0.8975603/3 valid；3/3 advisor calls；3/3 surface pass；median 233.6s / 681,146 tokens / $0.862909非重复小样本里 advisor 真实触发且不伤质量，GPT advisor median 时间、token、成本均低于 solo
Sonnet Caddy3, Opus advisor同上3/3 valid；3/3 advisor calls；3/3 surface pass；median 275.6s / 674,639 tokens / $0.804967Opus advisor 降 token/cost，但 median 时间略高于 solo
Sonnet Caddy/Docusaurus1211/12 valid；8/11 expected surface；median 252.5s / 794,591 tokens / $0.971724Opus: 11/12 valid、9/11 expected surface、9/11 advisor-call valid、median 240.1s / 844,288 / 0.804427当前最强的 Sonnet true-call 证据：advisor 介入后 expected-surface 比例更高。GPT 在 valid rows 上更快更省，但有两个 permission-denial regressions；Opus 更稳但 token 略高

综合判断

完整线索是：广度筛查证明能力可跨 executor 接入；DeepSeek / Sonnet 用于看强 executor 下 advisor 是否真的有收益；Haiku / LongCat 用于看弱或慢 executor 是否能被 rescue。

Advisor 的收益依赖触发点。强 executor 能自解的题，advisor-mode 的好结果经常来自 no-call，不能归因给 advisor。

DeepSeek 已经有最完整的数据链路：clean12 说明强 executor 自解能力，Carbon 说明高不确定任务上的 advisor 价值，Axios6/12 说明完整 usage 下的小样本成本和质量信号，同时也暴露 Babel/Carbon 长尾和限速问题。新的 Caddy/Docusaurus12 低并发复验进一步说明：advisor 能救个别 no-patch 题，但在 DeepSeek 上总体开销明显，不能默认开启。

Sonnet 现在有更清楚的 true-call 证据：Caddy3 和 Caddy/Docusaurus12 都显示 advisor 真实调用后能保持或改善生产修复面；GPT advisor 的成本/速度表现更好，但 permission-denial 回退需要继续看。

Haiku 和 LongCat2 Preview 可以单独讲，但最新 Caddy3 复验已经把口径收窄：只能讲弱/慢 executor 分层风险，不能讲稳定正向或成本优势。

LongCat-Flash-Chat 目前只能讲兼容性筛查结果，不能讲 advisor 效果。

适合的场景

复杂代码修复：当问题跨多个模块、调用链较长、生产入口不明显时，advisor 可以帮助 executor 更快判断应该看哪里、改哪里。

高风险生产链路：当修改可能影响核心流程、权限、持久化、工具执行、provider 调用或跨进程通信时，advisor 适合做额外审查。

弱模型或轻量模型执行：轻量 executor 在长任务中更容易遗漏上下文或误判修复面。Advisor 可以作为外部审查者，帮助它保持方向。

验证路径不明确：当 executor 不确定应该跑哪个测试、需要什么 smoke、是否应该继续扩大验证时，advisor 可以帮助明确下一步。

任务多次尝试仍未收敛：如果 executor 已经尝试过一个方向但没有得到可靠结果，advisor 可以审查当前思路，提示是否需要换入口、缩小范围或停止无效扩散。

不适合的场景

Advisor 不适合所有任务默认开启。以下情况通常不需要调用：

  • 简单、边界明确的单文件修改；
  • executor 已经能稳定自解的常规问题；
  • 只需要机械替换或格式调整的任务；
  • 没有代码风险、只做轻量文案调整的任务；
  • 当前问题主要受外部服务、网络或权限条件限制。

这些场景里，额外 advisor 调用可能只会增加流程复杂度。

使用方式

个人使用

Advisor 不是通过评测 runner 启动，而是在 Claude Code CLI 会话里打开和使用。当前通过 bin 入口启动 CLI；仓库内入口是 ./bin/claude-haha，如果本机已经配置了 cchaha 之类的别名，也可以直接用对应别名启动。

./bin/claude-haha

会话内开关

进入 CLI 后，通过 /advisor 命令管理 advisor。

命令作用
/advisor查看当前 advisor 状态
/advisor on打开 advisor
/advisor off关闭 advisor
/advisor set aws.claude-opus-4.7设置 advisor 模型
/advisor model aws.claude-opus-4.7同样用于设置 advisor 模型
/advisor unset清空已设置的 advisor 模型

推荐的个人使用顺序是：

/advisor set aws.claude-opus-4.7
/advisor on

打开后，executor 在适合的高风险节点可以调用 advisor。CLI 底部状态会显示 advisor on 或 advisor off，方便确认当前状态。

手动触发 Advisor

如果用户明确希望先听 advisor 建议，可以直接把任务写在 /advisor 后面：

/advisor 帮我判断这个登录态 bug 应该改哪个生产文件，先不要直接动代码

也可以用显式 task 写法：

/advisor task 检查这次重构应该优先验证哪些路径

手动触发时，advisor 会收集当前仓库上下文，生成只读建议，并写入 .agent/advice/ 下的 markdown 文件。随后 executor 会先阅读这份 advice，再继续执行任务。

典型使用场景

  • 不确定应该改哪个生产文件时，先用 /advisor task ... 做修复面判断；
  • 代码路径很长、跨模块调用多时，打开 advisor 作为风险节点 reviewer；
  • executor 多次尝试未收敛时，用 advisor 帮忙判断是否应该换入口或停止扩散；
  • 简单单文件改动、格式调整、文案类任务，一般保持 advisor off。

评测脚本入口

评测不是个人使用入口。评测主入口保留为 scripts/advisor-swe-parallel-live.sh，它会按 plan 批量调用 runner，并生成统一 scorecard。

常用 dry run：

DRY_RUN=1 \
PLAN_FILE=question/eval/plans/advisor_swe_breadth10_add7_deepseek_opus_v0.json \
BENCHMARK_FILE=question/eval/benchmark/swe_multilingual_advisor_breadth10_add7_v0.json \
PLAN_ITEM_SHARDS=1 \
PLAN_ID=swe-breadth10-add7-deepseek-opus-v0 \
scripts/advisor-swe-parallel-live.sh

常用小批量正式跑：

RUN_TAG=deepseek_opus_breadth10_sample \
PLAN_FILE=question/eval/plans/advisor_swe_breadth10_add7_deepseek_opus_v0.json \
BENCHMARK_FILE=question/eval/benchmark/swe_multilingual_advisor_breadth10_add7_v0.json \
PLAN_ITEM_SHARDS=1 \
PLAN_ID=swe-breadth10-add7-deepseek-opus-v0 \
CONCURRENCY=2 \
TIMEOUT=600 \
scripts/advisor-swe-parallel-live.sh

脚本输出两类文件：

  • question/eval/results/all_*.json：每个实验 shard 的原始结果；
  • question/eval/results/advisor_swe_parallel_<RUN_TAG>.md/json：统一 scorecard。

Scorecard 主入口

如果已经有一批 all_*.json，可以单独跑 scorecard：

python3 -B question/eval/advisor_p0_score.py \
  --benchmark-file question/eval/benchmark/swe_multilingual_advisor_breadth10_add7_v0.json \
  --results question/eval/results/all_*.json \
  --json-out question/eval/results/advisor_swe_parallel_sample.json \
  --markdown-out question/eval/results/advisor_swe_parallel_sample.md

最终看结果时，重点看这几个字段：

  • valid_rows：有效结果数；
  • advisor_call_rows / advisor_calls：advisor 是否真的介入；
  • median_tokens、median_cost_usd、median_wall_seconds：成本和耗时；
  • surface_pass、expected_surface_hit、forbidden_surface_hit：修复面是否合理；
  • usage_complete：token/cost 是否可用于对比。

评测迭代流程

Advisor 能力的评测重点不是单次结果，而是持续判断”什么时候该调用、调用后是否帮助 executor 做出更好的决策”。

1. 构造对照任务：评测会选取真实代码修复任务，保持任务输入、仓库状态和验证方式一致，对比 solo 执行与 advisor-mode 执行的差异。

2. 区分 Advisor 真实介入与未介入：Advisor-mode 并不等于 advisor 一定发挥了作用。评测会区分两类情况——advisor 被真实调用并产生可追踪建议，与 advisor-mode 开启但任务过程中没有触发 advisor。只有前一种情况才能用于分析 advisor 的实际影响。

3. 检查修复面是否正确：评测会关注修改是否落在合理的生产代码范围内，而不是只看任务是否产生了 patch。这样可以避免把错误修复面误判为有效结果。

4. 检查验证链路是否闭合：每个样本都会记录 executor 是否完成必要验证，验证是否与改动范围匹配，以及结果是否足以支撑交付。

5. 复盘触发策略：评测结束后会复盘 advisor 的触发时机——是否该触发但没有触发、是否触发过早或过晚、advice 是否聚焦生产修复、executor 是否正确吸收或拒绝 advice、触发规则是否需要调整。

6. 进入下一轮策略更新：根据复盘结果，迭代内容通常集中在三类——调整 advisor 触发条件、收紧或优化 advisor 输出格式、补充修复面/验证路径/停止条件约束。

当前推荐使用方式

现阶段建议把 advisor 作为风险触发能力使用，而不是默认全量开启。推荐策略是：

  • 常规简单任务由 executor 独立完成；
  • 生产链路不清楚时触发 advisor；
  • 修复面存在多个候选时触发 advisor；
  • 弱 executor 或长链路任务中适度提高触发概率；
  • 任务多次尝试未收敛时触发 advisor 做审查。

这样的使用方式能保持 executor 的执行效率，同时在高风险节点引入额外判断。

参考