前言¶
在 DSH 里同时使用 DeepSeek、GPT（Codex）、Gemini 的开发者，通常要在多个平台账户页之间切换才能确认各自还剩多少额度；账号多、窗口规则不同，逐个查看既打断工作流，也容易漏掉某个平台的重置时间。已有做法是继续开多个网页，或依赖各平台自己的额度文案。
dsh-quota-ring 把这个动作收进 DSH Web UI：在右下角显示一个悬浮圆环，点击后查看三家账号的额度状态。插件由 j352201657-debug 维护，属于客户端分类，在社区目录的星标为 1。下面介绍它的能力、安装方式和配置。
这是什么¶
dsh-quota-ring 是一个 DSH Web UI 插件，作用是聚合展示 DeepSeek / GPT（Codex）/ Gemini 三家账号的额度状态。当前版本为 3.1.1，许可证为 MIT，package.json 中声明的运行要求是 Node.js >=18、DSH >=0.2.0-rc.1 <0.3.0-0。
它解决的问题很集中：不替换各平台自己的查询入口，而是在 DSH 界面内给一个统一视图，让额度余量可见，而不是开多个窗口。
核心功能¶
圆环本身只显示「已知百分比窗口中的最低剩余额度」，即各平台当前能确定的最小余量；点击展开后才能看到明细。
DeepSeek 侧显示余额、累计消费、今日消耗估算和峰谷时段提示。GPT（Codex）显示账号上报的速率窗口及重置时间。Gemini 按 Antigravity 返回的额度组显示，可用组和窗口会随账号及上游接口变化。
三条设计约束值得注意：
- 三家平台独立查询，某个平台失败时其余平台继续显示。
- 金额和百分比分别展示，插件不把不同币种相加，也不做汇率折算。
- 未上报的数据不当作零额度或满额度处理，避免把「读不到」误显示成「用尽」。
刷新策略默认每 10 分钟一次，界面支持手动刷新；失焦时按 idleMultiplier 降频，页面隐藏时可暂停，服务端侧还有一层缓存用于合并并发的额度查询。
安装与启用¶
插件需要带 Web UI 和 webServer 服务的 DSH，以及 Node.js 18 或更高版本。安装分两种 profile。
桌面版通过桌面应用提供的插件安装入口安装，仓库地址为：
https://github.com/j352201657-debug/dsh-quota-ring
需要说明的是，桌面应用里的 desktop 是保留 profile，由桌面安装器管理，普通独立 CLI 不接受对该 profile 的安装命令。
独立 Web 版在已提供 dsh 命令的终端中执行：
dsh plugin --profile web add https://github.com/j352201657-debug/dsh-quota-ring
安装后重启对应的 DSH 实例。
三家平台的登录与组件要求不同：
| 平台 | 登录与组件要求 |
|---|---|
| DeepSeek | 在 DSH 内置的 DeepSeek 账号组件中登录 |
| GPT（Codex） | 安装 dsh-codex-subscription 并登录订阅账号 |
| Gemini | 安装 dsh-agy-cli 并完成 Antigravity 授权 |
补充两点依赖限制：Gemini 的原始额度读取依赖 Windows 凭据管理器，其他平台使用 AGY 状态接口回退，可能缺少部分窗口。只有对应平台具备有效登录状态时，才会显示其额度。
卸载时在对应 profile 中移除本插件的依赖和注册条目，再重启 DSH。统计状态位于 DSH 数据目录下的 dsh-quota-ring/usage-state.json，可按需保留。
配置¶
配置写在对应 profile 中本插件注册条目的 config 字段里。该插件提供的字段如下。
| 字段 | 默认值 | 说明 |
|---|---|---|
refreshIntervalMs |
600000 |
前端刷新间隔，毫秒，最小 5000 |
idleMultiplier |
3 |
失焦时的刷新间隔倍数 |
pauseWhenHidden |
false |
页面隐藏时是否暂停刷新 |
dshHome |
'' |
DSH 数据目录；留空自动查找 |
dshWebPort |
0 |
AGY 状态接口端口；0 表示从请求 Host 推断 |
proxy |
'' |
HTTP 或 HTTPS 代理地址；留空自动探测 |
serverCacheTtlMs |
60000 |
服务端缓存时长，毫秒；0 关闭缓存 |
requestTimeoutMs |
15000 |
单次上游请求超时，毫秒 |
corsOrigins |
回环来源 | 允许的跨域来源；另允许回环主机的任意端口 |
deepseekPeakWindows |
null |
UTC 峰时段列表，例如 [{start:1,end:4},{start:6,end:10}] |
deepseekPeakHolidays |
null |
UTC+8 假期日期列表，例如 ['2026-10-01'] |
凭据目录按以下顺序查找：config.dshHome；环境变量 DSH_HOME、DSH_DATA_DIR；从插件安装目录向上查找；用户主目录下的 .dsh。
代理按配置、HTTPS_PROXY / HTTP_PROXY / ALL_PROXY 环境变量、Windows 系统代理的顺序探测；无可用代理时直连，回环请求始终直连。服务端会合并并发的额度查询，手动刷新绕过已完成结果的缓存、复用仍在进行的请求。登录或切换账号后，下一次实际查询会重新读取凭据。
界面默认的峰谷窗口为 UTC 01:00–04:00、06:00–10:00（对应北京时间 09:00–12:00、14:00–18:00），周末和内置的 2026 年假期表参与计算。时段与假期均可通过配置覆盖。
HTTP API¶
插件在宿主内暴露 HTTP 接口，路由前缀为 /api/quota-hub，访问需遵循 DSH 宿主的身份验证和网络访问设置。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /summary |
查询聚合额度，支持缓存 |
| GET | /summary?force=1 |
绕过已完成结果的缓存 |
| POST | /refresh |
手动刷新 |
| GET | /config |
获取界面所需配置，代理仅返回配置状态 |
| GET | /diag |
查询本地诊断信息，不请求上游额度接口 |
额度结果包含 providers、fetchedAt 和 health。平台条目的状态为 ok、missing_key、unavailable 或 error，明细包含 windows，Gemini 还可包含 groups。DeepSeek 附带 peak 和 usage。
/diag 的详细结果在 diag 字段，包括凭据文件路径、解析状态、插件版本及处理建议。诊断结果可能包含本机路径，分享前应检查内容。
典型用法¶
按安装步骤装好、重启 DSH 后，进入 Web UI 即可在右下角看到圆环。如果某平台显示「未登录」，先确认该平台的登录组件是否已保存凭据，再手动刷新一次。
排障时可对照官方给出的对照表：
| 现象 | 检查项 |
|---|---|
| 圆环未显示 | 检查插件安装的 profile、注册条目和 DSH 启动日志 |
| 显示未登录 | 检查对应账号登录状态及 /diag 中的解析结果 |
| 登录后仍显示旧状态 | 手动刷新；检查 DSH 登录组件是否已保存新的凭据 |
| Gemini 数据不可用 | 检查 AGY 授权、组件启用状态和 DSH Web 端口 |
| Gemini 缺少部分窗口 | 检查是否使用 AGY 状态接口回退 |
| 查询超时 | 检查网络和 proxy 配置 |
| 峰谷提示不符合当前规则 | 更新时段和假期配置 |
设置环境变量 QH_DEBUG=1 可启用服务端调试日志；公开日志前应检查其中的账号信息和本机路径。
想自己核对实现的开发者可以运行离线测试，它使用临时目录和本地测试服务器，不读取真实登录凭据，也不请求平台额度接口：
npm test
node --check client.js
node --check index.js
需要本机账号生成预览时执行 node preview/build-preview.cjs，然后打开生成的 preview/preview.html。该命令会实际查询额度并更新本机消耗统计；预览页使用静态快照，生成文件不应直接公开，脱敏处理不能替代人工检查。
源码使用 CommonJS，客户端为原生 DOM，没有构建步骤。职责划分如下：index.js 处理路由与宿主生命周期，client.js 处理圆环、卡片和刷新交互，src/aggregator.js 处理请求合并、缓存及平台隔离，src/adapters/ 放各平台请求和响应解析，src/credentials.js 和 src/keyring.js 读取凭据，src/http.js 处理 HTTP、代理、超时及响应解析，src/peak.js、src/usage.js 处理时段提示和消耗估算。
适用场景与注意¶
适合在 DSH Web UI 内同时使用 DeepSeek、Codex、Gemini，且希望少开页面的开发者。它的价值在于把多平台余量压成一个常驻视图，而不是提供新的计费或对账能力。
使用前需要留意：
- 插件以当前 DSH 进程的权限运行，能读取该进程可访问的凭据、数据目录和网络出口。安装前建议通读源码并确认 MIT 许可证符合你的要求。
- 文中列出的 DeepSeek、Codex、Gemini 接口并非本插件定义的稳定公开协议，上游字段或鉴权变化可能导致查询失败。
- 今日消耗依据余额变化估算，不是官方账单；峰谷提示亦不用于计算官方账单，实际计费以平台公布的规则和账单为准。
- Gemini 原始额度读取依赖 Windows 凭据管理器，其他平台使用 AGY 状态接口回退，可能缺少部分窗口。
- 项目没有遥测上报逻辑，界面动态文本使用
textContent写入；但生成预览时会把额度快照写到本机。
结尾¶
这个插件做的事情单一：把 DeepSeek、GPT（Codex）、Gemini 三家的额度状态聚合到 DSH Web UI 右下角的悬浮圆环里，并在平台间保持查询隔离。对于已经在 DSH 中跑多模型工作流的开发者，它省掉的是反复切回各平台账户页的动作。
- 社区目录页：https://www.skillhub.cn/plugins/j352201657-debug/dsh-quota-ring
- GitHub：https://github.com/j352201657-debug/dsh-quota-ring
