dsh-subusage 0.10.4 → 0.10.5

package/README.md

@@ -6,7 +6,7 @@
 
 > **English.** dsh-subusage shows subscription quota and balance for the AI providers you already use, as a pill next to the model selector in DeepSeek Harness. Provider switches and credentials live in one settings page, and other plugins or agents can read the same snapshot through a read-only quota API.
 
-[![npm version](https://img.shields.io/badge/npm-0.10.4-blue)](https://www.npmjs.com/package/dsh-subusage)
+[![npm version](https://img.shields.io/badge/npm-0.10.5-blue)](https://www.npmjs.com/package/dsh-subusage)
 [![license](https://img.shields.io/badge/license-MIT-green)](#license--security--许可与安全)
 [![DSH](https://img.shields.io/badge/DSH-%3E%3D0.2.0--rc.1%20%3C0.3.0--0-informational)](#compatibility--兼容性)
 
@@ -246,9 +246,14 @@ ark-coding-plan-byteplus ARK_CODING_PLAN_BYTEPLUS_API_KEY
 
 | 参数 | 类型 | 说明 |
 |---|---|---|
-| `providers` | `string[]`（可选） | 限定 provider id，例如 `["deepseek", "openrouter"]`；省略表示读取全部 |
+| `providers` | `string[]`（可选） | 限定范围。可传本插件的 provider id（`deepseek`、`zai-coding-cn`、`kimi-coding`…），也可直接传厂商名（`zai`、`kimi`、`mimo`、`minimax`、`commandcode`、`grok`、`codex`、`ark`、`deepseek`…）；大小写与 `-` `.` `_` 都无关。省略即读取全部 |
 | `refresh` | `boolean`（可选） | `true` 绕过最多 60 秒的缓存，仅在确需最新数字时使用 |
 
+调用约定（**结果永远不为空**）：
+
+- 模型手里的名字往往不是这里的 provider id（它更可能看到 DSH 的路由名，例如 `zai`），所以匹配是**宽松**的：一个名字命中多条路由时**全部返回**（`zai` → 中国版 + 国际版，`ark` → 7 条），每条各自带着真实 `state`（没启用的如实标 `disabled`），由调用方自己判断要看哪条。
+- 一个名字都认不出时，返回里会**先**给一条说明（写明可用写法），**再附上全部 30 条数据**——数据先给出去，判断交给调用方，而不是回一个空结果。
+
 **Host 服务**（Cordis `Service`，key 为 `subUsage`）：
 
 ```js
@@ -256,14 +261,15 @@ const service = ctx.get("subUsage");
 const view = await service.quota({ providerIds: ["deepseek"], force: false });
 // view = {
 //   updatedAt,
-//   providers: [{ providerId, label, state, windows, extras, coverage, freshness, lastSuccessAt, error? }]
+//   providers: [{ providerId, label, state, windows, extras, coverage?, freshness?, lastSuccessAt?, error? }]
 // }
 ```
 
 - `state`：`ok` | `no-key` | `no-cookie` | `error` | `disabled`
 - `windows[].percent` 是**已用**百分比（0–100）；`extras` 放余额与套餐名等补充项
 - 视图**刻意精简**：不返回设置，也不返回 `keySource` / `apiDetected` / 继承变量名等内部状态，第三方消费者拿不到任何与 Key 相关的字段
-- `providerIds` 里的未知 id 会被忽略；单家读取失败只影响它自己的条目，其余照常返回
+- 视图里**不出现值为 `undefined` 的字段**：字段缺席表示「这家没有报告」，而不是「报告了空」——带 `undefined` 的键会被调用方的 schema 校验判成型别错误
+- 单家读取失败只影响它自己的条目，其余照常返回
 - 与设置页共用同一份缓存（TTL 60 秒），频繁调用不会反复请求各家接口
 
 ## Troubleshooting / 常见问题

package/lib/index.js

@@ -85,6 +85,65 @@ const IDS = Object.keys(PROVIDERS);
 // 用一个组级开关控制整组。这些 id 仍各自存在——药丸要靠 provider id 匹配路由，不能合并。
 const ARK_IDS = IDS.filter(id => PROVIDERS[id].credentialKind === "volc");
 const ARK_DEFAULT_ON = ARK_IDS.some(id => PROVIDERS[id].defaultEnabled !== false);
+/**
+ * 调用方（尤其是模型）手里的「提供商名」通常**不是**本插件的 provider id。模型能看到的往往是
+ * DSH 的 llm 路由名或厂商品牌名（`zai`、`grok`、`codex`、`ark`），而这里的 id 是路由 id
+ * （`zai-coding-cn`、`xai-oauth`、`openai-codex`…）。只做精确匹配时，`["zai"]` 会被整批过滤掉，
+ * 工具返回空列表——看上去像「本机什么都没配」，真正的原因却只是名字没对上。
+ * 所以先按别名收敛；一个别名指向多条路由时（`zai` 同时是中国版与国际版）不猜，交给调用方看结果。
+ */
+const PROVIDER_ALIASES = {
+	zai: ["zai-coding-cn", "zai-coding"], "z.ai": ["zai-coding-cn", "zai-coding"], "z-ai": ["zai-coding-cn", "zai-coding"],
+	zhipu: ["zai-coding-cn", "zai-coding"], glm: ["zai-coding-cn", "zai-coding"], "智谱": ["zai-coding-cn", "zai-coding"],
+	kimi: ["kimi-coding"], moonshot: ["kimi-coding"], "月之暗面": ["kimi-coding"],
+	mimo: ["xiaomi-token-plan-cn"], xiaomi: ["xiaomi-token-plan-cn"], "小米": ["xiaomi-token-plan-cn"],
+	minimax: ["minimax-cn", "minimax"], "海螺": ["minimax-cn", "minimax"],
+	commandcode: ["commandcode"], "command-code": ["commandcode"], "command code": ["commandcode"],
+	supergrok: ["xai-oauth"], grok: ["xai-oauth"], xai: ["xai-oauth"],
+	codex: ["openai-codex"], chatgpt: ["openai-codex"], gpt: ["openai-codex"], openai: ["openai-codex"],
+	ark: ARK_IDS, volcengine: ARK_IDS, volc: ARK_IDS, "火山": ARK_IDS, "方舟": ARK_IDS, "火山方舟": ARK_IDS, doubao: ARK_IDS, "豆包": ARK_IDS
+};
+/** 查表用的键：大小写与分隔符都无关，`Z.AI` / `zai_coding_cn` / `zai-coding-cn` 视为同一个词。 */
+function normalizeProviderKey(value) { return String(value ?? "").trim().toLowerCase().replace(/[\s._-]+/g, ""); }
+/**
+ * 归一化索引：id 与别名都进同一张表，因此「精确 id」只是这张表的一个特例。
+ * 一个键可以指向多条路由（`zai` → 中国版 + 国际版，`ark` → 7 条）。
+ */
+const PROVIDER_LOOKUP = (() => {
+	const map = new Map();
+	const add = (key, id) => {
+		const k = normalizeProviderKey(key);
+		if (!k) return;
+		const list = map.get(k) ?? [];
+		if (!list.includes(id)) list.push(id);
+		map.set(k, list);
+	};
+	for (const id of IDS) add(id, id);
+	for (const [alias, ids] of Object.entries(PROVIDER_ALIASES)) for (const id of ids) if (IDS.includes(id)) add(alias, id);
+	return map;
+})();
+/**
+ * 把调用方给的任意写法收敛成 provider id，**纯名字解析、不查任何外部状态**。
+ * 两条硬约定：
+ * 1. 认不出的原串**原样返回**而不是丢掉——调用方要能拿到「这个名字不认识，可用的是……」才能
+ *    自我纠正；静默过滤只会让它以为本机没有额度。
+ * 2. 一个名字命中多条路由时**全部返回**，各自带着真实状态（没启用的会如实标 disabled）。
+ *    例如 `zai` 同时是中国版与国际版、`ark` 是 7 条路由：宁可多给几条数据让调用方自己判断，
+ *    也不替它猜一条，更不能返回空。
+ * @param requested 调用方给的原始名字列表。
+ */
+function resolveProviderIds(requested) {
+	const hit = new Set(), unknown = [];
+	for (const raw of requested) {
+		const name = String(raw ?? "").trim();
+		if (!name) continue;
+		const ids = PROVIDER_LOOKUP.get(normalizeProviderKey(name));
+		if (!ids) { if (!unknown.includes(name)) unknown.push(name); continue; }
+		for (const id of ids) hit.add(id);
+	}
+	// 按登记顺序返回：命中多条时（例如 `ark`）读起来和设置页一致，而不是跟着调用方的输入顺序抖动。
+	return { ids: IDS.filter(id => hit.has(id)), unknown };
+}
 // 火山方舟额度接口的凭据是 IAM Access Key：AK 与 SK 必须同源配对，跨来源拼接只会得到 401。
 // 变量名沿用火山官方 SDK 习惯；与方舟推理 Key（ARK_*_API_KEY）无关。
 const VOLC_ACCESS_KEY_ENV = "VOLC_ACCESSKEY";
@@ -312,7 +371,7 @@ function volcFailure(action, error) {
 }
 async function fetchJson(fetcher, url, headers, lifetimeSignal, init = {}) {
  let response;
- 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.4", ...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.5", ...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) {
@@ -1072,23 +1131,37 @@ export class SubUsageService extends TypertRemoteService {
  // 不需要知道本机配了哪些凭据，更不该拿到任何与 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 asked = Array.isArray(request?.providerIds) ? request.providerIds.filter(id => typeof id === "string" && id.trim()) : [];
+  const { ids: matched, unknown } = asked.length ? resolveProviderIds(asked) : { ids: [...IDS], unknown: [] };
+  // 一个名字都没认出来，说明调用方手里的是**另一套命名**（最常见的就是 DSH 的 llm 路由名）。
+  // 与其只回一句「不认识」，不如把全量数据一并给出：数据先给出去，怎么判断交给调用方。
+  // 混合输入（认出一部分 + 认不出一部分）则只补上认出的那些，不额外放大请求量。
+  const wanted = matched.length || !unknown.length ? matched : [...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: "读取用量失败" }))));
+  // 认不出的名字要回一条**可读**条目而不是静默丢掉：调用方（尤其是模型）无从知道本插件用的是
+  // 路由 id，丢掉之后它只看到空列表，会当成「本机没配任何额度」——真正的原因只是名字没对上。
+  // 放在最前面，免得淹没在几十条数据后面。
+  const unknownEntries = unknown.map(name => ({
+   providerId: name, label: name, state: "error", windows: [], extras: [], coverage: "partial", freshness: "unknown",
+   error: `不认识提供商名「${name}」${wanted.length === IDS.length && matched.length === 0 ? "，下面是全部提供商的额度" : ""}。可以传本插件的 provider id（例如 deepseek、zai-coding-cn、kimi-coding、xiaomi-token-plan-cn），或直接传厂商名（zai、kimi、mimo、minimax、commandcode、grok、codex、ark、deepseek …）。省略 providers 也会查询全部 ${IDS.length} 条。`
+  }));
   return {
    updatedAt: new Date(this.now()).toISOString(),
-   providers: entries.map(entry => ({
+   providers: [...unknownEntries, ...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,
+    // 只输出真正有值的字段：视图里带 `undefined` 的键会被调用方的 schema 校验判成型别错误
+    // （DSH 就会），而且「字段缺席」本来就该表示「这家没报告」，不是「报告了空」。
+    ...(typeof entry.coverage === "string" ? { coverage: entry.coverage } : {}),
+    ...(typeof entry.freshness === "string" ? { freshness: entry.freshness } : {}),
+    ...(typeof entry.lastSuccessAt === "string" ? { lastSuccessAt: entry.lastSuccessAt } : {}),
     ...(entry.error ? { error: entry.error } : {})
-   }))
+   }))]
   };
  }
  async read(request) { return this.refresh(request && request.providerIds ? request : { providerIds: IDS, force: false }); }
@@ -1169,11 +1242,15 @@ 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, {}); registerQuotaTool(ctx); ctx.logger.info("dsh-subusage: usage service ready"); }
-/** 工具结果的人读文本：一行一个 provider，先给窗口再给余额，异常与未配置直说。 */
+/**
+ * 工具结果的人读文本：一行一个 provider，先给窗口再给余额，异常与未配置直说。
+ * 这段文本才是模型真正读到的东西，所以**任何情况下都不返回空**：读不到数据时也要给出
+ * 「怎么才能读到」的下一步，否则模型只会回一句「没有额度」，而原因其实是个可以修的动作项。
+ */
 function formatQuotaText(value) {
  const providers = Array.isArray(value?.providers) ? value.providers : [];
- if (!providers.length) return "没有可读的提供商额度。";
- return providers.map(entry => {
+ if (!providers.length) return `没有读到任何提供商。请不带 providers 参数再调用一次以查询全部 ${IDS.length} 条；若仍为空，在设置页确认「检测」开关与凭据。`;
+ const lines = 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}：检测已关闭`;
@@ -1185,7 +1262,14 @@ function formatQuotaText(value) {
   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");
+ });
+ // 一条额度都没读到时，末尾补一句汇总原因：模型据此才能告诉用户下一步做什么。
+ if (!providers.some(entry => entry.state === "ok")) {
+  const missing = providers.filter(entry => entry.state === "no-key" || entry.state === "no-cookie").length;
+  const off = providers.filter(entry => entry.state === "disabled").length;
+  lines.push(`（这 ${providers.length} 条都没读到额度：未配置凭据 ${missing} 条、检测已关闭 ${off} 条；其余为读取失败。凭据与开关都在 dsh-subusage 设置页，或参考 docs/credentials.md。）`);
+ }
+ return lines.join("\n");
 }
 /**
  * 注册 subusage_quota 工具：模型可以直接问「额度还剩多少」，不必自己逐个厂商请求。
@@ -1195,9 +1279,9 @@ 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.",
+   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, ...). Call it with no arguments to read every provider — that is the usual call. `providers` is an optional filter that accepts both this plugin's provider ids and plain vendor names (\"zai\", \"kimi\", \"mimo\", \"minimax\", \"commandcode\", \"grok\", \"codex\", \"ark\", \"deepseek\"); one name can match several routes and every match is returned with its own state, and a name that matches nothing still returns the full data plus an explanation instead of an empty result. Read-only: it never returns credentials and never changes settings. Each entry has state (ok | no-key | no-cookie | error | disabled), windows (percent is the USED percentage; absent resetsAt means the provider does not report one) and extras (plan name, balance). 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." },
+    providers: { type: "array", items: { type: "string" }, description: "Optional filter. Either a provider id this tool reports back (\"deepseek\", \"zai-coding-cn\", \"kimi-coding\") or a plain vendor name (\"zai\", \"kimi\", \"mimo\", \"minimax\", \"commandcode\", \"grok\", \"codex\", \"ark\"). Case and separators do not matter; an unmatched name is reported with the full data rather than dropped." },
     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: {
@@ -1214,11 +1298,39 @@ function registerQuotaTool(ctx) {
         type: "object",
         additionalProperties: false,
         properties: {
-         providerId: { type: "string", required: true },
+         providerId: { type: "string", required: true, description: "Provider id (the route id), or the unmatched name that was passed in." },
          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)." },
+         windows: {
+          type: "array", required: true, description: "Quota windows; percent is the USED percentage (0-100).",
+          items: {
+           // 这里刻意用 additionalProperties: true：窗口形态随厂商变化（有的给绝对量、有的给额度线标注），
+           // 收紧成白名单只会让新增字段在运行时被判违规，而这里声明的字段仍照旧受型别约束。
+           type: "object", additionalProperties: true,
+           properties: {
+            kind: { type: "string", required: true, description: "Window length: 5h | week | month | day | 7d | rolling | sub | period." },
+            percent: { type: "number", required: true, description: "USED percentage 0-100; remaining = 100 - percent." },
+            status: { type: "string", required: true, description: "ok | rate-limited" },
+            resetsAt: { type: "string", description: "ISO reset time; absent when the provider does not report one." },
+            groupLabel: { type: "string", description: "Credit line, when the provider has more than one (e.g. Volcengine AFP)." },
+            cascade: { type: "boolean", description: "true when this window is only blocked by a wider exhausted window." },
+            detail: {
+             type: "object", additionalProperties: true, description: "Absolute amounts and scope notes, when the provider reports them.",
+             properties: {
+              used: { type: "number" }, limit: { type: "number" }, remaining: { type: "number" }, unit: { type: "string" },
+              limitSource: { type: "string" }, note: { type: "string" }, blockedBy: { type: "array", items: { type: "string" } }
+             }
+            }
+           }
+          }
+         },
+         extras: {
+          type: "array", required: true, description: "Non-window facts: plan name, balance, seat id, ... (kind/value).",
+          items: { type: "object", additionalProperties: false, properties: {
+           kind: { type: "string", required: true, description: "plan | balance | spend | account | monthly-balance | ..." },
+           value: { type: "string", required: true }
+          } }
+         },
          coverage: { type: "string", description: "complete | partial" },
          freshness: { type: "string", description: "fresh | stale" },
          lastSuccessAt: { type: "string" },
@@ -1233,7 +1345,7 @@ function registerQuotaTool(ctx) {
    execute: async (args, exec) => {
     exec?.signal?.throwIfAborted?.();
     const service = toolCtx.get("subUsage");
-    if (!service || typeof service.quota !== "function") throw new Error("dsh-subusage 服务尚未就绪");
+    if (!service || typeof service.quota !== "function") throw new Error("dsh-subusage 服务尚未就绪：Host 端可能还在启动或刚更新完还没重启。请稍后重试；持续失败就重启 DSH。");
     return await service.quota({ providerIds: args?.providers, force: args?.refresh === true });
    }
   }));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-subusage",
   "displayName": "订阅用量显示",
-  "version": "0.10.4",
+  "version": "0.10.5",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"