dsh-plugin-token-report

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

dsh-plugin-token-report

在 DeepSeek Harness（DSH） 里直接查看本机 token 用量：输入框上方一条用量条，点开就是趋势图、

模型排行与自定义日期范围；要往部门看板汇总时，再填「服务端地址 + appKey」开始上报。

不填就不发：未署名 / 未配 appKey 时，插件只读本机日志 —— 不采集上报事件，也不上报。

• 📊 界面用量面板 —— 输入框上方的用量条（0.3.0 起是默认位置）或会话标题栏右上角的胶囊，共用同一个详情面板
• 🧮 只展示真值 —— 计费总量 = 未缓存输入 + 输出 + 缓存读 + 缓存写；cacheRead 不是 input 的一部分
• 💰 费用（估算） —— 按本机单价快照现算；未计价的用量写「未计价」而不是 ¥0.00，金额绝不跨币种相加
• 🔗 多套 DSH 并集 —— 命令行版与 DSH Desktop 的会话日志一起统计；互为镜像的会话按 event_id 去重，只算一次
• 🔌 本机客户端全覆盖 —— DSH / Codex / Claude Code / Trae（国际版与国内版）/ WorkBuddy 缺省就一起统计、也一起上报；装了哪个就有哪个，不用配置
• 🔍 按来源筛选 —— 工具栏下拉默认「全部来源」（= 什么参数都不带，与以前逐字节相同）；想看「这些几乎全是 Codex 跑的」就选一个客户端，整块面板只算它
• 📤 实时上报 + 历史补报 —— 异步批量、磁盘 outbox、断网续传；服务端按事件 ID 去重，重复投递无害
• 🤖 Agent 可查询 —— token_usage / token_usage_diagnostics 工具，以及供其它插件调用的 ctx.tokenReport 服务
• 🔒 不采集对话内容 —— 只取 token 数值、模型名、工作目录与轮次等统计字段

快速开始

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

1. 重启 —— dsh --profile web --no-open，用终端打印的完整地址打开浏览器

2. 看用量 —— 选择工作区，输入框上方出现用量条。想汇总到部门看板，点面板右上角齿轮「配置」填服务端地址 + appKey，保存即生效，不必重启

不需要改任何 profile 配置：0.9.0 起本插件不再注册 sessionTelemetry 服务（那个名字由官方 OTel 后端占用），改为订阅宿主会话事件流 —— 因此与官方 session-telemetry-otel 可以同时开着，各记各的。桌面端（DSH Desktop）的安装见「在 DSH Desktop（桌面端）上安装」。

环境要求

项 · 要求

DSH 宿主 · 0.1.7-rc.2 或更高、0.3.0 之前（本插件已在 0.1.7-rc.2 与 0.2.0-rc.2 上实测启动）

宿主模块 · 与宿主同代（@deepseek-ai/cordis ~4.0.4）。插件只吃宿主的会话事件流（@deepseek-ai/dsh-session）—— 0.9.0 起不再依赖 @deepseek-ai/dsh-session-telemetry

Node.js · ≥ 22.15.0

profile · 需要 web profile（界面面板与 /api 数据通道在那里；headless profile 下只有上报与工具）

上面那个版本窗口是兼容窗口，不是精确版本：宿主启动时逐个 peer 判定，**任一不满足就跳过整个

bundle** —— 现象是「面板不见了 + 一条也不上报」，启动日志只有一行 skipping profile bundle …，

不是报错。排查看下方「升级与常见问题」的排查表。

实际使用截图

以下截图来自 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）。

安装最新稳定版

前置要求（宿主版本窗口、Node 版本）见上方「环境要求」。安装本身只有一条命令：

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

dsh plugin add 会自动在 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles 中登记发布包。检查它只出现一次，且没有 0.9.0 之前的旧仓内源码包名 @ai-token-report/dsh-plugin（那个名字现在只用于清理历史装机）；不要再手动 insert 插件。正常列表例如：

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

不需要额外改 cordis.patch.yml：0.9.0 起本插件不注册 sessionTelemetry 服务，所以官方 session-telemetry-otel 可以继续开着 —— 它只在你主动提交反馈时上传，本插件只看 token 数值与模型名。

⚠️ 0.8.x 及更早是互斥的：那一版把自己注册成第二个 telemetry 后端（cordis 同名服务只能注册一个），所以必须在同一个 cordis.patch.yml 里合并 - id: session-telemetry-otel 与 disabled: true，否则 DSH 启动会失败并只报一行

service "sessionTelemetry" has been registered at <OpenTelemetrySessionBackend>。

升级到 0.9.0 之后那一行可以删掉（留着也无害 —— 只是官方后端不再工作）。

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

dsh --profile web --no-open

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

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

在 DSH Desktop（桌面端）上安装

桌面端有两条装法，同一套装配结果：

1. 界面里装（推荐）：侧栏「插件」→「+ 添加插件」→ 填包名 → 「安装」→ 「立即启用」→ 重启 Desktop。

2. 命令行装：用 Desktop 自带的 dsh 与它自己的 pnpm 走一遍 dsh plugin --profile web add …（headless / 排障 / 界面装不上时用，见下方「命令行安装」）。

同一套步骤的交付版在仓库的 docs/桌面端安装交付清单.md（逐条命令 + 核对 + 回滚，

文件不在 npm 包里，所以这里只写路径）；本节是它的说明版。

界面安装（侧栏「插件」）

这个页面是 Desktop 随包的官方插件管理器 @deepseek-ai/dsh-client-ui-plugin-manager（本机 Desktop 里实测存在，版本 0.1.7-rc.2；

侧栏那个「插件」入口与「添加插件」按钮的文案都出自它）。别与社区市场 dshmarket 搞混 ——

本机 profile 里两者都装着，但后者的入口叫「插件市场」（另一条侧栏项 + 设置里一张卡片）。

管理器的完整行为以它自己的 README 为准 —— 下面是与装本插件相关的那几条，引号里的文案都是从它客户端产物里逐字核出来的。

步骤 · 说明

① 侧栏「插件」 · 页面顶部「官方」是随 Desktop 提供、默认关闭的组合包；「已安装」是当前 profile 持有的组合包。

② 点「添加插件」 · 对话框标题与按钮同名，输入框标签「包名或地址」，说明是「输入插件的包名、GitHub 仓库地址或本地目录路径」。我们要填的就是包名：dsh-plugin-token-report（要钉版本就写 dsh-plugin-token-report@1.0.0）。旁边「插件安装引导和示例」里的「包名」一栏写得很直白：「插件包名即 npm 包名……社区插件的 README 安装命令中 dsh plugin add 或 pnpm add 之后的部分」，不确定就点「填入示例」。

③ 「安装源」（可跳过） · 只决定这次去哪个 npm 源问：「默认安装源」／「npm 官方源」／「中国大陆镜像源」／「自定义地址」（私有源要登录就把凭据放在本机 ~/.npmrc）。选择只记在本浏览器的 localStorage 里；dsh plugin 命令走的是 Host 配置的注册表 —— 所以在界面里换过源，不影响命令行。

④ 点「安装」 · Host 先问清 spec 指向什么（pluginManager.inspect），再跑 pnpm。被拒时输入框下方给一句话，其中与本插件有关的那条是「这个包没有声明组合包，无法作为插件安装」—— 本包自 0.9.0 起带 cordis.patch.yml，不会撞上它（见下方第二个坑）。

⑤ 点「立即启用」 · 装完给一次启用机会：启用新组合包／直接关闭对话框（关闭 = 已安装但关闭，插件不会生效）。装完点它最省事。

⑥ 重启 DSH Desktop · 管理器自己就写着「更改将在下次启动生效」。重启后面板出现在输入框上方（默认位置）即装好。

升级与回退：界面里没有版本选择器，spec 就是输入框里那一行（@1.0.0 才是钉版本）——

官方管理器的 README 明写：profile 安装的插件通过卸载后重新安装来升级（安装后暂不支持自动更新）。

所以升级 = 「卸载」（会要求确认）→ 「添加插件」填新版 → 「立即启用」→ 重启；命令行 add 同 version 也换不了版本。

一次只能跑一个安装 spec。

装之前请看一眼对话框里那句安全提示（大意：插件在本机以你的权限运行，来源不明的插件可能损坏 DSH 或读取你的数据）——

这也是为什么本插件只从 npm 上那个固定包名安装，不推荐从第三方链接装同名包。

命令行安装（headless / 排障）

界面装不了（宿主没有受管 profile、pnpm 被拦、装完没生效要排障）时，用 Desktop 自带的 dsh 与它自己的 pnpm 走一遍。步骤 ①~⑥ 来自仓内实测记录（只在版本号上按本次发布改成 1.0.0）：

① 退出 DSH Desktop（要写 profile 与 node_modules）。

② 打开一个 PowerShell，把 home、宿主入口与 Desktop 自己的 pnpm 都指过去：

# 安装目录按实际替换（本机在 D:\Program

…(truncated)