autoresearch:evals 结果分析器:Claude Autoresearch 迭代结果的趋势、平台期与回归检测实战指南

原创2026-10-08 21:38:511,770 阅读
文章标签:AI 技能AI 插件代码质量开发工具

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 按固定顺序寻找待分析的结果文件:

  1. 提供了 path → 直接使用该 TSV;
  2. 未提供 path → 扫描当前目录及 autoresearch/*/ 下的所有 *-results.tsv 文件;
  3. 找到多个 → 通过 AskUserQuestion 列出所有文件,由用户选择"Which results to analyze?";
  4. 一个都没找到 → 询问用户"Provide path to results TSV";
  5. 额外扫描项目根目录下的 v2.0.03 遗留 TSV 文件(向后兼容,见后文)。

这条发现链保证了"最省事的用法":循环跑完后直接在输出目录执行 /autoresearch:evals 即可命中刚生成的结果文件。


四、TSV 解析流程

evals 对 TSV 的解析遵循严格的四步协议:

  1. 读第 1 行:提取 # metric_direction: higher_is_better|lower_is_better 注释。该注释由主循环在建立基线(Iteration 0)时写入 TSV 头部(见 claude-plugin/commands/autoresearch.md 中"Write TSV header"一步)。若缺失,则从列名推断(如 metric / error_count),推断不出就问用户;
  2. 读第 2 行:表头行,据此检测实际存在的列;
  3. 读剩余行:数据行;
  4. 优雅处理缺失的 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 表头(来自各命令文件)可交叉印证列来源:


六、报告结构(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 分别提供了面向用户的操作说明和面向工程的可执行判定,二者与命令协议共同构成了完整的结果分析体系。

登录后查看全文
autoresearch