跳转到主要内容
Coding Agent 可以根据需求编写 NiceEval 配置与评估用例，也可以根据运行结果持续改进被测程序。整个过程只需要仓库文件和 Bash，不依赖浏览器或额外的 Skill。

​
读取安装版本的文档

NiceEval 把中文文档发布在 npm 包的 docs-site/zh/ 目录，并在包根提供供 Coding Agent 使用的 INDEX.md。Coding Agent 应先读取 node_modules/niceeval/INDEX.md，再从索引进入当前任务需要的页面，不依赖训练数据或其它版本的在线示例。这样可以保证 API、CLI 与安装版本一致。 npx niceeval init 会初始化配置，并把一段托管指引写进项目的 AGENTS.md。如果项目只有 CLAUDE.md，则写入 CLAUDE.md；两份文件都不存在时，新建 AGENTS.md。升级 NiceEval 后再运行一次 init，即可刷新托管区块。 给 AI 的起始任务可以直接写成：
AI 通常按任务选择这些入口：

​
用 bash 完成一次反馈闭环

闭环的目标不是”把命令跑绿”，而是形成并验证一个假设：失败来自被测程序、评估用例，还是运行环境。推荐按下面的顺序迭代。
1

运行实验

先读取退出码：0 表示所有评估用例通过；1 表示至少一个评估用例失败或出错；2 表示 NiceEval 自身未能完成运行。退出码决定是否继续，控制台文本用于定位原因。
2

读取失败

第一条命令显示当前各实验的通过率、成本、耗时，以及每个评估用例的紧凑 Attempt locator——locator 本身就是证据入口，不在列表里编码证据可用性。第二条命令直接打开选中的 Attempt，页面末尾的 available: 只列出这个 Attempt 实际可用的证据命令。
3

按问题读取证据

--execution 合并 AI 输出与 trace：标准事件流提供消息、thinking、tool call/result 和 Skill load；OTel 在能够关联时给同一节点补开始时间、耗时、父子关系和错误状态。没有 OTel 时步骤仍完整，只不显示时间。不带证据 flag 时，show @<id> 是失败诊断首页。它先列出失败断言的 group、matcher、expected、received、原因和源码位置，再给执行、生命周期阶段耗时与文件变化摘要。Coding Agent 应先读取这一页；需要追查值的来源时，再打开对应证据。
--execution 把 AI 消息、Skill load、工具调用和工具结果排成一棵执行树。它只展示 Agent 可理解的事件；没有关联到这些事件的 SDK / runtime span 不逐行输出，只报告省略数量并保留 trace.json 路径。下面的 Attempt 有 OTel，所以能关联的节点同时带相对时间与耗时：
没有 OTel 时仍用标准事件流展示相同的步骤，只去掉时间列和瀑布关系，不把“缺时间”误写成“没有执行”：
diff 是被测 Agent 在 Sandbox 工作区造成的文件变化，不是评估用例源码的新旧差异。只有 Sandbox 评估用例才会收集到 diff——非 Sandbox 评估用例或 agent 确实没碰任何文件时，attempt 页的 available: 列表会省略 --diff。默认先给文件级摘要，避免把大段补丁塞进 Agent 上下文；--diff=<文件> 再展开单个文件，原始 artifact 路径始终保留：
用这组输出检查信息是否足够：
4

提出假设并修改

根据证据只修改最可能出错的一侧：不要为了变绿而放宽一个本来正确的断言。先写清楚“哪条证据支持什么判断”，再修改代码。
5

局部重跑并验证假设

位置参数按评估用例 ID 前缀缩小实验范围。调试同一个失败时加 --force，确保刚才的修改真的触发一次新运行。然后用 show 验证判定、断言和证据是否按预期变化。
6

全量确认没有回归

局部结果变绿只证明当前假设成立。收工前必须强制全量重跑；只有命令退出码为 0，且 show 没有新的失败或错误，才算完成。

​
从输出读取诊断信号

--output agent 运行中只向 stderr 追加低频 checkpoint（存活信号，不是结果数据源），结束时向 stdout 打印一个有界 handoff block——这才是 AI 应该解析的部分：
Coding Agent 应先从 failures 选中 Attempt locator，再按证据位执行 next 给出的 niceeval show @<id> 或对应证据 flag。不要解析运行期间 stderr 上低频追加的 checkpoint 行；这些行只用于判断进程是否存活。失败条数超过上限（默认 5 条）时，handoff 只展开前几条并给出总数，完整清单从结果快照读取。机器读取以结果快照为事实来源：
  • snapshot.json 记录实验身份、运行配置、格式版本和时间。
  • result.json 记录该 Attempt 的判定、断言、结构化错误、diagnostics 和用量；瞬时 progress 不落盘。
  • events.json 是对话与工具调用事件，trace.json 是调用链，diff.json 是 Sandbox 文件变化。
  • 某类证据不存在时，对应文件不会生成。先以 show 的提示为准，不要假设每个目录都有全部文件。
show 的默认结果可能合成自多次运行：每个 Experiment × 评估用例选择最新判定，因此局部重跑后仍能看到其它评估用例的旧结果。该视图用于查看每条评估用例的最新已知判定；同一版代码的整体结果必须通过一次 --force 全量运行确认。

​
结果复用条件

不传 --force 时，NiceEval 会比较当前指纹与最近结果。指纹由评估用例源码和运行配置组成，包括实验 ID、Agent、model、flags、Sandbox、timeout 与 strict 等设置。 被测程序的源码不在指纹里。修改实现后，即使行为已经变化，旧的 passed 或 failed 仍可能被复用。因此可以这样选择：
  • 只想重看已有结果：运行 niceeval show，不产生新费用。
  • 修改了评估用例或实验配置：直接重跑；指纹变化会触发对应任务。
  • 修改了被测程序：对受影响的评估用例使用 --force。
  • 准备结束本轮工作：对整个实验使用 --force，排除其它评估用例的回归。

​
设置自主迭代协议

可以把下面的协议放进任务描述。它既适合优化被测实现，也适合调试评估用例：
真实 Agent 的运行可能产生费用。实验阶段可以加 --budget <美元> 限制本轮累计成本；预算只能限制单次命令，不能替代上面的停止条件。 人与 AI 随时可以接手同一轮工作。AI 用 niceeval show 读取的结果，也能由人运行 npx niceeval view 在网页中查看。两者读取同一批 artifact；完整的输出格式、历史选择和网页操作见查看结果。