niceeval 0.4.6 → 0.5.0

package/src/cli.ts

@@ -1,5 +1,6 @@
 // niceeval CLI 入口。执行 eval 必须以 experiment 为单位;位置参数只在 exp 后筛 eval id 前缀。
 //   niceeval exp [组|配置] [pattern]  跑实验
+//   niceeval show [pattern]          终端读结果:榜单 / 单 eval / 证据切面 / 时间轴 / --report
 //   niceeval list                    只列出发现到的 eval
 //   niceeval clean                   删除 .niceeval/ 历史运行工件
 
@@ -19,15 +20,27 @@ import { Console as ConsoleReporter } from "./runner/reporters/console.ts";
 import { JUnit } from "./runner/reporters/json.ts";
 import { Live as LiveReporter, type LiveRow } from "./runner/reporters/live.ts";
 import { Artifacts as ArtifactsReporter } from "./runner/reporters/artifacts.ts";
-import { buildView, startViewServer, loadLatestResultsPerEval, IncompatibleResultsError } from "./view/index.ts";
+import {
+  buildView,
+  startViewServer,
+  loadLatestResultsPerEval,
+  resolveViewInput,
+  IncompatibleResultsError,
+  ViewInputError,
+} from "./view/index.ts";
+import { ReportLoadError } from "./report/load.ts";
+import { runShow } from "./show/index.ts";
 import { t } from "./i18n/index.ts";
 import { formatThrown, upsertManagedBlock } from "./util.ts";
 import type { Config, DiscoveredExperiment, Reporter } from "./types.ts";
 
-/** `niceeval view <summary.json>` 指向版本不同的报告时:打印 npx 提示后退出,不抛堆栈。 */
-function exitOnIncompatibleResults(e: unknown): never {
-  if (e instanceof IncompatibleResultsError) {
-    process.stderr.write(e.message);
+/**
+ * view 的可预期用户错误:版本不同的报告(npx 提示)、位置参数/组合语义错误、
+ * --report 装载失败。打一句直说问题与下一步后退出,不抛堆栈。
+ */
+function exitOnViewUserError(e: unknown): never {
+  if (e instanceof IncompatibleResultsError || e instanceof ViewInputError || e instanceof ReportLoadError) {
+    process.stderr.write(e.message.endsWith("\n") ? e.message : `${e.message}\n`);
     process.exit(1);
   }
   throw e;
@@ -51,6 +64,17 @@ interface Flags {
   out?: string;
   port?: number;
   help: boolean;
+  // ── show 专属(位置参数仍是 eval id 前缀;这些 flag 选「怎么看」)──
+  transcript: boolean;
+  trace: boolean;
+  diff: boolean;
+  /** --diff=<路径>(必须 = 连写;空格形式会把路径当 eval id 前缀,按文档如此)。 */
+  diffPath?: string;
+  history: boolean;
+  experiment?: string;
+  attempt?: number;
+  run?: string;
+  report?: string;
 }
 
 // 表驱动的 flag 定义(node:util parseArgs)。--no-x 显式声明,不依赖 allowNegative(需 Node 20.14+,
@@ -72,6 +96,17 @@ const FLAG_OPTIONS = {
   // 免得照旧文档写的脚本直接崩;真正实现前不接任何行为。
   watch: { type: "boolean" },
   json: { type: "boolean" },
+  // show 的证据切面 / 时间轴 / 报告装载(docs-site/zh/guides/viewing-results.mdx)。
+  transcript: { type: "boolean" },
+  trace: { type: "boolean" },
+  // --diff 是布尔;--diff=<路径> 在 parseArgs 前预扫成 diffPath(路径必须 = 连写,
+  // 空格形式的下一个 token 仍是位置参数 = eval id 前缀,与文档一致)。
+  diff: { type: "boolean" },
+  history: { type: "boolean" },
+  experiment: { type: "string" },
+  attempt: { type: "string" },
+  run: { type: "string" },
+  report: { type: "string" },
   dry: { type: "boolean" },
   quiet: { type: "boolean" },
   force: { type: "boolean" },
@@ -96,6 +131,17 @@ function numberFlag(name: string, raw: string | undefined): number | undefined {
 function parseArgs(argv: string[]): { command: string; positionals: string[]; flags: Flags } {
   if (argv[0] === "--") argv = argv.slice(1);
 
+  // --diff=<路径> 预扫:diff 本体是布尔(裸 --diff = 文件级摘要),路径只接受 = 连写。
+  let diffPath: string | undefined;
+  argv = argv.map((arg) => {
+    if (arg.startsWith("--diff=")) {
+      const path = arg.slice("--diff=".length);
+      if (path) diffPath = path;
+      return "--diff";
+    }
+    return arg;
+  });
+
   let values: Record<string, string | boolean | undefined>;
   let rawPositionals: string[];
   try {
@@ -113,7 +159,7 @@ function parseArgs(argv: string[]): { command: string; positionals: string[]; fl
   }
 
   // 第一个位置参数若是已知命令,则为命令;其余是 eval id 前缀 / view 输入。
-  const commands = new Set(["exp", "list", "view", "clean", "init", "watch", "run"]);
+  const commands = new Set(["exp", "show", "list", "view", "clean", "init", "watch", "run"]);
   let command = "run";
   let positionals = rawPositionals;
   if (rawPositionals[0] && commands.has(rawPositionals[0])) {
@@ -139,6 +185,15 @@ function parseArgs(argv: string[]): { command: string; positionals: string[]; fl
     earlyExit: values["no-early-exit"] === true ? false : values["early-exit"] === true ? true : undefined,
     open: values["no-open"] === true ? false : values.open === true ? true : undefined,
     help: values.help === true,
+    transcript: values.transcript === true,
+    trace: values.trace === true,
+    diff: values.diff === true && diffPath === undefined,
+    diffPath,
+    history: values.history === true,
+    experiment: values.experiment as string | undefined,
+    attempt: numberFlag("attempt", values.attempt as string | undefined),
+    run: values.run as string | undefined,
+    report: values.report as string | undefined,
   };
   return { command, positionals, flags };
 }
@@ -185,16 +240,20 @@ async function loadConfig(cwd: string): Promise<Config> {
 }
 
 // AGENTS.md 托管区块:告诉在这个项目里干活的 coding agent「niceeval 不在你的训练数据里,
-// 先读随包文档,跑完读结构化结果」。init 时写入/刷新;标记之外的用户内容永不触碰。
+// 先读随包文档,跑完读结构化结果」。随包只发中文准绳版文档(英文站是手工同步、可能滞后,
+// 不进包,见 package.json 的 files);init 时写入/刷新;标记之外的用户内容永不触碰。
 const AGENT_RULES_BEGIN = "<!-- BEGIN:niceeval-agent-rules -->";
 const AGENT_RULES_END = "<!-- END:niceeval-agent-rules -->";
 const AGENT_RULES_CONTENT = [
   "# niceeval is NOT in your training data",
   "",
   "Its APIs and conventions may differ from anything you have seen. Read the relevant",
-  "guide in `node_modules/niceeval/docs-site/` (English at the top level, Chinese under",
-  "`zh/`) before writing any eval, experiment, adapter, or niceeval config. After a run,",
-  "read the `summary.json` path the CLI prints for structured results.",
+  "guide in `node_modules/niceeval/docs-site/zh/` before writing any eval, experiment,",
+  "adapter, or niceeval config. The bundled docs are Chinese-only — that is the single",
+  "authoritative, always-current version; read it regardless of your working language.",
+  "After a run, drill into failures with `niceeval show <eval id>` (add `--transcript` /",
+  "`--trace` / `--diff` for evidence); the `summary.json` path the CLI prints and the",
+  "artifact files it references are the structured source of truth.",
 ].join("\n");
 
 async function initProject(cwd: string): Promise<void> {
@@ -265,12 +324,27 @@ async function main(): Promise<void> {
   }
 
   if (command === "view") {
+    // 位置参数 = eval id 前缀(收窄报告槽选集);存在的文件路径 = 单文件模式;
+    // 结果目录经 --run 递入;--report 整槽替换报告槽(与 show --report 吃同一个文件)。
+    let viewInput: { input?: string; patterns: string[] };
+    try {
+      viewInput = resolveViewInput(cwd, positionals, flags.run);
+    } catch (e) {
+      exitOnViewUserError(e);
+    }
+    const scan = {
+      patterns: viewInput.patterns,
+      ...(flags.experiment !== undefined ? { experiment: flags.experiment } : {}),
+      ...(flags.report !== undefined ? { report: { path: flags.report, cwd } } : {}),
+    };
     if (flags.out) {
-      const out = await buildView({ input: positionals[0], out: flags.out }).catch(exitOnIncompatibleResults);
+      const out = await buildView({ input: viewInput.input, out: flags.out, scan }).catch(exitOnViewUserError);
       process.stdout.write(t("cli.view.exportedDir", { out }));
       process.exit(0);
     }
-    const server = await startViewServer({ input: positionals[0], port: flags.port }).catch(exitOnIncompatibleResults);
+    const server = await startViewServer({ input: viewInput.input, port: flags.port, scan }).catch(
+      exitOnViewUserError,
+    );
     process.stdout.write(t("cli.view.url", { url: server.url }));
     if (flags.open !== false) {
       const opened = await openBrowser(server.url);
@@ -280,6 +354,22 @@ async function main(): Promise<void> {
     await new Promise(() => {});
   }
 
+  if (command === "show") {
+    // show 不依赖 niceeval.config.ts:读的是 .niceeval/(或 --run 指定目录)的落盘结果。
+    const code = await runShow(cwd, positionals, {
+      transcript: flags.transcript,
+      trace: flags.trace,
+      diff: flags.diff,
+      diffPath: flags.diffPath,
+      history: flags.history,
+      experiment: flags.experiment,
+      attempt: flags.attempt,
+      run: flags.run,
+      report: flags.report,
+    });
+    process.exit(code);
+  }
+
   if (command === "clean") {
     await rm(join(cwd, ".niceeval"), { recursive: true, force: true });
     process.stdout.write(t("cli.clean.done"));
@@ -333,7 +423,7 @@ async function main(): Promise<void> {
         agent: exp.agent,
         model: exp.model,
         reasoningEffort: exp.reasoningEffort,
-        flags: exp.flags ?? {},
+        params: exp.params ?? {},
         runs: flags.runs ?? envNumber("NICEEVAL_RUNS") ?? exp.runs ?? 1,
         earlyExit: flags.earlyExit ?? exp.earlyExit ?? true,
         sandbox: exp.sandbox ?? config.sandbox,
@@ -349,7 +439,7 @@ async function main(): Promise<void> {
     }
   } else {
     // 裸 run / `niceeval <eval>` 不再执行。运行配置必须来自 experiments/,
-    // 这样 agent/model/flags/runs/budget 与结果聚合都有可签入的身份。
+    // 这样 agent/model/params/runs/budget 与结果聚合都有可签入的身份。
     const experiments = await discoverExperiments(cwd);
     const asExp = experiments.filter((e) =>
       positionals.some((p) => e.group === p || e.id === p || e.id.startsWith(p + "/")),

package/src/context/context.test.ts

@@ -57,7 +57,7 @@ function makeContext(agent: Agent, sandbox = fakeSandbox(), evalBaseDir?: string
   return createEvalContext({
     agent,
     sandbox,
-    flags: {},
+    params: {},
     signal: new AbortController().signal,
     log: () => {},
     judge: undefined,

package/src/context/context.ts

@@ -61,7 +61,7 @@ export interface ContextDeps {
   sandbox: Sandbox;
   model?: string;
   reasoningEffort?: string;
-  flags: Record<string, unknown>;
+  params: Record<string, unknown>;
   signal: AbortSignal;
   log(msg: string): void;
   judge: JudgeConfig | undefined;
@@ -92,7 +92,7 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
     sandbox: deps.sandbox,
     model: deps.model,
     reasoningEffort: deps.reasoningEffort,
-    flags: deps.flags,
+    params: deps.params,
     signal: deps.signal,
     log: deps.log,
     telemetry: deps.telemetry,
@@ -284,7 +284,7 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
     signal: deps.signal,
     model: deps.model,
     reasoningEffort: deps.reasoningEffort,
-    flags: deps.flags,
+    params: deps.params,
     log: deps.log,
     skip: (reason: string) => {
       if (reason.trim().length === 0) throw new Error(t("context.skipEmpty"));

package/src/context/session.ts

@@ -88,7 +88,7 @@ export interface SessionDeps {
   sandbox: Sandbox;
   model?: string;
   reasoningEffort?: string;
-  flags: Record<string, unknown>;
+  params: Record<string, unknown>;
   signal: AbortSignal;
   log(msg: string): void;
   /** tracing agent 的 OTLP 端点(经 send ctx 透给 adapter,用于注入导出 env)。 */
@@ -138,7 +138,7 @@ export class SessionManager {
       signal: this.deps.signal,
       model: this.deps.model,
       reasoningEffort: this.deps.reasoningEffort,
-      flags: this.deps.flags,
+      params: this.deps.params,
       sandbox: this.deps.sandbox,
       session,
       telemetry: this.deps.telemetry,

package/src/context/types.ts

@@ -274,8 +274,8 @@ export interface TestContext {
   readonly model?: string;
   /** 本次 attempt 的推理努力程度(如 "low"/"medium"/"high",取值由 adapter/模型决定)。 */
   readonly reasoningEffort?: string;
-  /** 本次 attempt 生效的 flags(experiment.flags 与 CLI flag 合并后的只读视图)。 */
-  readonly flags: Readonly<Record<string, unknown>>;
+  /** 本次 attempt 生效的 params(experiment.params 与 CLI flag 合并后的只读视图)。 */
+  readonly params: Readonly<Record<string, unknown>>;
   /** 打一行调试日志;有 live 进度回调时走该回调,否则落到 stderr,不出现在最终结果里。 */
   log(msg: string): void;
   /** 立即中止本 eval 并标记为 skipped(outcome / EvalResult.skipReason),reason 不能为空。 */

package/src/i18n/en.ts

@@ -20,7 +20,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/quickstart.mdx",
+    "  Docs: node_modules/niceeval/docs-site/zh/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)",
@@ -31,7 +31,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/guides/scoring-guide.mdx",
+    "  Docs: node_modules/niceeval/docs-site/zh/guides/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",
@@ -40,8 +40,18 @@ export const en = {
     "niceeval — agent-native evals\n\n" +
     "Usage:\n" +
     "  niceeval exp [group|experiment] [eval-id-prefix…]   run experiments\n" +
+    "  niceeval show [eval-id-prefix…]                     read results in the terminal\n" +
+    "      bare: current verdicts per experiment (composed across runs);\n" +
+    "      a single eval id: attempts + assertion details\n" +
+    "      --transcript / --trace / --diff[=file]   evidence slices of one eval\n" +
+    "      --history   cross-run timeline (mutually exclusive with --report)\n" +
+    "      --run <dir>   pin a results dir    --experiment <id>   one experiment\n" +
+    "      --attempt <n>   pick an attempt    --report <file>   custom report\n" +
     "  niceeval list                                       list discovered evals\n" +
-    "  niceeval view [summary.json|dir] [--out dir] [--port n] [--no-open]\n" +
+    "  niceeval view [eval-id-prefix…|summary.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" +
     "      --out <dir> exports a static site: index.html plus the viewer\n" +
     "      artifacts, ready for any static host\n" +
     "  niceeval clean                                      delete .niceeval/ artifacts\n" +
@@ -53,6 +63,17 @@ export const en = {
     "Positional args only select which evals to run (id prefixes); which agent and\n" +
     "how to run come from experiments/ + flags. Env overrides (flag > env > config):\n" +
     "  NICEEVAL_RUNS  NICEEVAL_MAX_CONCURRENCY  NICEEVAL_TIMEOUT  NICEEVAL_BUDGET\n",
+  "cli.show.noResults": "No results found under {{root}}. Run `niceeval exp` first, then `niceeval show`.\n",
+  "cli.show.runDirMissing": "Results directory not found: {{dir}}\n",
+  "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",
+  "cli.show.evidenceNeedsEval":
+    "--transcript / --trace / --diff show one eval's evidence, but the selection matched {{matched}} evals. Narrow to a single eval id first: niceeval show <eval id> --transcript\n",
+  "cli.show.attemptNeedsEval":
+    "--attempt picks one attempt of a single eval; pass a full eval id (and --experiment when several experiments ran it).\n",
+  "cli.show.attemptNotFound": "Attempt {{attempt}} not found for {{evalId}}. Available attempts: {{available}}\n",
   "cli.eval.noMatch": "No eval matched: {{patterns}}.\n",
   "cli.eval.noMatchHintExperiment": "Hint: \"{{pattern}}\" is an experiment{{kind}}; you probably meant: niceeval exp {{pattern}}\n",
   "cli.eval.noMatchKnown": "Discovered {{count}} evals: {{evals}}\n",
@@ -61,7 +82,7 @@ export const en = {
   "cli.experimentGroup": " group",
   "cli.fallbackCleanupTimeout": "\ngraceful cleanup timed out; force-cleaning sandboxes...\n",
   "cli.forceCleanupExit": "\nForce-cleaning sandboxes and exiting...\n",
-  "cli.init.done": "Ready: evals/, niceeval.config.ts, and the niceeval agent-rules block in AGENTS.md (points coding agents at node_modules/niceeval/docs-site).\n",
+  "cli.init.done": "Ready: evals/, niceeval.config.ts, and the niceeval agent-rules block in AGENTS.md (points coding agents at node_modules/niceeval/docs-site/zh).\n",
   "cli.interruptCleanup": "\nInterrupted; cleaning up sandbox containers... (press again to force cleanup and exit)\n",
   "cli.list.header": "Discovered {{count}} evals:\n",
   "cli.noAgent": "No agent specified (use --agent <name>).\n",
@@ -70,17 +91,18 @@ export const en = {
   "cli.resultsPath": "Structured results: {{path}} (each result's artifactsDir holds that attempt's 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/guides/write-experiment.mdx\n",
+    "  Docs: node_modules/niceeval/docs-site/zh/guides/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.sandboxFlagRemoved": "`--sandbox` is not a CLI flag. Set `sandbox` in the experiment (or `niceeval.config.ts` as a project-wide fallback) to dockerSandbox() / vercelSandbox() / e2bSandbox() (import from \"niceeval/sandbox\").\n",
   "cli.unimplemented": "Command \"{{command}}\" is not implemented yet (MVP).\n",
   "cli.view.exportedDir": "Exported static report site: {{out}} (serve the whole directory with any static host; opening index.html via file:// cannot fetch artifacts)\n",
   "cli.view.incompatible": "{{dir}}: written by niceeval {{producer}} (schemaVersion {{schemaVersion}}); this CLI reads schemaVersion {{supported}}.\nRun `{{command}}` to view it.\n",
+  "cli.view.incompatibleForeign": "{{dir}}: written by {{name}} {{version}} (schemaVersion {{schemaVersion}}); this CLI reads schemaVersion {{supported}}.\nOpen this report with the tool that produced it.\n",
   "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/guides/sandbox-agent.mdx",
+    "  Docs: node_modules/niceeval/docs-site/zh/guides/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)",
@@ -172,7 +194,7 @@ export const en = {
   "sandbox.backendNotImplemented": "{{backend}} sandbox backend 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/guides/sandbox-backends.mdx",
+    "  Docs: node_modules/niceeval/docs-site/zh/guides/sandbox-backends.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

@@ -38,8 +38,17 @@ export const zhCN = {
     "niceeval — agent-native evals\n\n" +
     "用法:\n" +
     "  niceeval exp [组|实验] [eval-id 前缀…]   跑实验\n" +
+    "  niceeval show [eval-id 前缀…]            终端读结果\n" +
+    "      裸跑:每个 experiment 的现刻判决(跨 run 合成)\n" +
+    "      单个 eval id:attempt 与断言明细\n" +
+    "      --transcript / --trace / --diff[=文件]   单 eval 的证据切面\n" +
+    "      --history   跨 run 时间轴(与 --report 互斥)\n" +
+    "      --run <目录> 钉死结果目录   --experiment <id> 只看该实验\n" +
+    "      --attempt <n> 指定 attempt   --report <文件> 自定义报告\n" +
     "  niceeval list                            列出发现到的 eval\n" +
-    "  niceeval view [summary.json|目录] [--out 目录] [--port n] [--no-open]\n" +
+    "  niceeval view [eval-id 前缀…|summary.json] [--out 目录] [--port n] [--no-open]\n" +
+    "      报告槽 + 证据室;--report <文件> 整槽换成自定义报告(与 show 同一文件)\n" +
+    "      --run <目录> 钉死结果目录   --experiment <id> 只看该实验\n" +
     "      --out <目录> 静态导出:index.html 连同查看器工件,可直接静态托管\n" +
     "  niceeval clean                           删除 .niceeval/ 历史工件\n" +
     "  niceeval init                            脚手架 config + evals/\n\n" +
@@ -50,6 +59,18 @@ export const zhCN = {
     "位置参数只选「跑哪些 eval」(id 前缀);对着哪个 agent、怎么跑来自 experiments/ 与\n" +
     "标志。环境变量覆盖(标志 > 环境变量 > config):\n" +
     "  NICEEVAL_RUNS  NICEEVAL_MAX_CONCURRENCY  NICEEVAL_TIMEOUT  NICEEVAL_BUDGET\n",
+  // show 的错误文案保持英文(错误文案英文的仓库约定);noResults 是提示,翻译。
+  "cli.show.noResults": "{{root}} 下没有结果。先 `niceeval exp` 跑一轮,再 `niceeval show`。\n",
+  "cli.show.runDirMissing": "Results directory not found: {{dir}}\n",
+  "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",
+  "cli.show.evidenceNeedsEval":
+    "--transcript / --trace / --diff show one eval's evidence, but the selection matched {{matched}} evals. Narrow to a single eval id first: niceeval show <eval id> --transcript\n",
+  "cli.show.attemptNeedsEval":
+    "--attempt picks one attempt of a single eval; pass a full eval id (and --experiment when several experiments ran it).\n",
+  "cli.show.attemptNotFound": "Attempt {{attempt}} not found for {{evalId}}. Available attempts: {{available}}\n",
   "cli.eval.noMatch": "没有匹配的 eval:{{patterns}}。\n",
   "cli.eval.noMatchHintExperiment": "提示:\"{{pattern}}\" 是实验{{kind}},你大概想跑:niceeval exp {{pattern}}\n",
   "cli.eval.noMatchKnown": "已发现 {{count}} 个 eval:{{evals}}\n",
@@ -58,7 +79,7 @@ export const zhCN = {
   "cli.experimentGroup": "组",
   "cli.fallbackCleanupTimeout": "\ngraceful 清理超时,强制清理沙箱…\n",
   "cli.forceCleanupExit": "\n强制清理沙箱并退出…\n",
-  "cli.init.done": "已就绪:evals/、niceeval.config.ts,以及 AGENTS.md 里的 niceeval agent 指引区块(指向 node_modules/niceeval/docs-site)。\n",
+  "cli.init.done": "已就绪:evals/、niceeval.config.ts,以及 AGENTS.md 里的 niceeval agent 指引区块(指向 node_modules/niceeval/docs-site/zh)。\n",
   "cli.interruptCleanup": "\n收到中断,正在清理沙箱容器…(再按一次强制清理并退出)\n",
   "cli.list.header": "发现 {{count}} 个 eval:\n",
   "cli.noAgent": "未指定 agent(用 --agent <name>)。\n",
@@ -74,6 +95,7 @@ export const zhCN = {
   "cli.unimplemented": "命令 \"{{command}}\" 暂未实现(MVP)。\n",
   "cli.view.exportedDir": "已导出静态查看站:{{out}}(整个目录可直接静态托管;本地打开 {{out}}/index.html 需经 http 服务,file:// 下工件 fetch 不可用)\n",
   "cli.view.incompatible": "{{dir}}: 由 niceeval {{producer}} 写入(schemaVersion {{schemaVersion}}),当前 CLI 只读 schemaVersion {{supported}}。\n运行 `{{command}}` 查看这份报告。\n",
+  "cli.view.incompatibleForeign": "{{dir}}: 由 {{name}} {{version}} 写入(schemaVersion {{schemaVersion}}),当前 CLI 只读 schemaVersion {{supported}}。\n请用写出它的那个工具查看这份报告。\n",
   "cli.view.url": "niceeval view: {{url}}\n",
   "context.capabilityMissing":
     "agent \"{{agent}}\" 不是沙箱型(defineSandboxAgent 构造),t.{{method}} 这类断言只有沙箱型 agent 可用。换用 defineSandboxAgent 构造的 agent,或去掉这条断言。\n" +

package/src/report/aggregate.ts

@@ -4,75 +4,77 @@
 // 和重试策略纠缠在一起(eval A=[1]、eval B=[0,0,0] 平铺 = 0.25,两级宏平均 = 0.5)。
 // 自定义维度把同一道题的 attempt 分进不同组时,第一级折叠发生在各组内部。
 
-import type { EvalResult } from "../types.ts";
-import type { AttemptHandle, SnapshotHandle } from "../results/types.ts";
+import {
+  dedupeAttempts,
+  type AttemptHandle,
+  type Selection,
+  type SelectionWarning,
+  type Snapshot,
+} from "../results/index.ts";
 import type {
   Aggregator,
   AttemptRef,
-  Dimension,
+  DimensionInput,
   Metric,
   MetricCell,
   MetricColumn,
+  ParamRef,
 } from "./types.ts";
 import { formatMetricValue } from "./format.ts";
 
 // 复合键分隔符:NUL 不会出现在 eval id / experimentId / ISO 时间里,拼接键不会串味
 const KEY_SEP = "\u0000";
 
+/** param 未声明时的组名:不猜,如实归一组。 */
+export const PARAM_UNSET = "(unset)";
+
+/** 计算函数的第一参:选集(warnings 随行)或手工挑的快照数组(没有挑选过程,自然无警告)。 */
+export type SnapshotsInput = Selection | Snapshot[];
+
+export function resolveInput(input: SnapshotsInput): {
+  snapshots: Snapshot[];
+  warnings: SelectionWarning[];
+} {
+  if (Array.isArray(input)) return { snapshots: input, warnings: [] };
+  return { snapshots: input.snapshots, warnings: input.warnings };
+}
+
 /** 展平后的一条样本:attempt + 它所属的快照(维度解析与题级折叠都需要快照身份)。 */
 export interface Item {
-  snapshot: SnapshotHandle;
+  snapshot: Snapshot;
   attempt: AttemptHandle;
 }
 
 export function experimentIdOf(item: Item): string {
-  return item.attempt.result.experimentId ?? item.snapshot.experimentId;
+  return item.attempt.experimentId || item.snapshot.experimentId;
 }
 
-/** 快照身份:与 view Compare 同口径的 (experimentId, startedAt)。 */
-function snapshotIdentity(snapshot: SnapshotHandle): string {
-  return `${snapshot.experimentId}${KEY_SEP}${snapshot.startedAt}`;
+export function evalIdOf(item: Item): string {
+  return item.attempt.evalId || item.attempt.result.id;
 }
 
-/** 身份键 (experimentId, evalId, attempt, startedAt);startedAt 缺失 → null(宁可不去重也不误删)。 */
-function identityKey(snapshot: SnapshotHandle, result: EvalResult): string | null {
-  if (!result.startedAt) return null;
-  return [
-    result.experimentId ?? snapshot.experimentId,
-    result.id,
-    result.attempt,
-    result.startedAt,
-  ].join(KEY_SEP);
+/** 快照键:与 view Compare 同口径的 "<experimentId> @ <startedAt>"。 */
+export function snapshotKeyOf(snapshot: Snapshot): string {
+  return `${snapshot.experimentId} @ ${snapshot.startedAt}`;
 }
 
 /**
- * 跨快照聚合前按身份键去重:--resume 会把上一轮已通过的结果原样合入新 run 的 summary,
- * 同一 attempt 因此存在于多份落盘。重复时保留最新 run(按 run.summary.startedAt)里的那份。
- *
- * TODO(results-lib):这是「去重是消费方义务」的本地实现(docs/results-lib.md「身份键与去重」);
- * writer 给合入结果打标之后,按 niceeval/results 的规则收编,本函数随 handles.ts 一起换掉。
+ * 展平 + 聚合前去重(niceeval/results 的 dedupeAttempts,身份键
+ * (experimentId, evalId, attempt, startedAt))。missing-startedAt 的警告不透出:
+ * 官方产出永不缺 startedAt,缺失只可能来自 legacy 落盘,「不去重、如实保留重复」即终稿。
  */
-export function dedupeAttempts(snapshots: SnapshotHandle[]): Item[] {
-  // 第一遍:按身份键选赢家(run.startedAt 是 ISO 字符串,字典序即时间序;并列保留后出现的)。
-  const winner = new Map<string, { attempt: AttemptHandle; runStartedAt: string }>();
+export function collectItems(snapshots: Snapshot[]): Item[] {
+  const snapshotByAttempt = new Map<AttemptHandle, Snapshot>();
+  const flattened: AttemptHandle[] = [];
   for (const snapshot of snapshots) {
     for (const attempt of snapshot.attempts) {
-      const key = identityKey(snapshot, attempt.result);
-      if (key === null) continue;
-      const runStartedAt = snapshot.run.summary.startedAt ?? "";
-      const prev = winner.get(key);
-      if (!prev || runStartedAt >= prev.runStartedAt) winner.set(key, { attempt, runStartedAt });
+      // 同一 handle 对象出现在两个快照里时以首次归属为准(手工挑重叠快照的极端场景)
+      if (!snapshotByAttempt.has(attempt)) snapshotByAttempt.set(attempt, snapshot);
+      flattened.push(attempt);
     }
   }
-  // 第二遍:按原始遍历顺序输出,只放行赢家;无 startedAt 的一律放行(不去重)。
-  const items: Item[] = [];
-  for (const snapshot of snapshots) {
-    for (const attempt of snapshot.attempts) {
-      const key = identityKey(snapshot, attempt.result);
-      if (key === null || winner.get(key)?.attempt === attempt) items.push({ snapshot, attempt });
-    }
-  }
-  return items;
+  const { attempts } = dedupeAttempts(flattened);
+  return attempts.map((attempt) => ({ attempt, snapshot: snapshotByAttempt.get(attempt)! }));
 }
 
 /**
@@ -88,12 +90,12 @@ export function evalPrefixPredicate(evals?: string | string[]): (id: string) =>
 export function filterItems(items: Item[], evals?: string | string[]): Item[] {
   if (evals === undefined) return items;
   const match = evalPrefixPredicate(evals);
-  return items.filter((item) => match(item.attempt.result.id));
+  return items.filter((item) => match(evalIdOf(item)));
 }
 
 // ───────────────────────── 维度 ─────────────────────────
 
-export function dimensionName(dimension: Dimension): string {
+export function dimensionName(dimension: DimensionInput): string {
   return typeof dimension === "string" ? dimension : dimension.name;
 }
 
@@ -103,8 +105,35 @@ export function evalGroupOf(id: string): string {
   return slash === -1 ? id : id.slice(0, slash);
 }
 
-export function dimensionKey(dimension: Dimension, item: Item): string {
-  if (typeof dimension !== "string") return dimension.of(item.attempt);
+function isParamRef(dimension: DimensionInput): dimension is ParamRef {
+  return typeof dimension === "object" && "kind" in dimension && dimension.kind === "param";
+}
+
+/** experiment 声明的 params(经 runner 原样透传进持久化字段 ExperimentRunInfo.params)。 */
+function paramsOf(attempt: AttemptHandle): Record<string, unknown> | undefined {
+  return attempt.result.experiment?.params;
+}
+
+/** param 声明值 → 组标签:label 函数优先,其余 String();未声明 → PARAM_UNSET。 */
+export function paramGroupKey(ref: ParamRef, item: Item): string {
+  const value = paramsOf(item.attempt)?.[ref.name];
+  if (value === undefined) return PARAM_UNSET;
+  // 持久化字段是 Record<string, unknown>;声明侧的合法值就是这三种标量
+  if (typeof ref.label === "function") return ref.label(value as string | number | boolean);
+  return String(value);
+}
+
+/** param 作轴:要求数值;未声明或非数值 → null(点不画,注脚报数)。 */
+export function paramAxisValue(ref: ParamRef, item: Item): number | null {
+  const value = paramsOf(item.attempt)?.[ref.name];
+  return typeof value === "number" ? value : null;
+}
+
+export function dimensionKey(dimension: DimensionInput, item: Item): string {
+  if (typeof dimension !== "string") {
+    if (isParamRef(dimension)) return paramGroupKey(dimension, item);
+    return dimension.of(item.attempt);
+  }
   const result = item.attempt.result;
   switch (dimension) {
     case "agent":
@@ -114,11 +143,11 @@ export function dimensionKey(dimension: Dimension, item: Item): string {
     case "experiment":
       return experimentIdOf(item);
     case "eval":
-      return result.id;
+      return evalIdOf(item);
     case "evalGroup":
-      return evalGroupOf(result.id);
+      return evalGroupOf(evalIdOf(item));
     case "snapshot":
-      return `${item.snapshot.experimentId} @ ${item.snapshot.startedAt}`;
+      return snapshotKeyOf(item.snapshot);
     default: {
       // 穷尽检查:新增内置维度而漏改这里时编译期报错
       const exhausted: never = dimension;
@@ -128,7 +157,7 @@ export function dimensionKey(dimension: Dimension, item: Item): string {
 }
 
 /** 按维度分组,保持首次出现顺序(无 sort 时表格行序即此序)。 */
-export function groupItems(items: Item[], dimension: Dimension): Map<string, Item[]> {
+export function groupItems(items: Item[], dimension: DimensionInput): Map<string, Item[]> {
   const groups = new Map<string, Item[]>();
   for (const item of items) {
     const key = dimensionKey(dimension, item);
@@ -180,8 +209,8 @@ export async function computeCell(metric: Metric, items: Item[]): Promise<Metric
     const value = await evaluateMetric(metric, item.attempt);
     if (value === null) continue;
     samples += 1;
-    refs.push(item.attempt.ref); // 证据引用由 niceeval/results 的句柄直供,不反查下标
-    const bucketKey = `${item.attempt.result.id}${KEY_SEP}${snapshotIdentity(item.snapshot)}`;
+    refs.push(item.attempt.ref); // 证据引用由句柄直供,不反查下标
+    const bucketKey = `${evalIdOf(item)}${KEY_SEP}${snapshotKeyOf(item.snapshot)}`;
     const bucket = buckets.get(bucketKey);
     if (bucket) bucket.push(value);
     else buckets.set(bucketKey, [value]);
@@ -202,7 +231,7 @@ export function toColumn(metric: Metric): MetricColumn {
   };
 }
 
-export function assertUniqueMetricNames(metrics: Metric[], where: string): void {
+export function assertUniqueMetricNames(metrics: readonly Metric[], where: string): void {
   const seen = new Set<string>();
   for (const metric of metrics) {
     if (seen.has(metric.name)) {