mslxdff 0.1.155 → 0.1.158

package/src/providers/zcode/const.js

@@ -0,0 +1,54 @@
+// zcode 供应商常量单一源：网关地址、客户端版本、业务码表、Start/Coding Plan 模型目录。
+// 端点契约调研自 zai-org/ZCode 源码（official-coding-plan-gateway.ts / zcodeEndpoint.ts）与 zcode-switch 实测。
+export const ZCODE_ORIGIN = "https://zcode.z.ai";
+export const ZCODE_CLI_INIT_URL = `${ZCODE_ORIGIN}/api/v1/oauth/cli/init`;
+export const zcodeCliPollUrl = (flowId) =>
+  `${ZCODE_ORIGIN}/api/v1/oauth/cli/poll/${encodeURIComponent(String(flowId || ""))}`;
+export const ZCODE_MESSAGES_URL = `${ZCODE_ORIGIN}/api/v1/zcode-plan/anthropic/v1/messages`;
+export const zcodeBalanceUrl = (appVersion) =>
+  `${ZCODE_ORIGIN}/api/v1/zcode-plan/billing/balance?app_version=${encodeURIComponent(String(appVersion || ""))}`;
+
+export const ZCODE_DEFAULT_APP_VERSION = "3.11.2";
+export const ZCODE_RELEASE_CHANNEL = "stable";
+
+export function zcodeAppVersion(env = process.env) {
+  const v = typeof env?.MSLXDFF_ZCODE_APP_VERSION === "string" ? env.MSLXDFF_ZCODE_APP_VERSION.trim() : "";
+  return v || ZCODE_DEFAULT_APP_VERSION;
+}
+
+// 业务码表（zcode-switch quota.rs classify + ZCode 客户端 model-execution.ts 实测）：
+// 401/1006 鉴权失效，1005 额度耗尽（data/plan/ends_at 为下次时间），限流组，3007 安全校验拒绝。
+export const ZCODE_ERROR_KINDS = {
+  401: "auth",
+  1006: "auth",
+  1005: "quota",
+  3002: "rate_limit",
+  3008: "rate_limit",
+  3009: "rate_limit",
+  3010: "rate_limit",
+  3007: "security",
+  2007: "server",
+  3001: "param",
+  3006: "param",
+  3102: "param",
+};
+
+export function zcodeErrorKind(code) {
+  const n = Number(code);
+  return ZCODE_ERROR_KINDS[n] || "unknown";
+}
+
+// 官方 canonical id（quota.rs BUILTIN_*_MODELS）；入站大小写不敏感，出站规范化为该表内的写法。
+export const ZCODE_CODING_PLAN_MODELS = ["GLM-5.3", "GLM-5.3-Flash"];
+export const ZCODE_START_PLAN_MODELS = ["GLM-5.3-Flash", "GLM-5.2", "GLM-5-Turbo"];
+export const ZCODE_MODEL_CATALOG = [...new Set([...ZCODE_CODING_PLAN_MODELS, ...ZCODE_START_PLAN_MODELS])];
+
+export function canonicalZcodeModel(id) {
+  let raw = String(id || "").trim();
+  if (raw.startsWith("zcode/")) raw = raw.slice(6);
+  const low = raw.toLowerCase();
+  for (const m of ZCODE_MODEL_CATALOG) {
+    if (m.toLowerCase() === low) return m;
+  }
+  return raw;
+}

package/src/providers/zcode/headers.js

@@ -0,0 +1,55 @@
+// zcode source headers 构造：与官方客户端同形的 12 项（zcode-source-headers.ts / quota.rs 双源核对）。
+// 官方要求 header value 必须是可见 ASCII，非法值一律剔除（缺失优于脏值）。
+import os from "node:os";
+import { uuid } from "../../compat.js";
+import { ZCODE_ORIGIN, ZCODE_RELEASE_CHANNEL, zcodeAppVersion } from "./const.js";
+
+const ASCII = /^[\x20-\x7e]+$/;
+
+export function normalizeHeaderValue(v) {
+  const t = typeof v === "string" ? v.trim() : "";
+  return t && ASCII.test(t) ? t : undefined;
+}
+
+export function osCategory(platform) {
+  switch (platform) {
+    case "win32":
+      return "windows";
+    case "darwin":
+      return "macos";
+    default:
+      return "linux";
+  }
+}
+
+export function buildZcodeHeaders(opts = {}) {
+  const ver = normalizeHeaderValue(opts.version) ?? zcodeAppVersion();
+  const platform = normalizeHeaderValue(opts.platform) ?? process.platform;
+  const arch = normalizeHeaderValue(opts.arch) ?? process.arch;
+  const intl = (() => { try { return Intl.DateTimeFormat().resolvedOptions() || {}; } catch { return {}; } })();
+  const language = normalizeHeaderValue(opts.lang) ?? normalizeHeaderValue(intl.locale) ?? "unknown";
+  const timeZone = normalizeHeaderValue(opts.tz) ?? normalizeHeaderValue(intl.timeZone) ?? "unknown";
+  // osVersion 显式传空 = 未知（省略该头）；未传则取系统 release。
+  const osVersion = "osVersion" in opts ? normalizeHeaderValue(opts.osVersion) : normalizeHeaderValue(os.release());
+  const deviceMid = normalizeHeaderValue(opts.deviceMid);
+  const requestId = normalizeHeaderValue(opts.requestId) ?? uuid();
+
+  const headers = {
+    "User-Agent": `ZCode/${ver}`,
+    "HTTP-Referer": ZCODE_ORIGIN,
+    "X-Title": "Z Code@electron",
+    "X-ZCode-App-Version": ver,
+    "X-Platform": `${platform}-${arch}`,
+    "X-Release-Channel": ZCODE_RELEASE_CHANNEL,
+    "X-Client-Language": language,
+    "X-Client-Timezone": timeZone,
+    "X-Os-Category": osCategory(platform),
+  };
+  if (osVersion) headers["X-Os-Version"] = osVersion;
+  if (deviceMid) headers["X-Device-Mid"] = deviceMid;
+  headers["x-request-id"] = requestId;
+
+  const token = normalizeHeaderValue(opts.token);
+  if (token) headers["Authorization"] = `Bearer ${token}`;
+  return headers;
+}

package/src/providers/zcode/index.js

@@ -0,0 +1,124 @@
+// zcode 供应商工厂：keyring 多号轮换 + 差异化冷却（auth/限流/服务端=短冷却、1005=长冷却、3007/参数=不冷却）。
+import { compatFetch } from "../../compat.js";
+import { envInt } from "../base.js";
+import { createKeyRing } from "../keyring.js";
+import { loadProviderKeys } from "../../state.js";
+import { createModelsService } from "./models.js";
+import { forwardZcodeChat } from "./chat.js";
+import { fetchZcodeBalance } from "./quota.js";
+import { listZcodeAccountDocs } from "./account-store.js";
+
+// 冷却策略：auth/限流/服务端/网络=短冷却；quota=长冷却（按日重置）；security/param/unknown=不冷却（换号无意义）
+const COOLDOWN_BY_KIND = { auth: "short", rate_limit: "short", server: "short", network: "short", quota: "long" };
+
+function notLoggedInResponse() {
+  return new Response(
+    JSON.stringify({ error: { message: "zcode: 无可用账号 —— 先运行 mslxdff -provider zcode login", type: "auth_error" } }),
+    { status: 401, headers: { "Content-Type": "application/json" } },
+  );
+}
+
+function allCoolingResponse() {
+  return new Response(
+    JSON.stringify({ error: { message: "zcode: 账号暂不可用（冷却中，可能额度用尽或限流），请稍后重试", type: "all_cooling" } }),
+    { status: 429, headers: { "Content-Type": "application/json", "x-mslxdff-zcode-all-cooling": "1" } },
+  );
+}
+
+export function createZcodeProvider({
+  id = "zcode",
+  apiKeys,
+  file,
+  fetchImpl,
+  cooldownMs = envInt("MSLXDFF_ZCODE_COOLDOWN_MS", 30_000),
+  quotaCooldownMs = envInt("MSLXDFF_ZCODE_QUOTA_COOLDOWN_MS", 3_600_000),
+  timeoutMs = Number(process.env.MSLXDFF_ZCODE_TIMEOUT_MS) || 120_000,
+} = {}) {
+  if (!fetchImpl) fetchImpl = compatFetch;
+  const keys = (() => {
+    if (Array.isArray(apiKeys) && apiKeys.length) return [...new Set(apiKeys.map((k) => String(k).trim()).filter(Boolean))];
+    try {
+      return loadProviderKeys(id, file ? { file } : {});
+    } catch {
+      return [];
+    }
+  })();
+  const ring = createKeyRing(keys, { cooldownMs });
+
+  // JWT → deviceMid 映射（设备身份跟账号走，取自 auths/zcode-<uid>.json）
+  let midCache = null;
+  function deviceMidFor(key) {
+    if (midCache === null) {
+      try {
+        midCache = new Map(listZcodeAccountDocs().map((d) => [d.jwt, d.deviceMid]));
+      } catch {
+        midCache = new Map();
+      }
+    }
+    return midCache.get(key) || "";
+  }
+
+  const modelsSvc = createModelsService({
+    id,
+    hasAccount: () => ring.keys.length > 0,
+    // balance capabilities 探测：entitlement 名 → canonical 目录交集（失败/空 → 服务回退全量目录）
+    probe: async () => {
+      const token = ring.keys[0];
+      if (!token) return [];
+      const r = await fetchZcodeBalance({ token, deviceMid: deviceMidFor(token), fetchImpl });
+      return r.ok ? r.modelIds : [];
+    },
+  });
+
+  async function chat(body, opts = {}) {
+    const total = ring.keys.length;
+    if (!total) return notLoggedInResponse();
+    let lastRes = null;
+    for (let hop = 0; hop <= total; hop++) {
+      const key = ring.next();
+      if (!key) break;
+      const res = await forwardZcodeChat({ body, token: key, deviceMid: deviceMidFor(key), fetchImpl, timeoutMs });
+      const kind = res.headers.get("x-mslxdff-zcode-kind");
+      if (!kind) return res;
+      const mode = COOLDOWN_BY_KIND[kind] || "none";
+      if (mode === "long") ring.onError(key, quotaCooldownMs);
+      else if (mode === "short") ring.onError(key, cooldownMs);
+      lastRes = res;
+      if (mode === "none") break; // security/param/unknown：换号无意义，如实透出
+      if (ring.available() === 0) break; // 没有别的可用号
+    }
+    if (lastRes) return lastRes;
+    return allCoolingResponse();
+  }
+
+  async function listModels() {
+    return modelsSvc.listModels();
+  }
+
+  async function preheat() {
+    try {
+      const list = await modelsSvc.listModels();
+      return list.length ? { ok: true } : { ok: false, error: "no catalog" };
+    } catch (e) {
+      return { ok: false, error: String(e?.message || e).slice(0, 120) };
+    }
+  }
+
+  async function close() {}
+
+  async function chatWithKeys(body, keysOverride, opts) {
+    const tmp = createZcodeProvider({ id, apiKeys: keysOverride, file, fetchImpl, cooldownMs, quotaCooldownMs, timeoutMs });
+    return tmp.chat(body, opts);
+  }
+
+  return {
+    id,
+    chat,
+    chatWithKeys,
+    listModels,
+    preheat,
+    close,
+    keyRing: ring,
+    baseUrl: "zcode://native",
+  };
+}

package/src/providers/zcode/models.js

@@ -0,0 +1,65 @@
+// zcode 模型目录：内置 Start/Coding Plan 目录 + allowlist 只增不减补齐 + 目录服务（可选按额度 capabilities 过滤）。
+import { joinModelId } from "../model-id.js";
+import { loadProviderAllowedModels, saveProviderAllowedModels } from "../../state.js";
+import { ZCODE_MODEL_CATALOG } from "./const.js";
+
+const CREATED = 1753600000;
+const CACHE_TTL_MS = 10 * 60 * 1000;
+
+// 登录后开箱可用：内置目录只增不减并入 allowlist（对齐 cline allowlist-sync 先例，避免显式请求 403）。
+export function seedZcodeAllowlist({ ids = ZCODE_MODEL_CATALOG, file } = {}) {
+  const opts = file ? { file } : {};
+  const cur = loadProviderAllowedModels("zcode", opts);
+  const added = ids.filter((m) => !cur.includes(m));
+  if (added.length) saveProviderAllowedModels("zcode", [...cur, ...added], opts);
+  return { allowed: [...cur, ...added], added };
+}
+
+// 对外目录条目（免费池：价格 0.00；id 带 provider 前缀，对齐 joinModelId 契约）。
+export function buildZcodeModelList({ id = "zcode", ids = ZCODE_MODEL_CATALOG } = {}) {
+  return ids.map((raw) => ({
+    id: joinModelId(id, raw),
+    object: "model",
+    created: CREATED,
+    owned_by: "zcode",
+    name: raw,
+    price: "0.00",
+    enable: true,
+    free: true,
+    mark: "*", // 可用标注：免费额度内，登录后可直接调用
+  }));
+}
+
+// 目录服务：静态目录 + 可选 probe()（额度 capabilities 的 live id 列表）过滤；10 分钟缓存。
+// probe 缺失/失败/为空 → 返回全量目录（宁可多列不可误删）。
+export function createModelsService({ id = "zcode", probe, hasAccount = () => true, clock = Date.now } = {}) {
+  let cache = null;
+  let fetchedAt = 0;
+
+  async function listModels() {
+    if (!hasAccount()) return []; // 未登录：空目录（不假装有额度）
+    const now = clock();
+    if (cache && now - fetchedAt < CACHE_TTL_MS) return cache;
+    let ids = ZCODE_MODEL_CATALOG;
+    if (typeof probe === "function") {
+      try {
+        const live = await probe();
+        if (Array.isArray(live) && live.length) {
+          const low = new Set(live.map((m) => String(m).toLowerCase()));
+          const filtered = ZCODE_MODEL_CATALOG.filter((m) => low.has(m.toLowerCase()));
+          ids = filtered.length ? filtered : ZCODE_MODEL_CATALOG;
+        }
+      } catch {}
+    }
+    cache = buildZcodeModelList({ id, ids });
+    fetchedAt = now;
+    return cache;
+  }
+
+  function clearCache() {
+    cache = null;
+    fetchedAt = 0;
+  }
+
+  return { listModels, clearCache, _cache: () => cache };
+}

package/src/providers/zcode/oauth.js

@@ -0,0 +1,120 @@
+// zcode CLI 轮询 OAuth：POST cli/init → 浏览器授权 → GET cli/poll/{flow_id} 拿 zcode JWT。
+// 契约对齐 zcode-switch oauth.rs（init 自带 poll_token 鉴权；服务端返回的 poll_token 优先；3004=流程过期）。
+import { randomBytes } from "node:crypto";
+import { timeoutSignal } from "../../compat.js";
+import { sleep } from "../base.js";
+import { ZCODE_CLI_INIT_URL, zcodeCliPollUrl, zcodeAppVersion } from "./const.js";
+import { buildZcodeHeaders } from "./headers.js";
+
+const INIT_TIMEOUT_MS = 20_000;
+const POLL_TIMEOUT_MS = 15_000;
+const DEFAULT_FLOW_TTL_MS = 300_000;
+
+export class ZcodeOAuthError extends Error {
+  constructor(message, code = 0) {
+    super(message);
+    this.name = "ZcodeOAuthError";
+    this.code = code;
+  }
+}
+
+function parseExpiresAtMs(v) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n * 1000 : 0;
+}
+
+export async function initZcodeFlow({ provider = "zai", fetchImpl, deviceMid, version } = {}) {
+  const pollToken = randomBytes(32).toString("hex");
+  const headers = {
+    ...buildZcodeHeaders({ token: pollToken, deviceMid, version: version || zcodeAppVersion() }),
+    "Content-Type": "application/json",
+  };
+  const res = await fetchImpl(ZCODE_CLI_INIT_URL, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ provider }),
+    signal: timeoutSignal(INIT_TIMEOUT_MS),
+  });
+  const payload = await res.json().catch(() => null);
+  if (!res.ok || payload?.code !== 0) {
+    const msg = String(payload?.msg || "").trim();
+    throw new ZcodeOAuthError(`zcode 登录初始化失败：HTTP ${res.status}${msg ? ` ${msg}` : ""}`, Number(payload?.code) || 0);
+  }
+  const data = payload?.data || {};
+  const flowId = String(data.flow_id || "").trim();
+  const authorizeUrl = String(data.authorize_url || "").trim();
+  if (!flowId || !authorizeUrl) throw new ZcodeOAuthError("zcode 登录初始化响应缺少 flow_id/authorize_url");
+  let parsed;
+  try { parsed = new URL(authorizeUrl); } catch { throw new ZcodeOAuthError("zcode authorize_url 非法"); }
+  if (parsed.protocol !== "https:") throw new ZcodeOAuthError("zcode authorize_url 必须 https");
+  const state = parsed.searchParams.get("state") || "";
+  if (!state) throw new ZcodeOAuthError("zcode authorize_url 缺少 state");
+  return {
+    provider,
+    flowId,
+    authorizeUrl,
+    state,
+    deviceMid: String(deviceMid || ""),
+    pollUrl: zcodeCliPollUrl(flowId),
+    pollToken: String(data.poll_token || "").trim() || pollToken,
+    expiresAtMs: parseExpiresAtMs(data.expires_at) || Date.now() + DEFAULT_FLOW_TTL_MS,
+    pollIntervalMs: Math.max(1000, Number(data.poll_interval_sec) * 1000 || 3000),
+  };
+}
+
+// 单次轮询：pending 继续、ready 返回凭据；3004/failed 抛终态；网络抖动按 pending（不判死）。
+export async function pollZcodeFlowOnce({ pollUrl, pollToken, deviceMid, version, fetchImpl } = {}) {
+  let res;
+  try {
+    res = await fetchImpl(pollUrl, {
+      headers: buildZcodeHeaders({ token: pollToken, deviceMid, version: version || zcodeAppVersion() }),
+      signal: timeoutSignal(POLL_TIMEOUT_MS),
+    });
+  } catch {
+    return { status: "pending" };
+  }
+  if (res.status >= 400) {
+    if (res.status === 408 || res.status === 429) return { status: "pending" };
+    const body = await res.json().catch(() => null);
+    const code = Number(body?.code) || 0;
+    if (code === 3004) throw new ZcodeOAuthError("授权已过期，请重新运行 login", 3004);
+    const msg = String(body?.msg || "").trim();
+    throw new ZcodeOAuthError(`zcode 登录轮询失败：HTTP ${res.status}${msg ? ` ${msg}` : ""}`, code);
+  }
+  const payload = await res.json().catch(() => null);
+  if (!payload || payload.code !== 0) {
+    const msg = String(payload?.msg || "响应异常").trim();
+    throw new ZcodeOAuthError(`zcode 登录轮询失败：${msg}`, Number(payload?.code) || 0);
+  }
+  const data = payload?.data || {};
+  const status = String(data.status || "").trim();
+  if (status === "pending") return { status: "pending" };
+  if (status === "failed") throw new ZcodeOAuthError("授权失败（服务端标记 failed），请重试", 0);
+  if (status === "ready") {
+    const jwt = String(data.token || "").trim();
+    const accessToken = String(data?.zai?.access_token || data?.bigmodel?.access_token || "").trim();
+    const user = {
+      userId: String(data?.user?.user_id || "").trim(),
+      name: String(data?.user?.name || "").trim(),
+      email: String(data?.user?.email || "").trim(),
+    };
+    if (!jwt || !user.userId) throw new ZcodeOAuthError("zcode 登录响应缺少 token/user_id");
+    return { status: "ready", jwt, accessToken, user };
+  }
+  throw new ZcodeOAuthError(`zcode 登录轮询未知状态：${status || "(空)"}`);
+}
+
+export async function waitForZcodeLogin({ flow, fetchImpl, log = () => {}, sleepFn = sleep, now = Date.now } = {}) {
+  if (!flow?.pollUrl) throw new ZcodeOAuthError("缺少轮询信息");
+  while (now() < (flow.expiresAtMs || 0)) {
+    const out = await pollZcodeFlowOnce({
+      pollUrl: flow.pollUrl,
+      pollToken: flow.pollToken,
+      deviceMid: flow.deviceMid,
+      fetchImpl,
+    });
+    if (out.status === "ready") return { ...out, provider: flow.provider || "zai" };
+    await sleepFn(flow.pollIntervalMs || 3000);
+  }
+  throw new ZcodeOAuthError("授权已过期，请重新运行 login", 3004);
+}

package/src/providers/zcode/quota.js

@@ -0,0 +1,176 @@
+// zcode 额度：GET /api/v1/zcode-plan/billing/balance?app_version= 解析（plans/balances 分组）+ CLI 渲染。
+// 契约来自 zcode-switch quota.rs（unwrap data/result → plans[].plan_id/name/status/expire、balances[].*_units）。
+import { timeoutSignal } from "../../compat.js";
+import { ZCODE_MODEL_CATALOG, zcodeAppVersion, zcodeBalanceUrl, zcodeErrorKind } from "./const.js";
+import { buildZcodeHeaders } from "./headers.js";
+
+const num = (v) => {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string" && v.trim()) {
+    const n = Number(v.replace(/,/g, "").trim());
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+};
+const firstStr = (obj, keys) => {
+  for (const k of keys) {
+    const v = obj?.[k];
+    if (typeof v === "string" && v.trim()) return v.trim();
+  }
+  return "";
+};
+const firstNum = (obj, keys) => {
+  for (const k of keys) {
+    const n = num(obj?.[k]);
+    if (n != null) return n;
+  }
+  return null;
+};
+const fmtNum = (n) => {
+  if (n == null) return "—";
+  return String(Math.round(Number(n))).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+};
+
+// 上游可能把业务体包在 data/result 里（最多下钻 4 层，与 zcode-switch unwrap 同语义）
+export function unwrapZcodeData(payload) {
+  let cur = payload;
+  for (let i = 0; i < 4; i++) {
+    if (!cur || typeof cur !== "object" || Array.isArray(cur)) break;
+    if (cur.data && typeof cur.data === "object" && !Array.isArray(cur.data)) { cur = cur.data; continue; }
+    if (cur.result && typeof cur.result === "object" && !Array.isArray(cur.result)) { cur = cur.result; continue; }
+    break;
+  }
+  return cur || {};
+}
+
+export function parseZcodeBalance(payload) {
+  const data = unwrapZcodeData(payload);
+  const rawPlans = Array.isArray(data.plans) ? data.plans : [];
+  const rawBalances = Array.isArray(data.balances) ? data.balances : [];
+
+  const plans = rawPlans.map((p) => ({
+    id: firstStr(p, ["plan_id", "planId", "id"]),
+    name: firstStr(p, ["name", "show_name", "plan_name"]) || firstStr(p, ["plan_id", "planId"]) || "套餐",
+    status: firstStr(p, ["status"]) || "UNKNOWN",
+    expire: firstStr(p, ["ends_at", "end_at", "expires_at", "expire", "period_end"]),
+    items: [],
+  }));
+  const loose = [];
+
+  for (const b of rawBalances) {
+    const item = {
+      name: firstStr(b, ["show_name", "name", "entitlement_id", "plan_id"]) || "Unknown",
+      total: firstNum(b, ["total_units", "total"]),
+      used: firstNum(b, ["used_units", "used"]),
+      remaining: firstNum(b, ["remaining_units", "available_units", "remaining"]),
+      unit: firstStr(b, ["unit_type", "meter", "unit"]) || "quota",
+      periodEnd: firstStr(b, ["period_end", "expires_at", "end_at"]),
+      planId: firstStr(b, ["plan_id", "planId", "entitlement_id"]),
+    };
+    item.percentUsed = item.total > 0 && item.used != null ? Math.min(100, Math.round((item.used / item.total) * 1000) / 10) : null;
+    const slot = item.planId ? plans.find((s) => s.id === item.planId) : plans.length === 1 ? plans[0] : null;
+    if (slot) slot.items.push(item);
+    else loose.push(item);
+  }
+  for (const s of plans) if (!s.expire) s.expire = s.items.map((i) => i.periodEnd).find(Boolean) || "";
+
+  const all = [...plans.flatMap((s) => s.items), ...loose];
+  const sum = (k) => (all.some((i) => i[k] != null) ? all.reduce((a, i) => a + (i[k] || 0), 0) : null);
+  return {
+    isEmpty: plans.length === 0 && loose.length === 0,
+    plans,
+    loose,
+    totals: { total: sum("total"), used: sum("used"), remaining: sum("remaining") },
+    itemCount: all.length,
+  };
+}
+
+// entitlement 名 → 内置目录里的 canonical id（同名词取最长命中的目录项，避免 GLM-5.3-Flash 误配 GLM-5.3）
+export function balanceModelIds(parsed) {
+  const names = [
+    ...(parsed?.plans || []).flatMap((s) => s.items.map((i) => i.name)),
+    ...(parsed?.loose || []).map((i) => i.name),
+  ]
+    .filter(Boolean)
+    .map((n) => String(n).toLowerCase().replace(/\s+/g, "-"));
+  const out = [];
+  for (const n of names) {
+    const hit = ZCODE_MODEL_CATALOG.filter((m) => n.includes(m.toLowerCase())).sort((a, b) => b.length - a.length)[0];
+    if (hit && !out.includes(hit)) out.push(hit);
+  }
+  return out;
+}
+
+export async function fetchZcodeBalance({ token, deviceMid = "", fetchImpl, version = zcodeAppVersion(), timeoutMs = 15_000 } = {}) {
+  const url = zcodeBalanceUrl(version);
+  const headers = { ...buildZcodeHeaders({ token, deviceMid, version }), Accept: "application/json" };
+  let res;
+  try {
+    res = await fetchImpl(url, { method: "GET", headers, signal: timeoutSignal(timeoutMs) });
+  } catch (e) {
+    return { ok: false, kind: "network", status: 0, code: 0, message: String(e?.message || e).slice(0, 160), modelIds: [] };
+  }
+  const payload = await res.json().catch(() => null);
+  const code = Number(payload?.code) || 0;
+  const bizOk = Boolean(payload) && payload.success !== false && (!code || code === 200);
+  if (!res.ok || !bizOk) {
+    let kind = zcodeErrorKind(code);
+    if (kind === "unknown") {
+      if (res.status === 401) kind = "auth";
+      else if (res.status === 429) kind = "rate_limit";
+      else if (res.status >= 500) kind = "server";
+      else if (!bizOk) kind = "server";
+    }
+    const message = String(payload?.msg || payload?.message || `HTTP ${res.status}`).trim();
+    return { ok: false, kind, status: res.status, code, message, modelIds: [] };
+  }
+  const parsed = parseZcodeBalance(payload);
+  return { ok: true, status: res.status, code, parsed, modelIds: balanceModelIds(parsed) };
+}
+
+export function formatZcodeQuota(result = {}, { account = "" } = {}) {
+  const head = `zcode quota${account ? ` · ${account}` : ""}`;
+  if (!result.ok) {
+    const kind = result.kind || "unknown";
+    if (kind === "auth") {
+      return [head, `登录已失效（code ${result.code || 1006}）。请重新登录：`, "  mslxdff -provider zcode login"].join("\n");
+    }
+    const detail = `${kind}${result.code ? ` code ${result.code}` : ""}${result.status ? ` HTTP ${result.status}` : ""}`;
+    return [
+      head,
+      `查询失败（${detail}）${result.message ? `：${result.message}` : ""}`,
+      "稍后重试；若反复失败：mslxdff -provider zcode login 重新登录",
+    ].join("\n");
+  }
+  const parsed = result.parsed || {};
+  if (parsed.isEmpty) {
+    return [
+      head,
+      "当前账号无套餐（未领取体验额度）。",
+      "可在官方 ZCode 客户端 / zcode-switch 领取 Start Plan 体验额度后重试：",
+      "  mslxdff -provider zcode quota",
+    ].join("\n");
+  }
+  const lines = [head];
+  if (parsed.totals?.remaining != null) {
+    lines.push(`总余量 ${fmtNum(parsed.totals.remaining)}（已用 ${fmtNum(parsed.totals.used ?? 0)} / 总 ${fmtNum(parsed.totals.total ?? 0)}）`);
+  }
+  for (const p of parsed.plans || []) {
+    lines.push("");
+    lines.push(`[${p.name || p.id || "套餐"}] ${p.status}${p.expire ? `  有效期至 ${p.expire}` : ""}`);
+    const w = Math.max(6, ...p.items.map((i) => String(i.name).length));
+    for (const i of p.items) {
+      const used = i.percentUsed != null ? `  已用 ${i.percentUsed}%` : "";
+      lines.push(`  * ${String(i.name).padEnd(w)}  余 ${fmtNum(i.remaining ?? 0)} ${i.unit} / 总 ${fmtNum(i.total ?? 0)}${used}`);
+    }
+    if (!p.items.length) lines.push("  （该套餐无 entitlement 明细）");
+  }
+  if ((parsed.loose || []).length) {
+    lines.push("");
+    lines.push("[未归属套餐的额度]");
+    for (const i of parsed.loose) lines.push(`  * ${i.name}  余 ${fmtNum(i.remaining ?? 0)} ${i.unit} / 总 ${fmtNum(i.total ?? 0)}`);
+  }
+  lines.push("");
+  lines.push("提示: mslxdff -provider zcode models 查看可用模型 · 额度按官方计费周期重置");
+  return lines.join("\n");
+}