mslxdff 0.1.55 → 0.1.56

package/src/providers/generic.js

@@ -0,0 +1,221 @@
+import { joinModelId } from "./model-id.js";
+import { createKeyRing } from "./keyring.js";
+import { loadProviderKeys, loadProviderBaseUrl } from "../state.js";
+
+let UndiciAgent = null;
+let UndiciFetch = null;
+try {
+  const mod = await import("undici");
+  UndiciAgent = mod.Agent;
+  UndiciFetch = mod.fetch;
+} catch {}
+
+function envInt(name, fallback) {
+  const v = Number(process.env[name]);
+  return Number.isInteger(v) && v > 0 ? v : fallback;
+}
+
+function collectApiKeys(id, apiKeys, apiKey) {
+  const list = [
+    ...(Array.isArray(apiKeys) ? apiKeys : [apiKeys].filter(Boolean)),
+    apiKey,
+    ...(apiKeys === undefined && apiKey === undefined ? loadProviderKeys(id) : []),
+  ].filter((k) => typeof k === "string" && k.trim().length);
+  return [...new Set(list.map((k) => k.trim()))];
+}
+
+function resolveBaseUrl(id, baseUrl) {
+  if (baseUrl) return String(baseUrl).trim().replace(/\/+$/, "");
+  const env = loadProviderBaseUrl(id);
+  if (env) return env;
+  return "";
+}
+
+export function createGenericProvider({
+  id,
+  baseUrl,
+  apiKeys,
+  apiKey,
+  connectTimeoutMs = Number(process.env.MSLXDFF_GENERIC_TIMEOUT_MS) || 30_000,
+  cooldownMs = envInt("MSLXDFF_GENERIC_COOLDOWN_MS", 30_000),
+  retry = {
+    network: { attempts: 2, delayMs: 300 },
+    429: { attempts: 1, delayMs: 100 },
+    502: { attempts: 1, delayMs: 100 },
+    503: { attempts: 1, delayMs: 100 },
+    504: { attempts: 1, delayMs: 100 },
+  },
+  fetchImpl,
+  headers: extraHeaders,
+  noAgent = false,
+} = {}) {
+  if (!id) throw new Error("generic provider requires id");
+  const resolvedBase = resolveBaseUrl(id, baseUrl);
+  if (!resolvedBase) throw new Error(`generic provider ${id}: missing baseUrl`);
+  if (!fetchImpl) fetchImpl = UndiciFetch || fetch;
+
+  const ring = createKeyRing(collectApiKeys(id, apiKeys, apiKey), { cooldownMs });
+
+  let dispatcher = null;
+  let agent = null;
+  if (UndiciAgent && !noAgent) {
+    try {
+      agent = new UndiciAgent({
+        keepAliveTimeout: envInt("MSLXDFF_GENERIC_KEEPALIVE_TIMEOUT", 30_000),
+        keepAliveMaxTimeout: envInt("MSLXDFF_GENERIC_KEEPALIVE_MAX_TIMEOUT", 60_000),
+        connections: envInt("MSLXDFF_GENERIC_KEEPALIVE_CONNECTIONS", 20),
+        pipelining: 1,
+      });
+      dispatcher = agent;
+    } catch {}
+  }
+
+  function buildHeaders(body, key) {
+    const isStream = body?.stream !== false;
+    const h = {
+      "Content-Type": "application/json",
+      "Accept": isStream ? "text/event-stream" : "*/*",
+      "User-Agent": "mslxdff",
+    };
+    if (key) h["Authorization"] = `Bearer ${key}`;
+    return { ...h, ...extraHeaders };
+  }
+
+  async function attemptOnce(url, body, key, activeRing) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`${id} timed out after ${connectTimeoutMs}ms`)), connectTimeoutMs);
+    try {
+      const opts = { method: "POST", headers: buildHeaders(body, key), body: JSON.stringify(body), signal: controller.signal };
+      if (dispatcher) opts.dispatcher = dispatcher;
+      const res = await fetchImpl(url, opts);
+      if (res.status === 401 && !activeRing.size) return { __needKey: true };
+      return res;
+    } catch (err) {
+      return err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async function runChat(body, activeRing, sourceKey) {
+    const url = `${resolvedBase}/chat/completions`;
+    const t0 = performance.now();
+    const attempts = [];
+    let waitMs = 0;
+    const key = activeRing.next();
+    if (!key && activeRing.size > 0) {
+      const err = new Error(`${id}: all API keys are in cooldown (last error < ${cooldownMs}ms ago) — provider temporarily unavailable`);
+      err._t = { attempts: [], waitMs: 0, totalMs: Math.round(performance.now() - t0), cooldownMs };
+      throw err;
+    }
+    for (let attempt = 0; ; attempt++) {
+      const t = performance.now();
+      const result = await attemptOnce(url, body, key, activeRing);
+      const type = result instanceof Error ? "network" : `http${result?.status}`;
+      attempts.push({ attempt, type, ms: Math.round(performance.now() - t) });
+      if (result?.__needKey) {
+        const err = new Error(`${id}: missing ${sourceKey} (chat requires a real key)`);
+        err._t = { attempts, waitMs, totalMs: Math.round(performance.now() - t0) };
+        throw err;
+      }
+      if (result instanceof Error) {
+        const entry = retry?.network;
+        if (entry && attempt < entry.attempts) {
+          await sleep(entry.delayMs);
+          waitMs += entry.delayMs;
+          continue;
+        }
+        activeRing.onError(key);
+        result._t = { attempts, waitMs, totalMs: Math.round(performance.now() - t0) };
+        throw result;
+      }
+      const entry = retry?.[result.status];
+      if (entry && attempt < entry.attempts) {
+        await sleep(entry.delayMs);
+        waitMs += entry.delayMs;
+        continue;
+      }
+      if (result.status === 401 || result.status === 403 || result.status === 429 || result.status >= 500) activeRing.onError(key);
+      result._t = { attempts, waitMs, totalMs: Math.round(performance.now() - t0) };
+      return result;
+    }
+  }
+
+  async function chat(body) {
+    return runChat(body, ring, `MSLXDFF_${id.toUpperCase()}_KEY`);
+  }
+
+  async function chatWithKeys(body, keys) {
+    const tmp = createKeyRing(keys, { cooldownMs });
+    return runChat(body, tmp, "shared provider keys");
+  }
+
+  const CACHE_TTL_MS = 10 * 60 * 1000;
+  let cache = null;
+  let fetchedAt = 0;
+  async function listModels() {
+    const now = Date.now();
+    if (cache && now - fetchedAt < CACHE_TTL_MS) return cache;
+    const url = `${resolvedBase}/models`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`${id} models timed out`)), 15_000);
+    try {
+      const headers = { Accept: "application/json" };
+      const key = ring.next();
+      if (key) headers["Authorization"] = `Bearer ${key}`;
+      const opts = { headers, signal: controller.signal };
+      if (dispatcher) opts.dispatcher = dispatcher;
+      const res = await fetchImpl(url, opts);
+      if (!res.ok) return [];
+      const json = await res.json().catch(() => ({}));
+      const raw = Array.isArray(json.data) ? json.data : Array.isArray(json) ? json : [];
+      // 通用：不过滤 pricing，全部前缀化
+      cache = raw.filter((m) => m && typeof m.id === "string").map((m) => ({ ...m, id: joinModelId(id, m.id) }));
+      fetchedAt = now;
+      return cache;
+    } catch {
+      return [];
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async function preheat() {
+    const url = `${resolvedBase}/models`;
+    const t0 = performance.now();
+    try {
+      const headers = { Accept: "application/json" };
+      const key = loadProviderKeys(id)[0] || ring.next();
+      if (key) headers["Authorization"] = `Bearer ${key}`;
+      const opts = { headers };
+      if (dispatcher) opts.dispatcher = dispatcher;
+      const res = await fetchImpl(url, opts);
+      try { if (res.body) await res.text().catch(() => {}); } catch {}
+      return { ok: res.ok, status: res.status, ms: Math.round(performance.now() - t0) };
+    } catch (err) {
+      return { ok: false, error: String(err?.message || err), ms: Math.round(performance.now() - t0) };
+    }
+  }
+
+  async function close() {
+    if (agent && typeof agent.close === "function") {
+      try { await agent.close(); } catch {}
+    }
+  }
+
+  return {
+    id,
+    chat,
+    chatWithKeys,
+    listModels,
+    preheat,
+    close,
+    agent,
+    keyRing: ring,
+    baseUrl: resolvedBase,
+  };
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/src/providers/index.js

@@ -0,0 +1,6 @@
+export { createProviderDispatcher } from "./dispatcher.js";
+export { createOpenCodeProvider } from "./opencode.js";
+export { createOpenRouterProvider } from "./openrouter.js";
+export { createGenericProvider } from "./generic.js";
+export { createWorkbuddyProvider } from "./workbuddy.js";
+export { splitModelId, joinModelId, normalizeProviderId, DEFAULT_PROVIDER } from "./model-id.js";

package/src/providers/keyring.js

@@ -0,0 +1,38 @@
+// 多 key 轮转器：round-robin 取键 + 出错冷却隔离。
+// 语义：某个 key 出错后 cooldownMs 内不再使用；全部 key 都在冷却 → next() 返回 null
+// （调用方应视为该供应商暂时失效，直接报错而非降级为单 key）。
+export const DEFAULT_COOLDOWN_MS = 30_000;
+
+export function createKeyRing(keys = [], { cooldownMs = DEFAULT_COOLDOWN_MS, now = Date.now } = {}) {
+  const list = [...new Set(keys.filter((k) => typeof k === "string" && k.trim().length))];
+  const errAt = new Map();
+  let cursor = 0;
+
+  function isCooling(key) {
+    const t = errAt.get(key);
+    return t != null && now() - t < cooldownMs;
+  }
+
+  function next() {
+    if (!list.length) return null;
+    for (let i = 0; i < list.length; i++) {
+      const idx = (cursor + i) % list.length;
+      const key = list[idx];
+      if (!isCooling(key)) {
+        cursor = (idx + 1) % list.length;
+        return key;
+      }
+    }
+    return null;
+  }
+
+  function onError(key) {
+    if (list.includes(key)) errAt.set(key, now());
+  }
+
+  function available() {
+    return list.filter((k) => !isCooling(k)).length;
+  }
+
+  return { next, onError, available, size: list.length, cooldownMs, keys: [...list] };
+}

package/src/providers/model-id.js

@@ -0,0 +1,36 @@
+// 模型 ID 前缀解析：`<provider>/<rawId>`。默认供应商（opencode）保持裸 id（向后兼容），
+// 其它供应商必须带前缀，请求按前缀路由到对应上游通道。
+
+export const DEFAULT_PROVIDER = "opencode";
+
+const ALIASES = { oc: "opencode", opencode: "opencode" };
+
+export function normalizeProviderId(p) {
+  const id = String(p || "").trim();
+  return ALIASES[id] || id;
+}
+
+// 把（可能带前缀的）模型 id 拆成 { provider, raw, prefixed }
+// - 无前缀（含默认供应商裸 id）→ provider = DEFAULT_PROVIDER
+// - 前缀是已知供应商 → 对应路由；开头的 `oc/` 视为 opencode 别名
+export function splitModelId(id, knownProviders = []) {
+  const s = String(id || "");
+  if (!s) return { provider: DEFAULT_PROVIDER, raw: s, prefixed: false };
+  const idx = s.indexOf("/");
+  if (idx > 0) {
+    const head = normalizeProviderId(s.slice(0, idx));
+    const known = new Set([DEFAULT_PROVIDER, ...knownProviders]);
+    if (known.has(head)) {
+      return { provider: head, raw: s.slice(idx + 1), prefixed: true };
+    }
+  }
+  return { provider: DEFAULT_PROVIDER, raw: s, prefixed: false };
+}
+
+// 生成对外暴露的模型 id：默认供应商裸 id（向后兼容），其它供应商带前缀
+export function joinModelId(provider, raw, { force = false } = {}) {
+  provider = normalizeProviderId(provider || "");
+  raw = String(raw || "");
+  if (provider === DEFAULT_PROVIDER && !force) return raw;
+  return `${provider}/${raw}`;
+}

package/src/providers/opencode.js

@@ -0,0 +1,20 @@
+import { createUpstreamClient } from "../upstream.js";
+import { joinModelId } from "./model-id.js";
+
+// opencode Provider：复用现有 createUpstreamClient 的全部能力（头/重试/匿名免费通道/keep-alive 预热），
+// 模型 id 保持裸 id（向后兼容）。
+export function createOpenCodeProvider({ upstream, modelsService, baseUrl, authToken, hooks } = {}) {
+  const client = upstream ?? createUpstreamClient({ baseUrl, authToken, hooks });
+  return {
+    id: "opencode",
+    upstream: client,
+    chat: (body) => client.chat(body),
+    preheat: (args) => client.preheat(args),
+    close: () => client.close(),
+    async listModels() {
+      const data = await modelsService?.get?.();
+      const list = data?.data ?? [];
+      return list.map((m) => ({ ...m, id: joinModelId("opencode", m.id) }));
+    },
+  };
+}

package/src/providers/openrouter.js

@@ -0,0 +1,217 @@
+import { joinModelId } from "./model-id.js";
+import { createKeyRing } from "./keyring.js";
+import { loadProviderKeys } from "../state.js";
+
+let UndiciAgent = null;
+let UndiciFetch = null;
+try {
+  const mod = await import("undici");
+  UndiciAgent = mod.Agent;
+  UndiciFetch = mod.fetch;
+} catch {}
+
+const DEFAULT_BASE_URL = "https://openrouter.ai/api/v1";
+
+function envInt(name, fallback) {
+  const v = Number(process.env[name]);
+  return Number.isInteger(v) && v > 0 ? v : fallback;
+}
+
+// 把 `apiKeys`(数组) + `apiKey`(单串) + state 的 key 合并成去重数组。
+// state 为空时只看显式传入；两者皆空 → []（无 key）。
+function collectApiKeys(apiKeys, apiKey) {
+  const list = [
+    ...(Array.isArray(apiKeys) ? apiKeys : [apiKeys].filter(Boolean)),
+    apiKey,
+    ...(apiKeys === undefined && apiKey === undefined ? loadProviderKeys("openrouter") : []),
+  ].filter((k) => typeof k === "string" && k.trim().length);
+  return [...new Set(list.map((k) => k.trim()))];
+}
+
+export function createOpenRouterProvider({
+  apiKeys,
+  apiKey,
+  baseUrl = process.env.MSLXDFF_OPENROUTER_BASE_URL || DEFAULT_BASE_URL,
+  connectTimeoutMs = Number(process.env.MSLXDFF_OPENROUTER_TIMEOUT_MS) || 30_000,
+  cooldownMs = envInt("MSLXDFF_OPENROUTER_COOLDOWN_MS", 30_000),
+  retry = {
+    network: { attempts: 2, delayMs: 300 },
+    429: { attempts: 1, delayMs: 100 },
+    502: { attempts: 1, delayMs: 100 },
+    503: { attempts: 1, delayMs: 100 },
+    504: { attempts: 1, delayMs: 100 },
+  },
+  fetchImpl,
+  headers: extraHeaders,
+  noAgent = false,
+} = {}) {
+  if (!fetchImpl) fetchImpl = UndiciFetch || fetch;
+
+  const ring = createKeyRing(collectApiKeys(apiKeys, apiKey), { cooldownMs });
+
+  let dispatcher = null;
+  let agent = null;
+  if (UndiciAgent && !noAgent) {
+    try {
+      agent = new UndiciAgent({
+        keepAliveTimeout: envInt("MSLXDFF_OA_KEEPALIVE_TIMEOUT", 30_000),
+        keepAliveMaxTimeout: envInt("MSLXDFF_OA_KEEPALIVE_MAX_TIMEOUT", 60_000),
+        connections: envInt("MSLXDFF_OA_KEEPALIVE_CONNECTIONS", 20),
+        pipelining: 1,
+      });
+      dispatcher = agent;
+    } catch {}
+  }
+
+  function buildHeaders(body, key) {
+    const isStream = body?.stream !== false;
+    const h = {
+      "Content-Type": "application/json",
+      "Accept": isStream ? "text/event-stream" : "*/*",
+      "User-Agent": "mslxdff",
+    };
+    if (key) h["Authorization"] = `Bearer ${key}`;
+    h["HTTP-Referer"] = process.env.MSLXDFF_OPENROUTER_REFERER || "https://github.com/mslxdff";
+    h["X-Title"] = process.env.MSLXDFF_OPENROUTER_TITLE || "mslxdff";
+    return { ...h, ...extraHeaders };
+  }
+
+  async function attemptOnce(url, body, key, activeRing) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`openrouter timed out after ${connectTimeoutMs}ms`)), connectTimeoutMs);
+    try {
+      const opts = { method: "POST", headers: buildHeaders(body, key), body: JSON.stringify(body), signal: controller.signal };
+      if (dispatcher) opts.dispatcher = dispatcher;
+      const res = await fetchImpl(url, opts);
+      if (res.status === 401 && !activeRing.size) return { __needKey: true };
+      return res;
+    } catch (err) {
+      return err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async function runChat(body, activeRing, sourceKey) {
+    const url = `${baseUrl}/chat/completions`;
+    const t0 = performance.now();
+    const attempts = [];
+    let waitMs = 0;
+
+    // 轮转取一个可用 key；仅当"有 key 但全部在冷却"才算供应商暂时失效。
+    // 没有配置任何 key 时不在这拦截——下降到 401 无 key 报错路径（__needKey）。
+    const key = activeRing.next();
+    if (!key && activeRing.size > 0) {
+      const err = new Error(`openrouter: all API keys are in cooldown (last error < ${cooldownMs}ms ago) — provider temporarily unavailable`);
+      err._t = { attempts: [], waitMs: 0, totalMs: Math.round(performance.now() - t0), cooldownMs };
+      throw err;
+    }
+
+    for (let attempt = 0; ; attempt++) {
+      const t = performance.now();
+      const result = await attemptOnce(url, body, key, activeRing);
+      const type = result instanceof Error ? "network" : `http${result?.status}`;
+      attempts.push({ attempt, type, ms: Math.round(performance.now() - t) });
+      if (result?.__needKey) {
+        const err = new Error(`openrouter: missing ${sourceKey} (chat requires a real key)`);
+        err._t = { attempts, waitMs, totalMs: Math.round(performance.now() - t0) };
+        throw err;
+      }
+      if (result instanceof Error) {
+        const entry = retry?.network;
+        if (entry && attempt < entry.attempts) {
+          await sleep(entry.delayMs);
+          waitMs += entry.delayMs;
+          continue;
+        }
+        activeRing.onError(key);
+        result._t = { attempts, waitMs, totalMs: Math.round(performance.now() - t0) };
+        throw result;
+      }
+      const entry = retry?.[result.status];
+      if (entry && attempt < entry.attempts) {
+        await sleep(entry.delayMs);
+        waitMs += entry.delayMs;
+        continue;
+      }
+      if (result.status === 401 || result.status === 403 || result.status === 429 || result.status >= 500) activeRing.onError(key);
+      result._t = { attempts, waitMs, totalMs: Math.round(performance.now() - t0) };
+      return result;
+    }
+  }
+
+  async function chat(body) {
+    return runChat(body, ring, "MSLXDFF_OPENROUTER_KEY");
+  }
+
+  // ADR-0008 瞬时共享：用组员方传来的临时 key 发布请求（不污染本 provider 的持久 ring）。
+  async function chatWithKeys(body, keys) {
+    const tmp = createKeyRing(keys, { cooldownMs });
+    return runChat(body, tmp, "shared provider keys");
+  }
+
+  // 拉免费模型：pricing 全 0 + 前缀化；可匿名
+  const CACHE_TTL_MS = 10 * 60 * 1000;
+  let cache = null;
+  let fetchedAt = 0;
+  async function listModels() {
+    const now = Date.now();
+    if (cache && now - fetchedAt < CACHE_TTL_MS) return cache;
+    const url = `${baseUrl}/models`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error("openrouter models timed out")), 15_000);
+    try {
+      const opts = { headers: { Accept: "application/json" }, signal: controller.signal };
+      if (dispatcher) opts.dispatcher = dispatcher;
+      const res = await fetchImpl(url, opts);
+      if (!res.ok) return [];
+      const json = await res.json().catch(() => ({}));
+      const raw = Array.isArray(json.data) ? json.data : [];
+      const free = raw.filter((m) =>
+        Number(m.pricing?.prompt || 0) === 0 && Number(m.pricing?.completion || 0) === 0
+      );
+      cache = free.map((m) => ({ ...m, id: joinModelId("openrouter", m.id) }));
+      fetchedAt = now;
+      return cache;
+    } catch {
+      return [];
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async function preheat() {
+    const url = `${baseUrl}/models`;
+    const t0 = performance.now();
+    try {
+      const opts = { headers: { Accept: "application/json" } };
+      if (dispatcher) opts.dispatcher = dispatcher;
+      const res = await fetchImpl(url, opts);
+      try { if (res.body) await res.text().catch(() => {}); } catch {}
+      return { ok: res.ok, status: res.status, ms: Math.round(performance.now() - t0) };
+    } catch (err) {
+      return { ok: false, error: String(err?.message || err), ms: Math.round(performance.now() - t0) };
+    }
+  }
+
+  async function close() {
+    if (agent && typeof agent.close === "function") {
+      try { await agent.close(); } catch {}
+    }
+  }
+
+  return {
+    id: "openrouter",
+    chat,
+    chatWithKeys,
+    listModels,
+    preheat,
+    close,
+    agent,
+    keyRing: ring,
+  };
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/src/providers/share-keys.js

@@ -0,0 +1,53 @@
+// ADR-0008：供应商 key 瞬时共享 —— 转发时附带、组员一次性借用，用完即弃。
+// header: `x-mslxdff-share-keys: <providerId>=<key1>,<key2>;<providerId2>=<key3>`
+import { splitModelId, DEFAULT_PROVIDER } from "./model-id.js";
+import { loadProviderKeys, loadProviderShareKeys } from "../state.js";
+
+export const SHARE_KEYS_HEADER = "x-mslxdff-share-keys";
+
+// 本节点应 cast key 到出站转发的供应商 id 集合（开启 share 且配了 key 的）。
+// share 只在"有 key 且开关为 true"时发生；否则不附带，避免空头泄露配置意图。
+// 默认供应商（opencode）恒排除：它无 key 可共享（public 即可），限流以 IP 为主，
+// 分散 IP 由 peer 转发天然实现，不需要也不应走 key 共享。
+export function shareableProviderIds({ file } = {}) {
+  const ids = new Set();
+  const raw = process.env.MSLXDFF_SHARE_PROVIDERS || ""; // 高级：显式白名单，逗号分隔
+  const explicit = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  if (explicit.length) {
+    for (const id of explicit) {
+      if (id === DEFAULT_PROVIDER) continue; // opencode 永远不可 share
+      ids.add(id);
+    }
+    return [...ids];
+  }
+  for (const id of ["openrouter"]) {
+    if (id !== DEFAULT_PROVIDER && loadProviderKeys(id, { file }).length && loadProviderShareKeys(id, { file })) ids.add(id);
+  }
+  return [...ids];
+}
+
+// 组装 share header 值（只含 shareable 且当前请求命中前缀的供应商）。
+// splitModelId 用 shareableProviderIds() 作为已知集合：命中 → 该供应商在此节点 shareable；
+// 未命中或裸 id（默认供应商 opencode）→ 不附带。返回 null 表示本请求不需要附带。
+export function buildShareKeysHeader(model, { file } = {}) {
+  const split = splitModelId(model, shareableProviderIds({ file }));
+  if (!split.provider || split.provider === DEFAULT_PROVIDER) return null;
+  const keys = loadProviderKeys(split.provider, { file });
+  if (!keys.length) return null;
+  return `${split.provider}=${keys.join(",")}`;
+}
+
+// 组员侧：解析 share header 为 { providerId -> keys[] }
+// 防御：默认供应商（opencode）即使出现在 header 一律忽略——它不该有共享 key。
+export function parseShareKeysHeader(value) {
+  const out = {};
+  if (!value) return out;
+  for (const seg of String(value).split(";")) {
+    const [provider, keysPart] = seg.split("=");
+    const id = String(provider || "").trim();
+    if (!id || id === DEFAULT_PROVIDER || !keysPart) continue;
+    const keys = String(keysPart).split(",").map((k) => k.trim()).filter(Boolean);
+    if (keys.length) out[id] = keys;
+  }
+  return out;
+}

package/src/providers/workbuddy-balance.js

@@ -0,0 +1,76 @@
+const BALANCE_TTL_MS = 5 * 60 * 1000;
+
+const balanceCache = new Map(); // uid -> { total, dailyPacks, activeCount, nextExpire, fetchedAt }
+
+export function getBalanceCache() { return balanceCache; }
+export function clearBalanceCache() { balanceCache.clear(); }
+
+export function getCachedBalance(uid) {
+  const v = balanceCache.get(String(uid));
+  if (!v) return null;
+  if (Date.now() - v.fetchedAt > BALANCE_TTL_MS) {
+    balanceCache.delete(String(uid));
+    return null;
+  }
+  return v;
+}
+
+export function setCachedBalance(uid, data) {
+  const v = { ...data, fetchedAt: Date.now() };
+  balanceCache.set(String(uid), v);
+  return v;
+}
+
+export async function fetchBalance({ uid, key, auth, domain, baseUrl = "https://www.codebuddy.cn", fetchImpl } = {}) {
+  const at = key || auth?.accessToken || "";
+  const u = uid || auth?.uid || "";
+  const d = domain || auth?.domain || "www.codebuddy.cn";
+  if (!u || !at) return null;
+  const fetcher = fetchImpl || fetch;
+  const body = JSON.stringify({
+    PageNumber: 1, PageSize: 100, ProductCode: "p_tcaca", Status: [0, 3],
+    PackageEndTimeRangeBegin: "2026-08-01 00:00:00",
+    PackageEndTimeRangeEnd: "2030-01-01 00:00:00",
+  });
+  try {
+    const res = await fetcher(`${baseUrl.replace(/\/+$/, "")}/v2/billing/meter/get-user-resource`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${at}`,
+        "Content-Type": "application/json",
+        "X-User-Id": u,
+        "X-Domain": d,
+      },
+      body,
+    });
+    if (!res.ok) return null;
+    const j = await res.json().catch(() => null);
+    const accs = j?.data?.Response?.Data?.Accounts || j?.data?.Response?.data?.Accounts || [];
+    // fallback for stub shape
+    const accounts = Array.isArray(accs) ? accs : [];
+    const active = accounts.filter(a => a.Status === 0);
+    const total = active.reduce((s, a) => s + Number(a.CycleCapacityRemainPrecise || a.CycleCapacityRemain || 0), 0);
+    const dailyPacks = active.filter(a => a.PackageName?.includes("裂变包") && String(a.CycleCapacitySizePrecise) === "100");
+    const sorted = [...active].sort((a,b)=> new Date(a.CycleEndTime) - new Date(b.CycleEndTime));
+    const nextExpire = sorted[0]?.CycleEndTime || null;
+    const data = {
+      total: Number(total.toFixed(2)),
+      dailyPacks: dailyPacks.length,
+      activeCount: active.length,
+      nextExpire,
+      fetchedAt: Date.now(),
+    };
+    // string total for CLI compatibility
+    data.totalStr = total.toFixed(2);
+    setCachedBalance(u, data);
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+export async function getBalanceWithCache({ uid, key, auth, domain, baseUrl, fetchImpl } = {}) {
+  const cached = getCachedBalance(uid || auth?.uid);
+  if (cached) return cached;
+  return fetchBalance({ uid, key, auth, domain, baseUrl, fetchImpl });
+}