调用用量统计 nobodyhere34/dsh-usage-calls

DSH Usage Calls

DSH web 插件的用量统计面板：按天 Token 趋势、GitHub 风格活跃热力图、缓存命中率曲线、按模型与按供应商两种用量拆分（堆叠柱状图 + 明细列表），在设置页新增一个"使用统计"页面。

与 dsh-usage-statistics-panel 的界面与图表一致；差异在数据层：统计单位从"按天累加的行"改为按调用记录的事实（call-fact，每个模型调用一条、key 为 session:turn:step:attempt，重放取最大值合并）。由此带来三个行为差异：

- 历史回扫每次启动都执行（不再只在首次启用）：已记录日志的重放是零写入，且能自愈被清空或半记录的存储；"装完插件想立刻看到历史"从安装的下一次启动起自动成立
- 会话删除不丢统计：调用一旦记录，事实独立于会话日志存在；旧版删除会话即失去其日志的再推导来源
- 实时与回扫收敛不重复计数：两条路径对同一次调用推导出同一个 key，无需游标/水位线分区

所有图表均为手绘 SVG，不依赖图表库；配色使用 GitHub Primer 的 data-viz 双套色板（模型前 10 名、供应商前 5 名各取一个等级色，其余归入灰色 "Other" 桶），并随 DSH 主题自适应。

预览

功能

- 时间范围：最近 7 / 14 / 30 / 90 天，或自定义起止日期
- 层级化筛选（双树勾选）：工具栏下的两个树形下拉——作用域树（工作区 ▸ 会话 ▸ 子会话，按会话头部的 parentSession 谱系缩进成树，行内显示标题 + 工作区 + 最近活跃日 + token 量）与模型树（服务商 ▸ 模型）。三态勾选：勾一行即选中整棵子树（半选横线 = 部分选中），父行数字为子树汇总；支持搜索（命中项平铺）、折叠、全选、一键清除。勾选即时重算整个面板（汇总卡片、热力图、趋势、模型/供应商拆分均跟随）；空勾选 = 全部；作用域树与模型树之间"与"、树内并集。展开规则：勾工作区走精确 workspace 维度，勾会话自动展开为整棵子树的会话 id 列表，跨工作区混选退化为纯会话枚举保证并集不丢数
- 汇总卡片：Token 用量、会话数量（完成的 turn）、请求数量、活跃天数、平均缓存命中率、最常用模型
- 26 周活跃热力图：每日 token 用量的 GitHub 风格色阶，悬停查看当天明细
- 按天 Token 趋势：堆叠柱状图叠加平滑的缓存命中率曲线（Catmull-Rom 样条），悬停查看各模型拆分
- 模型用量：堆叠柱状图 + 明细列表，前 10 名模型分色，其余折叠为可展开的 "Other" 明细；柱状图滚入视野时自基部升起
- 供应商用量：同一结构上移一层——前 5 名供应商分色（独立色板），其余归入灰色 "Other"；悬停任一侧联动另一侧，柱状图悬停显示该供应商的全部模型用量；每行可展开该供应商的模型明细，"Other" 展开被折叠的供应商、其下再展开各自的模型（展开不影响柱状图高度）
- 底部信息栏增强：设置页可开启"精确缓存命中率"（会话底部信息栏的缓存命中率以两位小数显示，如 85.25%）与"会话 Token 明细"（底部信息栏显示总 Token、输入、输入（命中缓存）、输入（未命中缓存）与输出 Token，替代默认的"输入/输出"两项）；开关位于"使用统计"面板底部，与"侧边栏快捷入口"同款样式，切换即时生效
- 历史回扫：每次启动枚举并重放全部持久化会话日志（幂等，已记录日志重放为零写入）；fork 出的子会话按宿主报告的继承前缀精确切割，不重复计入父会话调用
- 本地持久化：数据写入 $DSH_HOME/storages/usage_calls.json（storage-domain），纯本地、无外部依赖

安装

本仓库当前未发布到 npm，按本地链接安装：

在 web profile 的 package.json 中把本仓库以 link: 挂进依赖与 dsh.profile.bundles
pnpm add link:/path/to/dsh-usage-calls

发布后为 dsh plugin --profile <name> add dsh-usage-calls@latest。装完硬刷新浏览器（Cmd/Ctrl+Shift+R）：client 半的改动 DSH 会热加载，无需重启；仅 host 半（采集/存储/路由）更新时需要重启 DSH。

插件挂载后，在 Web UI 的设置页左侧导航会出现"使用统计"页面。
与 dsh-usage-statistics-panel 互斥：两者注册同一前缀路由 /usage/api，同时挂载会让整棵插件树在启动时以 "duplicate prefix route" 失败，只能二选一。换装时旧数据文件 usage_history.json 会被自动改名为 .bak 保留（可手工回退），新面板的数据由回扫从会话日志重建。

兼容性：本插件支持 DeepSeek Harness >= 0.1.2-rc.1，历史回扫双路径：0.1.2-rc.1 走 list+inspect，0.1.3 及以后版本走 list+open+分页 read+close（inspect 在新版宿主已移除）。开发依赖与核验目标对齐宿主 0.1.5-rc.1，两条路径产出相同事实由单测覆盖。

数据来源

面板的数据采集是观测式的，两条路径写入同一个事实存储：

- 实时：llm/stream 瀑布透传包裹每次模型调用，在终态取 provider 上报的最终 token 用量（输入 / 输出 / 缓存读 / 缓存写）与请求自带的 provider/model；调用键从会话事件流（step/start、llm/retry-started）推导——agent loop 在派发前先把这些事件写入日志，所以派发时键已确定。辅助调用（compaction、session-title）与无 sessionId 的手工请求原样透传、不记录。
- 回扫：每次启动折叠全部持久化会话日志，assistant/message 的 usage 与 source 归因落为同 key 的事实。

筛选维度的归因：每条事实自带 workspace（回扫取会话头部的 cwd，实时取 live 会话句柄），所属会话即事实 key 的首段（会话 id 为 UUID，不含冒号）；会话标题与父子谱系（parentSession）从日志顺带采集——回扫折叠日志时读取头部与 session/title 事件，实时路径监听同名事件与会话首见（重命名即时可见），存进旁路的伴生介质 $DSH_HOME/storages/usage_calls_meta.json——纯派生数据，丢失可由下次回扫重建，事实介质（usage_calls.json）的 v1 形状因此保持不变、无需迁移。

同一 key 的记录取逐字段最大值合并：两条路径收敛、崩溃重放、重复回扫都收敛到同一条事实，调用不会被重复计数；一条路径先落的 0-token 请求事实会被另一条路径的 token 补全。

提示：Token 用量从会话日志中 provider 上报的用量生成；更早的会话日志若无 provider 上报的用量数据，则无法回溯。

子代理会话：子代理是独立会话，其 token、请求与完成的轮次与顶层会话一并统计（实时采集覆盖全部会话事件流，回扫同样覆盖子代理会话日志）；其日志开头的父会话继承前缀被精确跳过，父调用不会记到子会话名下。日志中没有最终 assistant/message 的调用（失败或未完成）只有请求数、模型归因落在 "(unknown)" 桶——请求总数不受影响。

Token 口径：汇总卡片与趋势图的 Token 总量为服务商总口径——未缓存输入 + 输出 + 缓存读 + 缓存写，与服务商账单面板一致（DeepSeek 会把 prompt 拆成输入/缓存读两个不相交的桶，简单相加会漏掉占大头的缓存部分）。平均缓存命中率以输入侧（命中 + 未命中）为分母，其中未命中 = 未缓存输入 + 缓存写入——与会话底部信息栏（官方 StatsLine 口径）完全一致，两处读数不会出现分歧；命中率卡片下方同时展示缓存命中的绝对 token 量。

重建统计：POST /usage/api/reset（与面板同源信任围栏保护）清空本地统计并按当前归因规则全量重放会话日志——存储完全可从日志重建，reset 即"清空 + 重折叠"，无需水位线；并发调用合流为一次重建。

开发

pnpm install
pnpm typecheck # tsc --noEmit
pnpm test # vitest
pnpm build # tsc declarations + tsdown (host ESM + 双通道 client bundle)

设计与实现

- Host 半（src/）：facts/tracker（调用键与 max-merge 的单一实现）、observer（llm/stream 实时采集）、collector（每次启动的日志回扫）、store（usage_calls storage-domain）、query（范围聚合，翻译自 reasonix 的 query.go）、routes（/usage/api fenced JSON 路由，信任围栏与 /api 网关一致）
- Client 半（src/client/）：UsageStatsPanel.tsx（手绘 SVG 图表，移植自 reasonix 面板 + Primer 配色）、locales（en / zh / zh-TW）、api（/usage/api fetch 封装）
- 双通道打包：lib/client.js（官方 profile 通道，bundle id = 包名）与 lib/client-registry.js（插件注册表通道，bundle id = manifest id）。harness 0.1.x 官方加载链只消费前者；后者为外部 registry 通道预留，当前无消费者
- 详细设计见 docs/design.md

致谢

本插件衍生自 dsh-usage-statistics-panel：界面、图表与信任围栏复用其实现，数据层重构为 call-fact 模型（动机是「按天累加行」的重复计数风险与会话删除丢数）。上游面板本身是对 reasonix 用量统计功能的复刻移植：作者曾为 DeepSeek-Reasonix 实现并贡献了该功能（PR #7238、#7503）。如果你不需要 call-fact 数据模型，请优先使用原仓库 HaoyueQin/dsh-usage-statistics-panel（已发布 npm、持续维护）。

License

MIT