niceeval 0.6.2 → 0.7.1

package/src/cli.ts

@@ -97,7 +97,7 @@ interface Flags {
   help: boolean;
   version: boolean;
   // ── show 专属(位置参数仍是 eval id 前缀 / `@<locator>`;这些 flag 选「怎么看」)──
-  eval: boolean;
+  source: boolean;
   execution: boolean;
   diff: boolean;
   /** --diff=<路径>(必须 = 连写;空格形式会把路径当 eval id 前缀,按文档如此)。 */
@@ -111,8 +111,10 @@ interface Flags {
   leaveRunning: boolean;
   history: boolean;
   experiment?: string;
-  run?: string;
+  results?: string;
+  snapshot?: string;
   report?: string;
+  page?: string;
 }
 
 // 表驱动的 flag 定义(node:util parseArgs)。--no-x 显式声明,不依赖 allowNegative(需 Node 20.14+,
@@ -156,11 +158,11 @@ const FLAG_OPTIONS = {
   port: { type: "string" },
   /** `view --out` 专用:对非发布根(快照没有 publish:{redaction:"applied"} 标记)导出时的显式确认——静态站会原样携带未消毒的证据文件。 */
   "allow-sensitive-artifacts": { type: "boolean" },
-  // show 的证据切面 / 时间轴 / 报告装载(docs-site/zh/guides/viewing-results.mdx)。
+  // show 的证据切面 / 时间轴 / 报告装载(docs-site/zh/how-to/viewing-results.mdx)。
   // 证据切面只认 `@<locator>`(或收窄到单个 eval 的前缀)选出的那一个 attempt——不再有
   // 数字 `--attempt`,选哪个 attempt 由 locator 精确指名,不是「先选 eval 再挑第几次」。
   /** `show` 命令专用:该 attempt 运行时保存的 Eval 源码,gate/soft 断言标回源码行(证据切面)。 */
-  eval: { type: "boolean" },
+  source: { type: "boolean" },
   /** `show` 命令专用:该 attempt 的标准执行事件流(消息、thinking、Skill load、工具调用/结果);有 OTel 时同一节点补时间(证据切面)。 */
   execution: { type: "boolean" },
   /** `show` 命令专用:整个 Attempt 的统一时间树;裸 `--timing` 给有界诊断投影,`--timing=full` 逐节点展开全部 runner/已关联 OTel 节点。 */
@@ -169,14 +171,18 @@ const FLAG_OPTIONS = {
   // 空格形式的下一个 token 仍是位置参数 = eval id 前缀,与文档一致)。
   /** `show` 命令专用:sandbox 里的文件改动摘要;`--diff=<文件路径>` 看单个文件的完整改动(路径必须 `=` 连写)。 */
   diff: { type: "boolean" },
-  /** `show` 命令专用:跨 run 时间轴,只列真实执行;与 `--report` 互斥。 */
+  /** `show` 命令专用:执行时间轴——对匹配的每个 experiment × eval 分节,逐 attempt 列时间 / verdict / 摘要 / 耗时 / 成本 / locator;与 `--report` 互斥。 */
   history: { type: "boolean" },
   /** `show` / `view` 命令专用:按路径段前缀收窄 experiment;组名会选中组内全部配置。 */
   experiment: { type: "string" },
-  /** `show` / `view` 命令专用:钉死看某一个结果目录(某次快照或 `copySnapshots` 产物)。 */
-  run: { type: "string" },
+  /** `show` / `view` / `sandbox enter|list|stop` 共用:结果根目录(`.niceeval` 之外的另一个根,如 `copySnapshots` 产出的发布根)。 */
+  results: { type: "string" },
+  /** `view` 命令专用:只打开这一份快照文件(`snapshot.json`);文件不可读时命令失败(扫描模式只跳过)。 */
+  snapshot: { type: "string" },
   /** `show` / `view` 命令专用:用文件默认导出的 `defineReport(...)` 替换两者共用的默认报告。 */
   report: { type: "string" },
+  /** `show` / `view` 命令专用:选择多页报告的页(页 id 见 `show --report` 的页索引);`view` 里定初始页。 */
+  page: { type: "string" },
   /** 只打印本次会匹配到的 eval × 运行配置,不实际执行(按下面 `--output` 选中的 profile 给出预览)。 */
   dry: { type: "boolean" },
   /** 反馈 profile:`auto`(默认)按环境自动选择,`human` / `agent` / `ci` 强制指定;只改变终端展示,不改变选择、调度、判定、artifact 或退出码。`auto` 依次判定:stderr 是 TTY → human;否则 `CI`(或其它常见 CI 平台环境变量)存在 → ci;否则 → agent。 */
@@ -294,7 +300,7 @@ function parseArgs(argv: string[]): { command: string; positionals: string[]; fl
     open: values["no-open"] === true ? false : values.open === true ? true : undefined,
     help: values.help === true,
     version: values.version === true,
-    eval: values.eval === true,
+    source: values.source === true,
     execution: values.execution === true,
     diff: values.diff === true && diffPath === undefined,
     diffPath,
@@ -307,31 +313,35 @@ function parseArgs(argv: string[]): { command: string; positionals: string[]; fl
     leaveRunning: values["leave-running"] === true,
     history: values.history === true,
     experiment: values.experiment as string | undefined,
-    run: values.run as string | undefined,
+    results: values.results as string | undefined,
+    snapshot: values.snapshot as string | undefined,
     report: values.report as string | undefined,
+    page: values.page as string | undefined,
   };
   return { command, positionals, flags };
 }
 
 /**
  * exp 只接受两类输入:位置参数选「跑哪些 eval」+ 调度/输出/机器出口 flag 选「对着哪个 agent、
- * 怎么跑」。show / view 专属的证据切面(`--eval`/`--execution`/`--diff`)、时间轴(`--history`)、
- * Selection 收窄(`--experiment`/`--run`)、报告装载(`--report`)、查看器(`--out`/`--port`/`--open`)
- * 不能被 exp 静默忽略(见 docs/feature/experiments/cli.md「用法错误」)。返回第一个被误用的
- * flag 及其归属命令(用于报错),没有误用返回 undefined。
+ * 怎么跑」。show / view 专属的证据切面(`--source`/`--execution`/`--diff`)、时间轴(`--history`)、
+ * Scope 收窄(`--experiment`/`--results`)、报告装载(`--report`/`--page`)、查看器
+ * (`--snapshot`/`--out`/`--port`/`--open`)不能被 exp 静默忽略(见 docs/feature/experiments/
+ * cli.md「用法错误」)。返回第一个被误用的 flag 及其归属命令(用于报错),没有误用返回 undefined。
  */
 function firstViewerOnlyFlag(flags: Flags): { flag: string; command: string } | undefined {
   const SHOW = "show";
   const BOTH = "show / view";
   const VIEW = "view";
-  if (flags.eval) return { flag: "--eval", command: SHOW };
+  if (flags.source) return { flag: "--source", command: SHOW };
   if (flags.execution) return { flag: "--execution", command: SHOW };
   if (flags.timing !== undefined) return { flag: "--timing", command: SHOW };
   if (flags.diff || flags.diffPath !== undefined) return { flag: "--diff", command: SHOW };
   if (flags.history) return { flag: "--history", command: SHOW };
   if (flags.experiment !== undefined) return { flag: "--experiment", command: BOTH };
-  if (flags.run !== undefined) return { flag: "--run", command: BOTH };
+  if (flags.results !== undefined) return { flag: "--results", command: BOTH };
   if (flags.report !== undefined) return { flag: "--report", command: BOTH };
+  if (flags.page !== undefined) return { flag: "--page", command: BOTH };
+  if (flags.snapshot !== undefined) return { flag: "--snapshot", command: VIEW };
   if (flags.out !== undefined) return { flag: "--out", command: VIEW };
   if (flags.port !== undefined) return { flag: "--port", command: VIEW };
   if (flags.open !== undefined) return { flag: "--open", command: VIEW };
@@ -393,7 +403,7 @@ const AGENT_RULES_CONTENT = [
   "the bundled Chinese docs are the authoritative version matching this installation.",
   "After a run, drill into failures with `niceeval show` — pick an `@<locator>` from the",
   "compact index it prints, then `niceeval show @<locator>` for a compact overview, or add",
-  "`--eval` / `--execution` / `--diff` for evidence; the snapshot directories the CLI prints",
+  "`--source` / `--execution` / `--diff` for evidence; the snapshot directories the CLI prints",
   "are the structured source of truth: `snapshot.json` holds the run's metadata and each",
   "`<evalId>/a<attempt>/result.json` holds that attempt's verdict and assertions, next to",
   "its artifact files (`events.json` / `trace.json` / `diff.json`).",
@@ -560,11 +570,17 @@ async function main(): Promise<void> {
   }
 
   if (command === "view") {
-    // 位置参数 = eval id 前缀(收窄报告槽 Selection);存在的文件路径 = 单文件模式;
-    // 结果目录经 --run 递入;--report 整槽替换报告槽(与 show --report 吃同一个文件)。
+    // 位置参数只有一种含义:eval id 前缀(收窄报告槽 Scope)。结果根经 --results 递入,
+    // 单开一份快照经 --snapshot 递入;--report 整槽替换报告槽(与 show --report 吃同一个文件),
+    // --page 定初始页。文件与目录都不进位置参数(docs/feature/reports/view.md「打开与收窄」)。
+    // --out 与位置参数 / --experiment 的互斥在 buildView 内校验(单点,报错文案含 copySnapshots
+    // + filter 的下一步),经 exitOnViewUserError 按用法错误退出。
     let viewInput: { input?: string; patterns: string[] };
     try {
-      viewInput = resolveViewInput(cwd, positionals, flags.run);
+      viewInput = resolveViewInput(cwd, positionals, {
+        ...(flags.results !== undefined ? { results: flags.results } : {}),
+        ...(flags.snapshot !== undefined ? { snapshot: flags.snapshot } : {}),
+      });
     } catch (e) {
       exitOnViewUserError(e);
     }
@@ -572,6 +588,7 @@ async function main(): Promise<void> {
       patterns: viewInput.patterns,
       ...(flags.experiment !== undefined ? { experiment: flags.experiment } : {}),
       ...(flags.report !== undefined ? { report: { path: flags.report, cwd } } : {}),
+      ...(flags.page !== undefined ? { page: flags.page } : {}),
     };
     if (flags.out) {
       const out = await buildView({ input: viewInput.input, out: flags.out, allowSensitiveArtifacts: flags.allowSensitiveArtifacts, scan }).catch(exitOnViewUserError);
@@ -599,23 +616,25 @@ async function main(): Promise<void> {
       window: flags.window,
       path: flags.sandboxPath,
       leaveRunning: flags.leaveRunning,
-      run: flags.run,
+      // CLI flag 是 --results(结果根);sandbox 命令组的内部选项名保持 run,值语义相同。
+      run: flags.results,
     });
     process.exit(code);
   }
 
   if (command === "show") {
-    // show 不依赖 niceeval.config.ts:读的是 .niceeval/(或 --run 指定的某个快照目录)的落盘结果。
+    // show 不依赖 niceeval.config.ts:读的是 .niceeval/(或 --results 指定的结果根)的落盘结果。
     const code = await runShow(cwd, positionals, {
-      eval: flags.eval,
+      source: flags.source,
       execution: flags.execution,
       timing: flags.timing,
       diff: flags.diff,
       diffPath: flags.diffPath,
       history: flags.history,
       experiment: flags.experiment,
-      run: flags.run,
+      results: flags.results,
       report: flags.report,
+      page: flags.page,
     });
     process.exit(code);
   }

package/src/context/context.ts

@@ -91,7 +91,7 @@ export interface ContextDeps {
  * 这是唯一仍需要构造证据之外强制检查的能力——`t.sandbox.file`/`t.sandbox.fileChanged()` 等直接读沙箱
  * 文件系统,没有沙箱就没有东西可读,不报错会静默返回空结果。其余能力(多轮对话、
  * 工具断言……)都不再问卷式声明,由「做没做到」的构造证据决定,见
- * docs-site/zh/concepts/adapter.mdx「能力从哪来」一节。
+ * docs-site/zh/explanation/adapter.mdx「能力从哪来」一节。
  */
 function capabilityGuard(agentName: string, cap: string, method: string): () => never {
   return () => {

package/src/context/session.test.ts

@@ -5,7 +5,7 @@ import { createAgentSession, SessionManager } from "./session.ts";
 import type { Agent, Sandbox, StreamEvent, Turn, TurnInput } from "../types.ts";
 
 // createAgentSession() 是 ctx.session 的实现——一条会话线的存取器(见
-// docs-site/zh/concepts/adapter.mdx 的 AgentSession 契约)。这里直接测存取器本身;
+// docs-site/zh/explanation/adapter.mdx 的 AgentSession 契约)。这里直接测存取器本身;
 // 端到端的「同一条线同一个 ctx.session」由 SessionManager / RunSession 保证。
 
 function fakeSandbox(): Sandbox {

package/src/context/session.ts

@@ -8,7 +8,7 @@ import { captureLoc } from "../source-loc.ts";
 import { t } from "../i18n/index.ts";
 
 /**
- * 一条会话线的存取器实现(见 docs-site/zh/concepts/adapter.mdx 的 AgentSession 契约)。
+ * 一条会话线的存取器实现(见 docs-site/zh/explanation/adapter.mdx 的 AgentSession 契约)。
  * 私有槽都关在闭包里——`state` 只归用户,框架内部数据不往里塞。
  */
 export function createAgentSession(): AgentSession {

package/src/i18n/en.ts

@@ -48,7 +48,7 @@ export const en = {
     "Ways to fix:\n" +
     "  - [init] Run `npx niceeval init` to scaffold niceeval.config.ts and evals/\n" +
     "  - [cd] Run from the project root that contains niceeval.config.ts\n" +
-    "  Docs: node_modules/niceeval/docs-site/zh/quickstart.mdx",
+    "  Docs: node_modules/niceeval/docs-site/zh/tutorials/quickstart.mdx",
   "cli.config.noDefault": "niceeval.config.ts must default export defineConfig(...).",
   "cli.dry.header": "\n[dry] {{evals}} evals × {{configs}} run configs:\n",
   "cli.dry.noMatches": "(no matches)",
@@ -60,7 +60,7 @@ export const en = {
     "budget for {{budgetKey}}: several attempts completed without any cost data (agent reports no usage and the model is not in the price table) — the budget cannot be enforced for this agent; continuing without the guard.\n",
   "judge.modelMissing":
     "No judge model configured. Set it in defineConfig({ judge: { model: \"...\" } }), the eval's judge config, or the NICEEVAL_JUDGE_MODEL environment variable (there is no built-in default model).\n" +
-    "  Docs: node_modules/niceeval/docs-site/zh/guides/scoring-guide.mdx",
+    "  Docs: node_modules/niceeval/docs-site/zh/how-to/scoring-guide.mdx",
   "loaders.yamlMissing":
     "loadYaml(\"{{path}}\") needs a YAML parser: run `pnpm add yaml` first (or switch to loadJson with a JSON dataset).",
   "cli.flag.parseError": "{{message}}\nRun `niceeval --help` for usage.\n",
@@ -75,20 +75,22 @@ export const en = {
     "      a single eval id: attempts + assertion details\n" +
     "      @<locator>  exactly one attempt: no flag -> compact overview;\n" +
     "        with a flag -> that evidence slice\n" +
-    "      --eval        the Eval source captured when this attempt ran,\n" +
+    "      --source      the Eval source captured when this attempt ran,\n" +
     "        assertions mapped back to source lines\n" +
     "      --execution   this attempt's execution event stream (messages/thinking/\n" +
     "        Skill loads/tool calls); OTel adds timing to the same node when present\n" +
     "      --timing      unified timing tree for the attempt (phases + hooks/commands/turns + per-turn OTel)\n" +
     "      --diff[=file] sandbox workspace file-change summary; =file expands one file\n" +
-    "      --history   cross-run timeline (mutually exclusive with --report)\n" +
-    "      --run <dir>   pin a results dir    --experiment <id>   one experiment\n" +
-    "      --report <file>   custom report\n" +
+    "      --history   per experiment × eval execution timeline (mutually exclusive with --report)\n" +
+    "      --results <dir>   pin a results root    --experiment <id>   one experiment\n" +
+    "      --report <file>   custom report    --page <id>   pick a page (multi-page\n" +
+    "        reports print a page index with copyable commands)\n" +
     "  niceeval list                                       list discovered evals\n" +
-    "  niceeval view [eval-id-prefix…|snapshot.json] [--out dir] [--port n] [--no-open]\n" +
-    "      report slot + evidence rooms; --report <file> swaps in your report\n" +
-    "      (same file as show); --run <dir> pins a results dir;\n" +
-    "      --experiment <id> one experiment\n" +
+    "  niceeval view [eval-id-prefix…] [--out dir] [--port n] [--no-open]\n" +
+    "      report pages + evidence rooms; --report <file> swaps in your report\n" +
+    "      (same file as show); --page <id> picks the initial page;\n" +
+    "      --results <dir> pins a results root; --snapshot <file> opens exactly\n" +
+    "      one snapshot; --experiment <id> one experiment\n" +
     "      --out <dir> exports a static site: index.html plus the viewer\n" +
     "      artifacts, ready for any static host\n" +
     "  niceeval sandbox list|enter|history|diff|stop  inspect & destroy sandboxes kept by --keep-sandbox\n" +
@@ -107,9 +109,9 @@ export const en = {
   "cli.show.noEvalMatch": "No results matched: {{patterns}}. Evals with results: {{evals}}\n",
   "cli.show.noExperimentMatch": "No experiment matched --experiment {{arg}}. Experiments with results: {{experiments}}\n",
   "cli.show.historyReportConflict":
-    "`--history` and `--report` are mutually exclusive: --history is the built-in trend view. For a custom trend, compose exp.snapshots inside your report file instead.\n",
+    "`--history` and `--report` are mutually exclusive: both take over the main output. --history is the host's per-attempt execution timeline; for snapshot-level trends, compose exp.snapshots inside your report file instead.\n",
   "cli.show.evidenceNeedsEval":
-    "--eval / --execution / --diff show one attempt's evidence, but the selection matched {{matched}} evals. Pick an attempt locator from the index below:\n{{index}}\n",
+    "--source / --execution / --diff show one attempt's evidence, but the selection matched {{matched}} evals. Pick an attempt locator from the index below:\n{{index}}\n",
   "cli.show.locatorMalformed": "{{message}}\n",
   "cli.show.locatorNotFound": "{{message}}\n",
   "cli.eval.noMatch": "No eval matched: {{patterns}}.\n",
@@ -132,7 +134,7 @@ export const en = {
   "cli.resultsPath": "Structured results: {{path}} (snapshot.json + per-attempt result.json / events.json / trace.json / diff.json)\n",
   "cli.run.experimentRequired":
     "Run evals through an experiment: use `niceeval exp [group|config] [eval id prefix]`.\n" +
-    "  Docs: node_modules/niceeval/docs-site/zh/guides/write-experiment.mdx\n",
+    "  Docs: node_modules/niceeval/docs-site/zh/how-to/write-experiment.mdx\n",
   "cli.run.experimentRequiredHint": "Hint: \"{{pattern}}\" is an experiment{{kind}}; you probably meant: niceeval exp {{pattern}}\n",
   "cli.run.experimentRequiredKnown": "Discovered experiments: {{experiments}}\n",
   "cli.unimplemented": "Command \"{{command}}\" is not implemented yet (MVP).\n",
@@ -143,7 +145,7 @@ export const en = {
   "cli.view.url": "niceeval view: {{url}}\n",
   "context.capabilityMissing":
     "Agent \"{{agent}}\" is not sandbox-backed (built with defineSandboxAgent), so t.{{method}} is unavailable. Use an agent built with defineSandboxAgent, or drop this assertion.\n" +
-    "  Docs: node_modules/niceeval/docs-site/zh/guides/sandbox-agent.mdx",
+    "  Docs: node_modules/niceeval/docs-site/zh/how-to/sandbox-agent.mdx",
   "context.skipEmpty": "skip() requires a non-empty reason.",
   "context.turnFailed": "This send returned failed (turn status = failed): {{message}}",
   "context.turnFailedDefault": "This send returned failed (turn status = failed)",
@@ -167,7 +169,7 @@ export const en = {
   "feedback.human.compare": "Compare: niceeval view {{group}}",
   "feedback.human.counts": "{{total}} total · {{reused}} reused · {{running}} running · {{queued}} queued · {{completed}} completed",
   "feedback.human.diffHint": "Diff:    niceeval show {{locator}} --diff",
-  "feedback.human.evalHint": "Eval:    niceeval show {{locator}} --eval",
+  "feedback.human.evalHint": "Eval:    niceeval show {{locator}} --source",
   "feedback.human.failuresHeader": "FAILURES",
   "feedback.human.heartbeat": "{{elapsed}} elapsed · {{counts}}",
   "feedback.human.inspect": "Inspect: niceeval show {{locator}}",
@@ -274,7 +276,7 @@ export const en = {
   "sandbox.providerNotImplemented": "{{provider}} sandbox provider is not implemented; use docker, vercel, or e2b",
   "sandbox.missingSpec":
     "sandbox agent needs a sandbox, but none was given. niceeval no longer picks a default — set `sandbox` in defineExperiment()/defineConfig() to dockerSandbox() / vercelSandbox() / e2bSandbox() (import from \"niceeval/sandbox\").\n" +
-    "  Docs: node_modules/niceeval/docs-site/zh/guides/sandbox-providers.mdx",
+    "  Docs: node_modules/niceeval/docs-site/zh/how-to/sandbox-providers.mdx",
   "sandbox.dependencyMissing.docker": "Docker sandbox requires 'dockerode'. Install it with: pnpm add dockerode @types/dockerode",
   "sandbox.dependencyMissing.e2b": "E2B sandbox requires 'e2b'. Install it with: pnpm add e2b",
   "sandbox.dependencyMissing.vercel": "Vercel sandbox requires '@vercel/sandbox'. Install it with: pnpm add @vercel/sandbox",

package/src/i18n/zh-CN.ts

@@ -46,7 +46,7 @@ export const zhCN = {
     "修法:\n" +
     "  - [init] 运行 `npx niceeval init` 生成 niceeval.config.ts 和 evals/\n" +
     "  - [cd] 切到包含 niceeval.config.ts 的项目根再运行\n" +
-    "  文档:node_modules/niceeval/docs-site/zh/quickstart.mdx",
+    "  文档:node_modules/niceeval/docs-site/zh/tutorials/quickstart.mdx",
   "cli.config.noDefault": "niceeval.config.ts 需要 default export(defineConfig(...))。",
   "cli.dry.header": "\n[dry] {{evals}} 个 eval × {{configs}} 个运行配置:\n",
   "cli.dry.noMatches": "(无匹配)",
@@ -58,7 +58,7 @@ export const zhCN = {
     "{{budgetKey}} 的 budget:连续多个 attempt 完成后都拿不到成本数据(agent 不上报用量且模型不在价格表)——该 agent 的 budget 无法执行,取消护栏继续跑。\n",
   "judge.modelMissing":
     "judge 未配置模型:在 defineConfig({ judge: { model: \"...\" } })、eval 的 judge 配置或环境变量 NICEEVAL_JUDGE_MODEL 里指定裁判模型(没有内置默认模型)。\n" +
-    "  文档:node_modules/niceeval/docs-site/zh/guides/scoring-guide.mdx",
+    "  文档:node_modules/niceeval/docs-site/zh/how-to/scoring-guide.mdx",
   "loaders.yamlMissing":
     "loadYaml(\"{{path}}\") 需要 YAML 解析器:请先 `pnpm add yaml`(或改用 loadJson + JSON 数据集)。",
   "cli.flag.parseError": "{{message}}\n运行 `niceeval --help` 查看用法。\n",
@@ -72,18 +72,19 @@ export const zhCN = {
     "        (locator + 失败原因)\n" +
     "      单个 eval id:attempt 与断言明细\n" +
     "      @<locator>  精确一个 attempt:无 flag → 紧凑全景;带 flag → 对应证据切面\n" +
-    "      --eval        该 attempt 运行时保存的 Eval 源码,断言标回源码行\n" +
+    "      --source      该 attempt 运行时保存的 Eval 源码,断言标回源码行\n" +
     "      --execution   该 attempt 的执行事件流(消息/thinking/Skill/工具调用),\n" +
     "        有 OTel 时同一节点补时间\n" +
     "      --timing      整个 attempt 的统一时间树(阶段 + hook/命令/turn + 轮内 OTel)\n" +
     "      --diff[=文件] agent 归因的文件改动摘要;=文件 按窗口展开单个文件\n" +
-    "      --history   跨 run 时间轴(与 --report 互斥)\n" +
-    "      --run <目录> 钉死结果目录   --experiment <id> 只看该实验\n" +
-    "      --report <文件> 自定义报告\n" +
+    "      --history   逐 experiment × eval 的执行时间轴(与 --report 互斥)\n" +
+    "      --results <目录> 钉死结果根   --experiment <id> 只看该实验\n" +
+    "      --report <文件> 自定义报告   --page <id> 选页(多页报告先输出页索引)\n" +
     "  niceeval list                            列出发现到的 eval\n" +
-    "  niceeval view [eval-id 前缀…|snapshot.json] [--out 目录] [--port n] [--no-open]\n" +
-    "      报告槽 + 证据室;--report <文件> 整槽换成自定义报告(与 show 同一文件)\n" +
-    "      --run <目录> 钉死结果目录   --experiment <id> 只看该实验\n" +
+    "  niceeval view [eval-id 前缀…] [--out 目录] [--port n] [--no-open]\n" +
+    "      报告页 + 证据室;--report <文件> 整槽换成自定义报告(与 show 同一文件)\n" +
+    "      --page <id> 定初始页   --results <目录> 钉死结果根\n" +
+    "      --snapshot <文件> 只打开这一份快照   --experiment <id> 只看该实验\n" +
     "      --out <目录> 静态导出:index.html 连同查看器 artifact,可直接静态托管\n" +
     "  niceeval sandbox list|enter|history|diff|stop  查看与销毁 --keep-sandbox 留下的现场\n" +
     "  niceeval clean                           删除 .niceeval/ 历史 artifact\n" +
@@ -102,9 +103,9 @@ export const zhCN = {
   "cli.show.noEvalMatch": "No results matched: {{patterns}}. Evals with results: {{evals}}\n",
   "cli.show.noExperimentMatch": "No experiment matched --experiment {{arg}}. Experiments with results: {{experiments}}\n",
   "cli.show.historyReportConflict":
-    "`--history` and `--report` are mutually exclusive: --history is the built-in trend view. For a custom trend, compose exp.snapshots inside your report file instead.\n",
+    "`--history` and `--report` are mutually exclusive: both take over the main output. --history is the host's per-attempt execution timeline; for snapshot-level trends, compose exp.snapshots inside your report file instead.\n",
   "cli.show.evidenceNeedsEval":
-    "--eval / --execution / --diff show one attempt's evidence, but the selection matched {{matched}} evals. Pick an attempt locator from the index below:\n{{index}}\n",
+    "--source / --execution / --diff show one attempt's evidence, but the selection matched {{matched}} evals. Pick an attempt locator from the index below:\n{{index}}\n",
   "cli.show.locatorMalformed": "{{message}}\n",
   "cli.show.locatorNotFound": "{{message}}\n",
   "cli.eval.noMatch": "没有匹配的 eval:{{patterns}}。\n",
@@ -127,7 +128,7 @@ export const zhCN = {
   "cli.resultsPath": "结构化结果:{{path}}(snapshot.json + 每 attempt 的 result.json / events.json / trace.json / diff.json)\n",
   "cli.run.experimentRequired":
     "运行 eval 必须通过 experiment:用 `niceeval exp [实验组|配置] [eval id 前缀]`。\n" +
-    "  文档:node_modules/niceeval/docs-site/zh/guides/write-experiment.mdx\n",
+    "  文档:node_modules/niceeval/docs-site/zh/how-to/write-experiment.mdx\n",
   "cli.run.experimentRequiredHint": "提示:\"{{pattern}}\" 是实验{{kind}},你大概想跑:niceeval exp {{pattern}}\n",
   "cli.run.experimentRequiredKnown": "已发现实验:{{experiments}}\n",
   "cli.unimplemented": "命令 \"{{command}}\" 暂未实现(MVP)。\n",
@@ -138,7 +139,7 @@ export const zhCN = {
   "cli.view.url": "niceeval view: {{url}}\n",
   "context.capabilityMissing":
     "agent \"{{agent}}\" 不是沙箱型(defineSandboxAgent 构造),t.{{method}} 这类断言只有沙箱型 agent 可用。换用 defineSandboxAgent 构造的 agent,或去掉这条断言。\n" +
-    "  文档:node_modules/niceeval/docs-site/zh/guides/sandbox-agent.mdx",
+    "  文档:node_modules/niceeval/docs-site/zh/how-to/sandbox-agent.mdx",
   "context.skipEmpty": "skip() 需要一个非空理由。",
   "context.turnFailed": "本轮 send 返回 failed(turn status = failed):{{message}}",
   "context.turnFailedDefault": "本轮 send 返回 failed(turn status = failed)",
@@ -162,7 +163,7 @@ export const zhCN = {
   "feedback.human.compare": "Compare: niceeval view {{group}}",
   "feedback.human.counts": "共 {{total}} · 复用 {{reused}} · 运行中 {{running}} · 排队 {{queued}} · 已完成 {{completed}}",
   "feedback.human.diffHint": "Diff:    niceeval show {{locator}} --diff",
-  "feedback.human.evalHint": "Eval:    niceeval show {{locator}} --eval",
+  "feedback.human.evalHint": "Eval:    niceeval show {{locator}} --source",
   "feedback.human.failuresHeader": "FAILURES",
   "feedback.human.heartbeat": "已运行 {{elapsed}} · {{counts}}",
   "feedback.human.inspect": "Inspect: niceeval show {{locator}}",
@@ -269,7 +270,7 @@ export const zhCN = {
   "sandbox.providerNotImplemented": "{{provider}} sandbox provider not implemented; use docker, vercel, or e2b",
   "sandbox.missingSpec":
     "沙箱型 agent 需要一个 sandbox,但没有提供。niceeval 不再自动选默认 provider——请在 defineExperiment()/defineConfig() 里把 sandbox 设成 dockerSandbox() / vercelSandbox() / e2bSandbox()(从 \"niceeval/sandbox\" 导入)。\n" +
-    "  文档:node_modules/niceeval/docs-site/zh/guides/sandbox-providers.mdx",
+    "  文档:node_modules/niceeval/docs-site/zh/how-to/sandbox-providers.mdx",
   "sandbox.dependencyMissing.docker": "Docker sandbox requires 'dockerode'. Install it with: pnpm add dockerode @types/dockerode",
   "sandbox.dependencyMissing.e2b": "E2B sandbox requires 'e2b'. Install it with: pnpm add e2b",
   "sandbox.dependencyMissing.vercel": "Vercel sandbox requires '@vercel/sandbox'. Install it with: pnpm add @vercel/sandbox",