lugezuishuai/dsh-token-chart

dsh-token-chart

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

🚀 快速开始

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

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

📖 使用指南

三个入口

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

图表形式与交互

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

• 缓存命中率叠加：柱状 / 折线 / 多柱状 / 多折线 / 组合图都可在右轴叠加一条命中率折线（默认开）。
• 范围选择条：坐标轴下方的 dataZoom，拖动两端或中间窗口即可只看某一段 x 范围（滚轮与触控板捏合同样生效）。缩放只改变可见窗口，不改统计口径——数据表、KPI 卡片与总量始终是完整区间的值。
• 分页数据表：默认每页 20 条，页大小用下拉切换（10 / 20 / 50），页码为数字按钮 + 省略号（1 … 4 5 [6] 7 8 … 50），整条分页栏常驻右下角。切换页大小或数据变化会回到第一页。
• 会话跳转：「今天」表格的「会话」列显示会话名称（取自 DSH 的会话标题），名称过长时以省略号截断、hover 显示完整名称；点击即可打开对应会话（离开用量面板，主区域切回该会话）。没有标题或会话已不在目录里时，回退显示会话 id 尾部。

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

配置

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

枚举值：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 前缀），脚本与外部工具可以直接用：

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

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 + 趋势图 + 数据表。
• 会话跳转：「今天」表格的会话列显示会话名称，长名称省略号截断、hover 显示完整名称，点击打开对应会话。
• 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 分钟缓存）。可就地安装的 profile 才显示「更新版本」按钮，完成后按插件管理器返回的结果给出「已安装，重启 DSH 生效」或真实失败原因；启用 HMR 的 profile（如桌面端）不能就地升级，会提示到「插件市场」更新并重启。

🛠 本地开发与调试

源码全部是 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 + 宿主用例

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

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

浏览器用例会在跑前快照、跑后恢复你的真实偏好；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/：

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。

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

📄 License

MIT © 2026 lugezuishuai. 详见 LICENSE。