dsh-token-stat
DeepSeek Harness 插件：统计使用 DSH 以来累计 token 用量，并按模型 / 日期区分明细；统计结果在设置页直接点击查看，数据保存目录可在设置页在线更改。
- 零运行时依赖（不 import 任何
@deepseek-ai/*，dsh plugin add 后无需构建、无需 allowBuilds 授权）
- 不修改任何会话数据，只读会话日志做折叠统计
- 数据来自会话日志中供应商上报的精确 usage（与官方
dsh-token-meter 同一数据源）
- 同一
(turn, step) 步内的重试/重复上报只计最后一次采样，不重复计数
- 数据隔离：报告默认写入
~/.dsh-token-stat（可用 $DSH_TOKEN_STAT_DATA_DIR 覆盖），
完全位于 DSH_HOME 之外 —— 官方对 profiles / storages / sessions
等目录的任何清理、重装都不会误删本插件的数据
安装（粘贴仓库地址即装）
本仓库根 package.json 声明了 dsh.bundle（补丁层 cordis.patch.yml）与
dsh.client（浏览器半面，设置页卡片）。因此在 DeepSeek Harness 里粘贴本仓库地址
即可安装，无需构建：
# 方式 1: CLI(把 <profile> 换成你的 profile,如 web)
dsh plugin --profile <profile> add https://github.com/Anna-la/token-stat
# 方式 2: 本地目录(开发调试)
dsh plugin --profile <profile> add ./path/to/token-stat
# 方式 3: 从插件市场(awesome-dsh-plugin 列表 / dsh.market)找到
# 「Token 用量统计」一键安装
安装后重启 DeepSeek Harness Desktop，插件即开始扫描 <DSH_HOME>/sessions
下全部历史会话并增量累计。
使用
- 设置页查看（推荐）：打开「设置 → 插件 → 可配置」，找到
Token 用量统计卡片，点击展开即显示：
- 累计总量（输入 / 缓存读取 / 缓存写入 / 输出 / 总计，含占比）
- 按模型明细表（请求数、各类 token）
- 按日期（近 14 天）
- 数据目录、扫描时间等元信息，并可点「重新扫描」。
卡片数据由插件自带的桥
/api/token-stat/stats 提供（仅回环地址可访问，
外部请求一律 403），每 15 秒自动刷新。
- 「可视化」：点击弹出窗口内浮层面板（非全屏），3 张手写 SVG 图表
（零第三方依赖，主题与设置页一致，悬停显示精确数值）：
① 模型用量占比环形图（<1% 合并「其他」）；② 每日用量堆叠柱状图
（输入/缓存读/缓存写/输出，近 14 天 ↔ 全部可切换，清晰展示缓存命中占比）；
③ 模型用量横向排行（Top 10 + 其他）。数据直接复用上面的统计快照，
无需任何额外接口，随 15 秒自动刷新同步更新。
- 「重新扫描」：从磁盘全量重新折叠，保留插件已有数据库——归档账本
（
archive.json）不清空，已删除会话的用量保留，同一会话只会覆盖更新、
不会重复计数。
- 「清空插件数据库」：将累计用量与归档全部置零，并把已有历史会话标记为
忽略——之后重新扫描/重启都不会再把它们自动导入（新会话正常统计）。
如需恢复历史统计：删除
~/.dsh-token-stat/archive.json 后重启即可。
- 更改数据保存目录：同一张卡片里的「数据保存目录」一栏：
- 输入新目录 → 点「保存」：立即生效，并把旧的
report.md / report.json /
archive.json 自动迁移到新目录（跨盘移动不支持时会在新目录重建）；
- 点「恢复默认」：清空设置，回到默认数据目录（
~/.dsh-token-stat）。
设置写入官方 settings 用户层（settings.yaml），重启后仍生效；
也可在 cordis.patch.yml 的 config.reportDir 预设。
- 自动统计：插件加载后即直接扫描
<DSH_HOME>/sessions 磁盘会话日志
（不依赖会话服务就绪），覆盖所有项目——包括已关闭、已删除但日志仍在磁盘的
项目；此后实时监听 session/event 增量累计（含子 agent 会话）。
每个会话的用量会写入「归档账本」（archive.json，随报告目录存储），
即使之后某个会话的文件被彻底删除，其最后已知用量也仍然计入总数。
- 随时查询：在对话框里问"查一下 token 用量统计"，模型会调用本插件的
token_usage_stats 工具并返回报告文本。
- 报告文件：默认写入
~/.dsh-token-stat\ 下的
report.md + report.json + archive.json（可在设置页卡片里随时改目录，
三个文件会一起迁移）。
配置（可选，均为默认值）
- insert:
- id: token-stat
name: token-stat
config:
enabled: true # 总开关
reportDir: '' # 报告目录,默认 ~/.dsh-token-stat(DSH_HOME 之外)
writeMd: true # 写 Markdown 报告 report.md
writeJson: true # 写 JSON 快照 report.json
debounceMs: 2000 # 实时事件落盘最小间隔
verbose: false # 详细日志
统计口径
会话日志（session log）中的持久事件：
assistant/message → message.source.{provider,model} 记录产出模型；
usage.{inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens} 记录
供应商上报的精确 token 数。- 同一
(turn, step) 内重试采样的 usage 互相替换（与 dsh-token-meter 的
tokenUsage 投影语义一致），避免重复计数。
- 会话来源：优先磁盘直扫
<DSH_HOME>/sessions/<项目>/<会话>/session*.zstd|jsonl
（全部历史，含已删除项目）；仅当磁盘无会话文件（如 SQLite 存储后端）时
才回退到 sessionPersistence 服务。
- 归档账本
archive.json：按会话 id 记录最后已知用量；当前磁盘/内存里已不存在的
会话（被彻底删除）仍会计入总数，且不会重复计数（同一 id 的更新覆盖旧值）。
- 绝大多数消息（99.5%+）都带 usage；个别缺失 usage 的消息只计条数不计 token。
- 模型归属：消息自带
source → 最近一次 request/context 路由 → unknown。
目录结构
token-stat/
├── package.json # 根清单:dsh.bundle(patch)+ dsh.client(platform=web)
├── cordis.patch.yml # bundle 补丁层:把 token-stat 挂进 loader
├── index.mjs # 插件核心(折叠/渲染/apply,零依赖)
├── lib/
│ ├── index.js # 服务端入口(薄壳,re-export index.mjs)
│ └── client.js # 浏览器半面:设置页「Token 用量统计」卡片
└── tools/ # 开发/自检脚本
├── install.mjs # 开发模式安装:junction + 维护 profile patch(幂等)
├── verify-load.mjs # 模拟 loader 解析链路 + 数据隔离 + 客户端元数据 + bundle 清单校验
├── replay-sessions.mjs # 离线全量回放(全部历史会话 → 报告 + 数据质量诊断)
├── test-fold.mjs # 折叠语义单元测试(8 组)
├── smoke-test.mjs # 插件加载冒烟测试(含 settings/webServer 桥、目录迁移)
├── publish-github.mjs # 用 gh REST 把本仓库发布到 GitHub(无需本地 git)
└── submit-list-pr.mjs # 向 awesome-dsh-plugin 列表仓库提交条目并开 PR(无需本地 git)
本地开发 / 自检
node tools/install.mjs # 开发模式安装(junction 直连源码,幂等;改代码无需重装)
node tools/verify-load.mjs # 校验 loader 解析链路 + 数据隔离 + 客户端 bundle
node tools/test-fold.mjs # 折叠语义单元测试
node tools/smoke-test.mjs # 插件加载冒烟测试(工具/settings namespace/桥/目录迁移)
node tools/replay-sessions.mjs # 离线回放真实日志(约几秒)
pnpm 注意：如果未来在 profile 里跑 pnpm install，它可能会清掉未登记于
profile package.json 的顶层目录（包括开发模式的 junction）。届时重跑
node tools/install.mjs 即可恢复。
说明：本插件只是"统计账本"，不改写任何会话/日志文件；卸载插件后不再累计，
历史报告文件仍在（默认 ~/.dsh-token-stat，不受官方目录管理影响）。
License
MIT
