前言¶

在 DeepSeek Harness（DSH）里跑任务时，Token 消耗分散在会话日志里，想看清累计用量、单日峰值、模型占比或连续使用天数，往往要自己翻文件或靠零散脚本。DSH Token Insight 是维护者 daniei-chen 发布的客户端类本地插件：数据只读本机 ~/.dsh，在 DSH 的「设置 → 使用统计」里提供完整面板，并附带面向 AI 的安装说明文档；可选配套的 Android 壳应用见独立仓库 DeepSeek-Harness-APP，插件本身装在运行 DSH 的 host 上即可。

下面介绍插件定位、能力、安装与验收方式。事实以 GitHub 仓库 README 为准；社区目录页：daniei-chen/dsh-token-insight。

这是什么¶

DSH Token Insight（dsh-token-insight，当前版本 0.5.0，MIT 许可证）是装在 DSH host 上的插件。host 侧只读解析会话与历史汇总，client 侧在设置页渲染统计结果；不写 sessions、不写 storages，增量结果缓存在 ~/.dsh/dsh-usage-stats/session-cache.sqlite。

一句话：Local-first token usage dashboard for DeepSeek Harness——累计/峰值 Token、连续天数、52 周热力图、每日趋势、模型用量、会话 Top 5、成本与导出，均来自本机数据，不联网、不上传、不需要账号或 API key。

环境要求¶

DSH_HOME 默认为 ~/.dsh；若自定义，安装脚本与插件都会读取该变量。

核心功能¶

README 中列出的面板模块如下，均基于解析当前版本的 session.v4.jsonl.zstd（非估算），并标注数据覆盖范围，避免把「没记录」误看成「没使用」。

数据流要点：当前会话来自 ~/.dsh/sessions/**/session.v4.jsonl.zstd；旧版日汇总 ~/.dsh/storages/web-billing.json；cost-meter ~/.dsh/storages/cost-meter/ledger.json。同一自然日若多处有记录，按 max() 合并，避免重复累加。

安装与启用¶

插件以当前 DSH 进程权限运行本机文件；安装前请自行查看仓库源码与 MIT 许可证。以下命令与路径来自官方 README，不要凭插件名拼接 dsh plugin add github:owner/repo。

方式一：Release 包（无需克隆仓库）¶

从 Release v0.5.0 下载 dsh-token-insight-0.5.0.tgz，在 DSH 插件管理器中选择该 tgz，或解压到：

~/.dsh/profiles/desktop/node_modules/dsh-token-insight

方式二：手动写入 profile¶

在 ~/.dsh/profiles/desktop/package.json 中增加依赖，并把包名加入 dsh.profile.bundles：

{
  "dependencies": {
    "dsh-token-insight": "file:/absolute/path/to/dsh-token-insight"
  },
  "dsh": {
    "profile": {
      "bundles": ["...", "dsh-token-insight"]
    }
  }
}

在 profile 的 node_modules 下建立指向插件目录的 junction 或符号链接。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"

若本地已有插件目录副本¶

在插件目录内执行安装脚本，会把依赖写入 profile 并建立 node_modules 链接：

node scripts/install.mjs --profile desktop

无论采用哪种方式，都需要完整重启 DSH（关闭应用再打开），然后在 设置 → 使用统计 打开面板。

面向 AI / 自动化安装时，可先读仓库内 docs/INSTALL_FOR_AGENTS.md，内含逐步命令、验收与排错。

验证安装¶

在 host 上可按 README 做三项检查（将 <port> 换成 DSH Web GUI 端口）：

cd "$HOME/.dsh/profiles/desktop"
node -e "console.log(require.resolve('dsh-token-insight/client'))"

curl "http://127.0.0.1:<port>/usage-stats/api?days=30"
curl "http://127.0.0.1:<port>/usage-stats/api?days=all"

期望响应中 "ok": true，并包含 totalTokens、peakTokens、longestChat、models、cacheHitRate、todayTokens、weekTokens、sessionsTop、coverage 等字段。

典型用法¶

在界面中查看¶

安装并重启后，自上而下依次为：总览卡、数据覆盖、今日/本周/缓存命中/历史计费、日预算、52 周热力图、时间范围切换、每日趋势、模型用量、会话 Top 5、导出与刷新。

HTTP API¶

其他本机工具可只读消费统计结果：

GET /usage-stats/api?days=7|30|all

常见返回字段包括：coverage（firstDay、lastDay、sources）、totalTokens / peakTokens、longestChat、currentStreak / longestStreak、cacheHitRate、todayTokens / weekTokens、cost、dayList、dayModels、models、sessionsTop、heatList 等。详见 README「API」一节。

与手机 App 的关系¶

DeepSeek-Harness-APP 是独立 Android 项目；插件不需要装到手机。App 通过 WebView 显示 DSH Web UI，host 装好插件后，手机端同样进入「设置 → 使用统计」即可看到同一份本机数据。

适用场景与注意¶

适合需要在 DSH 内长期跟踪 Token 用量、模型分布与会话成本的开发者：数据留在本机，适合对隐私和离线统计有要求的场景。

常见问题（摘自 README）：若设置里同时出现旧包「DSH 使用统计」与新「使用统计」，需确认 profile 只保留 dsh-token-insight 并完整重启；/usage-stats/api 返回 404 时检查插件是否加载、profile 与端口；Cannot find module 'node:sqlite' 表示 DSH 内置 Node 过低，需 Node 24 的 DSH；无数据时确认 ~/.dsh/sessions 下存在 .zstd 并在 DSH 中实际产生会话。

卸载时从 package.json 的 dependencies 与 dsh.profile.bundles 移除 dsh-token-insight，删除对应 node_modules 条目并重启；可选删除 ~/.dsh/dsh-usage-stats/session-cache.sqlite，不会删除原始会话。

结尾¶

DSH Token Insight 把本机会话与历史汇总整理成可读面板与 /usage-stats/api，适合作为 DSH 生态里「客户端 / 使用统计」类插件的参考实现。目录页：https://www.skillhub.cn/plugins/daniei-chen/dsh-token-insight；源码与文档：https://github.com/daniei-chen/dsh-token-insight。