dsh-subusage 0.8.3 → 0.10.0

package/lib/index.js

@@ -1,5 +1,6 @@
 // dsh-subusage Host：秘密仅保存在 Host，远端只暴露 provider 补丁和公开设置。
 import { RemoteError, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import { defineTool } from "@deepseek-ai/dsh-tools";
 import { credentialRef, isCredentialRefName } from "@deepseek-ai/dsh-credentials";
 import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
 import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
@@ -7,6 +8,7 @@ import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { MimoLogin } from "./mimo-login.js";
+import { parseVolcAgentPlan, parseVolcCodingPlan, parseVolcSeatAfp, parseVolcSeatCoding, parseVolcSeatIds, volcError, volcSignature } from "./volcengine.js";
 
 const name = "dsh-subusage";
 const inject = ["llm"];
@@ -18,13 +20,70 @@ const PROVIDERS = {
  "kimi-coding": { label: "Kimi", envName: "KIMI_CODING_API_KEY" },
  "xiaomi-token-plan-cn": { label: "MiMo", envName: "XIAOMI_TOKEN_PLAN_CN_API_KEY" },
  "opencode-go": { label: "OpenCode Go", envName: "OPENCODE_API_KEY" },
- "minimax": { label: "MiniMax", envName: "MINIMAX_API_KEY", usageUrl: "https://api.minimax.io/v1/token_plan/remains" },
+ // MiniMax 国际版默认关闭（中国版保持默认开启）。
+ "minimax": { label: "MiniMax", envName: "MINIMAX_API_KEY", usageUrl: "https://api.minimax.io/v1/token_plan/remains", defaultEnabled: false },
  "minimax-cn": { label: "MiniMax CN", envName: "MINIMAX_CN_API_KEY", usageUrl: "https://api.minimaxi.com/v1/token_plan/remains" },
+ // SiliconFlow（硅基流动）：余额型接口，鉴权与推理是**同一把** API Key（Bearer）。
+ // 官方 OpenAPI 仓库 siliconflow/siliconcloud 的 openapi.yaml 列出 GET /v1/user/info（bearerAuth）。
+ "siliconflow": { label: "SiliconFlow", envName: "SILICONFLOW_API_KEY", defaultEnabled: false },
  // Commandcode 路由由另一个插件（@mars-sea/dsh-commandcode-provider）注册：凭据、多账户与
  // API 地址都在那边管理。本插件不保存其凭据，只沿用同一凭据来源链自取 Key 后直连计费接口。
- "commandcode": { label: "Command Code", envName: "COMMANDCODE_API_KEY", managedByPlugin: true }
+ "commandcode": { label: "Command Code", envName: "COMMANDCODE_API_KEY", managedByPlugin: true },
+ // SuperGrok / X Premium 订阅路由由 dsh-grok-kit（xai-oauth）注册，登录是 OAuth：凭据只认
+ // 与 Grok CLI 共享的登录文件，API Key（XAI_API_KEY）路线取不到订阅周池，故不设继承变量。
+ "xai-oauth": { label: "SuperGrok", envName: "", managedByPlugin: true },
+ // OpenAI Codex / ChatGPT 订阅：路由由 DSH 内置的 openai-codex（或 dsh-codex-connect 等插件）提供，
+ // 额度凭据只认 Codex CLI 的 OAuth 登录文件，不提供本地凭据编辑。
+ "openai-codex": { label: "Codex (ChatGPT)", envName: "", managedByPlugin: true },
+ // 火山方舟：方舟路由由两种方式写入——官方 CLI（arkcli helper，见下）或官方插件
+ // @volcengine/ark-plan-api（legacy 段）。**provider id 必须与写入方逐字一致**，
+ // 否则选中方舟模型时药丸不会出现。额度读取走管控面 OpenAPI，凭据是 IAM 的 AK/SK 配对
+ // （HMAC-SHA256 签名），与这些路由的推理 API Key 是两套：拿推理 Key 去查额度会被上游拒绝
+ // （"GetAFPUsage requires Volcengine Ark SSO STS"）。
+ // 7 条 volc 路由共用一组 AK/SK（settings.volc）：个人版各自固定一个 Action，
+ // 企业版/团队版走 ListSeatInfos → GetSeatAFPUsage / GetSeatInfoUsage 两步。
+ // ── arkcli（官方 CLI）安装的路由 ──────────────────────────────────────────
+ // 官方 CLI 的 `arkcli helper configure deepseek-harness` 把 provider 写成
+ // `arkcli-<planType>`（本机实测：`arkcli-agent-plan`），凭据引用是
+ // `ARKCLI_<PLAN>_API_KEY`。这是目前使用人数最多的安装方式，故默认开启
+ // （没配 AK/SK 时会被「没有检测到 API 的默认隐藏」收起）。
+ // 注意：路由（数据面，模型访问）与额度查询（管控面，需 IAM AK/SK）是两码事。
+ "arkcli-agent-plan": { label: "ARK Agent Plan (arkcli)", envName: "ARKCLI_AGENT_PLAN_API_KEY", credentialKind: "volc", volcAction: "GetAFPUsage", volcHost: "open.volcengineapi.com", volcRegion: "cn-beijing" },
+ "arkcli-coding-plan": { label: "ARK Coding Plan (arkcli)", envName: "ARKCLI_CODING_PLAN_API_KEY", credentialKind: "volc", volcAction: "GetCodingPlanUsage", volcHost: "open.volcengineapi.com", volcRegion: "cn-beijing" },
+ // 企业版/团队版：额度挂在席位上，先 ListSeatInfos 取 SeatID 再查该席位（volcSeat 决定用哪对 Action）。
+ "arkcli-agent-plan-team": { label: "ARK Agent Plan Team (arkcli)", envName: "ARKCLI_AGENT_PLAN_TEAM_API_KEY", credentialKind: "volc", volcSeat: "agent", volcScene: "agent_plan_enterprise", volcHost: "open.volcengineapi.com", volcRegion: "cn-beijing", defaultEnabled: false },
+ "arkcli-coding-plan-team": { label: "ARK Coding Plan Team (arkcli)", envName: "ARKCLI_CODING_PLAN_TEAM_API_KEY", credentialKind: "volc", volcSeat: "coding", volcScene: "coding_plan_enterprise", volcHost: "open.volcengineapi.com", volcRegion: "cn-beijing", defaultEnabled: false },
+ // ── 旧插件 @volcengine/ark-plan-api 注册的路由（保留兼容）─────────────────
+ // 两条路线的 provider id 不同，故并存；装旧插件的用户仍会走这几条。
+ "ark-coding-plan-cn": { label: "Ark Coding Plan (CN, legacy plugin)", envName: "ARK_CODING_PLAN_CN_API_KEY", credentialKind: "volc", volcAction: "GetCodingPlanUsage", volcHost: "open.volcengineapi.com", volcRegion: "cn-beijing", defaultEnabled: false },
+ "ark-agent-plan-cn": { label: "Ark Agent Plan (CN, legacy plugin)", envName: "ARK_AGENT_PLAN_CN_API_KEY", credentialKind: "volc", volcAction: "GetAFPUsage", volcHost: "open.volcengineapi.com", volcRegion: "cn-beijing", defaultEnabled: false },
+ // BytePlus（海外）Coding Plan：同一套 AK/SK，但走 BytePlus 管控面与 ap-southeast-1 区域。
+ "ark-coding-plan-byteplus": { label: "Ark Coding Plan (BytePlus, legacy plugin)", envName: "ARK_CODING_PLAN_BYTEPLUS_API_KEY", credentialKind: "volc", volcAction: "GetCodingPlanUsage", volcHost: "ark.ap-southeast-1.byteplusapi.com", volcRegion: "ap-southeast-1", defaultEnabled: false },
+ // DeepSeek 官方：余额型（不是订阅窗口），与推理**同一把** API Key，端点与响应见官方文档
+ // https://api-docs.deepseek.com/zh-cn/api/get-user-balance
+ "deepseek": { label: "DeepSeek", envName: "DEEPSEEK_API_KEY" },
+ // OpenRouter：key 限额与用量走 /key（任意 key 可用），账户余额走 /credits（**只对
+ // management / provisioning key 开放**，普通推理 key 会被拒 → 静默降级为只显示限额）。
+ "openrouter": { label: "OpenRouter", envName: "OPENROUTER_API_KEY", defaultEnabled: false },
+ // 以下六家都是**余额型**（单体 GET + 一个余额数字），与推理**同一把** Key；默认关闭，
+ // 没配 Key 时由「没有检测到 API 的默认隐藏」收起。
+ "novita": { label: "Novita AI", envName: "NOVITA_API_KEY", defaultEnabled: false },
+ "hyperbolic": { label: "Hyperbolic", envName: "HYPERBOLIC_API_KEY", defaultEnabled: false },
+ "deepinfra": { label: "DeepInfra", envName: "DEEPINFRA_API_KEY", defaultEnabled: false },
+ "chutes": { label: "Chutes", envName: "CHUTES_API_KEY", defaultEnabled: false },
+ // Ollama Cloud 的鉴权是**裸 Authorization**（不加 Bearer），照抄别家实现时必须注意。
+ "ollama-cloud": { label: "Ollama Cloud", envName: "OLLAMA_API_KEY", defaultEnabled: false },
+ "vercel-ai-gateway": { label: "Vercel AI Gateway", envName: "AI_GATEWAY_API_KEY", defaultEnabled: false },
+ // ZenMux 的额度端点只认 Management API Key；变量名单独区分以免误填推理 key。
+ "zenmux": { label: "ZenMux", envName: "ZENMUX_MANAGEMENT_API_KEY", defaultEnabled: false },
+ // LiteLLM 是自建网关：除虚拟 Key 外还要配自己的 proxy 地址（settings.litellm.baseUrl）。
+ "litellm": { label: "LiteLLM", envName: "LITELLM_API_KEY", defaultEnabled: false }
 };
 const IDS = Object.keys(PROVIDERS);
+// 火山方舟额度接口的凭据是 IAM Access Key：AK 与 SK 必须同源配对，跨来源拼接只会得到 401。
+// 变量名沿用火山官方 SDK 习惯；与方舟推理 Key（ARK_*_API_KEY）无关。
+const VOLC_ACCESS_KEY_ENV = "VOLC_ACCESSKEY";
+const VOLC_SECRET_KEY_ENV = "VOLC_SECRETKEY";
 // 与 @mars-sea/dsh-commandcode-provider 一致的 CLI 版本标识（其常量 COMMAND_CODE_CLI_VERSION）。
 const COMMAND_CODE_CLI_VERSION = "1.73.0";
 const COMMAND_CODE_API_BASE = "https://api.commandcode.ai";
@@ -53,6 +112,65 @@ function commandCodeAuthFileKey(io) {
   return str(parsed.apiKey) ?? str(parsed.commandcode) ?? fromRecord(parsed.commandcode) ?? fromRecord(parsed["command-code"]);
  } catch { return undefined; }
 }
+// SuperGrok / X Premium 订阅（dsh-grok-kit 的 xai-oauth 路由）：用量走官方 Grok CLI 的计费
+// 代理（转发后端 GetGrokCreditsConfig）。凭据是 dsh-grok-kit / Grok CLI 共享登录文件里的
+// OAuth Bearer（短命轮换），只读不写、不自行刷新，避免与两端的 refresh-token 轮换互相顶掉。
+const GROK_API_BASE = "https://cli-chat-proxy.grok.com/v1";
+// 官方 GrokComConfig.token_header 默认值：必须是该字符串，nginx 鉴权子请求才路由到 OAuth。
+const GROK_TOKEN_AUTH = "xai-grok-cli";
+const GROK_CLIENT_VERSION = "1.0.13";
+const GROK_AUTH_FILE = join(homedir(), ".grok", "auth.json");
+// dsh-grok-kit 旧版私存路径（其 resolveXaiOAuthStorePath 的回退分支）。
+const XAI_OAUTH_AUTH_FILE = join(homedir(), ".dsh", ".xai-oauth-auth.json");
+// Bearer 的 JWT payload 里有 sub（= user_id）；登录文件缺 user_id 时兜底取它。
+function bearerSubject(key) {
+ try {
+  const payload = key.split(".")[1]?.replace(/-/g, "+").replace(/_/g, "/");
+  if (!payload) return undefined;
+  const claims = JSON.parse(Buffer.from(payload, "base64").toString("utf8"));
+  return typeof claims?.sub === "string" && claims.sub.trim() ? claims.sub.trim() : undefined;
+ } catch { return undefined; }
+}
+// 兼容两种登录文件形态：Grok CLI auth.json（槽位 map，槽位名含签发方）与 dsh 信封
+// （{ version, credential: { access, accountId } }）。槽位优先 auth.x.ai，其次旧签发方。
+function grokAuthFileCredentials(io) {
+ const str = v => typeof v === "string" && v.trim() ? v.trim() : undefined;
+ const read = path => {
+  try {
+   const parsed = JSON.parse(io.readFileSync(path, "utf8"));
+   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+   const envelope = parsed.credential && typeof parsed.credential === "object" && !Array.isArray(parsed.credential) ? parsed.credential : undefined;
+   const pick = (record, userId) => {
+    const key = str(record.key) ?? str(record.access) ?? str(record.access_token);
+    return key ? { key, userId: str(record.user_id) ?? str(record.principal_id) ?? userId ?? bearerSubject(key) } : undefined;
+   };
+   if (envelope) return pick(envelope, str(envelope.accountId));
+   const slots = Object.entries(parsed).filter(([, v]) => v && typeof v === "object" && !Array.isArray(v) && (str(v.key) ?? str(v.access) ?? str(v.access_token)));
+   const find = test => slots.find(([slotName]) => test(slotName))?.[1];
+   return pick(find(slotName => slotName.includes("auth.x.ai")) ?? find(slotName => slotName.includes("accounts.x.ai")) ?? slots[0]?.[1] ?? {});
+  } catch { return undefined; }
+ };
+ return read(GROK_AUTH_FILE) ?? read(XAI_OAUTH_AUTH_FILE);
+}
+// OpenAI Codex / ChatGPT 订阅额度：走 ChatGPT 后端私有接口，凭据是 Codex CLI 的 OAuth 登录文件
+// （`$CODEX_HOME/auth.json`，默认 `~/.codex/auth.json`），**与 OPENAI_API_KEY 是两套**：
+// `auth_mode` 不是 `chatgpt` 时（API Key 模式）取不到订阅额度，此时按未配置处理而不是拿 API Key 冒充。
+// 与 Grok 一样只读：token 由 Codex CLI 自己轮换，第三端刷新会互相顶掉。
+const CODEX_AUTH_DIR = join(homedir(), ".codex");
+const CODEX_API_BASE = "https://chatgpt.com/backend-api";
+export function codexAuthFileCredentials(io, env) {
+	const home = typeof env?.CODEX_HOME === "string" && env.CODEX_HOME.trim() ? env.CODEX_HOME.trim() : CODEX_AUTH_DIR;
+	try {
+		const parsed = JSON.parse(io.readFileSync(join(home, "auth.json"), "utf8"));
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+		if (parsed.auth_mode !== "chatgpt") return undefined;
+		const tokens = parsed.tokens && typeof parsed.tokens === "object" && !Array.isArray(parsed.tokens) ? parsed.tokens : {};
+		const key = typeof tokens.access_token === "string" && tokens.access_token.trim() ? tokens.access_token.trim() : undefined;
+		if (!key) return undefined;
+		const accountId = typeof tokens.account_id === "string" && tokens.account_id.trim() ? tokens.account_id.trim() : undefined;
+		return { key, accountId };
+	} catch { return undefined; }
+}
 const CONFIG_PATH = join(homedir(), ".dsh", "dsh-subusage.json");
 // 官方 MiMo 会话 Cookie 自签发起 24 小时有效；从凭据写入时刻起计时，手动导入与自动登录同源。
 const MIMO_COOKIE_TTL_MS = 24 * 60 * 60 * 1000;
@@ -69,12 +187,14 @@ function redactMimo(value, cookie) {
  return { ...value, ...(Array.isArray(value.extras) ? { extras: value.extras.map(extra => extra.kind === "plan" ? { ...extra, value: sanitize(extra.value) } : extra) } : {}) };
 }
 function defaultSettings() {
- return { zai: { type: 1, organization: "", project: "" }, xiaomi: { cookie: "", loginAt: 0, expiresAt: 0 }, keys: {}, keyModes: Object.fromEntries(IDS.map(id => [id, "inherit"])), visibility: { hideWithoutApi: true, providers: Object.fromEntries(IDS.map(id => [id, PROVIDERS[id].defaultEnabled !== false])) } };
+ return { zai: { type: 1, organization: "", project: "" }, volc: { accessKeyId: "", secretAccessKey: "" }, litellm: { baseUrl: "" }, xiaomi: { cookie: "", loginAt: 0, expiresAt: 0 }, keys: {}, keyModes: Object.fromEntries(IDS.map(id => [id, "inherit"])), visibility: { hideWithoutApi: true, providers: Object.fromEntries(IDS.map(id => [id, PROVIDERS[id].defaultEnabled !== false])) } };
 }
 function parseStored(value) {
  const s = defaultSettings();
  if (!value || typeof value !== "object" || Array.isArray(value)) throw failure("subusage/config", "设置文件结构无效");
  if (value.zai && typeof value.zai === "object") s.zai = { type: value.zai.type === 2 ? 2 : 1, organization: typeof value.zai.organization === "string" ? value.zai.organization : "", project: typeof value.zai.project === "string" ? value.zai.project : "" };
+ if (value.volc && typeof value.volc === "object" && !Array.isArray(value.volc)) for (const field of ["accessKeyId", "secretAccessKey"]) if (typeof value.volc[field] === "string") s.volc[field] = value.volc[field];
+ if (value.litellm && typeof value.litellm === "object" && !Array.isArray(value.litellm) && typeof value.litellm.baseUrl === "string") s.litellm.baseUrl = value.litellm.baseUrl;
  if (value.xiaomi && typeof value.xiaomi === "object") { if (typeof value.xiaomi.cookie === "string") s.xiaomi.cookie = value.xiaomi.cookie; for (const field of ["loginAt", "expiresAt"]) if (Number.isSafeInteger(value.xiaomi[field]) && value.xiaomi[field] > 0) s.xiaomi[field] = value.xiaomi[field]; }
  if (typeof value.visibility?.hideWithoutApi === "boolean") s.visibility.hideWithoutApi = value.visibility.hideWithoutApi;
  for (const id of IDS) {
@@ -86,7 +206,7 @@ function parseStored(value) {
  return s;
 }
 function publicSettings(s) {
- return { revision: hash(s), zai: { ...s.zai }, xiaomi: { hasCookie: !!s.xiaomi.cookie.trim(), loginAt: isoStamp(s.xiaomi.loginAt), expiresAt: isoStamp(s.xiaomi.expiresAt) }, hasKeys: Object.fromEntries(IDS.map(id => [id, !!s.keys[id]?.trim()])), keyModes: { ...s.keyModes }, visibility: { hideWithoutApi: s.visibility.hideWithoutApi, providers: { ...s.visibility.providers } } };
+ return { revision: hash(s), zai: { ...s.zai }, volc: { hasAccessKeyId: !!s.volc.accessKeyId?.trim(), hasSecretAccessKey: !!s.volc.secretAccessKey?.trim() }, litellm: { baseUrl: s.litellm.baseUrl }, xiaomi: { hasCookie: !!s.xiaomi.cookie.trim(), loginAt: isoStamp(s.xiaomi.loginAt), expiresAt: isoStamp(s.xiaomi.expiresAt) }, hasKeys: Object.fromEntries(IDS.map(id => [id, !!s.keys[id]?.trim()])), keyModes: { ...s.keyModes }, visibility: { hideWithoutApi: s.visibility.hideWithoutApi, providers: { ...s.visibility.providers } } };
 }
 function invalid(message) { return new RemoteError("subusage/invalid-request", message, { retryable: false, retainPrevious: false }); }
 function parseUpdate(update) {
@@ -112,6 +232,8 @@ function parseSettings(value) {
  if (value.expectedRevision !== undefined) { if (typeof value.expectedRevision !== "string") throw invalid("Invalid revision"); out.expectedRevision = value.expectedRevision; }
  if (value.keyMode !== undefined) { if (!["inherit", "manual"].includes(value.keyMode)) throw invalid("Invalid key mode"); out.keyMode = value.keyMode; }
  for (const field of ["keyUpdate", "cookieUpdate"]) if (value[field] !== undefined) out[field] = parseUpdate(value[field]);
+ // 火山方舟的凭据是 AK/SK 配对，只能走 volc 补丁；单值 keyUpdate 会让 AK 与 SK 失去配对来源。
+ if (PROVIDERS[value.providerId]?.credentialKind === "volc" && (value.keyUpdate !== undefined || value.cookieUpdate !== undefined)) throw invalid("Volcengine credentials use the volc patch");
  if (PROVIDERS[value.providerId]?.managedByPlugin && (out.keyMode !== undefined || out.keyUpdate !== undefined || out.cookieUpdate !== undefined)) throw invalid("Credentials are managed by the provider plugin");
  if (out.keyUpdate?.action === "replace" && /[\x00-\x1f\x7f]/.test(value.keyUpdate.value)) throw invalid("Invalid API key");
  if (out.cookieUpdate && out.providerId !== "xiaomi-token-plan-cn") throw invalid("Cookie patch is MiMo-only");
@@ -130,6 +252,22 @@ function parseSettings(value) {
   if (out.providerId !== "zai-coding-cn" || !value.zai || ![1, 2].includes(value.zai.type) || typeof value.zai.organization !== "string" || typeof value.zai.project !== "string") throw invalid("Invalid Z.ai patch");
   out.zai = { type: value.zai.type, organization: value.zai.organization.trim(), project: value.zai.project.trim() };
  }
+ if (value.litellm !== undefined) {
+  // 端点地址不是秘密，可以原样回显；这里只做形状校验，真正的合法性在请求前用 URL 解析把关。
+  if (out.providerId !== "litellm" || !value.litellm || typeof value.litellm !== "object" || Array.isArray(value.litellm) || typeof value.litellm.baseUrl !== "string" || Object.keys(value.litellm).some(key => key !== "baseUrl")) throw invalid("Invalid LiteLLM patch");
+  if (/[\x00-\x1f\x7f]/.test(value.litellm.baseUrl)) throw invalid("Invalid LiteLLM base URL");
+  out.litellm = { baseUrl: value.litellm.baseUrl.trim() };
+ }
+ if (value.volc !== undefined) {
+  const volc = value.volc;
+  if (PROVIDERS[out.providerId]?.credentialKind !== "volc" || !volc || typeof volc !== "object" || Array.isArray(volc) || !Object.keys(volc).length || Object.keys(volc).some(key => !["accessKeyId", "secretAccessKey"].includes(key))) throw invalid("Invalid Volcengine patch");
+  // 每个字段各自 keep/replace/clear：SK 不回显，空串不能当清空，否则只改 AK 会把已存的 SK 一起抹掉。
+  for (const [field, target] of [["accessKeyId", "accessKeyUpdate"], ["secretAccessKey", "secretKeyUpdate"]]) {
+   if (volc[field] === undefined) continue;
+   out[target] = parseUpdate(volc[field]);
+   if (out[target].action === "replace" && /[\x00-\x1f\x7f]/.test(volc[field].value)) throw invalid("Invalid Volcengine credential");
+  }
+ }
  return out;
 }
 function parseQuery(value) {
@@ -145,9 +283,20 @@ function parseQuery(value) {
 function failure(code, message, retryable = false, retryAfterMs) {
  return new RemoteError(code, message, { retryable, retainPrevious: retryable, ...(retryAfterMs !== undefined ? { retryAfterMs } : {}) });
 }
-async function fetchJson(fetcher, url, headers, lifetimeSignal) {
+// 火山方舟把拒绝原因放在 ResponseMetadata.Error 业务信封里：401 是签名/凭据（服务端不知道你是谁），
+// 403 是授权（身份已确认但不能做：IAM 权限不足、套餐未开通、欠费），两者对用户的行动项不同。
+function volcFailure(action, error) {
+ const detail = error.message ? ` · ${error.message}` : "";
+ if (/^(AuthenticationError|SignatureDoesNotMatch|InvalidAccessKey|InvalidSecretToken|InvalidCredential|InvalidAuthorization|MissingRequestInfo|InvalidTimestamp)$/.test(error.code)) return failure("subusage/auth", `火山方舟 ${action}：凭据或签名无效（${error.code}）${detail}。额度查询要 IAM Access Key 的 AK/SK，不是推理用的方舟 API Key`);
+ if (/^(AccessDenied|OperationDenied|AccountOverdueError)/.test(error.code)) return failure("subusage/auth", `火山方舟 ${action}：${error.code}${detail}。请确认该 AK/SK 有方舟读权限，且账号已订阅对应套餐`);
+ if (error.code === "InvalidActionOrVersion" || error.code === "PathNotFound") return failure("subusage/response", `火山方舟 ${action}：接口不存在（${error.code}），该 Action 可能已变更`);
+ if (error.code === "FlowLimitExceeded") return failure("subusage/rate-limit", `火山方舟 ${action}：触发限流`, true);
+ if (/InternalError|InternalServiceError/.test(error.code)) return failure("subusage/http", `火山方舟 ${action}：服务端错误（${error.code}）`, true);
+ return failure("subusage/response", `火山方舟 ${action}：${error.code}${detail}`);
+}
+async function fetchJson(fetcher, url, headers, lifetimeSignal, init = {}) {
  let response;
- try { response = await fetcher(url, { headers: { accept: "application/json", "user-agent": "dsh-subusage/0.8.3", ...headers }, signal: lifetimeSignal ? AbortSignal.any([AbortSignal.timeout(10000), lifetimeSignal]) : AbortSignal.timeout(10000), redirect: "manual" }); }
+ try { response = await fetcher(url, { method: init.method ?? "GET", ...(init.body !== undefined ? { body: init.body } : {}), headers: { accept: "application/json", "user-agent": "dsh-subusage/0.10.0", ...headers }, signal: lifetimeSignal ? AbortSignal.any([AbortSignal.timeout(10000), lifetimeSignal]) : AbortSignal.timeout(10000), redirect: "manual" }); }
  catch { throw failure("subusage/network", "网络请求失败或超时", true); }
  if (response.status >= 300 && response.status < 400 || response.status === 401 || response.status === 403) throw failure("subusage/auth", "登录或凭据已失效");
  if (!response.ok) {
@@ -257,7 +406,8 @@ export function normalizeSynthetic(body) {
  return { windows: [windowRow("rolling", row.requests / row.limit * 100, row.renewsAt, undefined, { used: row.requests, limit: row.limit, unit: "requests" })], extras: [], coverage: "complete" };
 }
 // https://docs.nano-gpt.com/api-reference/endpoint/subscription-usage
-export function normalizeNanoGpt(body) {
+// 第二个参数是 /api/check-balance 的可选余额响应：余额是**增量**，拿不到就不显示，不影响配额。
+export function normalizeNanoGpt(body, balanceBody) {
  if (typeof body?.active !== "boolean" || !["active", "grace", "inactive"].includes(body.state)) throw failure("subusage/response", "Invalid NanoGPT subscription response");
  const windows = []; let partial = false;
  if (body.active && body.state !== "inactive") for (const [field, kind, limit] of [["dailyInputTokens", "day", body.limits?.dailyInputTokens], ["weeklyInputTokens", "week", body.limits?.weeklyInputTokens], ["tokens", "period", body.tokenLimits?.total]]) {
@@ -267,7 +417,10 @@ export function normalizeNanoGpt(body) {
   const reset = numeric(row.resetAt) && Number.isFinite(new Date(row.resetAt).getTime()) ? new Date(row.resetAt).toISOString() : undefined;
   windows.push(windowRow(kind, row.percentUsed * 100, reset, undefined, { used: row.used, limit, unit: "tokens" }));
  }
- return { windows: cascadeRateLimited(windows), extras: [{ kind: "plan", value: body.state }], coverage: windows.length && !partial ? "complete" : "partial" };
+ const extras = [{ kind: "plan", value: body.state }];
+ const usd = typeof balanceBody?.usd_balance === "string" && /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/.test(balanceBody.usd_balance.trim()) ? balanceBody.usd_balance.trim() : undefined;
+ if (usd) extras.push({ kind: "balance", value: `${usd} USD` });
+ return { windows: cascadeRateLimited(windows), extras, coverage: windows.length && !partial ? "complete" : "partial" };
 }
 // 官方 CLI 的计数消歧规则：有 remaining_percent 时按它校准；旧响应 usage_count 是剩余。
 // https://github.com/MiniMax-AI/cli/blob/main/src/utils/quota.ts
@@ -353,6 +506,242 @@ export function normalizeCommandCode(body, subscriptionBody) {
   cascadeRateLimited(windows.filter(w => w.kind !== "month"));
   return { windows, extras, coverage: hasMonthlyBalance && monthlyCap !== undefined ? "complete" : "partial" };
 }
+// SuperGrok / X Premium 统一用量池：GetGrokCreditsConfig 响应（官方 grok CLI 的
+// /v1/billing?format=credits）。creditUsagePercent 是“已用”百分比（0-100），剩余由
+// client 取补；新形态用 creditUsagePercent + currentPeriod（周/月），旧形态回退
+// monthlyLimit/used（美分）+ 月账期。无绝对额度字段时不编造明细。
+export function normalizeSuperGrok(body, settingsBody) {
+ const config = body?.config && typeof body.config === "object" && !Array.isArray(body.config) ? body.config : {};
+ const period = config.currentPeriod && typeof config.currentPeriod === "object" && !Array.isArray(config.currentPeriod) ? config.currentPeriod : undefined;
+ const cent = row => row && typeof row === "object" && typeof row.val === "number" && Number.isFinite(row.val) ? row.val : undefined;
+ let percent;
+ if (numeric(config.creditUsagePercent)) percent = config.creditUsagePercent;
+ else {
+  // 旧形态按美分绝对值折算比例；{}（proto3 零值）解码为 0，无上限（limit<=0）不折算。
+  const limit = cent(config.monthlyLimit), used = cent(config.used) ?? 0;
+  if (limit !== undefined && limit > 0) percent = used / limit * 100;
+ }
+ if (percent === undefined) throw failure("subusage/response", "Invalid SuperGrok billing response");
+ // 周期类型是 proto 枚举名；未知/缺失类型不猜窗口名，按通用订阅池展示；旧形态按月账期。
+ const kind = period?.type === "USAGE_PERIOD_TYPE_WEEKLY" ? "week" : period?.type === "USAGE_PERIOD_TYPE_MONTHLY" ? "month" : period ? "sub"
+  : config.billingPeriodStart !== undefined || config.billingPeriodEnd !== undefined ? "month" : "sub";
+ const windows = [windowRow(kind, percent, period?.end ?? config.billingPeriodEnd)];
+ const extras = [];
+ const plan = typeof settingsBody?.subscription_tier_display === "string" && settingsBody.subscription_tier_display.trim() ? settingsBody.subscription_tier_display.trim()
+  : typeof body?.subscription_tier === "string" && body.subscription_tier.trim() ? body.subscription_tier.trim() : "";
+ if (plan) extras.push({ kind: "plan", value: plan });
+ // prepaidBalance（已购加量余额）以美分计价；只合并真正报告过的值，未报告不冒充 0。
+ const prepaid = cent(config.prepaidBalance);
+ if (prepaid !== undefined) extras.push({ kind: "balance", value: `${(prepaid / 100).toFixed(2)} USD` });
+ return { windows, extras, coverage: "complete" };
+}
+// SiliconFlow（硅基流动）：**余额型** provider —— 接口返回账户余额而不是订阅窗口。
+// 官方 OpenAPI 仓库 siliconflow/siliconcloud 的 openapi.yaml：GET https://api.siliconflow.cn/v1/user/info
+// （bearerAuth，与推理同一把 Key），返回 data.balance / chargeBalance / totalBalance / status。
+// 没有上限也就没有百分比：不把余额硬凑成一个窗口，只产出 extras，由客户端的余额兜底文案显示。
+export function normalizeSiliconFlow(body) {
+ const data = body?.data;
+ if (!data || typeof data !== "object" || Array.isArray(data)) throw failure("subusage/response", "Invalid SiliconFlow user info response");
+ const amount = value => typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.round(value * 100) / 100 : undefined;
+ const total = amount(data.totalBalance) ?? amount(data.balance);
+ if (total === undefined) throw failure("subusage/response", "SiliconFlow 响应没有可用余额");
+ // 响应不带货币字段；该平台以人民币计价，所以按 CNY 显示，不猜测成其它货币。
+ return { windows: [], extras: [{ kind: "balance", value: `${total} CNY` }], coverage: "complete" };
+}
+// Codex / ChatGPT 订阅用量：rate_limit.primary_window 与 secondary_window 各含 used_percent 与
+// resets_at。免费档的次窗口是 30 天，所以有 window_seconds 时按它判窗口名，缺失时按位置回退 5h / 7d。
+// credits 只在真正报告了可用余额时显示：has_credits=false、unlimited=true、balance="0" 都不显示，
+// 不把「无额度」画成 0。
+// https://raw.githubusercontent.com/steipete/CodexBar/main/docs/codex.md
+export function normalizeCodexUsage(body) {
+	const windows = [];
+	const windowKind = (row, fallback) => {
+		const seconds = row?.window_seconds ?? row?.limit_window_seconds;
+		if (!Number.isFinite(seconds) || seconds <= 0) return fallback;
+		return seconds >= 2592000 ? "month" : seconds >= 604800 ? "week" : seconds >= 86400 ? "day" : "5h";
+	};
+	const push = (row, fallback) => {
+		if (!row || typeof row !== "object" || Array.isArray(row)) return;
+		if (!numeric(row.used_percent)) throw failure("subusage/response", "Invalid Codex used_percent");
+		// 实测（2026-10-09）：resets_at 是 **Unix 秒数**，不是 ISO 串——两种都要认，否则重置时间会静默丢失。
+		const raw = row.resets_at ?? row.reset_at;
+		const reset = typeof raw === "string" && Number.isFinite(Date.parse(raw)) ? new Date(Date.parse(raw)).toISOString()
+			: numeric(raw) && raw > 0 ? new Date(raw * 1000).toISOString()
+			: undefined;
+		windows.push(windowRow(windowKind(row, fallback), row.used_percent, reset));
+	};
+	const limits = body?.rate_limit && typeof body.rate_limit === "object" && !Array.isArray(body.rate_limit) ? body.rate_limit : {};
+	push(limits.primary_window, "5h");
+	push(limits.secondary_window, "7d");
+	// HTTP 200 但没有任何窗口 = 该账号没有可读的订阅额度，不是 0% 用量。
+	if (!windows.length) return { windows: [], extras: [{ kind: "plan", value: "未检测到订阅额度窗口" }], coverage: "partial" };
+	const extras = [];
+	// 实测：plan_type 给套餐档位（如 "plus"），值得显示。
+	const plan = typeof body?.plan_type === "string" && body.plan_type.trim() ? body.plan_type.trim() : "";
+	if (plan) extras.push({ kind: "plan", value: plan });
+	const credits = body?.credits && typeof body.credits === "object" && !Array.isArray(body.credits) ? body.credits : {};
+	const balance = typeof credits.balance === "string" && credits.balance.trim() ? credits.balance.trim() : typeof credits.balance === "number" ? String(credits.balance) : "";
+	if (credits.has_credits === true && credits.unlimited !== true && balance && balance !== "0") extras.push({ kind: "balance", value: balance });
+	return { windows: cascadeRateLimited(windows), extras, coverage: windows.length >= 2 ? "complete" : "partial" };
+}
+// DeepSeek 官方余额（余额型）：GET https://api.deepseek.com/user/balance，Bearer 与推理同一把 Key。
+// 响应 { is_available, balance_infos: [{ currency, total_balance, granted_balance, topped_up_balance }] }，
+// 金额是**字符串十进制**。余额没有上限也就没有百分比：不产出窗口，只产出 extras。
+export function normalizeDeepseekBalance(body) {
+	if (typeof body?.is_available !== "boolean") throw failure("subusage/response", "Invalid DeepSeek balance response");
+	const infos = Array.isArray(body.balance_infos) ? body.balance_infos : [];
+	const row = infos.find(item => item && typeof item.currency === "string" && typeof item.total_balance === "string" && /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/.test(item.total_balance));
+	if (!row) throw failure("subusage/response", "DeepSeek 响应没有可用的余额信息");
+	const currency = /^[A-Z]{3}$/.test(row.currency) ? row.currency : "";
+	const extras = [{ kind: "balance", value: `${row.total_balance} ${currency}`.trim() }];
+	// 余额不可用是行动项（去充值），不是 0 元余额的展示问题。
+	if (body.is_available === false) extras.push({ kind: "plan", value: "余额不足，请充值" });
+	return { windows: [], extras, coverage: "complete" };
+}
+// OpenRouter：/key 给 key 级限额与日/周/月用量（任意 key 可读），/credits 给账户余额
+// （只对 management / provisioning key 开放）。余额拿不到时**静默降级**为只显示限额，
+// 不因为余额端点 403 就把整个条目判失败。
+// https://openrouter.ai/docs/api/api-reference/api-keys/get-current-key
+export function normalizeOpenRouter(keyBody, creditBody) {
+	const data = keyBody?.data;
+	if (!data || typeof data !== "object" || Array.isArray(data)) throw failure("subusage/response", "Invalid OpenRouter key response");
+	const num = value => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+	const windows = [];
+	const limit = num(data.limit), remaining = num(data.limit_remaining);
+	if (limit !== undefined && limit > 0 && remaining !== undefined) {
+		const kind = data.limit_reset === "monthly" ? "month" : data.limit_reset === "weekly" ? "week" : data.limit_reset === "daily" ? "day" : "period";
+		windows.push(windowRow(kind, Math.max(0, limit - remaining) / limit * 100, undefined, undefined, { used: Math.round(Math.max(0, limit - remaining) * 100) / 100, limit, unit: "credits" }));
+	}
+	// 免费档没有 key 限额，但有免费模型的每日请求上限：它同样是一个真实窗口。
+	const free = data.free_model_daily_requests;
+	const freeLimit = num(free?.limit), freeUsed = num(free?.used);
+	if (freeLimit !== undefined && freeLimit > 0 && freeUsed !== undefined) {
+		windows.push(windowRow("day", Math.min(100, freeUsed / freeLimit * 100), undefined, undefined, { used: freeUsed, limit: freeLimit, unit: "requests" }));
+	}
+	const extras = [];
+	const credits = creditBody?.data;
+	const total = num(credits?.total_credits), spent = num(credits?.total_usage);
+	if (total !== undefined && spent !== undefined) extras.push({ kind: "balance", value: `${Math.round(Math.max(0, total - spent) * 100) / 100} USD` });
+	if (data.is_free_tier === true) extras.push({ kind: "plan", value: "Free tier" });
+	if (!windows.length && !extras.length) throw failure("subusage/response", "OpenRouter 响应没有可用的限额或余额");
+	return { windows: cascadeRateLimited(windows), extras, coverage: windows.length ? "complete" : "partial" };
+}
+// ── 余额型聚合商（各家单位与形状都不同，逐个显式换算，不做通用折算）────────────────
+/** Novita：金额单位是 1/10000 USD（10000 = $1.00）。 */
+export function normalizeNovitaBalance(body) {
+	const num = value => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+	const available = num(body?.availableBalance);
+	if (available === undefined) throw failure("subusage/response", "Invalid Novita balance response");
+	return { windows: [], extras: [{ kind: "balance", value: `${Math.round(available / 100) / 100} USD` }], coverage: "complete" };
+}
+/** Hyperbolic：balanceCents 是美分。 */
+export function normalizeHyperbolicBalance(body) {
+	const cents = typeof body?.balanceCents === "number" && Number.isFinite(body.balanceCents) ? body.balanceCents : undefined;
+	if (cents === undefined) throw failure("subusage/response", "Invalid Hyperbolic balance response");
+	return { windows: [], extras: [{ kind: "balance", value: `${Math.round(cents) / 100} USD` }], coverage: "complete" };
+}
+/**
+ * DeepInfra：预付资金以**负的** stripe_balance 表示，可用金额要取负；正值代表欠款。
+ * 欠款是行动项，单独提示而不是显示成负余额。
+ */
+export function normalizeDeepinfraBalance(body) {
+	const raw = typeof body?.stripe_balance === "number" && Number.isFinite(body.stripe_balance) ? body.stripe_balance : undefined;
+	if (raw === undefined) throw failure("subusage/response", "Invalid DeepInfra balance response");
+	const available = Math.round(-raw * 100) / 100;
+	const extras = [{ kind: "balance", value: `${Math.max(0, available)} USD` }];
+	if (available < 0) extras.push({ kind: "plan", value: `欠款 ${Math.abs(available)} USD` });
+	return { windows: [], extras, coverage: "complete" };
+}
+/** Chutes：{quota, used} 直接给绝对量；重置时刻接口不给，故不显示（不编造次日 00:00 UTC）。 */
+export function normalizeChutesQuota(body) {
+	const num = value => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+	const quota = num(body?.quota), used = num(body?.used);
+	if (quota === undefined || used === undefined) throw failure("subusage/response", "Invalid Chutes quota response");
+	if (quota <= 0) throw failure("subusage/response", "Chutes 配额为 0，无法计算比例");
+	return { windows: [windowRow("period", Math.min(100, used / quota * 100), undefined, undefined, { used, limit: quota, unit: "quota" })], extras: [], coverage: "complete" };
+}
+/** Ollama Cloud：limits.{session,weekly,monthly}.usage 是 **0–1 小数**；任一层缺失就跳过该窗口。 */
+export function normalizeOllamaCloudUsage(body) {
+	const limits = body?.limits && typeof body.limits === "object" && !Array.isArray(body.limits) ? body.limits : {};
+	const windows = [];
+	for (const [field, kind] of [["session", "period"], ["weekly", "week"], ["monthly", "month"]]) {
+		const usage = limits[field]?.usage;
+		if (usage === undefined || usage === null) continue;
+		if (typeof usage !== "number" || !Number.isFinite(usage) || usage < 0) throw failure("subusage/response", "Invalid Ollama Cloud usage");
+		windows.push(windowRow(kind, Math.min(100, usage * 100)));
+	}
+	if (!windows.length) throw failure("subusage/response", "Ollama Cloud 响应没有可用的额度窗口");
+	return { windows: cascadeRateLimited(windows), extras: [], coverage: windows.length >= 3 ? "complete" : "partial" };
+}
+/** Vercel AI Gateway：balance / total_used 是十进制字符串；没有限额也没有重置，只显示金额。 */
+export function normalizeVercelCredits(body) {
+	const decimal = value => typeof value === "string" && /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/.test(value.trim()) ? value.trim() : typeof value === "number" && Number.isFinite(value) ? String(value) : undefined;
+	const balance = decimal(body?.balance) ?? decimal(body?.data?.balance);
+	if (balance === undefined) throw failure("subusage/response", "Invalid Vercel AI Gateway credits response");
+	return { windows: [], extras: [{ kind: "balance", value: `${balance} USD` }], coverage: "complete" };
+}
+// ZenMux：订阅配额走 subscription/detail（`quota_5_hour.usage_percentage` 是 **0–1 小数**），
+// PAYG 余额走 payg/balance。两个端点都**只认 Management API Key**（推理 key 不适用），
+// 因此继承变量单独命名，避免用户把推理 key 填进来。
+// https://docs.zenmux.ai/api/platform/subscription-detail
+export function normalizeZenmux(subscriptionBody, balanceBody) {
+	const num = value => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+	const windows = [], extras = [];
+	const data = subscriptionBody?.data && typeof subscriptionBody.data === "object" && !Array.isArray(subscriptionBody.data) ? subscriptionBody.data : {};
+	const quota = data.quota_5_hour && typeof data.quota_5_hour === "object" ? data.quota_5_hour : {};
+	const usage = num(quota.usage_percentage);
+	if (usage !== undefined) {
+		const detail = num(quota.used_flows) !== undefined && num(quota.max_flows) !== undefined ? { used: quota.used_flows, limit: quota.max_flows, unit: "flows" } : undefined;
+		windows.push(windowRow("5h", Math.min(100, usage * 100), typeof quota.resets_at === "string" ? quota.resets_at : undefined, undefined, detail));
+	}
+	const tier = data.plan && typeof data.plan.tier === "string" ? data.plan.tier.trim() : "";
+	if (tier) extras.push({ kind: "plan", value: tier });
+	const balance = balanceBody?.data && typeof balanceBody.data === "object" && !Array.isArray(balanceBody.data) ? balanceBody.data : {};
+	const total = num(balance.total_credits);
+	if (total !== undefined) {
+		const currency = typeof balance.currency === "string" && /^[A-Za-z]{3}$/.test(balance.currency) ? balance.currency.toUpperCase() : "";
+		extras.push({ kind: "balance", value: `${Math.round(total * 100) / 100} ${currency}`.trim() });
+	}
+	if (!windows.length && !extras.length) throw failure("subusage/response", "ZenMux 响应没有可用的配额或余额");
+	return { windows: cascadeRateLimited(windows), extras, coverage: windows.length ? "complete" : "partial" };
+}
+/**
+ * LiteLLM 的管理端点在 **proxy 根**（不是 /v1）：去掉尾部斜杠与常见的 /v1 后缀，
+ * 否则会拼成 /v1/key/info 而 404。只接受 http(s)，其它协议一律视为未配置。
+ */
+export function litellmRoot(baseUrl) {
+	const raw = typeof baseUrl === "string" ? baseUrl.trim() : "";
+	if (!raw) return "";
+	let url;
+	try { url = new URL(raw); } catch { return ""; }
+	if (url.protocol !== "http:" && url.protocol !== "https:") return "";
+	const path = url.pathname.replace(/\/+$/, "").replace(/\/v1$/, "");
+	return `${url.origin}${path}`;
+}
+/**
+ * LiteLLM：`/key/info` 给 key 自身的预算与花费，`/user/info`｜`/team/info` 给更完整的视图。
+ * 有预算上限才画进度；**没有上限时不编造百分比**，只如实显示已用金额。
+ * 接口不给重置时刻时不显示重置（别把金额渲染成倒计时）。
+ * https://docs.litellm.ai/docs/proxy/virtual_keys
+ */
+export function normalizeLitellm(keyBody, budgetBody) {
+	const num = value => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+	const pick = value => value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+	// 真实响应是 `{ key, info: {...} }`；也接受直接把字段放在顶层。
+	const keyInfo = pick(keyBody?.info) ?? pick(keyBody);
+	if (!keyInfo) throw failure("subusage/response", "Invalid LiteLLM key info response");
+	const scope = pick(budgetBody) ?? {};
+	const spend = num(scope.spend) ?? num(keyInfo.spend);
+	const maxBudget = num(scope.max_budget) ?? num(keyInfo.max_budget);
+	const resetAt = typeof scope.budget_reset_at === "string" ? scope.budget_reset_at : typeof keyInfo.budget_reset_at === "string" ? keyInfo.budget_reset_at : undefined;
+	const round = value => Math.round(value * 100) / 100;
+	if (spend !== undefined && maxBudget !== undefined && maxBudget > 0) {
+		return { windows: [windowRow("period", Math.min(100, spend / maxBudget * 100), resetAt, undefined, { used: round(spend), limit: round(maxBudget), unit: "USD" })], extras: [], coverage: "complete" };
+	}
+	// 没有预算上限：没有百分比可算，如实给金额。
+	if (spend !== undefined) return { windows: [], extras: [{ kind: "spend", value: `${round(spend)} USD` }], coverage: "complete" };
+	throw failure("subusage/response", "LiteLLM 响应没有可用的预算或花费");
+}
 function detectConfigured(ctx) {
  try { const ids = new Set(ctx.llm.listProviders().map(p => p.id)); return Object.fromEntries(IDS.map(id => [id, ids.has(id)])); }
  catch { return Object.fromEntries(IDS.map(id => [id, false])); }
@@ -385,11 +774,18 @@ export class SubUsageService extends TypertRemoteService {
   this.now = options.now ?? Date.now;
   this.credentials = options.resolveCredentials ?? (async id => await ctx.get("credentials")?.resolve(credentialRef(PROVIDERS[id].envName)));
   this.environment = options.resolveEnvironment ?? (id => launchEnvironmentOf(ctx).get(PROVIDERS[id].envName));
+  // 火山方舟的 AK/SK 不是路由的推理 Key，按固定变量名各自解析，两端都命中才算配对。
+  this.credentialByName = options.resolveCredentialByName ?? (async refName => await ctx.get("credentials")?.resolve(credentialRef(refName)));
+  this.environmentByName = options.resolveEnvironmentByName ?? (refName => launchEnvironmentOf(ctx).get(refName));
   // 额外账户按凭据引用名（apiKeyEnv）解析，与提供方插件 slots()/resolveRef 同一通道；
   // 默认账户仍走上面的 envName 链（凭据服务 → 启动环境 → ~/.commandcode/auth.json）。
   this.accountCredentials = options.resolveAccountCredentials ?? (async ref => await ctx.get("credentials")?.resolve(credentialRef(ref)));
   this.accountEnvironment = options.resolveAccountEnvironment ?? (ref => launchEnvironmentOf(ctx).get(ref));
   this.authFile = options.resolveAuthFile ?? (async () => commandCodeAuthFileKey(this.io));
+  // SuperGrok 只读共享登录文件（~/.grok/auth.json 等）取 OAuth Bearer；可注入仅供隔离测试。
+  this.grokAuth = options.resolveGrokAuth ?? (async () => grokAuthFileCredentials(this.io));
+  // Codex 只读共享登录文件（$CODEX_HOME/auth.json 或 ~/.codex/auth.json）取 OAuth access token。
+  this.codexAuth = options.resolveCodexAuth ?? (async () => codexAuthFileCredentials(this.io, { CODEX_HOME: (await this.environmentByName("CODEX_HOME"))?.value }));
   this.cache = new Map(); this.inflight = new Map(); this.generations = new Map(); this.fingerprints = new Map(); this.disposed = false; this.controller = new AbortController();
   this.login = new MimoLogin({
    error: failure,
@@ -413,6 +809,18 @@ export class SubUsageService extends TypertRemoteService {
  result(settings, entries) { return { updatedAt: new Date(this.now()).toISOString(), settings: publicSettings(settings), configured: detectConfigured(this.ctx), entries }; }
  async identity(id, s, account) {
   if (id === "xiaomi-token-plan-cn") return { key: s.xiaomi.cookie.trim(), source: s.xiaomi.cookie.trim() ? "cookie" : "none" };
+  if (PROVIDERS[id].credentialKind === "volc") return await this.volcIdentity(id, s);
+  if (id === "xai-oauth") {
+   // SuperGrok 只认共享登录文件里的 OAuth Bearer：token 短命轮换，凭据服务/环境变量副本
+   // 必然过期顶掉新 token，故不走通用 Key 链；user_id 随行给 x-userid 请求头。
+   const cred = await this.grokAuth();
+   return cred?.key ? { key: cred.key, source: "auth-file", ...(cred.userId ? { userId: cred.userId } : {}) } : { key: undefined, source: "none" };
+  }
+  if (id === "openai-codex") {
+   // 同上：只读 Codex CLI 的 OAuth 登录文件，token 由 Codex CLI 轮换，第三端刷新会互相顶掉。
+   const cred = await this.codexAuth();
+   return cred?.key ? { key: cred.key, source: "auth-file", ...(cred.accountId ? { accountId: cred.accountId } : {}) } : { key: undefined, source: "none" };
+  }
   if (!PROVIDERS[id].managedByPlugin && s.keyModes[id] === "manual") return { key: s.keys[id]?.trim(), source: s.keys[id]?.trim() ? "manual" : "none" };
   if (id === "commandcode" && account && account !== "default") {
    // 额外账户：id 即凭据引用名（apiKeyEnv）。引用名不合法（不可能来自提供方
@@ -435,11 +843,71 @@ export class SubUsageService extends TypertRemoteService {
   }
   return PROVIDERS[id].managedByPlugin ? { key: undefined, source: "none" } : { key: s.keys[id]?.trim(), source: s.keys[id]?.trim() ? "manual" : "none" };
  }
+ // 火山方舟额度接口是 IAM Access Key 鉴权：AK 与 SK 必须**同源配对**。跨来源拼接
+ // （例如拿路由的推理 Key 去配凭据库里的 SK）只会得到 401，且报错看不出根因。
+ async volcIdentity(id, s) {
+  const ak = s.volc.accessKeyId.trim(), sk = s.volc.secretAccessKey.trim();
+  if (s.keyModes[id] === "manual") return ak && sk ? { key: ak, secret: sk, source: "manual" } : { key: undefined, secret: undefined, source: "none" };
+  const credentialAk = await this.credentialByName(VOLC_ACCESS_KEY_ENV), credentialSk = await this.credentialByName(VOLC_SECRET_KEY_ENV);
+  if (typeof credentialAk?.value === "string" && credentialAk.value.trim() && typeof credentialSk?.value === "string" && credentialSk.value.trim()) return { key: credentialAk.value.trim(), secret: credentialSk.value.trim(), source: "credentials" };
+  const envAk = await this.environmentByName(VOLC_ACCESS_KEY_ENV), envSk = await this.environmentByName(VOLC_SECRET_KEY_ENV);
+  if (typeof envAk?.value === "string" && envAk.value.trim() && typeof envSk?.value === "string" && envSk.value.trim()) return { key: envAk.value.trim(), secret: envSk.value.trim(), source: "env" };
+  return ak && sk ? { key: ak, secret: sk, source: "manual" } : { key: undefined, secret: undefined, source: "none" };
+ }
  async fetchProvider(id, identity, settings, signal = this.controller.signal) {
-  const get = (url, headers) => fetchJson(this.fetcher, url, headers, signal);
+  const get = (url, headers, init) => fetchJson(this.fetcher, url, headers, signal, init);
+  // 火山方舟额度走管控面 OpenAPI：POST 根路径 + Action/Version 在 query，鉴权是 AK/SK 签名。
+  if (PROVIDERS[id].credentialKind === "volc") {
+   const spec = PROVIDERS[id];
+   const call = async (action, payload) => {
+    const body = payload === undefined ? "{}" : JSON.stringify(payload);
+    const signed = volcSignature({ accessKeyId: identity.key, secretAccessKey: identity.secret, action, host: spec.volcHost, region: spec.volcRegion, body });
+    const response = await get(signed.url, signed.headers, { method: "POST", body });
+    const apiError = volcError(response);
+    if (apiError) throw volcFailure(action, apiError);
+    return response;
+   };
+   const toWindows = parsed => cascadeRateLimited(parsed.windows.map(w => windowRow(w.kind, w.percent, w.resetsAt, w.percent >= 100 ? "rate-limited" : undefined, w.detail)));
+   // 企业版/团队版：额度挂在席位上，先取 SeatID 再查该席位。
+   if (spec.volcSeat) {
+    const seatIds = parseVolcSeatIds(await call("ListSeatInfos", { Filter: {}, Scene: spec.volcScene, PageNum: 1, PageSize: 100 }));
+    if (!seatIds.length) return { windows: [], extras: [{ kind: "plan", value: "该账号下没有可读的席位（或当前身份无权查看）" }], coverage: "partial" };
+    const seatId = seatIds[0];
+    // 多个席位时只看第一个，但如实说明总数，不假装看全了。
+    const seatNote = seatIds.length > 1 ? `${seatId}（共 ${seatIds.length} 个席位）` : seatId;
+    let parsed;
+    try {
+     parsed = spec.volcSeat === "agent"
+      ? parseVolcSeatAfp(await call("GetSeatAFPUsage", { SeatIDs: [seatId] }))
+      // GetSeatInfoUsage **确实有 Scene 参数**（官方契约 + ark-cli 源码一致）：Coding Plan 企业版传空字符串。
+      // 传错值（如 "coding_plan"）会**静默返回空 SeatID 而不报错**，所以这里必须精确。
+      : parseVolcSeatCoding(await call("GetSeatInfoUsage", { SeatID: seatId, Scene: "" }));
+    } catch (error) { if (error instanceof RemoteError) throw error; throw failure("subusage/response", `火山方舟 ${spec.volcSeat === "agent" ? "GetSeatAFPUsage" : "GetSeatInfoUsage"} 的额度结构无法解析`); }
+    const extras = [];
+    if (parsed.plan) extras.push({ kind: "plan", value: parsed.plan });
+    // 与个人版口径一致：没有窗口时说清「本周期没有可读额度」，而不是只给一个 partial 状态。
+    extras.push({ kind: "account", value: parsed.windows.length ? `席位 ${seatNote}` : `席位 ${seatNote}（本周期没有可读的额度窗口）` });
+    return { windows: toWindows(parsed), extras, coverage: parsed.windows.length ? "complete" : "partial" };
+   }
+   const body = await call(spec.volcAction);
+   let parsed;
+   try { parsed = spec.volcAction === "GetAFPUsage" ? parseVolcAgentPlan(body) : parseVolcCodingPlan(body); }
+   catch { throw failure("subusage/response", `火山方舟 ${spec.volcAction} 的额度结构无法解析`); }
+   const windows = toWindows(parsed);
+   const extras = [];
+   if (parsed.plan) extras.push({ kind: "plan", value: parsed.plan });
+   // HTTP 200 但窗口为空是「未订阅」，不是 0% 用量：显式说明，不画零额度的假象。
+   else if (!windows.length) extras.push({ kind: "plan", value: parsed.subscribed ? "本周期暂无窗口数据" : "未检测到该套餐订阅" });
+   return { windows, extras, coverage: windows.length ? "complete" : "partial" };
+  }
   const headers = { authorization: `Bearer ${identity.key}` };
   if (id === "synthetic") return normalizeSynthetic(await get("https://api.synthetic.new/v2/quotas", headers));
-  if (id === "nanogpt") return normalizeNanoGpt(await get(identity.key.startsWith("sk-nano-mgmt-") ? "https://nano-gpt.com/api/management/v1/subscription/usage" : "https://api.nano-gpt.com/api/subscription/v1/usage", headers));
+  if (id === "nanogpt") {
+   const body = await get(identity.key.startsWith("sk-nano-mgmt-") ? "https://nano-gpt.com/api/management/v1/subscription/usage" : "https://api.nano-gpt.com/api/subscription/v1/usage", headers);
+   // 余额走独立端点，且鉴权头是 x-api-key（不是 Bearer）；拿不到就静默降级，不影响配额展示。
+   const balance = await get("https://nano-gpt.com/api/check-balance", { "x-api-key": identity.key }, { method: "POST", body: "{}" }).catch(() => undefined);
+   return normalizeNanoGpt(body, balance);
+  }
   if (id === "zai-coding") {
    const out = normalizeZai(await get("https://api.z.ai/api/monitor/usage/quota/limit", { authorization: identity.key }));
    return { windows: out.windows, extras: out.level ? [{ kind: "plan", value: out.level }] : [] };
@@ -455,6 +923,42 @@ export class SubUsageService extends TypertRemoteService {
   }
   if (id === "opencode-go") return normalizeOpencodeGo(await get("https://opencode.ai/zen/go/v1/usage", headers));
    if (id === "minimax" || id === "minimax-cn") return normalizeMinimax(await get(PROVIDERS[id].usageUrl, headers));
+  if (id === "siliconflow") return normalizeSiliconFlow(await get("https://api.siliconflow.cn/v1/user/info", headers));
+  if (id === "deepseek") return normalizeDeepseekBalance(await get("https://api.deepseek.com/user/balance", headers));
+  if (id === "openrouter") {
+   const keyBody = await get("https://openrouter.ai/api/v1/key", headers);
+   // 余额端点对普通推理 key 会 403；这一次失败不影响 key 限额与用量的展示。
+   const creditBody = await get("https://openrouter.ai/api/v1/credits", headers).catch(() => undefined);
+   return normalizeOpenRouter(keyBody, creditBody);
+  }
+  // 余额型聚合商：单体 GET，单位换算在各 normalize 里显式做。
+  if (id === "novita") return normalizeNovitaBalance(await get("https://api.novita.ai/openapi/v1/billing/balance/detail", headers));
+  if (id === "hyperbolic") return normalizeHyperbolicBalance(await get("https://api.hyperbolic.ai/v2/customer/balance", headers));
+  if (id === "deepinfra") return normalizeDeepinfraBalance(await get("https://api.deepinfra.com/payment/checklist?compute_owed=true", headers));
+  if (id === "chutes") return normalizeChutesQuota(await get("https://api.chutes.ai/users/me/quota_usage/me", headers));
+  // Ollama Cloud 的鉴权是裸 Authorization：这里显式覆盖掉通用 Bearer。
+  if (id === "ollama-cloud") return normalizeOllamaCloudUsage(await get("https://ollama.com/api/usage", { authorization: identity.key }));
+  if (id === "vercel-ai-gateway") return normalizeVercelCredits(await get("https://ai-gateway.vercel.sh/v1/credits", headers));
+  if (id === "zenmux") {
+   // 订阅配额与 PAYG 余额各拿各的：任一失败不影响另一个。
+   const [subscription, balance] = await Promise.all([
+    get("https://zenmux.ai/api/v1/management/subscription/detail", headers).catch(() => undefined),
+    get("https://zenmux.ai/api/v1/management/payg/balance", headers).catch(() => undefined)
+   ]);
+   return normalizeZenmux(subscription, balance);
+  }
+  if (id === "litellm") {
+   // 地址是用户自己的 proxy；缺地址算「凭据不完整」，与缺 Key 一样给出可行动的指引。
+   const root = litellmRoot(settings.litellm?.baseUrl);
+   if (!root) throw failure("subusage/credentials", "未配置 LiteLLM 代理地址：在 设置 → 订阅用量 → LiteLLM 的「连接与凭据」里填写");
+   const keyInfo = await get(`${root}/key/info`, headers);
+   const own = keyInfo?.info && typeof keyInfo.info === "object" && !Array.isArray(keyInfo.info) ? keyInfo.info : {};
+   // 更完整的预算视图在 user/team info；拿不到就退回 key 自身的 info。
+   const scoped = typeof own.team_id === "string" && own.team_id.trim() ? `/team/info?team_id=${encodeURIComponent(own.team_id.trim())}`
+    : typeof own.user_id === "string" && own.user_id.trim() ? `/user/info?user_id=${encodeURIComponent(own.user_id.trim())}` : "";
+   const budget = scoped ? await get(`${root}${scoped}`, headers).catch(() => undefined) : undefined;
+   return normalizeLitellm(keyInfo, budget);
+  }
   if (id === "commandcode") {
    // 与提供方插件同一凭据来源，但直连计费接口并行拉取：其 report() 会对每个账户
    // 串行 whoami + 三个端点（60 秒预算），作为药丸刷新来源太慢。仅并行读取余额与套餐/账期；请求头对齐其 accountHeaders。
@@ -465,6 +969,21 @@ export class SubUsageService extends TypertRemoteService {
    ]);
    return normalizeCommandCode(credits, subscription);
   }
+  if (id === "xai-oauth") {
+   // 直连官方 Grok CLI 计费代理；X-XAI-Token-Auth 的取值是 token_header 字符串（xai-grok-cli）
+   // 而非布尔，x-userid 取登录文件。套餐名走 /v1/settings（subscription_tier_display），
+   // 失败不阻塞用量（回退 billing 响应里的 subscription_tier）。
+   const grokHeaders = { ...headers, "x-xai-token-auth": GROK_TOKEN_AUTH, "x-grok-client-version": GROK_CLIENT_VERSION, ...(identity.userId ? { "x-userid": identity.userId } : {}) };
+   const [billing, settings] = await Promise.all([
+    get(`${GROK_API_BASE}/billing?format=credits`, grokHeaders),
+    get(`${GROK_API_BASE}/settings`, grokHeaders).catch(() => undefined)
+   ]);
+   return normalizeSuperGrok(billing, settings);
+  }
+  if (id === "openai-codex") {
+   // ChatGPT 后端私有接口：Bearer 是 Codex CLI 的 OAuth access token，不是 OPENAI_API_KEY。
+   return normalizeCodexUsage(await get(`${CODEX_API_BASE}/wham/usage`, headers));
+  }
   const base = "https://platform.xiaomimimo.com/api/v1";
   const h = { cookie: identity.key, origin: "https://platform.xiaomimimo.com", referer: "https://platform.xiaomimimo.com/#/console/balance", "x-timezone": "UTC+08:00" };
   let usageError;
@@ -494,7 +1013,7 @@ export class SubUsageService extends TypertRemoteService {
   }
   // fingerprint 计入账户选择：切换账户后同 id 缓存/inflight 不串账（不同账户 key 必不同）；
   // 空串与 "default" 同为默认账户，归一后共享缓存。
-  const fingerprint = hash([identity.key ?? "", identity.source, settings.keyModes[id], id === "zai-coding-cn" ? settings.zai : null, id === "commandcode" ? (account && account !== "default" ? account : "default") : null]);
+  const fingerprint = hash([identity.key ?? "", identity.secret ?? "", identity.source, settings.keyModes[id], id === "zai-coding-cn" ? settings.zai : null, id === "commandcode" ? (account && account !== "default" ? account : "default") : null]);
   if (this.fingerprints.has(id) && this.fingerprints.get(id) !== fingerprint) this.generations.set(id, (this.generations.get(id) ?? 0) + 1);
   this.fingerprints.set(id, fingerprint);
   const generation = this.generations.get(id) ?? 0;
@@ -508,7 +1027,7 @@ export class SubUsageService extends TypertRemoteService {
   if (previous && (now < previous.retryAt || !resetDue && !force && now - previous.at < TTL)) return previous.entry;
   const promise = (async () => {
    const base = this.base(id, identity.source, settings, account); let entry; let retryAt = 0; let failures = previous?.failures ?? 0;
-   if (!identity.key) entry = { ...base, apiDetected: false, state: id === "xiaomi-token-plan-cn" ? "no-cookie" : "no-key", error: id === "xiaomi-token-plan-cn" ? "需登录或粘贴 Cookie" : id === "commandcode" ? (account && account !== "default" ? `未检测到账户 ${account} 的 Key：确认提供方插件已保存该账户的凭据（凭据服务或启动环境中无引用 ${account}）` : "未检测到 Key：可在 设置 → Command Code 登录、运行 cmd login，或使用 COMMANDCODE_API_KEY（凭据服务/启动环境）") : "未配置 API Key", errorCode: "subusage/no-key" };
+   if (!identity.key) entry = { ...base, apiDetected: false, state: id === "xiaomi-token-plan-cn" ? "no-cookie" : "no-key", error: id === "xiaomi-token-plan-cn" ? "需登录或粘贴 Cookie" : id === "commandcode" ? (account && account !== "default" ? `未检测到账户 ${account} 的 Key：确认提供方插件已保存该账户的凭据（凭据服务或启动环境中无引用 ${account}）` : "未检测到 Key：可在 设置 → Command Code 登录、运行 cmd login，或使用 COMMANDCODE_API_KEY（凭据服务/启动环境）") : id === "xai-oauth" ? "未检测到 Grok 登录：可在 设置 → Grok Kit（xAI OAuth）登录、运行 grok login（共享登录文件 ~/.grok/auth.json）" : id === "openai-codex" ? "未检测到 Codex 订阅登录：运行 codex login 完成 ChatGPT 登录（登录文件需为 $CODEX_HOME/auth.json 或 ~/.codex/auth.json，且 auth_mode 为 chatgpt；API Key 模式取不到订阅额度）" : PROVIDERS[id].credentialKind === "volc" ? "未配置火山方舟 AK/SK：额度查询要 IAM Access Key（VOLC_ACCESSKEY / VOLC_SECRETKEY，或在本页填写），不是推理用的方舟 API Key" : "未配置 API Key", errorCode: "subusage/no-key" };
    else try {
     const data = await this.fetchProvider(id, identity, settings);
     const usageError = data.usageError; delete data.usageError;
@@ -530,6 +1049,30 @@ export class SubUsageService extends TypertRemoteService {
   this.inflight.set(id, { fingerprint, generation, promise });
   try { return await promise; } finally { if (this.inflight.get(id)?.promise === promise) this.inflight.delete(id); }
  }
+ // 对外只读额度视图：供其他插件（ctx.get("subUsage").quota(...)）与 subusage_quota 工具使用。
+ // **刻意不返回 settings，也不返回 keySource / apiDetected**：第三方消费者只需要额度，
+ // 不需要知道本机配了哪些凭据，更不该拿到任何与 Key 相关的字段。
+ async quota(request = {}) {
+  if (this.disposed) throw failure("subusage/disposed", "服务已卸载");
+  const wanted = Array.isArray(request?.providerIds) && request.providerIds.length ? request.providerIds.filter(id => IDS.includes(id)) : [...IDS];
+  const settings = this.load();
+  const force = request?.force === true;
+  const entries = await Promise.all(wanted.map(id => this.provider(id, settings, force).catch(() => ({ providerId: id, label: PROVIDERS[id].label, state: "error", errorCode: "subusage/internal", error: "读取用量失败" }))));
+  return {
+   updatedAt: new Date(this.now()).toISOString(),
+   providers: entries.map(entry => ({
+    providerId: entry.providerId,
+    label: entry.label,
+    state: entry.state,
+    windows: Array.isArray(entry.windows) ? entry.windows : [],
+    extras: Array.isArray(entry.extras) ? entry.extras : [],
+    coverage: entry.coverage,
+    freshness: entry.freshness,
+    lastSuccessAt: entry.lastSuccessAt,
+    ...(entry.error ? { error: entry.error } : {})
+   }))
+  };
+ }
  async read(request) { return this.refresh(request && request.providerIds ? request : { providerIds: IDS, force: false }); }
  async refresh(request) {
   if (this.disposed) throw failure("subusage/disposed", "服务已卸载");
@@ -539,8 +1082,7 @@ export class SubUsageService extends TypertRemoteService {
   if (hash(latest) !== hash(settings)) return this.result(latest, query.providerIds.map(id => ({ ...this.base(id, "none", latest, query.commandCodeAccount), state: "error", errorCode: "subusage/config-changed", error: "读取期间配置已改变，请刷新" })));
   return this.result(latest, entries);
  }
- startMimoLogin(request) { return this.login.start(parseLoginStart(request)); }
- getMimoLoginStatus() { return this.login.status(); }
+ startMimoLogin(request) { return this.login.start(parseLoginStart(request)); } getMimoLoginStatus() { return this.login.status(); }
  cancelMimoLogin(request) { return this.login.cancel(parseLoginCancel(request)); }
  mimoMaterial(s) { const id = "xiaomi-token-plan-cn"; return hash([s.xiaomi.cookie, s.keys[id] ?? "", s.keyModes[id]]); }
  commitMimoLogin(cookie, captured, verified, observedExpiresAt) {
@@ -552,7 +1094,9 @@ export class SubUsageService extends TypertRemoteService {
   const entry = { ...this.base(id, "cookie", stored), ...data, state: "ok", coverage: data.coverage ?? "partial", freshness: "fresh", lastSuccessAt: new Date(this.now()).toISOString(), ...(usageError ? { errorCode: usageError.code, error: "额度暂时无法读取", retryable: usageError.details?.retryable === true } : {}) };
   // 响应内容也不得回显本次 Cookie（服务端字段属于不可信输入）。
   const safeEntry = redactMimo(entry, cookie);
-  const fingerprint = hash([cookie, "cookie", stored.keyModes[id], null, null]);
+  // 指纹段必须与 provider() 的五段顺序逐位对齐：MiMo 没有 secret，第二段固定空串。
+  // 少一段会让登录提交后的首次刷新认不出同一份缓存，重复拉取。
+  const fingerprint = hash([cookie, "", "cookie", stored.keyModes[id], null, null]);
   this.fingerprints.set(id, fingerprint); this.cache.set(id, { fingerprint, entry: safeEntry, at: this.now(), retryAt: usageError ? this.now() + 15000 : 0, failures: 0 });
   this.loginResultMaterial = this.mimoMaterial(stored);
   return this.result(stored, [safeEntry]);
@@ -563,7 +1107,9 @@ export class SubUsageService extends TypertRemoteService {
   const patch = parseSettings(settings); const stored = this.load();
   if (patch.expectedRevision !== undefined && patch.expectedRevision !== hash(stored)) throw failure("subusage/revision-conflict", "设置已被其他窗口修改，请重新读取");
   const id = patch.providerId;
-  const affected = patch.visibility ? Object.keys(patch.visibility.providers ?? {}).filter(key => stored.visibility.providers[key] !== patch.visibility.providers[key]) : [id];
+  // 火山方舟两个 provider 共用一组 AK/SK：改凭据要让所有用它的条目失效，不能只失效当前标签页。
+  const sharedVolc = patch.accessKeyUpdate !== undefined || patch.secretKeyUpdate !== undefined;
+  const affected = patch.visibility ? Object.keys(patch.visibility.providers ?? {}).filter(key => stored.visibility.providers[key] !== patch.visibility.providers[key]) : sharedVolc ? IDS.filter(key => PROVIDERS[key].credentialKind === "volc") : [id];
   if (patch.visibility) {
    if (patch.visibility.hideWithoutApi !== undefined) stored.visibility.hideWithoutApi = patch.visibility.hideWithoutApi;
    Object.assign(stored.visibility.providers, patch.visibility.providers);
@@ -580,6 +1126,12 @@ export class SubUsageService extends TypertRemoteService {
    stored.xiaomi.expiresAt = Math.min(at + MIMO_COOKIE_TTL_MS, Number.isSafeInteger(cookieCap) && cookieCap > at ? cookieCap : Number.POSITIVE_INFINITY);
   }
   if (patch.zai) stored.zai = patch.zai;
+  if (patch.litellm) stored.litellm = patch.litellm;
+  // volc 用「置空字符串」而不是 delete：这两个字段在内存里必须始终存在（publicSettings 会读它们），
+  // 空串与 parseStored 的默认值同义 = 未配置。
+  const updateVolc = (key, op) => { if (op?.action === "replace") stored.volc[key] = op.value; else if (op?.action === "clear") stored.volc[key] = ""; };
+  updateVolc("accessKeyId", patch.accessKeyUpdate);
+  updateVolc("secretAccessKey", patch.secretKeyUpdate);
   try { this.io.mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 }); this.io.writeFileSync(`${this.path}.tmp`, JSON.stringify(stored, null, 2), { encoding: "utf8", mode: 0o600 }); this.io.chmodSync(`${this.path}.tmp`, 0o600); this.io.renameSync(`${this.path}.tmp`, this.path); }
   catch { throw failure("subusage/config", "无法保存订阅设置"); }
   for (const key of affected) { this.generations.set(key, (this.generations.get(key) ?? 0) + 1); this.cache.delete(key); this.inflight.delete(key); }
@@ -590,6 +1142,76 @@ export class SubUsageService extends TypertRemoteService {
 function registerRemotes(ctx) {
  ctx.inject(["typert"], scope => { scope.effect(() => scope.typert.register({ package: subUsageRemote.package, face: "host", schemas: [], model: { services: [], events: [], objects: [] }, invocations: subUsageRemote.descriptors })); });
 }
-function apply(ctx) { registerRemotes(ctx); ctx.plugin(SubUsageService, {}); ctx.logger.info("dsh-subusage: usage service ready"); }
+function apply(ctx) { registerRemotes(ctx); ctx.plugin(SubUsageService, {}); registerQuotaTool(ctx); ctx.logger.info("dsh-subusage: usage service ready"); }
+/** 工具结果的人读文本：一行一个 provider，先给窗口再给余额，异常与未配置直说。 */
+function formatQuotaText(value) {
+ const providers = Array.isArray(value?.providers) ? value.providers : [];
+ if (!providers.length) return "没有可读的提供商额度。";
+ return providers.map(entry => {
+  const head = `${entry.label || entry.providerId} [${entry.state}]`;
+  if (entry.state === "no-key" || entry.state === "no-cookie") return `${head}：未配置凭据`;
+  if (entry.state === "disabled") return `${head}：检测已关闭`;
+  if (entry.state !== "ok") return `${head}：${entry.error || "读取失败"}`;
+  const parts = [];
+  for (const window of entry.windows || []) {
+   parts.push(`${window.kind} ${window.status === "rate-limited" ? "已达限额" : `${Math.round(Math.max(0, 100 - window.percent) * 10) / 10}% 剩余`}${window.resetsAt ? `（重置 ${window.resetsAt}）` : ""}`);
+  }
+  for (const extra of entry.extras || []) parts.push(`${extra.kind}: ${extra.value}`);
+  if (entry.freshness === "stale") parts.push("缓存数据");
+  return `${head}：${parts.length ? parts.join("；") : "暂无额度数据"}`;
+ }).join("\n");
+}
+/**
+ * 注册 subusage_quota 工具：模型可以直接问「额度还剩多少」，不必自己逐个厂商请求。
+ * 工具只读：不写设置、不碰凭据，数据来自与设置页同一份缓存（TTL 60 秒）。
+ */
+function registerQuotaTool(ctx) {
+ ctx.inject(["tools"], toolCtx => {
+  toolCtx.tools.register(defineTool({
+   name: "subusage_quota",
+   description: "Read the remaining quota and balance of the AI subscriptions configured on this machine (DeepSeek, Z.ai, Kimi, MiMo, OpenCode Go, Command Code, Codex, SuperGrok, MiniMax, Volcengine Ark, OpenRouter, SiliconFlow, ...). Read-only: it never returns credentials and never changes settings. Results may come from a cache up to 60 seconds old; pass refresh=true only when the user explicitly needs up-to-date numbers.",
+   parameters: {
+    providers: { type: "array", items: { type: "string" }, description: "Optional provider ids to limit the query, e.g. [\"deepseek\", \"openrouter\"]. Omit to read every provider." },
+    refresh: { type: "boolean", description: "Force a fresh fetch instead of the up-to-60s cache. Use only when the user asks for the latest numbers." }
+   },
+   output: {
+    schema: {
+     type: "object",
+     additionalProperties: false,
+     properties: {
+      updatedAt: { type: "string", required: true, description: "ISO timestamp of this reading." },
+      providers: {
+       type: "array",
+       required: true,
+       description: "One entry per provider.",
+       items: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+         providerId: { type: "string", required: true },
+         label: { type: "string", required: true },
+         state: { type: "string", required: true, description: "ok | no-key | no-cookie | error | disabled" },
+         windows: { type: "array", required: true, description: "Quota windows; percent is the USED percentage (0-100)." },
+         extras: { type: "array", required: true, description: "Balances and plan names (kind/value)." },
+         coverage: { type: "string", description: "complete | partial" },
+         freshness: { type: "string", description: "fresh | stale" },
+         lastSuccessAt: { type: "string" },
+         error: { type: "string", description: "Failure reason when state is error." }
+        }
+       }
+      }
+     }
+    },
+    render: (_args, value) => [{ type: "text", text: formatQuotaText(value) }]
+   },
+   execute: async (args, exec) => {
+    exec?.signal?.throwIfAborted?.();
+    const service = toolCtx.get("subUsage");
+    if (!service || typeof service.quota !== "function") throw new Error("dsh-subusage 服务尚未就绪");
+    return await service.quota({ providerIds: args?.providers, force: args?.refresh === true });
+   }
+  }));
+ });
+}
 export { apply, inject, name };
 export default { name, inject, apply };