dsh-quota-panel

dsh plugin --profile web add dsh-quota-panel

dsh-quota-panel

[English](README.md) | 中文

dsh-quota-panel 是 DeepSeek Harness（DSH）网页端（dsh web）的供应商额度/余额状态组件。

它驻留在产品界面右下角，监控你配置过 API Key 的每一个 AI 供应商，

一眼看清还剩多少余额/额度——DeepSeek、OpenRouter、SiliconFlow、Moonshot、

StepFun、xAI、智谱 GLM、OpenCode Go、火山方舟（Agent/Coding Plan），one-api / new-api 风格的聚合站，

以及各家 Coding Plan（智谱 GLM Coding、Z.AI、Kimi Coding、MiniMax

Coding 国际/国内）：5 小时窗口、周配额与 MCP 月度额度一目了然。

StepFun、xAI、智谱 GLM、OpenCode Go、ChatGPT 订阅（Plus/Pro，经 Codex 登录），

one-api / new-api 风格的聚合站，以及各家 Coding Plan（智谱 GLM Coding、Z.AI、

Kimi Coding、MiniMax Coding 国际/国内、火山方舟 Agent/Coding Plan）：5 小时窗口、

周配额与 MCP 月度额度一目了然。

v0.5 起为双面插件 + 内置供应商目录自动发现：安装并重启 dsh web 后，

凡是 key 能解析的供应商都会自动出现在面板上——零配置。

它零 npm 依赖，也不需要 allowBuilds 构建授权。

效果图（真实浏览器渲染）

收起胶囊，浅色：

展开卡片，浅色：

设置面板（⚙），浅色：

收起胶囊，深色：

展开卡片，深色：

设置面板（⚙），深色：

支持的功能

• 自动发现 —— 宿主侧内置常见供应商目录，每项声明该供应商标准的 credential

引用名；**key 能解析（$DSH_HOME/.credentials.yaml / .env / 环境变量）的供应商

自动出现在面板上**，零配置；删除 key 行即消失。DSH 没有凭据枚举 API，

因此每个刷新周期都会探测一次目录。

• 两种尺寸 —— 收起：极简胶囊，每个账户一个「独立状态点 + 数值」对

（● ¥58.36 · ● 45%）；展开：完整卡片，每个供应商一行（状态点、名称、主数值、

次级信息，用量型供应商还有进度条）。

• 自动刷新 —— 跟随配置间隔（默认 60 秒），页面隐藏时暂停；刷新按钮请求期间旋转，

重复点击不会触发并发请求。

• 逐账户状态 —— 余额行按分级阈值（critical <= warn <= healthy），

用量行按百分比（error >= warn）；只有异常的点和数值变色，其余保持平静。

用量百分比使用手机电量式三色着色，与状态点独立。

• 设置面板（⚙） —— 逐供应商显示开关、刷新间隔、逐供应商预警阈值、

逐供应商 HTTP(S) 代理 URL、胶囊显示模式（自动 = 最高窗口（默认）/

5h 窗口 / 周窗口 / 最高窗口）、「恢复默认」。全部本地设置即时生效，

保存在浏览器 localStorage，绝不写入 profile 或上传。

• 按行 HTTP(S) 代理 —— 为无法直连的供应商配置代理（见下）。
• Coding Plan 用量窗口 —— 智谱 / Z.AI / Kimi / MiniMax 套餐渲染为用量行：

5 小时窗口、周配额与（GLM/Z.AI）MCP 月度车道，各带重置倒计时；

套餐没有的窗口显示 —，绝不伪造 0%。

• one-api / new-api 聚合站 —— 内置 openai-billing 格式适配聚合站仪表盘。
• 主题跟随 —— 完全使用 Harness 设计 Token（--dsw-alias-、--dsw-static-、

--dsw-shadow-、--dsw-font-）驱动，token 缺失时有合理 fallback，

自动跟随产品主题（浅色/深色），不携带自己的配色。

• 构架即安全 —— API Key 绝不进入浏览器；浏览器只与本插件在 DSH 自带 /api

鉴权通道（受信任主机 + 浏览器会话围栏）中的方法通信，只接收归一化视图（见「实现逻辑」）。

不支持的功能（规划中）

• usage-only 供应商 —— OpenAI、Anthropic、Together、Groq、Mistral、Cohere、

DashScope、百川没有公开的「剩余余额」接口，只有 usage/cost 类查询

（通常需要 admin key 与时间窗参数，语义是「已花多少」而非「还剩多少」）。

计划作为独立的 usage 型行接入，显示月度花费（首选 Anthropic Admin API 与

OpenAI usage API）。

• 仅 Cookie / CLI 的 Coding Plan —— 通义 Token Plan（百炼控制台）、小米 MiMo

Token Plan 与 Qoder 的配额页没有 API-key 查询端点：需要网页 Cookie、

arkcli 命令行或聊天接口限频探测（依据

CodexBar 的调研）。

火山方舟（豆包）的 Agent Plan / Coding Plan 已通过 AK/SK OpenAPI 接入（见上表）。

本插件其余供应商只使用 API key/Bearer 认证。

• socks5 代理 —— 仅接受 HTTP/HTTPS 代理（socks URL 会被拒绝并给出清晰的单行错误）。
• 自定义适配器 —— 无法从 profile 扩展新的上游格式；format 值超出内置集合时

在挂载时 fail loud。

• 多位置挂载 —— 组件只存在于 shell.overlay 槽位（右下角），

不支持侧边栏、顶栏或状态栏位置。

申请新增供应商

缺少你想监控的供应商？欢迎提 issue，附上：

1. provider id（^[a-z0-9-]+$，如 together）；双站点供应商的国内站用

-cn 后缀（参考 siliconflow / siliconflow-cn）；

2. 获取余额的 API URL —— 用该供应商的标准 API key 即可查询剩余

余额/额度的公开端点（如 GET https://api.provider.com/v1/user/info，

Bearer 认证）；能贴一段响应 JSON 结构更好。

目录接入只需要这些：一个标准凭据引用可解析的 id、一个端点、一个响应

格式适配器。只有 Cookie/CLI 配额页的供应商（见上）在官方提供

API-key 端点前无法支持。

实现逻辑

┌─────────────── browser (lib/client.js) ───────────────┐
│  shell.overlay 槽位 → 胶囊 / 卡片 / 设置面板           │
│  localStorage: 显示开关 · 间隔 · 阈值 ·               │
│                代理 URL（前端设置）                   │
└──────────────┬─────────────────────────────────────────┘
               │ Connection /api 通道（浏览器会话围栏）:
               │   POST /api/dsh-quota-panel/specs（渲染提示）
               │   POST /api/dsh-quota-panel/fetch-all { proxy }
┌──────────────▼────────────── host (lib/index.js) ──────┐
│  ctx.credentials → API Key（绝不离开宿主）              │
│  目录探测 → 自动发现（15 个内置供应商）                 │
│  逐行请求 → 代理引擎（CONNECT 隧道 / 绝对 URI）→ 上游 JSON │
│  归一化 → {balance | usage | info} 视图模型            │
└─────────────────────────────────────────────────────────┘

• 宿主侧（lib/index.js）注册一条仅限回环的 Connection RPC 通道

/dsh-quota-panel，两个端点：

• specs —— 解析后的行，只含渲染提示（id、label、行类型、货币、阈值分级、

窗口标签、已配置的代理名）。不含凭据，不含 endpoint。

• fetch-all —— 拉取每个可见行，把上游响应归一化为通用视图模型

（balance / usage / info），返回 {rows: [{id, view} | {id, error}], fetchedAt}。

上游原始 JSON 与 key 一样留在宿主侧；单行失败不影响其他行。

• 自动发现 —— DSH 的凭据库没有枚举 API，因此宿主侧在每个刷新周期探测目录项

的标准引用名；key 能解析的条目加入面板，解析不到的跳过（只有通过 providers

显式配置的行，key 缺失才会给出清晰的单行错误）。

• 代理引擎 —— 零依赖手写 proxiedGetJson：https 目标走 HTTP CONNECT 隧道

（TLS over 隧道），http 目标走绝对 URI 转发。每行独立 15 秒超时、1 MB 响应上限。

代理选择优先级：前端设置面板 > profile 配置 > 直连。

• 阈值判断发生在客户端 —— 基于 specs 提示，因此本地阈值覆盖无需重新拉取；

profile 阈值随 specs 下发，前端设置在其之上本地覆盖。

• 配置校验 —— 导出的 Config schema（vendor 的 schemastery）声明结构与默认值；

跨字段约束（id 唯一、critical <= warn <= healthy、代理引用存在、catalog 覆盖键合法）

由宿主侧在挂载时校验，失败即报错（fail loud）。

• DOM 安全 —— 卡片只用 createElement/textContent 构建 DOM，API 返回值绝不

经过 innerHTML；技术错误（401、超时、凭据缺失、代理拒绝）只写入 title 悬停提示

或行内错误文案。

• 代理故障绝不会带崩宿主 —— 代理引擎打开的每个 socket 与请求都会把 error

事件汇入该行结果，因此代理不可达（例如 clash 没开、ECONNREFUSED 127.0.0.1:7890）

只显示为该行的错误，而不是未处理的 EventEmitter error。

需要的配置

开箱即用：什么都不用配。 安装、重启，key 能解析的供应商自动出现。

下表只用于调优。

所有键都可选——结构与默认值在导出的 Config schema 里，profile patch 可省略一切

带默认值的字段。

键 · 含义 · 默认值

auto · 探测内置目录，key 已配置的供应商自动上板 · true

hide · 要隐藏的行 id 列表（目录行与显式行都生效） · []

proxies · 代理定义 {<名称>: "http://host:port"}，仅 HTTP(S) · {}

catalog · 对自动行的局部覆盖 {<目录id>: {...}} · {}

refreshMs · 自动刷新间隔 · 60000

providers · 显式行；同 id 整体替换目录行 · []

catalog 每项可覆盖：label / endpoint / format / proxy / refs（探测的

credential 引用名，UPPER_SNAKE）/ secretRefs（第二凭据引用，火山方舟 AK/SK 场景使用，

必须与

…(truncated)