niceeval 0.5.4 → 0.6.0

package/src/view/app/components/SkippedRunsBanner.tsx

@@ -0,0 +1,140 @@
+import { useState } from "react";
+import { AlertCircle, ChevronRight, Copy, Check } from "lucide-react";
+import type { T } from "../shared.ts";
+import type { MessageKey } from "../i18n.ts";
+import type { SkippedRunNotice } from "../types.ts";
+import { copyText } from "./CopyControls.tsx";
+
+// 折叠前默认可见的条目数(跨分组累计);超出的部分收进「展开其余」。
+const DEFAULT_VISIBLE = 3;
+
+type GroupKind = "incompatible" | "incompatibleForeign" | "malformed" | "incomplete";
+
+interface SkippedGroup {
+  key: string;
+  kind: GroupKind;
+  messageKey: MessageKey;
+  vars: Record<string, string | number>;
+  items: SkippedRunNotice[];
+}
+
+/** 同一原因(且描述文案完全相同)的失败 run 归成一组,组内条目只保留目录名 + 命令,
+ *  避免把完整原因句子重复 N 遍——这正是原实现把首屏挤满的根因。 */
+function groupSkippedRuns(runs: SkippedRunNotice[]): SkippedGroup[] {
+  const groups = new Map<string, SkippedGroup>();
+  for (const run of runs) {
+    let kind: GroupKind;
+    let key: string;
+    let messageKey: MessageKey;
+    let vars: Record<string, string | number>;
+
+    if (run.reason === "malformed") {
+      kind = "malformed";
+      vars = { detail: run.detail ?? "?" };
+      key = `malformed:${vars.detail}`;
+      messageKey = "banner.skipped.malformed";
+    } else if (run.reason === "incomplete") {
+      kind = "incomplete";
+      vars = {};
+      key = "incomplete";
+      messageKey = "banner.skipped.incomplete";
+    } else if (run.producerName && run.producerName !== "niceeval") {
+      kind = "incompatibleForeign";
+      vars = { name: run.producerName, version: run.producerVersion ?? "?", schemaVersion: run.schemaVersion ?? "?" };
+      key = `foreign:${vars.name}:${vars.version}:${vars.schemaVersion}`;
+      messageKey = "banner.skipped.incompatibleForeign";
+    } else {
+      kind = "incompatible";
+      vars = { producer: run.producerVersion ?? "?", schemaVersion: run.schemaVersion ?? "?" };
+      key = `incompatible:${vars.producer}:${vars.schemaVersion}`;
+      messageKey = "banner.skipped.incompatible";
+    }
+
+    const existing = groups.get(key);
+    if (existing) {
+      existing.items.push(run);
+    } else {
+      groups.set(key, { key, kind, messageKey, vars, items: [run] });
+    }
+  }
+  return [...groups.values()];
+}
+
+function CopyCommandButton({ command, t }: { command: string; t: T }) {
+  const [copied, setCopied] = useState(false);
+  return (
+    <button
+      type="button"
+      className={`ib-copy${copied ? " is-copied" : ""}`}
+      title={t("banner.copyCommand")}
+      onClick={async () => {
+        await copyText(command);
+        setCopied(true);
+        setTimeout(() => setCopied(false), 1200);
+      }}
+    >
+      {copied ? <Check aria-hidden="true" /> : <Copy aria-hidden="true" />}
+    </button>
+  );
+}
+
+export function SkippedRunsBanner({ skippedRuns, t }: { skippedRuns: SkippedRunNotice[]; t: T }) {
+  const [expanded, setExpanded] = useState(false);
+  if (skippedRuns.length === 0) return null;
+
+  const groups = groupSkippedRuns(skippedRuns);
+  const total = skippedRuns.length;
+  let budget = expanded ? total : DEFAULT_VISIBLE;
+  const hiddenCount = expanded ? 0 : Math.max(0, total - DEFAULT_VISIBLE);
+
+  return (
+    <section className="incompatible-banner" role="alert">
+      <div className="ib-head">
+        <AlertCircle className="ib-icon" aria-hidden="true" />
+        <b>{t("banner.skippedTitle", { count: total })}</b>
+      </div>
+      <div className="ib-groups">
+        {groups.map((group) => {
+          const visibleItems = group.items.slice(0, Math.max(0, budget));
+          budget -= visibleItems.length;
+          const hiddenInGroup = group.items.length - visibleItems.length;
+          return (
+            <div className="ib-group" key={group.key}>
+              <div className="ib-group-head">
+                <span className="ib-group-count">{group.items.length}</span>
+                <span className="ib-group-desc">{t(group.messageKey, group.vars)}</span>
+              </div>
+              {visibleItems.length > 0 && (
+                <ul>
+                  {visibleItems.map((item) => (
+                    <li key={item.dir}>
+                      <span className="ib-dir">{item.dir}</span>
+                      {item.command && <CopyCommandButton command={item.command} t={t} />}
+                    </li>
+                  ))}
+                  {hiddenInGroup > 0 && !expanded && (
+                    <li className="ib-more" aria-hidden="true">
+                      +{hiddenInGroup}
+                    </li>
+                  )}
+                </ul>
+              )}
+            </div>
+          );
+        })}
+      </div>
+      {hiddenCount > 0 && (
+        <button type="button" className="ib-toggle" onClick={() => setExpanded(true)}>
+          <ChevronRight aria-hidden="true" />
+          {t("banner.expandRest", { count: hiddenCount })}
+        </button>
+      )}
+      {expanded && total > DEFAULT_VISIBLE && (
+        <button type="button" className="ib-toggle" onClick={() => setExpanded(false)}>
+          <ChevronRight className="is-open" aria-hidden="true" />
+          {t("banner.collapse")}
+        </button>
+      )}
+    </section>
+  );
+}

package/src/view/app/components/ui/badge.tsx

@@ -3,7 +3,7 @@ import { cn } from "../../lib/cn.ts";
 
 /**
  * 状态小标签:边框 + 浅底都取自当前文字色,tone(.good/.bad/.warn/.infra-err)决定颜色。
- * 取代旧的 .modal-outcome / 内联状态 chip。
+ * 取代旧的 .modal-verdict / 内联状态 chip。
  */
 export function Badge({ tone, className, children }: { tone?: string; className?: string; children: ReactNode }) {
   return (

package/src/view/app/components/ui/dialog.tsx

@@ -17,10 +17,10 @@ export function DialogContent({
 }: ComponentPropsWithoutRef<typeof DialogPrimitive.Content>) {
   return (
     <DialogPrimitive.Portal>
-      <DialogPrimitive.Overlay className="fixed inset-0 z-[200] bg-black/50 backdrop-blur-[3px]" />
+      <DialogPrimitive.Overlay className="fixed inset-0 z-[200] bg-black/90" />
       <DialogPrimitive.Content
         className={cn(
-          "fixed left-1/2 top-1/2 z-[200] flex max-h-[min(86vh,820px)] w-[min(960px,calc(100vw-48px))]",
+          "fixed left-1/2 top-1/2 z-[200] flex max-h-[min(86vh,820px)] w-[min(1120px,calc(100vw-48px))]",
           "-translate-x-1/2 -translate-y-1/2 flex-col overflow-hidden rounded-xl border border-line-strong",
           "bg-panel shadow-[0_20px_60px_rgba(0,0,0,0.45)] focus:outline-none",
           className,

package/src/view/app/i18n.ts

@@ -33,9 +33,9 @@ export type MessageKey =
   | "table.successRate"
   | "table.tokens"
   | "table.estCost"
-  | "table.outcomes"
+  | "table.verdicts"
   | "table.evalId"
-  | "table.outcome"
+  | "table.verdict"
   | "table.ranAt"
   | "detail.evalResult"
   | "detail.evalResults"
@@ -104,15 +104,18 @@ export type MessageKey =
   | "assert.fail"
   | "assert.soft"
   | "assert.evidence"
-  | "outcome.passed"
-  | "outcome.failed"
-  | "outcome.errored"
-  | "outcome.skipped"
+  | "verdict.passed"
+  | "verdict.failed"
+  | "verdict.errored"
+  | "verdict.skipped"
   | "banner.skippedTitle"
   | "banner.skipped.incompatible"
   | "banner.skipped.incompatibleForeign"
   | "banner.skipped.malformed"
   | "banner.skipped.incomplete"
+  | "banner.expandRest"
+  | "banner.collapse"
+  | "banner.copyCommand"
   | "banner.warningsTitle"
   | "hero.composedFrom"
   | "chart.costVsScore"
@@ -141,7 +144,7 @@ const dictionaries: Record<Locale, Dictionary> = {
     "section.traces": "Traces",
     "search.experiments": "Filter experiment, agent, model, or eval...",
     "search.runs": "Filter eval ID or experiment...",
-    "empty.summary": "No summary.json files found. Run niceeval or pass niceeval view path/to/summary.json.",
+    "empty.summary": "No snapshots found. Run niceeval or pass niceeval view path/to/snapshot.json.",
     "empty.individualRuns": "No individual runs found.",
     "empty.runsFilter": "No results match the filter.",
     "empty.traces": "No traces available. Traces are collected during eval runs when artifacts are saved.",
@@ -152,9 +155,9 @@ const dictionaries: Record<Locale, Dictionary> = {
     "table.successRate": "Success Rate",
     "table.tokens": "Tokens",
     "table.estCost": "Est. Cost",
-    "table.outcomes": "Outcomes",
+    "table.verdicts": "Verdicts",
     "table.evalId": "Eval ID",
-    "table.outcome": "Outcome",
+    "table.verdict": "Verdict",
     "table.ranAt": "Ran At",
     "detail.evalResult": "eval",
     "detail.evalResults": "evals",
@@ -223,15 +226,18 @@ const dictionaries: Record<Locale, Dictionary> = {
     "assert.fail": "fail",
     "assert.soft": "soft",
     "assert.evidence": "What was checked",
-    "outcome.passed": "passed",
-    "outcome.failed": "failed",
-    "outcome.errored": "errors",
-    "outcome.skipped": "skipped",
-    "banner.skippedTitle": "Some runs could not be loaded and are not shown here:",
-    "banner.skipped.incompatible": "written by niceeval {{producer}} (schemaVersion {{schemaVersion}}) — view it with the command on the right",
-    "banner.skipped.incompatibleForeign": "written by {{name}} {{version}} (schemaVersion {{schemaVersion}}) — this viewer cannot read it; open it with the tool that produced it",
-    "banner.skipped.malformed": "unreadable report ({{detail}}) — it may be corrupted; re-run the eval or delete this run directory",
-    "banner.skipped.incomplete": "the run crashed before writing summary.json — completed attempt artifacts remain on disk for manual inspection; delete the directory if you no longer need them",
+    "verdict.passed": "passed",
+    "verdict.failed": "failed",
+    "verdict.errored": "errors",
+    "verdict.skipped": "skipped",
+    "banner.skippedTitle": "{{count}} run(s) could not be loaded and are not shown here",
+    "banner.skipped.incompatible": "written by niceeval {{producer}} (schemaVersion {{schemaVersion}}) — current version can't read it, expand for the view command",
+    "banner.skipped.incompatibleForeign": "written by {{name}} {{version}} (schemaVersion {{schemaVersion}}) — this viewer cannot read them; open with the tool that produced them",
+    "banner.skipped.malformed": "unreadable report ({{detail}}) — may be corrupted; re-run the eval or delete the run directory",
+    "banner.skipped.incomplete": "snapshot.json was never written (a narrow crash window) — completed attempt artifacts remain on disk for manual inspection; delete the directory if you no longer need them",
+    "banner.expandRest": "Show {{count}} more",
+    "banner.collapse": "Collapse",
+    "banner.copyCommand": "Copy view command",
     "banner.warningsTitle": "Heads-up about the current leaderboard selection:",
     "hero.composedFrom": "Composed from {{count}} run(s)",
     "chart.costVsScore": "Cost vs. Score",
@@ -257,10 +263,10 @@ const dictionaries: Record<Locale, Dictionary> = {
     "section.traces": "追踪",
     "search.experiments": "筛选实验、agent、model 或 eval...",
     "search.runs": "筛选 eval ID 或实验...",
-    "empty.summary": "没有找到 summary.json。请先运行 niceeval，或传入 niceeval view path/to/summary.json。",
+    "empty.summary": "没有找到快照。请先运行 niceeval，或传入 niceeval view path/to/snapshot.json。",
     "empty.individualRuns": "没有单次运行结果。",
     "empty.runsFilter": "没有匹配筛选条件的结果。",
-    "empty.traces": "没有可用追踪。保存工件的 eval run 会收集 traces。",
+    "empty.traces": "没有可用追踪。保存 artifact 的 eval run 会收集 traces。",
     "table.experiment": "实验",
     "table.model": "模型",
     "table.agent": "Agent",
@@ -268,9 +274,9 @@ const dictionaries: Record<Locale, Dictionary> = {
     "table.successRate": "成功率",
     "table.tokens": "Tokens",
     "table.estCost": "预估成本",
-    "table.outcomes": "结果",
+    "table.verdicts": "结果",
     "table.evalId": "Eval ID",
-    "table.outcome": "状态",
+    "table.verdict": "状态",
     "table.ranAt": "运行时间",
     "detail.evalResult": "个 eval",
     "detail.evalResults": "个 eval",
@@ -334,20 +340,23 @@ const dictionaries: Record<Locale, Dictionary> = {
     "code.checks": "检查",
     "code.conversation": "会话",
     "code.noSource": "源码未捕获。此 run 可能早于 source-loc，或源码不可读。重跑此 eval 即可看到代码视图。",
-    "code.sourceUnavailable": "此 run 捕获过源码，但当前部署里缺少它的工件文件。用 `niceeval view --out <目录>` 重新导出（目录模式会带上工件），或在本地 `niceeval view` 查看。",
+    "code.sourceUnavailable": "此 run 捕获过源码，但当前部署里缺少它的 artifact 文件。用 `niceeval view --out <目录>` 重新导出（目录模式会带上 artifact），或在本地 `niceeval view` 查看。",
     "assert.pass": "通过",
     "assert.fail": "失败",
     "assert.soft": "soft",
     "assert.evidence": "实际被检查的内容",
-    "outcome.passed": "通过",
-    "outcome.failed": "失败",
-    "outcome.errored": "错误",
-    "outcome.skipped": "跳过",
-    "banner.skippedTitle": "以下 run 读取失败,此处不展示:",
-    "banner.skipped.incompatible": "由 niceeval {{producer}} 写入(schemaVersion {{schemaVersion}})—— 用右侧命令查看",
+    "verdict.passed": "通过",
+    "verdict.failed": "失败",
+    "verdict.errored": "错误",
+    "verdict.skipped": "跳过",
+    "banner.skippedTitle": "{{count}} 个 run 读取失败,此处不展示",
+    "banner.skipped.incompatible": "由 niceeval {{producer}} 写入(schemaVersion {{schemaVersion}})—— 当前版本读不了,展开查看命令",
     "banner.skipped.incompatibleForeign": "由 {{name}} {{version}} 写入(schemaVersion {{schemaVersion}})—— 当前查看器读不了;请用写出它的工具查看",
-    "banner.skipped.malformed": "报告读不了({{detail}})—— 可能已损坏;重跑该 eval 或删除这个 run 目录",
-    "banner.skipped.incomplete": "该 run 中途崩溃、没写出 summary.json —— 已完成的 attempt 工件仍在盘上供手工排查;不需要就删除该目录",
+    "banner.skipped.malformed": "报告读不了({{detail}})—— 可能已损坏;重跑该 eval 或删除对应 run 目录",
+    "banner.skipped.incomplete": "快照目录已创建但从未写出 snapshot.json(极窄的崩溃窗口)—— 已完成的 attempt artifact 仍在盘上供手工排查;不需要就删除对应目录",
+    "banner.expandRest": "展开其余 {{count}} 个",
+    "banner.collapse": "收起",
+    "banner.copyCommand": "复制查看命令",
     "banner.warningsTitle": "当前榜单挑选的提醒:",
     "hero.composedFrom": "合成自 {{count}} 个 run",
     "chart.costVsScore": "成本 × 通过率",

package/src/view/app/lib/artifact-url.ts

@@ -1,4 +1,4 @@
-// 工件 fetch 的 URL:相对路径 `artifact/<rel>`。
+// artifact fetch 的 URL:相对路径 `artifact/<rel>`。
 // 本地 dev server(server.ts 的 /artifact/ 路由)和目录式静态导出(buildView 拷到 <out>/artifact/)
 // 共用同一布局,前端不需要知道自己被谁托管。相对路径也保证子路径部署(如 host/foo/)不断链。
 export function artifactUrl(rel: string): string {

package/src/view/app/lib/attempt-route.test.ts

@@ -1,46 +1,39 @@
-// #/attempt/<run>/<result> 深链的纯函数单测:解析 / 格式化往返、坏输入、按 attemptRef 定位。
+// #/attempt/@<locator> 深链的纯函数单测:解析 / 格式化往返、坏输入、按 locator 定位。
 
 import { describe, expect, it } from "vitest";
-import { formatAttemptHash, parseAttemptHash, resolveAttemptRef } from "./attempt-route.ts";
-import type { ViewResult, ViewSnapshot } from "../types.ts";
+import { formatAttemptHash, parseAttemptHash, resolveAttemptLocator } from "./attempt-route.ts";
+import type { AttemptLocator, ViewResult, ViewSnapshot } from "../types.ts";
 
-const attempt = (run: string, index: number): ViewResult => ({
+const LOCATOR_A = "@1abc123" as AttemptLocator;
+const LOCATOR_B = "@1zzz999" as AttemptLocator;
+
+const attempt = (locator: AttemptLocator | undefined, index: number): ViewResult => ({
   id: `demo/eval-${index}`,
   agent: "demo-agent",
-  outcome: "passed",
+  verdict: "passed",
   attempt: 0,
   durationMs: 1,
   assertions: [],
-  attemptRef: { run, result: index },
+  ...(locator !== undefined ? { locator } : {}),
 });
 
 // 快照只有 results 参与定位,其余元信息字段与路由无关。
 const snap = (results: ViewResult[]): ViewSnapshot => ({ results }) as ViewSnapshot;
 
-describe("parseAttemptHash", () => {
-  it("parses the canonical run-dir + index shape", () => {
-    expect(parseAttemptHash("#/attempt/2026-07-02T03-10-24-123Z/4")).toEqual({
-      run: "2026-07-02T03-10-24-123Z",
-      result: 4,
-    });
+describe("parseAttemptHash / formatAttemptHash", () => {
+  it("parses the canonical `@<scheme><body>` locator shape", () => {
+    expect(parseAttemptHash("#/attempt/@1abc123")).toBe("@1abc123");
   });
 
-  it("round-trips through formatAttemptHash, including runs that need encoding", () => {
-    for (const ref of [
-      { run: "2026-07-02T03-10-24-123Z", result: 0 },
-      { run: "nested/2026-01-01T00-00-00-000Z", result: 12 },
-      { run: "with space", result: 3 },
-      { run: ".", result: 7 }, // 单文件入口的 run 占位
-    ]) {
-      expect(parseAttemptHash(formatAttemptHash(ref))).toEqual(ref);
+  it("round-trips through formatAttemptHash", () => {
+    for (const locator of [LOCATOR_A, LOCATOR_B, "@10000000" as AttemptLocator]) {
+      expect(parseAttemptHash(formatAttemptHash(locator))).toBe(locator);
     }
   });
 
-  it("treats the last segment as the index so hand-written nested runs still parse", () => {
-    expect(parseAttemptHash("#/attempt/nested/2026-01-01T00-00-00-000Z/12")).toEqual({
-      run: "nested/2026-01-01T00-00-00-000Z",
-      result: 12,
-    });
+  it("formatAttemptHash matches the report tree's DEFAULT_WEB_CONTEXT.attemptHref format exactly", () => {
+    // src/report/tree.ts: attemptHref: (locator) => `#/attempt/${locator}` — locator 本身自带 "@" 前缀。
+    expect(formatAttemptHash(LOCATOR_A)).toBe(`#/attempt/${LOCATOR_A}`);
   });
 
   it("rejects non-attempt hashes and malformed shapes", () => {
@@ -52,38 +45,35 @@ describe("parseAttemptHash", () => {
       "#/compare/a/b",
       "#/attempt",
       "#/attempt/",
-      "#/attempt/run-only",
-      "#/attempt//3",
-      "#/attempt/run/",
-      "#/attempt/run/abc",
-      "#/attempt/run/1.5",
-      "#/attempt/run/-1",
-      "#/attempt/run/1/", // 末段为空
-      "#/attempt/%zz/1", // 非法 % 转义
+      "#/attempt/exp/snap/eval/a0", // 旧的两段式路由,不再被接受
+      "#/attempt/nolocatorprefix",
+      "#/attempt/@", // 只有前缀,没有 scheme + body
+      "#/attempt/@ABC123", // 大写不合法(base36 恒小写)
+      "#/attempt/@1abc 123", // 含空格
+      "#/attempt/@1abc/123", // 含 "/"
     ]) {
       expect(parseAttemptHash(hash), hash).toBeNull();
     }
   });
 });
 
-describe("resolveAttemptRef", () => {
-  const runA = "2026-07-01T10-00-00-000Z";
-  const runB = "2026-07-02T10-00-00-000Z";
-  const snapshots = [snap([attempt(runA, 0), attempt(runB, 0)]), snap([attempt(runA, 1)])];
+describe("resolveAttemptLocator", () => {
+  const snapshots = [
+    snap([attempt(LOCATOR_A, 0), attempt(LOCATOR_B, 1)]),
+    snap([attempt("@1other01" as AttemptLocator, 2)]),
+  ];
 
-  it("finds the attempt whose injected ref matches run + index", () => {
-    expect(resolveAttemptRef(snapshots, { run: runA, result: 1 })).toBe(snapshots[1]!.results[0]);
-    expect(resolveAttemptRef(snapshots, { run: runB, result: 0 })).toBe(snapshots[0]!.results[1]);
+  it("finds the attempt whose injected locator matches", () => {
+    expect(resolveAttemptLocator(snapshots, LOCATOR_A)).toBe(snapshots[0]!.results[0]);
+    expect(resolveAttemptLocator(snapshots, LOCATOR_B)).toBe(snapshots[0]!.results[1]);
   });
 
-  it("returns null for unknown runs and out-of-range indexes", () => {
-    expect(resolveAttemptRef(snapshots, { run: "no-such-run", result: 0 })).toBeNull();
-    expect(resolveAttemptRef(snapshots, { run: runA, result: 99 })).toBeNull();
+  it("returns null for unknown locators", () => {
+    expect(resolveAttemptLocator(snapshots, "@1nosuch1" as AttemptLocator)).toBeNull();
   });
 
-  it("returns null when results predate attemptRef injection (old baked data)", () => {
-    const legacy = attempt(runA, 0);
-    delete (legacy as { attemptRef?: unknown }).attemptRef;
-    expect(resolveAttemptRef([snap([legacy])], { run: runA, result: 0 })).toBeNull();
+  it("returns null when results predate locator injection (old baked data)", () => {
+    const legacy = attempt(undefined, 0);
+    expect(resolveAttemptLocator([snap([legacy])], LOCATOR_A)).toBeNull();
   });
 });

package/src/view/app/lib/attempt-route.ts

@@ -1,43 +1,43 @@
-// attempt 级 hash 深链:`#/attempt/<run>/<result>`(docs/view.md「用 Reports 积木重建 view」)。
-// 路由参数就是 AttemptRef(run 目录名 + summary.results 下标),由 loader 注入到每条 result 上;
-// 这里只做纯解析 / 格式化 / 匹配,不碰 location / history,方便单测。
+// attempt 级 hash 深链:`#/attempt/@<locator>`(docs/feature/reports/view.md「打开与收窄」)。
+// 路由参数就是不透明的 AttemptLocator(src/results/locator.ts),由 loader 注入到每条
+// result 上;这里只做纯解析 / 格式化 / 匹配,不碰 location / history,方便单测。与报告槽
+// DEFAULT_WEB_CONTEXT.attemptHref(src/report/tree.ts)同一格式,两条深链来源互通。
 // hash 目前只有这一种路由:tab 切换是纯组件 state,旧版 modal 深链走 ?modal= 查询参数,互不占用。
+//
+// AttemptLocator 的编码/解码本体住在 src/results/locator.ts,但那个模块顶层 import 了
+// node:crypto(encodeAttemptLocator 用于生成 locator),不能被这个浏览器打包的 app/ 目录
+// 静态 import——这里只需要「像不像一个 locator」的轻量语法校验,不需要真校验 scheme/body
+// 长度(那是 reader 建索引时的事,view 前端拿到的 locator 恒来自可信的 loader 注入)。
 
-import type { AttemptRef, ViewResult, ViewSnapshot } from "../types.ts";
+import type { AttemptLocator, ViewResult, ViewSnapshot } from "../types.ts";
 
 export const ATTEMPT_HASH_PREFIX = "#/attempt/";
 
-/** AttemptRef → 可分享的 hash。run 整体编码(嵌套 run 目录里的 "/" 也编进去),下标恒为末段。 */
-export function formatAttemptHash(ref: AttemptRef): string {
-  return `${ATTEMPT_HASH_PREFIX}${encodeURIComponent(ref.run)}/${ref.result}`;
+/** locator 串的最小形状:`@` + 至少一个 base36 字符(scheme 字符 + body)。 */
+const LOCATOR_SHAPE = /^@[0-9a-z]+$/;
+
+/** AttemptLocator → 可分享的 hash:locator 本身就是路由参数,原样拼在前缀后面,不需要分段编码。 */
+export function formatAttemptHash(locator: AttemptLocator): string {
+  return `${ATTEMPT_HASH_PREFIX}${locator}`;
 }
 
 /**
- * hash → AttemptRef;不是本路由 / 形状不对返回 null(由调用方决定 warn 与否)。
- * 手写链接可能不编码 run 里的 "/"(嵌套 run 目录),所以按「最后一段是下标」切,而不是按段数。
+ * hash → AttemptLocator;不是本路由 / 形状不像 locator 返回 null(由调用方决定 warn 与否)。
+ * 只做前缀 + 粗粒度字符集校验,不重新实现 decodeAttemptLocator 的 scheme/body 长度校验——
+ * 那份权威校验属于 src/results/locator.ts,这里刻意保持浏览器打包安全(不引入 node:crypto)。
  */
-export function parseAttemptHash(hash: string): AttemptRef | null {
+export function parseAttemptHash(hash: string): AttemptLocator | null {
   if (!hash.startsWith(ATTEMPT_HASH_PREFIX)) return null;
   const rest = hash.slice(ATTEMPT_HASH_PREFIX.length);
-  const cut = rest.lastIndexOf("/");
-  if (cut <= 0) return null; // 没有下标段,或 run 为空
-  const indexPart = rest.slice(cut + 1);
-  if (!/^\d+$/.test(indexPart)) return null;
-  let run: string;
-  try {
-    run = decodeURIComponent(rest.slice(0, cut));
-  } catch {
-    return null; // 非法 % 转义
-  }
-  if (!run) return null;
-  return { run, result: parseInt(indexPart, 10) };
+  if (!LOCATOR_SHAPE.test(rest)) return null;
+  return rest as AttemptLocator;
 }
 
-/** 在全部快照(含历史)里找 AttemptRef 指向的 attempt;旧格式烘焙的数据没有 attemptRef,自然找不到。 */
-export function resolveAttemptRef(snapshots: ViewSnapshot[], ref: AttemptRef): ViewResult | null {
+/** 在全部快照(含历史)里找 locator 指向的 attempt;旧格式烘焙的数据没有 locator,自然找不到。 */
+export function resolveAttemptLocator(snapshots: ViewSnapshot[], locator: AttemptLocator): ViewResult | null {
   for (const snapshot of snapshots) {
     for (const result of snapshot.results ?? []) {
-      if (result.attemptRef?.run === ref.run && result.attemptRef.result === ref.result) return result;
+      if (result.locator === locator) return result;
     }
   }
   return null;
@@ -47,6 +47,6 @@ export function resolveAttemptRef(snapshots: ViewSnapshot[], ref: AttemptRef): V
 export function unresolvedAttemptWarning(hash: string): string {
   return (
     `[niceeval view] Ignoring attempt link "${hash}": no matching attempt in this view ` +
-    `(run not loaded, result index out of range, or the data was baked without attempt refs).`
+    `(snapshot not loaded, attempt not found, or the data was baked without a locator).`
   );
 }