前言¶
在 DeepSeek Harness（DSH）里跑多模型、多会话时，单条会话里的用量气泡只能看当前会话。若要回答「一共烧了多少」「哪个模型占大头」「近七天趋势如何」，只能自己翻 ~/.dsh/sessions 下的日志，或写脚本逐条解析 session.v4.jsonl.zstd。下面介绍的 dsh-token-usage 是社区插件，由 fuchen9 维护，在 Harness 侧边栏增加「Token 用量」面板，把本机全部已存会话的 token 消耗汇总起来，并按模型、提供商、会话类型、预设与时间窗口拆分；统计口径与 Harness 自带的 tokenUsage 投影一致，离线完成，运行时零第三方依赖。
这是什么¶
dsh-token-usage（npm 包名 @local/dsh-token-usage，当前版本 0.1.1，MIT 许可）面向已安装 DeepSeek Harness 桌面版或 dsh web 的用户。它不改动会话数据、不发任何出站请求，只只读本地会话日志并渲染统计页；在 SkillHub 目录中归类为 admin-security。
核心功能¶
装好后，侧边栏面板列表会出现「Token 用量」入口，点开是一整页统计，主要包括：
- 汇总：合计、输入、缓存命中、输出、请求数、会话数。
- 按模型：每个「提供商 + 模型」的请求数、各分项 token、合计、占比条、最近使用时间；模型分组以
message.source.provider与message.source.model为准，重复的provider/前缀会在与 provider 相容时自动剥掉，避免同一模型裂成两行。 - 维度对照：按会话类型（主会话 / 子会话）、按 agent preset、按提供商聚合。
- 时间窗口：全部、近 30 天、近 7 天、今天一键切换；另有按本地日历日的最近几天曲线、最近会话排行。
数据来源仅为 ~/.dsh/sessions/**/session.v4.jsonl.zstd。Host 半通过 sessionPersistence 枚举并增量读取（按会话 revision 判断变化）；进程内活跃会话走 sessions 的 snapshot。扫描时即按 YYYY-MM-DD 分桶，切换 range 只在内存合并，不重读磁盘。实测 README 中提到的规模（220+ 会话、8700+ 条用量事件）首次全量约 1–2 秒，之后请求可命中缓存。
界面使用 --dsw-alias-* 设计 token，跟随明暗主题；支持中文与 English。禁用插件后，路由与槽位通过 ctx.effect 撤销。
统计口径（与面板数字对齐）¶
- 总 token =
inputTokens + cacheReadTokens + cacheWriteTokens + outputTokens，并与事件自带的totalTokens取较大者。 - 请求数：带
usage的assistant/message事件条数；会话数：至少有一条用量事件的会话数。 - 多轮对话里缓存读取往往占多数，因此「输入」常远小于「合计」，属正常现象；事件里的
usage来自模型回报，与单会话用量气泡同源。
若本机有用量历史不足 30 天，「近 30 天」与「全部」数字相同是预期行为，可用「今天」或「近 7 天」对照验证窗口是否生效。
安装与启用¶
需要 DeepSeek Harness。本包是标准 bundle：package.json 的 dsh.bundle.patch 指向 cordis.patch.yml，其中插入 @local/dsh-token-usage。
方式一：插件管理器（推荐）¶
在 Harness 插件管理器中选择「安装 bundle / 本地目录」，指向本仓库克隆或解压后的绝对路径，然后重启 Harness。
方式二：手工装进某个 profile¶
# <profile> 换成你的 profile 名（桌面版是 desktop，CLI 通常是 default）
cd ~/.dsh/profiles/<profile>
# 备份 package.json / pnpm-lock.yaml
pnpm link /绝对路径/dsh-token-usage # 写入依赖 + 建 node_modules 软链接
然后把 "@local/dsh-token-usage" 追加到该 package.json 的 dsh.profile.bundles 数组里，重启 Harness。
桌面版注意：dsh plugin --profile desktop ... 会被拒绝（profile "desktop" is managed exclusively by the Electron application）；桌面版请用插件管理器或上述手工步骤。
方式三：从 GitHub 以 git 依赖安装¶
cd ~/.dsh/profiles/<profile>
pnpm add github:fuchen9/dsh-token-usage
# 同样别忘把 "@local/dsh-token-usage" 加进 dsh.profile.bundles
装完之后：修改 lib/index.js（Host 半）必须重启 Harness；只改 lib/client.js 时刷新页面（必要时 Ctrl+Shift+R）即可，客户端 bundle 支持 HMR。
典型用法¶
在界面中查看¶
- 安装并重启 Harness。
- 打开侧边栏，进入「Token 用量」。
- 在页顶切换 全部 / 近 30 天 / 近 7 天 / 今天，对照汇总卡片、按模型表格、按天曲线与最近会话列表。
HTTP API（同源 GET）¶
本机 Harness 提供只读接口，供自动化或调试；路由校验 loopback / 同源，非 GET/HEAD 返回 405。
GET /api/dsh-token-usage?range=all|30d|7d|today&refresh=1
refresh=1 强制重扫（有 1.5 秒节流），否则使用缓存。响应包含 totals、models、providers、agents、presets、daily、sessions 等字段，各数组有上限（例如 models ≤200、sessions ≤60），避免超大用量撑爆响应。具体 JSON 结构见仓库 README 的示例。
适用场景与注意¶
适合谁：需要在 DSH 内一眼看清本机历史 token 消耗、按模型与时间段做对照、且不希望数据离开本机的开发者或管理员。
权限与安全：插件以当前 DSH 进程权限读取会话目录；安装前应自行审阅 GitHub 源码 与 MIT 许可证。README 明确说明插件本身无出站请求；唯一与模型相关的网络行为来自 Harness 调用模型，而非本插件上报。
故障排查：若面板显示「无法读取用量索引」或数字全为 0，常见原因是 Host 半 export const inject 漏声明 webServer、sessionPersistence 或 sessions 之一，导致扫描被静默吞掉；可查看 Harness 日志中的 dsh-token-usage: scan failed: …。页面下半截无法滚动时，与 flex 布局守卫有关，仓库 scripts/harness-layout.mjs 用于验证此类问题。
DSH 生态理念是「一切皆插件」；SkillHub 目录页 是社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-token-usage 把分散在各会话日志里的用量收成一块离线面板，口径与 Harness 单会话展示一致，适合在本机做用量审计与模型占比分析。更多信息与更新日志见 GitHub 仓库；目录条目见 SkillHub。
- 目录页：https://www.skillhub.cn/plugins/fuchen9/dsh-token-usage
- GitHub：https://github.com/fuchen9/dsh-token-usage
