autoresearch:evals 结果分析器:Claude Autoresearch 迭代结果的趋势、平台期与回归检测实战指南
autoresearch:evals 结果分析器:Claude Autoresearch 迭代结果的趋势、平台期与回归检测实战指南
本篇技术指南聚焦 Claude Autoresearch Skill 中的 autoresearch:evals 命令(仓库路径 claude-plugin/commands/autoresearch/evals.md)。该命令是"修改 → 验证 → 保留/回退 → 循环"自动化迭代流程(见 claude-plugin/commands/autoresearch.md)中的结果分析中枢:它一次性解析任意 *-results.tsv 文件,检测趋势、平台期(plateau)、速度变化与异常,并输出继续 / 停止 / 调整策略的 go/no-go 建议。读完本文,你将掌握如何单次分析任意循环命令的实验结果、如何在长循环中嵌入自适应检查点、如何把 evals 接入 CI/CD 与命令链,以及这些能力背后的 TSV 数据契约与源码级判定逻辑。
一、命令定位:evals 在 Autoresearch 生态中的角色
Autoresearch 的核心循环由主命令 autoresearch 驱动:围绕任意可量化指标(metric)反复执行 修改 → 验证 → 保留/丢弃,并把每一轮的结果以 TSV 行追加到 autoresearch/loop-{YYMMDD}-{HHMM}/ 目录。而 debug、fix、security、scenario、reason、learn 等子命令各自运行自己的有界循环,同样产出 *-results.tsv。
autoresearch:evals 就是对这些循环产物做"复盘"的命令:
- 解析任意循环命令(autoresearch、debug、fix、security、scenario、reason)产生的
*-results.tsv; - 检测收敛趋势、平台期区域和速度跌落(velocity drops);
- 找出单轮改进最大的高影响迭代(biggest positive deltas);
- 标记异常:连续 discard、guard 失败、指标震荡(oscillation);
- 以
text、json或md三种格式输出结构化报告; - 给出继续循环或停止循环的 go/no-go 建议。
从命令文件的元信息可以确认其接口形态:
name: autoresearch:evals
description: "Analyze iteration results: trends, plateaus, regressions, recommendations"
argument-hint: "[path/to/results.tsv] [--format text|json|md]"
它有两种使用场景:一次性分析(对既有结果文件做单次复盘)与 循环内嵌检查点(通过主循环命令的 --evals 标志在运行途中自动触发)。
二、参数解析
autoresearch:evals 从 $ARGUMENTS 中提取三类参数:
| 参数 | 含义 | 说明 |
|---|---|---|
| 位置参数(path) | 指向某个具体的 TSV 文件 | 若省略,则走输入发现逻辑(见下节) |
--format |
输出格式:text、json、md |
默认 text(控制台输出) |
--compare <path> |
对比另一份结果文件 | 注意:这是 v2.2.0 的占位参数,当前版本尚未实现,传入后应提示用户该能力未落地 |
三、输入发现(Input Discovery)
当未显式给出文件路径时,evals 按固定顺序寻找待分析的结果文件:
- 提供了 path → 直接使用该 TSV;
- 未提供 path → 扫描当前目录及
autoresearch/*/下的所有*-results.tsv文件; - 找到多个 → 通过 AskUserQuestion 列出所有文件,由用户选择"Which results to analyze?";
- 一个都没找到 → 询问用户"Provide path to results TSV";
- 额外扫描项目根目录下的 v2.0.03 遗留 TSV 文件(向后兼容,见后文)。
这条发现链保证了"最省事的用法":循环跑完后直接在输出目录执行 /autoresearch:evals 即可命中刚生成的结果文件。
四、TSV 解析流程
evals 对 TSV 的解析遵循严格的四步协议:
- 读第 1 行:提取
# metric_direction: higher_is_better|lower_is_better注释。该注释由主循环在建立基线(Iteration 0)时写入 TSV 头部(见 claude-plugin/commands/autoresearch.md 中"Write TSV header"一步)。若缺失,则从列名推断(如metric/error_count),推断不出就问用户; - 读第 2 行:表头行,据此检测实际存在的列;
- 读剩余行:数据行;
- 优雅处理缺失的
timestamp列:这是 v2.0.03 兼容性要求——老版本 TSV 没有时间戳列,解析器不得因此报错。
五、列检测与逐列分析(核心能力)
evals 的核心设计是动态列检测:不预设固定 schema,而是根据表头实际存在的列激活对应分析。以下是命令文档中定义完整的列 → 分析映射,并附各列在实际循环命令中的来源:
| 列 | 激活的分析 | 主要来源命令 |
|---|---|---|
metric |
趋势方向、平台期检测(3+ 轮持平)、收益递减、单轮最大跳变 | autoresearch、fix |
delta |
每轮效率、累计改进、投入-收益比(effort-to-gain ratio) | autoresearch、fix |
status |
keep/discard 率、崩溃频率、成功连胜、失败簇、最长连胜 | 所有命令 |
guard + guard-metric |
guard 失败率、"指标改进但 guard 失败"分析 | autoresearch、fix |
severity |
严重级分布(critical/high/medium/low/info)、每轮 critical 发现率 | debug、security |
hypothesis + status |
假设确认率、调查效率、最高产的技术手段 | debug |
commit |
文件热点分析(与保留提交的 git diff 交叉引用)、变更规模相关性 |
autoresearch、fix |
technique |
技术手段有效性排名 | debug |
dimension |
维度覆盖完整度(X/12) | scenario |
candidate_label + judge_verdict |
收敛速度、震荡次数 | reason |
error_type |
错误类别分布、各类别修复率 | fix |
classification |
new / extension / duplicate 比例、饱和曲线 | scenario |
convergence_count |
收敛轨迹 | reason |
未知列:仅报告其存在、跳过分析。这一设计使 evals 对未来的子命令保持前向兼容——新子命令引入新列时,旧版 evals 不会崩溃,只是暂时不分析该列。
各命令实际写入的 TSV 表头(来自各命令文件)可交叉印证列来源:
fix:iteration\ttimestamp\terror_type\terror_fixed\tcommit\tmetric\tdelta\tguard\tstatus\tdescription(claude-plugin/commands/autoresearch/fix.md);debug:iteration\ttimestamp\thypothesis\tstatus\ttechnique\tevidence\tfile_line(claude-plugin/commands/autoresearch/debug.md);security:iteration\ttimestamp\tfinding\tseverity\towasp\tstride\tevidence\tfile_line(claude-plugin/commands/autoresearch/security.md);scenario:iteration\ttimestamp\tscenario\tdimension\tclassification\tseverity\tdescription,注意它没有# metric_direction注释——因为场景探索不是指标优化(claude-plugin/commands/autoresearch/scenario.md);reason:round\ttimestamp\tcandidate_label\tjudge_verdict\tconvergence_count\tdescription(claude-plugin/commands/autoresearch/reason.md)。
六、报告结构(Report Structure)
evals 输出的核心报告遵循如下模板,任何循环命令的分析结果都能套入:
## Evals Summary — {subcommand} ({N} iterations)
### Key Metrics
- Total iterations: N | Kept: X | Reverted: Y | Revert rate: Z%
- Starting metric: A | Final metric: B | Improvement: C%
### Trend Analysis
- Metric progression: [description of trajectory]
- Plateau detected at iteration N (metric stable for M iterations)
- Biggest win: iteration X (+delta, description)
- Biggest loss: iteration Y (-delta, description)
- Diminishing returns: [after iteration N, average delta dropped below threshold]
### Patterns
- What types of changes succeeded: [extracted from descriptions of kept iterations]
- What types of changes failed: [extracted from descriptions of discarded iterations]
- File hotspots: [files changed most in kept iterations, if commit data available]
- Technique effectiveness: [ranked by confirmation rate, if technique column present]
### Recommendation
- [continue / stop / change strategy — based on trend, plateau, revert rate]
- [specific actionable suggestion based on pattern analysis]
模板各段的生成依据:
- Key Metrics 由
metric、status两列直接统计; - Trend Analysis 中的"平台期"判定来自
metric列(连续 M 轮持平)与delta列(平均 delta 跌破阈值判定收益递减); - Patterns 部分依赖
description列做语义归纳、commit列做文件热点统计、technique列做手段有效性排序; - Recommendation 是最终决策段,综合趋势、平台期和 revert rate 三要素。
用户侧的操作指南 guide/autoresearch-evals.md 给出了更直观的解读示例——例如平台期可以这样呈现:
Iterations 1–8: +2.1% avg delta (strong momentum)
Iterations 9–15: +0.8% avg delta (slowing)
Iterations 16–20: +0.1% avg delta (plateau)
Plateau detected at iteration 16 — 5 consecutive iterations below 0.1% delta
速度与异常报告示例:
Best iteration: #7 (+3.2%) — add payment edge case tests
Worst keep: #12 (+0.1%) — minor refactor
Keep rate: 68% (17/25)
Discard rate: 28% (7/25)
Rework rate: 4% (1/25)
ANOMALY: 4 consecutive discards at iterations 9–12
ANOMALY: Guard failed 3 times — npm test failures during bundle optimization
NOTE: Metric oscillated between 187KB and 203KB in iterations 14–17
七、输出格式
控制台输出(默认 text)
结构化报告,约 30–50 行,包含 summary、velocity、anomalies、recommendation 四个区块,适合人读。
--format md
在同一目录写出 evals-summary.md(命令文档口径)——注意与用户指南的另一个口径(evals/{YYMMDD}-{HHMM}-{slug}-report.md)略有差异,实际以命令文档 evals-summary.md 为准。Markdown 报告适合附在 PR 上或与结果文件一起存档。
--format json
写出 evals-summary.json,机器可读,含全部指标、趋势数据和异常标志,供 CI/CD 解析。用户指南给出了 JSON 的示例结构:
{
"iterations_run": 25,
"keeps": 17,
"discards": 7,
"baseline": 287,
"final": 198,
"improvement_pct": 31.7,
"plateau_detected": true,
"plateau_start": 16,
"goal_achieved": true,
"recommendation": "STOP",
"anomalies": ["4_consecutive_discards_at_9-12"]
}
八、中途检查点协议(Mid-Loop Checkpoint Protocol)
这是 evals 能力向其他循环命令的内嵌扩展:autoresearch、debug、fix、security、scenario、reason、learn 都接受 --evals 与 --evals-interval N 两个标志,在循环中途按固定节奏暂停、分析当前 TSV、打印压缩检查点。
自适应间隔
间隔默认按 floor(max_iterations / 3) 计算(最小为 1);无界循环固定为 10;可用 --evals-interval N 覆盖。
| 子命令 | 默认迭代数 | 默认检查点间隔 | 检查点位置 |
|---|---|---|---|
| reason | 8 | 2 | 2, 4, 6, 8 |
| learn | 10 | 3 | 3, 6, 9, final |
| debug / security | 15 | 5 | 5, 10, 15 |
| fix / scenario | 20 | 6 | 6, 12, 18, final |
| core | 25 | 8 | 8, 16, 24, final |
| unbounded | unlimited | 10 | every 10 |
检查点格式(最多 5 行)
--- Eval Checkpoint (iterations {X}-{Y}) ---
Metric: {start} → {end} ({delta}) | Kept: {n}/{total} | Trend: {up/flat/down}
{one-line recommendation}
---
各子命令的检查点内容随其指标而异,例如:
fix:Errors: {start} → {end} ({delta}) | Kept: {n}/{total} | Trend: {up/flat/down}(claude-plugin/commands/autoresearch/fix.md);debug:Findings: {confirmed} confirmed | Trend: {up/flat/down};scenario:New scenarios: {n} | Dimensions covered: {x}/12 | Saturation: {status};reason:Incumbent: {label} | Convergence: {count}/{target} | Oscillations: {n};security:Score: {start} → {end} | New findings: {n} | Coverage: OWASP {x}/10, STRIDE {y}/6;learn:Docs written: {n} | Validation: {pass}/{total} | Gaps remaining: {m}。
早停建议
- 若连续 3+ 个检查点都检测到平台期(或等价信号:无新确认 finding、无新文档、mostly duplicates、oscillation)→ 建议提前停止;
- 循环结束后 → 生成完整 evals 报告到控制台,并写
evals-summary.md。
用户指南补充了平台期中止时的交互选项:Claude 暂停并询问是继续当前方案 / 扩大范围 / 换策略 / 停止并复盘。
九、向后兼容(Backward Compatibility)
evals 对历史数据兼容性有明确承诺:
- v2.0.03 TSV:列名原样保留,缺失
timestamp列时优雅处理; - 模糊列匹配:
metric_value→metric,error_count→metric; - 扫描范围:项目根目录(非
autoresearch/子目录)的遗留文件也会被输入发现逻辑扫描到; - v2.0.03 状态值全支持:
baseline、keep、keep (reworked)、discard、crash、no-op、hook-blocked、metric-error。
这些状态值在主循环的"Decide"阶段产生(claude-plugin/commands/autoresearch.md):指标改进且 guard 通过 → keep;指标变差 → discard(git revert HEAD --no-edit);verify/guard 命令崩溃 → crash;本轮无改动 → no-op;git hook 阻止提交 → hook-blocked;verify 输出不是合法数字 → metric-error。
十、源码级纵深:平台期与收敛判定的实现原理
evals 命令本身是面向 Claude 的协议文档,但其判定的核心逻辑在仓库脚本中具备可直接验证的实现——scripts/orchestrate.sh 提供了多个纯函数式判定入口,可作为理解 evals 平台期逻辑的底层参考:
plateau 子命令(平台期判定)
读取单位值历史(每行一个数值或 unknown),判定"最近 N 个计算值持平或变差":
- 跳过穿插的
unknown(崩溃/不可计算轮次); - 连续 N=5 个尾部 unknown → BLOCKED(exit 3),防止"持续输出 unknown 的卡死循环"被误读为仍在进步;
- 至少需要 N 个计算值才可判定平台期;
- 净改进 = 窗口内最后一个值严格低于第一个值(lower_is_better 语义)→ 判定仍在进步(exit 1);任何震荡只要净持平或变差 → 平台期(exit 0)——这从源码层面印证了 evals"震荡也计平台期"的设计(见 orchestrate.sh 的
plateau()函数)。
units 子命令(单位剩余量)
units = failing_tests + open_hard_regressions + (metric_delta / metric_target),lower_is_better;目标为 0 时拒绝计算(防除零),输入缺失时输出 unknown 并 exit 2。该标量正是 orchestrator 路由决策中"进展是否停滞"的量化依据。
verdict 子命令(收敛裁决)
读取 units、plateau、ceiling 三个状态字段:plateau==true → PLATEAU(ship=no);ceiling==true → CEILING(ship=no);units==0 且无平台期/天花板 → CONVERGED(ship=yes);否则 → BLOCKED。这与 evals 报告最终段"continue / stop / change strategy"的裁决逻辑同构:平台期与回退率是停止的主要触发条件。
路由侧印证
claude-plugin/skills/autoresearch/references/orchestrator-routing.md 的路由决策表中,optimize-metric 类目标的预设管线为 plan → (classic loop) → holdout-verify → evals,即 evals 是指标优化类目标的收尾环节;而 plateau detected(由 scripts/orchestrate.sh plateau 计算)会直接路由到 PLATEAU(停止并报告)。这解释了 evals 与 orchestrator 的配合关系:orchestrator 决定"何时路由",evals 负责"证据呈现与建议输出"。
十一、实战:命令链、CI/CD 与典型用法
1. 循环结束后的基础复盘
/autoresearch
Iterations: 25
Goal: Reduce bundle size below 200KB
Verify: npm run build 2>&1 | grep "First Load JS"
# After loop completes:
/autoresearch:evals --recommend
2. 中途每 5 轮检查点
/autoresearch
Iterations: 50
Goal: Increase test coverage to 90%
Verify: npm test -- --coverage | grep "All files"
--evals-interval 5
每 5 轮打印压缩检查点,结束时输出完整报告。
3. 目标达成 → 移交 ship
/autoresearch:evals --recommend --chain ship
当推荐为 STOP 且目标达成时,立即交接给 autoresearch:ship(对接命令链机制,见主命令文档的 --chain 参数)。
4. 安全审计后的分析
/autoresearch:security
Iterations: 15
/autoresearch:evals --file security/*/security-audit-results.tsv --format md
5. CI/CD 解析 evals JSON 输出
- name: Analyze autoresearch results
run: |
claude -p "/autoresearch:evals --format json" > evals-report.json
goal_achieved=$(jq '.goal_achieved' evals-report.json)
if [ "$goal_achieved" = "true" ]; then
echo "Goal achieved — proceeding to ship"
fi
6. debug 会话复盘
/autoresearch:debug
Iterations: 15
/autoresearch:evals --file debug/*/debug-results.tsv --format md
十二、小结:什么时候该用 evals
- 循环刚跑完 → 执行
/autoresearch:evals(或加--recommend)获得复盘报告与下一步建议; - 长循环运行中 → 给主命令加
--evals/--evals-interval N,让循环自己按自适应间隔做中途检查、提前止损; - 需要自动化 →
--format json对接 CI/CD;--chain ship在目标达成时自动交接; - 处理历史数据 → 直接喂入 v2.0.03 遗留 TSV,模糊列匹配与缺失列容错保证兼容。
evals 的价值在于把"反复试错"变成"可量化的收敛证据":趋势、平台期、回退率、异常簇共同构成停止或继续的决策依据,而 guide/autoresearch-evals.md 与 scripts/orchestrate.sh 分别提供了面向用户的操作说明和面向工程的可执行判定,二者与命令协议共同构成了完整的结果分析体系。