📖 使用指南

三个入口

位置	入口	内容
左侧边栏	「Token 用量」菜单	今天 / 近 3 天 / 近 7 天 / 近 30 天：KPI 卡片 + 趋势图 + 分页表格；「今天」表格的会话列显示会话名称，点击跳转到该会话
会话标题栏	「用量」小按钮（与 ⋯ 菜单同一行，常驻）	右侧边栏抽屉：总 Token、输入/输出、缓存读取/写入、命中率、轮次、模型 + 逐轮趋势图
设置页	设置 →「Token 用量」	图表形式、展示指标、开关；标题行含插件版本与更新入口（就地安装 / 重启生效 / HMR profile 指向插件市场）

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

你看到的「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），整条分页栏常驻右下角。切换页大小或数据变化会回到第一页。
会话跳转：「今天」表格的「会话」列显示会话名称（取自 DSH 的会话标题），名称过长时以省略号截断、hover 显示完整名称；点击即可打开对应会话（离开用量面板，主区域切回该会话）。没有标题或会话已不在目录里时，回退显示会话 id 尾部。

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}'

配置