dsh-plugin-token-report

在 DeepSeek Harness（DSH）里直接查看本机 token 用量：输入框摘要、趋势图、模型排行和自定义日期范围；需要团队汇总时，再配置身份与上报连接。

npm 包名：dsh-plugin-token-report · 仓内开发包名：@ai-token-report/dsh-plugin

实际使用截图

以下截图来自 2026-09-25 本机运行的 DSH Web 与真实会话日志，仅截取插件区域。数值是该机器当时的用量，不是模拟数据，也不代表性能基准。

用量概览与模型明细

点击输入框上方 TOKEN 用量 条里的「详情」，即可查看计费总量、未缓存输入、输出、缓存读、缓存命中率、调用数和会话数。趋势支持切换 Token 总量、调用数与命中率，明细支持模型、服务商、项目和会话分组，点击行可展开，超过 10 行可翻页。

自定义日期范围

除了今天、昨天、本周、最近 7 天、本月、近 30 天和今年，还可以通过双月日历选择开始与结束日期。开始与结束日期既可以点日历选，也可以直接敲进输入框（2026-09-21、2026/9/21、2026年9月21日 都认，失焦后统一成 2026-09-21）；格式不对、日期不存在或开始晚于结束时，标题右侧会说明原因，「应用范围」只在区间可用时才可点。范围按本地时区计算，包含起止两天，点击「应用范围」后更新统计；生效期间按钮上直接显示所选区间（如 09-12 – 10-06）。

安装最新稳定版

需要已经安装 DSH，并使用与插件兼容的宿主模块（@deepseek-ai/cordis ^4.0.2、@deepseek-ai/dsh-session-telemetry ^0.1.5-rc.1）。Node.js 要求 22.15.0 或更新版本。

dsh plugin --profile web add dsh-plugin-token-report@latest

dsh plugin add 会自动在 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles 中登记发布包。检查它只出现一次，且没有旧源码包 @ai-token-report/dsh-plugin；不要再手动 insert 插件。正常列表例如：

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-plugin-token-report"
      ]
    }
  }
}

在该 profile 的 cordis.patch.yml 中合并以下条目：

# 同一时间只能有一个 sessionTelemetry 后端。
- id: session-telemetry-otel
  disabled: true

随后重启 DSH，用终端打印的完整地址打开浏览器：

dsh --profile web --no-open

选择工作区后，输入框上方会出现用量条（0.3.0 起这是默认位置）。想让面板改到会话标题栏右上角、或两个位置都要，见上方「调整面板位置」。安装后无需单独启动本地统计网页。

dsh plugin 内部调用宿主自己的包管理器。上面的安装命令用于 DSH profile；本仓开发、构建与发布使用 Bun。

第一次使用

1. 打开「详情」，选择需要查看的周期。首次建立索引可能需要十几秒，后续只增量读取变化的日志。
2. 切换趋势指标或明细分组查看用量来源。图表下方「查看图表数据」提供精确值。
3. 手动点击刷新即可读取最新数据；页面每 3 秒问一次「有没有新数」（没有就零成本）， 有新采集时按宿主缓存节奏（最多 30 秒）自动更新；切回前台标签页会立刻取一次。

仅查看本机统计不需要署名。未署名时，插件不采集上报事件，也不上报。 页面读取的是 DSH 已有的本机会话日志。

调整面板位置

面板默认出现在输入框上方。想让它出现在会话标题栏右上角、或两个位置都要，在 profile 的 cordis.patch.yml 里给插件加一段 ui：

- id: token-report
  config:
    ui:
      position: dock      # dock(默认，输入框上方) | header(右上角) | both(两处都要)

取值	效果
dock	只显示输入框上方的用量条（默认）
header	只显示标题栏右上角的胶囊；点开就是同一个详情面板
both	两处都显示 —— 与 0.2.0 的外观一致

改完刷新页面即可生效（位置在页面加载时确定）。三种取值共用同一个详情面板，数字口径完全一致。 也可以不改 YAML，用环境变量 DSH_TOKEN_REPORT_UI_POSITION 临时覆盖。

写错的值不会让面板消失：只认上面三个值，其它一律回退 dock，并在 DSH 启动日志里告警。

开启团队上报

在详情面板右上角点击齿轮「配置」，填写管理员提供的姓名、身份 Key 和完整上报地址，例如 https://portal.example.com/api/v1/token-usage。如果团队使用独立 appKey，也可以一并填写；留空使用本次身份 Key。

点击「验证并保存」后，插件先向对应服务端校验身份，姓名与部门以服务端返回值为准。保存后重启 DSH，新的署名与连接才会用于上报。已保存的 Key 不回显。

身份与连接保存在 $DSH_HOME/token-report/ 下；默认 DSH_HOME 为 ~/.dsh。插件与本地 Web 共用身份文件。部署侧固定了身份时，页面会提示配置由管理员管理。

让 Agent 查询

可以在 DSH 会话里要求：

调用 token_usage，查看我今天的 token 用量，按模型分组。
调用 token_usage，查看最近 7 天的用量，按天显示趋势。
调用 token_usage_diagnostics，检查上报是否成功、是否有待发送数据。

工具注册需要宿主提供对应能力并启用 features.tools。查询工具只读本机日志，本身不产生上报。

功能说明

能力	使用方式
界面统计	用量条与标题栏入口（挂哪几个由 ui.position 决定，默认只挂输入框上方），共用详情面板
时间分析	预设周期、双月日历、自定义范围、趋势切换
明细分析	模型 / 服务商 / 项目 / 会话分组，展开与分页
本地增量查询	SQLite 增量索引；库不可用时自动回退日志扫描并提示
身份配置	面板内验证署名与上报连接，重启后生效
实时上报	异步批量发送、磁盘 outbox、失败保留、重启重放
Agent 与插件集成	token_usage、token_usage_diagnostics、ctx.tokenReport

只展示 token 数，不展示金额。只采集用量相关字段（包含模型名、工作目录、轮次等），不采集对话内容。上报失败不会阻塞 DSH 的会话循环；服务端按事件 ID 去重。

升级与常见问题

从旧版升级时，重新运行上方带 @latest 的安装命令即可安装最新稳定版。若曾源码直挂或手动 insert，先执行下方离线修复，再重启 DSH。

0.3.0 启动报 duplicate loader entry id: token-report

插件树里重复挂载了相同 ID，Loader 在插件代码执行前就会失败。仅升级 JS 文件不能清理旧 profile。0.3.1 随包提供离线修复工具；先停止该 profile 的 DSH，再在 Windows PowerShell 运行：

node "$env:USERPROFILE/.dsh/profiles/web/node_modules/dsh-plugin-token-report/repair-profile.mjs" --profile web
node "$env:USERPROFILE/.dsh/profiles/web/node_modules/dsh-plugin-token-report/repair-profile.mjs" --profile web --apply

设置过 DSH_HOME 时，把上面的 USERPROFILE/.dsh 路径替换成实际 DSH_HOME。第一条只检查，需修复时退出码为 1；第二条先备份，再修改。工具去掉重复 bundle 和旧源码包依赖，把插件 insert 转成 ID 配置覆盖；保留其它插件、原配置与 !!js 表达式。YAML 注释在原文备份中保留。

终端会打印备份目录（$DSH_HOME/token-report/plugin-backups/repair-*）。遇到配置冲突、其它插件占用 ID，或全局 $DSH_HOME/cordis.patch.yml 仍重复插入时拒绝写入，需人工合并。不要删除整个 profile、身份文件、数据库或 outbox。修复后重新运行 dsh web。

尚未升级时，也可单独复制仓库构建出的 repair-profile.mjs 到故障电脑，用同样参数运行，无需启动 DSH。

0.2.0 → 0.3.0 的行为变更（唯一一处）：用量面板的默认位置改成 ui.position: dock —— 默认只出现输入框上方那条用量条， 会话标题栏右侧的胶囊不再默认出现。要保留 0.2.0 的外观（两处都有）， 在插件 config 里加 ui: { position: both }。 位置配错（写了别的值）不会让面板消失：一律回退 dock 并在启动日志里告警。

现象	处理
sessionTelemetry 已注册	确认官方 OTel 后端已禁用，且没有重复挂载插件
没有用量入口	确认安装在 web profile、bundle 数组包含发布包名，并已重启；features.ui 不能关闭
401 / 未通过宿主鉴权	使用本次 DSH 启动时打印的完整地址重新打开
首次统计较慢	等待首次索引完成；如显示降级，检查 SQLite 权限与宿主 Node 版本
团队看板没有数据	验证并保存身份与连接后重启，再调用 token_usage_diagnostics 查看原因
修改配置后仍使用旧身份	当前进程仍绑定启动时配置，需要重启 DSH

源码与开发文档见 GitHub 仓库。

单文件离线版（截图以 Base64 内嵌）：README.offline.md。