eval-harness

eval-harness 快速入门

别再凭感觉说”新 Skill 更好用”,让数据帮你做决定。

这是什么?解决什么问题?

随着 Agent Skills 越来越多,大家普遍面临一个难题:装了这个 Skill 后,AI 的输出到底变好了还是变差了?不同的 Skill 组合,哪个效果最好?SKILL.md 写法的不同对结果有多大影响? eval-harness 是一个社区维护的评估框架 Skill。它能帮你:

• 把一组测试任务(比如 50 道编程题)交给 AI 跑两遍——一遍装 Skill,一遍不装。
• 对比两轮输出的差异,计算成功率、代码质量、token 消耗等指标。
• 输出带统计显著性的报告,告诉你”提升是真实的,还是运气”。 这个 Skill 来自 affaan-m/everything-claude-code 仓库,是 Anthropic 黑客马拉松获奖项目。它特别适合 Skills 开发者做 A/B 测试,以及团队选型时做客观评估。

准备工作

• Node.js 18+ 或 Python 3.10+
• 一个支持 Agent Skill 的客户端(Claude Code、OpenCode 等)
• 一组测试任务(JSONL 格式,每行一个 prompt)
• 至少 30 分钟时间(评估需要多次跑 AI,会比较慢)
• API 访问令牌(评估会消耗 token)

3 步快速上手

第 1 步:克隆仓库

git clone https://github.com/affaan-m/everything-claude-code.git
cd everything-claude-code
ls skills/eval-harness/

你应该能看到 SKILL.md、harness.py(或 .js)、example_tasks/ 等文件。

第 2 步:准备测试任务集

在 tasks/ 目录创建一个 JSONL 文件,每行一个 JSON 对象:

{"id": "q1", "prompt": "写一个 Python 函数判断回文", "expected": "def is_palindrome(s): ..."}
{"id": "q2", "prompt": "修复这个 bug: ...", "expected": "fixed code..."}
{"id": "q3", "prompt": "解释 async/await", "rubric": "是否提到 event loop..."}

每条任务可以带 expected(期望输出)或 rubric(评分准则)。

第 3 步:跑评估

python harness.py \
--tasks tasks/q1-q3.jsonl \
--skill eval-harness \
--baseline no-skill \
--output report.html

跑完后打开 report.html,你会看到:

• 每个任务的两轮输出对比
• 成功率(通过的题目数 / 总题目数)
• 平均 token 消耗
• 统计显著性(p-value)
• 改进/退步的具体例子

常见踩坑

1. 测试集太小(< 10 题):统计结果不可信,跑出来的差异可能是运气。建议至少 30 题。
2. 测试任务太相似:如果 50 题都是”写排序”,优化点会过拟合,无法反映真实场景。要包含不同类型任务。
3. baseline 设置不当:baseline 应该是”完全不装任何 Skill”或”装的是上一版本”,而不是”装了不同 Skill”。
4. 评估指标单一:只看”通过率”是不够的,还应该看代码质量、可读性、token 效率。harness 支持多维度评分,但你需要主动配置。
5. 忽略 LLM 评分的主观性:用 LLM 当 judge 时,它自己也有偏好(倾向于自己风格的答案)。建议设置 rubric 而不是简单 yes/no。
6. 温度参数不固定:不同 temperature 会导致结果不稳定。评估时必须固定 temperature=0,否则数据不可复现。

初级用法

• 回归测试:每次 Skill 更新前,跑一遍测试集,确认新版本没退步。
• Skill A/B 测试:比较两个候选 Skill 哪个更适合你们团队的工作流。
• 模型对比:同一个 Skill,对比 GPT-4o、Claude Sonnet、Gemini 哪个跑分高。

高级玩法

• 配对样本 t 检验:harness 内置统计检验,告诉你提升是不是显著(p<0.05 才有意义)。
• 多轮对话评估:不仅评估单次回答,还评估多轮交互(任务分解、错误恢复、用户反馈响应)。
• 集成到 CI:GitHub Action 里每次 Skill 变更自动跑评估,把报告作为 PR 评论。

小技巧

• 先用 5 道题小规模验证流程跑通,再扩到 50 道完整测试。
• 评估结果不要只看平均值,要看方差——稳定的 Skill 比偶尔超神的 Skill 更值得依赖。
• 跑评估时用固定的 API key 和 region,避免后端策略变化导致数据不可比。
• 把报告归档到 eval-history/,长期看 Skill 演进的趋势。
• LLM judge 的 prompt 也要评估,形成”元评估”闭环。

常见问题 FAQ

Q1: 这个 Skill 跟 eval-harness 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他? A: eval-harness 来自 community,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了? A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 eval-harness 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

参考链接

• Skill 仓库
• Anthropic 评估指南
• OpenAI Evals 框架
• 提示工程评估最佳实践
• LangSmith 评估工具