lurejewel/dsh-usage-plugin

dsh-usage-plugin

npm version npm downloads License: MIT

一个用于 DeepSeek Harness Web 的原生侧边栏用量面板：直接在侧边栏中显示你的官方 DeepSeek 余额和token 用量历史（今天 / 最近 7 天），无需独立进程，也没有跨域调用。

左侧边栏底部、设置上方会出现一个触发按钮——侧边栏展开时为带标签的全宽按钮，折叠时为紧凑图标。点击它即可打开面板：实时余额、今天的输入 / 输出 / 缓存 token，以及根据你自己的会话日志计算出的 7 天趋势。

功能特性

- 官方余额——使用 DSH 已有的 API key（来自你的凭据中的 DEEPSEEK_API_KEY）实时查询 api.deepseek.com/user/balance，绝不存储在浏览器中。
- Token 用量历史——读取你的 $DSH_HOME/sessions 日志，并按天汇总输入 / 输出 / 缓存 token（今天、总计、日均值、缓存命中率）。
- 侧边栏集成——注册一个 sidebar.footer.action 触发器和 shell.overlay 模态框；布局遵循 DSH 设计令牌（包含浅色 / 深色主题）。
- 零足迹——无守护进程、无配置、无数据库；数据来自你已经在运行的同一个 DSH 安装。

要求

| 要求 | 版本 |
|---|---|
| DeepSeek Harness | >= 0.1.0-rc.7（已在 0.1.5-rc.2 上验证） |
| Node.js | >= 20 |
| pnpm | >= 10（用于 dsh plugin 安装） |
| API key | 一个现有的 DEEPSEEK_API_KEY 凭据（DSH 已经在使用的那个） |

安装

在任意位置运行：

dsh plugin --profile web add dsh-usage-plugin

就这样——该包声明了一个 dsh.bundle 补丁，因此 dsh plugin 会自动将其挂载到 profile 层栈中。然后：

1. 重启 dsh web（停止并启动该进程）。加载器树在启动时只组合一次，因此安装到正在运行的服务器中的插件在此之前不会被加载。
2. 强制刷新浏览器（Cmd/Ctrl+Shift+R）。
3. 在左侧边栏底部找到用量图标。

验证安装

GET /api/dsh-usage/balance 和 GET /api/dsh-usage/stats?days=N 与 DSH 其余 /api（dsh >= 0.1.5）一样位于同一个进程令牌防护之后，因此直接 curl 会得到 401 unauthorized。请使用浏览器页面，或传入 dsh web 在启动时打印的令牌：

dsh web: http://127.0.0.1:3080/?token=XXXXXXXX
node scripts/verify-install.mjs 3080 XXXXXXXX

验证器随包一起发布，因此 npm 安装后可以从 ~/.dsh/profiles/web/node_modules/dsh-usage-plugin 运行它。

其他方式

- 从 GitHub 安装：dsh plugin --profile web add github:lurejewel/dsh-usage-plugin
- 从发布 tarball 安装：dsh plugin --profile web add https://github.com/lurejewel/dsh-usage-plugin/archive/refs/tags/v0.1.3.tar.gz
- 从本地检出安装（开发）：在此仓库内运行同一命令。给路径加引号：dsh plugin 会通过 shell 将其参数转发给 pnpm 而不加引号，因此包含空格的未加引号路径会被拆分成多个包规格——D:\Software\DeepSeek Harness\dsh-usage-plugin 会变成 link:D:/Software/DeepSeek 外加一个幽灵依赖 Harness\dsh-usage-plugin，并且该插件会从 dsh.profile.bundles 中被丢弃：

dsh plugin --profile web add '"D:\Software\DeepSeek Harness\dsh-usage-plugin"'

scripts/install-local.ps1 正是这样做的。

- 在较旧环境上手动挂载：将下面这一行添加到 ~/.dsh/profiles/web/cordis.patch.yml，然后重启：

- insert:
- id: dsh-usage-plugin
name: dsh-usage-plugin

卸载

dsh plugin --profile web remove dsh-usage-plugin

然后重启 dsh web。

工作原理

一个包，两半，作为普通 Cordis 插件挂载：

lib/index.js          宿主半：DSH Web 服务器上的同源 HTTP 路由
lib/client.js         浏览器半：提供给 Web GUI 的 __ModuleLoader__ 包
lib/usage-history.js  会话日志读取器（zstd 帧扫描 + 每步去重 + 按日聚合）

- GET /api/dsh-usage/balance — 实时官方余额（服务端调用，密钥从不离开服务器）。
- GET /api/dsh-usage/stats?days=N — 余额 + 使用历史；N 默认为 7，限制在 1–90 之间。

值得了解的实现说明：

- DSH 会话日志（session..jsonl.zstd）是多个串联的 zstd 帧（每个持久化批次一帧）；读取器逐帧扫描，而不是假定只有单帧。一个损坏的帧只会损失它自己的行。
- 会话产物是带版本号的格式代际——session.jsonl.zstd 是已发布的 v0 根文件，session.vN.jsonl.zstd 是更晚的一代，而 DSH 始终写入并读取会话目录中存在的最高代际。因此，读取器会为每个会话选择最高的规范代际（绝不只读普通的 v0 文件，也绝不每个会话读取超过一个文件）：较低代际会在该会话的迁移点停止，而读取其中两个会导致重复计数。
- assistant/message 和 assistant/chunk 事件会为相同的 (turn, step) 报告相同的用量数字；读取器按 (turn, step) 去重，因此总数不会被重复计数。
- API 密钥通过 DSH 的 credentials 服务解析——与 DeepSeek 提供程序使用的来源相同。浏览器中不存储任何内容；所有调用均为同源。
- 两条路由都继承 DSH 的浏览器信任围栏，并且在 dsh >= 0.1.5 上，客户端包作为 shell 的单个组合 /plugins/??… 请求的一部分交付，而不是按包 URL 交付。两者都不会改变浏览器半：它在已认证的页面内运行。

隐私与安全
- 余额调用从你的服务器发往 api.deepseek.com；API 密钥绝不会进入浏览器。
- 该面板只读取 $DSH_HOME/sessions 下你自己的会话日志。
- 无遥测，无第三方网络调用。

开发

npm test                       # 单元测试（帧扫描 / 解码 / 去重 / 30 天窗口）
npm run test:client-boot       # 在 Node 中针对 mock slots 启动真实客户端 bundle
npm run test:standalone        # 进程内 E2E：真实 cordis + 真实 API + 真实日志
（需要本地安装 DSH，且 @deepseek-ai 包
可在 $DSH_HOME/profiles/node_modules 访问，
需要 DEEPSEEK_API_KEY 凭据，以及会话日志）
npm run verify -- 3080  # 重启后针对运行中的 dsh web 进行检查

lib/ 是发布产物，同时也兼作可读源码（纯 ESM，带文档）。

Windows 辅助脚本（可选）

- scripts/install-local.ps1 — 一键本地安装，以 link: 指向本仓库（为 dsh plugin 的 shell 跳转对路径加引号）。
- scripts/restart-web.ps1 — 重启 dsh web，从服务器日志中读取带令牌的 URL，然后运行验证。
- scripts/verify-install.mjs — 重启后检查：令牌交换、stats/balance 路由、物化的客户端行、合并后的 bundle 内容。在 dsh >= 0.1.5 上需要  。

两个 .ps1 辅助脚本仅存在于 git 检出中；verify-install.mjs 也会发布在 npm 包中。

许可证

MIT