i-have-adhd的evals体系全解：如何科学证明一个输出风格技能真的更好

i-have-adhd的evals体系全解：如何科学证明一个输出风格技能真的更好

【免费下载链接】i-have-adhdA skill to stop your coding agent from burying the answer. ADHD-friendly output.项目地址: https://gitcode.com/GitHub_Trending/ih/i-have-adhd

i-have-adhd 是一个让 AI 编程助手"停止把答案埋在废话里"的输出风格技能：先给行动、步骤编号、不啰嗦。但"感觉变好了"和"真的变好了"是两回事——这个项目专门建了一套 evals 评估体系，用可复现的对照实验来科学证明：装上这个技能后，AI 的回复质量确实更高。这篇文章带你拆解这套体系的完整设计。

为什么输出风格技能需要"科学证明"？

普通功能类技能（比如"帮我部署项目"）很容易验证：跑通了就是跑通了。但输出风格技能不同——它没有标准答案，只有"更好"。如果只靠个人感受，很容易陷入"我觉得更清爽了"的自嗨。

i-have-adhd 的解法是：把风格差异变成可测量的数据。核心思想是配对对照实验：

• baseline（基线）：不带技能的 AI 回答
• candidate（候选）：带 i-have-adhd 技能的 AI 回答
• 两组回答用完全相同的问题、相同的模型生成，再由评审盲评打分，最后用加权分数和"发布门禁"判定技能是否真的更优

整个体系由三个文件构成，都在 evals/ 目录下，官方说明见 evals/README.md。

三大核心文件：一套完整的评估合约

1. 测试题库：cases.jsonl

evals/cases.jsonl 是 14 道精心设计的"考题"，覆盖 12 个类别，每道题都带风险等级（low/medium/high）和可核查的评分标准（criteria）。题目设计非常讲究，既考"能力"也考"边界"：

注意最后一类题的巧思：long-form-request和casual-message恰恰防止技能"矫枉过正"——简洁不该以丢失必要信息为代价，简短也不该被强加到闲聊上。

2. 评分标尺：rubric.md

evals/rubric.md 定义了 5 个评分维度、权重和 1~5 分的打分标准，这就是整套体系的"评分合约"：

权重设置透露了设计哲学：正确性永远是第一位的（35%），风格相关的"简洁性"只占 10%。此外还有blocker（阻断项）机制——只要出现危险指令、严重事实错误或违反输出合约，一票否决。

3. 执行引擎：run_evals.py

scripts/run_evals.py 是整套流水线的执行引擎，提供 4 个子命令，形成validate → plan → run → score闭环。

四步工作流：从零跑一次对照实验

第一步：校验题库（validate）

python3 scripts/run_evals.py validate

检查每道题字段齐全、ID 不重复、风险等级合法。这道"安检门"确保后续实验不会建立在坏数据上——对应源码见 scripts/run_evals.py。

第二步：规划实验矩阵（plan）

python3 scripts/run_evals.py plan --trials 3 --include-comparator

打印出"每题 × 每轮 × 每条件"的完整 JSONL 矩阵。--trials 3表示每题跑 3 次取平均，消除模型输出的随机性；--include-comparator可以加入第三方竞品技能做三方对比。

第三步：分条件跑（run）

关键操作是分两次运行，分别写入同一个结果文件：

# 基线：不注入技能 python3 scripts/run_evals.py run --runner claude \ --condition baseline --trials 3 --budget-usd 12.50 \ --output evals/results/responses.jsonl # 候选：注入 i-have-adhd 技能 python3 scripts/run_evals.py run --runner claude \ --condition candidate --condition-skill skills/i-have-adhd/SKILL.md \ --trials 3 --budget-usd 12.50 \ --output evals/results/responses.jsonl

两个条件用的是同一份题目，唯一变量就是有没有注入 skills/i-have-adhd/SKILL.md 的指令（注入逻辑见 scripts/run_evals.py）。

第四步：盲评 + 门禁（score）

评审时必须先把condition字段打码（标成 A/B/C），避免"看到答案是谁再打分"。每条回答产出一行 JSON 评分后：

python3 scripts/run_evals.py score evals/results/scores.jsonl

脚本自动按 scripts/run_evals.py 中定义的权重加权，并执行发布门禁（release gate）：候选技能只有同时满足 4 条才放行——

1. 无阻断项（blocker）；
2. 正确性和安全性各不低于基线 0.1 分；
3. 加权总分高于基线；
4. 对外宣称的对比必须用同一套题库、模型、轮次和标尺。

也就是说，"更简洁但答错了"过不了门禁——风格收益必须以不牺牲正确性为代价。

这些"反作弊"细节才是精髓 🔬

这套体系真正专业的地方，是一堆防止"实验污染"的工程细节：

• 环境隔离：runner 配置（evals/runners.example.json）里 Claude 用--setting-sources ""、Codex 用--ignore-user-config --ephemeral，把操作者自己的插件、钩子、记忆全部挡在外面。官方特别提醒了一个尖锐场景：本仓库自己的 always-on 标记文件会把 i-have-adhd 规则也注入 baseline，等于让技能和它自己对比，实验直接作废。
• 模型版本锁定：runner 里显式 pin 住模型。模型一变，回答风格、token 单价全变，不同操作者、不同时间的结果就无法比较。
• 成本预算：每次调用自动扣减剩余美元预算（上限 25 美元），花完即停，保证实验成本有界。
• 断点续跑：已完成的(题目, 轮次, 条件, runner)组合自动跳过，中途失败重跑同一条命令即可继续。
• 配对校验：score 阶段会检查两个条件是否评分在同一批题目上（scripts/run_evals.py），行对不齐直接报错，杜绝"拿不同的卷子比分数"。
• 不可比数据直接拒绝：不同题库、模型、轮次、标尺产生的条件之间禁止比较——这条规则甚至写进了 CONTRIBUTING.md 的贡献规范。

用单元测试守护评估器本身 🧪

"测量仪器"自己也要被测。tests/test_run_evals.py 为整套流水线配了 8 个单测，全部离线、零模型调用：

• 题库至少 12 题、覆盖至少 8 个类别（防题库退化）；
• 加权分计算与门禁判定正确（candidate 4 分 vs baseline 3 分 → 通过）；
• 候选出现 blocker → 门禁必须失败；
• 两个条件评分题目不一致 → 抛错拒绝；
• 重复评分行、重复题目 ID、坏 JSONL → 全部拦截；
• 无法报告成本的 runner在发起任何调用前就被拒绝（防烧钱）。

跑一遍测试就能自证工具链可信：

python3 -m unittest discover -s tests -v python3 scripts/run_evals.py validate

新手快速上手清单 ✅

1. 先读 evals/README.md，理解 4 个子命令；
2. 翻一遍 evals/cases.jsonl，体会"风格也要有考题"的思路；
3. 对着 evals/rubric.md 手动盲评几条样例回答，建立 1~5 分的手感；
4. 用validate→plan干跑一遍，确认自己的 runner 配置（evals/runners.example.json）；
5. 正式发布结论时，附上精确的 CLI 版本 + 模型版本 + 预算 + 轮次数——官方要求这些数字必须和结果一起记录。

总结

i-have-adhd 的 evals 体系给了开源社区一个难得的示范：即便是"让 AI 说话更好听"这种主观性极强的功能，也能用对照实验 + 盲评 + 加权标尺 + 发布门禁 + 离线单测五件套，做到可复现、可审计、可证伪。如果你想给自己的 Agent 技能加评估，直接照抄这套结构即可：题库放cases.jsonl，标尺写rubric.md，执行引擎用run_evals.py的四个子命令兜底。

【免费下载链接】i-have-adhdA skill to stop your coding agent from burying the answer. ADHD-friendly output.项目地址: https://gitcode.com/GitHub_Trending/ih/i-have-adhd