它是什么
DSH Token Insight 是一个装在 DSH host 上的本地插件。安装后，DSH 的
设置 → 使用统计 会出现一个完整的使用面板：
- 数据只来自本机
~/.dsh，不联网、不上传、不需要账号或 API key
- 直接解析当前版本的
session.v4.jsonl.zstd，不是估算
- 增量扫描 + SQLite 缓存；内存命中时约 35ms，文件没变不会重复合并会话
- 明确标注数据覆盖范围，缺档时不会把“没记录”误看成“没使用”
给 AI / For AI agents： 先读
docs/INSTALL_FOR_AGENTS.md，里面有逐步命令、验收检查和排错。
手机 App 是另一个项目，见 手机 App。
界面截图
使用统计面板
桌面端截图（0.5.1）；0.5.2 起移除导出和日预算，0.5.3 把版本提示移到底部，0.5.4 把数据覆盖和今日/本周信息也移到底部，0.5.5 给刷新按钮加了旋转加载态并上移了加载文案，0.5.6 增加会话排行和翻页，0.5.7 加了内存缓存，0.5.8 统一整页刷新并补齐失败重试、token 构成和计费来源，0.5.9 默认近 7 日和选中高亮，0.5.10 选中改蓝色并支持模型聚焦，0.5.11/0.5.12 打开先用上次结果并后台更新，缓存跨重启保留，0.5.13 去掉重复的原生 tooltip。手机端 52 周热力图比屏幕宽，可左右滑动，并会自动定位到最近几周。
功能一览
| 模块 | 能力 |
|---|
| 5 个总览指标 | 累计 Token、峰值 Token、最长聊天时长、当前连续天数、最长连续天数 |
| 52 周热力图 | 每日 / 每周 / 累计三种模式；悬停显示日期、token、轮消息 |
| 每日趋势 | 默认近 7 日 / 近 30 日 / 全部；平滑曲线、面积渐变；点击某天固定高亮，再点取消 |
| 模型用量 | 环形图 + 明细列表；点击图例或环段只看该模型，点「显示全部」恢复 |
| 数据覆盖 | 实际起止日期；今日、本周、缓存命中率（页面底部） |
| 会话排行 | 跟随近 7 日 / 近 30 日 / 全部；默认 Top 5，点「查看全部」看完整排行，10 条/页可翻页；带缓存读 / 输出占比 |
| 历史计费 | 从旧 web-billing / cost-meter 补出部分费用，标注来源和覆盖天数 |
| 刷新 | 打开时先显示上次结果并后台更新；手动刷新一次更新整页；失败时轻量重试 |
| 主题适配 | 跟随 DSH 深色/浅色主题；手机端横向滚动 |
快速开始
一键安装（推荐）
git clone https://github.com/daniei-chen/dsh-token-insight.git
cd dsh-token-insight
node scripts/install.mjs --profile desktop
# 完整重启 DSH（关闭应用再打开）
脚本会：
- 把
dsh-token-insight 写入 ~/.dsh/profiles/desktop/package.json
- 加入
dsh.profile.bundles
- 在 profile 的
node_modules 下建立指向本仓库的 junction / symlink
安装完成后，打开 设置 → 使用统计。
没有脚本 / 不想克隆仓库？
GitHub Release 下载：
dsh-token-insight-0.5.13.tgz
在 DSH 插件管理器里选择这个 tgz，或解压到
~/.dsh/profiles/desktop/node_modules/dsh-token-insight。
手动改 profile：
{
"dependencies": {
"dsh-token-insight": "file:/absolute/path/to/dsh-token-insight"
},
"dsh": {
"profile": {
"bundles": ["...", "dsh-token-insight"]
}
}
}
# Windows
New-Item -ItemType Junction `
-Path "$HOME/.dsh/profiles/desktop/node_modules/dsh-token-insight" `
-Target "<absolute-path-to-dsh-token-insight>"
# macOS / Linux
ln -s "<absolute-path-to-dsh-token-insight>" \
"$HOME/.dsh/profiles/desktop/node_modules/dsh-token-insight"
安装流程
flowchart LR
A[git clone] --> B[node scripts/install.mjs]
B --> C[profile package.json]
B --> D[node_modules junction]
C --> E[完整重启 DSH]
D --> E
E --> F[设置 → 使用统计]
环境要求
| 项目 | 要求 |
|---|
| DSH | 0.2.1-rc.2 或更新 |
| Profile | desktop（默认） |
| DSH runtime Node | Node 24（插件使用内置 node:sqlite） |
| 手机 App | 可选，见 手机 App |
DSH_HOME 默认是 ~/.dsh；如果自定义了，安装脚本和插件都会读取它。
界面导览
对应上面的截图，从上到下：
- 总览卡：累计 / 峰值 / 最长聊天 / 当前连续 / 最长连续，全部时间口径
- Token 活动：52 周热力图，可切换每日 / 每周 / 累计
- 时间范围：默认近 7 日，可切近 30 日 / 全部；选中按钮描边加深
- 每日 Token 趋势图：按模型分色，图例可点击隐藏
- 模型用量：环形图 + 明细列表；点击只看某个模型，点「显示全部」恢复
- 会话用量：随全局范围切换；默认 Top 5，点「查看全部」后按 10 条/页翻页
- 刷新：手动重新读取本地统计，点击后图标旋转并显示「正在读取…」
- 页面底部：数据覆盖（
2026-08-13 ~ 2026-10-23 · 本地会话）、今日 / 本周 / 缓存命中 / 历史计费（含来源天数）、当前范围无记录天数；host 版本不一致提示也在这里
数据流
架构图
一句话：host 侧只读解析，client 侧只消费统计结果。
- 当前会话：
~/.dsh/sessions/**/session.v4.jsonl.zstd
- 旧版日汇总：
~/.dsh/storages/web-billing.json
- cost-meter 日汇总：
~/.dsh/storages/cost-meter/ledger.json
- 增量缓存：
~/.dsh/dsh-usage-stats/session-cache.sqlite
同一自然日如果 sessions 与旧 billing/ledger 都有记录，按 max() 合并，避免重复累加。
插件不写 sessions、不写 storages，只读这些文件。
数据来源与隐私
| 文件 | 用途 | 插件行为 |
|---|
~/.dsh/sessions/**/*.zstd | 当前版本会话记录、usage、turn 时长 | 只读 |
~/.dsh/storages/web-billing.json | 旧版本日汇总 | 只读，按天补全 |
~/.dsh/storages/cost-meter/ledger.json | cost-meter 日汇总 / 历史计费 | 只读，按天补全 |
~/.dsh/dsh-usage-stats/session-cache.sqlite | 增量缓存 | 读写 |
- 不发起网络请求
- 不上传会话内容
- 不需要账号、API key 或云端服务
- 统计结果只在本机 DSH 页面内渲染
数据口径
| 指标 | 计算方式 |
|---|
| 累计 Token | usage.totalTokens；旧消息缺失时用 input + cacheRead + output + reasoning + cacheCreation 补算 |
| 峰值 Token | 单日最大 Token 消耗 |
| 最长聊天时长 | 单个 turn（turn/start → turn/end）的最大跨度 |
| 当前/最长连续 | 有 Token 消耗的自然日连续段 |
| 缓存命中率 | cacheRead / (input + cacheRead) |
| 热力图 | 最近 52 周，周日起始；每日 / 每周 / 累计 |
| 历史计费 | 旧 billing 的 totals.cost 或 ledger 的日 cost 之和，标注“部分” |
手机 App
手机端是独立项目：DeepSeek-Harness-APP。
| 组件 | 装在哪 | 作用 |
|---|
dsh-token-insight（本仓库） | 运行 DSH 的电脑 | 提供 设置 → 使用统计 |
| DeepSeek-Harness-APP | 手机 + DSH host | Android WebView 壳、连接、通知、文件、Relay |
插件不需要装到手机上。 手机 App 只是显示 DSH Web UI；插件装在 host 后，手机打开
设置 → 使用统计 即可看到同一份数据。
App 的完整安装步骤见 app 仓库的
docs/INSTALL_FOR_AGENTS.md。
验证安装
# 1. 模块能解析
cd "$HOME/.dsh/profiles/desktop"
node -e "console.log(require.resolve('dsh-token-insight/client'))"
# 2. API 正常（端口换成 DSH Web GUI 端口）
curl "http://127.0.0.1:<port>/usage-stats/api?days=30"
# 3. 全部范围（0.5.2+ 新 host）
curl "http://127.0.0.1:<port>/usage-stats/api?days=all"
期望："ok": true，并包含 totalTokens、peakTokens、longestChat、models、
cacheHitRate、todayTokens、weekTokens、sessionsTop、sessionsRanking、coverage。
API
GET /usage-stats/api?days=7|30|all
| 字段 | 说明 |
|---|
version | host 版本 |
days | 7 / 30 / 0（全部） |
coverage | firstDay、lastDay、sources |
totalTokens / peakTokens | 累计 / 单日峰值 |
longestChat | 最长聊天时长（本地化字符串） |
currentStreak / longestStreak | 当前 / 最长连续天数 |
cacheHitRate | 缓存命中率（0–100） |
todayTokens / weekTokens | 今日 / 近 7 日 |
cost | { amount, currency, partial, source } 或 null |
dayList | [{ date, tokens }] |
dayModels | { date: { model: tokens } } |
models | [{ name, tokens, pct }] |
sessionsTop | 当前范围内前 5 个会话：[{ id, title, tokens, inputTokens, outputTokens, cacheReadTokens, duration }] |
sessionsRanking | 当前范围内完整会话排行，client 用于「查看全部」和分页 |
heatList | [{ date, tokens, calls }] |
常见问题
| 现象 | 处理 |
|---|
| 设置里同时出现「DSH 使用统计」和「使用统计」 | 旧包 @dsh-external/dsh-usage-stats 还在运行中的进程里；确认 profile 只剩 dsh-token-insight，完整重启 DSH |
| 插件列表还有旧「DSH 使用统计」 | 同上；删除旧 node_modules/@dsh-external/dsh-usage-stats 后重启 |
热力图显示 0 轮消息 | host 还是旧版；完整重启 DSH |
| 手机端热力图看起来是空的 | 数据在 52 周网格右侧；会自动滚到最近几周，也可以左右滑动 |
/usage-stats/api 404 | 插件没加载、profile 不对，或端口不是 DSH Web GUI 端口 |
Cannot find module 'node:sqlite' | DSH runtime Node 低于 22.5；升级到 Node 24 的 DSH |
| 没有数据 | 确认 ~/.dsh/sessions 有 .zstd；先在 DSH 里跑几个任务 |
全部 比 近 30 日 少 | 旧 host 把 days=all 当成 7 天；完整重启 DSH |
更新
cd dsh-token-insight
git pull
node scripts/install.mjs --profile desktop
# 完整重启 DSH
卸载
- 从
~/.dsh/profiles/desktop/package.json 删除 dsh-token-insight（dependencies 和
dsh.profile.bundles 都要删）
- 删除
~/.dsh/profiles/desktop/node_modules/dsh-token-insight
- 重启 DSH
- 可选：删除缓存
~/.dsh/dsh-usage-stats/session-cache.sqlite 和旧的
~/.dsh/dsh-usage-stats/session-cache.json
删除插件不会删除 ~/.dsh/sessions 或 ~/.dsh/storages。
开发与测试
node scripts/install.mjs --profile desktop # 安装/更新到 profile
node sync.mjs # 同步到已安装副本
npm run verify # 语法检查 + host 单测
npm pack # 重新打包
- host：
lib/index.js
- client：
lib/client.js
- 测试：
test/host.test.mjs
- 安装器：
scripts/install.mjs
修改 host 后需要完整重启 DSH；只刷新页面不够。
项目结构
dsh-token-insight/
├─ lib/
│ ├─ index.js # host：解析、缓存、聚合、API
│ └─ client.js # client：设置页 UI
├─ locale/
│ ├─ zh.json
│ └─ en.json
├─ scripts/
│ └─ install.mjs # profile 安装器
├─ test/
│ └─ host.test.mjs # 多帧 zstd / 统计口径测试
├─ docs/
│ ├─ INSTALL_FOR_AGENTS.md
│ ├─ CI.md
│ ├─ PUBLISH.md
│ ├─ banner.svg
│ ├─ architecture.svg
│ └─ screenshot.png
├─ cordis.patch.yml
├─ package.json
└─ README.md
Roadmap
相关文档
License
MIT
