Autoresearch Evals:Claude Autoresearch 迭代结果分析协议全解析

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

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 行):

  1. 给了路径 → 直接使用该 TSV;
  2. 没给路径 → 扫描当前目录 + autoresearch/*/ 下所有 *-results.tsv 文件;
  3. 找到多个 → 询问用户"Which results to analyze?",并列出找到的文件;
  4. 一个都没找到 → 询问用户提供结果 TSV 路径;
  5. 附加扫描:同时扫描项目根目录下的 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. 读第 1 行:提取 # metric_direction: higher_is_better|lower_is_better 注释,确定指标方向(越大越好还是越小越好);
    • 若缺失 → 从列名推断(metric / error_count 猜测),拿不准就询问用户;
  2. 读第 2 行:表头行 → 检测可用列;
  3. 读剩余行:数据行;
  4. 优雅处理缺失 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 三条关键规则

  1. 早停建议:若连续 3+ 个检查点都检测到平台期 → 建议提前停止;
  2. 最终汇总:循环结束时,在控制台输出完整 evals 报告,并写入 evals-summary.md;
  3. 触发方式:主循环规格(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 转译成可读、可传递、可编程消费的复盘结论。核心要点可以浓缩为四条:

  1. 列驱动:分析深度由 TSV 的列结构决定,缺列优雅降级,未知列前向兼容;
  2. 方向先行:# metric_direction 注释缺失时宁可询问也不猜测,保证 delta 语义正确;
  3. 双模式:既可作为独立的一次性复盘命令(/autoresearch:evals),也可通过 --evals / --evals-interval 内嵌为循环的周期性检查点,配合"3+ 检查点平台期即建议早停"的规则控制空转;
  4. 可编程出口:--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(同类的数值分析脚本实现)。

登录后查看全文
autoresearch