dsh-commandcode-quota 0.2.2 → 0.3.0

package/src/index.js

@@ -24,8 +24,8 @@
  *
  * ESM module format (cordis bundle rule): named exports apply/inject/name.
  */
-import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
@@ -37,6 +37,14 @@ const DEFAULT_API_KEY_ENV = "COMMANDCODE_API_KEY";
 // Command Code 的 usage / subscriptions / whoami 实测要 8~20s, 8s 超时必然误杀。
 const DEFAULT_TIMEOUT_MS = 30000;
 
+// 落盘缓存文件名(与凭据选择文件同目录)。只存额度相关字段:
+// whoami 带邮箱等个人信息, 没有落盘价值, 不写进去。
+const CACHE_FILE_NAME = "dsh-commandcode-quota-cache.json";
+const PERSISTED_ENDPOINTS = ["credits", "usage", "subscriptions"];
+
+// 接口名 → 中文, 用于把失败原因写成一句人能看懂的话。
+const ENDPOINT_LABELS = { credits: "余额", usage: "用量", subscriptions: "订阅", whoami: "账户" };
+
 // --- HTTP helpers ------------------------------------------------------------
 
 function sendJson(res, status, obj) {
@@ -72,7 +80,7 @@ async function ccFetch(baseURL, path, apiKey, timeoutMs) {
       headers: {
         authorization: `Bearer ${apiKey}`,
         accept: "application/json",
-        "user-agent": "dsh-commandcode-quota/0.2.2"
+        "user-agent": "dsh-commandcode-quota/0.3.0"
       },
       signal: controller.signal
     });
@@ -143,17 +151,77 @@ const HANDLERS = {
  */
 const CACHE_TTL_MS = 6 * 60 * 60 * 1000;
 const lastGood = new Map();
+// 已从磁盘灌入过缓存的 key 指纹, 避免每次请求都读盘
+let hydratedFor = null;
+
+/** 缓存键带上 key 指纹: 换 key 后不会把上一个账号的数据当成兜底值。 */
+function cacheKey(fingerprint, endpoint) {
+  return `${fingerprint}|${endpoint}`;
+}
 
-function cacheGet(key) {
-  const hit = lastGood.get(key);
+function cacheGet(fingerprint, endpoint) {
+  const hit = lastGood.get(cacheKey(fingerprint, endpoint));
   if (!hit) return null;
   if (Date.now() - hit.at > CACHE_TTL_MS) return null;
   return hit;
 }
 
-function cacheSet(key, value) {
+function cacheSet(fingerprint, endpoint, value) {
   if (value === undefined || value === null) return;
-  lastGood.set(key, { value, at: Date.now() });
+  lastGood.set(cacheKey(fingerprint, endpoint), { value, at: Date.now() });
+}
+
+/** key 的短指纹: 落盘只存指纹, 绝不写原始 key。 */
+function keyFingerprint(apiKey) {
+  return createHash("sha256").update(String(apiKey)).digest("hex").slice(0, 16);
+}
+
+function cacheFile() {
+  return join(dshHome(), CACHE_FILE_NAME);
+}
+
+/**
+ * 冷启动兜底: 把上次进程落盘的额度数据读回内存缓存。
+ *
+ * 没有这一步时, DSH 一重启内存缓存就空 —— 此时 credits 单接口失败就没有旧值可退,
+ * 面板会整块空白。只认同一把 key(指纹相同), 过期的条目直接丢弃。
+ */
+function hydrateCache(fingerprint) {
+  if (!fingerprint || hydratedFor === fingerprint) return;
+  hydratedFor = fingerprint;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(cacheFile(), "utf8"));
+  } catch {
+    return;
+  }
+  if (!parsed || parsed.fingerprint !== fingerprint) return;
+  const entries = parsed.entries;
+  if (!entries || typeof entries !== "object") return;
+  for (const endpoint of PERSISTED_ENDPOINTS) {
+    const hit = entries[endpoint];
+    if (!hit || typeof hit.at !== "number") continue;
+    if (Date.now() - hit.at > CACHE_TTL_MS) continue;
+    if (lastGood.has(cacheKey(fingerprint, endpoint))) continue;
+    lastGood.set(cacheKey(fingerprint, endpoint), { value: hit.value, at: hit.at });
+  }
+}
+
+/** 把当前指纹下仍然新鲜的额度快照落盘; 失败静默, 不能影响查询本身。 */
+function persistCache(fingerprint) {
+  const entries = {};
+  for (const endpoint of PERSISTED_ENDPOINTS) {
+    const hit = cacheGet(fingerprint, endpoint);
+    if (hit) entries[endpoint] = hit;
+  }
+  if (Object.keys(entries).length === 0) return;
+  try {
+    const file = cacheFile();
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ fingerprint, entries }, null, 2) + "\n", "utf8");
+  } catch {
+    /* 落盘失败不影响查询 */
+  }
 }
 
 /**
@@ -167,6 +235,8 @@ async function fetchDashboard(cfg, timeoutMs, onlyKeys) {
   const errors = [];
   const stale = [];
   const out = { ok: true, fetchedAt: Date.now(), errors, stale };
+  const fingerprint = keyFingerprint(cfg.apiKey);
+  hydrateCache(fingerprint);
 
   const list = Array.isArray(onlyKeys) && onlyKeys.length > 0
     ? ENDPOINTS.filter(([key]) => onlyKeys.includes(key))
@@ -185,14 +255,14 @@ async function fetchDashboard(cfg, timeoutMs, onlyKeys) {
     const handler = HANDLERS[r.key];
     if (!r.error && r.status === 200 && r.json) {
       handler.apply(r.json, out);
-      cacheSet(r.key, handler.snapshot(out));
+      cacheSet(fingerprint, 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);
+    const hit = r.status === 401 ? null : cacheGet(fingerprint, r.key);
     if (hit) {
       handler.restore(hit.value, out);
       stale.push({ endpoint: r.key, message, at: hit.at });
@@ -206,14 +276,24 @@ async function fetchDashboard(cfg, timeoutMs, onlyKeys) {
   if (skipped.length > 0) {
     out.cached = [];
     for (const [key] of skipped) {
-      const hit = cacheGet(key);
+      const hit = cacheGet(fingerprint, key);
       if (!hit) continue;
       HANDLERS[key].restore(hit.value, out);
       out.cached.push(key);
     }
   }
 
-  if (errors.length >= list.length) out.ok = false;
+  // 落盘: 下次进程启动时 hydrateCache 能把这份快照读回来
+  persistCache(fingerprint);
+
+  if (errors.length >= list.length) {
+    out.ok = false;
+    // 全部失败时必须把具体原因带出去。否则客户端只收到 ok:false、拿不到任何文案,
+    // 面板会被渲染成一块空白(2026-10-29 key 失效时就这么空了一整片)。
+    out.error = `查询失败: ${errors
+      .map((e) => `${ENDPOINT_LABELS[e.endpoint] ?? e.endpoint} ${e.message}`)
+      .join("；")}`;
+  }
   return out;
 }
 
@@ -265,6 +345,27 @@ async function resolveAccountOptions(ctx, account) {
 /** 合法凭据条目名：POSIX shell 标识符，与 dsh-credentials 的 REF_PATTERN 一致。 */
 const REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
+/**
+ * 把环境变量名校验成凭据引用（等价于 @deepseek-ai/dsh-credentials 的 credentialRef）。
+ *
+ * 为什么本地实现而不 import 那个包：那是【运行时导入】，而插件的真实路径未必在
+ * profile 的 node_modules 里面（本地 junction 安装就是这种情况）。此时
+ * "@deepseek-ai/dsh-credentials" 只能靠 profiles/node_modules 下的链接解析，
+ * 而 DSH 升级会清空那里的 @deepseek-ai —— 导入立刻抛 ERR_MODULE_NOT_FOUND，
+ * 整个宿主端（连带界面面板）都不会上线；市场里的普通用户同样会踩到。
+ * 校验规则只有一行正则，本地实现即可让插件零 harness 运行时依赖。
+ *
+ * @param {unknown} value 候选引用，如 BAILIAN_API_KEY。
+ * @returns {string} 通过校验的引用本身。
+ * @throws {TypeError} 名字不符合 shell 标识符语法时。
+ */
+function credentialRef(value) {
+  if (typeof value !== "string" || !REF_PATTERN.test(value)) {
+    throw new TypeError(`credential ref "${String(value)}" must match ${String(REF_PATTERN)}`);
+  }
+  return value;
+}
+
 function dshHome() {
   const fromEnv = process.env.DSH_HOME;
   return typeof fromEnv === "string" && fromEnv.length > 0 ? fromEnv : join(homedir(), ".dsh");

package/test/client.test.cjs

@@ -13,9 +13,9 @@ const fixture = {
   // 月度窗口的重置时间取自订阅周期末，是 ISO 字符串而非毫秒数
   subscription: { status: "active", currentPeriodEnd: new Date(Date.now() + 20 * 86400000).toISOString() },
 };
-function mount({ open = true, data = fixture, failed = false, creds = null } = {}) {
+function mount({ open = true, data = fixture, failed = false, creds = null, gearOpen = false } = {}) {
   let registration, component, slot, stateIndex = 0;
-  const values = [open, data, false, null, creds || { entries: [], apiKeyEnv: null, saving: false, error: null }];
+  const values = [open, data, false, null, creds || { entries: [], apiKeyEnv: null, saving: false, error: null }, gearOpen, null];
   const updates = [], callbacks = [], effects = [], requests = [], timers = [];
   const React = {
     Fragment: "fragment",
@@ -61,8 +61,8 @@ function mount({ open = true, data = fixture, failed = false, creds = null } = {
 async function main() {
   const view = mount();
   const buttons = view.nodes.filter(node => node.type === "button");
-  assert.equal(buttons.length, 3, "只保留状态栏、刷新和关闭按钮，不应存在账号切换按钮");
-  assert.equal(view.stateIndex, 5, "状态：面板开合 / 数据 / 加载 / 错误 / 凭据条目");
+  assert.equal(buttons.length, 4, "状态栏 + 齿轮 + 刷新 + 关闭，不应存在账号切换按钮");
+  assert.equal(view.stateIndex, 7, "状态：面板开合 / 数据 / 加载 / 错误 / 凭据条目 / 凭据设置 / 配色");
   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}`);
@@ -107,7 +107,7 @@ async function main() {
     ["报错态", { failed: true }],
     ["无数据态", { data: null }],
   ]) {
-    const view2 = mount({ ...options, creds: pickerState });
+    const view2 = mount({ ...options, creds: pickerState, gearOpen: true });
     const selects = view2.nodes.filter((n) => n.type === "select");
     assert.equal(selects.length, 1, `${label}下应能看到凭据条目下拉`);
     const opts = view2.nodes.filter((n) => n.type === "option");
@@ -126,13 +126,13 @@ async function main() {
     assert.equal(selects[0].props.value, "COMMANDCODE2_API_KEY", `${label}下应选中当前条目`);
   }
   // 宿主端读不到供应商时会退化成纯字符串数组，也必须照常工作
-  const plain = mount({ creds: { entries: ["BAILIAN_API_KEY"], apiKeyEnv: null, saving: false, error: null } });
+  const plain = mount({ creds: { entries: ["BAILIAN_API_KEY"], apiKeyEnv: null, saving: false, error: null }, gearOpen: true });
   assert.deepEqual(
     plain.nodes.filter((n) => n.type === "option").map((o) => o.children[0]),
     ["（未设置）", "BAILIAN_API_KEY"],
   );
   // 配置指向一个尚未添加的条目时也要出现在候选里，否则下拉会显示成空白
-  const orphan = mount({ creds: { entries: [{ ref: "OTHER_KEY", provider: null }], apiKeyEnv: "MISSING_KEY", saving: false, error: null } });
+  const orphan = mount({ creds: { entries: [{ ref: "OTHER_KEY", provider: null }], apiKeyEnv: "MISSING_KEY", saving: false, error: null }, gearOpen: true });
   assert.deepEqual(
     orphan.nodes.filter((n) => n.type === "option").map((o) => o.props.value),
     ["", "MISSING_KEY", "OTHER_KEY"],
@@ -140,9 +140,12 @@ async function main() {
   const timerView = mount({ open: false, data: null });
   assert.equal(timerView.nodes.filter(node => node.type === "button").length, 1);
   const cleanup = timerView.effects[0]();
+  // 分层轮询: 余额 3 分钟一次, 用量/订阅 30 分钟一次(重查询不该跟余额同频)
   assert.equal(timerView.timers[0].ms, 3 * 60 * 1000);
+  assert.equal(timerView.timers[1].ms, 30 * 60 * 1000);
   cleanup();
-  assert.equal(timerView.timers[1].cleared, 1);
+  assert.equal(timerView.timers[2].cleared, 1);
+  assert.equal(timerView.timers[3].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")));

package/test/host.test.cjs

@@ -38,7 +38,6 @@ function load() {
     join, dirname,
     homedir: () => fakeHome,
     process: { env: { DSH_HOME: fakeHome } },
-    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, "") +
@@ -139,11 +138,22 @@ async function main() {
   const stale = await app.request();
   assert.equal(stale.body.balance.monthlyCredits, 70);
   assert.equal(stale.body.stale.length, 4);
+  // 落盘缓存: 模拟 DSH 重启(新 context, 内存缓存为空)后 credits 失败,
+  // 应该能从磁盘快照回退余额, 而不是让面板空白。
+  const restarted = load();
+  restarted.respond(async () => ({ status: 503, json: async () => ({}) }));
+  const restored = await mount(restarted, config, { PRIMARY_TEST_KEY: "fixture-primary" })
+    .request(DASHBOARD + "?scope=quick");
+  assert.equal(restored.body.balance.monthlyCredits, 70, "重启后应能从落盘缓存回退余额");
+  assert.equal(restored.body.stale.length, 1);
   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);
+  // 全失败必须带出可读原因, 否则客户端只拿到 ok:false, 面板会渲染成空白
+  assert.ok(unauthorized.body.error.includes("查询失败"), "全失败时应带出可读原因");
+  assert.ok(unauthorized.body.error.includes("余额"), "失败原因应标明是哪个接口");
   runtime.requests.length = 0;
   assert.equal((await app.request(undefined, "POST")).status, 405);
   assert.equal(runtime.requests.length, 0);
@@ -173,6 +183,9 @@ async function main() {
   });
   assert.equal((await mount(retryRuntime, config, { PRIMARY_TEST_KEY: "fixture-primary" }).request(DASHBOARD + "?scope=quick")).body.ok, true);
   assert.equal(attempts, 2);
+  // 超时用例要求「冷启动且无任何可用缓存」: 先清掉落盘快照,
+  // 否则 hydrateCache 会让 credits 兜底成功, 就测不到 ok:false 了。
+  fs.rmSync(join(fakeHome, "dsh-commandcode-quota-cache.json"), { force: true });
   const timeoutRuntime = load();
   timeoutRuntime.respond((url, options) => new Promise((resolve, reject) => {
     options.signal.addEventListener("abort", () => reject(new Error("模拟超时")), { once: true });
@@ -260,6 +273,12 @@ async function main() {
     typeof peerRange === "string" && /-0/.test(peerRange),
     `官方包 peer 范围必须含显式预发布分支（当前: ${peerRange}）`,
   );
+  // 宿主端不得再有 @deepseek-ai 的【运行时导入】：插件真实路径可能在 profile 之外，
+  // 该包只能靠 profiles/node_modules 下的链接解析，而 DSH 升级会清掉那些链接，
+  // 导入即抛 ERR_MODULE_NOT_FOUND，整个插件（含界面）都不上线（2026-10-17 真挂过一次）。
+  // peer 声明只用于兼容性判定（读 package.json），不参与运行时解析，因此保留。
+  const runtimeHarnessImports = source.match(/^import[^\n]*from\s+"@deepseek-ai\/[^"]+";?$/gm) ?? [];
+  assert.deepEqual(runtimeHarnessImports, [], "宿主端不得 import harness 包（会在 profile 之外解析失败）");
   console.log("通过：单账号响应、主/回退凭据、完整/快速查询、缓存、401、405、重试和超时。");
   console.log("通过：凭据端点只回条目名、翻译供应商名、保存后覆盖 patch 配置、非法名被拒、无 key 时依然可用。");
   console.log("通过：宿主端导出、路由、包名与 bundle 补丁层一致。");