dsh-token-insight

它是什么

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 周热力图比屏幕宽，可左右滑动，并会自动定位到最近几周。

功能一览

快速开始

一键安装（推荐）

git clone https://github.com/daniei-chen/dsh-token-insight.git
cd dsh-token-insight
node scripts/install.mjs --profile desktop
# 完整重启 DSH（关闭应用再打开）

脚本会：

1. 把 dsh-token-insight 写入 ~/.dsh/profiles/desktop/package.json
2. 加入 dsh.profile.bundles
3. 在 profile 的 node_modules 下建立指向本仓库的 junction / symlink

安装完成后，打开 设置 → 使用统计。

{
  "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_HOME 默认是 ~/.dsh；如果自定义了，安装脚本和插件都会读取它。

界面导览

对应上面的截图，从上到下：

1. 总览卡：累计 / 峰值 / 最长聊天 / 当前连续 / 最长连续，全部时间口径
2. Token 活动：52 周热力图，可切换每日 / 每周 / 累计
3. 时间范围：默认近 7 日，可切近 30 日 / 全部；选中按钮描边加深
4. 每日 Token 趋势图：按模型分色，图例可点击隐藏
5. 模型用量：环形图 + 明细列表；点击只看某个模型，点「显示全部」恢复
6. 会话用量：随全局范围切换；默认 Top 5，点「查看全部」后按 10 条/页翻页
7. 刷新：手动重新读取本地统计，点击后图标旋转并显示「正在读取…」
8. 页面底部：数据覆盖（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，只读这些文件。

数据来源与隐私

• 不发起网络请求
• 不上传会话内容
• 不需要账号、API key 或云端服务
• 统计结果只在本机 DSH 页面内渲染

数据口径

手机 App

手机端是独立项目：DeepSeek-Harness-APP。

插件不需要装到手机上。 手机 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

常见问题

更新

cd dsh-token-insight
git pull
node scripts/install.mjs --profile desktop
# 完整重启 DSH

卸载

1. 从 ~/.dsh/profiles/desktop/package.json 删除 dsh-token-insight（dependencies 和 dsh.profile.bundles 都要删）
2. 删除 ~/.dsh/profiles/desktop/node_modules/dsh-token-insight
3. 重启 DSH
4. 可选：删除缓存 ~/.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

• 0.5.0：全部范围、数据覆盖、缓存命中、会话 Top 5、导出、预算、SQLite 缓存
• 0.5.1：tooltip 挂 body，兼容 Catppuccin glass 等会 transform 弹窗的主题
• 0.5.2：移除导出和日预算，保留刷新，界面更专注
• 0.5.3：版本提示移到底部，加载文案改为几分钟，刷新静默处理
• 0.5.4：数据覆盖和今日/本周信息移到底部，加载态改为居中的「正在统计模型使用」
• 0.5.5：刷新按钮增加旋转加载态，加载文案上移到视觉中心
• 0.5.6：会话排行按范围统计，支持「查看全部」和 10 条/页翻页
• 0.5.7：内存缓存合并结果，无变化时热请求约 35ms；预热提前到 2s
• 0.5.8：整页刷新、失败重试、会话 token 构成、计费来源、无记录天数、图例记忆、跨日测试
• 0.5.9：默认近 7 日；加载态改为圆圈 +「加载中」；热力图、趋势图、时间范围、模型图例选中高亮
• 0.5.10：选中态统一为蓝色；模型用量改为聚焦查看；修复热更新后加载圈不显示
• 0.5.12：打开先用 localStorage 上次结果，后台更新，缓存跨重启保留
• 0.5.13：移除热力图 / 趋势图 / 环图的原生 title，只保留统一 tooltip
• 0.6：真实成本账本（按模型单价、缓存节省）
• 0.6：会话下钻（点击 Top 5 / 峰值日期看明细）
• 0.6：今日常驻小部件（侧边栏 / 桌宠气泡）
• 0.7：7 日/30 日环比、周报长图
• 0.7：多设备 / 多 profile 汇总
• 0.8：TypeScript + 构建、worker 扫描、E2E 测试

相关文档

• AI 安装指南
• CI / 验证
• npm 发布
• CHANGELOG

License

MIT