dsh-usage-stats

一句话定位

为 DeepSeek Harness 网页端补充多供应商账户余额、订阅 / Token Plan 额度窗口、按天按 provider/model 聚合的 Token 用量与缓存命中率，统一收口在侧边栏底部一个浮层面板里。普通用户在 dsh web 里就能看到今天烧了多少 Token、当前账户还能用多久，而不用切到每个供应商自己的控制台。

核心能力

• 在侧边栏底部新增"用量/余额"入口：点开后是浮层面板，一次只显示当前选中的 provider，标题栏可手动刷新（同时刷新 Token、provider 列表、当前账户）
• 每日 Token 用量统计：今日、本月、累计、缓存命中率、按日期/provider/model 下钻；同模型来自不同 provider 会分别归集（例如 deepseek-official · deepseek-chat 与 ark · deepseek-chat）
• 类 Codex 蓝色月历热图：方格按当月最大值的平方根连续映射（零是中性灰"空"），点击日期展开当天的 provider/model 明细与命中条
• 多供应商余额统一卡片：DeepSeek、OpenRouter、Moonshot、Z.ai、New API、Sub2API、Passion、通用余额模板，按"normal/warning/critical"剩余比例上色（默认 30%/10% 阈值）
• 订阅 / Token Plan 额度窗口：OpenCode Go 滚动用量、Z.ai Coding Plan（支持中国区 bigmodel-cn）、Kimi For Coding、MiniMax Coding Plan（支持 cn 区域），每窗口显示剩余比例与重置时间
• 后台自动监测：服务端启动即刷新一次，之后每 5 分钟刷新所有已配置账户与本地 Token 聚合；浏览器只请求当前 provider，刷新频率与面板是否打开无关

技术实现

• 语言: JavaScript（ESM；lib/ 下 5 个 .js 文件，客户端 bundle 单文件 1464 行手写，无构建步骤）
• 关键依赖: 纯 Node.js 内置模块——node:fs/promises（缓存原子写）、node:http/node:https/node:dns/node:net（上游请求 + DNS 解析 + IP 过滤）、node:path/node:os（DSH_HOME 解析）。客户端用宿主 bundle 提供的 React 18 与 @deepseek-ai/dsh-client-ui-primitives
• 架构模式: dual-half 宿主插件。cordis.patch.yml 在 web profile 插入 1 行 Loader（id: usage-stats, name: dsh-usage-stats）；package.json#dsh.bundle.patch 指向 patch；服务端 apply(ctx, rawConfig) 注册 5 个 exact GET 路由并启动 5 分钟定时器；客户端通过 __ModuleLoader__ 注入 sidebar.footer.action 插槽，用 React.createPortal 把浮层挂到 document.body 避免侧边栏主题变量泄漏
• 入口文件: 服务端 lib/index.js（apply / name = "usage-stats" / Config = { ~standard: ... }）；客户端 lib/client.js；账户适配器 lib/accounts.js；Token 聚合 lib/usage.js；余额方案 lib/balance.js；订阅窗口 lib/subscriptions.js

适用场景

DSH 用户希望把多个 LLM 供应商的"还剩多少钱/多少额度/今天烧了多少 Token"集中在一处查看，特别是同时使用 DeepSeek 官方 + 几家 Coding Plan + 自建 New API/Sub2API 中转的开发者。本插件不展示模型本身或对话历史，只在原有的侧边栏新增一个独立的浮层面板，对工作流零侵入。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:Ychris12138/dsh-usage-stats

也可走 npx 兼容安装：npx --yes github:Ychris12138/dsh-usage-stats，支持 --dry-run / --check / --no-enable。安装或更新后必须重启已运行的 dsh web，并在浏览器硬刷新加载新的客户端 bundle。

配置项

插件开箱即用——无需任何 config 也能在侧边栏看到 Token 用量热图；下面所有字段均为可选，仅当你想让面板显示某个 provider 的余额/Token Plan 时才需要填。配置写在 ~/.dsh/profiles/web/cordis.patch.yml 中已有的 name: dsh-usage-stats entry 的 config.monitors 下（不要新开第二个插件 entry，否则会重复挂载）。

常见问题

Q: 安装后侧边栏没看到"用量/余额"入口怎么办？

A: 安装或更新插件后必须重启已运行的 dsh web，并在浏览器硬刷新（Ctrl/Cmd+Shift+R）。插件的服务端路由与客户端 bundle 都在 dsh web 启动时挂载，只刷新浏览器不会重新装载。安装器在 cordis.patch.yml 写入一条 - insert: id: usage-stats, name: dsh-usage-stats，重复运行是幂等的，不会重复追加。

Q: 不配置 Key 能用吗？能看到什么？

A: Token 用量热图与缓存命中率完全无需任何凭据，会自动汇总所有 session 的事件流。没有公开余额端点的 provider 在账户卡片显示"不支持"，插件不会乱猜余额；缺 Key 的 provider 显示"未配置"。OpenRouter 是唯一例外：官方账户 credits 必须用独立的 OPENROUTER_MANAGEMENT_KEY，插件不会拿普通推理 OPENROUTER_API_KEY 去试探 /api/v1/key。

Q: 数据存在哪里？会不会上传？

A: 服务端聚合缓存只保存按 provider/model 折叠后的 Token 数、会话 id、不透明 revision 与折叠游标，写入 $DSH_HOME/storages/usage-stats-cache.json，采用临时文件 + 原子 rename 写入。API Key、OpenCode auth.json、Cookie、管理 PAT 与上游原始响应永远不会进入浏览器响应、插件缓存或日志。validate:live 脚本会逐会话对比插件端点与官方 token projection，结果不一致会返回非零退出码——但脚本可能输出真实余额，不要把输出贴到公开 issue。

Q: 能接入自己的私有供应商吗？

A: 可以，用 declarative adapter：在 monitor 下设置 mode: balance 或 mode: subscription、request.path（HTTPS 同源相对路径）、request.auth.type（bearer/raw/x-api-key）、extract.* JSON Pointer 字段。仅执行受限 GET + JSON Pointer，不执行 JavaScript。凭据只能通过 credential 引用注入，usageBaseURL 不允许内嵌 username/password；敏感 header（Authorization/X-API-Key/API-Key/Cookie 等）必须在 request.headers 里被插件拒绝直接覆盖。发凭据前会筛选域名的 IPv4/IPv6 解析结果并固定一个允许的连接地址，优先使用公网地址。

Q: OpenCode Go 额度突然不可用 / 接口变 401 怎么办？

A: OpenCode Go 的 Bearer usage 端点（opencode.ai/zen/go/v1/usage）不是官方公开 API，上游可能随时调整结构；接口变化时面板会显示具体错误信息。可在 monitors.opencode-go 下显式设置 credentialRef: OPENCODE_GO_API_KEY，或回退到 OPENCODE_GO_AUTH_COOKIE + OPENCODE_GO_WORKSPACE_ID 的 cookie 兼容方案（plugin 会优先用 Harness credential，其次读 ~/.local/share/opencode/auth.json，最后才用 cookie）。不想用时直接从 Cordis entry 里删掉对应 monitor 即可停用。

Q: 反向代理能否把这五个端点暴露到公网？

A: 不建议。五个端点（/api/usage-stats/{usage,providers,balance,subscriptions,account}）只校验 peer socket 是否回环 + Host header，不做身份认证；如果挂在反代后面，插件看到的 peer 会是代理自身的回环地址，等同绕过安全边界。README 与 SECURITY.md 都明确"不要把端点经反向代理暴露到局域网或公网；确需代理时必须在代理层增加可靠认证与访问控制"。安全问题请按 SECURITY.md 描述私下报告。

Q: 如何卸载？

A: dsh plugin --profile web remove dsh-usage-stats 重启 dsh web 即可。缓存文件 $DSH_HOME/storages/usage-stats-cache.json 留在磁盘上，需要时手动删除；安装器写入的 cordis patch 也会被一并清理。安装器不会动 ~/.dsh/.credentials.yaml。

上手难度

入门 — 一条 dsh plugin --profile web add + 重启 dsh web 即在侧边栏看到"用量/余额"入口，Token 用量统计自动可用。进阶处在于阅读 README 里 monitors.<providerId> 的 YAML 配置示例，给 OpenRouter、OpenCode Go、各家 Coding Plan 与自建中转（New API / Sub2API / Passion / declarative）配上对应的 adapter 与 credential 引用。

已知问题与限制

• OpenCode Go 的 Bearer usage 端点（opencode.ai/zen/go/v1/usage）为非官方公开 API：上游调整结构时额度面板会显示错误信息；可用 OPENCODE_GO_AUTH_COOKIE + OPENCODE_GO_WORKSPACE_ID cookie 兼容回退，不愿用可直接删 monitor 关闭
• DSH 客户端侧边栏布局是 ROW 排布：本插件作为第二个 footer action 会触发宿主布局把后面条目挤出可视区——插件通过把宿主容器临时切到 column 布局规避（见 client.js 中 flexDirection 切换 effect，issue #21 已记录）
• 部分第三方 Coding Plan 仅余额可用：Kimi Code 5 小时 / 周窗、Z.ai 部分接口若上游结构变化需等适配；Anthropic OAuth、OpenAI Codex、Gemini Code Assist、GitHub Copilot 个人版暂无 API-Key 化用量端点
• DSH 重启后会以压缩摘要恢复活跃会话：插件发现内存事件游标低于折叠游标时会整会话重新折叠统计（issue #23 已记录），重启后短时间内用量数字会先"回滚"再追平
• 账户卡片在 panel 容器内 portal 到 document.body：避免侧边栏主题变量泄漏进浮层（issue #17 已记录），但因此与侧边栏的视觉层级完全独立
• 自定义 monitor 默认要求 HTTPS + 同源相对路径 + 手动 redirect + JSON + 1 MiB 上限：allowInsecure 必须显式开启才能用 HTTP；198.18.0.0/15 区间仅作为 Clash/Mihomo 风格 fake-IP 的合成地址接受（仅 HTTPS 域名），字面 IP 与其它私网地址默认拒绝，防止 DNS rebinding 绕过
• 安装 / 更新插件后必须重启 dsh web：服务端 exact 路由、5 分钟定时器与客户端 bundle 均在 dsh web 启动时挂载，只刷新浏览器不会重新装载
• dsh plugin 与 npx 是两条独立的安装路径：不要同时保留手工 cordis entry 与 bundle 注册，否则会重复挂载；安装器在写入前会校验 YAML 根节点不为空 []，历史版本留下的 [] 残根会被自动清理

为 DeepSeek Harness 网页端提供多供应商账户监测与 Token 用量分析。

Provider balances, subscription quotas, and token-usage analytics for the DeepSeek Harness Web GUI (dsh web).

展示图使用脱敏演示数据；插件不会把 API Key、Cookie、管理 PAT 或上游原始响应发送到浏览器。

一眼看懂 / At a glance

界面支持中文和英文。浏览器只请求当前选择的 provider；后台刷新与面板是否打开无关。手动刷新会更新用量、供应商列表，并强制刷新当前账户，不会批量强制请求其他供应商。

快速安装 / Quick start

需要 DeepSeek Harness web profile（@deepseek-ai/dsh >= 0.1.0-rc.6）。

dsh plugin --profile web add "github:Ychris12138/dsh-usage-stats"

然后重启已经运行的 dsh web，并在浏览器中硬刷新。侧边栏底部会出现“用量/余额”（Usage/Balance）入口。

插件市场 GUI 安装（DSH Community Market，Path A 标准来源）

本仓库按 DSH Community Market 目录 adapter 指南 的标准来源（Path A） 接入，无需修改 Market 代码。内置两份目录数据：

• catalog/catalog-source.json — 来源 manifest（catalog-source.schema.json v1.0.0）
• catalog/v1/plugins.json — 标准 provider page（catalog-provider-page.schema.json v1.0.0）

使用前提（重要）：市场托管安装只接受 npm registry 的精确稳定版本，git 条目仅可浏览。dsh-usage-stats 这个 npm 名已被其他项目占用，因此目录条目身份使用 @ychris12138/dsh-usage-stats（当前可用）。要启用 GUI「安装」按钮，需先发布：

1. 仓库包身份已统一为 @ychris12138/dsh-usage-stats；每次发版需同步 package.json / package-lock.json / catalog/v1/plugins.json 的版本。
2. 发布 scoped 公共包：npm publish --access public。
3. 把 catalog/v1/plugins.json 内容发布到 https://ychris12138.github.io/dsh-usage-stats/v1/plugins（GitHub Pages，manifest 与 endpoint 必须同源、HTTPS 443、无凭据）。
4. 在 DSH 插件市场 → 来源管理 → 添加来源，粘贴 manifest URL：https://ychris12138.github.io/dsh-usage-stats/catalog-source.json，选择后即可走「可恢复安装边界」GUI 安装。

若最终包名不同，请同步修改 catalog-source.json 的 providerId/transport.endpoint 与 catalog/v1/plugins.json 的身份字段。发布前目录条目可浏览但安装保持禁用（fail-closed，属预期）。

升级或卸载：

dsh plugin --profile web update "@ychris12138/dsh-usage-stats"
dsh plugin --profile web remove "@ychris12138/dsh-usage-stats"

npx --yes github:Ychris12138/dsh-usage-stats

# 预览，不修改文件
npx --yes github:Ychris12138/dsh-usage-stats --dry-run

# 检查现有安装
npx --yes github:Ychris12138/dsh-usage-stats --check

# 安装但不修改 Cordis patch
npx --yes github:Ychris12138/dsh-usage-stats --no-enable

支持的账户类型 / Providers

插件自动发现官方 DeepSeek 路由和 llm-pi-ai 中的 provider profile。只有存在公开账户接口或显式 monitor 的供应商才会查询远端账户；Token 用量统计不需要额外凭据。

没有公开账户接口的供应商仍会正常统计 Token；账户卡片会明确显示“不支持”，不会猜测余额。

凭据与供应商配置 / Configuration

凭据由 Harness 从 ~/.dsh/.credentials.yaml 解析。安装器不会读取、创建或修改该文件。不要把真实 Key、Cookie 或管理令牌提交到 Git、公开 issue，或粘贴给编码 Agent。

余额型供应商

DeepSeek、Moonshot 等默认复用对应 provider profile 的 apiKeyEnv。例如：

# ~/.dsh/.credentials.yaml
DEEPSEEK_API_KEY: sk-your-key-here

OpenRouter 是明确的例外：官方账户 credits 接口要求 Management Key，不能复用普通推理 OPENROUTER_API_KEY。插件默认读取独立引用；未配置时显示“未配置”，不会拿推理 Key 试探：

# ~/.dsh/.credentials.yaml
OPENROUTER_MANAGEMENT_KEY: sk-or-v1-your-management-key

插件按 total_credits - total_usage 显示 OpenRouter 余额，并同时展示累计已用和总 credits。普通 Key 的 /api/v1/key 只描述单个 Key 的 spending limit，不会被当作账户余额。自定义引用可在 monitors.openrouter 中设置 adapter: openrouter-balance 与 credentialRef。

Token Plan 供应商

# ~/.dsh/.credentials.yaml
OPENCODE_GO_API_KEY: sk-opencode-your-key
ZAI_API_KEY: your-zai-key
# 中国区 Z.ai 用户可选；默认 global
ZAI_API_REGION: bigmodel-cn
KIMI_API_KEY: your-kimi-key
MINIMAX_API_KEY: your-minimax-key
# 中国区 MiniMax 用户可选；默认 global
MINIMAX_API_REGION: cn

OpenCode Go 依次尝试 Harness credential、~/.local/share/opencode/auth.json，最后才使用显式 OPENCODE_GO_AUTH_COOKIE + OPENCODE_GO_WORKSPACE_ID 兼容回退。Bearer usage endpoint 目前不是公开 API，可能随上游变化；Cookie 等同登录凭据，不应进入日志或 issue。

Z.ai 全球区使用 api.z.ai，中国区使用 open.bigmodel.cn。MiniMax 优先使用官方 www.minimax.io / www.minimaxi.com Token Plan 地址，并解析 5 小时与周窗口的剩余比例和重置时间。

New API、Sub2API 与自定义 monitor

在现有 name: "@ychris12138/dsh-usage-stats" Cordis entry 下合并 config，不要追加第二个插件 entry。monitor 键必须是 Harness 中真实存在的 provider id；未知 provider、adapter 或非法映射会在路由和 timer 注册前阻止插件启动。例外：monitor 同时显式提供 usageBaseURL 与 credentialRef 时视为自包含，会在 provider 注册可见前临时物化为 provider（适用于 Harness 设置页里后加载的 provider），此时不要求该 provider 已出现在注册表中。

# ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: usage-stats
      name: "@ychris12138/dsh-usage-stats"
      config:
        monitors:
          relay-a:                 # Harness provider id
            adapter: new-api
            # 仅旧实例的 /api/user/self 回退需要：
            fallbackCredentialRef: RELAY_A_MANAGEMENT_PAT

        monitors:
          relay-a:
            adapter: general
            warning:
              warnBelow: 5
              criticalBelow: 1

        monitors:
          relay-a:
            adapter: sub2api
            warning:
              warnBelow: 5
              criticalBelow: 1

        monitors:
          relay-b:
            adapter: sub2api-auth

# 只要这些（不需要单独的 SUB2API_* 凭据）
# DSH 模型页里为 Sub2API 面板配置 provider，baseURL 指向面板，API Key 填可用的密钥

        monitors:
          private-model:
            adapter: declarative
            mode: balance
            request:
              path: /account/balance
              auth:
                type: bearer
                credentialRef: PRIVATE_MODEL_API_KEY
            extract:
              root: /data
              remaining: /available_balance
              used: /used_balance
              total: /total_balance
              currency: /currency

支持的 adapter：deepseek-balance、openrouter-balance、moonshot-balance、zai-balance、new-api、sub2api、sub2api-auth、general、opencode-go、zai-token-plan、kimi-token-plan、minimax-token-plan、declarative。

warning.warnBelow 与 warning.criticalBelow 是余额绝对值阈值。具有总额度的余额和 Token Plan 会自动产生 normal / warning / critical 剩余比例状态（默认 30% / 10%）。

使用 / Usage

1. 点击侧边栏“用量/余额”。
2. 用“当前供应商”切换账户卡片；一次只显示一个 provider。
3. 使用 ‹ / › 切换月份，点击热图日期查看当天的 provider/model 明细。
4. 标题栏刷新会更新 Token、provider 列表，并强制刷新当前账户。

“最近 14 天”按本地日历计算，只显示窗口内存在用量的日期；未来时间戳不会计入。同一模型来自不同 provider 时会分别统计，例如 deepseek-official · deepseek-chat 与 ark · deepseek-chat。

Agent 友好安装 / Agent-friendly installation

Install or update dsh-usage-stats from:
https://github.com/Ychris12138/dsh-usage-stats

Constraints:
- Resolve DSH_HOME from the environment; otherwise use ~/.dsh.
- Do not read, print, edit, or request .credentials.yaml, auth.json, cookies, or any API key.
- Do not expose the plugin through a reverse proxy.
- Do not restart or terminate an existing dsh process without asking me.

Procedure:
1. Confirm node, npx, and dsh are available.
2. Prefer `dsh plugin --profile web update "@ychris12138/dsh-usage-stats"` when already installed; otherwise use `dsh plugin --profile web add "github:Ychris12138/dsh-usage-stats"`.
3. If unavailable, use: npx --yes github:Ychris12138/dsh-usage-stats
4. Do not combine bundle installation with an existing manual dsh-usage-stats Cordis entry.
5. For npx, require a verified package and exactly one Cordis entry, then run again with --check.
6. Report the installation path and resolved profile paths.
7. If dsh web is running, report that a restart is needed and stop.

Optional account setup (never handle secret values yourself):
- OpenRouter account balance requires OPENROUTER_MANAGEMENT_KEY, not the inference key.
- OpenCode Go may reuse local auth.json or use OPENCODE_GO_API_KEY.
- Z.ai uses ZAI_API_KEY; China accounts may set ZAI_API_REGION=bigmodel-cn.
- Kimi and MiniMax use KIMI_API_KEY and MINIMAX_API_KEY.
- Never ask me to paste a key or browser cookie into chat.

Optional monitor setup:
- Read configured Harness provider ids and ask which id should receive a monitor.
- Add only non-secret config under the existing dsh-usage-stats Cordis entry.
- Store credential reference names, never credential values.
- Validate relative request.path and JSON Pointer fields beginning with /.
- Do not enable cross-origin, insecure HTTP, or private-network access unless I explicitly request it.

npx --yes github:Ychris12138/dsh-usage-stats --check

隐私与安全 / Privacy & security

• API Key、OpenCode auth.json、Cookie 与管理 PAT 不会进入浏览器响应、插件缓存或日志。
• Sub2API sub2api-auth 复用 provider 自己的推理 API Key（模型页已配置的那个），不会再引入或落盘额外的面板凭据。
• 自定义 monitor 默认要求 HTTPS、同源相对路径、手动 redirect 和 JSON 响应，body 上限为 1 MiB。
• 发凭据前会筛选域名的 IPv4/IPv6 解析结果并固定一个允许的连接地址，优先使用公网地址；HTTPS 域名解析到 198.18.0.0/15 时可作为 Clash/Mihomo 等代理的 synthetic fake-IP 使用。字面量 198.18/15、其他私网/特殊地址仍默认拒绝，防止 DNS rebinding 绕过私网限制。
• usageBaseURL 禁止内嵌 username/password；Authorization、X-API-Key、API-Key 等 header 必须由 credential ref 注入。
• 五个端点仅接受 GET，并同时校验 peer socket 与 Host；支持 IPv4、IPv4-mapped IPv6 和 [::1]:port。
• 用量缓存 ~/.dsh/storages/usage-stats-cache.json 只保存聚合 Token、会话 id、不透明 revision 与折叠游标，不保存提示词、回复或文件路径。

本机反向代理会让插件看到代理自身的回环地址。请勿把端点经反向代理暴露到局域网或公网；确需代理时必须在代理层增加可靠认证与访问控制。安全问题请按 SECURITY.md 私下报告。

正确性与数据口径 / Correctness

统计值来自 assistant/chunk 或 assistant/message 中 provider-reported usage，不是本地估算。相同 turn/step 的后续样本会替换旧样本，并按 provider/model 归集。

• 活跃会话只处理新追加事件。
• 持久化会话使用不透明 revision；未变化时不重复读取日志。
• seq 缺口、日志重写或 live/persisted 切换时完整重折叠该会话。
• 聚合采用 single-flight，并在同一临界区原子保存缓存。
• validate:live 会逐会话比较 raw artifact、session.history、插件端点与官方 token projection；缺文件或不一致会返回非零。

API

非 GET 返回 405，非回环请求返回 403；所有响应均为 JSON 并带 Cache-Control: no-cache。

开发与验证 / Development

npm install
npm run check
npm test
npm pack --dry-run

npm test 完全离线，覆盖 bundle、客户端渲染与请求竞态、服务端安全边界、余额/Token Plan adapter、缓存和安装器幂等性。真实数据验证需先运行 dsh web：

npm run validate:live
node scripts/check-balance.mjs

所有服务端脚本均遵循 DSH_HOME。check-balance.mjs 可能显示真实余额，不要把输出粘贴到公开 issue。

兼容性与致谢 / Compatibility & credits

当前版本为 0.2.0。插件依赖 Harness 客户端模块加载器、Cordis 服务与 session persistence；Harness 预发布接口变化时可能需要同步适配。

• Javis603/token-monitor：参考多 provider 配额归一化与 Z.ai 限额解析。
• xiaoqi20/dsh-opencode-go-usage：参考 DSH 凭据接入、OpenCode auth.json 回退与 Bearer usage endpoint。

本项目重新实现统一 account protocol、adapter 与单供应商 UI，不复制参考项目界面。

License

MIT