dsh-commandcode-quota 0.0.0-stage → 0.2.0

package/src/index.js

@@ -0,0 +1,311 @@
+/**
+ * dsh-commandcode-quota —— Command Code 余额额度仪表盘（单账号宿主端）
+ *
+ * 通过 Command Code 官方 API 读取余额与限额数据, 在 DSH Web 界面提供
+ * 一个与 OpenCode 余额查询类似的单账号仪表盘。
+ *
+ *   GET /__dsh-commandcode-quota/dashboard              → 余额 + 限额 + 用量
+ *   GET /__dsh-commandcode-quota/dashboard?scope=quick  → 余额优先，其余字段用缓存回填
+ *
+ * 数据源 (均为 Authorization: Bearer <key> 的 GET 请求):
+ *   GET {base}/alpha/billing/credits        余额 & 窗口限额
+ *   GET {base}/alpha/usage/summary          用量汇总
+ *   GET {base}/alpha/billing/subscriptions  订阅信息
+ *   GET {base}/alpha/whoami                 用户信息
+ *
+ * 凭据通过 ctx.credentials 服务解析，不向客户端返回 API key。
+ *
+ * 配置 (cordis.patch.yml):
+ *   apiKeyEnv: COMMANDCODE_API_KEY
+ *   fallbackEnv: COMMANDCODE2_API_KEY      # 可选回退凭据
+ *   baseURL: https://api.commandcode.ai
+ *
+ * ESM module format (cordis bundle rule): named exports apply/inject/name.
+ */
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+
+const name = "dsh-commandcode-quota";
+const inject = ["credentials"];
+
+const DEFAULT_BASE_URL = "https://api.commandcode.ai";
+const DEFAULT_API_KEY_ENV = "COMMANDCODE_API_KEY";
+// Command Code 的 usage / subscriptions / whoami 实测要 8~20s, 8s 超时必然误杀。
+const DEFAULT_TIMEOUT_MS = 30000;
+
+// --- HTTP helpers ------------------------------------------------------------
+
+function sendJson(res, status, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": Buffer.byteLength(body),
+    "cache-control": "no-store"
+  });
+  res.end(body);
+}
+
+function readQuery(req, key) {
+  try {
+    const url = new URL(req.url ?? "/", "http://x");
+    return url.searchParams.get(key);
+  } catch {
+    return null;
+  }
+}
+
+// --- Command Code API client -------------------------------------------------
+
+async function ccFetch(baseURL, path, apiKey, timeoutMs) {
+  const url = `${baseURL}${path}`;
+  const controller = new AbortController();
+  let timedOut = false;
+  const started = Date.now();
+  const timer = setTimeout(() => { timedOut = true; controller.abort(); }, timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method: "GET",
+      headers: {
+        authorization: `Bearer ${apiKey}`,
+        accept: "application/json",
+        "user-agent": "dsh-commandcode-quota/0.2.0"
+      },
+      signal: controller.signal
+    });
+    let json = null;
+    try { json = await res.json(); } catch { /* 非 JSON */ }
+    return { status: res.status, json, tookMs: Date.now() - started };
+  } catch (error) {
+    const detail = timedOut
+      ? `本插件超时 ${timeoutMs}ms (${Date.now() - started}ms)`
+      : `${error?.name ?? "Error"}: ${error?.message ?? String(error)} (${Date.now() - started}ms)`;
+    const wrapped = new Error(detail);
+    wrapped.cause = error;
+    wrapped.timedOut = timedOut;
+    throw wrapped;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** 连接级偶发失败 (TypeError: fetch failed / socket reset) 重试一次;
+ * 本插件主动超时不重试 —— 服务器本来就慢, 再等一轮更慢。 */
+async function ccFetchRetry(baseURL, path, apiKey, timeoutMs) {
+  try {
+    return await ccFetch(baseURL, path, apiKey, timeoutMs);
+  } catch (error) {
+    if (error?.timedOut) throw error;
+    return await ccFetch(baseURL, path, apiKey, timeoutMs);
+  }
+}
+
+/**
+ * 各接口的写入 / 快照 / 回填: 便于统一处理"成功则写 + 缓存, 失败则回退上次值"。
+ */
+const ENDPOINTS = [
+  ["credits", "/alpha/billing/credits"],
+  ["usage", "/alpha/usage/summary"],
+  ["subscriptions", "/alpha/billing/subscriptions"],
+  ["whoami", "/alpha/whoami"]
+];
+
+const HANDLERS = {
+  credits: {
+    apply(json, out) { out.balance = json.credits; out.windowLimits = json.windowLimits; },
+    snapshot(out) { return out.balance ? { balance: out.balance, windowLimits: out.windowLimits } : null; },
+    restore(snap, out) { out.balance = snap.balance; out.windowLimits = snap.windowLimits; }
+  },
+  usage: {
+    apply(json, out) { out.usage = json; },
+    snapshot(out) { return out.usage ?? null; },
+    restore(snap, out) { out.usage = snap; }
+  },
+  subscriptions: {
+    apply(json, out) { if (json.data) out.subscription = json.data; },
+    snapshot(out) { return out.subscription ?? null; },
+    restore(snap, out) { out.subscription = snap; }
+  },
+  whoami: {
+    apply(json, out) { if (json.user) out.user = json.user; },
+    snapshot(out) { return out.user ?? null; },
+    restore(snap, out) { out.user = snap; }
+  }
+};
+
+/**
+ * 上次成功值的进程内缓存。
+ * Command Code 的 usage / subscriptions / whoami 实测响应 8~20s 且偶发 500,
+ * 超时或报错时用上次成功值兜底, 避免面板闪出"订阅信息暂不可用"。
+ */
+const CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+const lastGood = new Map();
+
+function cacheGet(key) {
+  const hit = lastGood.get(key);
+  if (!hit) return null;
+  if (Date.now() - hit.at > CACHE_TTL_MS) return null;
+  return hit;
+}
+
+function cacheSet(key, value) {
+  if (value === undefined || value === null) return;
+  lastGood.set(key, { value, at: Date.now() });
+}
+
+/**
+ * 请求一个账号的完整仪表盘数据。
+ * 四个接口并行发出 (总耗时 = 最慢的一个, 而不是四个之和), 单接口失败不影响其他;
+ * 失败且曾有成功值时用缓存兜底, 并在 stale 里说明。
+ * onlyKeys 非空时只查这些接口 (scope=quick: 只查快的 credits),
+ * 其余字段用上次缓存回填, 并在 cached 里列出。
+ */
+async function fetchDashboard(cfg, timeoutMs, onlyKeys) {
+  const errors = [];
+  const stale = [];
+  const out = { ok: true, fetchedAt: Date.now(), errors, stale };
+
+  const list = Array.isArray(onlyKeys) && onlyKeys.length > 0
+    ? ENDPOINTS.filter(([key]) => onlyKeys.includes(key))
+    : ENDPOINTS;
+
+  const results = await Promise.all(list.map(async ([key, path]) => {
+    try {
+      const res = await ccFetchRetry(cfg.baseURL, path, cfg.apiKey, timeoutMs);
+      return { key, status: res.status, json: res.json };
+    } catch (error) {
+      return { key, error: String(error) };
+    }
+  }));
+
+  for (const r of results) {
+    const handler = HANDLERS[r.key];
+    if (!r.error && r.status === 200 && r.json) {
+      handler.apply(r.json, out);
+      cacheSet(r.key, handler.snapshot(out));
+      continue;
+    }
+    const message = r.error
+      ? `请求失败: ${r.error}`
+      : (r.status === 401 ? "API key 无效或无权限 (HTTP 401)" : `HTTP ${r.status}`);
+    // 401 是凭据问题, 不能拿旧数据掩盖; 其余失败回退上次成功值。
+    const hit = r.status === 401 ? null : cacheGet(r.key);
+    if (hit) {
+      handler.restore(hit.value, out);
+      stale.push({ endpoint: r.key, message, at: hit.at });
+    } else {
+      errors.push({ endpoint: r.key, message });
+    }
+  }
+
+  // quick 模式跳过的接口: 用缓存回填 (不算 stale, 本次根本没查)
+  const skipped = ENDPOINTS.filter(([key]) => !list.some(([k]) => k === key));
+  if (skipped.length > 0) {
+    out.cached = [];
+    for (const [key] of skipped) {
+      const hit = cacheGet(key);
+      if (!hit) continue;
+      HANDLERS[key].restore(hit.value, out);
+      out.cached.push(key);
+    }
+  }
+
+  if (errors.length >= list.length) out.ok = false;
+  return out;
+}
+
+// --- 配置解析 ------------------------------------------------------------------
+
+/** 单账号配置；fallbackEnv 仅在首选凭据缺失时使用，不做账号切换。 */
+function normalizeAccount(config) {
+  return {
+    apiKeyEnv: typeof config?.apiKeyEnv === "string" && config.apiKeyEnv.length > 0 ? config.apiKeyEnv : DEFAULT_API_KEY_ENV,
+    fallbackEnv: typeof config?.fallbackEnv === "string" && config.fallbackEnv.length > 0 ? config.fallbackEnv : null,
+    baseURL: typeof config?.baseURL === "string" && config.baseURL.length > 0 ? config.baseURL : DEFAULT_BASE_URL
+  };
+}
+
+/** 解析单账号请求选项；每次现读凭据，缺失时尝试回退条目。 */
+async function resolveAccountOptions(ctx, account) {
+  const credentials = ctx.get("credentials");
+  const tried = [];
+  const candidates = [account.apiKeyEnv, account.fallbackEnv].filter((v) => typeof v === "string" && v.length > 0);
+  let apiKey = "";
+
+  for (const envName of candidates) {
+    tried.push(envName);
+    if (!credentials) break;
+    try {
+      const resolved = await credentials.resolve(credentialRef(envName));
+      if (resolved && typeof resolved.value === "string" && resolved.value.length > 0) {
+        apiKey = resolved.value;
+        break;
+      }
+    } catch { /* 试下一个 */ }
+  }
+
+  return {
+    apiKey,
+    triedEnvs: tried,
+    baseURL: account.baseURL
+  };
+}
+
+// --- plugin ------------------------------------------------------------------
+
+function apply(ctx, config) {
+  const account = normalizeAccount(config);
+  const timeoutMs = Number.isFinite(config?.timeoutMs) && config.timeoutMs > 0
+    ? config.timeoutMs
+    : DEFAULT_TIMEOUT_MS;
+
+  function registerHttp(host, targetCtx) {
+    targetCtx.effect(() => host.register({
+      kind: "exact",
+      path: "/__dsh-commandcode-quota/dashboard",
+      handler: async (req, res) => {
+        if (req.method !== "GET") {
+          sendJson(res, 405, { error: "method not allowed" });
+          return;
+        }
+        try {
+          const t0 = Date.now();
+          // scope=quick: 只查响应快的 credits, 用量/订阅用缓存回填 (客户端先渲染再补全)
+          const scope = readQuery(req, "scope");
+
+          const options = await resolveAccountOptions(ctx, account);
+          const meta = { ok: true };
+          if (options.apiKey.length === 0) {
+            sendJson(res, 200, {
+              ...meta,
+              ok: false,
+              error: `未配置 API key (尝试过: ${options.triedEnvs.join(", ") || "无"}); 请在 ~/.dsh/.credentials.yaml 中配置`,
+              keyConfigured: false
+            });
+            return;
+          }
+          const dashboard = await fetchDashboard(
+            options,
+            timeoutMs,
+            scope === "quick" ? ["credits"] : null
+          );
+          sendJson(res, 200, { ...meta, ...dashboard, keyConfigured: true, debug: { timeoutMs, scope: scope ?? "full", handlerMs: Date.now() - t0 } });
+        } catch (error) {
+          sendJson(res, 500, { ok: false, error: `仪表盘请求失败: ${String(error)}` });
+        }
+      }
+    }));
+  }
+
+  const ws = ctx.get("webServer");
+  if (ws !== undefined) {
+    registerHttp(ws, ctx);
+  } else {
+    ctx.inject(["webServer"], (sub) => {
+      registerHttp(sub.webServer, sub);
+    });
+  }
+
+  ctx.logger.info("[dsh-commandcode-quota] Command Code 单账号余额仪表盘已注册");
+}
+
+export { apply, fetchDashboard, inject, name };
+export default { apply, inject, name };

package/test/client.test.cjs

@@ -0,0 +1,102 @@
+// 用轻量 React/请求替身测试前端；不访问网络，不操作 DSH 进程。
+const fs = require("node:fs");
+const vm = require("node:vm");
+const assert = require("node:assert/strict");
+const { join } = require("node:path");
+const plugin = join(__dirname, "..");
+const fixture = {
+  ok: true, providerId: "cc2",
+  providers: [{ id: "cc1", label: "账号 1" }, { id: "cc2", label: "账号 2" }],
+  balance: { monthlyCredits: 70 },
+  usage: { totalMonthlyCredits: 30, totalTokens: 100, totalCost: 5, successRate: 98 },
+  windowLimits: { fiveHour: { used: 10, cap: 100 }, weekly: { used: 20, cap: 100 } },
+  // 月度窗口的重置时间取自订阅周期末，是 ISO 字符串而非毫秒数
+  subscription: { status: "active", currentPeriodEnd: new Date(Date.now() + 20 * 86400000).toISOString() },
+};
+function mount({ open = true, data = fixture, failed = false } = {}) {
+  let registration, component, slot, stateIndex = 0;
+  const values = [open, data, false, null];
+  const updates = [], callbacks = [], effects = [], requests = [], timers = [];
+  const React = {
+    Fragment: "fragment",
+    createElement(type, props, ...children) { return { type, props: props || {}, children }; },
+    useState(initial) {
+      const index = stateIndex++;
+      return [index < values.length ? values[index] : initial, value => updates.push({ index, value })];
+    },
+    useCallback(fn, deps) { callbacks.push({ fn, deps }); return fn; },
+    useEffect(fn) { effects.push(fn); },
+    useRef(value) { return { current: value }; },
+  };
+  vm.runInNewContext(fs.readFileSync(join(plugin, "src/client.js"), "utf8"), {
+    window: { __ModuleLoader__: { load(row) { registration = row; } } },
+    fetch: async (url, options) => {
+      requests.push({ url, options });
+      return { ok: !failed, status: failed ? 503 : 200, json: async () => fixture };
+    },
+    setInterval(fn, ms) { timers.push({ fn, ms }); return 1; },
+    clearInterval(id) { timers.push({ cleared: id }); },
+  });
+  assert.equal(registration.id, "dsh-commandcode-quota");
+  const client = registration.factory(() => React);
+  assert.deepEqual(Array.from(client.inject), ["slots"]);
+  client.apply({ slots: {
+    inject(name, fn) { assert.equal(name, "conversation.composer.dock"); fn(); },
+    register(row, fn) { slot = row; component = fn; },
+  } });
+  assert.equal(slot.id, "dsh-commandcode-quota-dashboard");
+  assert.equal(slot.order, -1);
+  const tree = component(), nodes = [], texts = [];
+  function visit(node) {
+    if (Array.isArray(node)) return node.forEach(visit);
+    if (node == null || typeof node === "boolean") return;
+    if (typeof node !== "object") return texts.push(String(node));
+    if (typeof node.type === "function") return visit(node.type(node.props));
+    nodes.push(node);
+    visit(node.children);
+  }
+  visit(tree);
+  return { nodes, texts, updates, callbacks, effects, requests, timers, stateIndex };
+}
+async function main() {
+  const view = mount();
+  const buttons = view.nodes.filter(node => node.type === "button");
+  assert.equal(buttons.length, 3, "只保留状态栏、刷新和关闭按钮，不应存在账号切换按钮");
+  assert.equal(view.stateIndex, 4, "不再维护选中账号状态");
+  assert.equal(view.callbacks[0].deps.length, 0);
+  for (const label of ["5h 10%", "周 20%", "月 30%", "$70.00", "5 小时窗口", "每周窗口", "每月窗口"]) {
+    assert.ok(view.texts.includes(label), `保留额度展示：${label}`);
+  }
+  // 回归：月度重置时间来自 ISO 字符串，未经 toMs 归一化会渲染成 "NaN分NaN秒"
+  const resetTexts = view.texts.filter((t) => t.includes("重置"));
+  assert.equal(resetTexts.length, 3, "三个窗口都应显示重置信息");
+  for (const t of resetTexts) assert.ok(!t.includes("NaN"), `重置文本不应出现 NaN：${t}`);
+  assert.ok(
+    resetTexts.some((t) => /\d+天\d+小时（\d{4}\/\d{2}\/\d{2}）/.test(t)),
+    `月度应显示天级倒计时与到期日，实际：${resetTexts.join(" | ")}`,
+  );
+  await buttons.find(node => node.props.title === "刷新").props.onClick();
+  assert.deepEqual(view.requests.map(req => req.url), ["/__dsh-commandcode-quota/dashboard?scope=quick", "/__dsh-commandcode-quota/dashboard"]);
+  assert.ok(view.requests.every(req => req.options.cache === "no-store"));
+  assert.ok(!view.updates.some(update => update.index > 3));
+  const timerView = mount({ open: false, data: null });
+  assert.equal(timerView.nodes.filter(node => node.type === "button").length, 1);
+  const cleanup = timerView.effects[0]();
+  assert.equal(timerView.timers[0].ms, 3 * 60 * 1000);
+  cleanup();
+  assert.equal(timerView.timers[1].cleared, 1);
+  const failure = mount({ failed: true });
+  await failure.callbacks[0].fn();
+  assert.ok(failure.updates.some(update => update.index === 3 && update.value.includes("HTTP 503")));
+  assert.ok(failure.updates.some(update => update.index === 2 && update.value === false));
+  const manifest = JSON.parse(fs.readFileSync(join(plugin, "package.json"), "utf8"));
+  assert.equal(manifest.name, "dsh-commandcode-quota", "客户端注册 id 必须等于包名");
+  assert.equal(manifest.exports["./client"], "./src/client.js", "必须导出 ./client 供客户端模块加载");
+  for (const file of ["locale/en.json", "locale/zh.json"]) {
+    const meta = JSON.parse(fs.readFileSync(join(plugin, file), "utf8"));
+    assert.ok(meta.meta?.title && meta.meta?.description, `${file} 必须提供标题与描述`);
+  }
+  console.log("通过：无账号切换；额度展示、手动/定时刷新、错误处理、槽位注册保持可用。");
+  console.log("通过：包名与客户端注册 id 一致，locale 为合法 JSON。");
+}
+main().catch(error => { console.error(error.message); process.exitCode = 1; });

package/test/host.test.cjs

@@ -0,0 +1,134 @@
+// 模拟宿主、凭据与 API，不读取真实凭据，也不访问网络。
+const fs = require("node:fs");
+const vm = require("node:vm");
+const assert = require("node:assert/strict");
+const { createHash } = require("node:crypto");
+const { join } = require("node:path");
+const plugin = join(__dirname, "..");
+const source = fs.readFileSync(join(plugin, "src/index.js"), "utf8");
+const responses = {
+  "/alpha/billing/credits": { credits: { monthlyCredits: 70 }, windowLimits: { fiveHour: { used: 10, cap: 100 } } },
+  "/alpha/usage/summary": { totalMonthlyCredits: 30, totalTokens: 100, totalCost: 5, successRate: 98 },
+  "/alpha/billing/subscriptions": { data: { status: "active", currentPeriodEnd: "2026-11-01T00:00:00Z" } },
+  "/alpha/whoami": { user: { name: "测试账号" } },
+};
+function load() {
+  const requests = [];
+  let reply = async (url) => ({ ok: true, status: 200, json: async () => responses[new URL(url).pathname] });
+  const context = vm.createContext({
+    Buffer, URL, AbortController, setTimeout, clearTimeout, createHash,
+    credentialRef: (ref) => ref,
+    fetch: async (url, options) => { requests.push({ url, options }); return reply(url, options); },
+  });
+  vm.runInContext(source.replace(/^import .*;\r?$/gm, "").replace(/^export .*;\r?$/gm, "") +
+    "\nglobalThis.host = { apply, fetchDashboard, inject, name };", context);
+  return { host: context.host, requests, respond(fn) { reply = fn; } };
+}
+function mount(runtime, config = {}, keys = {}, lazy = false) {
+  let route;
+  const refs = [];
+  const web = { register(row) { route = row; return () => {}; } };
+  const credentials = { async resolve(ref) { refs.push(ref); return { value: keys[ref] ?? "" }; } };
+  const ctx = {
+    get(name) { return name === "credentials" ? credentials : name === "webServer" && !lazy ? web : undefined; },
+    effect(fn) { return fn(); },
+    inject(names, fn) { assert.deepEqual(Array.from(names), ["webServer"]); fn({ webServer: web, effect: ctx.effect }); },
+    logger: { info() {} },
+  };
+  runtime.host.apply(ctx, config);
+  assert.equal(runtime.host.name, "dsh-commandcode-quota");
+  assert.deepEqual(Array.from(runtime.host.inject), ["credentials"]);
+  assert.equal(route.kind, "exact");
+  assert.equal(route.path, "/__dsh-commandcode-quota/dashboard");
+  return {
+    refs,
+    async request(url = route.path, method = "GET") {
+      let status, headers, raw;
+      await route.handler({ method, url }, {
+        writeHead(code, values) { status = code; headers = values; },
+        end(body) { raw = body; },
+      });
+      assert.equal(headers["cache-control"], "no-store");
+      assert.equal(headers["content-length"], Buffer.byteLength(raw));
+      return { status, body: JSON.parse(raw), raw };
+    },
+  };
+}
+const config = { apiKeyEnv: "PRIMARY_TEST_KEY", fallbackEnv: "FALLBACK_TEST_KEY", baseURL: "https://mock.invalid" };
+async function main() {
+  const runtime = load();
+  const app = mount(runtime, config, { PRIMARY_TEST_KEY: "fixture-primary" });
+  const full = await app.request();
+  assert.equal(full.status, 200);
+  assert.equal(full.body.ok, true);
+  assert.equal(full.body.balance.monthlyCredits, 70);
+  assert.equal(full.body.usage.totalMonthlyCredits, 30);
+  assert.equal(full.body.subscription.status, "active");
+  assert.equal(full.body.user.name, "测试账号");
+  for (const field of ["providers", "providerId", "providerLabel", "keyInfo", "warnings"]) {
+    assert.ok(!(field in full.body), `单账号响应不应包含 ${field}`);
+  }
+  assert.ok(!full.raw.includes("fixture-primary"));
+  assert.equal(runtime.requests.length, 4);
+  assert.ok(runtime.requests.every(req => req.options.headers.authorization === "Bearer fixture-primary"));
+  assert.deepEqual(app.refs, ["PRIMARY_TEST_KEY"]);
+  runtime.requests.length = 0;
+  const quick = await app.request("/__dsh-commandcode-quota/dashboard?scope=quick");
+  assert.equal(runtime.requests.length, 1);
+  assert.equal(new URL(runtime.requests[0].url).pathname, "/alpha/billing/credits");
+  assert.equal(quick.body.usage.totalMonthlyCredits, 30);
+  assert.deepEqual(quick.body.cached, ["usage", "subscriptions", "whoami"]);
+  runtime.respond(async () => ({ status: 503, json: async () => ({}) }));
+  const stale = await app.request();
+  assert.equal(stale.body.balance.monthlyCredits, 70);
+  assert.equal(stale.body.stale.length, 4);
+  runtime.respond(async () => ({ status: 401, json: async () => ({}) }));
+  const unauthorized = await app.request();
+  assert.equal(unauthorized.body.ok, false);
+  assert.equal(unauthorized.body.balance, undefined);
+  assert.equal(unauthorized.body.errors.length, 4);
+  runtime.requests.length = 0;
+  assert.equal((await app.request(undefined, "POST")).status, 405);
+  assert.equal(runtime.requests.length, 0);
+  const fallbackRuntime = load();
+  const fallback = mount(fallbackRuntime, config, { FALLBACK_TEST_KEY: "fixture-fallback" }, true);
+  assert.equal((await fallback.request("/__dsh-commandcode-quota/dashboard?scope=quick")).body.keyConfigured, true);
+  assert.deepEqual(fallback.refs, ["PRIMARY_TEST_KEY", "FALLBACK_TEST_KEY"]);
+  assert.equal(fallbackRuntime.requests[0].options.headers.authorization, "Bearer fixture-fallback");
+  const emptyRuntime = load();
+  const missing = await mount(emptyRuntime, config).request();
+  assert.equal(missing.body.keyConfigured, false);
+  assert.equal(missing.body.ok, false);
+  assert.equal(emptyRuntime.requests.length, 0);
+  const defaultRuntime = load();
+  assert.equal((await mount(defaultRuntime, {}, { COMMANDCODE_API_KEY: "fixture-default" }).request()).body.ok, true);
+  let attempts = 0;
+  const retryRuntime = load();
+  retryRuntime.respond(async (url) => {
+    if (++attempts === 1) throw new TypeError("模拟连接失败");
+    return { status: 200, json: async () => responses[new URL(url).pathname] };
+  });
+  assert.equal((await mount(retryRuntime, config, { PRIMARY_TEST_KEY: "fixture-primary" }).request("/__dsh-commandcode-quota/dashboard?scope=quick")).body.ok, true);
+  assert.equal(attempts, 2);
+  const timeoutRuntime = load();
+  timeoutRuntime.respond((url, options) => new Promise((resolve, reject) => {
+    options.signal.addEventListener("abort", () => reject(new Error("模拟超时")), { once: true });
+  }));
+  assert.equal((await mount(timeoutRuntime, { ...config, timeoutMs: 5 }, { PRIMARY_TEST_KEY: "fixture-primary" }).request("/__dsh-commandcode-quota/dashboard?scope=quick")).body.ok, false);
+  assert.equal(timeoutRuntime.requests.length, 1, "主动超时不重试");
+  // 包自检：声明、注册 id 与 bundle 补丁层三者必须一致。
+  const manifest = JSON.parse(fs.readFileSync(join(plugin, "package.json"), "utf8"));
+  assert.equal(manifest.name, "dsh-commandcode-quota", "package.json 的 name 必须等于宿主端导出 name");
+  assert.equal(manifest.dsh.bundle.patch, "./cordis.patch.yml", "必须声明 bundle 补丁层");
+  const patch = fs.readFileSync(join(plugin, "cordis.patch.yml"), "utf8");
+  assert.ok(
+    patch.includes(`id: ${manifest.name}`) && patch.includes(`name: '${manifest.name}'`),
+    "bundle 补丁的注册 id 与包名必须一致",
+  );
+  // 发版时最容易漏的一处：user-agent 里的版本号要与 package.json 同步。
+  const uaVersion = source.match(/"user-agent":\s*"[^"]*\/([^"]+)"/)?.[1];
+  assert.equal(uaVersion, manifest.version, "user-agent 版本必须与 package.json 的 version 一致");
+  console.log("通过：单账号响应、主/回退凭据、完整/快速查询、缓存、401、405、重试和超时。");
+  console.log("通过：宿主端导出、路由、包名与 bundle 补丁层一致。");
+}
+main().catch(error => { console.error(error.message); process.exitCode = 1; });