前言¶
用 DeepSeek Harness（DSH）跑 dsh web 时，余额和 token 用量通常要切到别的页面或终端去查。多 provider、多通道（DSH 与 Claude Code）并行时，更难一眼看清「今天花了多少」「哪条通道占大头」。
dsh-usage 是社区维护的客户端插件，在 Web GUI 左下角挂一个持久化 dock，并提供一个可定制的余额 / 用量面板。数据在本地聚合，凭证由 Harness 服务端解析，不进入浏览器响应。
这是什么¶
dsh-usage（GitHub：Aisland-SJL/dsh-usage，SkillHub 目录：Aisland-SJL/dsh-usage）由 Aisland-SJL 维护，分类为客户端插件，MIT 许可。当前版本 0.2.0，GitHub 约 20 stars。
它面向已启用 web profile 的 DSH 用户，解决三件事：随时可见的余额与用量摘要、可拖拽排序的详情面板、以及 DSH 通道与 Claude Code 通道的用量对比。
核心功能¶
持久化 dock¶
关键数字常驻界面左下角。余额充足时显示为绿色，余额耗尽时变红；今日 / 本月 token、缓存命中率以紧凑行展示。角落有设置齿轮与一键刷新。侧边栏折叠时，dock 收成一个小型余额胶囊。
详情面板（七个组件）¶
两列卡片布局，每个组件可展开详情、折叠、隐藏、固定（pin），并支持拖拽排序：
| 组件 | 作用 |
|---|---|
| Balance | 左侧大数字，右侧展示可用 / 充值 / 赠送余额；可切换 provider |
| Today | 今日 token 总量，含 input / output / cache-read 拆分 |
| This month | 本月 token 总量，拆分同上 |
| Cache hit | 今日与全时段缓存命中率 |
| Channel share | DSH 通道与 Claude Code 通道占比条 |
| Usage log | 近 14 天按日列表，点击可下钻到各模型明细 |
| Activity heatmap | 28 天 × 6 个四小时时段的点阵热力图 |
外观与布局定制¶
强调色（预设 + 取色器）、背景色、面板透明度可实时调整。组件的 pin / collapse / hide / drag-reorder 状态写入 localStorage，刷新后保留。
双通道用量对比¶
DSH 侧 token 来自 Harness 内置统计；Claude Code 侧通过增量解析 ~/.claude/projects 下的 JSONL 日志聚合，只保留数字，不读取消息正文。
本地优先与安全边界¶
插件暴露三个仅 loopback 可访问的 GET 端点。凭证从 ~/.dsh/.credentials.yaml 经 Harness credentials seam 在服务端解析，插件不读取、不缓存、不回显密钥。上游余额查询强制 HTTPS，DNS 预解析并拒绝私网 / 环回地址，连接绑定到已校验 IP（防 DNS rebinding），响应上限 1 MiB，超时 15 秒。用量缓存写在 ~/.dsh/storages/，仅存聚合数字与 fold 游标。
支持的余额 provider¶
| Provider | 上游端点 | 默认凭证引用 |
|---|---|---|
| DeepSeek | GET {origin}/user/balance |
DEEPSEEK_API_KEY |
| OpenRouter | GET {origin}/api/v1/credits |
OPENROUTER_MANAGEMENT_KEY |
| Moonshot / Kimi | GET {origin}/v1/users/me/balance |
pi-ai provider 的 apiKeyEnv（自动发现） |
| Z.ai / GLM | GET {origin}/api/paas/v4/balance |
ZAI_API_KEY |
没有公开余额接口的 provider 会显示明确状态，不会猜测数值。界面支持中英文。
安装与启用¶
前置条件：@deepseek-ai/dsh >= 0.1.0-rc.6，且使用 web profile。
下面命令来自插件 README 与 SkillHub 目录页：
dsh plugin --profile web add "github:Aisland-SJL/dsh-usage"
安装后重启 dsh web，在浏览器执行硬刷新，左下角应出现 dock。更新与卸载：
dsh plugin --profile web update dsh-usage
dsh plugin --profile web remove dsh-usage
典型用法¶
配置凭证¶
余额查询读取 ~/.dsh/.credentials.yaml 中的引用，按实际使用的 provider 填写：
DEEPSEEK_API_KEY: sk-your-key-here # 官方 DeepSeek 线路
OPENROUTER_MANAGEMENT_KEY: sk-or-v1-... # OpenRouter 账户（Management Key，非推理 key）
ZAI_API_KEY: your-zai-key # Z.ai 开放平台
Moonshot / Kimi 若在 llm-pi-ai 中已配置，会自动发现对应 apiKeyEnv。
面板操作¶
- 点击 dock 角落齿轮打开详情面板。
- 在 Balance 组件切换 provider，查看分项余额。
- 点击 ↻ 或等待后台刷新（启动时刷新一次，之后每 5 分钟）：余额、DSH token、Claude Code 聚合同步更新。
- 在 Usage log 点击某一天，下钻到 per-model 明细。
- 在定制器中调整强调色、背景、透明度，拖拽组件顺序并 pin 常用项。
HTTP API（仅供本机调试）¶
| 方法 | 路径 | 响应内容 |
|---|---|---|
GET |
/api/usage/providers |
provider 列表、余额 scheme、状态摘要 |
GET |
/api/usage/balance?provider=<id> |
统一余额快照；refresh=1 强制上游查询 |
GET |
/api/usage/usage |
按日 / 按模型 token 聚合、缓存命中率、24 小时桶（days[].hours）、Claude Code 通道（claude） |
非 GET 请求返回 405，非 loopback 调用返回 403。响应均为 JSON，Cache-Control: no-cache。请勿通过反向代理把这些端点暴露到局域网或公网。
适用场景与注意¶
适合人群：
- 长期开着
dsh web，需要随时看余额和今日 / 本月用量； - 同时使用 DSH 与 Claude Code，想对比两条通道的 token 占比；
- 在意隐私，希望用量在本地聚合、密钥不进入浏览器。
安装前注意：
- 插件以当前
dsh进程权限运行，安装前应自行检查源码与 MIT 许可证。 - Claude Code 聚合依赖本机
~/.claude/projects日志；无日志时对应通道显示为空或零，属预期行为。 - OpenRouter 余额需 Management Key，普通推理 key 无法查询 credits。
- SkillHub 为社区目录站点，与 DeepSeek / 幻方无官方从属关系；插件同样属于社区生态，遵循 DSH「一切皆插件」的扩展方式。
结尾¶
dsh-usage 把余额、token 用量、缓存命中、活动热力图和双通道对比收进 Web GUI 左下角，配置项与布局可本地持久化，凭证与上游查询留在服务端边界内。若你已在用 DSH web profile，可按上文命令安装，重启后硬刷新即可验证。
- SkillHub 目录：https://www.skillhub.cn/plugins/Aisland-SJL/dsh-usage
- GitHub 仓库：https://github.com/Aisland-SJL/dsh-usage
