EvalArc Skill 技能

技能简介

EvalArc 是一款开源的命令行「Agent 评估回归审查器」，专注解决「分数上升、实际却在偷偷退步」的盲点。它逐项对比两次评估运行的 check、显式应用接受门槛（acceptance gate）、生成可被他人离线复算的审计报告，覆盖 inspect-ai、promptfoo、JUnit、GitHub Actions 等主流评估框架。当 Agent 平均分从 90% 升到 93.75%、三项改善但一项通过多年的 check 突然失败时，EvalArc 会高亮那一项并附上录制证据（包含工具调用轨迹），让评审人能独立复核。MIT 协议、Python 3.11+、零第三方 Python 运行时依赖、Linux 原生支持。

核心能力

• 逐项 check 对比：逐条对比两次评估运行的 check 通过率，分辨「平均分提升」背后的具体回归/改进项，而非只看平均分。
• 显式接受门槛（acceptance gate）：可在配置中明确「哪一项 check 必须通过才允许合并」，门槛不通过则 CI 红色。
• 录制证据导出：保存的工具调用轨迹可被审阅者离线回放——同一份原始记录可被任意第三方重算结果，避免「只有我能复现」的信任黑盒。
• 多框架兼容：内置 inspect-ai、promptfoo、JUnit 适配器，同时支持 GitHub Actions 集成；标准 pytest 检查可直接对比。
• 失败原因重放：每个失败 check 都附上录制时的工具调用序列、模型输出、断言文本，方便定位是 prompt 问题、工具问题还是评分问题。
• 公开范例 + Hugging Face Space：自带 8 个公共支持规划 case × 3 次生成的对比范例（Qwen3-8B vs Qwen3-8B-27B-FP8），可在线体验升级轨迹与回归发现过程。

安装配置

• 环境要求：Python 3.11+；Linux 原生体验最佳（macOS/WSL 也可）；可访问 GitHub 与 Hugging Face Space。
• PyPI 安装：pip install evalarc 或 pipx install evalarc，零运行时第三方依赖。
• 首次体验：执行 evalarc demo 自动下载公开记录（Qwen3-8B vs Qwen3.8-27B-FP8 升级对比），无需模型 Key 即可在终端/浏览器重看 24 项原始评估结果。
• GitHub Actions 集成：在 .github/workflows/agent-eval.yml 中加入 evalarc compare --baseline main --candidate pr --gate policy.yaml，PR 评估不通过门槛时直接红灯。
• 生成对比报告：evalarc compare --baseline runs/baseline --candidate runs/candidate --out reports/upgrade.html，生成可在浏览器内交互式查看的对比页。

使用步骤

• 步骤 1：用评估框架（inspect-ai / promptfoo / 自研）跑出 baseline 与 candidate 两份原始运行记录，EvalArc 直接解析 JSONL / JUnit 格式。
• 步骤 2：编写 policy.yaml，列出每条 check 的「必须通过 / 允许退化幅度 / 必填字段」，作为接受门槛。
• 步骤 3：执行 evalarc compare --baseline runs/baseline --candidate runs/candidate --gate policy.yaml，工具会逐 check 对比、应用门槛、输出报告。
• 步骤 4：阅读生成的 HTML 报告，每条 check 都有「分数对比」「失败原因回放」「工具调用轨迹」三栏，审阅人能离线复核。
• 步骤 5：把报告附在 PR/评审单里，团队可在合并前量化讨论「这一次升级是否真的更好」。
• 步骤 6：把 evalarc compare 加到 CI，每次 Agent 配置/Prompt/模型升级自动跑一次回归门槛。

适用场景

• Agent 框架升级评审：升级 LangChain / LlamaIndex / inspect-ai 主版本前先跑 EvalArc，避免「升级后总体分上升但某核心 check 失败」上线才发现。
• 模型升级评估：在「是否值得为新模型多付 2x 推理费」这种决策中，提供逐 check 的客观对比而非平均分。
• Prompt 调优量化：A/B 测试两版 prompt 时，用 EvalArc 防止「总体分上升但某边界 case 失败」被掩盖。
• CI 防回归：在 Agent CI pipeline 中加入 EvalArc 门槛，自动拒绝导致核心 check 退化的改动。
• 学术研究复算：把评估原始数据 + EvalArc 报告打包提交，让审稿人能独立复核分数，不依赖作者提供的截图。
• 跨模型对比：在同一组 case × 多个模型之间做交叉对比，量化「这个模型擅长哪类任务」。

适用人群

• AI Agent 工程师 / 应用开发者，每次升级框架/模型前需要客观对比
• ML 工程师，做模型选型与能力评测
• 研发团队 Tech Lead，把 Agent 评估门槛纳入 CI
• AI 安全 / 评测研究员，做权威规则 / Cohen's κ 类研究的复算
• 学术作者，提交可被审稿人独立复核的实验结果

工作原理

EvalArc 的核心是「逐 check 对比 + 显式门槛 + 可重算报告」：每次 Agent 评估运行的原始记录（prompt、模型输出、工具调用、断言、分数）都被完整保存，EvalArc 解析后逐条 check 与 candidate 对比，应用用户在 policy.yaml 中定义的接受门槛（可指定某项必须通过、某项允许的退化比例），最终生成 HTML/JSON 报告并在 CI 中按门槛返回退出码。每个失败 check 都附上录制时的完整证据链（原始 prompt、工具调用序列、断言文本），审阅者可在离线环境用同一份原始记录重算。这种「透明可重算」的设计避免了「只有作者能复现」的传统评测黑盒，特别适合需要跨团队、跨模型复算结果的场景。

官方链接

• PyPI 包：https://pypi.org/project/evalarc/
• GitHub 仓库：https://github.com/noteflowai/evalarc
• 首页范例：https://noteflowai.github.io/evalarc/
• Hugging Face Space：https://huggingface.co/spaces/glayguo/evalarc
• 协议：MIT License
• 当前版本：0.17.6