Token 用量图表 lugezuishuai/dsh-token-chart

dsh-token-chart

一个 DeepSeek Harness 插件：把本机会话的 Token 用量采集下来，以图表与统计的形式放回你正在用的界面里——会话抽屉、每日面板、可自由配置的图表形式。交互参考 DSH 产品自带的「用量」，数据口径与它一致（计费口径，含缓存重读）。

🚀 快速开始

dsh plugin --profile web add dsh-token-chart

安装的是发布时预构建好的产物（lib/ 已构建好），在你的机器上不执行任何构建脚本；用量数据全部留在本机，不上报任何遥测。装好之后怎么用见 使用指南。

📖 使用指南

三个入口

| 位置 | 入口 | 内容 |
| 左侧边栏 | 「Token 用量」菜单 | 今天 / 近 3 天 / 近 7 天 / 近 30 天：KPI 卡片 + 趋势图 + 分页表格 |
| 会话标题栏 | 「用量」小按钮（与 ⋯ 菜单同一行，常驻） | 右侧边栏抽屉：总 Token、输入/输出、缓存读取/写入、命中率、轮次、模型 + 逐轮趋势图 |
| 设置页 | 设置 →「Token 用量」 | 图表形式、展示指标、开关；标题行含插件版本与「更新版本」按钮 |

页面上会出现三个「用量」入口，它们彼此独立，各由不同的东西控制：

| 你看到的「Token 用量」 | 由什么控制 |
| 消息底部 / 输入框上方的「用量」胶囊 | 产品自身的组件；插件只拦截点击，把它改成打开本抽屉（开关：拦截产品用量按钮） |
| 会话标题栏右上角的小按钮 | 本插件注册在 conversation.session.header.utilities 的入口，常驻显示（不设开关） |
| 右侧边栏的标签页标题 | 本插件的 sidebar.right.pane.tab.title 座位，不受上面那个开关影响 |

图表形式与交互

图表形式有 7 种：柱状、折线、饼图、表格、多柱状、多折线、柱状折线组合，会话抽屉与每日面板可以分别配置。

- 缓存命中率叠加：柱状 / 折线 / 多柱状 / 多折线 / 组合图都可在右轴叠加一条命中率折线（默认开）。
- 范围选择条：坐标轴下方的 dataZoom，拖动两端或中间窗口即可只看某一段 x 范围（滚轮与触控板捏合同样生效）。缩放只改变可见窗口，不改统计口径——数据表、KPI 卡片与总量始终是完整区间的值。
- 分页数据表：默认每页 20 条，页大小用下拉切换（10 / 20 / 50），页码为数字按钮 + 省略号（1 … 4 5 [6] 7 8 … 50），整条分页栏常驻右下角。切换页大小或数据变化会回到第一页。

x 轴按视图区分，口径如下：

| 视图 | x 轴 | 一个点是什么 |
| 每日面板「今天」 | 时间 HH:mm（同分钟多轮自动补到 HH:mm:ss） | 一轮的用量 |
| 每日面板「近 3 / 7 / 30 天」 | 日期 | 一天 |
| 会话抽屉 | #轮次 | 会话内的一轮 |

配置

配置在设置 →「Token 用量」里改，落盘到 $DSH_HOME/storages/dsh-token-chart/prefs.json（默认 ~/.dsh/...）。

| 字段 | 类型 | 默认 | 说明 |
| sessionChart | 枚举 | multi-bar | 会话抽屉的图表形式 |
| dailyChart | 枚举 | multi-bar | 每日面板的图表形式 |
| sessionMetrics | 数组 | ["input","output","cache","total"] | 会话抽屉展示的指标 |
| dailyMetrics | 数组 | ["input","output","cache","total"] | 每日面板展示的指标 |
| showTable | 布尔 | true | 图表下方是否渲染数据表 |
| showCacheHitRate | 布尔 | true | 组合图是否叠加缓存命中率折线 |
| interceptUsageButton | 布尔 | true | 点击产品「用量」胶囊时打开本插件抽屉 |

枚举值：bar / line / pie / table / multi-bar / multi-line / bar-line；指标值：input / output / cache / total。非法值会被 normalizePrefs() 丢弃并回退到默认，不会让界面挂掉。

数据与口径

- 数据目录：$DSH_HOME/storages/dsh-token-chart/（默认 ~/.dsh/storages/dsh-token-chart/），usage.json 是用量库，prefs.json 是界面偏好。
- 只保留最近 30 个自然日，更早的轮次在每次落盘前滚动丢弃（超出窗口的会话会被整条移除）。
- 幂等采集：按 (轮次, 步骤, 重试世代) 存槽位，重放会话日志不重复计数；存储 schema 不符时丢弃并从日志重建。
- 会话总量取会话级折叠，而不是把逐轮数字相加；运行时还会与产品的 tokenUsage 投影交叉校验，不一致时抽屉里会显式提示。
- 口径提醒：这里的「总 Token」是计费口径——每次请求的上下文（含缓存重读）都计入，所以一个约 1.5M 上下文的会话跑 350 步会得到约 150M；它不是「上下文大小」。
- 网络：唯一的出网行为是版本检查（profile 的 .npmrc registry，缺省 https://registry.npmmirror.com/，宿主侧缓存 30 分钟、超时 12 秒）；用量数据只写本机。

进阶：用 HTTP API 读写

宿主半边在 Harness 的 web server 上提供这些路由（/token-chart/api 前缀），脚本与外部工具可以直接用：
| 方法 | 路径 | 说明 |
| GET | /token-chart/api/health | 采集器状态（保留天数、已跟踪会话数、偏好是否加载、回填是否完成） |
| GET | /token-chart/api/prefs | 读取配置（含默认值） |
| POST | /token-chart/api/prefs | 保存配置补丁 |
| GET | /token-chart/api/overview?range=today\|3d\|7d\|30d | 区间统计（按天分桶 + 今天逐轮明细；未知区间回退到 today） |
| GET | /token-chart/api/session?sessionId=… | 单会话逐轮用量 |
| GET | /token-chart/api/version | 插件版本、registry 最新版与更新状态 |
| POST | /token-chart/api/update | 触发一次版本更新 |
| POST | /token-chart/api/reset | 清空本地用量库 |

改配置（补丁式，只写要改的键）：

curl -s -X POST http://127.0.0.1:19387/token-chart/api/prefs \
-H 'content-type: application/json' \
-d '{"dailyChart":"bar-line","showCacheHitRate":false}'

✨ 特性

- 会话抽屉：单个会话的逐轮用量趋势 + 文字统计，从会话标题栏一键打开。
- 每日面板：今天 / 近 3 天 / 近 7 天 / 近 30 天四个区间，KPI + 趋势图 + 数据表。
- 7 种图表形式：柱状、折线、饼图、表格、多柱状、多折线、柱状折线组合，会话与面板可分别配置。
- 缓存命中率叠加：柱状 / 折线 / 多柱状 / 多折线 / 组合图都可在右轴叠加命中率折线（默认开）。
- 范围选择条：坐标轴下方的 dataZoom，拖动只看某一段 x 范围；缩放不改变统计口径（KPI、总量、表格始终是完整区间）。
- 分页数据表：默认 20 条/页，页大小 10 / 20 / 50 下拉切换，页码为数字按钮 + 省略号，常驻右下角。
- 接管产品「用量」胶囊：点击改为打开本插件抽屉，而不是产品自带的对话框（可关）。
- 口径与产品一致：总 Token 采用计费口径（每次请求的上下文含缓存重读都计入）；运行时与产品的 tokenUsage 投影交叉校验，不一致会在抽屉里显式提示。
- 幂等采集：按 (轮次, 步骤, 重试世代) 存槽位，重放会话日志不重复计数；存储 schema 不符时丢弃并从日志重建。
- 降级可用：ECharts chunk 拉取失败（离线、被拦、产物损坏）时自动回退到内置自绘 SVG，界面不会空掉。
- 零运行时依赖：宿主半边不 import 任何 @deepseek-ai/，浏览器半边只把 react 平台种子留作 external，安装不需要 peer 解析或共享实例授权。
- 懒加载图表库：启动只需 ~70 KB 的 client.js（gzip 20 KB），首次出图才拉 618 KB 的 ECharts chunk（gzip 234 KB）。
- 可热更新：设置页自动查一次新版本（30 分钟缓存），有新版时给出「更新版本」按钮，走 ctx.pluginManager.installBundle。

🛠 本地开发与调试

源码全部是 TypeScript（浏览器半边 TSX + JSX automatic runtime）；src/ 是唯一事实来源，一切产物落在 lib/ 且不入 git。

git clone https://github.com/lugezuishuai/dsh-token-chart.git && cd dsh-token-chart
npm install # 触发 prepare：全量构建出 lib/
npm run typecheck # 两个工程分别类型检查（宿主 + 浏览器）
npm run build # 清空 lib/ 后全量重建
npm run check # 发布门禁：typecheck + build + preflight + 宿主用例

| 命令 | 作用 |
| npm run build:host / :styles / :client / :chunk | 单独重跑某一段（tsc / tailwind+less / esbuild / esbuild） |
| npm run preflight | 产物与元数据自检：loader id、包名、四件产物、registry、lockfile |
| npm run test:host | 宿主套件：折叠语义、跨天分桶、配置校验、落盘、版本检查 |
| npm run test:client | 浏览器套件：jsdom 加载真实产物，通过 HTTP 连运行中的 Harness |
| npm run format | prettier：src/、tests/、scripts/ |

调试期建议隔离数据目录，避免污染真实用量库：

DSH_HOME=$(mktemp -d) npm run test:host # 宿主用例必须用独立 DSH_HOME

浏览器用例需要运行中的 Harness（默认 http://127.0.0.1:19387）与一个真实会话 id
DSH_ORIGIN=http://127.0.0.1:19387 DSH_SESSION_ID=<session-id> npm run test:client

| 环境变量 | 作用 | 默认 |
| DSH_HOME | 数据根目录（usage.json / prefs.json 在其下） | ~/.dsh |
| DSH_ORIGIN | 浏览器用例连接的 Harness 地址 | http://127.0.0.1:19387 |
| DSH_SESSION_ID | 浏览器用例打开的会话 | 内置一个示例 id |
| REACT_DIR / JSDOM_DIR | 用例解析 react / jsdom 的目录 | npx 缓存目录 |
浏览器用例会在跑前快照、跑后恢复你的真实偏好；jsdom 没有 canvas 与布局，脚本会补 HTMLCanvasElement.getContext 与 clientWidth 垫片，浏览器端不需要。

让宿主半边也热加载（默认只热替换浏览器半边）：把插件目录加进 profile 的 hmr 监听根，改 src/ 重建后即时生效，无需重启。

~/.dsh/profiles/<profile>/cordis.patch.yml
- id: hmr
name: '@deepseek-ai/dsh-hmr'
config:
root:
- /path/to/dsh-token-chart

构建请用你自己的 Node（本机为 ~/.nvm/versions/node/v22.22.0）。DSH 自带的 Node 在 macOS 上无法 dlopen tailwind 的 lightningcss 原生模块，build:styles 会失败。

📦 构建与发布

构建产物与 DSH 包契约一一对应，全部落在 lib/：

| 产物 | 生成方式 | 被谁读 |
| lib/index.js + lib/.js | tsc（package.json#main） | DSH 宿主进程 |
| lib/types/*.d.ts | tsc（package.json#types） | 消费方类型检查 |
| lib/client.js | esbuild → __ModuleLoader__ CJS 工厂（不压缩，逐行可审阅） | 浏览器（exports["./client"]） |
| lib/client.echarts.js | esbuild → 压缩、自包含的懒加载 chunk | 浏览器（require.async） |
| lib/token-chart.css | tailwindcss + lessc | 浏览器（宿主路由下发） |

npm run check # 发布门禁：typecheck + build + preflight + 宿主用例
npm pack # prepack 自动重建 + preflight，然后打包
npm version patch # 版本号即 tag，更新检查按版本号比较，两者务必一致
npm publish # publishConfig 固定发往 registry.npmjs.org

发布也可以交给 CI：.github/workflows/release.yml 在推送到 main（含 PR 合并）与手动触发时运行——跑门禁 → 版本还不在 npm 上就自动发布、打 v<version> tag、建 GitHub Release；版本已存在则只跑门禁。认证走 npm Trusted Publishing（OIDC），仓库里不存任何 npm token；预发布版本按 preid 走独立 dist-tag（0.1.1-rc.1 → rc），不会顶掉 latest。

发布流水线要点：

1. prepack = 全量构建 + scripts/preflight.mjs，因此 tarball 一定带着四件产物与 lib/types；产物不进 git，files 白名单决定包内容。
2. 安装与发布都走 npmjs 源站：项目 .npmrc 与 package.json#publishConfig.registry 都指向 https://registry.npmjs.org/——镜像是只读的、不接受发布，统一在源站可以让「消费者装到的版本」与「发布出去的版本」始终一致。
3. preflight 检查：包名与 loader id 一致（改名事故的护栏）、四件产物存在、cordis.patch.yml 按包名插入、private 已移除、engines.dsh 已声明、lockfile 不含内网/私有 registry。

三种分发方式的产物来源：

| 分发方式 | 产物从哪来 |
| npm / tarball | 发布机上的 prepack 预构建，消费者零构建 |
| git 安装 | 消费者机器上的 prepare 现场构建（需先授权构建脚本） |
| 本地 link | 工作区里的 lib/，由你 npm run build 产出 |

📄 License

MIT © 2026 lugezuishuai. 详见 LICENSE。