niceeval 0.3.0 → 0.4.0

package/src/runner/run.ts

@@ -70,7 +70,7 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
     for (const r of opts.priorResults) {
       if (!r.experimentId || !priorRunKeys.has(`${r.experimentId}|${r.id}`)) continue;
       // artifactsDir 是相对"本次 run 自己目录"的路径,新 summary 换了目录就会失效,必须清掉。
-      // artifactBase 不一样:它已经是 loadMostRecentResults(经 withArtifactBases)拼好的、
+      // artifactBase 不一样:它已经是 loadMostRecentResults(经 withViewRefs)拼好的、
       // 相对稳定的 .niceeval 根的路径,指向旧 run 的产物目录依然可解析,原样带过来
       // ——不然 view 就再也找不到这条携带结果的源码/转录/trace 了。
       carriedResults.push({ ...r, artifactsDir: undefined });
@@ -201,12 +201,14 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
             // 早停:同 key 已通过,或已 errored(重跑只会重复同一个框架错误)且开了 earlyExit
             // → 跳过未启动的 attempt。
             if (a.run.earlyExit && (passedKeys.has(a.key) || erroredKeys.has(a.key))) {
-              yield* Effect.promise(() =>
-                emitReporterEvent(opts.reporters, {
-                  type: "run:earlyExit",
-                  evalId: a.evalDef.id,
-                  experimentId: a.run.experimentId,
-                }),
+              yield* reportMutex.withPermits(1)(
+                Effect.promise(() =>
+                  emitReporterEvent(opts.reporters, {
+                    type: "run:earlyExit",
+                    evalId: a.evalDef.id,
+                    experimentId: a.run.experimentId,
+                  }),
+                ),
               );
               return;
             }
@@ -222,8 +224,10 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
                 if (s.spent >= budget) {
                   if (!budgetReported.has(budgetKey)) {
                     budgetReported.add(budgetKey);
-                    yield* Effect.promise(() =>
-                      emitReporterEvent(opts.reporters, { type: "run:budgetExceeded", budget, spent: s.spent }),
+                    yield* reportMutex.withPermits(1)(
+                      Effect.promise(() =>
+                        emitReporterEvent(opts.reporters, { type: "run:budgetExceeded", budget, spent: s.spent }),
+                      ),
                     );
                   }
                   return;
@@ -255,15 +259,17 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
                 ? AbortSignal.any([opts.signal, evalAc.signal])
                 : (evalAc?.signal ?? opts.signal);
 
-            yield* Effect.promise(() =>
-              emitReporterEvent(opts.reporters, {
-                type: "eval:start",
-                eval: { id: a.evalDef.id },
-                agent: a.run.agent,
-                model: a.run.model,
-                attempt: a.attempt,
-                experimentId: a.run.experimentId,
-              }),
+            yield* reportMutex.withPermits(1)(
+              Effect.promise(() =>
+                emitReporterEvent(opts.reporters, {
+                  type: "eval:start",
+                  eval: { id: a.evalDef.id },
+                  agent: a.run.agent,
+                  model: a.run.model,
+                  attempt: a.attempt,
+                  experimentId: a.run.experimentId,
+                }),
+              ),
             );
             const result = yield* runAttemptEffect(a, opts, sandboxSem, attemptSignal).pipe(
               Effect.ensuring(
@@ -310,7 +316,12 @@ export async function runEvals(opts: RunOptions): Promise<RunSummary> {
                 ),
               ),
             );
-            yield* Effect.promise(() => emitReporterEvent(opts.reporters, { type: "eval:complete", result }));
+            // 和上面的 onEvalComplete 同一把 reportMutex:两条回调路径都要串行化,否则并发
+            // attempt 各自触发的 eval:complete 会绕开 permit=1 直接并发跑,和文档承诺的
+            // 「报告回调串行化」不一致。
+            yield* reportMutex.withPermits(1)(
+              Effect.promise(() => emitReporterEvent(opts.reporters, { type: "eval:complete", result })),
+            );
           }),
       { concurrency: opts.maxConcurrency, discard: true },
     ).pipe(

package/src/runner/types.ts

@@ -153,6 +153,8 @@ export interface ExperimentDef {
   agent: Agent;
   /** 单个模型(agent 留空时实验决定);省略=用 agent 原生默认。跨模型对比写多个实验文件,别用数组。 */
   model?: string;
+  /** 模型推理努力程度(如 "low"/"medium"/"high",取值由具体模型/adapter 决定);省略=用 agent 原生默认。经 ctx.reasoningEffort 透给 adapter 与 eval。 */
+  reasoningEffort?: string;
   flags?: Record<string, unknown>;
   runs?: number;
   earlyExit?: boolean;
@@ -191,6 +193,20 @@ export interface Config {
    * 的远程接入,在这里覆盖。
    */
   telemetry?: { host?: string; port?: number };
+  /**
+   * 内置价格表(`o11y/prices.json`)之上的用户覆盖 / 补充,按 model 查(见 Observability
+   * · 用量与成本)。key 支持精确 model 名或 `provider/*` 通配(自托管/网关折扣按 provider 批量覆盖);
+   * 精确 key 优先于通配。只在没有网关实测成本(`usage.costUSD`)时才会用到——实测优先于估算恒成立。
+   */
+  pricing?: Record<string, PriceOverride>;
+}
+
+/** 每百万 token 的美元单价;省略的桶退回 `inputPerMTok`(cache token 本质也是 input)。 */
+export interface PriceOverride {
+  inputPerMTok: number;
+  outputPerMTok: number;
+  cacheReadPerMTok?: number;
+  cacheWritePerMTok?: number;
 }
 
 // ───────────────────────── 调度编排 ─────────────────────────
@@ -199,6 +215,7 @@ export interface Config {
 export interface AgentRun {
   agent: Agent;
   model?: string;
+  reasoningEffort?: string;
   flags: Record<string, unknown>;
   runs: number;
   earlyExit: boolean;

package/src/sandbox/types.ts

@@ -54,8 +54,8 @@ export type SandboxRuntime = "node20" | "node24";
 /**
  * Sandbox 的「数据结构」定义 —— 与 agent 一样可带参数(见 docs/sandbox.md)。
  * 必须用工厂函数构造(`dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` / `defineSandbox()`),
- * 放进 config / experiment 的 `sandbox` 字段 —— 字段类型只接受这个数据结构,不接受裸字符串,
- * 省略字段 = 按环境自动探测后端。各后端的参数互不相同 —— 这是个按 `backend` 区分的可辨识联合(discriminated union)。
+ * 放进 config / experiment 的 `sandbox` 字段 —— 字段类型只接受这个数据结构,不接受裸字符串。
+ * 各后端的参数互不相同 —— 这是个按 `backend` 区分的可辨识联合(discriminated union)。
  */
 export interface DockerSandboxSpec {
   readonly backend: "docker";
@@ -89,7 +89,7 @@ export interface CustomSandboxSpec {
 
 export type SandboxSpec = DockerSandboxSpec | VercelSandboxSpec | E2BSandboxSpec | CustomSandboxSpec;
 
-/** config / experiment 的 `sandbox` 字段:必须是工厂函数产出的 spec 数据结构,省略 = 自动探测后端。 */
+/** config / experiment 的 `sandbox` 字段:必须是工厂函数产出的 spec 数据结构;沙箱型 agent 不能省略。 */
 export type SandboxOption = SandboxSpec;
 
 export interface CommandOptions {

package/src/view/app/App.tsx

@@ -1,11 +1,13 @@
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { detectLocale, makeTranslator, persistLocale, setDocumentLocale } from "./i18n.ts";
 import type { MessageKey } from "./i18n.ts";
 import type { Locale, LocalizedText, SortKey, SortState, Tab, ViewData, ViewResult, ViewRow } from "./types.ts";
 import { buildGroupMap, compareRows, resultFromUrl } from "./lib/rows.ts";
+import { formatAttemptHash, parseAttemptHash, resolveAttemptRef, unresolvedAttemptWarning } from "./lib/attempt-route.ts";
 import { formatCost, formatDateTime, formatDuration, formatPercent } from "./lib/format.ts";
 import { Metric } from "./components/primitives.tsx";
 import { GroupSelector } from "./components/GroupSelector.tsx";
+import { CostScoreChart } from "./components/CostScoreChart.tsx";
 import { ExperimentTable } from "./components/ExperimentTable.tsx";
 import { CopyAllErrors } from "./components/CopyControls.tsx";
 import { AttemptModal } from "./components/AttemptModal.tsx";
@@ -26,6 +28,19 @@ export function localizedText(text: LocalizedText | undefined, locale: Locale):
   return text[locale] ?? text.en ?? Object.values(text)[0];
 }
 
+/** 初始 URL → 直接打开的 attempt:先认 #/attempt/<run>/<result> 深链,回退旧版 ?modal= 参数。 */
+function modalResultFromLocation(rows: ViewRow[]): ViewResult | null {
+  const ref = parseAttemptHash(location.hash);
+  if (ref) {
+    const found = resolveAttemptRef(rows, ref);
+    if (found) return found;
+    // 定位不到(run 不在、下标越界、旧格式数据):不开空 modal,页面照常渲染。
+    console.warn(unresolvedAttemptWarning(location.hash));
+    return null;
+  }
+  return resultFromUrl(rows);
+}
+
 export function App({ data }: { data: ViewData }) {
   const rows = data.rows ?? [];
   const [locale, setLocale] = useState<Locale>(() => detectLocale());
@@ -38,7 +53,11 @@ export function App({ data }: { data: ViewData }) {
     const groups = [...new Set(rows.map((r) => r.group).filter(Boolean))].sort();
     return groups[0] ?? null;
   });
-  const [modalResult, setModalResult] = useState<ViewResult | null>(() => resultFromUrl(rows));
+  const [modalResult, setModalResult] = useState<ViewResult | null>(() => modalResultFromLocation(rows));
+  // 当前 modal 的 hash 历史条目前面是否还有本页条目(本页 push 的 / 前进键回到的):
+  // true → UI 关闭走 history.back(),前进键还能重新打开;false(深链直接落地)→ 原地抹 hash,
+  // 免得 back 把用户弹出站外。
+  const modalOwnsHistory = useRef(false);
 
   useEffect(() => {
     setDocumentLocale(locale);
@@ -47,18 +66,61 @@ export function App({ data }: { data: ViewData }) {
 
   const openModal = useCallback((result: ViewResult) => {
     setModalResult(result);
-    const p = new URLSearchParams();
-    p.set("modal", result.id);
-    if (result.experimentId) p.set("exp", result.experimentId);
-    p.set("a", String(result.attempt));
-    history.replaceState(null, "", "?" + p.toString());
+    const ref = result.attemptRef;
+    // 旧格式烘焙的数据没有 attemptRef:modal 照常打开,只是这条 attempt 产不出可分享链接。
+    if (!ref) return;
+    try {
+      // pushState/replaceState 不触发 hashchange,不会和下面的监听器重复开合。
+      if (parseAttemptHash(location.hash)) {
+        // 已经在某条 attempt 深链上(防御浏览器导航竞态):替换当前条目,不叠历史。
+        history.replaceState(null, "", formatAttemptHash(ref));
+      } else {
+        history.pushState(null, "", formatAttemptHash(ref));
+        modalOwnsHistory.current = true;
+      }
+    } catch {
+      // file:// 等受限环境可能拒绝写 history;URL 同步失败不影响打开 modal。
+    }
   }, []);
 
   const closeModal = useCallback(() => {
     setModalResult(null);
-    history.replaceState(null, "", location.pathname);
+    if (modalOwnsHistory.current) {
+      modalOwnsHistory.current = false;
+      history.back();
+      return;
+    }
+    try {
+      // 深链直接落地 / 旧版 ?modal= 链接:没有可回退的本页条目,原地还原成无 modal 的 URL。
+      history.replaceState(null, "", location.pathname);
+    } catch {
+      // 还原 URL 失败不影响关闭。
+    }
   }, []);
 
+  // 浏览器前进/后退、手改 hash、页内 attempt 链接统一从 hashchange 开合 modal。
+  useEffect(() => {
+    const onHashChange = () => {
+      const ref = parseAttemptHash(location.hash);
+      if (!ref) {
+        modalOwnsHistory.current = false;
+        setModalResult(null);
+        return;
+      }
+      const found = resolveAttemptRef(rows, ref);
+      if (!found) {
+        console.warn(unresolvedAttemptWarning(location.hash));
+        setModalResult(null);
+        return;
+      }
+      // 经浏览器导航打开:前一条历史仍是本页,UI 关闭可以安全 back()。
+      modalOwnsHistory.current = true;
+      setModalResult(found);
+    };
+    window.addEventListener("hashchange", onHashChange);
+    return () => window.removeEventListener("hashchange", onHashChange);
+  }, [rows]);
+
   const groupMap = useMemo<Map<string, ViewRow[]>>(() => buildGroupMap(rows), [rows]);
   const pool = selectedGroup ? groupMap.get(selectedGroup) ?? [] : rows;
   const filtered = useMemo(() => {
@@ -181,15 +243,18 @@ export function App({ data }: { data: ViewData }) {
             </div>
           </div>
           {rows.length ? (
-            <ExperimentTable
-              rows={filtered}
-              sort={sort}
-              setSortKey={setSortKey}
-              openRows={openRows}
-              toggleRow={toggleRow}
-              openModal={openModal}
-              t={t}
-            />
+            <>
+              <CostScoreChart rows={filtered} t={t} />
+              <ExperimentTable
+                rows={filtered}
+                sort={sort}
+                setSortKey={setSortKey}
+                openRows={openRows}
+                toggleRow={toggleRow}
+                openModal={openModal}
+                t={t}
+              />
+            </>
           ) : (
             <div className="empty">
               {t("empty.summary")}

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

@@ -0,0 +1,127 @@
+import { useState } from "react";
+import type { T } from "../shared.ts";
+import type { ViewRow } from "../types.ts";
+import { formatCost, formatPercent } from "../lib/format.ts";
+import { layoutLabelOffsets, niceTicks, seriesColor } from "../lib/chart.ts";
+
+const WIDTH = 640;
+const HEIGHT = 300;
+const MARGIN = { top: 16, right: 24, bottom: 34, left: 46 };
+
+/** formatCost(0) 显示 "—"(表示"没测出成本"),但坐标轴原点确实就是 $0,不能沿用那个语义。 */
+function formatAxisCost(value: number): string {
+  return value === 0 ? "$0" : formatCost(value);
+}
+
+/**
+ * 一个 group 内「成本 vs 通过率」散点图:一行(一个实验/config)= 一个点。
+ * 只在 group 内至少两条 row 有 estimatedCostUSD 时渲染,否则没有比较意义。
+ */
+export function CostScoreChart({ rows, t }: { rows: ViewRow[]; t: T }) {
+  const [hoverKey, setHoverKey] = useState<string | null>(null);
+  const points = rows.filter((r): r is ViewRow & { estimatedCostUSD: number } => typeof r.estimatedCostUSD === "number" && Number.isFinite(r.estimatedCostUSD));
+  if (points.length < 2) return null;
+
+  const plotW = WIDTH - MARGIN.left - MARGIN.right;
+  const plotH = HEIGHT - MARGIN.top - MARGIN.bottom;
+
+  const xTicks = niceTicks(0, Math.max(...points.map((p) => p.estimatedCostUSD)), 5);
+  const xMax = xTicks[xTicks.length - 1] || 1;
+
+  const rates = points.map((p) => p.passRate);
+  const rateMin = Math.min(...rates);
+  const rateMax = Math.max(...rates);
+  const pad = Math.max(0.03, (rateMax - rateMin) * 0.25);
+  const yTicksRaw = niceTicks(Math.max(0, rateMin - pad), Math.min(1, rateMax + pad), 5);
+  const yMin = Math.max(0, yTicksRaw[0] ?? 0);
+  const yMax = Math.min(1, yTicksRaw[yTicksRaw.length - 1] ?? 1);
+  const yTicks = yTicksRaw.filter((v) => v >= yMin - 1e-9 && v <= yMax + 1e-9);
+
+  const xScale = (cost: number) => MARGIN.left + (cost / xMax) * plotW;
+  const yScale = (rate: number) => MARGIN.top + (1 - (rate - yMin) / (yMax - yMin)) * plotH;
+
+  const hovered = points.find((p) => p.key === hoverKey);
+
+  const positions = points.map((p) => {
+    const cx = xScale(p.estimatedCostUSD);
+    const cy = yScale(p.passRate);
+    const anchorLeft = cx >= MARGIN.left + plotW * 0.72;
+    return { cx, cy, anchorLeft, width: p.label.length * 6.4 + 10 };
+  });
+  const labelOffsets = layoutLabelOffsets(positions);
+
+  return (
+    <div className="cost-score-chart">
+      <div className="csc-head">{t("chart.costVsScore")}</div>
+      <div className="csc-svg-wrap">
+        <svg className="csc-svg" viewBox={`0 0 ${WIDTH} ${HEIGHT}`} role="img" aria-label={t("chart.costVsScore")}>
+          <g className="csc-grid">
+            {yTicks.map((tick) => (
+              <line key={`gy-${tick}`} x1={MARGIN.left} x2={WIDTH - MARGIN.right} y1={yScale(tick)} y2={yScale(tick)} />
+            ))}
+            {xTicks.map((tick) => (
+              <line key={`gx-${tick}`} y1={MARGIN.top} y2={HEIGHT - MARGIN.bottom} x1={xScale(tick)} x2={xScale(tick)} />
+            ))}
+          </g>
+          <g className="csc-axis csc-axis-y">
+            {yTicks.map((tick) => (
+              <text key={`ay-${tick}`} x={MARGIN.left - 8} y={yScale(tick)} textAnchor="end" dominantBaseline="middle">
+                {formatPercent(tick)}
+              </text>
+            ))}
+          </g>
+          <g className="csc-axis csc-axis-x">
+            {xTicks.map((tick) => (
+              <text key={`ax-${tick}`} x={xScale(tick)} y={HEIGHT - MARGIN.bottom + 18} textAnchor="middle">
+                {formatAxisCost(tick)}
+              </text>
+            ))}
+            <text x={MARGIN.left + plotW / 2} y={HEIGHT - 4} textAnchor="middle">
+              {t("chart.axisCost")}
+            </text>
+          </g>
+          <g className="csc-points">
+            {points.map((p, i) => {
+              const { cx, cy, anchorLeft } = positions[i]!;
+              const labelY = cy + 4 + labelOffsets[i]!;
+              const color = seriesColor(i);
+              const labelX = cx + (anchorLeft ? -10 : 10);
+              return (
+                <g
+                  key={p.key}
+                  className="csc-point"
+                  tabIndex={0}
+                  role="button"
+                  aria-label={`${p.label}: ${formatCost(p.estimatedCostUSD)}, ${formatPercent(p.passRate)}`}
+                  onMouseEnter={() => setHoverKey(p.key)}
+                  onMouseLeave={() => setHoverKey((k) => (k === p.key ? null : k))}
+                  onFocus={() => setHoverKey(p.key)}
+                  onBlur={() => setHoverKey((k) => (k === p.key ? null : k))}
+                >
+                  {/* 标签被挤开时补一条 leader line,避免脱离原点看不出对应关系。 */}
+                  {labelOffsets[i] ? <line className="csc-leader" x1={cx} y1={cy} x2={labelX} y2={labelY - 4} /> : null}
+                  <circle className="csc-hit" cx={cx} cy={cy} r={13} />
+                  <circle className="csc-dot" cx={cx} cy={cy} r={5} style={{ fill: color }} />
+                  <text x={labelX} y={labelY} textAnchor={anchorLeft ? "end" : "start"}>
+                    {p.label}
+                  </text>
+                </g>
+              );
+            })}
+          </g>
+        </svg>
+        {hovered ? (
+          <div
+            className="csc-tooltip"
+            style={{ left: `${(xScale(hovered.estimatedCostUSD) / WIDTH) * 100}%`, top: `${(yScale(hovered.passRate) / HEIGHT) * 100}%` }}
+          >
+            <b>{formatPercent(hovered.passRate)}</b> {t("chart.axisScore")}
+            <div className="csc-tooltip-meta">
+              {formatCost(hovered.estimatedCostUSD)} · {hovered.model || hovered.agent}
+            </div>
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/src/view/app/i18n.ts

@@ -109,7 +109,10 @@ export type MessageKey =
   | "outcome.skipped"
   | "banner.skippedTitle"
   | "banner.skipped.incompatible"
-  | "banner.skipped.malformed";
+  | "banner.skipped.malformed"
+  | "chart.costVsScore"
+  | "chart.axisCost"
+  | "chart.axisScore";
 
 type Dictionary = Record<MessageKey, string>;
 
@@ -221,6 +224,9 @@ const dictionaries: Record<Locale, Dictionary> = {
     "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.malformed": "unreadable report ({{detail}}) — it may be corrupted; re-run the eval or delete this run directory",
+    "chart.costVsScore": "Cost vs. Score",
+    "chart.axisCost": "Avg cost per eval",
+    "chart.axisScore": "Pass rate",
   },
   "zh-CN": {
     "app.title": "niceeval 实验查看器",
@@ -329,6 +335,9 @@ const dictionaries: Record<Locale, Dictionary> = {
     "banner.skippedTitle": "以下 run 读取失败,此处不展示:",
     "banner.skipped.incompatible": "由 niceeval {{producer}} 写入(schemaVersion {{schemaVersion}})—— 用右侧命令查看",
     "banner.skipped.malformed": "报告读不了({{detail}})—— 可能已损坏;重跑该 eval 或删除这个 run 目录",
+    "chart.costVsScore": "成本 × 通过率",
+    "chart.axisCost": "平均每个 eval 成本",
+    "chart.axisScore": "通过率",
   },
 };
 

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

@@ -0,0 +1,89 @@
+// #/attempt/<run>/<result> 深链的纯函数单测:解析 / 格式化往返、坏输入、按 attemptRef 定位。
+
+import { describe, expect, it } from "vitest";
+import { formatAttemptHash, parseAttemptHash, resolveAttemptRef } from "./attempt-route.ts";
+import type { ViewResult, ViewRow } from "../types.ts";
+
+const attempt = (run: string, index: number): ViewResult => ({
+  id: `demo/eval-${index}`,
+  agent: "demo-agent",
+  outcome: "passed",
+  attempt: 0,
+  durationMs: 1,
+  assertions: [],
+  attemptRef: { run, result: index },
+});
+
+// 榜单行只有 results 参与定位,其余聚合字段与路由无关。
+const row = (results: ViewResult[]): ViewRow => ({ results }) as ViewRow;
+
+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,
+    });
+  });
+
+  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("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("rejects non-attempt hashes and malformed shapes", () => {
+    for (const hash of [
+      "",
+      "#",
+      "#/",
+      "#tab-experiments", // 页内锚点不归这条路由
+      "#/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", // 非法 % 转义
+    ]) {
+      expect(parseAttemptHash(hash), hash).toBeNull();
+    }
+  });
+});
+
+describe("resolveAttemptRef", () => {
+  const runA = "2026-07-01T10-00-00-000Z";
+  const runB = "2026-07-02T10-00-00-000Z";
+  const rows = [row([attempt(runA, 0), attempt(runB, 0)]), row([attempt(runA, 1)])];
+
+  it("finds the attempt whose injected ref matches run + index", () => {
+    expect(resolveAttemptRef(rows, { run: runA, result: 1 })).toBe(rows[1]!.results[0]);
+    expect(resolveAttemptRef(rows, { run: runB, result: 0 })).toBe(rows[0]!.results[1]);
+  });
+
+  it("returns null for unknown runs and out-of-range indexes", () => {
+    expect(resolveAttemptRef(rows, { run: "no-such-run", result: 0 })).toBeNull();
+    expect(resolveAttemptRef(rows, { run: runA, result: 99 })).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([row([legacy])], { run: runA, result: 0 })).toBeNull();
+  });
+});

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

@@ -0,0 +1,52 @@
+// attempt 级 hash 深链:`#/attempt/<run>/<result>`(docs/view.md「用 Reports 积木重建 view」)。
+// 路由参数就是 AttemptRef(run 目录名 + summary.results 下标),由 loader 注入到每条 result 上;
+// 这里只做纯解析 / 格式化 / 匹配,不碰 location / history,方便单测。
+// hash 目前只有这一种路由:tab 切换是纯组件 state,旧版 modal 深链走 ?modal= 查询参数,互不占用。
+
+import type { AttemptRef, ViewResult, ViewRow } 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}`;
+}
+
+/**
+ * hash → AttemptRef;不是本路由 / 形状不对返回 null(由调用方决定 warn 与否)。
+ * 手写链接可能不编码 run 里的 "/"(嵌套 run 目录),所以按「最后一段是下标」切,而不是按段数。
+ */
+export function parseAttemptHash(hash: string): AttemptRef | 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) };
+}
+
+/** 在榜单行里找 AttemptRef 指向的 attempt;旧格式烘焙的数据没有 attemptRef,自然找不到。 */
+export function resolveAttemptRef(rows: ViewRow[], ref: AttemptRef): ViewResult | null {
+  for (const row of rows) {
+    for (const result of row.results ?? []) {
+      if (result.attemptRef?.run === ref.run && result.attemptRef.result === ref.result) return result;
+    }
+  }
+  return null;
+}
+
+/** 深链定位不到时的提示(console.warn 用,英文);页面照常渲染,不开空 modal。 */
+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).`
+  );
+}

package/src/view/app/lib/chart.ts

@@ -0,0 +1,72 @@
+// 通用图表数值工具:round-number 刻度生成,无第三方依赖(遵循 view/ 不引图表库的现状)。
+
+function niceNumber(range: number, round: boolean): number {
+  if (range <= 0) return 1;
+  const exponent = Math.floor(Math.log10(range));
+  const fraction = range / 10 ** exponent;
+  let niceFraction: number;
+  if (round) {
+    if (fraction < 1.5) niceFraction = 1;
+    else if (fraction < 3) niceFraction = 2;
+    else if (fraction < 7) niceFraction = 5;
+    else niceFraction = 10;
+  } else {
+    if (fraction <= 1) niceFraction = 1;
+    else if (fraction <= 2) niceFraction = 2;
+    else if (fraction <= 5) niceFraction = 5;
+    else niceFraction = 10;
+  }
+  return niceFraction * 10 ** exponent;
+}
+
+/** [min, max] 区间上生成 count 个左右的“整齐”刻度(Heckbert nice-numbers)。 */
+export function niceTicks(min: number, max: number, count = 5): number[] {
+  if (min === max) {
+    min -= 1;
+    max += 1;
+  }
+  const range = niceNumber(max - min, false);
+  const step = niceNumber(range / Math.max(1, count - 1), true);
+  const niceMin = Math.floor(min / step) * step;
+  const niceMax = Math.ceil(max / step) * step;
+  const ticks: number[] = [];
+  for (let v = niceMin; v <= niceMax + step * 0.5; v += step) ticks.push(Number(v.toFixed(10)));
+  return ticks;
+}
+
+/** 六色分类色板之外的第 7+ 个系列一律回退到中性色,避免同色误导身份(见 dataviz 分类色板规则)。 */
+export function seriesColor(index: number): string {
+  return index < 6 ? `var(--series-${index + 1})` : "var(--muted)";
+}
+
+export interface LabelInput {
+  cx: number;
+  cy: number;
+  width: number;
+  /** true = 文字锚在点左侧(text-anchor: end),false = 锚在右侧(text-anchor: start)。 */
+  anchorLeft: boolean;
+}
+
+/**
+ * 贪心地把互相重叠的直接标签往下推开(按 y 排序、逐个查重叠再下移),点本身位置不变。
+ * 散点常见同分不同价的聚簇,这一步避免标签叠成一团糊字。
+ */
+export function layoutLabelOffsets(items: LabelInput[], lineHeight = 14, padX = 4): number[] {
+  const offsets = new Array(items.length).fill(0);
+  const order = [...items.keys()].sort((a, b) => items[a].cy - items[b].cy || items[a].cx - items[b].cx);
+  const placed: { x0: number; x1: number; y: number }[] = [];
+  for (const i of order) {
+    const it = items[i];
+    const x0 = it.anchorLeft ? it.cx - it.width : it.cx;
+    const x1 = it.anchorLeft ? it.cx : it.cx + it.width;
+    let y = it.cy;
+    let guard = 0;
+    while (guard < 40 && placed.some((p) => x0 < p.x1 + padX && x1 > p.x0 - padX && Math.abs(y - p.y) < lineHeight)) {
+      y += lineHeight;
+      guard++;
+    }
+    placed.push({ x0, x1, y });
+    offsets[i] = y - it.cy;
+  }
+  return offsets;
+}