- 跑评估。
- 从运行结束时的 receipt 里拿到这次的 Run ID。
- 用 Run ID 查看结果，找到失败的那几次运行。
- 判断该改应用、Adapter 还是评估用例。
- 改完再跑同一范围，确认修好了。
先让 Agent 读安装版本的文档
Agent 凭训练记忆写出来的命令和 API，可能和你装的 NiceEval 版本对不上。先让它读跟着 npm 包发布的文档。 NiceEval 把中文文档放在 npm 包的docs-site/zh/ 目录，并在包根提供给 Coding Agent 用的 INDEX.md。Agent 先读 node_modules/niceeval/INDEX.md，再从索引进入当前任务需要的页面。
pnpm exec niceeval init 会初始化配置，并把一段托管指引写进项目的 AGENTS.md。项目只有 CLAUDE.md 时写进 CLAUDE.md；两份都没有时新建 AGENTS.md。升级 NiceEval 后再运行一次 init，就能刷新这段指引。
这段指引把两件事分开：
- 写代码时，Agent 当然可以读
evals/、agents/等项目源码。 - 要证明某次运行发生了什么时，在终端用
niceeval show，要稳定的 JSON 用niceeval query，浏览器审阅用niceeval view。不要扫描.niceeval/下的原始文件，也不要拿当前源码反推历史运行。
运行并保存 receipt
让 Agent 用--json 运行，并把输出存下来：
--json 的每一行都描述这次运行的进度和诊断。最后恰好一行是 receipt：
createdRunIds 列出这次新建的全部 Run，后面查看结果就用它。publicationCutoff 不要解析，原样传给后续命令。
completion 是 completed 只说明这次运行结束了，不说明任务完成了，评估也可能没通过。receipt 也不是长期保存的结果格式，结果要通过 createdRunIds 去读。
用 Run ID 查看结果
运行结束后，Agent 先在终端打开 receipt 里的 Run：show @<attempt-locator> 显示这个 Attempt 的判定、断言摘要、各部分是否完整和已知限制。--source 显示这次运行用的评估源码和每条断言的结果。--execution 显示精简后的执行过程，要展开其中一项，复制它旁边的 ID 运行 --execution --expand <stable-id>。
需要让脚本、CI 或 Agent 稳定处理结果时，先找到可用的查询，再发送完整 request：
query 返回固定格式的 JSON。人要在浏览器里看时，用 pnpm exec niceeval view --run <run-id>；view 不接受 locator。
按看到的状态决定下一步
处理
failed 时，不要为了通过一个过窄的 Match 去改本来符合任务的产物。产物满足任务、断言却拒绝了任务允许的结果，说明评估用例误判了，应该改评估用例。完整的归因流程见排查手册。
修改后再跑一次
让 Agent 每次只验证一个假设：改程序或评估用例，运行同一个范围，再读新的 receipt 和 Run。 默认情况下，没受改动影响、上次已经有结论的 Attempt 会被沿用。运行前加--dry 可以看到哪些会沿用、哪些会重跑，以及原因。需要所有 Attempt 都真实执行时，加 --rerun all：
- 任务要求修好、且已有授权时，先修运行出错的问题，再只复验受影响的范围。
- 只要求分析时，只做归因，不改代码也不重跑。
- 业务失败符合任务预期时，保留这个结果并如实报告，不要为了变绿去改应用或评估用例。
结果保存后不能修改
已经保存的结果不会被修改。Agent 想得到不同的结果，就改程序或评估用例，重新运行，再用新 receipt 的createdRunIds 查看。
需要把结果交给别人时，复制项目里的 .niceeval/record.sqlite，不要把终端输出或 NDJSON 当作分享格式。