.niceeval/<experiment>/<快照>/。快照记录本次运行实际选择的 selectedEvalIds；show / view 直接比较当前 Scope 中的 experiments。
控制台输出
.niceeval/<experiment>/<快照>/
落盘单位是结果快照（一个 experiment 的一次运行）：实验目录在外层，快照目录（时间戳 + 随机后缀，独占创建）在实验目录下。典型结构：
niceeval show：终端下钻
niceeval show 的位置参数有两种形态：评估用例 ID 前缀选择评估用例范围，@<locator> 精确指定一次 Attempt。Flag 选择证据类型：
@<locator> 是一次 Attempt 的持久、不透明身份，形如 @1k2m9qrs：由 {experimentId, 快照时刻, evalId, attempt 序号} 这个身份元组确定性派生，同一份落盘结果反复解析恒得到同一个值。它出现在 niceeval show 的分组明细里，直接复制粘贴就能定位到那一次运行。列表里的 locator 只打印 @<id>，不追加判定或证据能力缩写；打开 Attempt 首页后，available 会列出实际可用的证据命令。
Sandbox 创建、setup 或 teardown 错误不依赖 trace。result.json 保存错误的 code、message、生命周期阶段（phase）、有限 cause/stack 和 diagnostics；trace 只在存在时补调用关系与耗时。Attempt 在 cleanup、teardown 和 sandbox stop 结束后才封口写入，因此收尾 diagnostic 也能回顾。
同一个 Experiment 多次运行会留下多份结果。不带 @<locator> 的默认视图显示每个 Experiment × 评估用例最新的判定，并可能从同一个 Experiment 的多次运行中组合结果。按前缀只重跑部分评估用例时，其余评估用例的判定从更早的运行补齐。每份判定都带有生成时间，因此可以识别组合结果的来源。组合结果可能包含不同版本的被测代码，最终判定应以 --force 全量重跑为准。
单个评估用例视图里，多 experiment、多 Attempt 时默认展开最新一次失败的 Attempt；需要精确查看就复制该行的 @<locator>。--exp agents/codex 按 experiment id 路径收窄；--results 换结果根，--snapshot 只看某一次快照。
niceeval view 的每个视图都有 CLI 对应物：
默认分组比较报告
不带 flag 的niceeval show 直接输出当前 Scope 的成本 × 端到端成功率图和实验列表。每个 experiment 的 eval 数与指标分母读取其快照 selectedEvalIds；未选择的评估用例不补成失败。
实验列表先给固定列汇总，再按 experiment → 评估用例 → Attempt 展开。locator 只保留 @<id>；完整断言和 evidence 留在 niceeval show @<locator>。只有一个 experiment 时散点仍显示单点。
单个评估用例
@<locator>（compare/bub-gpt-5.4 只有一次 attempt 就代表它自己，compare/codex-gpt-5.4 代表的是默认展开的那一次失败）；展开的明细块结尾再重复一次精确的 attempt locator:，两处给的是同一个值。想看别的 attempt（比如 compare/codex-gpt-5.4 更早失败的那次），去 --history 或 artifact 目录里找到它的 locator，niceeval show @<locator> 直接跳过去，不需要先回到这张列表。
@<locator>：一次 Attempt 的摘要
不带证据 flag 的 niceeval show @<locator> 是失败诊断首页：除断言计票外，失败项直接列 group、matcher、expected、received、原因和源码位置；随后给出评估用例源码可用性、Agent 事件计数、OTel 计时可用性与工作区 diff 摘要。该页用于定位失败原因；需要追查 Agent 结果的来源时，再打开对应证据视图：
changes 行会说明 diff 不可用的具体原因：此处的 weather/brooklyn 不是 Sandbox 评估用例，因此从未收集工作区改动；Sandbox 评估用例未修改文件时则显示「没有产生工作区文件改动」。
--source、--execution、--timing、--diff：四个证据切面
四个证据 flag 既可以加在 @<locator> 后面（精确到一次 Attempt），也可以加在能唯一收窄到一个评估用例的前缀后面（挑同一套默认启发式选中的 attempt——最新一次失败，没有失败就挑最新一次，与单个评估用例详情块展开的是同一次）；前缀撞到不止一个评估用例时会报错，报错正文直接给出每个候选评估用例的 @<locator>，照抄一个继续即可。可以同时传多个证据 flag，一次输出全部要看的切面。
--source 是运行时保存的评估用例源码，按行标注每条断言、gate 失败与 soft 分数直接排在对应源码行下面，源码里没能对应到具体行的断言（没有位置信息，或位置指向另一个文件）单独成一段，永不丢弃：
--execution 把标准事件流（消息、thinking、Skill 加载、工具调用/结果、subagent、错误）排成一棵执行树；这次 Attempt 接入过 OTel 时，同一节点能关联到的 span 会补上相对时间与耗时。无法关联到 Agent 事件的 SDK / runtime span 不逐行混入执行记录，只在结尾报告省略数量并指向完整 trace.json。没接入 OTel 时骨架、顺序和内容不变，只去掉时间列并标 timing unavailable：
calledTool("get_weather") 这条 gate 断言失败的原因，--execution 在这里直接印证了 --source 那份断言标注。有 Skill 加载和工具调用时,--execution 把它们按发生顺序一起排进同一棵树,工具调用拆成「调用」与「结果」两行读:
--timing 显示整个 Attempt 的阶段耗时。Runner 把 lifecycle、setup/teardown hook、批量工作的 operation、所有经 Sandbox API 发出的 shell 命令，以及每个 session/turn 的 send 墙钟时间记入 result.json。某轮有 OTel 时，再按 traceId 把 Agent、model 和 tool span 挂到该轮下面。没有 OTel 时，phase、hook、operation、shell 与 Turn 时间仍完整，只缺轮内细分。出错或超时的 Attempt 会在已知的最深节点用 ✗ 标出：
--timing 会完整列出 phase，并把 phase 下的细节控制在 80 个节点内。超过上限时，它优先保留失败路径、最慢节点与首尾时序，在省略位置显示节点数、未展示的失败数，并给出 --timing=full。小树中两种模式输出相同；--timing=full 不设节点上限，适合审计旧结果或把完整树重定向到文件。NiceEval 不自动启动 pager，因此管道、CI 和 coding agent 不会等待键盘输入。命令可能并发，省略行不会把子节点耗时相加。
Operation 名称由执行工作的组件在采集时写入。例如一次 Workspace diff 导出可以显示为 export workspace diff · 1 window · 3,302 files，并包含一条真实的批量 shell。展示层不会解析 git show 等命令文本来推测 git show ×N 分组。旧 artifact 记录大量调用时，默认模式提供有界摘要，--timing=full 可以逐条核对。--timing 会分别显示 Sandbox 创建、安装命令和轮内模型或工具耗时。旧结果或第三方结果没有阶段数据时，两种模式都会提示 phase timing unavailable。
--diff 默认给文件级摘要（落盘的 diff 只有改动后的全文，没有基线可比对增删行数，所以每个改动过的文件都标 M、后面跟它现在的行数，不区分新建与修改）；看单个文件的完整内容用 --diff=<文件路径>——路径必须用 = 连写，位置参数永远留给评估用例 id 前缀 / @<locator>：
给 coding agent 的最短阅读路径
把下面这条闭环交给 coding agent 即可。每一步只在上一层不足以定位问题时继续，避免一开始就把完整 artifact 塞进上下文：--source 显示评估用例检查内容和断言结果，--execution 显示 Agent 消息与调用（可关联时附 OTel 时间），--timing 显示 Attempt 各阶段耗时，--diff 显示 Sandbox 文件改动。按诊断目标选择证据，不需要每次读取全部四种视图。
历史与抖动：--history
默认报告和单个评估用例视图显示最新判定。--history 用跨 run 时间轴显示稳定性和回归起点，每次真实执行一行：
view --snapshot <snapshot.json> 钉住拐点前后两次细看。时间轴只列真实执行——缓存携带的旧结果是判定的复印件，不占行，否则趋势会被复印件灌满假数据。不带评估用例 id 的 niceeval show --history 给每个 experiment 的 per-run 通过率序列，同一份趋势的榜单视角。
两次 run 的精确对比不提供专用 flag。使用 DeltaTable 组件编写自定义对比报告，再把文件传给 --report；终端和网页会渲染同一份报告。具体写法见自定义报告。
niceeval view：在网页看证据
niceeval show 选结果的规则一模一样：对每个 experiment 的每道评估用例，取时间上最新的那份判定，同一个 experiment 跨多次运行拼出来；收窄范围（评估用例 ID 前缀、--exp）时按同一条规则收窄。你可以浏览评估用例、查看 agent 的对话与工具调用、读 diff、检查断言结果。数据不会上传到外部服务。
view 的首页直接显示当前 Scope 的摘要、成本 × 端到端成功率散点图与实验表。传 --report 就换成自己的报告。Attempt 详情里的 transcript、时间树、trace 与 diff 始终可用。
网页版可以排序实验表、筛行、展开 experiment、悬停散点看数值；这些操作不改判定口径。
导出与静态托管
发布结果使用--out <目录> 导出完整静态站。需要自定义页面时，使用报告组件编写报告，见自定义报告。
内置查看器整站：静态托管
<dir>/index.html，并把查看器要读取的 artifact（sources.json、events.json、trace.json，有 diff.json 也带上）复制到 <dir>/artifact/ 下。把整个目录交给任何静态托管（Vercel、GitHub Pages 或 python3 -m http.server），代码视图、transcript 和 trace 瀑布图都和本地 niceeval view 一致；表格排序、过滤和图表悬停也照常可用——所需脚本已内联进页面，浏览器禁用 JS 时页面仍完整可读，只是少这些浏览操作。
只想发布一部分结果时，把本地查看用的收窄直接交给导出：
artifact/ 证据都只含收窄后的范围，被滤掉实验的 transcript、源码和 trace 不会跟着出站。不收窄就是整站导出完整结果。
--out 只接受目录。没有单文件导出：代码视图、transcript 和 trace 依赖 artifact 文件，单个 HTML 装不下完整证据。要把结果发给别人，托管整站发链接即可。
零可读结果时 view 直接报错、非零退出——本地服务起不来，--out 不导出空页面。错误逐条列出被跳过的快照目录与原因；落盘 schemaVersion 与当前版本不兼容时，还给出能直接查看旧落盘的 npx niceeval@<版本> view 命令。
两点限制：
o11y.json不会被复制——报告数字已经算进页面，查看器不读取它。- 用
file://直接打开index.html时浏览器不允许 fetch artifact，代码视图会提示源码不可用。本地预览用 http 服务打开。
copySnapshots 生成经过单文件预算检查的发布结果根并提交到仓库，再让 CI 对该目录运行 view --results <目录> --out。Workflow 与托管平台配置见通过 CI 发布报告。
Artifact 说明
snapshot.json
快照级元数据：实验身份（experimentId）、agent、model、开始与收尾时间、格式版本。不含任何逐 attempt 数据——通过数、失败数这类聚合不落盘，由读取面逐条推导。
result.json
单个 Attempt 的权威记录：判定、断言、正式阶段耗时、结构化 error、去重后的 diagnostics、用量和成本。cleanup、teardown 与 Sandbox stop 完成后一次写成，之后不再改写。progress 的短期 message/current/total 不落盘。
events.json
标准事件流，是工具调用、消息、命令和错误的底层事实来源。
diff.json
Sandbox 评估用例中 agent 改动的文件 diff。
sources.json
评估用例源码位置和断言位置，用于查看器把失败断言对应回代码。
trace.json
OTLP trace 或标准化后的 span 数据。它是可选的执行关系和耗时证据，不是错误存储：Sandbox 创建（sandbox.create）可能早于 telemetry，teardown 可能晚于 trace collect。
o11y.json
工具调用、命令、usage 和成本等观测摘要。
Verdict 含义
- passed
- failed
- errored
- skipped
所有 gate 通过。
assertions[].score 里；非 --strict 模式下，它们不会产生额外的 verdict。
调试建议
- 榜单里失败/错误的题每条自带下钻命令：
niceeval show <eval id>先看断言明细，行尾的@<locator>可以直接精确下钻到某一次 Attempt。 - 检查评估用例内容和断言结果时使用
--source，断言标注会对应到源码行。 - 检查 Agent 消息和调用时使用
--execution；关联成功的 OTel 时间会显示在同一事件旁。 - coding-agent 失败时看
--diff和--execution里的工具调用；两者结合能看出「改错了文件」还是「压根没调用该调用的工具」。 - Sandbox 评估用例运行缓慢或超时时，先看
--timing。该视图分别列出排队、Sandbox 启动、setup hook 中的 shell、Agent 安装命令、每轮send、可关联的 OTel model/tool 以及收尾阶段耗时。 - 定位被测程序或评估用例缺陷并完成重跑的流程见 Coding Agent 反馈闭环。