devtu-benchmark-harness

基准测试套件 — 持续改进系统

用于提升 ToolUniverse 工具、技能和插件质量的 5 步反馈循环。

注意：此技能与数据集无关。每个基准测试的分数历史、已知失败问题 ID 和数据集特定调查内容，应放在 temp_docs_and_tests/benchmark_tracking/（被 git 忽略的工作文件夹）中，而不是此技能目录中。

反馈循环

1. RUN benchmark → 2. ANALYZE results → 3. DIAGNOSE failures → 4. FIX via devtu skill → 5. RETEST → repeat

编排式运行器（推荐）

一条命令即可执行步骤 0（记忆审计）、1（构建）、2（运行）、3（分析）、4（诊断 + 提取失败项）：

bash skills/devtu-benchmark-harness/scripts/run_harness_loop.sh --benchmark bixbench --n 20 --seed 42
# After reviewing diagnose.log and applying devtu skill fixes:
bash skills/devtu-benchmark-harness/scripts/run_harness_loop.sh --retest /path/to/failures.json

该脚本会创建 temp_docs_and_tests/benchmark_tracking/run_<TS>/，其中包含 results.json、analysis.log、diagnose.log 和 failures.json。诊断输出会列出每项失败及应调用的确切 devtu 技能——请勿手动修复。

防记忆化检查

接受任何技能编辑（来自 devtu-optimize-skills 或手动编辑）之前，请运行：

python3 skills/devtu-benchmark-harness/scripts/check_memorization.py --all

如果任何技能中包含基准测试名称、capsule UUID、bix-N 问题 ID 或已知的 GT 特定数值答案，此检查就会失败。这可以防止插件针对单个基准测试的答案键过拟合。使用 --strict 模式运行，还会标记特定基因名称和数据集文件名（较弱的信号）。

步骤 1：RUN — 运行基准测试

bash scripts/build-plugin.sh   # rebuild plugin with latest skills

python skills/devtu-benchmark-harness/scripts/run_eval.py \
  --benchmark bixbench \        # bixbench | lab-bench | custom
  --mode plugin-only \          # plugin-only | baseline-only | comparison
  --n 205 \                     # number of questions
  --timeout 1800 \              # seconds per question
  --max-turns 30                # agent turns per question

选项：--category DESeq2（筛选）、--resume results.json（跳过已完成项）、--guidance path.md（注入自定义指引）。

可靠性模式：APPEND_CONVENTIONS 环境变量

交互模式下的技能自动匹配不稳定——有时 Claude 会读取技能说明，却在加载技能正文前就开始编写代码。若要强制将路由器的关键约定加入每个请求的系统提示词（可靠性更高，可按设计评估插件约定，而非按实现评估技能路由）：

APPEND_CONVENTIONS=1 python skills/evals/run_benchmark.py --benchmark bixbench --plugin-only

测量约定的正确性（规则是否合适？）时使用此模式。测量技能路由的可靠性（Claude 是否确实调用了技能？）时使用默认模式。这两个数值之间的差距，就是路由可靠性问题。

基准测试设置（仅首次运行）

Rscript skills/evals/install_r_packages.R                  # R packages
python3 skills/evals/bixbench/download_capsules.py         # BixBench data (~5 GB)

可用基准测试

基准测试	问题数	测试内容	数据
lab-bench	20 道选择题	数据库查询准确性	skills/evals/lab-bench/questions.json
bixbench	205 道计算题	数据分析 + 统计	skills/evals/bixbench/questions.json + capsule 数据
custom	用户定义	任意内容	自定义 JSON 文件

步骤 2：ANALYZE — 将失败项映射到技能

python skills/devtu-benchmark-harness/scripts/analyze_results.py \
  --results results.json \
  --questions skills/evals/bixbench/questions.json \
  --benchmark bixbench

输出：

• 按技能划分：准确率最低的技能（优先修复这些技能）
• 按类别划分：DESeq2、ANOVA、系统发育、variant_analysis 等
• 失败类型：超时、答案错误、工具错误、缺少 API 密钥

类别 → 技能映射

类别	技能
DESeq2, fold_change	tooluniverse-rnaseq-deseq2
ANOVA, regression, chi_square, spline_fitting	tooluniverse-statistical-modeling
pathway_enrichment, DESeq2+enrichGO	tooluniverse-gene-enrichment
phylogenetics	tooluniverse-phylogenetics
variant_analysis, epigenomics	tooluniverse-variant-analysis
crispr_screen, functional_genomics	tooluniverse-crispr-screen-analysis
single_cell	tooluniverse-single-cell

步骤 3：DIAGNOSE — 获取改进建议

python skills/devtu-benchmark-harness/scripts/analyze_results.py \
  --results results.json \
  --questions skills/evals/bixbench/questions.json \
  --diagnose

每条建议都包含失败类别、相关技能、失败类型，以及应调用哪个 devtu 技能来修复。

根因调查

对于每项失败，请确认这是 Agent 错误还是 GT（ground truth，标准答案）问题：

1. 找到 capsule 数据：temp_docs_and_tests/bixbench/bixbench/data/CapsuleFolder-{uuid}/
2. 查找权威脚本：*.py、*.R、analysis.R、run_*.py
3. 自行运行脚本——能否复现 GT 值？
4. 如果你的计算结果与 Agent 一致（而非 GT），则这是 GT 问题，不是 Agent 错误

第 4 步：修复——路由到合适的 devtu 技能

不要手动修复——使用 devtu 技能，确保修复遵循既定模式并包含测试。

诊断	操作	调用
工具返回了错误数据	修复工具代码和 JSON 配置	Skill('devtu-fix-tool')
没有工具可执行此计算	创建新的 ToolUniverse 工具	Skill('devtu-create-tool')
技能提供了错误指导	更新 SKILL.md 约定	Skill('devtu-optimize-skills')
Agent 需要打包脚本	将脚本添加到技能的 scripts/ 目录	Skill('devtu-optimize-skills') Pattern 15
Grader 误判为错误	修复 grade_answers.py	直接修复代码
多项协调变更	完整周期	Skill('devtu-self-evolve')

修复工作流

1. analyze_results.py --diagnose → get recommendations
2. For each recommendation → invoke the appropriate devtu skill
3. bash scripts/build-plugin.sh → rebuild dist
4. run_eval.py --retest failures.json → verify fix

示例

Diagnosis: "ANOVA wrong_answer → tooluniverse-statistical-modeling"
  → Invoke: Skill('devtu-optimize-skills')
  → Tell it: "statistical-modeling skill produces wrong F-statistics for
     per-gene expression ANOVA. Agent aggregates at sample level instead
     of gene level."
  → The skill handles: read SKILL.md, add convention, verify no
     memorization, rebuild, suggest retest.

第 5 步：重新测试——验证修复

# Extract failed question IDs
python skills/devtu-benchmark-harness/scripts/analyze_results.py \
  --results results.json --extract-failures /tmp/failures.json

# Retest only failures
python skills/devtu-benchmark-harness/scripts/run_eval.py \
  --benchmark bixbench --mode plugin-only --retest /tmp/failures.json

比较：有多少项从错误变为正确？如果有所改善，请更新基线。

Grader

grade_answers.py 按顺序应用 7 种策略：

1. 精确匹配——预测中包含 GT 子字符串
2. 选择题匹配——检测字母答案（A/B/C/D）
3. 范围匹配——数值在 (low, high) 范围内，并允许舍入误差
4. 规范化匹配——去除标点，进行双向子字符串匹配，并提取粗体片段
5. 数值接近度——误差在 5% 以内
6. 同义词匹配——科学术语等价匹配
7. LLM 验证器——Claude 判断语义是否正确（用于 eval_mode=llm_verifier）

Unicode 规范化：减号（U+2212）、上标指数（10⁻²⁶ → e-26）。

# Re-grade with LLM
python skills/devtu-benchmark-harness/scripts/grade_answers.py \
  --results results.json --output graded.json --llm

插件架构

ToolUniverse 插件仅使用路由器匹配技能：

1 auto-matchable skill: "tooluniverse" (router, ~300 chars)
  └── Routing table → 113 sub-skills (all disable-model-invocation: true)

原因：Claude Code 对技能描述有字符预算（约为上下文的 1%）。114 个技能 × 500 个字符 = 57K，超出预算 → 描述会被丢弃。使用 1 个路由器后，Agent 总能看到它并正确路由。

在 -p 模式下，技能不会自动匹配。基准测试运行器通过 full_skill_injection 模式模拟交互行为：以编程方式检测匹配的技能，并注入其完整的 SKILL.md 内容。

与 devtu-self-evolve 集成

将其作为阶段 3.5插入 Testing 与 Fix 之间：

Phase 3 (Test) → Phase 3.5 (Benchmark) → Phase 4 (Fix via devtu) → Phase 5 (Retest)

已知失败模式

--diagnose 标志会引用以下模式：

模式	根本原因	修复操作
DESeq2 wrong_answer	pydeseq2 与 R 的结果不一致，集合运算错误	对 rnaseq-deseq2 使用 devtu-optimize-skills
ANOVA wrong_answer	混淆 F 统计量与 p 值，聚合错误	对 statistical-modeling 使用 devtu-optimize-skills
spline wrong_answer	R ns() ≠ Python patsy；端点是否包含存在差异	对 statistical-modeling 使用 devtu-optimize-skills
phylogenetics wrong_answer	PhyKIT 输出列选择、文件配对	对 phykit_batch_analysis 使用 devtu-fix-tool
variant wrong_answer	Excel 多行表头，编码变异的分母	对 variant-analysis 使用 devtu-optimize-skills
enrichGO wrong_answer	R clusterProfiler 对版本敏感	对 run_deseq2_analysis 使用 devtu-fix-tool
timeout	流水线运行超过 30 分钟（Trimmomatic、GATK）	使用 devtu-create-tool 封装流水线
GT issue	使用当前工具无法复现真实答案	在结果中记录，并从评分中排除

技能约定规则

根据基准测试结果向技能添加约定时：

• 仅限通用知识——不得包含特定数据集的数值或记忆答案
• 原则优先于示例——使用“按基因而非按样本执行 ANOVA”，而不是“此数据集上的 F=0.77”
• 工具偏好——使用“使用 R DESeq2 计算离散度”，而不是“R 得到 4，pydeseq2 得到 2”
• 确认没有污染——在约定文本中搜索数据集名称和具体数值答案