Anna-la/token-stat

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 下全部历史会话并增量累计。

使用

1. 设置页查看（推荐）：打开「设置 → 插件 → 可配置」，找到 Token 用量统计卡片，点击展开即显示：
   • 累计总量（输入 / 缓存读取 / 缓存写入 / 输出 / 总计，含占比）
   • 按模型明细表（请求数、各类 token）
   • 按日期（近 14 天）
   • 数据目录、扫描时间等元信息，并可点「重新扫描」。 卡片数据由插件自带的桥 /api/token-stat/stats 提供（仅回环地址可访问， 外部请求一律 403），每 15 秒自动刷新。
   • 「可视化」：点击弹出窗口内浮层面板（非全屏），3 张手写 SVG 图表 （零第三方依赖，主题与设置页一致，悬停显示精确数值）： ① 模型用量占比环形图（<1% 合并「其他」）；② 每日用量堆叠柱状图 （输入/缓存读/缓存写/输出，近 14 天 ↔ 全部可切换，清晰展示缓存命中占比）； ③ 模型用量横向排行（Top 10 + 其他）。数据直接复用上面的统计快照， 无需任何额外接口，随 15 秒自动刷新同步更新。
   • 「重新扫描」：从磁盘全量重新折叠，保留插件已有数据库——归档账本 （archive.json）不清空，已删除会话的用量保留，同一会话只会覆盖更新、 不会重复计数。
   • 「清空插件数据库」：将累计用量与归档全部置零，并把已有历史会话标记为 忽略——之后重新扫描/重启都不会再把它们自动导入（新会话正常统计）。 如需恢复历史统计：删除 ~/.dsh-token-stat/archive.json 后重启即可。
2. 更改数据保存目录：同一张卡片里的「数据保存目录」一栏：
   • 输入新目录 → 点「保存」：立即生效，并把旧的 report.md / report.json / archive.json 自动迁移到新目录（跨盘移动不支持时会在新目录重建）；
   • 点「恢复默认」：清空设置，回到默认数据目录（~/.dsh-token-stat）。 设置写入官方 settings 用户层（settings.yaml），重启后仍生效； 也可在 cordis.patch.yml 的 config.reportDir 预设。
3. 自动统计：插件加载后即直接扫描 <DSH_HOME>/sessions 磁盘会话日志 （不依赖会话服务就绪），覆盖所有项目——包括已关闭、已删除但日志仍在磁盘的 项目；此后实时监听 session/event 增量累计（含子 agent 会话）。 每个会话的用量会写入「归档账本」（archive.json，随报告目录存储）， 即使之后某个会话的文件被彻底删除，其最后已知用量也仍然计入总数。
4. 随时查询：在对话框里问"查一下 token 用量统计"，模型会调用本插件的 token_usage_stats 工具并返回报告文本。
5. 报告文件：默认写入 ~/.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