dsh-subusage

DeepSeek Harness 订阅用量显示插件。 在模型选择器旁显示当前模型商的订阅余量药丸，点开可看各周期用量、重置时间与套餐；设置页集中管理 30 条提供商 / 区域路由的检测开关与凭据；并以只读额度 API 供其他插件与 Agent 查询。

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.

Overview / 功能

药丸示例：✓ 余 87%、⚠ 7d 余 12%、✕ 7d 已达限额。多窗口取最差一窗，点击查看完整明细；成功结果按提供商缓存 60 秒，手动刷新可跳过普通 TTL（仍遵守上游限流退避与 Retry-After）。

本插件不注册模型路由，药丸按 provider id 匹配；因此使用哪个插件提供该模型路由不影响匹配，id 对不上时才不显示。

支持的数据 / Supported data

共 30 条 provider id：新安装默认开启 10 条、默认关闭 20 条（数字与清单取自 lib/index.js 顶部的 PROVIDERS，展示顺序与短名取自 lib/client.js 顶部的 PROVIDER_META / PROVIDER_ORDER）。

• 各家的窗口语义、明细字段与单位换算（例如 ZenMux / Ollama 的 0–1 小数、Novita 的 1/10000 USD、Kimi 随套餐变化的窗口集合）见 提供商清单与额度语义。
• 评估过但不接入的厂商与理由见 提供商覆盖与取舍（含已由用户决策跳过的 Anthropic）。

非公开控制台接口可能变更；缺失或非法百分比不会被当作零用量；「读取成功」只表示接口读取健康度，不保证仍有额度。

Support status / 实测覆盖

已实测验证

下面这些在真实账号上跑通过（本仓库开发机 + 各家的官方 CLI / 插件）：

未验证

其余提供商只经过桩测试——响应形态取自公开文档、第三方实现或抓包，没有在真实账号上跑通过：

Z.ai（中国与国际）、OpenCode Go、MiniMax（中国与国际）、Synthetic、NanoGPT、SiliconFlow、DeepSeek、OpenRouter、Novita、Hyperbolic、DeepInfra、Chutes、Ollama Cloud、Vercel AI Gateway、ZenMux、LiteLLM，以及火山方舟的团队版席位与 BytePlus 站点。

它们可能可用，也可能因为接口变更、字段差异或权限要求而失败。本插件只保证上面那张表里的。

如果你用了其中之一，不管成功还是失败，都欢迎开 issue——附上提供商名称、错误文案与 DSH 版本即可（不要贴 Key 或 Cookie）。失败和成功一样有用：失败帮我们修适配，成功帮我们把这一行挪进上表。

主要风险

• 额度数字仅供参考，不要当计费依据。 各家的额度接口都是未公开或半公开的，字段语义可能随时变化；本插件不做任何换算，读到什么显示什么。
• 未验证的提供商会随接口变化而失效（见上一节）。失效时在设置页关掉那一家的检测即可，其余不受影响；欢迎开 issue 帮我们补上。
• 凭据以明文落盘：本插件的配置不是加密凭据库；Windows 上真正的访问边界取决于目录 ACL，chmod 不能替代它。
• 火山方舟是账号级读取：一组 IAM AK/SK 能查到该账号名下所有套餐（Agent Plan、Coding Plan、团队席位）。把装了本插件的机器或配置文件交给别人时请注意这一点。
• 浏览器自动化：MiMo 的自动登录会启动一个隔离的 Chromium 会话——不点「登录并自动导入」就不会触发。
• 收录不等于安全审计：无论 DSH STORE 还是 awesome-dsh-plugin，收录只表示满足它们各自的清单规则，都不是对代码的安全审查。

Compatibility / 兼容性

范围里那个 || 分支不是冗余。 node-semver 只有在范围中某个比较符与该版本的 major.minor.patch 元组完全一致、且自身带预发布标签时，才放行预发布版本。所以 >=0.2.0-rc.1 <0.3.0-0 这种看起来覆盖 0.2.x 的写法会静默排除 0.2.1-alpha.1——而它正是当前活跃版本。必须为每个 minor 元组各写一个带预发布标签的分支。

dsh.compatibility.dshReleases 逐版本声明已知状态：只有实际验证过的标 compatible，其余一律 unknown——没有证据不猜。声明范围不代表范围内所有版本都已实机验证；实际验证范围（在线接口、真实账号、浏览器像素验收等）见 开发与验证说明。这是树外 Host / Client bundle，通过 cordis.patch.yml 插入，不修改 DSH 核心、安装树或 ASAR。

Install / 安装

# npm 包名（推荐：预构建，免构建授权）
dsh plugin --profile <profile> add dsh-subusage

# GitHub 固定 Commit（DSH STORE / awesome-dsh-plugin 只接受这种来源）
dsh plugin --profile <profile> add 'git+https://github.com/KouzakiUmi/dsh-subusage.git#<40 位完整 Commit>'

# GitHub Release tarball（资产名不带版本号，所以这个地址不会随发版而失效）
dsh plugin --profile <profile> add https://github.com/KouzakiUmi/dsh-subusage/releases/latest/download/dsh-subusage.tgz

# 本地开发目录（link 工作副本）
dsh plugin --profile <profile> add D:\src\dsh-subusage

升级与卸载：

dsh plugin --profile <profile> update dsh-subusage
dsh plugin --profile <profile> update dsh-subusage@https://github.com/KouzakiUmi/dsh-subusage/releases/latest/download/dsh-subusage.tgz
dsh plugin --profile <profile> remove dsh-subusage

• <profile> 换成目标 profile；Desktop 请使用随包 DSH CLI 或应用内插件管理页，PATH 上的 npm 全局 dsh 不一定是它。参数与 profile 名以目标部署的 dsh plugin --help 为准；桌面插件页同样接受包名、GitHub 地址或本地目录。
• 不要用浮动分支（#main）安装：市场与商店只认固定到完整 40 位 Commit 的来源，浮动分支无法核实你装到的到底是哪份代码。
• 安装只把包放进 profile，不等于已启用；按部署方式重载或重启，让 Host 与 Client 一起生效（只刷新页面不保证 Host 升级）。
• 只取压缩包：npm pack dsh-subusage；核对发布结果：npm view dsh-subusage version dist-tags。
• 本包没有 preinstall / install / postinstall / prepare 脚本，安装期不执行任何代码；也不需要 pnpm 的 allowBuilds 授权。

Quick start / 快速开始

1. 安装并启用 bundle，按部署方式重载或重启。
2. 打开 设置 → 订阅用量 → 提供商管理，开启需要的提供商（默认关闭的 19 条需手动开启）。
3. 为它配置凭据：在卡片里展开「连接与凭据」填 Key / AK-SK，或把 Key 放进凭据服务 / 启动环境；MiMo 用「登录并自动导入」。不知道去哪拿、或填了不生效 → 见凭据获取指引。
4. 回到会话，选中该提供商的模型：输入区左侧出现余量药丸（绿色成功 / 红色失败），点开看窗口明细。
5. 排障顺序：点「立即刷新」→ 看设置页顶部 X/Y 家数据获取成功（可点击，跳到第一家没读成功的）。

可复现的最小示例（DeepSeek，余额型，默认开启，与推理同一把 Key）：

# 任选一种凭据来源
$env:DEEPSEEK_API_KEY = "<你的 DeepSeek API Key>"   # 启动环境；改完需按部署方式重启
# 或在 设置 → 订阅用量 → DeepSeek →「连接与凭据」里手动填写

重启后在会话中选中 DeepSeek 模型，药丸显示账户余额；也可以直接让 Agent 调用 subusage_quota(providers: ["deepseek"]) 验证（无需界面）。

前置：这几家需要提供方插件

绝大多数提供商只要一把 API Key 就能用。但下面几家要先装提供方插件——它们负责注册模型路由、完成登录并持有凭据；本插件只读取同一份凭据，不代为登录、也不保存它们。

Codex 默认关闭：它的提供方插件本身就带一个用量药丸，两个并排只是重复信息。想要本插件这一份（比如想把 Codex 和别家放在一起看）可以在提供商管理里手动开启。

这几家的凭据不在本插件的设置页里：请用上表的登录方式。缺登录时本插件的卡片会直接给出对应的登录命令。

Configuration / 配置

• 设置页路径：设置 → 订阅用量 → 提供商管理。「没有检测到API的默认隐藏」默认开启；首次没有可见条目时管理区自动展开。关闭的提供商仍可配置凭据，只是不会发起用量请求。
• 凭据从哪来：每一类凭据的官网入口、环境变量名与界面填入位置都写在凭据获取指引——包括火山的 IAM AK/SK（子用户还要挂 ArkReadOnlyAccess 且不限制到项目）、MiMo 的平台会话 Cookie、以及各家 API Key 的对照表。注意推理 Key 与额度凭据不通用。
• 默认开关策略：新安装默认开启 10 条、默认关闭 20 条（Codex 默认关闭——它的提供方插件自带用量药丸）；开关即时保存，升级保留已保存的开关，不重算默认值。默认隐藏只影响显示，不会自动开启被关闭的提供商。
• 火山方舟是一组：5 条路由共用同一组 IAM AK/SK，所以设置页只呈现一张卡片、一个开关（组内最后选的那条作为代表），卡片里写明本机实际装了哪几条。这些 provider id 并没有合并——药丸仍按 id 匹配路由。旧插件 @volcengine/ark-plan-api 的两个国内路由（ark-coding-plan-cn / ark-agent-plan-cn）已移除：它们与 arkcli 的路由查同一份订阅，并列显示只会让人以为买了两个套餐；装了旧插件的用户，药丸仍按那两个 id 显示同一份数据（入口归并到 arkcli 路由）。
• 火山方舟不按路由收起：它的额度走账号级管控面，一组 AK/SK 就能查到名下所有套餐（GetCodingPlanUsage 与 GetAFPUsage 是同一套协议、同一组凭据）。推理路由装没装只影响模型能不能用，不影响额度能不能查——所以只持有 Coding Plan、却没在 DSH 里配 coding-plan 路由时，那条额度照样会显示（前提是配了 AK/SK）。
• 凭据来源优先级（inherit 模式）：凭据服务 → 启动环境 → 旧手动配置兜底；切到自定义（manual）模式时只使用保存的手动 Key。界面会区分这三种来源。
• 不接受本地 Key 的提供商：commandcode（凭据链属提供方插件）、xai-oauth、openai-codex（只读各自 CLI 的登录文件），以及 MiMo（Cookie 会话）。
• 保存与验证分离：凭据先确认持久化，再独立做在线验证；检测关闭的提供商只保存凭据、不发起验证，验证失败不代表保存失败。
• 出错时在卡片上修：MiMo 未登录 / Cookie 被拒 → 「登录并自动导入」；Cookie 临近到期或已过期 → 「重新登录」；其他家缺凭据 → 「配置凭据」（展开该厂商编辑器并滚动过去）。正常状态不显示行动条。

deepseek                 DEEPSEEK_API_KEY
zai-coding-cn            ZAI_CODING_CN_API_KEY
zai-coding               ZAI_CODING_API_KEY
kimi-coding              KIMI_CODING_API_KEY
xiaomi-token-plan-cn     XIAOMI_TOKEN_PLAN_CN_API_KEY   （界面走官方平台 Cookie）
opencode-go              OPENCODE_API_KEY
commandcode              COMMANDCODE_API_KEY
xai-oauth                —                              （OAuth 登录文件）
openai-codex             —                              （OAuth 登录文件）
minimax                  MINIMAX_API_KEY
minimax-cn               MINIMAX_CN_API_KEY
synthetic                SYNTHETIC_API_KEY
nanogpt                  NANOGPT_API_KEY
siliconflow              SILICONFLOW_API_KEY
openrouter               OPENROUTER_API_KEY
novita                   NOVITA_API_KEY
hyperbolic               HYPERBOLIC_API_KEY
deepinfra                DEEPINFRA_API_KEY
chutes                   CHUTES_API_KEY
ollama-cloud             OLLAMA_API_KEY
vercel-ai-gateway        AI_GATEWAY_API_KEY
zenmux                   ZENMUX_MANAGEMENT_API_KEY
litellm                  LITELLM_API_KEY                （另需自填 proxy 地址）
arkcli-agent-plan        ARKCLI_AGENT_PLAN_API_KEY      （额度用 VOLC_ACCESSKEY / VOLC_SECRETKEY）
arkcli-coding-plan       ARKCLI_CODING_PLAN_API_KEY
arkcli-agent-plan-team   ARKCLI_AGENT_PLAN_TEAM_API_KEY
arkcli-coding-plan-team  ARKCLI_CODING_PLAN_TEAM_API_KEY
ark-coding-plan-byteplus ARK_CODING_PLAN_BYTEPLUS_API_KEY

Permissions & data / 权限与数据

读取 / 写入的文件

网络访问：只连上面清单里各家自己的额度 / 余额端点，以及 platform.xiaomimimo.com（MiMo 用量与登录）、api.commandcode.ai、cli-chat-proxy.grok.com、chatgpt.com/backend-api、火山管控面 open.volcengineapi.com，外加你自己填写的 LiteLLM proxy 地址。完整域名表见 网络端点。MiMo 自动登录会另外打开官方平台页面，由你在该页面自行输入密码与验证码。本插件没有自己的服务器，不做遥测，也不把你的数据发给任何第三方。

命令、进程与安装期行为

密钥如何处理

• Key 与 Cookie 不回传页面：读取接口不返回凭据本身，界面不回填已保存的秘密（Cookie 只在需要替换时输入）；公开设置只有 hasKeys / hasCookie 这类布尔状态与来源标记。
• 日志与产物不落盘：真实 Key / Cookie 不会写进日志、测试、截图或读取结果；MiMo 响应在返回前做字段级 Cookie 脱敏。
• MiMo 自动登录使用独立临时 Chrome 会话：不读取日常 Chrome 配置，不读取密码 / 验证码字段，Cookie 不通过 RPC 返回页面；五分钟未完成自动超时。
• 计时元数据（xiaomi.loginAt / xiaomi.expiresAt）只是本地时间戳，不是秘密，也不参与凭据有效性判断。
• 这不是加密凭据库：本版仍兼容本机 JSON 配置存储，凭据以明文落盘；加密凭据存储通道尚未实施。Windows 上的实际访问权限取决于目录 ACL，chmod 不能替代 ACL 或加密库。请不要上传、分享该配置文件，也不要把它写进日志或工单。

额度查询 API

Agent 工具 subusage_quota（模型可直接调用，只读：不写设置、不碰凭据）

调用约定（结果永远不为空）：

• 模型手里的名字往往不是这里的 provider id（它更可能看到 DSH 的路由名，例如 zai），所以匹配是宽松的：一个名字命中多条路由时全部返回（zai → 中国版 + 国际版，ark → 5 条），每条各自带着真实 state（没启用的如实标 disabled），由调用方自己判断要看哪条。
• 一个名字都认不出时，返回里会先给一条说明（写明可用写法），再附上全部 30 条数据——数据先给出去，判断交给调用方，而不是回一个空结果。

Host 服务（Cordis Service，key 为 subUsage）：

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? }]
// }

• state：ok | no-key | no-cookie | error | disabled
• windows[].percent 是已用百分比（0–100）；extras 放余额与套餐名等补充项
• 视图刻意精简：不返回设置，也不返回 keySource / apiDetected / 继承变量名等内部状态，第三方消费者拿不到任何与 Key 相关的字段
• 视图里不出现值为 undefined 的字段：字段缺席表示「这家没有报告」，而不是「报告了空」——带 undefined 的键会被调用方的 schema 校验判成型别错误
• 单家读取失败只影响它自己的条目，其余照常返回
• 与设置页共用同一份缓存（TTL 60 秒），频繁调用不会反复请求各家接口

Troubleshooting / 常见问题

Development / 开发

没有源码转译步骤，直接维护 lib/*.js。基础检查不需要安装 DSH 或连接账号：

node tests/run-all.mjs
node scripts/check-manifest.mjs
node --check lib/index.js
node --check lib/client.js
node --check lib/mimo-login.js

离线预览（生成 HTML，使用虚构用量与桩 Hook，不连接 DSH、不读取真实凭据）：

foreach ($theme in @('dark', 'light')) {
  foreach ($width in @(530, 500, 499, 360)) {
    node scripts/render-ui-preview.mjs $width xiaomi-token-plan-cn $theme credentials
  }
}
node scripts/render-ui-preview.mjs 530 nanogpt light pill
node scripts/check-browser-runtime.mjs   # 需要工作区可解析 playwright-core 且本机装有 Google Chrome

文档入口：凭据获取指引（每类凭据的官网入口、环境变量与填入位置、报错对照）、开发与验证（RPC 契约、缓存与凭据约定、离线预览与实机验收范围）、提供商清单与额度语义、提供商覆盖与取舍、UX 设计、发布与市场收录、更新记录、审查记录。

打包说明：package.json 的 files 白名单是 lib / locale / cordis.patch.yml / README.md，因此 assets/title.svg、assets/screenshots/ 与 docs/ 不进 npm 包——顶部 title 图与下面的界面预览只在 GitHub 页面显示。改动白名单属于发布决策，需单独处理。

界面预览

以下为 0.7.0 的离线组件测试截图，使用虚构用量数据，不包含真实账号信息，也不是运行中的 DSH 截图。

深色设置页：查看订阅用量、管理凭据与提供商。

浅色用量弹层：查看每日与每周额度、用量明细。

截图声明见根目录 screenshots.json。两张图都是当前版本的离线组件预览（虚构用量、桩网络、无凭据），已随本版本重做，底部水印明确标注「非运行中的 DSH 截图」。真实 DSH Loader、实际账号在线接口与多账户映射仍未验收，截图不代表已通过这些检查。

License & security / 许可与安全

MIT，见 package.json 的 license 字段。本项目与 DeepSeek Harness 及各服务商无官方关联；非公开接口可能随时变更，请以各服务商官方条款为准。

报告安全问题：请不要在公开 issue 里粘贴 Key、Cookie 或完整配置文件。优先使用 GitHub 仓库的 Security → Report a vulnerability 私有渠道；该入口不可用时，也可以在 issue 中只描述问题与影响范围，凭据一律留空。任何复现步骤请先自行脱敏。