前言¶
做 DSH 插件时，常见一类需求：我想知道本机每个会话每天烧了多少 token，顺便看看 DeepSeek 账号还剩多少余额。这类数据散落在本地的会话日志里，通常得开终端翻文件、写脚本，才能拼出一张按天的汇总。
dsh-usage-monitor 就是针对这个痛点：它不替代任何统计命令，只把会话日志解析成按天的汇总，再叠加一个余额卡片。下面介绍它的功能、安装方式、数据流向和局限。
这是什么¶
- 维护者：Alvin-Sun6612
- 仓库：https://github.com/Alvin-Sun6612/dsh-usage-monitor
- 目录页：https://www.skillhub.cn/plugins/Alvin-Sun6612/dsh-usage-monitor
- 定位：DSH（DeepSeek Harness）客户端插件，在侧边栏开一个「用量与余额」面板
它解决两件事：
- 按天统计本机会话的 token 用量，分今日、近 7 天、近 30 天、累计四个窗口。
- 显示 DeepSeek 账号余额，但需要你自己在面板里粘贴 API Key。
核心功能¶
下面是 README 中已核实的能力，逐条列出。
- 用量窗口：今日 / 近 7 天 / 近 30 天 / 累计，每个窗口给 token 总量、调用次数、缓存命中率。
- 今日明细：未缓存输入、缓存命中、输出。
- 近 30 天柱状图，悬停可看当天数值。
- 余额卡片：需要 DeepSeek API Key，在面板里粘贴即可，Key 存在本机。
- 面板名与描述提供中英两份 locale。
关于余额，README 明确写了一点容易踩坑的约束：余额接口 /user/balance 只认 API Key（sk-...）。如果只在 DSH 里登录了 DeepSeek 账号、没有 Key，面板会显示「未配置 API Key」。用量统计本身不需要 Key。
安装与启用¶
README 给了三条安装路径，按场景选。安装命令照抄自 README，没有自行拼接。
方式一：本机目录（开发用）¶
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
# 或指定 profile：-Profile web
装完需要重启 DSH，侧边栏才会出现「用量与余额」。这条路径假设你已经把仓库拉到本地，适合改源码的阶段。
方式二：安装 Release 里的 tgz¶
这是 README 标注的推荐路径，不需要 git、也不需要 npm：
# 直接装 Release 附件（推荐）
dsh plugin --profile desktop add "https://github.com/Alvin-Sun6612/dsh-usage-monitor/releases/download/v0.1.0/dsh-usage-monitor-0.1.0.tgz"
# 手上有 tgz 文件时
dsh plugin --profile desktop add .\dsh-usage-monitor-0.1.0.tgz
# 仓库装了 git 时也可以用 GitHub 直装（pnpm 会走 git，需 allowBuilds 授权）
dsh plugin --profile desktop add github:Alvin-Sun6612/dsh-usage-monitor
装完同样要重启 DSH。卸载命令：
dsh plugin --profile desktop remove dsh-usage-monitor
注意这里的 profile 固定为 desktop。如果你装完看不到入口，README 让检查 ~/.dsh/profiles/desktop/package.json 的 dsh.profile.bundles 是否包含 dsh-usage-monitor。
它读什么、发什么¶
这部分决定你愿意在多大范围内信任它。README 给了一张表，下面照录重点。
| 项目 | 说明 |
|---|---|
| 数据来源 | ~/.dsh/sessions/<工作区>/<会话>/*.jsonl.zstd，只读 |
| 解析内容 | assistant/message 事件的 usage（inputTokens / cacheReadTokens / cacheWriteTokens / outputTokens）与事件时间 |
| 本地服务 | 127.0.0.1:46850 起只读 HTTP 服务，CORS 只放行 localhost |
| 联网 | 只有配置了 API Key 后，才请求 https://api.deepseek.com/user/balance；用量统计完全离线 |
| Key 存放 | ~/.dsh/dsh-usage-monitor.json（权限 0600），面板不回显、不记录 |
| 缓存 | 会话文件按 (mtime, size) 缓存解析结果；余额结果缓存 60 秒 |
端口被占用时，可以在面板底部改端口（浏览器端记住设置），也可以直接在 ~/.dsh/dsh-usage-monitor.json 里写：
{"port": 46851}
典型用法¶
不必起 DSH，直接验证 Host 半¶
README 提供一条独立自测路径。index.js 是 Host 半，负责解析 zstd 日志、代理余额、起本地 HTTP 服务；它不依赖 DSH 运行时，可以直接跑起来：
node index.js
# http://127.0.0.1:46850/health
# http://127.0.0.1:46850/summary?days=30
# http://127.0.0.1:46850/balance
/health：服务是否存活。/summary?days=30：用量汇总。/balance：余额，未配 Key 时返回未配置状态。
/summary 返回结构（README 节选）：
{
"sessions": 22, "scanned": 22, "parsed": 22, "scanMs": 465,
"today": { "requests": 525, "totalTokens": 43301332, "cacheHitRate": 0.982 },
"last7": { "...": "同上结构" },
"last30": { "...": "同上结构" },
"allTime":{ "...": "同上结构" },
"series": [{ "date": "2026-11-05", "totalTokens": 43301332 }]
}
浏览器半契约测试¶
修改面板逻辑后，README 建议跑一遍 19 项契约测试，覆盖浏览器半的渲染与交互：
node test/smoke.mjs
版本与发布¶
package.json 里的 version 是 0.1.0，license 是 MIT。README 还给了几条发布路径，这里只提醒两点：npm publish 前要 npm login，且 package.json 里得有 repository；直接发 tgz 则用 pnpm pack，产出 dsh-usage-monitor-0.1.0.tgz。
目录结构¶
dsh-usage-monitor/
├─ package.json # dsh.bundle + dsh.client 声明，exports 四项
├─ cordis.patch.yml # 组合包补丁：insert id=usage-monitor
├─ index.js # Host 半：解析 zstd 会话日志 + 余额代理 + 本地 HTTP 服务
├─ client.js # 浏览器半：侧边栏面板（无构建，React.createElement）
├─ locale/{zh,en}.json # 面板名与描述
├─ icon.svg / icon.png # 图标
├─ install.ps1 # 一键安装（UTF-8 BOM）
└─ test/smoke.mjs # 契约测试：node test/smoke.mjs
两部分是分离的：index.js 跑在本机进程里，client.js 跑在浏览器侧边栏，中间靠 127.0.0.1:46850 的本地只读 HTTP 服务连通。想改造功能时，client.js 是面板侧，index.js 是数据侧。
自定义与上架¶
如果你想改名或换成自己的功能，README 给了四步：改 package.json（保留 dsh.bundle.patch）；cordis.patch.yml 的 id 与 name 与包名对齐；client.js 里的 NS、PANEL_ID、PORT_KEY 和 CSS 前缀 dsh-um-* 建议一起换，避免与别的插件冲突；locale/*.json 的 meta.title / meta.description 就是市场卡片文案。
上架 DSH 插件市场（dshmarket）时，README 结论很明确：不要给 dsh-market 仓库提 PR，也不要手改 README / plugins.json / index.json，它们由 CI 生成。唯一动作是往 https://github.com/awesome-dsh-plugin/awesome-dsh-plugin 提交一个新文件 data/plugins/Alvin-Sun6612__dsh-usage-monitor.yml，条目用 category: usage。本插件的市场条目已经准备好，位于仓库内的 data/plugins/Alvin-Sun6612__dsh-usage-monitor.yml。
前置条件之一是把目录内容推到你自己的 GitHub 仓库根目录，仓库创建满 1 天，加 dsh-plugin topic。合并后市场自动重建，通常一天内可搜到。
常见问题¶
下面几条是 README 已列的故障与处理，挑了最常见的四条。
| 现象 | 原因 / 处理 |
|---|---|
| 面板提示「读不到本地服务的数据」 | 插件没随 DSH 重启加载，或 Host 半端口被占。重启 DSH；必要时在面板底部改端口。 |
| 余额一直是「未配置 API Key」 | 用的是账号登录而非 API Key。去 platform.deepseek.com 建 Key 粘贴进面板。 |
| 余额显示 HTTP 401 | Key 无效或已被删除；重新生成。 |
| 今日用量为 0，但确实在用 | 面板按本机时区分桶；刚产生的调用需要点「刷新」清缓存。 |
还有一条环境坑：PowerShell 5.1 读文件要加 -Encoding UTF8，.ps1 要存成 UTF-8 with BOM。
适用场景与注意¶
适合这些人和场景：
- 想按天、按窗口看本机 token 趋势，而不是只有单次调用的瞬时数字。
- 想顺手盯 DeepSeek 余额，不想开浏览器登控制台。
- 要做 DSH 插件、需要一个 Host 半 + 浏览器半的最小参考结构。
需要留意的点：
- 插件以当前 DSH 进程权限运行。安装前应读一遍源码与
LICENSE（MIT），确认它访问~/.dsh/sessions/和~/.dsh/dsh-usage-monitor.json的权限你能接受。 - 用量统计是本机范围，只覆盖
~/.dsh/sessions/下的会话日志；多机、多工作区的全局视图它不提供。 - 余额是插件转发的
api.deepseek.com/user/balance结果，Key 只存在本机、面板不回显。 - 本地服务默认端口固定为 46850，被占用时才需要改。
结尾¶
dsh-usage-monitor 的价值在于把「用量统计」和「余额」这两件运维级小事收进侧边栏，Host 半离线跑、浏览器半做展示，职责切得干净。目录页在 https://www.skillhub.cn/plugins/Alvin-Sun6612/dsh-usage-monitor ，源码在 https://github.com/Alvin-Sun6612/dsh-usage-monitor 。
