Autoresearch Evals:Claude Autoresearch 迭代结果分析协议全解析
Autoresearch Evals:Claude Autoresearch 迭代结果分析协议全解析
Autoresearch 项目(Claude Autoresearch Skill,仓库根目录 README.md)以"修改 → 验证 → 保留/回滚 → 无限重复"的自主迭代循环为核心,而 evals(结果分析)命令 正是这条循环的"仪表盘":它一次性分析任意 *-results.tsv 迭代日志,检测趋势、平台期(plateau)、回归与异常,并给出继续、停止或换策略的明确建议。本文以 .opencode/commands/autoresearch_evals.md 为骨架,结合仓库中的命令规格、Guide 文档与源码实现,完整讲解 evals 的参数解析、输入发现、TSV 解析、列驱动分析、报告结构与中循环检查点协议,并给出可直接复制的调用示例,让读者掌握"读懂迭代数据并做出 go/no-go 决策"的完整能力。
1. Evals 是什么:一次循环的复盘工具
在 Autoresearch 中,所有循环类子命令(autoresearch、debug、fix、security、scenario、reason、learn 等)都会把每一轮迭代的结果追加写入 *-results.tsv 文件。evals 命令负责读取这些 TSV 并输出结构化复盘报告。
根据 .opencode/commands/autoresearch_evals.md 的元数据定义,该命令的定位是:
- 功能:Analyze iteration results —— trends, plateaus, regressions, recommendations;
- 参数形态:
[path/to/results.tsv] [--format text|json|md]; - 执行指令:
EXECUTE IMMEDIATELY,即解析到参数后直接开始分析,不需要额外确认。
guide/autoresearch-evals.md 对它的概括更加直白:它是一次性(one-shot)分析任何循环产生的 *-results.tsv 的工具,能够动态探测 TSV 列结构,因此与所有循环命令兼容,同时向后兼容 v2.0.x 的 TSV 格式。这意味着 evals 不绑定某个具体子命令——无论是优化 bundle 大小的 autoresearch 主循环,还是 debug 的假说验证循环,只要产物是 *-results.tsv,evals 就能分析。
在 plugins/autoresearch/skills/autoresearch/SKILL.md 的子命令表中,$autoresearch evals 被列为 N/A(无默认迭代次数),因为它是分析型命令而非循环型命令;同一张表也确认了所有循环命令都支持 --evals 与 --evals-interval N 两个通用标志,这正是 evals 能"嵌入"循环内部的机制。
2. 参数解析与输入发现
2.1 支持的参数
按照命令规格(.opencode/commands/autoresearch_evals.md),从 $ARGUMENTS 中提取三类参数:
| 参数 | 说明 | 状态 |
|---|---|---|
| 位置参数(path/to/results.tsv) | 指定要分析的 TSV 文件路径 | 已实现 |
--format text|json|md |
输出格式:text(默认控制台)、json、md(写入 Markdown 文件) | 已实现 |
--compare <path> |
与另一份结果对比 | v2.2.0 占位符,尚未实现 |
需要说明的是,--compare 在规格中被明确标注为占位符(placeholder),使用时应视其为预留接口而非可用功能。
另外,guide/autoresearch-evals.md 还记录了更丰富的标志集(对应 Guide 层面的演进版本),其中与本节直接相关的是:
| 标志 | 用途 | 默认值 |
|---|---|---|
--file <path> |
指定目标 TSV 文件 | 自动探测最新的 *-results.tsv |
--format text|json|md |
输出格式 | text |
--recommend |
附加 go/no-go 建议与下一步 | 关闭 |
--plateau-window N |
定义"平台期"所需的连续迭代数 | 5 |
--chain <targets> |
分析完成后链式调用后续命令 | 无 |
2.2 输入发现规则(五步探测)
当用户没有显式给出路径时,命令按以下顺序自动发现输入(.opencode/commands/autoresearch_evals.md 第 16–22 行):
- 给了路径 → 直接使用该 TSV;
- 没给路径 → 扫描当前目录 +
autoresearch/*/下所有*-results.tsv文件; - 找到多个 → 询问用户"Which results to analyze?",并列出找到的文件;
- 一个都没找到 → 询问用户提供结果 TSV 路径;
- 附加扫描:同时扫描项目根目录下的 v2.0.03 遗留 TSV 文件(向后兼容)。
这套规则保证了三种典型场景都能顺畅工作:明确指定文件、目录中恰好一份结果(直接分析)、目录中多份结果(让用户选择)。与 plugins/autoresearch/skills/autoresearch/autoresearch.md 中主循环的产物约定对应——循环会把结果写入 autoresearch/loop-{YYMMDD}-{HHMM}/ 目录并维护 results.tsv(实际命名为 *-results.tsv 模式),因此 evals 的自动扫描恰好能覆盖循环的输出位置。
3. TSV 解析与列探测机制
3.1 解析四步
evals 对 TSV 的解析是"先读元数据、再读结构、最后读数据"的渐进过程:
- 读第 1 行:提取
# metric_direction: higher_is_better|lower_is_better注释,确定指标方向(越大越好还是越小越好);- 若缺失 → 从列名推断(
metric/error_count猜测),拿不准就询问用户;
- 若缺失 → 从列名推断(
- 读第 2 行:表头行 → 检测可用列;
- 读剩余行:数据行;
- 优雅处理缺失
timestamp列(v2.0.03 兼容)。
这一步的关键设计是:方向注释缺失时宁可询问也不瞎猜。方向决定了"delta 为正是否意味着进步",是后续所有趋势判断的基准,猜错方向会直接导致整份报告结论反转。
3.2 主循环如何产出 TSV(数据来源侧)
理解解析逻辑后,有必要看一下数据是怎么写出来的。plugins/autoresearch/skills/autoresearch/autoresearch.md 中定义了主循环的 TSV 格式约定:
- 第 0 行(基线):
0\t{timestamp}\t{commit}\t{metric}\t0.0\t{guard}\t-\tbaseline\tinitial state; - 表头:
# metric_direction: {direction}换行后接iteration\ttimestamp\tcommit\tmetric\tdelta\tguard\tguard-metric\tstatus\tdescription; - 数据行:每轮迭代追加
iteration, timestamp, commit/-, metric, delta, guard status, guard-metric, status, description。
可以看到表头第一行就是 evals 解析依赖的 # metric_direction 注释,二者是一一对应的契约。文档 docs/codebase-summary.md 中也将 evals-summary.md(evals 命令或任何带 --evals 标志的命令产生)与 evals-summary.json(evals 命令加 --format json 产生)列入项目产物清单。
3.3 列驱动分析表
TSV 的每一列都会激活对应维度的分析(.opencode/commands/autoresearch_evals.md 第 34–52 行)。这是 evals 的核心机制——"有多少列,就分析多深":
| 列 | 激活的分析 |
|---|---|
metric |
趋势方向、平台期检测(3+ 次持平迭代)、收益递减、单次迭代最大跃升 |
delta |
单次迭代效率、累计提升、投入产出比 |
status |
keep/discard 比率、崩溃频率、成功连续段、失败簇、最长连胜 |
guard + guard-metric |
守卫失败率、指标提升但守卫失败的交叉分析 |
severity |
严重度分布(critical/high/medium/low/info)、每轮 critical 发现率 |
hypothesis + status |
假说确认率、调查效率、最高产技术 |
commit |
文件热点分析(与已保留提交的 git diff 交叉引用)、变更规模相关性 |
technique |
技术手段有效性排名 |
dimension |
维度覆盖完整性(X/12) |
candidate_label + judge_verdict |
收敛速度、振荡次数 |
error_type |
错误类别分布、每类修复率 |
classification |
new vs extension vs duplicate 比例、饱和曲线 |
convergence_count |
收敛轨迹 |
未知列:报告其存在但跳过分析。这一设计让 evals 对未来新增的子命令列保持前向兼容——新列不会导致解析失败,只是暂不参与分析。从源码结构看,这与 plugins/autoresearch/skills/autoresearch/SKILL.md 中"列存在则分析、缺列则优雅降级"的描述相互印证。
3.4 各子命令产出的典型列
guide/autoresearch-evals.md 给出了各循环命令实际会写入哪些列,帮助理解同一份 TSV 为何列结构不同:
| 列 | 产生命令 | 含义 |
|---|---|---|
iteration |
所有 | 循环计数器 |
commit |
autoresearch、fix | 保留时的 Git SHA |
metric |
autoresearch、fix | 数值型指标 |
delta |
autoresearch、fix | 相对上次保留迭代的变化 |
guard |
autoresearch、fix | pass / fail / skip |
status |
所有 | baseline / keep / discard / rework |
description |
所有 | 变更的一行摘要 |
severity |
debug、security | Critical / High / Medium / Low |
hypothesis |
debug | 假说文本 |
owasp |
security | OWASP 类别 |
stride |
security | STRIDE 标签 |
dimension |
scenario | 12 维度中的哪一个 |
winner_type |
reason | A / B / AB |
4. 报告结构:四段式复盘
分析完成后,evals 输出结构化的四段式报告(.opencode/commands/autoresearch_evals.md 第 54–79 行):
## 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 —— 一眼看到总量与成败比(总迭代、保留数、回滚数、回滚率、起止指标、提升百分比);
- Trend Analysis —— 判断"还有没有戏":轨迹描述、平台期位置、最大胜/败迭代、收益递减拐点;
- Patterns —— 回答"什么有效、什么无效":从保留/丢弃迭代的描述中提取成功与失败模式,有 commit 列时给出文件热点,有 technique 列时给出按确认率排序的技术排名;
- Recommendation —— 给出决策:continue / stop / change strategy,并附基于模式分析的具体行动建议。
guide/autoresearch-evals.md 补充展示了同类分析的另一种呈现(Velocity Report 风格),例如:
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)
以及异常标记与 go/no-go 建议:
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
RECOMMENDATION: STOP — plateau reached
Baseline: 287KB → Current: 198KB (-31.7%)
Goal achieved: YES (target was <200KB)
Suggested next step: /autoresearch:ship --type code-pr --auto
从仓库的测试基础设施看,这类"趋势/平台/回归"判定并非纯文字描述——scripts/score-regression.sh 及其插件副本 plugins/autoresearch/skills/autoresearch/scripts/score-regression.sh 展示了同类 TSV 数值分析在"回归稳定性门禁"场景中的落地方式(baseline vs candidate、STABLE/UNSTABLE 判定),且 tests/fixtures/regression/ 下存放了 score-boundary-94.tsv、score-boundary-95.tsv、perf-over-band.tsv 等边界与异常用例,说明这类"读 TSV → 算指标 → 出结论"的分析逻辑在项目中有成体系的测试覆盖(参见 tests/test-regression.sh)。
5. 输出格式:text / md / json
5.1 三种输出形态
按命令规格(.opencode/commands/autoresearch_evals.md 第 81–85 行):
- 控制台(默认):输出 30–50 行的结构化报告;
--format md:在输入 TSV 同目录写入evals-summary.md;--format json:写入evals-summary.json,含结构化数据。
guide/autoresearch-evals.md 对三者的定位描述得更细:
- text —— 人类可读的控制台输出,包含 summary、velocity、anomalies、recommendation 各段;
- md —— Markdown 报告,保存到
evals/{YYMMDD}-{HHMM}-{slug}-report.md,适合挂到 PR 上或与结果文件一起留存; - json —— 机器可读的 JSON,含全部指标、趋势数据与异常标记,适合 CI/CD 解析。
5.2 JSON 输出示例
Guide 文档给出了可直接对照的 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"]
}
注意字段语义:improvement_pct 是百分比数值(31.7 而非 0.317),plateau_start 是平台期起始迭代号,recommendation 是可直接做分支判断的枚举值(如 STOP)。这与 docs/project-changelog.md 中记录的演进(--evals 标志在所有循环命令上引入"自适应中循环检查点 + 最终 evals-summary.md")保持一致。
6. 中循环检查点协议(--evals 内嵌机制)
evals 不只是"事后分析"工具,它还能被循环命令内嵌为中循环的"体检"(.opencode/commands/autoresearch_evals.md 第 87–111 行)。
6.1 自适应间隔
- 计算公式:
floor(max_iterations / 3),最小为 1;无界循环固定为 10; - 覆盖方式:
--evals-interval N可手动覆盖。
以各子命令默认迭代次数计算的检查点分布如下:
| 子命令 | 默认迭代数 | 检查点间隔 | 检查点位置 |
|---|---|---|---|
| reason | 8 | 2 | 2, 4, 6, 8 |
| learn | 10 | 3 | 3, 6, 9, 最终 |
| debug/security | 15 | 5 | 5, 10, 15 |
| fix/scenario | 20 | 6 | 6, 12, 18, 最终 |
| core | 25 | 8 | 8, 16, 24, 最终 |
| unbounded | 无限制 | 10 | 每 10 次 |
(默认迭代数来自 plugins/autoresearch/skills/autoresearch/SKILL.md 的子命令表,检查点分布来自命令规格的示例表。)
6.2 检查点格式(最多 5 行)
--- Eval Checkpoint (iterations {X}-{Y}) ---
Metric: {start} → {end} ({delta}) | Kept: {n}/{total} | Trend: {up/flat/down}
{one-line recommendation}
---
6.3 三条关键规则
- 早停建议:若连续 3+ 个检查点都检测到平台期 → 建议提前停止;
- 最终汇总:循环结束时,在控制台输出完整 evals 报告,并写入
evals-summary.md; - 触发方式:主循环规格(plugins/autoresearch/skills/autoresearch/autoresearch.md)中规定,带
--evals时每current_iteration % interval == 0执行一次检查点分析;若连续 3+ 检查点平台期则建议早停;循环结束时把完整汇总写入输出目录的evals-summary.md。
Guide 文档还补充了检查点的 4 项内容(速度趋势、平台期检测——连续 N 次 delta < 0.1%、异常标记、建议),以及平台期检测到后 Claude 会暂停并向用户提供四个选项:继续当前方案 / 扩大范围 / 换策略 / 停止并复盘。这正是"修改 → 验证 → 保留/回滚"循环中的人类监督闸门,避免无意义的空转迭代。
7. 典型调用场景与组合用法
7.1 基本用法(无参数自动探测)
# 分析最近一次循环的结果 TSV(自动探测)
/autoresearch:evals
结合 .opencode/commands/autoresearch_evals.md 的输入发现规则,无参调用会扫描当前目录与 autoresearch/*/,找到唯一结果则直接分析,多个则列出待选。
7.2 指定文件 + 指定格式
# 分析 security 审计结果并输出 Markdown 报告
/autoresearch:security
Iterations: 15
/autoresearch:evals --file security/*/security-audit-results.tsv --format md
7.3 中循环检查点(内嵌在循环中)
/autoresearch
Iterations: 25
Goal: Reduce bundle size below 200KB
Verify: npm run build 2>&1 | grep "First Load JS"
--evals
--evals-interval 5
这段配置让主循环每 5 次迭代打印一份检查点报告(含指标、保留数、趋势与一行建议),循环结束后输出最终报告。
7.4 建议 + 链式交接
# 目标达成时建议 STOP,并链式交给 ship
/autoresearch:evals --recommend --chain ship
当建议为 STOP 且目标已达成时,立即交接给 ship 命令(对应 SKILL.md 中 --chain <targets> 通用标志的语义)。
7.5 CI/CD 中解析 JSON
guide/autoresearch-evals.md 给出了把 evals 接入流水线的完整示例:
- 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
这是 --format json 的核心价值:goal_achieved、recommendation、anomalies 都是结构化字段,可直接被 jq 消费并驱动流水线分支。
8. 向后兼容与模糊列匹配
evals 对旧版本产物保持了明确的兼容承诺(.opencode/commands/autoresearch_evals.md 第 113–118 行):
- v2.0.03 TSV:列名保持原样,缺失
timestamp时优雅处理; - 模糊列匹配:
metric_value→metric,error_count→metric; - 文件位置:项目根目录(而非
autoresearch/子目录)的 TSV 也会在扫描时被发现; - 状态值全集:
baseline、keep、keep (reworked)、discard、crash、no-op、hook-blocked、metric-error全部支持。
其中 hook-blocked(git hook 拦截提交)与 metric-error(verify 输出不是合法数字)两个状态来自主循环的决策阶段(plugins/autoresearch/skills/autoresearch/autoresearch.md 第 74–83 行),evals 对它们的完整支持意味着即使是"异常终止"的迭代也能如实纳入统计,而不会被误判或丢弃。
guide/autoresearch-evals.md 的兼容声明进一步补充:v2.0.x 中存在的列完全受支持;v2.1.0 新增列在缺失时被视为可选,分析优雅降级而非报错失败——与命令规格中"未知列:报告存在但跳过分析"的前向兼容设计互为表里。
9. 结语:把迭代数据变成决策依据
evals 是 Autoresearch 循环的"决策枢纽":它用一套统一的分析协议,把各子命令产出的异构 TSV 转译成可读、可传递、可编程消费的复盘结论。核心要点可以浓缩为四条:
- 列驱动:分析深度由 TSV 的列结构决定,缺列优雅降级,未知列前向兼容;
- 方向先行:
# metric_direction注释缺失时宁可询问也不猜测,保证 delta 语义正确; - 双模式:既可作为独立的一次性复盘命令(
/autoresearch:evals),也可通过--evals/--evals-interval内嵌为循环的周期性检查点,配合"3+ 检查点平台期即建议早停"的规则控制空转; - 可编程出口:
--format json让goal_achieved、recommendation、anomalies成为 CI/CD 可直接消费的结构化信号,--chain让"分析 → 交接"变成无缝流水线。
从 docs/development-roadmap.md 和 docs/project-changelog.md 的演进记录看,evals 的能力仍在持续扩展(如 --compare 对比分析占位);但即便只使用当前已实现的能力,它也已经足以回答循环复盘中最关键的三个问题:进展如何、是否陷入平台期、下一步该怎么办。后续读者若想深入理解数据生产侧,可继续阅读 plugins/autoresearch/skills/autoresearch/autoresearch.md(主循环 TSV 写入协议)与 plugins/autoresearch/skills/autoresearch/scripts/score-regression.sh(同类的数值分析脚本实现)。