跳转到主要内容
运行评估用 niceeval exp。读取结果有三条路:脚本和 CI 用 niceeval show --json 取 JSON,人和 Coding Agent 在终端用 niceeval show 逐层查看,在浏览器里审阅用 niceeval view。 三条路读的是同一份运行记录 .niceeval/record.sqlite。每次读取开始时,NiceEval 会固定一个可见边界:此刻已经写入的结果都能看到,之后写入的不会混进这次读取。所属 Run 还在运行时,已经写入的 Attempt 也能读到。 把 niceeval exp 的输出接到管道时,stdout 仍会显示进度。每行带上 Experiment、评估用例和 Attempt 序号。同一个 Attempt 每秒最多输出一次,内容没变就不重复输出。直接在终端里运行时显示动态面板。脚本要读结构化结果时加 --json。 重复传入 --experiment 可以一次运行多个实验,例如 niceeval exp --experiment baseline --experiment memory --max-concurrency 4。这些实验在同一次运行里共享并发上限和预算。同一个 ID 写两次只运行一次。只要有一个 ID 不存在,整条命令在开始执行前就会失败。用了 --experiment 后,位置参数用来筛选评估用例。

--dry 沿用状态

niceeval exp <experiment> --dry 只读计划,不执行评估。每行是一个实验与评估用例的组合,reused 0、gap 0:... 中的数字是从 0 开始的 Attempt 序号。 source 后面的 verdict 是历史判定:passed 为通过,failed 为断言失败,errored 为执行出错,skipped 为跳过。 errored、skipped 需要按缺口原因决定重跑;用 niceeval show @<locator> 查看详情。 若显示 not-recorded、unsupported 或 invalid,表示判定附件未记录、不支持或内容无效;不能把它们读成通过。 先运行 niceeval show @<locator> assertions 取证。旧格式 Record 在打开时明确拒绝,不自动升级;保留或归档原文件后再重新执行。

--dry 缺口代码

下表列出 gap <序号>:<代码> 的全部原因。表中的“重跑”指先核对费用与选择范围,再运行 niceeval exp <experiment> <eval-prefix>;这会保留历史结果。 同时显示 locked 时先等待持锁执行结束,再判断缺口。

--dry 差异摘要

changed、added、removed 分别表示输入变化、新增或移除;先审阅该输入,再决定执行。unknown 表示无法比较,应查看 --dry --json 的诊断。 niceeval: 是依赖的框架能力,config: 是配置,plan:physical 是执行计划,plugins: 是生命周期插件,source: 与 data: 分别是源码和受管数据。 结构化摘要完整时会显示具体值。摘要不完整时,summary sha256:<短哈希> 区分两侧已保存的摘要;它不是完整执行身份的 digest,也不能恢复被省略的字段。 如果两份不完整摘要恰好相同,会显示一次 comparison unavailable,并说明无法比较的原因;这不代表输入相同。 需要更多证据时运行 niceeval exp <experiment> --dry --json。--dry 不修改历史 manifest,也不因摘要可读性改变沿用决定。

niceeval show

先写对象,再写方面或稳定 ID。省略对象读取当前结果;带 --record 时读取该文件中的历史结果。
追加 --json 得到 JSON Lines。每份成功 document 的 links 含 rel 和完整 command,复制命令并追加 --json 即可继续读取。 Next 与 links 中的命令一致;外部 Record 的命令保留同一个 --record。explanation 和 failure 不带 links。 用 niceeval show <对象> <方面> --explain --json 查看这次读取使用的事实,成功结果的 outcome 为 success,解释为 explanation,错误为 failure。 ae_ 选择断言,fc_ 选择文件改动,art_ 选择产物;执行记录使用输出给出的稳定 ID。 这些 ID 可以省略方面词。方面与前缀冲突或前缀未知时会报错并列出可用方面。 --full 只用于单条断言,--eval 只用于 Experiment 判据矩阵,--actor 和 --type 只用于 execution,--reprice 只用于 usage。 有分页时沿 next-page link 继续读取。--continuation 绑定同一对象、筛选条件与可见范围;绑定变化时从第一页重新读取。 断言图片命令把完整图片写入文件,不接受 --json。

niceeval compare

左右两组各至少一个 Run,组内用空格分开。模式为 paired、side-by-side 或 exact。 --max-regressions 只用于 paired 或 exact;回退数量超过上限时命令失败。追加 --json 读取相同比较的机器结果。

niceeval view

把 show 换成 view,保留对象、方面与 ID,就能在浏览器打开同一位置。 启动时先校验选择;未命中或 ID 冲突时失败,不打开浏览器。--no-open 只打印 URL,--port 选择本机端口。

选择读取方式

三条路读取得到的是同一份结果,但各自负责自己的排版和展示。

发现和恢复 Run

niceeval run list 按创建时间从新到旧列出 Run;时间相同则按 Run ID 排序。多个 --state 取并集,不同筛选项取交集:
exp:suite 匹配 suite 和 suite/...,不会匹配 suite-other。--limit 必须是正整数;不传时不截断。JSON 的 omitted 是筛选后被省略的数量。 active、recovering 行会显示 owner 的 alive、gone 或 unknown 观察及观察时间。alive 表示观察时记录的进程仍存在,gone 表示已证明终止。unknown 的 reason 区分异机记录、缺失进程身份、外部 Record 或探测失败。观察不会修改 Run 状态;读取外部 Record 不会探测本机进程。
--orphaned 在一次读取边界上冻结 active、recovering 候选集,确认前列出 Run ID,再逐项重验状态、写入世代和进程身份。它会跳过 alive、unknown owner;单项失败不阻止其余项,存在失败时退出码非零。JSON 的 items 为每个 Run 列出 recovered、skipped 或 failed 结果。没有候选是成功的空结果。JSON 模式必须传 --yes;人读模式只在交互终端询问一次确认。 recovering 表示恢复已经取得写入权,但这个 Run 还没有被标为结束。恢复进程中断后可重试同一命令;仍需证明上一个恢复进程已终止。恢复只为未发布的位置补上 absence 并结束这个 Run,保留已发布的 Attempt。它不会释放共享 State、执行 Experiment after 或清理 Sandbox;这些操作需要各自的显式命令。

CLI flags

下表从各命令自己的选项定义生成。表里没有的 flag 会被当作未知参数拒绝。