evalsnap

evalsnap

你重新运行了 Agent，答案看起来有些不同—— 但实际效果变差了吗？evalsnap 会获取两份案例输出快照：一份基准运行结果和一份当前运行结果， 按 case_id 匹配，并准确告知有哪些变化：

• 已匹配、已新增、已移除 — 两边都存在的案例、 仅存在于当前运行结果中的案例，以及 在基准运行结果中存在但已消失的案例；每个列表均按 ID 排序
• 逐案例结果 — 对每个匹配的案例：输出是否在精确字符串相等的条件下 保持不变或发生变化、分数差值和耗时差值（如果 任一侧未记录相应度量值，则为 null），以及仅当分数下降时才会设置的 回归标记
• 回归和改进 — 发生回归的案例 ID 排序列表，以及分数上升的案例数量
• 平均分数 — 每一侧都仅对两边均有分数的匹配案例求平均值，确保比较 覆盖两边相同的案例集合；如果没有符合条件的匹配案例， 两边的平均值均为 null
• 判定结果 — 至少存在一次回归时为 fail， 否则为 pass；会报告新增和移除的案例，但它们本身 不会导致判定失败

差值和平均值均四舍五入到小数点后四位。计算纯粹在本地进行： 不联网、不需要配置，也不会读取你传入的快照以外的任何内容。无效输入 ——空快照、缺少 ID 或输出的案例、同一侧存在重复 ID、非数字分数、 负数耗时——都会被拒绝，并报告指出问题所在路径和侧的错误， 不会生成不完整的差异结果。

CLI

npx @reneturcios/evalsnap diff --input args.json
npx @reneturcios/evalsnap --version

args.json 包含完整的参数对象：

{
  "baseline": [
    { "case_id": "greeting", "output": "hello", "score": 0.9, "duration_ms": 120 },
    { "case_id": "summary", "output": "short text", "score": 0.7 }
  ],
  "current": [
    { "case_id": "greeting", "output": "hello", "score": 0.95, "duration_ms": 110 },
    { "case_id": "summary", "output": "short text", "score": 0.6 }
  ]
}

每个条目的 score 和 duration_ms 均为可选项。差异结果 以 JSON 格式输出。

退出码：成功时为 0，运行时错误时为 1（包括 无法读取或无效的输入文件，或无效输入），用法错误时为 2。

MCP 服务

npx -y @reneturcios/evalsnap mcp

MCP 客户端配置：

{
  "mcpServers": {
    "evalsnap": {
      "command": "npx",
      "args": ["-y", "@reneturcios/evalsnap", "mcp"]
    }
  }
}

工具

• diff_snapshots — 按 case_id 匹配并比较两个评估快照。

  • baseline（数组，必填，至少一个条目）— 条目格式为 {case_id, output, score?, duration_ms?} 对象
  • current（数组，必填，至少一个条目）— 条目格式 相同

  返回 {total_baseline, total_current, matched, unchanged, changed, added, removed, case_results, regressions, improved_count, baseline_avg_score, current_avg_score, verdict}。

Docker

docker run -i ghcr.io/cloudcorprecords/evalsnap
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/evalsnap diff --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios