dsh-subusage 0.10.10 → 0.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +91 -39
- package/lib/client.js +309 -149
- package/lib/index.js +185 -39
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,16 +1,44 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/KouzakiUmi/dsh-subusage/main/assets/title.png" width="100%" alt="dsh-subusage —— 模型选择器旁的余量药丸，右侧是同一界面的浅色与深色用量弹层（真实渲染截图）">
|
|
2
3
|
|
|
3
|
-
|
|
4
|
+
# 订阅用量显示
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
**选中的模型还剩多少额度，输入框旁边一眼可见。**
|
|
6
7
|
|
|
7
|
-
|
|
8
|
+
dsh-subusage 把你订阅的 30 家模型服务商额度装进 DeepSeek Harness 的输入框旁边——不切控制台、不猜百分比、不等报错。
|
|
8
9
|
|
|
9
|
-
[](#license--security--许可与安全)
|
|
11
|
-
[](https://www.npmjs.com/package/dsh-subusage)
|
|
11
|
+
[](#license--security--许可与安全)
|
|
12
|
+
[](#compatibility--兼容性)
|
|
12
13
|
|
|
13
|
-
|
|
14
|
+
**安装只需一条命令** → [快速开始](#快速开始)
|
|
15
|
+
</div>
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## 为什么需要它
|
|
20
|
+
|
|
21
|
+
| 没有它 | 有了它 |
|
|
22
|
+
|---|---|
|
|
23
|
+
| 额度散落在五六家控制台，查一次余额要开五个标签页 | 药丸常驻输入框旁：选中哪家模型就看哪家，多窗口自动取最差一窗 |
|
|
24
|
+
| Agent 跑到一半撞上 429，才知道额度用尽 | 弹层先给结论再给依据：「即将用尽 · 最紧张：每周 · 剩 5% · 3 天后重置」 |
|
|
25
|
+
| Cookie、OAuth 悄悄过期，报错才发现 | MiMo Cookie 提前 2 小时变黄、30 分钟变橙、过期变红；认证失效直说原因与修法 |
|
|
26
|
+
| 每家插件各管各的凭据，格式五花八门 | 一个设置页集中管理 30 条路由的开关与凭据，缺什么补什么 |
|
|
27
|
+
|
|
28
|
+
## 15 种状态，一眼分清
|
|
29
|
+
|
|
30
|
+
药丸不写字也能传达状态：每个额度窗口一根彩条（绿 / 黄 / 橙 / 红，满格 = 100% 剩余），需要留意时才追加一个词。下面是全部状态的离线预览（虚构用量数据）：
|
|
31
|
+
|
|
32
|
+
<img src="https://raw.githubusercontent.com/KouzakiUmi/dsh-subusage/main/assets/screenshots/pill-states-light.png" width="100%" alt="药丸 15 种状态（浅色，离线预览）">
|
|
33
|
+
|
|
34
|
+
<details>
|
|
35
|
+
<summary>深色主题</summary>
|
|
36
|
+
|
|
37
|
+
<img src="https://raw.githubusercontent.com/KouzakiUmi/dsh-subusage/main/assets/screenshots/pill-states-dark.png" width="100%" alt="药丸 15 种状态（深色，离线预览）">
|
|
38
|
+
|
|
39
|
+
</details>
|
|
40
|
+
|
|
41
|
+
## 三块能力，一个设置页
|
|
14
42
|
|
|
15
43
|
| 能力 | 解决什么问题 | 入口 |
|
|
16
44
|
|---|---|---|
|
|
@@ -18,10 +46,45 @@
|
|
|
18
46
|
| 设置页 | 开关与凭据集中管理；缺凭据、Cookie 过期时把修复入口直接送到卡片上 | 设置 → 订阅用量 → 提供商管理 |
|
|
19
47
|
| 只读额度 API | 其他插件与 Agent 复用同一份额度数据，不必各自对接各家接口 | Agent 工具 `subusage_quota`、Host 服务 `subUsage.quota()` |
|
|
20
48
|
|
|
21
|
-
|
|
49
|
+
药丸只画图形：每个额度窗口一根彩色余量条（绿 / 黄 / 橙 / 红，满 = 100% 剩余），正常时不写字；需要留意时追加一个词，如 `周 偏少`、`5时 已用尽`、`需配置`、`拉取失败`。成功结果按提供商缓存 **60 秒**，手动刷新可跳过普通 TTL（仍遵守上游限流退避与 `Retry-After`）。
|
|
22
50
|
|
|
23
51
|
本插件**不注册模型路由**，药丸按 provider id 匹配；因此使用哪个插件提供该模型路由不影响匹配，id 对不上时才不显示。
|
|
24
52
|
|
|
53
|
+
## 30 家提供商，默认开箱即用 10 家
|
|
54
|
+
|
|
55
|
+
DeepSeek、火山方舟（Agent / Coding Plan 个人版与企业版席位）、Z.ai（中国与国际）、Kimi、小米 MiMo、OpenCode Go、Command Code、SuperGrok、Codex（ChatGPT 订阅）、MiniMax（中国与国际）、Synthetic、NanoGPT、SiliconFlow、OpenRouter、Novita、Hyperbolic、DeepInfra、Chutes、Ollama Cloud、Vercel AI Gateway、ZenMux、LiteLLM——订阅窗口、余额、周期额度池都支持。**新安装默认开启 10 条**，其余在设置页一键开启；完整清单、额度类型与鉴权方式见[下方技术文档](#支持的数据--supported-data)。
|
|
56
|
+
|
|
57
|
+
## 快速开始
|
|
58
|
+
|
|
59
|
+
```console
|
|
60
|
+
dsh plugin --profile <profile> add dsh-subusage
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
1. 安装并启用 bundle，按部署方式重载或重启（只刷新页面不保证 Host 升级）。
|
|
64
|
+
2. 打开 **设置 → 订阅用量 → 提供商管理**，开启需要的提供商并填凭据——每类凭据的官网入口与填入位置见[凭据获取指引](docs/credentials.md)；MiMo 用「登录并自动导入」。
|
|
65
|
+
3. 回到会话，选中该提供商的模型：输入区左侧出现药丸，点开看窗口明细。
|
|
66
|
+
4. 排障：点「立即刷新」→ 看设置页顶部 `X/Y 家数据获取成功`（可点击，直接跳到第一家没读成功的）。
|
|
67
|
+
|
|
68
|
+
可复现的最小示例（DeepSeek，余额型，默认开启，与推理同一把 Key）：
|
|
69
|
+
|
|
70
|
+
```powershell
|
|
71
|
+
# 任选一种凭据来源
|
|
72
|
+
$env:DEEPSEEK_API_KEY = "<你的 DeepSeek API Key>" # 启动环境；改完需按部署方式重启
|
|
73
|
+
# 或在 设置 → 订阅用量 → DeepSeek →「连接与凭据」里手动填写
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
重启后在会话中选中 DeepSeek 模型，药丸显示账户余额；也可以直接让 Agent 调用 `subusage_quota(providers: ["deepseek"])` 验证（无需界面）。
|
|
77
|
+
|
|
78
|
+
## 先说清楚：哪些是实测过的
|
|
79
|
+
|
|
80
|
+
**7 家在真实账号上跑通**：火山方舟 Agent Plan、火山方舟 Coding Plan、Kimi Coding、小米 MiMo、Command Code、SuperGrok、Codex (ChatGPT)。**其余只经过桩测试**——响应形态取自公开文档、第三方实现或抓包，没有在真实账号上跑通，可能随接口变化而失效；失效时在设置页关掉那一家即可，其余不受影响。验证范围与主要风险见[实测覆盖](#support-status--实测覆盖)。额度数字仅供参考，不要当计费依据。
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
# 技术文档
|
|
85
|
+
|
|
86
|
+
> 安装、配置、排障的完整参考。快速上手看上面就够了。
|
|
87
|
+
|
|
25
88
|
## 支持的数据 / Supported data
|
|
26
89
|
|
|
27
90
|
共 **30 条 provider id**：新安装**默认开启 10 条、默认关闭 20 条**（数字与清单取自 [`lib/index.js`](lib/index.js) 顶部的 `PROVIDERS`，展示顺序与短名取自 [`lib/client.js`](lib/client.js) 顶部的 `PROVIDER_META` / `PROVIDER_ORDER`）。
|
|
@@ -103,12 +166,12 @@
|
|
|
103
166
|
|---|---|---|
|
|
104
167
|
| 核心 peer 范围 | `@deepseek-ai/dsh` 及各核心包均为 `>=0.2.0-rc.1 <0.2.1-0 \|\| >=0.2.1-0 <0.3.0-0` | [`package.json`](package.json) 的 `peerDependencies` |
|
|
105
168
|
| Node.js | `>=22.19.0` | `engines` 与 `dsh.compatibility.node` |
|
|
106
|
-
| 已验证的 Core 版本 | `0.2.1-alpha.1` |
|
|
107
|
-
| 最后验证日期 | `2026-10-
|
|
169
|
+
| 已验证的 Core 版本 | `0.2.0-rc.2`、`0.2.1-alpha.1`、`0.2.1-alpha.2` | 实机运行；逐版本状态与验证方式见 `dsh.compatibility.dshReleases` |
|
|
170
|
+
| 最后验证日期 | `2026-10-11` | [开发与验证说明](docs/development.md) |
|
|
108
171
|
|
|
109
172
|
> **范围里那个 `||` 分支不是冗余。** node-semver 只有在范围中**某个比较符与该版本的 `major.minor.patch` 元组完全一致、且自身带预发布标签**时，才放行预发布版本。所以 `>=0.2.0-rc.1 <0.3.0-0` 这种看起来覆盖 0.2.x 的写法会**静默排除** `0.2.1-alpha.1`——而它正是当前活跃版本。必须为每个 minor 元组各写一个带预发布标签的分支。
|
|
110
173
|
|
|
111
|
-
`dsh.compatibility.dshReleases` 逐版本声明已知状态：**只有实际验证过的标 `compatible`**，其余一律 `unknown
|
|
174
|
+
`dsh.compatibility.dshReleases` 逐版本声明已知状态：**只有实际验证过的标 `compatible`**，其余一律 `unknown`——没有证据不猜。本插件只依赖 Core 的**公开扩展 API 面**（Cordis 服务 `llm`/slots/locale/remote/settings/modelDirectories、4 个核心包的公开导出、client 基座的公开模块），不碰内部组件、不依赖桌面壳版本——这是 0.2.x 各版本实际全兼容的原因；`dshReleases` 记录的是**实测证据**，不是依赖声明。实际验证范围（在线接口、真实账号、浏览器像素验收等）见 [开发与验证说明](docs/development.md)。这是树外 Host / Client bundle，通过 `cordis.patch.yml` 插入，不修改 DSH 核心、安装树或 ASAR。
|
|
112
175
|
|
|
113
176
|
## Install / 安装
|
|
114
177
|
|
|
@@ -146,24 +209,6 @@ dsh plugin --profile <profile> remove dsh-subusage
|
|
|
146
209
|
- 只取压缩包：`npm pack dsh-subusage`；核对发布结果：`npm view dsh-subusage version dist-tags`。
|
|
147
210
|
- 本包**没有** `preinstall` / `install` / `postinstall` / `prepare` 脚本，安装期不执行任何代码；也不需要 pnpm 的 `allowBuilds` 授权。
|
|
148
211
|
|
|
149
|
-
## Quick start / 快速开始
|
|
150
|
-
|
|
151
|
-
1. 安装并启用 bundle，按部署方式重载或重启。
|
|
152
|
-
2. 打开 **设置 → 订阅用量 → 提供商管理**，开启需要的提供商（默认关闭的 19 条需手动开启）。
|
|
153
|
-
3. 为它配置凭据：在卡片里展开「连接与凭据」填 Key / AK-SK，或把 Key 放进凭据服务 / 启动环境；MiMo 用「登录并自动导入」。**不知道去哪拿、或填了不生效** → 见[凭据获取指引](docs/credentials.md)。
|
|
154
|
-
4. 回到会话，选中该提供商的模型：输入区左侧出现余量药丸（绿色成功 / 红色失败），点开看窗口明细。
|
|
155
|
-
5. 排障顺序：点「立即刷新」→ 看设置页顶部 `X/Y 家数据获取成功`（可点击，跳到第一家没读成功的）。
|
|
156
|
-
|
|
157
|
-
可复现的最小示例（DeepSeek，余额型，默认开启，与推理同一把 Key）：
|
|
158
|
-
|
|
159
|
-
```powershell
|
|
160
|
-
# 任选一种凭据来源
|
|
161
|
-
$env:DEEPSEEK_API_KEY = "<你的 DeepSeek API Key>" # 启动环境；改完需按部署方式重启
|
|
162
|
-
# 或在 设置 → 订阅用量 → DeepSeek →「连接与凭据」里手动填写
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
重启后在会话中选中 DeepSeek 模型，药丸显示账户余额；也可以直接让 Agent 调用 `subusage_quota(providers: ["deepseek"])` 验证（无需界面）。
|
|
166
|
-
|
|
167
212
|
## 前置：这几家需要提供方插件
|
|
168
213
|
|
|
169
214
|
绝大多数提供商只要一把 API Key 就能用。但下面几家要先装**提供方插件**——它们负责注册模型路由、完成登录并持有凭据；本插件只**读取**同一份凭据，不代为登录、也不保存它们。
|
|
@@ -172,7 +217,7 @@ $env:DEEPSEEK_API_KEY = "<你的 DeepSeek API Key>" # 启动环境；改完需
|
|
|
172
217
|
| --- | --- | --- |
|
|
173
218
|
| Command Code | [`@mars-sea/dsh-commandcode-provider`](https://www.npmjs.com/package/@mars-sea/dsh-commandcode-provider) | 在该插件的设置页登录，或运行 `cmd login`（兜底读 `~/.commandcode/auth.json`） |
|
|
174
219
|
| SuperGrok | [`dsh-grok-kit`](https://github.com/KouzakiUmi/dsh-grok-kit) | 运行 `grok login`，登录文件 `~/.grok/auth.json` |
|
|
175
|
-
| Codex（ChatGPT 订阅） |
|
|
220
|
+
| Codex（ChatGPT 订阅） | [`dsh-codex-connect`](https://github.com/franksong2702/dsh-codex-connect)（npm 同名包） | 运行 `codex login`，登录文件 `$CODEX_HOME/auth.json` 或 `~/.codex/auth.json` |
|
|
176
221
|
|
|
177
222
|
> **Codex 默认关闭**：它的提供方插件本身就带一个用量药丸，两个并排只是重复信息。想要本插件这一份（比如想把 Codex 和别家放在一起看）可以在**提供商管理**里手动开启。
|
|
178
223
|
>
|
|
@@ -303,6 +348,8 @@ ark-coding-plan-byteplus ARK_CODING_PLAN_BYTEPLUS_API_KEY
|
|
|
303
348
|
|
|
304
349
|
- 模型手里的名字往往不是这里的 provider id（它更可能看到 DSH 的路由名，例如 `zai`），所以匹配是**宽松**的：一个名字命中多条路由时**全部返回**（`zai` → 中国版 + 国际版，`ark` → 5 条），每条各自带着真实 `state`（没启用的如实标 `disabled`），由调用方自己判断要看哪条。
|
|
305
350
|
- 一个名字都认不出时，返回里会**先**给一条说明（写明可用写法），**再附上全部 30 条数据**——数据先给出去，判断交给调用方，而不是回一个空结果。
|
|
351
|
+
- **点名的家原样返回，其余按「有没有数据」收起**：`providers: ["kimi"]` 时被点中的家即使没配凭据也照原样给出（用户问的正是「它为什么没数据」）；**不点名时**——以及名字一个都没认出来、走全量兜底时——省略检测已关闭、未配置凭据、以及接口没报告任何额度的条目，省略条数按**家**写进 `omitted`（同一家的多个 Command Code 账户只算一家），否则三十来条路由会把真正的数字淹掉。**读取失败的条目会保留**——那是「这次没读到」，不是「没配置」，省略掉只会把排障方向带偏；认不出的名字自己那行也保留。
|
|
352
|
+
- **Command Code 按账户各回一条**：账户清单读自提供方插件的 `llm-commandcode` 设置，每条带 `account`（账户名）、`accountActive`（当前激活的那个）与 `accountMode`（`fixed` 固定账户 / `auto` 自动轮换），激活账户排在最前。「还剩多少」与「现在实际用哪个账户」一次问清。
|
|
306
353
|
|
|
307
354
|
**Host 服务**（Cordis `Service`，key 为 `subUsage`）：
|
|
308
355
|
|
|
@@ -311,16 +358,19 @@ const service = ctx.get("subUsage");
|
|
|
311
358
|
const view = await service.quota({ providerIds: ["deepseek"], force: false });
|
|
312
359
|
// view = {
|
|
313
360
|
// updatedAt,
|
|
314
|
-
// providers: [{ providerId, label, state, windows, extras, coverage?, freshness?, lastSuccessAt?, error
|
|
361
|
+
// providers: [{ providerId, label, state, windows, extras, coverage?, freshness?, lastSuccessAt?, error?,
|
|
362
|
+
// account?, accountActive?, accountMode? }]
|
|
315
363
|
// }
|
|
316
364
|
```
|
|
317
365
|
|
|
318
366
|
- `state`：`ok` | `no-key` | `no-cookie` | `error` | `disabled`
|
|
319
367
|
- `windows[].percent` 是**已用**百分比（0–100）；`extras` 放余额与套餐名等补充项
|
|
320
|
-
-
|
|
368
|
+
- `account` / `accountActive` / `accountMode` 只在多账户的 Command Code 上出现（见下）；此时同一条路由会有**多条**条目（每个账户一条，`providerId` 相同），消费方按 `account` 区分
|
|
369
|
+
- 视图**刻意精简**：不返回设置，也不返回 `keySource` / `apiDetected` / 继承变量名等内部状态，第三方消费者拿不到任何与 Key 相关的字段。多账户路由（Command Code）连错误文案里的**凭据引用名**也会换成账户标签（`Account 2`），内部 `apiKeyEnv` 只留在本机界面那条通道里（用户要靠它定位该往哪个 ref 写凭据）
|
|
321
370
|
- 视图里**不出现值为 `undefined` 的字段**：字段缺席表示「这家没有报告」，而不是「报告了空」——带 `undefined` 的键会被调用方的 schema 校验判成型别错误
|
|
322
371
|
- 单家读取失败只影响它自己的条目，其余照常返回
|
|
323
|
-
- 与设置页共用同一份缓存（TTL 60
|
|
372
|
+
- 与设置页共用同一份缓存（TTL 60 秒），频繁调用不会反复请求各家接口；多账户各按「路由 id + 账户引用名」占一份缓存，读全部账户不会互相驱逐
|
|
373
|
+
- `quota()` 本身**不过滤**条目（第三方可能正需要「这家没配」这个事实）；`subusage_quota` 工具的不点名调用才省略空条目
|
|
324
374
|
|
|
325
375
|
## Troubleshooting / 常见问题
|
|
326
376
|
|
|
@@ -341,7 +391,7 @@ const view = await service.quota({ providerIds: ["deepseek"], force: false });
|
|
|
341
391
|
| 保存成功但验证失败 | 凭据已保存，检查网络、区域或账号后重试；保存与在线验证分别反馈 |
|
|
342
392
|
| 保存提示配置已改变 | 另一窗口或实例更新了设置；重新读取配置后再编辑，避免旧表单覆盖新值 |
|
|
343
393
|
| 升级后仍是旧界面或 RPC 不匹配 | 确认运行中的 Host 和 Client 都已重载；仅刷新页面不能保证 Host 升级 |
|
|
344
|
-
| Command Code 额度与实际账户不同 |
|
|
394
|
+
| Command Code 额度与实际账户不同 | 在 设置 → 订阅用量 的 Command Code 面板或用量的药丸弹层里都能切换提供方插件的服务账户（同一开关）：「自动轮换」时显示默认账户（顶层 Key）的用量，不跟随轮换中的实际服务账户，提供方自定义 `apiBase` 也不跟随。想一次看全部账户的余量与当前激活项，可让 Agent 调 `subusage_quota(providers: ["commandcode"])` |
|
|
345
395
|
| SuperGrok 提示认证失效 | 登录文件里的 OAuth token 会过期；在 设置 → Grok Kit 重新登录、运行 `grok login`，或让 Grok 侧使用一次以刷新共享登录文件后重试。API Key（`XAI_API_KEY`）取不到订阅周池 |
|
|
346
396
|
| 火山方舟报签名或权限错误 | AK 与 SK 必须来自同一个 IAM 用户（跨来源拼凑只会 401 且看不出根因）；确认用的是 IAM Access Key 而不是方舟推理 API Key；403 多为未订阅或权限不足 |
|
|
347
397
|
|
|
@@ -381,21 +431,23 @@ node scripts/check-browser-runtime.mjs # 需要工作区可解析 playwright-c
|
|
|
381
431
|
|
|
382
432
|
文档入口：[凭据获取指引](docs/credentials.md)（每类凭据的官网入口、环境变量与填入位置、报错对照）、[开发与验证](docs/development.md)（RPC 契约、缓存与凭据约定、离线预览与实机验收范围）、[提供商清单与额度语义](docs/providers.md)、[提供商覆盖与取舍](docs/provider-coverage.md)、[UX 设计](docs/design-ux.md)、[发布与市场收录](docs/publish.md)、[更新记录](docs/changelog.md)、[审查记录](docs/code-review.md)。
|
|
383
433
|
|
|
384
|
-
> 打包说明：`package.json` 的 `files` 白名单是 `lib` / `
|
|
434
|
+
> 打包说明：`package.json` 的 `files` 白名单是 `lib` / `cordis.patch.yml` / `README.md` / `LICENSE`，因此 `assets/title.svg`、`assets/screenshots/` 与 `docs/` **不进 npm 包**——顶部 title 图与下面的界面预览只在 GitHub 页面显示。改动白名单属于发布决策，需单独处理。
|
|
385
435
|
|
|
386
436
|
### 界面预览
|
|
387
437
|
|
|
388
|
-
以下为 0.
|
|
438
|
+
以下为 0.10.11 的离线组件测试截图，使用虚构用量数据，不包含真实账号信息，也不是运行中的 DSH 截图。
|
|
389
439
|
|
|
390
440
|
深色设置页：查看订阅用量、管理凭据与提供商。
|
|
391
441
|
|
|
392
442
|
|
|
393
443
|
|
|
394
|
-
|
|
444
|
+
浅色用量弹层：顶部先给结论（额度充足 / 余量偏低 / 即将用尽…），下面是各窗口的剩余百分比与重置时间。右下角是收起态药丸——每个窗口一根彩条，正常时不写字。
|
|
395
445
|
|
|
396
446
|
|
|
397
447
|
|
|
398
|
-
|
|
448
|
+
药丸 15 种状态一览（浅色 / 深色）见[开头的能力展示](#15-种状态一眼分清)。
|
|
449
|
+
|
|
450
|
+
截图声明见根目录 [`screenshots.json`](screenshots.json)。这些图都是**当前版本**的离线组件预览（虚构用量、桩网络、无凭据），已随本版本重做，底部水印明确标注「非运行中的 DSH 截图」。真实 DSH Loader、实际账号在线接口与多账户映射仍未验收，截图不代表已通过这些检查。
|
|
399
451
|
|
|
400
452
|
## License & security / 许可与安全
|
|
401
453
|
|