dsh-plugin-billing 0.0.0-stage → 0.1.1

package/scripts/verify.mjs

@@ -0,0 +1,1474 @@
+#!/usr/bin/env node
+/**
+ * 插件自检：不需要浏览器，也不需要运行中的 dsh 服务端。
+ *
+ * 覆盖三块容易出错、又最该被钉住的东西：
+ *
+ *  1. **计价数学**：高峰/空闲时段判定（含边界与周末）、三档单价折算、四个计费桶
+ *     的归并与金额——金额是给用户看的数字，错一位都是误导。
+ *  2. **客户端 bundle**：自注册格式、共享模块请求清单、`apply()` 是否把金额行注册
+ *     进 `conversation.composer.dock`、zh/en 文案键是否一一对应。
+ *  3. **Host 侧**：是否注册了精确路由、非 GET 是否 405、缺凭据时是否给出可解析的
+ *     失败响应（不发任何网络请求）。
+ *
+ * 另有一个默认关闭的联网用例：`DSH_BILLING_LIVE_TEST=1 node scripts/verify.mjs`
+ * 会真的调用上游余额接口并断言 `ok: true`。
+ *
+ * 用法：node scripts/verify.mjs
+ */
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, extname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import vm from 'node:vm';
+import { parsePricingText, withLegacyAliases } from '../lib/prices.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = join(here, '..');
+const PACKAGE_ID = 'dsh-plugin-billing';
+
+let failures = 0;
+/** 跑一个用例；抛错时记录并继续，最后统一汇报。 */
+function check(label, fn) {
+  try {
+    fn();
+    console.log(`  ✔ ${label}`);
+  } catch (error) {
+    failures += 1;
+    console.error(`  ✘ ${label}`);
+    console.error(`     ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+async function checkAsync(label, fn) {
+  try {
+    await fn();
+    console.log(`  ✔ ${label}`);
+  } catch (error) {
+    failures += 1;
+    console.error(`  ✘ ${label}`);
+    console.error(`     ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+console.log('余额与金额插件自检\n');
+
+// ─────────────────────────────────────────────── 客户端 bundle
+console.log('客户端 bundle');
+
+const bundleSource = readFileSync(join(root, 'lib', 'client.js'), 'utf8');
+
+/** 抓住 bundle 的自注册行。 */
+let registration;
+vm.runInNewContext(
+  bundleSource,
+  {
+    window: { __ModuleLoader__: { load: (row) => { registration = row; } } },
+    console,
+    // 组件挂载后会去取余额；这里给一个"永远失败"的替身，测试只关心渲染结果。
+    fetch: async () => ({ ok: false, status: 503, json: async () => ({ ok: false, error: { message: 'test' } }) }),
+    setInterval: () => 0,
+    clearInterval: () => {},
+    setTimeout,
+    clearTimeout,
+  },
+  { filename: 'lib/client.js' },
+);
+
+/**
+ * 外壳播种的共享模块（`staticModules`），取自
+ * `@deepseek-ai/dsh-web-frontend/dist/assets/index-*.js` 里的播种表：
+ * react、react/jsx-runtime、react-dom、react-dom/client、@deepseek-ai/cordis、
+ * @deepseek-ai/dsh-client-ui-slots、@deepseek-ai/dsh-client-ui-primitives。
+ *
+ * 不在播种表、也不是启动图条目的 specifier 会在 `require()` 处抛错
+ * （client-modules 的 bundle 纯度门禁）。因此这里把清单钉住。
+ */
+const SHELL_SEED_MODULES = [
+  'react',
+  'react/jsx-runtime',
+  'react-dom',
+  'react-dom/client',
+  '@deepseek-ai/cordis',
+  '@deepseek-ai/dsh-client-ui-slots',
+  '@deepseek-ai/dsh-client-ui-primitives',
+];
+
+/** 统一基座提供的共享模块的最小替身。 */
+const SHARED = {
+  react: {
+    useState: (initial) => [initial, () => {}],
+    useEffect: (fn) => (typeof fn === 'function' ? fn() : undefined),
+    useMemo: (fn) => fn(),
+    useCallback: (fn) => fn,
+    memo: (component) => component,
+  },
+  // 返回可辨识的标记对象：若返回 null，就分不清「渲染了」和「组件返回 null」。
+  'react/jsx-runtime': {
+    jsx: (type, props) => ({ __jsx: true, type, props }),
+    jsxs: (type, props) => ({ __jsx: true, type, props }),
+    Fragment: 'Fragment',
+  },
+  '@deepseek-ai/dsh-client-ui-primitives': {
+    Tooltip: () => null,
+    Button: (props) => ({ __jsx: true, type: 'Button', props }),
+  },
+};
+
+const requested = [];
+const clientExports = registration.factory((specifier) => {
+  requested.push(specifier);
+  if (SHARED[specifier] === undefined) throw new Error(`未预料的共享模块请求：${specifier}`);
+  return SHARED[specifier];
+});
+
+check('bundle 通过 window.__ModuleLoader__.load 自注册，id 为包名', () => {
+  assert.ok(registration, 'bundle 没有调用 __ModuleLoader__.load');
+  assert.equal(registration.id, PACKAGE_ID);
+  assert.equal(typeof registration.factory, 'function');
+});
+
+check('只请求外壳播种的共享模块（否则 require 会抛纯度门禁错误）', () => {
+  assert.ok(requested.length > 0, 'bundle 没有请求任何共享模块');
+  for (const specifier of requested) {
+    assert.ok(
+      SHELL_SEED_MODULES.includes(specifier),
+      `${specifier} 不在外壳播种表里，浏览器 require 时会失败`,
+    );
+  }
+  assert.deepEqual([...requested].sort(), [
+    '@deepseek-ai/dsh-client-ui-primitives',
+    'react',
+    'react/jsx-runtime',
+  ]);
+});
+
+check('导出 inject = ["slots","locale"] 与 apply', () => {
+  assert.deepEqual([...clientExports.inject], ['slots', 'locale']);
+  assert.equal(typeof clientExports.apply, 'function');
+});
+
+// ─────────────────────────────────────────────── 计价数学
+console.log('\n计价数学');
+
+const testing = clientExports.__testing;
+
+/**
+ * bundle 跑在 vm 的独立 realm 里，返回对象的原型与本 realm 不同，
+ * `deepStrictEqual` 会因原型不同而失败，因此断言前先序列化回普通对象。
+ * @param value - 任意 JSON 可序列化值。
+ * @returns 本 realm 的等价副本。
+ */
+const plain = (value) => JSON.parse(JSON.stringify(value));
+
+/**
+ * 构造一个“北京时间某星期几某时刻”的 epoch 毫秒（不依赖本机时区）。
+ * @param weekday - 0=周日 … 6=周六。
+ * @param hour - 北京时间小时。
+ * @param minute - 北京时间分钟。
+ * @returns epoch 毫秒。
+ */
+function beijingAt(weekday, hour, minute) {
+  for (let offset = 0; offset < 14; offset += 1) {
+    const ms = Date.UTC(2026, 0, 1 + offset, hour - 8, minute);
+    if (new Date(ms + 8 * 3600 * 1000).getUTCDay() === weekday) return ms;
+  }
+  throw new Error(`找不到星期 ${weekday}`);
+}
+
+const MONDAY_PEAK = beijingAt(1, 10, 30);
+const MONDAY_AFTERNOON = beijingAt(1, 15, 0);
+const MONDAY_LUNCH = beijingAt(1, 13, 0);
+const MONDAY_EVENING = beijingAt(1, 19, 0);
+const SATURDAY = beijingAt(6, 10, 30);
+
+check('高峰时段：周一上午与下午为高峰，午休/傍晚/周末为空闲', () => {
+  assert.equal(testing.isPeak(MONDAY_PEAK), true);
+  assert.equal(testing.isPeak(MONDAY_AFTERNOON), true);
+  assert.equal(testing.isPeak(MONDAY_LUNCH), false);
+  assert.equal(testing.isPeak(MONDAY_EVENING), false);
+  assert.equal(testing.isPeak(SATURDAY), false);
+});
+
+check('高峰窗口边界：09:00 起、12:00 止、14:00 起、18:00 止', () => {
+  assert.equal(testing.isPeak(beijingAt(1, 9, 0)), true);
+  assert.equal(testing.isPeak(beijingAt(1, 11, 59)), true);
+  assert.equal(testing.isPeak(beijingAt(1, 12, 0)), false);
+  assert.equal(testing.isPeak(beijingAt(1, 14, 0)), true);
+  assert.equal(testing.isPeak(beijingAt(1, 17, 59)), true);
+  assert.equal(testing.isPeak(beijingAt(1, 18, 0)), false);
+});
+
+check('deepseek-flash（V4.1-Flash）高峰价为官方三档（0.04 / 2 / 8）', () => {
+  const rates = testing.ratesFor('deepseek-flash', MONDAY_PEAK);
+  assert.equal(rates.peak, true);
+  assert.equal(rates.cacheHit, 0.04);
+  assert.equal(rates.cacheMiss, 2);
+  assert.equal(rates.output, 8);
+});
+
+check('两个旧模型名已下线但按 Flash 价计费，必须与 deepseek-flash 同价', () => {
+  // 官方定价页注(1)：旧名 deepseek-v4-flash / deepseek-v4-flash-vision-exp 的请求
+  // 由 DeepSeek-V4.1-Flash 提供服务，并按 Flash 价格计费。
+  const flash = testing.ratesFor('deepseek-flash', MONDAY_PEAK);
+  for (const legacy of ['deepseek-v4-flash', 'deepseek-v4-flash-vision-exp']) {
+    const rates = testing.ratesFor(legacy, MONDAY_PEAK);
+    assert.ok(rates !== undefined, `${legacy} 必须有价（否则界面会显示"未配置单价"）`);
+    assert.deepEqual(
+      { cacheHit: rates.cacheHit, cacheMiss: rates.cacheMiss, output: rates.output },
+      { cacheHit: flash.cacheHit, cacheMiss: flash.cacheMiss, output: flash.output },
+    );
+  }
+});
+
+check('deepseek-v4-pro 价格未变（0.3 / 9 / 27）', () => {
+  const rates = testing.ratesFor('deepseek-v4-pro', MONDAY_PEAK);
+  assert.equal(rates.cacheHit, 0.3);
+  assert.equal(rates.cacheMiss, 9);
+  assert.equal(rates.output, 27);
+});
+
+check('路由下发的价格表优先于 bundle 内联的兜底表（改价无需重建）', () => {
+  const custom = { 'my-model': { cacheHit: 1, cacheMiss: 2, output: 3 } };
+  const rates = testing.ratesFor('my-model', MONDAY_PEAK, custom);
+  assert.ok(rates !== undefined, '自定义表里的模型应可计价');
+  assert.equal(rates.output, 3);
+  // 自定义表里没有的模型不会被兜底表"救活"，避免两表混用的错觉
+  assert.equal(testing.ratesFor('deepseek-flash', MONDAY_PEAK, custom), undefined);
+  assert.ok(testing.priceTable({ prices: custom }) === custom, 'priceTable 应返回路由下发的表');
+  assert.ok(testing.priceTable(null) !== custom, '无下发时退回内联兜底表');
+});
+
+check('空闲时段价格为高峰的一半', () => {
+  const peak = testing.ratesFor('deepseek-v4-flash', MONDAY_PEAK);
+  const off = testing.ratesFor('deepseek-v4-flash', MONDAY_EVENING);
+  assert.equal(off.peak, false);
+  assert.equal(off.cacheHit, peak.cacheHit / 2);
+  assert.equal(off.cacheMiss, peak.cacheMiss / 2);
+  assert.equal(off.output, peak.output / 2);
+});
+
+check('未登记模型返回 undefined（而不是伪造单价）', () => {
+  assert.equal(testing.ratesFor('some-unknown-model', MONDAY_PEAK), undefined);
+});
+
+check('TokenUsage → 四个计费桶，缺字段与负数按 0 处理', () => {
+  assert.deepEqual(plain(testing.bucketsOf({ inputTokens: 10, outputTokens: 5 })), {
+    cacheMiss: 10,
+    cacheRead: 0,
+    cacheWrite: 0,
+    output: 5,
+  });
+  assert.deepEqual(plain(testing.bucketsOf({ inputTokens: -1, outputTokens: 2, cacheReadTokens: 3 })), {
+    cacheMiss: 0,
+    cacheRead: 3,
+    cacheWrite: 0,
+    output: 2,
+  });
+  assert.deepEqual(plain(testing.bucketsOf(undefined)), {
+    cacheMiss: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    output: 0,
+  });
+});
+
+check('推理 token 不重复计入（reasoningTokens 不属于任何桶）', () => {
+  const buckets = testing.bucketsOf({ inputTokens: 100, outputTokens: 50, reasoningTokens: 40 });
+  assert.equal(buckets.output, 50);
+});
+
+check('金额 = 各桶 × 对应单价（百万 tokens）', () => {
+  const peak = testing.ratesFor('deepseek-v4-flash', MONDAY_PEAK);
+  // 每桶各 100 万 tokens（deepseek-flash 高峰价）：2（未命中）+ 0.04（命中）+ 8（输出）= 10.04
+  const cost = testing.costOf({ cacheMiss: 1e6, cacheRead: 1e6, cacheWrite: 0, output: 1e6 }, peak);
+  assert.equal(Math.round(cost * 1e6) / 1e6, 10.04);
+});
+
+check('缓存写入并入“缓存未命中”档计费', () => {
+  const peak = testing.ratesFor('deepseek-v4-flash', MONDAY_PEAK);
+  const writeOnly = testing.costOf({ cacheMiss: 0, cacheRead: 0, cacheWrite: 1e6, output: 0 }, peak);
+  assert.equal(Math.round(writeOnly * 1e6) / 1e6, 2);
+});
+
+check('小额金额保留有效位，不显示成 ¥0.00', () => {
+  assert.equal(testing.formatMoney(0), '¥0');
+  assert.equal(testing.formatMoney(0.0004), '¥0.0004');
+  assert.equal(testing.formatMoney(0.032), '¥0.032');
+  assert.equal(testing.formatMoney(0.5432), '¥0.543');
+  assert.equal(testing.formatMoney(12.345), '¥12.35');
+});
+
+// ─────────────────────────────────────────────── 轮次折叠
+console.log('\n轮次折叠');
+
+const nodes = [
+  {
+    kind: 'assistant',
+    turn: 1,
+    step: 1,
+    time: MONDAY_PEAK,
+    usage: { inputTokens: 1000, outputTokens: 200 },
+  },
+  {
+    kind: 'assistant',
+    turn: 1,
+    step: 2,
+    time: MONDAY_PEAK,
+    usage: { inputTokens: 500, outputTokens: 100, cacheReadTokens: 300 },
+  },
+  // 非 assistant 节点必须被忽略
+  { kind: 'tool-result', turn: 1, time: MONDAY_PEAK, callTime: MONDAY_PEAK - 10 },
+  { kind: 'user', turn: 1, time: MONDAY_PEAK },
+  // 跨到空闲时段的第二轮
+  {
+    kind: 'assistant',
+    turn: 2,
+    step: 1,
+    time: MONDAY_EVENING,
+    usage: { inputTokens: 2000, outputTokens: 400, cacheWriteTokens: 100 },
+  },
+];
+
+const folded = testing.foldTurns(nodes);
+
+check('按轮次汇总用量，忽略非 assistant 节点', () => {
+  assert.equal(folded.perTurn.size, 2);
+  assert.deepEqual(plain(folded.perTurn.get(1).buckets), {
+    cacheMiss: 1500,
+    cacheRead: 300,
+    cacheWrite: 0,
+    output: 300,
+  });
+  assert.deepEqual(plain(folded.perTurn.get(2).buckets), {
+    cacheMiss: 2000,
+    cacheRead: 0,
+    cacheWrite: 100,
+    output: 400,
+  });
+});
+
+check('lastTurn 取最大轮次号', () => {
+  assert.equal(folded.lastTurn, 2);
+});
+
+check('会话总用量为各轮之和', () => {
+  assert.deepEqual(plain(folded.sessionBuckets), {
+    cacheMiss: 3500,
+    cacheRead: 300,
+    cacheWrite: 100,
+    output: 700,
+  });
+});
+
+check('空节点列表不产生轮次', () => {
+  const empty = testing.foldTurns([]);
+  assert.equal(empty.lastTurn, null);
+  assert.equal(empty.perTurn.size, 0);
+});
+
+// ─────────────────────────────────────────────── 客户端注册
+console.log('\n客户端注册');
+
+const registrations = [];
+const locales = [];
+clientExports.apply({
+  effect: (fn) => {
+    fn();
+    return () => {};
+  },
+  locale: { register: (ns, dict) => locales.push({ ns, dict }) },
+  slots: {
+    inject: (name, factory) => factory(),
+    register: (entry, component) => registrations.push({ entry, component }),
+  },
+});
+
+check('把金额行注册进 conversation.composer.dock', () => {
+  // apply() 先注册金额行、再注册价格行；下面的断言与渲染用例都依赖这个顺序。
+  const rows = registrations.filter((item) => item.entry.name === 'conversation.composer.dock');
+  assert.equal(rows.length, 1);
+  assert.equal(registrations[0], rows[0], '金额行应当是第一个注册的席位');
+  assert.equal(registrations[0].entry.id, 'billing');
+  assert.ok(registrations[0].entry.order > 0, 'order 应排在 ui-conversation 的 stats（order 0）之后');
+  assert.equal(registrations[0].entry.locale, 'billing');
+  assert.equal(typeof registrations[0].component, 'function');
+});
+
+check('跨版本节点选择器：0.1.5 的 s.legacy.nodes 与 0.1.1 的 s.chat.legacy.nodes 都认', () => {
+  const arr = [{ kind: 'assistant', turn: 1 }];
+  assert.equal(testing.selectNodes({ legacy: { nodes: arr } }), arr, '0.1.5 形状');
+  assert.equal(testing.selectNodes({ chat: { legacy: { nodes: arr } } }), arr, '0.1.1 形状');
+});
+
+check('节点选择器对畸形 store 返回稳定空数组（避免重渲染循环）', () => {
+  const a = testing.selectNodes(undefined);
+  const b = testing.selectNodes({});
+  const c = testing.selectNodes({ legacy: null });
+  const d = testing.selectNodes({ chat: {} });
+  assert.ok(Array.isArray(a) && a.length === 0);
+  assert.equal(a, b, '必须是同一个稳定引用');
+  assert.equal(b, c);
+  assert.equal(c, d);
+});
+
+check('组件优先用 useChat（0.1.5+ 的座位）', () => {
+  const nodes = [{ kind: 'assistant', turn: 1, usage: { inputTokens: 100, outputTokens: 20 } }];
+  let called = 0;
+  const useChat = (selector) => {
+    called += 1;
+    return selector({ legacy: { nodes } });
+  };
+  const view = registrations[0].component({ useChat, t: testing.fallbackTranslate });
+  assert.ok(called > 0, '没有调用传入的 useChat 座位');
+  assert.ok(view && view.__jsx === true, '应当渲染出金额行');
+  assert.match(String(view.props.label), /余额/, 'tooltip 应带余额明细');
+});
+
+check('组件回退到 useSession（0.1.1 的座位）', () => {
+  const nodes = [{ kind: 'assistant', turn: 1, usage: { inputTokens: 100, outputTokens: 20 } }];
+  let called = 0;
+  const useSession = (selector) => {
+    called += 1;
+    return selector({ chat: { legacy: { nodes } } });
+  };
+  const view = registrations[0].component({ useSession, t: testing.fallbackTranslate });
+  assert.ok(called > 0, '没有调用传入的 useSession 座位');
+  assert.ok(view && view.__jsx === true, '应当渲染出金额行');
+});
+
+check('两个座位都没有时静默不渲染（不抛错）', () => {
+  const view = registrations[0].component({ t: testing.fallbackTranslate });
+  assert.equal(view, null);
+});
+
+check('注册时声明 inject 回调，把会话 id 注入组件 props', () => {
+  const { inject } = registrations[0].entry;
+  assert.equal(typeof inject, 'function', '缺少 inject 回调 → 拿不到 sessionId，只能按默认路由计价');
+  // 逐个断言属性：vm 跨 realm 的对象原型不同，且 JSON 往返会丢掉 undefined，
+  // 所以这里不比对整体结构。
+  assert.equal(inject('sess-123').sessionId, 'sess-123');
+  assert.equal(inject(undefined).sessionId, undefined);
+  assert.equal(inject(42).sessionId, undefined, '非字符串必须被挡掉');
+  assert.equal(inject(null).sessionId, undefined);
+});
+
+check('注册 zh/en 文案字典', () => {
+  assert.equal(locales.length, 1);
+  assert.equal(locales[0].ns, 'billing');
+  assert.ok(locales[0].dict.zh, '缺少 zh 字典');
+  assert.ok(locales[0].dict.en, '缺少 en 字典');
+});
+
+check('zh 与 en 的键一一对应（避免某种语言漏文案）', () => {
+  const { zh, en } = locales[0].dict;
+  assert.deepEqual(Object.keys(zh).sort(), Object.keys(en).sort());
+});
+
+check('文案占位符在两份字典中一致', () => {
+  const placeholders = (text) => (String(text).match(/\{(\w+)\}/g) ?? []).sort();
+  for (const key of Object.keys(locales[0].dict.zh)) {
+    assert.deepEqual(
+      placeholders(locales[0].dict.zh[key]),
+      placeholders(locales[0].dict.en[key]),
+      `键 ${key} 的占位符不一致`,
+    );
+  }
+});
+
+// ─────────────────────────────────────────────── 视图装配
+console.log('\n视图装配');
+
+/** 从真实 zh 字典构造翻译函数，顺带验证字典本身可插值。 */
+const zhDictionary = locales[0].dict.zh;
+const fakeT = (key, params) => {
+  const template = zhDictionary[key];
+  assert.ok(template !== undefined, `字典缺少键 ${key}`);
+  if (params === undefined) return template;
+  return template.replace(/\{(\w+)\}/g, (_, name) => {
+    assert.ok(name in params, `键 ${key} 缺少参数 ${name}`);
+    return String(params[name]);
+  });
+};
+
+/** 一次成功的余额摘要（模型为 deepseek-v4-flash）。 */
+const okSummary = {
+  phase: 'ready',
+  data: {
+    ok: true,
+    currency: 'CNY',
+    balance: { state: 'ok', total: '45.26', granted: '0.00', toppedUp: '45.26' },
+    model: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+  },
+};
+
+check('余额组显示账户余额', () => {
+  const view = testing.composeView(folded, okSummary, fakeT);
+  assert.equal(view.groups[0], '余额 ¥45.26');
+});
+
+check('本轮金额按该轮时刻的档位独立算出（与视图内部实现无关地重算一遍）', () => {
+  const view = testing.composeView(folded, okSummary, fakeT);
+  // 最后轮次是 turn 2，发生在周一傍晚 → 空闲价（高峰价的一半）
+  const offPeak = { cacheMiss: 1, cacheHit: 0.02, output: 4 };
+  const expected = ((2000 + 100) * offPeak.cacheMiss + 0 * offPeak.cacheHit + 400 * offPeak.output) / 1e6;
+  assert.equal(view.groups[1], `本轮 ${testing.formatMoney(expected)}`);
+});
+
+check('会话金额为各轮按各自档位之和', () => {
+  const view = testing.composeView(folded, okSummary, fakeT);
+  const peak = { cacheMiss: 2, cacheHit: 0.04, output: 8 };
+  const offPeak = { cacheMiss: 1, cacheHit: 0.02, output: 4 };
+  const turn1 = ((1500 + 0) * peak.cacheMiss + 300 * peak.cacheHit + 300 * peak.output) / 1e6;
+  const turn2 = ((2000 + 100) * offPeak.cacheMiss + 0 * offPeak.cacheHit + 400 * offPeak.output) / 1e6;
+  assert.equal(view.groups[2], `本会话 ${testing.formatMoney(turn1 + turn2)}`);
+});
+
+check('hover 明细带上模型、档位、单价与 token 拆分', () => {
+  const view = testing.composeView(folded, okSummary, fakeT);
+  const detail = view.detail.join(' · ');
+  assert.match(detail, /余额 45\.26（赠送 0\.00 · 充值 45\.26）/);
+  assert.match(detail, /按 deepseek-v4-flash 计价（部署默认路由，未取到会话路由）/);
+  assert.match(detail, /空闲价 CNY\/百万 tokens：命中 0\.02 · 未命中 1 · 输出 4/);
+  assert.match(detail, /本轮 tokens 入 2\.1K（命中 0）· 出 400/);
+  assert.match(detail, /单价来源：/);
+});
+
+check('计价依据是该会话真实路由时，hover 明确标注', () => {
+  const summary = {
+    phase: 'ready',
+    data: {
+      ...okSummary.data,
+      model: { provider: 'deepseek-official', model: 'deepseek-v4-flash', source: 'session' },
+    },
+  };
+  const view = testing.composeView(folded, summary, fakeT);
+  assert.match(view.detail.join(' · '), /按 deepseek-v4-flash 计价（该会话实际路由）/);
+});
+
+check('未登记单价的模型只报 token，不编造金额', () => {
+  const summary = {
+    phase: 'ready',
+    data: { ...okSummary.data, model: { provider: 'x', model: 'mystery-model' } },
+  };
+  const view = testing.composeView(folded, summary, fakeT);
+  assert.equal(view.groups[0], '余额 ¥45.26');
+  assert.equal(view.groups[1], '本轮 未配置单价');
+  assert.equal(view.groups.length, 2, '未配置单价时不应出现会话金额');
+});
+
+check('余额接口失败时保留占位并在 hover 里给出原因', () => {
+  const summary = {
+    phase: 'ready',
+    data: {
+      ok: false,
+      currency: 'CNY',
+      model: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      error: { code: 'missing-credential', message: '未配置凭据 DEEPSEEK_API_KEY' },
+    },
+  };
+  const view = testing.composeView(folded, summary, fakeT);
+  assert.equal(view.groups[0], '余额 —');
+  assert.match(view.detail.join(' · '), /余额不可用：未配置凭据 DEEPSEEK_API_KEY/);
+});
+
+check('只有一轮时不显示会话金额（与 stats 行不重复）', () => {
+  const turnTwoNodes = nodes.filter((node) => node.kind === 'assistant' && node.turn === 2);
+  assert.equal(turnTwoNodes.length, 1, '样例里应当只有一个第二轮 assistant 节点');
+  const single = testing.foldTurns(turnTwoNodes);
+  assert.equal(single.perTurn.size, 1);
+  const view = testing.composeView(single, okSummary, fakeT);
+  assert.equal(view.groups.length, 2, '单轮时不应出现会话金额组');
+  assert.match(view.groups[0], /^余额 /);
+  assert.match(view.groups[1], /^本轮 /);
+});
+
+check('空会话只显示余额占位', () => {
+  const view = testing.composeView(testing.foldTurns([]), { phase: 'loading' }, fakeT);
+  assert.deepEqual([...view.groups], ['余额 —']);
+});
+
+check('缺 t 席位时用 zh 字典兜底，整行仍能渲染', () => {
+  const view = testing.composeView(folded, okSummary, testing.fallbackTranslate);
+  assert.equal(view.groups[0], '余额 ¥45.26');
+});
+
+check('兜底翻译遇到未知键返回键名而不是抛错', () => {
+  assert.equal(testing.fallbackTranslate('nope.missing'), 'nope.missing');
+  assert.equal(testing.fallbackTranslate('turn', { amount: '¥1' }), '本轮 ¥1');
+});
+
+check('英文文案同样可插值（en 字典不缺键）', () => {
+  const enDictionary = locales[0].dict.en;
+  const enT = (key, params) => {
+    const template = enDictionary[key];
+    assert.ok(template !== undefined, `en 字典缺少键 ${key}`);
+    if (params === undefined) return template;
+    return template.replace(/\{(\w+)\}/g, (_, name) => String(params[name]));
+  };
+  const view = testing.composeView(folded, okSummary, enT);
+  assert.match(view.groups[0], /^Balance ¥45\.26$/);
+  assert.match(view.groups[1], /^This turn ¥/);
+});
+
+check('复刻线上场景：model=deepseek-flash（settings.yaml 里的当前值）→ 出金额，不是"未配置单价"', () => {
+  // 这是截图里的真实情况：模型座位显示 DeepSeek-V41-Flash，settings 里写的是 deepseek-flash。
+  // 之前单价表只有旧的 deepseek-v4-flash，于是界面显示"未配置单价"。
+  const nodes = [
+    { kind: 'assistant', turn: 1, time: MONDAY_EVENING, usage: { inputTokens: 2000, outputTokens: 400 } },
+  ];
+  const summary = {
+    phase: 'ready',
+    data: {
+      ok: true,
+      currency: 'CNY',
+      balance: { state: 'ok', total: '52.18', granted: '0.00', toppedUp: '52.18' },
+      model: { provider: 'deepseek-official', model: 'deepseek-flash', source: 'session' },
+    },
+  };
+  const view = testing.composeView(testing.foldTurns(nodes), summary, fakeT);
+  assert.equal(view.groups[0], '余额 ¥52.18');
+  assert.match(view.groups[1], /^本轮 ¥\d/, `本轮必须是金额，实际 ${view.groups[1]}`);
+  assert.ok(!view.groups[1].includes('未配置单价'), '不应再显示"未配置单价"');
+  assert.match(view.detail.join(' · '), /按 deepseek-flash 计价/);
+});
+
+check('路由下发的价格表覆盖内联表时，界面用下发的价（改价热生效）', () => {
+  const nodes = [
+    { kind: 'assistant', turn: 1, time: MONDAY_EVENING, usage: { inputTokens: 1e6, outputTokens: 1e6, cacheReadTokens: 0 } },
+  ];
+  const base = {
+    phase: 'ready',
+    data: {
+      ok: true,
+      currency: 'CNY',
+      balance: { state: 'ok', total: '1.00', granted: '0', toppedUp: '1.00' },
+      model: { provider: 'p', model: 'deepseek-flash', source: 'session' },
+    },
+  };
+  // 空闲价（周一傍晚）× 1M 未命中输入 + 1M 输出 = 1 + 4 = 5 元
+  const builtin = testing.composeView(testing.foldTurns(nodes), base, fakeT);
+  assert.equal(builtin.groups[1], '本轮 ¥5.00');
+  // 下发一张更贵的表（高峰 10 / 40，空闲减半 → 5 / 20）：1M 未命中 + 1M 输出 = 25 元
+  const override = {
+    phase: 'ready',
+    data: {
+      ...base.data,
+      priceSource: '测试覆盖表',
+      prices: { 'deepseek-flash': { cacheHit: 1, cacheMiss: 10, output: 40 } },
+    },
+  };
+  const served = testing.composeView(testing.foldTurns(nodes), override, fakeT);
+  assert.equal(served.groups[1], '本轮 ¥25.00', '应用下发价格表（注意覆盖表同样按空闲时段减半）');
+  assert.match(served.detail.join(' · '), /单价来源：测试覆盖表/);
+});
+
+check('数据链：0.1.5 形状 store → 折叠 → 出「本轮/本会话」金额', () => {
+  // 走真实链路：selectNodes 取节点 → foldTurns 折叠 → composeView 出文案。
+  // （不穿过组件：测试用的 React 替身不跑 effect/状态更新，测不了 fetch 那条路。）
+  const store = {
+    legacy: {
+      nodes: [
+        { kind: 'assistant', turn: 1, time: MONDAY_PEAK, usage: { inputTokens: 1000, outputTokens: 200 } },
+        { kind: 'assistant', turn: 2, time: MONDAY_EVENING, usage: { inputTokens: 2000, outputTokens: 400 } },
+      ],
+    },
+  };
+  const nodes = testing.selectNodes(store);
+  assert.equal(nodes.length, 2, '应能从 0.1.5 的 store 形状取到节点');
+  const folded2 = testing.foldTurns(nodes);
+  assert.equal(folded2.lastTurn, 2);
+  const view = testing.composeView(folded2, okSummary, fakeT);
+  assert.match(view.groups[0], /^余额 ¥45\.26$/);
+  assert.match(view.groups[1], /^本轮 ¥/, '第二轮应算出本轮金额');
+  assert.match(view.groups[2], /^本会话 ¥/, '两轮应有本会话金额');
+  assert.match(view.detail.join(' · '), /按 deepseek-v4-flash 计价（部署默认路由，未取到会话路由）/);
+});
+
+// ─────────────────────────────────────────────── Host 侧
+console.log('\nHost 侧');
+
+const { createPricingReader } = await import('../lib/pricing.js');
+const { apply: hostApply } = await import('../lib/index.js');
+
+/** 采集路由注册。 */
+const routes = [];
+const hostCtx = {
+  effect: (fn) => {
+    fn();
+    return () => {};
+  },
+  inject: (deps, fn) => fn(hostCtx),
+  get: () => undefined,
+  logger: { info: () => {}, warn: () => {} },
+  webServer: {
+    register: (route) => {
+      routes.push(route);
+      return () => {};
+    },
+  },
+};
+
+// 让“缺凭据”这条路径可复现：指向一个必然不存在的环境变量名。
+process.env.DSH_BILLING_API_KEY_ENV = 'DSH_BILLING_ABSENT_KEY_FOR_TEST';
+
+hostApply(hostCtx);
+
+const summaryRoute = routes.find((route) => route.path === '/plugins/billing/summary');
+const pricesRoute = routes.find((route) => route.path === '/plugins/billing/prices');
+
+check('注册了余额摘要路由与价格表路由', () => {
+  assert.ok(summaryRoute, '缺 /plugins/billing/summary');
+  assert.equal(summaryRoute.kind, 'exact');
+  assert.equal(typeof summaryRoute.handler, 'function');
+  assert.ok(pricesRoute, '缺 /plugins/billing/prices');
+  assert.equal(pricesRoute.kind, 'prefix', '价格表路由要一次挂住 GET 与 POST 两个子路径');
+  assert.equal(typeof pricesRoute.handler, 'function');
+});
+
+/** 最小 http 响应替身，记录写出的状态码与正文。 */
+function fakeResponse() {
+  const captured = { status: null, headers: null, body: undefined };
+  return {
+    captured,
+    headersSent: false,
+    writeHead(status, headers) {
+      captured.status = status;
+      captured.headers = headers;
+      this.headersSent = true;
+    },
+    end(body) {
+      captured.body = body;
+    },
+  };
+}
+
+// ── 数据面鉴权（与 /api 对齐）──
+console.log('Host 侧 · 鉴权');
+
+/** 带自定义 connection 服务的 ctx（用它模拟新版 dsh 的 cookie 鉴权）。 */
+function ctxWithAuth(reject) {
+  const registered = [];
+  const c = {
+    effect: (fn) => {
+      fn();
+      return () => {};
+    },
+    logger: { info: () => {}, warn: () => {} },
+    webServer: {
+      register: (route) => {
+        registered.push(route);
+        return () => {};
+      },
+    },
+    get: (name) => (name === 'connection' ? { requestRejection: reject } : undefined),
+  };
+  c.inject = (deps, fn) => fn(c);
+  hostApply(c);
+  return registered[0];
+}
+
+await checkAsync('未认证时返回 401（与 /api 一致），且不碰余额接口', async () => {
+  const route = ctxWithAuth(() => 401);
+  const res = fakeResponse();
+  await route.handler({ method: 'GET', url: '/plugins/billing/summary' }, res);
+  assert.equal(res.captured.status, 401);
+  assert.match(String(res.captured.body), /authentication required/);
+});
+
+await checkAsync('权威不受信时返回 403（Host/Origin 围栏）', async () => {
+  const route = ctxWithAuth(() => 403);
+  const res = fakeResponse();
+  await route.handler({ method: 'GET', url: '/plugins/billing/summary' }, res);
+  assert.equal(res.captured.status, 403);
+  assert.match(String(res.captured.body), /forbidden/);
+});
+
+await checkAsync('准入通过时正常返回余额摘要', async () => {
+  const route = ctxWithAuth((req) => (req.headers?.cookie === 'dsh-auth-x=ok' ? undefined : 401));
+  const res = fakeResponse();
+  await route.handler(
+    { method: 'GET', url: '/plugins/billing/summary', headers: { cookie: 'dsh-auth-x=ok' } },
+    res,
+  );
+  assert.equal(res.captured.status, 200);
+  assert.equal(JSON.parse(res.captured.body).ok, false);
+});
+
+await checkAsync('鉴权服务抛错时按拒绝处理（数据面宁可 401）', async () => {
+  const route = ctxWithAuth(() => {
+    throw new Error('boom');
+  });
+  const res = fakeResponse();
+  await route.handler({ method: 'GET', url: '/plugins/billing/summary' }, res);
+  assert.equal(res.captured.status, 401);
+});
+
+await checkAsync('旧版没有 connection 服务时跳过校验（向后兼容）', async () => {
+  const res = fakeResponse();
+  await summaryRoute.handler({ method: 'GET', url: '/plugins/billing/summary' }, res);
+  assert.equal(res.captured.status, 200, '旧版部署不应因为缺少鉴权服务而 401');
+});
+
+await checkAsync('非 GET 请求返回 405 且不发网络请求', async () => {
+  const res = fakeResponse();
+  await summaryRoute.handler({ method: 'POST' }, res);
+  assert.equal(res.captured.status, 405);
+  assert.equal(res.captured.headers.allow, 'GET, HEAD');
+});
+
+await checkAsync('缺凭据时返回可解析的 JSON 失败响应（而非 500 或挂住）', async () => {
+  const res = fakeResponse();
+  await summaryRoute.handler({ method: 'GET' }, res);
+  assert.equal(res.captured.status, 200);
+  assert.equal(res.captured.headers['content-type'], 'application/json; charset=utf-8');
+  const body = JSON.parse(res.captured.body);
+  assert.equal(body.ok, false);
+  assert.equal(body.error.code, 'missing-credential');
+  assert.match(body.error.message, /未配置凭据/);
+});
+
+await checkAsync('失败响应里绝不出现密钥字样', async () => {
+  const res = fakeResponse();
+  const previous = process.env.DSH_BILLING_ABSENT_KEY_FOR_TEST;
+  process.env.DSH_BILLING_ABSENT_KEY_FOR_TEST = 'sk-super-secret-value';
+  try {
+    await summaryRoute.handler({ method: 'GET' }, res);
+  } finally {
+    if (previous === undefined) delete process.env.DSH_BILLING_ABSENT_KEY_FOR_TEST;
+    else process.env.DSH_BILLING_ABSENT_KEY_FOR_TEST = previous;
+  }
+  const body = JSON.parse(res.captured.body);
+  // 配了密钥却没有 credentials 服务时，会走环境兜底并尝试联网；
+  // 无论成败，正文都不该出现密钥本身。
+  assert.ok(!String(res.captured.body).includes('sk-super-secret-value'), '响应正文泄露了密钥');
+  assert.ok(body.ok === true || typeof body.error?.code === 'string');
+});
+
+// ── 价格读取器（Host 侧，可热更新）──
+console.log('\nHost 侧 · 价格读取器');
+
+check('内置表：读到 pricing.json 且含当前在用的 deepseek-flash', () => {
+  // 这条只验内置表；读取器要显式指定一个空的 home，免得被真实 ~/.dsh 里的覆盖文件影响。
+  const isolated = createPricingReader({ home: mkdtempSync(join(tmpdir(), 'billing-builtin-')), ttlMs: 0 });
+  const info = isolated.read();
+  assert.ok(Object.keys(info.prices).length >= 4, `至少 4 个模型，实际 ${Object.keys(info.prices).length}`);
+  assert.deepEqual(info.prices['deepseek-flash'], { cacheHit: 0.04, cacheMiss: 2, output: 8 });
+  assert.equal(info.currency, 'CNY');
+  assert.match(String(info.source), /DeepSeek 官方定价页/);
+});
+
+check('覆盖文件：新增模型、改价、并采用其 source', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'billing-prices-'));
+  const overridePath = join(dir, 'billing-prices.json');
+  writeFileSync(overridePath, JSON.stringify({
+    source: '本机覆盖 · 测试',
+    peakPrices: {
+      'my-custom-model': { cacheHit: 1, cacheMiss: 2, output: 3 },
+      'deepseek-flash': { cacheHit: 9, cacheMiss: 9, output: 9 },
+    },
+  }));
+  const info = createPricingReader({ overridePath, ttlMs: 0 }).read();
+  assert.deepEqual(info.prices['my-custom-model'], { cacheHit: 1, cacheMiss: 2, output: 3 });
+  assert.deepEqual(info.prices['deepseek-flash'], { cacheHit: 9, cacheMiss: 9, output: 9 }, '覆盖应生效');
+  assert.equal(info.source, '本机覆盖 · 测试');
+  assert.equal(info.overrideUsed, true);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+check('覆盖文件里的畸形记录被忽略，不影响其它条目', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'billing-prices-'));
+  const overridePath = join(dir, 'billing-prices.json');
+  writeFileSync(overridePath, JSON.stringify({
+    peakPrices: {
+      'bad-1': { cacheHit: 'x', cacheMiss: 2, output: 3 },
+      'bad-2': { cacheHit: 1, cacheMiss: -1, output: 3 },
+      'bad-3': null,
+      'good-one': { cacheHit: 0.5, cacheMiss: 1, output: 2 },
+    },
+  }));
+  const info = createPricingReader({ overridePath, ttlMs: 0 }).read();
+  for (const bad of ['bad-1', 'bad-2', 'bad-3']) assert.equal(info.prices[bad], undefined, `${bad} 应被忽略`);
+  assert.deepEqual(info.prices['good-one'], { cacheHit: 0.5, cacheMiss: 1, output: 2 });
+  rmSync(dir, { recursive: true, force: true });
+});
+
+check('覆盖文件不存在时不报错，只有内置表', () => {
+  const info = createPricingReader({ overridePath: join(tmpdir(), 'definitely-not-here-12345.json'), ttlMs: 0 }).read();
+  assert.ok(info.prices['deepseek-flash'] !== undefined);
+  assert.equal(info.overrideUsed, false);
+});
+
+check('TTL：缓存期内不重读，ttlMs=0 立即生效（改价无需重启的前提）', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'billing-prices-'));
+  const overridePath = join(dir, 'billing-prices.json');
+  writeFileSync(overridePath, JSON.stringify({ peakPrices: { m: { cacheHit: 1, cacheMiss: 1, output: 1 } } }));
+  const cached = createPricingReader({ overridePath, ttlMs: 60_000 });
+  assert.equal(cached.read().prices.m.output, 1);
+  writeFileSync(overridePath, JSON.stringify({ peakPrices: { m: { cacheHit: 2, cacheMiss: 2, output: 2 } } }));
+  assert.equal(cached.read().prices.m.output, 1, '缓存期内应返回旧值');
+  assert.equal(createPricingReader({ overridePath, ttlMs: 0 }).read().prices.m.output, 2, 'ttlMs=0 应立刻读到新值');
+  rmSync(dir, { recursive: true, force: true });
+});
+
+await checkAsync('响应里带 prices/priceSource（客户端优先用它 → 改价不用重建 bundle）', async () => {
+  const res = fakeResponse();
+  await summaryRoute.handler({ method: 'GET', url: '/plugins/billing/summary' }, res);
+  const body = JSON.parse(res.captured.body);
+  assert.ok(body.prices !== undefined && Object.keys(body.prices).length >= 4, '应下发价格表');
+  assert.deepEqual(body.prices['deepseek-flash'], { cacheHit: 0.04, cacheMiss: 2, output: 8 });
+  assert.match(String(body.priceSource), /DeepSeek 官方定价页/);
+});
+
+// ── 按会话解析计价模型 ──
+// 部署默认路由是 v4-pro，而会话实际跑 v4-flash（单价差 3 倍），
+// 因此这条路径必须能被独立验证：命中 / 失败退回 / 不带参数三种情况。
+console.log('\nHost 侧 · 按会话解析计价模型');
+
+/** 假会话日志：最后一条 request/context 才是权威值。 */
+const SESSION_EVENTS = [
+  { type: 'turn/start', data: { turn: 1 } },
+  { type: 'request/context', data: { provider: 'deepseek-official', model: 'deepseek-v4-pro' } },
+  { type: 'assistant/message', data: { turn: 1, step: 1, message: {}, usage: { inputTokens: 10, outputTokens: 5 } } },
+  { type: 'request/context', data: { provider: 'deepseek-official', model: 'deepseek-v4-flash' } },
+];
+
+const sessionRoutes = [];
+const sessionCtx = {
+  effect: (fn) => {
+    fn();
+    return () => {};
+  },
+  logger: { info: () => {}, warn: () => {} },
+  webServer: {
+    register: (route) => {
+      sessionRoutes.push(route);
+      return () => {};
+    },
+  },
+  get: (name) => {
+    if (name === 'sessionPersistence') {
+      return {
+        inspect: async (id) => {
+          if (id !== 'sess-ok') throw new Error(`unknown session ${id}`);
+          return { meta: {}, events: SESSION_EVENTS };
+        },
+      };
+    }
+    if (name === 'agentDefaultModel') {
+      return { currentSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-v4-pro' }) };
+    }
+    return undefined;
+  },
+};
+sessionCtx.inject = (deps, fn) => fn(sessionCtx);
+hostApply(sessionCtx);
+
+await checkAsync('带 session 参数时取该会话日志里最后一条 request/context', async () => {
+  const res = fakeResponse();
+  await sessionRoutes[0].handler({ method: 'GET', url: '/plugins/billing/summary?session=sess-ok' }, res);
+  const body = JSON.parse(res.captured.body);
+  assert.equal(body.model.model, 'deepseek-v4-flash', '应当取最后一条而非第一条');
+  assert.equal(body.model.provider, 'deepseek-official');
+  assert.equal(body.model.source, 'session');
+});
+
+await checkAsync('会话读取失败时退回部署默认路由，并标明来源', async () => {
+  const res = fakeResponse();
+  await sessionRoutes[0].handler({ method: 'GET', url: '/plugins/billing/summary?session=sess-missing' }, res);
+  const body = JSON.parse(res.captured.body);
+  assert.equal(body.model.model, 'deepseek-v4-pro');
+  assert.equal(body.model.source, 'default');
+});
+
+await checkAsync('不带 session 参数时用部署默认路由', async () => {
+  const res = fakeResponse();
+  await sessionRoutes[0].handler({ method: 'GET', url: '/plugins/billing/summary' }, res);
+  const body = JSON.parse(res.captured.body);
+  assert.equal(body.model.source, 'default');
+});
+
+await checkAsync('畸形 url 不会让处理器抛错', async () => {
+  const res = fakeResponse();
+  await sessionRoutes[0].handler({ method: 'GET', url: '::::not a url::::' }, res);
+  assert.equal(res.captured.status, 200);
+  const body = JSON.parse(res.captured.body);
+  assert.equal(typeof body.ok, 'boolean');
+});
+
+// ── 0.1.5+ 的句柄式 API（inspect 已被移除）──
+console.log('Host 侧 · 0.1.5 句柄式 API');
+
+const handleOpened = [];
+const handleRoutes = [];
+const handleCtx = {
+  effect: (fn) => {
+    fn();
+    return () => {};
+  },
+  logger: { info: () => {}, warn: () => {} },
+  webServer: {
+    register: (route) => {
+      handleRoutes.push(route);
+      return () => {};
+    },
+  },
+  get: (name) => {
+    if (name === 'sessionPersistence') {
+      return {
+        // 新 API：只有 open(id, mode)，没有 inspect
+        open: async (id, mode) => {
+          handleOpened.push({ id, mode });
+          if (id !== 'sess-ok') throw new Error(`unknown session ${id}`);
+          let closed = false;
+          return {
+            read: async () => ({ events: SESSION_EVENTS }),
+            close: async () => {
+              closed = true;
+            },
+            isClosed: () => closed,
+          };
+        },
+      };
+    }
+    if (name === 'agentDefaultModel') {
+      return { currentSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-v4-pro' }) };
+    }
+    return undefined;
+  },
+};
+handleCtx.inject = (deps, fn) => fn(handleCtx);
+hostApply(handleCtx);
+
+await checkAsync('句柄式 API 下也能取到会话真实模型', async () => {
+  const res = fakeResponse();
+  await handleRoutes[0].handler({ method: 'GET', url: '/plugins/billing/summary?session=sess-ok' }, res);
+  const body = JSON.parse(res.captured.body);
+  assert.equal(body.model.model, 'deepseek-v4-flash');
+  assert.equal(body.model.source, 'session');
+});
+
+await checkAsync('以只读模式打开句柄（不抢写所有权）', () => {
+  assert.ok(handleOpened.length > 0, '没有调用 open()');
+  for (const call of handleOpened) {
+    assert.equal(call.mode, 'read', `必须以 read 模式打开，实际是 ${call.mode}`);
+  }
+});
+
+await checkAsync('句柄式 API 读取失败时退回默认路由', async () => {
+  const res = fakeResponse();
+  await handleRoutes[0].handler({ method: 'GET', url: '/plugins/billing/summary?session=nope' }, res);
+  const body = JSON.parse(res.captured.body);
+  assert.equal(body.model.source, 'default');
+});
+
+await checkAsync('没有 sessionPersistence 服务时不崩，退回默认路由', async () => {
+  const res = fakeResponse();
+  await sessionRoutes[0].handler({ method: 'GET', url: '/plugins/billing/summary?session=whatever' }, res);
+  const body = JSON.parse(res.captured.body);
+  // 这个 ctx 里 inspect 对非 sess-ok 会抛错，因此走的是 default；
+  // 真正要守的是「不抛错、仍有可解析响应」。
+  assert.equal(res.captured.status, 200);
+  assert.equal(body.model.source, 'default');
+});
+
+if (process.env.DSH_BILLING_LIVE_TEST === '1') {
+  console.log('\n联网用例（DSH_BILLING_LIVE_TEST=1）');
+  delete process.env.DSH_BILLING_API_KEY_ENV;
+  // 用真实凭据 seam 需要完整的 Host 组合；这里直接读凭据文件所在环境，
+  // 因此仅断言路由在真实凭据下的响应形状。
+  await checkAsync('真实调用上游余额接口', async () => {
+    const { apply: liveApply } = await import('../lib/index.js');
+    const liveRoutes = [];
+    /** 与上面的 hostCtx 同构的替身：inject 必须把完整 ctx 交给回调。 */
+    const liveCtx = {
+      effect: (fn) => {
+        fn();
+        return () => {};
+      },
+      get: () => undefined,
+      logger: { info: () => {}, warn: () => {} },
+      webServer: {
+        register: (route) => {
+          liveRoutes.push(route);
+          return () => {};
+        },
+      },
+    };
+    liveCtx.inject = (deps, fn) => fn(liveCtx);
+    liveApply(liveCtx);
+    // 直接把凭据文件里的密钥交给进程环境，模拟本机已配置。
+    const credentialsPath = join(process.env.HOME ?? '', '.dsh', '.credentials.yaml');
+    const raw = readFileSync(credentialsPath, 'utf8');
+    const match = /DEEPSEEK_API_KEY:\s*(\S+)/.exec(raw);
+    assert.ok(match, '凭据文件里没有 DEEPSEEK_API_KEY');
+    process.env.DEEPSEEK_API_KEY = match[1];
+    const res = fakeResponse();
+    await liveRoutes[0].handler({ method: 'GET' }, res);
+    const body = JSON.parse(res.captured.body);
+    assert.equal(body.ok, true, `上游调用失败：${JSON.stringify(body.error)}`);
+    assert.equal(body.balance.state, 'ok');
+    assert.equal(typeof body.currency, 'string');
+    console.log(`     余额 ${body.balance.total} ${body.currency} · 模型 ${body.model?.model}`);
+  });
+}
+
+// ───────────────────────────────────── 排版契约（与原生用量行同一排）
+//
+// 这一组是给「看起来不像原生」这类退化兜底的：dock 里的条目要和
+// dsh-client-ui-chat 的 StatsPills 逐项对齐，否则一眼就能看出是外挂。
+
+check('金额行排版照抄原生用量行（字号 / 行高 / 胶囊内距）', () => {
+  const css = testing.CSS;
+  // dock 在输入卡片外面，不显式写字号就会继承 body 的 14px，而原生是 secondary-1px（默认 12px）。
+  assert.ok(
+    css.includes('var(--dsh-content-font-size-secondary,13px) - 1px'),
+    '缺原生的 secondary 字号公式',
+  );
+  assert.ok(
+    css.includes('calc(20px + var(--dsh-content-font-delta-secondary,0px))'),
+    '缺原生行高公式（1px 内距 + 20px 行高 = 与原生等高的 22px）',
+  );
+  assert.ok(css.includes('padding:1px 8px'), '胶囊内距应与原生一致');
+  assert.ok(css.includes('border-radius:999px'), '胶囊圆角应与原生一致');
+  assert.ok(css.includes('font-variant-numeric:tabular-nums'), '数字应对齐（等宽数字）');
+  assert.ok(css.includes('var(--dsw-alias-label-tertiary)'), '文字色应取原生三级文字色');
+});
+
+check('金额行不抢宽度、不用竖线分隔', () => {
+  const css = testing.CSS;
+  // 外层 .yhfFVG_dock 已经是 flex + 居中 + gap:12px；条目自己抢宽度会把原生两枚胶囊挤开。
+  assert.ok(!css.includes('text-align'), 'flex 子项上 text-align 无效，不应出现');
+  assert.ok(!/(^|[;{])width:100%/.test(css), '不应写成整宽（max-width:100% 可以）');
+  assert.ok(!css.includes('opacity'), '原生这一行没有任何 opacity，层级靠文字色 token');
+  assert.ok(!css.includes('margin:0 auto'), '不应自行居中，容器已经居中');
+  // 分隔符用原生中点，而不是竖线。
+  assert.ok(bundleSource.includes("children: '·'"), '分隔符应是原生中点 ·');
+  assert.ok(!bundleSource.includes("children: '|'"), '不应使用竖线分隔');
+});
+
+// ───────────────────────────────── 价格表：设置行按钮 + 宿主刷新路由
+
+check('把价格行注册进 settings.general.item（list 槽必须给 id）', () => {
+  const row = registrations.find((item) => item.entry.name === 'settings.general.item');
+  assert.ok(row, '没有注册价格设置行');
+  assert.equal(row.entry.id, 'billing-prices');
+  assert.equal(typeof row.entry.order, 'number');
+  assert.ok(row.entry.order > 12, 'order 应排在 外观/字号/护眼 之后');
+  assert.equal(typeof row.component, 'function');
+});
+
+/** 在独立的 vm realm 里加载 bundle，并注入 fetch（只有价格行用得到网络）。 */
+function loadBillingBundle(fetchImpl) {
+  let reg;
+  const sandbox = {
+    window: { __ModuleLoader__: { load: (row) => { reg = row; } } },
+    console,
+    fetch: fetchImpl,
+    setTimeout,
+  };
+  vm.runInNewContext(bundleSource, sandbox, { filename: 'lib/client.js' });
+  return reg.factory((specifier) => {
+    if (SHARED[specifier] === undefined) throw new Error(`未预料的共享模块请求：${specifier}`);
+    return SHARED[specifier];
+  });
+}
+
+/** 在假 jsx 树里按谓词收集节点（字符串子节点也算，文案断言要用）。 */
+function findNodes(node, match, out = []) {
+  if (node === null || node === undefined) return out;
+  if (typeof node !== 'object') {
+    if (match(node)) out.push(node);
+    return out;
+  }
+  if (match(node)) out.push(node);
+  const children = node.props?.children;
+  if (Array.isArray(children)) children.forEach((child) => findNodes(child, match, out));
+  else if (children !== undefined) findNodes(children, match, out);
+  return out;
+}
+
+await checkAsync('价格行渲染出当前来源与官方 Button', async () => {
+  const bundle = loadBillingBundle(async () => ({
+    ok: true,
+    json: async () => ({ ok: true, source: 'DeepSeek 官方定价页 · 2026-09-18 抓取', updatedAt: '2026-09-18' }),
+  }));
+  const view = bundle.__testing.PricesRow({ t: testing.fallbackTranslate });
+  const texts = findNodes(view, (node) => typeof node === 'string');
+  assert.ok(JSON.stringify(texts).includes('用量价格表'), '缺标题');
+  const buttons = findNodes(view, (node) => node.type === SHARED['@deepseek-ai/dsh-client-ui-primitives'].Button);
+  assert.equal(buttons.length, 1, '应当渲染一个官方 Button');
+  assert.equal(buttons[0].props.children, '立即更新');
+  assert.equal(buttons[0].props.disabled, false);
+});
+
+await checkAsync('点按钮：POST 刷新路由、按结果递增价格版本号（金额行随即重算）', async () => {
+  const calls = [];
+  const bundle = loadBillingBundle(async (url, init) => {
+    calls.push({ url, method: init?.method ?? 'GET' });
+    if ((init?.method ?? 'GET') === 'GET') {
+      return { ok: true, json: async () => ({ ok: true, source: '旧表', updatedAt: '2026-09-18' }) };
+    }
+    return {
+      ok: true,
+      json: async () => ({ ok: true, changed: ['deepseek-flash'], source: '新表', updatedAt: '2026-10-09' }),
+    };
+  });
+  assert.equal(bundle.__testing.pricesEpochOf(), 0);
+  const view = bundle.__testing.PricesRow({ t: testing.fallbackTranslate });
+  const button = findNodes(view, (node) => node.type === SHARED['@deepseek-ai/dsh-client-ui-primitives'].Button)[0];
+  await button.props.onClick();
+  assert.deepEqual(
+    calls.map((call) => call.method + ' ' + call.url),
+    ['GET ' + bundle.__testing.PRICES_URL, 'POST ' + bundle.__testing.PRICES_REFRESH_URL],
+  );
+  assert.equal(bundle.__testing.pricesEpochOf(), 1, '成功更新后应通知金额行重算');
+});
+
+await checkAsync('按钮失败路径：刷新接口报错时不递增版本号、把原因交给界面', async () => {
+  const bundle = loadBillingBundle(async (url, init) => {
+    if ((init?.method ?? 'GET') === 'GET') {
+      return { ok: true, json: async () => ({ ok: true, source: '旧表' }) };
+    }
+    return {
+      ok: false,
+      status: 502,
+      json: async () => ({ ok: false, error: 'refresh-failed', message: '不满足「空闲 = 高峰的一半」' }),
+    };
+  });
+  const view = bundle.__testing.PricesRow({ t: testing.fallbackTranslate });
+  await findNodes(view, (node) => node.type === SHARED['@deepseek-ai/dsh-client-ui-primitives'].Button)[0].props.onClick();
+  assert.equal(bundle.__testing.pricesEpochOf(), 0, '失败时不应动价格版本号');
+});
+
+/** 官方页的最小夹具：两个模型、时段交替、空闲 = 高峰一半。 */
+const OFFICIAL_PAGE_HTML = `<html><body><table>
+<tr><td>模型</td><td>deepseek-flash(1)</td><td>deepseek-v4-pro</td></tr>
+<tr><td>价格(2)</td></tr>
+<tr><td>百万tokens输入（缓存命中）</td><td>空闲时段</td><td>0.02元</td><td>0.15元</td></tr>
+<tr><td>高峰时段</td><td>0.04元</td><td>0.30元</td></tr>
+<tr><td>百万tokens输入（缓存未命中）</td><td>空闲时段</td><td>1元</td><td>4.5元</td></tr>
+<tr><td>高峰时段</td><td>2元</td><td>9.0元</td></tr>
+<tr><td>百万tokens输出</td><td>空闲时段</td><td>4元</td><td>13.5元</td></tr>
+<tr><td>高峰时段</td><td>8元</td><td>27.0元</td></tr>
+<tr><td>并发限制(3)</td><td>2500</td><td>500</td></tr>
+</table></body></html>`;
+
+await checkAsync('宿主刷新路由：抓官方页 → 写本机覆盖文件 → 报出变化（按钮背后就是这个）', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'billing-refresh-'));
+  const previousHome = process.env.DSH_HOME;
+  const realFetch = globalThis.fetch;
+  process.env.DSH_HOME = dir;
+  globalThis.fetch = async () => ({ ok: true, status: 200, text: async () => OFFICIAL_PAGE_HTML });
+  try {
+    const registered = [];
+    const ctx = {
+      effect: (fn) => { fn(); return () => {}; },
+      inject: (deps, fn) => fn(ctx),
+      get: () => undefined,
+      logger: { info: () => {}, warn: () => {} },
+      webServer: { register: (route) => { registered.push(route); return () => {}; } },
+    };
+    hostApply(ctx);
+    const route = registered.find((item) => item.path === '/plugins/billing/prices');
+    const res = fakeResponse();
+    await route.handler({ method: 'POST', url: '/plugins/billing/prices/refresh' }, res);
+    const body = JSON.parse(res.captured.body);
+    assert.equal(res.captured.status, 200, res.captured.body);
+    assert.equal(body.ok, true);
+    // 覆盖文件真的落盘了，且 Host 立刻用上了新表（不用等 TTL）
+    const written = JSON.parse(readFileSync(join(dir, 'billing-prices.json'), 'utf8'));
+    assert.deepEqual(written.peakPrices['deepseek-flash'], { cacheHit: 0.04, cacheMiss: 2, output: 8 });
+    assert.equal(body.overrideUsed, true);
+    assert.equal(body.updatedAt, new Date().toISOString().slice(0, 10));
+  } finally {
+    globalThis.fetch = realFetch;
+    if (previousHome === undefined) delete process.env.DSH_HOME;
+    else process.env.DSH_HOME = previousHome;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+await checkAsync('宿主刷新路由：官方页改版时 502 且**一个字节都不写**', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'billing-refresh-bad-'));
+  const previousHome = process.env.DSH_HOME;
+  const realFetch = globalThis.fetch;
+  process.env.DSH_HOME = dir;
+  // 把「输出 高峰」改成 9 → 不再是空闲(4)的两倍，结构自校验必须拦下
+  globalThis.fetch = async () => ({
+    ok: true,
+    status: 200,
+    text: async () => OFFICIAL_PAGE_HTML.replace('8元', '9元'),
+  });
+  try {
+    const registered = [];
+    const ctx = {
+      effect: (fn) => { fn(); return () => {}; },
+      inject: (deps, fn) => fn(ctx),
+      get: () => undefined,
+      logger: { info: () => {}, warn: () => {} },
+      webServer: { register: (route) => { registered.push(route); return () => {}; } },
+    };
+    hostApply(ctx);
+    const route = registered.find((item) => item.path === '/plugins/billing/prices');
+    const res = fakeResponse();
+    await route.handler({ method: 'POST', url: '/plugins/billing/prices/refresh' }, res);
+    assert.equal(res.captured.status, 502);
+    assert.match(JSON.parse(res.captured.body).message, /空闲 = 高峰的一半/);
+    assert.equal(existsSync(join(dir, 'billing-prices.json')), false, '自校验失败时不应写文件');
+  } finally {
+    globalThis.fetch = realFetch;
+    if (previousHome === undefined) delete process.env.DSH_HOME;
+    else process.env.DSH_HOME = previousHome;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+await checkAsync('宿主价格路由：GET 报当前来源、未认证 401、非 POST 405、未知子路径 404', async () => {
+  const registered = [];
+  const ctx = {
+    effect: (fn) => { fn(); return () => {}; },
+    inject: (deps, fn) => fn(ctx),
+    get: (name) => (name === 'connection' ? { requestRejection: () => 401 } : undefined),
+    logger: { info: () => {}, warn: () => {} },
+    webServer: { register: (route) => { registered.push(route); return () => {}; } },
+  };
+  hostApply(ctx);
+  const route = registered.find((item) => item.path === '/plugins/billing/prices');
+  const denied = fakeResponse();
+  await route.handler({ method: 'GET', url: '/plugins/billing/prices' }, denied);
+  assert.equal(denied.captured.status, 401, '写文件的能力必须和 /api 同级鉴权');
+
+  const open = [];
+  const ctx2 = {
+    effect: (fn) => { fn(); return () => {}; },
+    inject: (deps, fn) => fn(ctx2),
+    get: () => undefined,
+    logger: { info: () => {}, warn: () => {} },
+    webServer: { register: (route) => { open.push(route); return () => {}; } },
+  };
+  hostApply(ctx2);
+  const route2 = open.find((item) => item.path === '/plugins/billing/prices');
+  const read = fakeResponse();
+  await route2.handler({ method: 'GET', url: '/plugins/billing/prices' }, read);
+  assert.equal(read.captured.status, 200);
+  const info = JSON.parse(read.captured.body);
+  assert.equal(info.ok, true);
+  assert.ok(info.modelCount >= 4, '应报出模型个数');
+  assert.ok(typeof info.overridePath === 'string' && info.overridePath.endsWith('billing-prices.json'));
+
+  const wrongMethod = fakeResponse();
+  await route2.handler({ method: 'GET', url: '/plugins/billing/prices/refresh' }, wrongMethod);
+  assert.equal(wrongMethod.captured.status, 405);
+
+  const missing = fakeResponse();
+  await route2.handler({ method: 'GET', url: '/plugins/billing/prices/nope' }, missing);
+  assert.equal(missing.captured.status, 404);
+});
+
+// ───────────────────────────────── 官方定价页解析器（离线夹具，防页面改版后默默解析错）
+
+/** 仿官方中文定价页纯文本的关键片段（两个模型）。 */
+const PRICING_FIXTURE = [
+  '模型',
+  'deepseek-flash(1)',
+  'deepseek-v4-pro',
+  '价格(2)',
+  '百万tokens输入',
+  '（缓存命中）',
+  '空闲时段',
+  '0.02元',
+  '0.15元',
+  '高峰时段',
+  '0.04元',
+  '0.30元',
+  '百万tokens输入',
+  '（缓存未命中）',
+  '空闲时段',
+  '1元',
+  '4.5元',
+  '高峰时段',
+  '2元',
+  '9.0元',
+  '百万tokens输出',
+  '空闲时段',
+  '4元',
+  '13.5元',
+  '高峰时段',
+  '8元',
+  '27.0元',
+  '并发限制(3)',
+  '2500',
+  '500',
+].join('\n');
+
+check('解析官方定价页：按行序取高峰价，并认可旧模型名按 Flash 计价', () => {
+  const parsed = parsePricingText(PRICING_FIXTURE);
+  assert.deepEqual([...parsed.models], ['deepseek-flash', 'deepseek-v4-pro']);
+  assert.deepEqual(parsed.peakPrices['deepseek-flash'], { cacheHit: 0.04, cacheMiss: 2, output: 8 });
+  assert.deepEqual(parsed.peakPrices['deepseek-v4-pro'], { cacheHit: 0.3, cacheMiss: 9, output: 27 });
+  const aliased = withLegacyAliases(parsed.peakPrices);
+  assert.deepEqual(aliased['deepseek-v4-flash'], { cacheHit: 0.04, cacheMiss: 2, output: 8 });
+  assert.deepEqual(aliased['deepseek-v4-flash-vision-exp'], { cacheHit: 0.04, cacheMiss: 2, output: 8 });
+});
+
+check('解析器宁可失败也不写错钱：空闲 ≠ 高峰一半、缺行、非人民币都拒绝', () => {
+  // 把「输出 高峰」从 8 改成 9 → 不再是空闲(4)的两倍，说明行序/政策变了
+  const broken = PRICING_FIXTURE.replace('高峰时段\n8元', '高峰时段\n9元');
+  assert.throws(() => parsePricingText(broken), /空闲 = 高峰的一半/);
+  // 少一行时段标签（例如官方去掉空闲价）
+  const missing = PRICING_FIXTURE.replace('空闲时段\n4元\n13.5元\n', '');
+  assert.throws(() => parsePricingText(missing), /时段标签|个数/);
+  // 币种不是人民币
+  const usd = PRICING_FIXTURE.replace(/元/g, '美元');
+  assert.throws(() => parsePricingText(usd), /人民币/);
+});
+
+// ───────────────────────────── 插件清单元数据（插件页卡片上的图标 / 名称 / 描述）
+//
+// 卡片文案取 <包>/locale/<lang>.json 的 meta.title / meta.description，图标取 package.json
+// 的 icon（包内相对路径，宿主内联成 data URI）。注意 `./locale/*.json` 必须在 exports 里
+// 声明：宿主是按包名自引用解析这个子路径的，没声明会被 ERR_PACKAGE_PATH_NOT_EXPORTED 拒掉，
+// 卡片就**静默**回退成包名 + 包描述（不会有任何报错提示）。
+
+const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+
+check('清单：声明了 locale 子路径导出（否则读不到本地化名称/描述）', () => {
+  assert.ok(
+    Object.keys(manifest.exports ?? {}).includes('./locale/*.json'),
+    'package.json 的 exports 里缺 "./locale/*.json"',
+  );
+});
+
+check('清单：图标是包内相对图片，且不超过 256 KiB', () => {
+  const icon = manifest.icon;
+  assert.equal(typeof icon, 'string', 'package.json 缺 icon 字段');
+  assert.ok(!icon.startsWith('/') && !/^[a-z][a-z\d+.-]*:/i.test(icon), 'icon 必须是相对路径');
+  assert.ok(
+    ['.svg', '.png', '.jpg', '.jpeg', '.webp'].includes(extname(icon).toLowerCase()),
+    'icon 必须是 SVG / PNG / JPEG / WebP',
+  );
+  const file = join(root, icon);
+  assert.ok(existsSync(file), `图标文件不存在：${icon}`);
+  assert.ok(statSync(file).size <= 256 * 1024, '图标超过 256 KiB，宿主会拒绝读取');
+});
+
+check('清单：zh / en 都有 meta.title 与 meta.description，且中英不同', () => {
+  const zh = JSON.parse(readFileSync(join(root, 'locale', 'zh.json'), 'utf8')).meta;
+  const en = JSON.parse(readFileSync(join(root, 'locale', 'en.json'), 'utf8')).meta;
+  for (const [lang, meta] of [['zh', zh], ['en', en]]) {
+    assert.equal(typeof meta?.title, 'string', `${lang} 缺 meta.title`);
+    assert.equal(typeof meta?.description, 'string', `${lang} 缺 meta.description`);
+  }
+  assert.notEqual(zh.title, en.title, '中英标题相同，可能是漏了翻译');
+  assert.ok(zh.title.length <= 24, `中文标题偏长（${zh.title.length} 字），卡片会被截断`);
+  assert.ok(zh.description.length <= 60, `中文描述偏长（${zh.description.length} 字），卡片会被截断`);
+});
+
+console.log('');
+if (failures > 0) {
+  console.error(`自检失败：${failures} 项未通过 ❌`);
+  process.exit(1);
+}
+console.log('全部自检通过 ✅');