@visol-456/dsh-cost-tracker
English | 中文
DeepSeek Harness 的 LLM 成本统计插件：监听每次模型调用完成事件，按 provider 上报的
token 用量（输入 / 输出 / 缓存命中 / 缓存未命中）与价格表折算费用，持久化每次调用记录，
并在 dsh web 里提供三层 UI：
- A. 调用级明细：对话轨迹输入框下方的统计带里，官方统计行（turn/step、首 token
平均秒数、缓存命中状态）之下多出一行 ——
费用 ¥0.0042 · 会话 ¥0.1234，即本次调用费用；
- B. 会话级汇总：同一统计带的「会话汇总」卡片 —— 会话总费用 + 缓存命中 / 未命中 /
输出三类费用 + 各桶 token 数 + 缓存命中率 + 平均首 token 延迟；
- C. 全局统计页：会话页顶部「使用统计」tab（与「对话」「轨迹」平级，布局参照 CC Switch 的 Usage Statistics）：
主指标卡（真实消耗 Tokens / 总请求数 / 总成本）+ 详细指标卡（新增输入 / 输出 /
缓存创建 / 缓存命中 / 缓存命中率进度条）+ 双 Y 轴趋势折线图（成本 / 缓存创建 /
缓存命中 / 输入 / 输出五条线，日期范围 + 30s 自动刷新）+ 来源 / 模型筛选 +
底部 tabs（请求日志 / Provider 统计 / 模型统计）+ 价格表编辑器。
DeepSeek Harness dsh-plugin 生态的社区插件，不属于官方仓库。
兼容 DeepSeek Harness 0.1.7-rc.2 波浪：peerDependencies / devDependencies 已对齐
0.1.7-rc.2（cordis ^4.0.4）。0.1.7 把 settings seam 从
SettingsProvider.installSection(...) 换成了 Config 驱动的表单：价格表现在是插件自身
Config 里的一个 volatile 字段，设置页与数据桥按 profile 条目 id
（本包 cordis.patch.yml 里是 cost-tracker）访问它；编辑经 Loader 就地提交热生效，
不重挂插件。同时适配了 Loader.await() 不再抛出失败的 entry（启动失败留在 fiber 上，
需 Fiber.await() 才会抛出）以及客户端 SessionSnapshot.queue 字段的移除。
致谢 / 设计参考
使用统计页面（指标卡、双 Y 轴趋势图、请求日志表格、tooltip 交互等）的 UI 全面对齐
CC Switch（MIT 协议）的 Usage Statistics
页面 —— 布局、配色、图表样式与交互密度均以其为蓝本。向 CC Switch 原作者
farion1231 及项目致谢；本插件为独立实现（自绘 SVG 图表，未引入 recharts），
仅参考其视觉设计与交互模式。
开发原因
DeepSeek 2026-08-17 起调整价格并引入峰谷定价（高峰 9:00-12:00、14:00-18:00 为高峰价，
其余半价）。Harness 本身没有任何货币计费能力（token-meter 的 "shadow price" 只是上下文
压力估算，不是钱），于是有了这个插件：用 provider 上报的缓存命中/未命中分开的 token 数
按价格表实时折算人民币费用，并给出与 DeepSeek 平台用量页可交叉核对的可视化界面。
快速开始
npm i @visol-456/dsh-cost-tracker
在 cordis.yml 中挂载插件（裸机 node 部署）：
- name: '@visol-456/dsh-cost-tracker'
config:
dataDir: /path/to/cost-records # 可选，默认 <DSH_HOME>/cost-tracker
挂载即开始记录，无需任何配置。默认价格表为 2026-08-17 起的官方峰谷定价的低谷价
（元 / 百万 tokens），高峰时段（北京时间 9:00-12:00、14:00-18:00）按括号内的高峰价计费：
| 模型 | 缓存命中 | 未命中输入 | 输出 |
|---|
| deepseek-v4-flash | 0.05（峰 0.10） | 1.5（峰 3） | 4.5（峰 9） |
| deepseek-v4-flash-vision-exp | 0.05（峰 0.10） | 1.5（峰 3） | 4.5（峰 9） |
| deepseek-v4-pro | 0.15（峰 0.30） | 4.5（峰 9） | 13.5（峰 27） |
| 其他模型（default） | 0.05（峰 0.10） | 1.5（峰 3） | 4.5（峰 9） |
价格可在 会话页 → 使用统计 → 价格配置 修改（支持按模型填峰谷价与高峰时段），
或直接写 cordis.yml（条目 config.prices，即插件的「组成层」）与 profile 补丁
（$DSH_HOME/profiles/<name>/cordis.patch.yml，即「用户层」）。用户层缺失的键会回落到
组成层与内置默认值。错误的价格表会在加载时报错（fail loud）；运行中被改坏的表格会
被拒绝并保留上一份可用价格，绝不会静默错算。
0.1.7 起价格编辑走插件自身的 Config 表单：设置命名空间就是 profile 条目 id
（bundle 自带的 cordis.patch.yml 用 cost-tracker），改完由 Loader 就地提交，
下一次调用立刻用新价，不需要重启 dsh。
部署到 web profile（dsh web）
A. dsh plugin add（推荐）
本包声明了 dsh.bundle，安装后会作为 profile 层自动激活（随包 cordis.patch.yml
以默认价格挂载插件，价格在 UI 里编辑）：
dsh plugin --profile web add @visol-456/dsh-cost-tracker
B. 手动 patch 覆盖层
# cordis.yml（patch 列表）
- insert:
- id: cost-tracker
name: '@visol-456/dsh-cost-tracker'
dsh web --patch ./cordis.yml
patch 语法（最大的坑）
- 每个挂载条目必须有
id；新增条目必须放在顶层 - insert: 列表里。
- 裸条目列表会被静默拒绝且
dsh web 启动不打印任何错误。
- 用
node --import tsx/esm apps/cli/src/bin.ts web --dump-config --patch <file>
诊断组合配置树。
本地开发 junction 位置
$DSH_HOME/profiles/node_modules 是 launcher 维护的 bundle 回退目录，不参与
cordis.yml 条目的裸 import 解析。本地挂载未发布的 checkout，必须把 junction 建在
harness 根 node_modules：
mkdir -p <harness-root>/node_modules/@visol-456
ln -s ~/myshare/deepseek_harness/dsh-cost-tracker <harness-root>/node_modules/@visol-456/dsh-cost-tracker
数据与安全
- 记录文件：
<dataDir>/records.jsonl（默认 <DSH_HOME>/cost-tracker/，
$DSH_HOME 缺省为 ~/.dsh），每次调用一行 JSON。
- 费用公式：命中费用 = 命中 tokens × 命中单价；未命中费用 = 未命中 tokens × 未命中单价
（= 正常输入价）；输出费用 = 输出 tokens × 输出单价；无缓存细分时退化为
输入费用 + 输出费用。
- 数据桥：
/cost-tracker/* 路由挂在共享 webServer 上，loopback + Origin 同源守卫
（--host 0.0.0.0 时 LAN 请求被 403 拒绝），与 dsh-llm-fallback 的配置桥同款信任模型。
- 无 webServer 时纯 node 运行照常记录，仅 UI 缺失。
与 dsh-llm-fallbacks 的定位区别
- omdsh-dev/dsh-llm-fallbacks（及
@visol-456/dsh-llm-fallback）：请求路由/容灾插件 —— 主 provider 失败时把同一请求
切换到备用 provider/model。管的是"请求往哪走"。
- 本插件：计量/计费插件 —— 调用完成后按真实用量折算费用。管的是"花了多少钱"。
- 两者互补、可同时挂载；本插件记录的是实际服务的 provider/model
（
assistant/message 的 message.source），因此 fallback 切换后费用归属依然正确。
开发
npm install
npm run build # tsc 双 tsconfig + tsdown（node + client 双入口）
npm run typecheck # 双 tsconfig --noEmit
npm test # vitest：费用计算/价格校验/持久化/聚合/桥守卫/loader E2E/
# 真实 SettingsForms 热改价/真实 HTTP 桥冒烟
原理速览
- 监听点：
internal/dispatch（global）→ session/event；assistant/message 携带
provider 上报的 TokenUsage（harness 的 DeepSeek adapter 已把
prompt_cache_hit_tokens 映射为 cacheReadTokens 并从 inputTokens 中减掉，
见 packages/llm/llm-deepseek/src/translate.ts 的 mapUsage）。
- 客户端：
conversation.view（order 2）注册「使用统计」tab，与「对话」「轨迹」平级；
conversation.composer.dock（order 1，紧随官方 stats line）注册费用行与会话汇总卡片；
数据经 HTTP 桥获取，新消息/切会话自动刷新。
- 趋势图：自绘 SVG 双 Y 轴平滑趋势图（Catmull-Rom 转 cubic Bézier，harness 无图表库，recharts 会显著膨胀插件 bundle）。
- 设置 seam：
Config.prices 是 schemastery 的 volatile 字段，schema 只声明形状（金额非负），
语义校验仍由 pricing.ts 的 resolvePriceTable 独占（未知键、峰谷时段等跨字段约束），
并在每次读取时对「内置默认 ⊕ 当前 section」的合并结果执行一次；失败保留上一份可用价格。
dataDir 保持普通（非 volatile）配置：改它需要重挂，改价格不需要。
License
MIT
