fishOfOUC/dsh-price-monitor

description: "dsh-price-monitor：一个 dsh-better-sidebar 标签页，用于为 DeepSeek Harness 会话中提供商报告的 token 用量定价。"
kind: "user-guide"

dsh-price-monitor

DeepSeek Harness 的会话成本监控：宿主侧会话投影将持久日志折叠为按尝试划分的 token 账本，而
dsh-better-sidebar 标签页则使用官方或手动输入的套餐为该账本定价。

要求——请先阅读

此插件没有自己的用户界面。它完全作为
dsh-better-sidebar 的一个标签页呈现，而后者必须首先安装并挂载。 如果没有它：

- 成本视图没有地方显示——此包只注册一个侧边栏标签页和一个套餐设置面板，仅此而已；
- 客户端部分拒绝激活，并会说明原因
（dsh-price-monitor requires Better Sidebar features: pluginSettings, stateSubscription），
而不是加载一个半可用的面板。

| 要求 | 原因 |
|---|---|
| 带有 web 配置文件的 DeepSeek Harness | 该插件附带一个宿主部分（会话投影和 HTTP 路由）和一个浏览器部分 |
| dsh-better-sidebar ≥ 0.18.0，已挂载并启用 | 标签页、设置面板、套餐目录的存储以及投影读取都来自其服务 API（ctx.betterSidebar、stateSubscription、pluginSettings）——参见安装 |
| 一个用于你希望查看的费率的套餐 | 所选套餐会为会话定价；如果没有套餐，每个请求都会被列为未定价，而不是被猜测 |

宿主部分（token 账本）在没有侧边栏的情况下也能工作，但没有任何东西会读取它：除了那个标签页之外，该账本没有 UI。

它显示什么

- 当前会话总成本，按所选套餐的费率计算，并以套餐自身的货币，同时以 token 和金额显示精确的三桶拆分（缓存未命中 / 缓存命中 / 输出）。
- 按轮次列表：每一轮及其 token 和成本，可展开到每个计费请求——包括重试过、切换过模型或无法定价的请求。一个请求就是一次模型调用，即一个 harness 步骤，而循环会将一轮中的步骤编号为 1..N，因此一行显示为“request N”。重试的请求会保留该编号，并增加“retry N”，而不是作为额外步骤出现。
- 套餐卡片，显示所选套餐的费率，并在所有已保存套餐之间进行相同 token 的对比。
- 部分诚实：某个尝试的用量从未到达或未通过验证、其缓存桶无法分离，或者报告了套餐没有对应费率的缓存写入 token，则该尝试会被排除在金额之外，并列出其原因。Token 计数作为提供商报告的事实，仍会被汇总并显示：未知成本绝不会清空已知计数，未知也绝不会显示为零。

架构

host   priceMonitorUsage session projection   ← the only fact source
└─ 每（轮次、步骤、尝试）一行：startedAt/settledAt、provider、
model、四个 DSH token 桶、completeness
客户端价格标签页（dsh-better-sidebar）
├─ 通过 ctx.sessions.binding(id) 读取投影
├─ 在 pluginSettings['price-monitor'] 下用 decimal.js 计价
└─ 官方刷新：POST /price-monitor/api/official-pricing

这种拆分带来三个特性，每个都有测试覆盖：

1. 完整历史 —— 账本来自整个持久化日志，而非客户端分页的事件窗口。
2. 无重复计数 —— 计价从不重新推导 token；它消费的是 provider 上报的精确桶。该折叠逻辑与 harness 自身的 deriveTurnTokenUsage 一致，并对每个完整轮次进行交叉校验。
3. 重新计价是免费的 —— 套餐存在于侧边栏的设置中，因此切换套餐即可重新计价，无需触碰会话日志。

Token 桶语义

DSH 的 TokenUsage 各桶互不重叠：inputTokens 仅指未缓存的输入，DeepSeek 的适配器在写入 prompt_tokens 之前会从中扣除缓存命中部分。因此计价时每个桶乘以各自的费率，绝不计算 prompt_tokens - cacheReadTokens。outputTokens 已包含推理 token，因此推理不会被重复计费。

计价套餐

费率以每百万 token 为单位，存储为十进制字符串；每个乘积与求和都保持为 Decimal 直到显示。

| 套餐来源 | 可编辑 | 创建方式 |
|---|---|---|
| official | 否 —— 请先复制 | 官方刷新（抓取到的时期） |
| manual | 是 | 设置面板，或下方的内置历史 |

内置目录是 flash 模型已发布的价格历史 —— 每个时期一个套餐，均以人民币计价，并选中当前生效的时期：

| 套餐 | 每 1M token 费率（非高峰、高峰） |
|---|---|
| 涨价前（8-17 前） | ¥0.02 / ¥1 / ¥2，单一固定价格 |
| 涨价后（8-17 起） | ¥0.05 / ¥1.5 / ¥4.5，高峰 ¥0.1 / ¥3 / ¥9 |
| 降价后（现行官方价） | flash ¥0.02 / ¥1 / ¥4，高峰 ¥0.04 / ¥2 / ¥8；pro ¥0.15 / ¥4.5 / ¥13.5，高峰 ¥0.3 / ¥9 / ¥27 |

刷新会用页面当前描述的时期替换 official 套餐：一个套餐为页面列出的每个模型携带一张费率表，因此按其后继模型费率计费的已退役模型，会以同时命名两个 id 的分组来表达。

货币

官方定价默认以人民币计价：内置快照和刷新路由都读取 DeepSeek 的中文定价页面，该页面以元为单位显示主要公布数字。英文页面将相同费率显示为其四舍五入后的美元换算值（2026-09-10 快照时 1 美元 ≈ 6.818 人民币：flash 在中文页面为 ¥0.02 / ¥1 / ¥4，在英文页面为 $0.003 / $0.15 / $0.6），本插件从不在两者之间进行换算。

因此，套餐携带其发布者所印制的货币 —— 官方套餐为 CNY，手动套餐则为其保存时所用的货币 —— 而一个
amount 始终以产生它的计划所用货币读取。$0.15 和 ¥1 绝不会被静默相加。同样的规则也适用于比较列表：不同货币的行仍会列出各自的总计，但不会在它们之间显示百分比，因为跨货币的比率毫无意义。

如果你以美元记账，就手动添加一个美元计划；并将官方计划复制为手动计划，以另一种货币重新表述它。计划的 modelIds 绝不会影响金额，因此美元计划为任何会话定价的方式与人民币计划完全相同。

价格阶段

DeepSeek 会随时间调整这些费率，因此可以通过为每个阶段保存一个计划并在它们之间切换，来跨阶段比较同一会话；比较列表随后会显示完全相同的 token 在每个阶段的总计。在其费率周期（effectiveFrom / effectiveTo）中记录每个阶段适用的时间——该周期只是计划卡片的标签，绝不会限制定价，因此所选计划会为整个会话定价，无论其尝试落在哪些日期。

被取代的阶段知道它何时结束，却不知道它何时开始，因此周期的任一端都可以单独填写。

会话如何定价

所选计划就是整个定价基础，而一个计划就是一个时代：某个提供商在一段时间窗口内为一组模型收取的费率。切换计划会同时移动主总计、三个分桶明细、每轮行以及比较列表——切换的理由正是“这些 token 在另一个时代会花费多少”，而一个中途切换过模型的会话仍会按模型逐一计价。

在一个计划内，每次尝试都按其自身模型所属的分组定价：

- 命名了该模型的分组为其定价；
- 没有任何分组命名的模型（被重命名的 id、该时代从未列出的模型、未记录路由的尝试）按计划的第一个分组定价，即该时代的头条费率，并且该尝试行会显示 priced as ，使这种替代可见而非静默发生。

提供商本身也不会限制金额：在另一个网关上运行的请求也以同样的方式定价。只有 token 事实才能使一次尝试不被计入金额。

只有 token 事实才能使一次尝试不被计入金额：从未到达或未通过验证的用量、无法分离的缓存分桶，以及计划没有对应费率的缓存写入 token。它们的 token 仍会被计数，并且主总计会切换为“已知成本”并附上原因统计，因此未知金额绝不会变成零。

计划声明的费率周期（effectiveFrom / effectiveTo）是计划卡片的标签——表示这些费率何时适用——而绝不是限制条件：所选计划会为整个会话定价，无论其尝试落在哪些日期。捆绑快照故意省略开始时间，因为一次获取观察到的是今天的费率，而不是得知它们何时开始。

峰/谷时段使用每次尝试的 UTC 开始时间：周一至周五，01:00–04:00 以及
06:00–10:00 UTC 为高峰时段（左闭右开），而没有高峰时段的方案会将所有用量按其单一费率计价。随附的快照日期为 2026-09-10，并在 UI 中显示其来源链接；它为页面列出的两个模型——flash 模型和 pro 模型——定价，其中 flash 价格覆盖该模型曾被列出或报告过的所有 id（deepseek-flash、deepseek-v4-flash、deepseek-v4-flash-vision-exp）。

存储的设置带有一个 schemaVersion。一个可读的版本 1 blob——其中还包含一个计算模式和一个模型别名映射——会被就地升级，同时保留用户的方案和选择；这两个字段都被移除，因为在单一计价基准下，二者都无法改变金额。

官方价格刷新

客户端从不抓取上游页面。它向插件的主机路由发送 POST 请求，该路由会：

1. 要求通过浏览器信任防护（Host 头必须是回环地址或已配置的受信任机构；cross-site 和不匹配的 Origin 会被拒绝），且仅接受 POST；
2. 抓取一个硬编码的 URL
（https://api-docs.deepseek.com/zh-cn/quick_start/pricing/）——客户端载荷无法更改目标，重定向必须保持在该单一主机上的 HTTPS，且响应体上限为 256 KiB 且必须是 HTML；
3. 严格解析页面：模型表头、两个时段下的三个计价类别、高峰 = 2 × 非高峰的关系，以及高峰时段脚注（页面以北京时间表述；调度器存储等效的 UTC 时段）。任何结构性变化都会导致整个导入失败（HTTP 502），调用方保留上一个良好的目录；
4. 返回逐字段差异。用户在任何内容被写入之前需在标签页中确认，应用时会追加新的不可变官方版本（全新 id）——之前的版本保留以供历史比较。

安装

先安装并挂载 dsh-better-sidebar——本插件的标签页会出现在该侧边栏的 + 菜单中，其方案设置会出现在该侧边栏的 Side card 设置页面中。然后安装本插件：
sh
1. 本插件渲染所在的侧边栏（如果已有则跳过）
dsh plugin --profile web add dsh-better-sidebar

2. 本插件
dsh plugin --profile web add dsh-price-monitor

两条命令都会向 profile 追加一个 bundle 及重启时挂载；安装后重启 DSH（Host 两半已更改），然后打开侧边栏的 + 菜单并选择 Session cost。

开发安装（从此检出目录）
sh
cd dsh-price-monitor
pnpm install
pnpm run build          # tsc 输出 lib/types，tsdown 输出 lib/index.js + lib/client.js

然后将 profile 的 sidebar 插件指向构建后的包：
yaml
~/.dsh/profiles/web/package.json
"dependencies": {
"dsh-price-monitor": "link:E:/Code/my_code/dsh_price_monitor/dsh-price-monitor"
}
sh
cd ~/.dsh/profiles/web && pnpm install

该包自带的 cordis.patch.yml（dsh.bundle.patch）会挂载主机半部分
一旦 bundle 出现在 dsh.profile.bundles 中；对于 link: 安装，也要在那里添加 bundle 名称：
json
"dsh": { "profile": { "bundles": [ "...", "dsh-price-monitor" ] } }

然后重启 DSH 并强制刷新浏览器。该标签页会以 Session cost 的形式出现在侧边栏的 + 菜单中；其齿轮图标会打开计划设置。

在任何重新构建之后都要重启宿主，包括仅客户端的编辑：客户端产物由 /plugins//client.js 提供，其修订版本号派生自其字节内容，而位于加载器监视工作区之外的 link: 包在宿主运行期间不会被重新读取——重新构建的 lib/client.js 会一直从宿主的内存副本中提供，直到宿主重启。

已发布安装
sh
dsh plugin --profile web add dsh-price-monitor

同样的侧边栏优先规则适用：如果没有挂载 dsh-better-sidebar，客户端部分会在激活时抛出异常，而不是静默地什么都不做，所以在此处提交 bug 之前，请先检查侧边栏本身是否正常工作。

隐私与网络行为

- 读取账本和定价完全在本地进行；不会上传任何内容。
- 唯一的出站请求是官方定价刷新，由用户显式触发，并且只获取一个公开文档页面。
- 计划设置存放在侧边栏自己的偏好文档中
（pluginSettings['price-monitor'].catalog），即与用户的其他
侧边栏设置放在一起；该插件不会向会话日志写入任何内容。

配置

没有 cordis.yml 配置：计划目录是用户数据，在设置面板中编辑。捆绑的官方快照是离线默认值。

开发说明

- pnpm run typecheck、pnpm run test、pnpm run build。
- lib/ 已提交，因此 git 安装（dsh plugin add github:/dsh-price-monitor）
无需构建步骤。在任何源代码更改后，重新运行 pnpm run build 并将 lib/ 一起提交。
- 客户端部分是一个 ModuleLoader 闭包工厂（format: 'cjs' 包裹在
window.__ModuleLoader__.load 中），因为测试框架将其作为经典脚本在
/plugins/dsh-price-monitor/client.js 处求值；只有测试框架的浏览器
模块表可以保持外部，因此 zod 和 decimal.js 被内联。
- 样式从 src/client/styles.ts 作为单个  元素注入，
而不是通过 *.module.css 导入：tsdown 在没有额外插件的情况下不会编译 CSS 模块，
并且每个类都带有 dpm- 前缀，因此一个全局样式表不会发生冲突。颜色仅来自 DSH 主题令牌。
- 该标签页通过侧边栏自己的设置路由写入其目录，并使用其客户端发送的相同
整个 pluginSettings 补丁，通过一条 promise 链进行序列化，因此两次快速编辑不会交错。

测试

| 文件 | 覆盖范围 |
|---|---|
| tests/usage-ledger.spec.ts | 折叠：尝试生命周期、重试、验证、矛盾、一个从未报告缓存写入桶的用量样本、引用稳定性、冷/实时一致性，以及与测试框架的 deriveTurnTokenUsage 的交叉校验 |
| tests/pricing-engine.spec.ts | 峰值边界、以所选时代作为唯一依据并为每个模型组提供一张表、未列出模型的标题组回退、切换套餐时对每一层重新定价、部分定价下的 token 事实、小数精确性、schema 拒绝，以及第 1/2 代升级 |
| tests/official-pricing.spec.ts | 两个保存的页面 fixture（三列布局和重命名后的双模型布局）都能精确解析；金额、类别、表头、格式错误的 id 或脚注窗口发生变化时都会失败 |
| tests/trust-fence.spec.ts | 回环/受信任主机通过；跨站、不透明和来源不匹配则失败 |
| tests/client.spec.tsx | 激活与功能门控、目录读取（包括 v1 升级）、hero 总计等于各轮次行之和，以及切换套餐时对 hero、明细和行重新定价 |
| tests/client-interaction.spec.tsx | 展开一个轮次会按步骤为每个请求编号并标记重试；点击套餐会写入目录并重新定价已渲染的标签页；套餐表单为每个模型组编辑一张费率表；写入失败会显现出来 |
| tests/built-artifacts.spec.ts | 构建后的入口点存在且行为正常；客户端 bundle 是有效的 loader 工厂；真实 HTTP 上的路由拒绝 GET/跨站/外部重定向，并返回一个候选及 diff |