dsh-token-pricing

Readme

# dsh-token-pricing

中文 | [English](README.en.md)

> `dsh-token-pricing` 是一款**第三方（非官方）插件**，由社区维护，与 deepseek-ai 官方发布无关。

Web 界面的按提供方/模型 token 定价：按提供方/模型配置美元价格（未命中输入、缓存命中输入、输出，以及可在任意多个高峰时段内生效的高峰价格档），并在三个表面查看会话费用——底部数据栏，以及一个可折叠可拖拽的浮窗（「按轮计价」与「按模型计价」两种视图）。按轮用量由 `tokenPricing` 投影从会话日志派生，随会话持久化、随归档一并保留。node 半身注册设置命名空间与投影单元，其余全部复用现有 Host 服务。

## 安装

前置：Node ≥ 22、pnpm、可用的 dsh 安装（官方 CLI `npm i -g @deepseek-ai/dsh`，或源码启动 `pnpm dsh`）。

```sh
# 1. 安装到 web profile（自动初始化 profile、安装依赖、注册补丁层）
dsh plugin --profile web add dsh-token-pricing

# 2. 启动（已在运行则重启后生效）
dsh web
```

`dsh plugin add` 走官方插件机制：把本包装进 `$DSH_HOME/profiles/web/` 的依赖 → 依据 `dsh.bundle` 声明加入 profile 补丁层 → 补丁层的一行 row 同时挂载 node 半身（Host）与浏览器半身（`dsh.client` 扫描）。本包只声明两个自用运行时依赖（`schemastery`、`zod`）；其余 `@deepseek-ai/dsh-*` 由 dsh 安装本身提供（官方机制的双锚点解析），因此安装不会拉取任何内部包。

验证安装：启动后打开 设置 → 模型定价 配置价格；右下角出现费用小球，对话底部数据栏显示费用读数。

更新与卸载：

```sh
dsh plugin --profile web update dsh-token-pricing
dsh plugin --profile web remove dsh-token-pricing
```

npm 之外，也可用 git 源安装（装某个分支/提交；仓库内已提交构建好的 `lib/`）：

```sh
dsh plugin --profile web add github:LightClear/dsh-token-pricing
```

注意事项：

- 若 profile 中已存在 id 为 `token-pricing` 的插件行，安装后会产生冲突——移除其一即可。
- 若需要把插件直接编译进 harness 主仓库（开发/集成），见 [INTEGRATION.md](INTEGRATION.md)。

## 功能亮点

### 配置模型价格与高峰时段规则

![设置页：展示具体模型的设置页面，读取已设置的模型配置，并配置模型价格与高峰期计价规则](docs/settings-page.png)

设置 → 模型定价 把模型目录按提供方分组为卡片，每个模型带已配置/未配置圆点。展开某个模型打开编辑器，自动载入已存配置，可编辑三档基础费率——输入未命中、输入命中、输出（美元/每百万 token）——以及高峰期计价规则：启用高峰定价后，可按需增删任意多个高峰时段（`添加高峰时段` / `删除时段`），全部时段共享一套高峰费率。默认只有一段，时段支持跨午夜（22:00–08:00），当前时间落入任一时段即按高峰价计费。

### 会话底部数据栏的实时费用

![会话底部数据栏：展示对话框底部数据区域的计价数据](docs/bottom-data-view.png)

对话框底部数据栏在出厂统计行旁显示会话的 `输入 $X · 输出 $Y · 总计 $Z`。每一步按自身时间、在其派发路由下计价，读数对每个已计价步骤求和，因此与浮窗总计永远一致；未配置计价路由的用量不计入该数字。

### 可折叠、可拖拽的费用浮窗

![费用浮窗折叠态：右下角小球显示会话总费用](docs/floating-window-folded.png)

折叠态是小球形状，显示当前会话的累计费用；点击小球展开面板。

![费用浮窗展开态：完整窗口，含标题栏、视图切换与底部总计](docs/floating-window-expanded.png)

展开态面板包含两个视图切换页签与底部总计栏。标题栏（顶部）与总计栏（底部）都是拖拽区域。

### 按轮计价与按模型计价

悬浮窗提供两种计价方式：按对话轮数计价与按模型计价。

![费用浮窗的按轮计价页面](docs/floating-window-turn.png)

「按轮计价」按对话轮次列出每轮（轮次号与开始时间）使用的路由、token 数与费用；一轮中途切换模型时按路由拆分为多行。

![费用浮窗的按模型计价页面](docs/floating-window-model.png)

「按模型计价」按会话中使用过的所有模型聚合 token 数与费用，按首次使用顺序排列。两种视图中，未配置计价规则的模型仍显示 token 数并提示 `未设置计价`。

### 跨项目费用统计面板

侧栏底部的币币图标按钮（设置按钮上方）打开独立的费用统计面板，覆盖**全部项目与全部对话**，而不只是当前会话。

![费用统计面板总览：展示全局费用指标、最贵轮、每日费用、项目列表与会话表](docs/cost-dashboard.png)

面板提供两个维度：**按项目**（左侧项目列表带费用占比条，右侧为所选项目的会话表，未分组会话殿后成桶）与**按模型**（跨全部会话按路由汇总：三桶输入拆分、输出、费用、占比、缓存命中率、有效单价 $/M、峰谷拆分、缓存节省，可下钻到使用该模型的会话列表）。两个维度最终都进入同一个会话详情页——汇总卡（总计、输入/输出、缓存节省、峰/谷、命中率、有效单价），「按轮计价」的轮行可展开为**逐步明细**（未命中/命中/写入 token、输出、适用费率、峰谷档位、该步费用），以及「按模型计价」聚合表；从模型维度进入时带可一键移除的模型筛选。

![费用统计面板单轮详尽视图：展示会话汇总与展开后的逐步 token、费率、峰谷档位和费用](docs/cost-dashboard-turn.png)

覆盖语义沿用侧栏：blank 会话排除；归档会话默认隐藏、`含归档` 开关可纳入；子代理会话不单列，其费用并入顶层父会话行（`+子代理` 标记）。顶栏提供时间窗（全部/今天/7天/30天，按每步自身时刻过滤）与 **CSV 导出**（当前视图：项目/会话/模型/模型会话/步骤级轮明细，带 UTF-8 BOM）。两个维度的总览都显示「全局分析」区，其中包含时间窗与归档开关所纳入全部会话的最贵轮 Top 5 和近 30 天每日费用条；进入项目、模型或会话详情会隐藏该区，并在顶栏显示「返回总览」。全部为客户端聚合：面板的会话费用与数据栏、浮窗按构造一致，改价即全量重算历史。

## 数据来源

按轮用量不是单独存储的：`tokenPricing` 投影将会话的持久事件日志折叠为逐步用量事实——每条携带服务商上报 `usage` 的 `assistant/message`，盖上其派发路由（最近一条 `request/header`）与该步自身的时间戳。由于折叠重放日志，数据随会话持久化、重启后还原，并随归档的会话一并保留（归档只隐藏列表行，从不改写日志）。投影只携带用量事实——费率住在设置作用域里——因此浏览器在渲染时逐步计价，事后修改价格条目会按新价重算历史。高峰/非高峰按每步自身时间判定：某步的时间落入其条目任一 `peakWindows` 即按高峰价计费。

`/client` 导出为插件主体（`apply`/`inject`）、dock、浮窗、设置页与统计面板组件及其注入面类型。纯费用计算位于 `src/client/pricing.ts`，投影折叠位于 `src/projection.ts`，统计面板的分组、分析与导出位于 `src/client/dashboard/`。

## 模型体验

### 基于已记录用量的费用读数

#### 模型看到的内容

本插件不向任何模型请求添加任何内容：不注册工具、不注册提示段，也没有任何设置值进入请求路径。数据栏、浮窗与设置页只呈现线上已有的持久数据——`tokenPricing` 投影值与 `token-pricing` 设置段。

#### Token 影响

零：本包不添加、移除或改动任何提示内容、工具 schema 或消息。

## 未来优化

- **计价货币选择与自动汇率处理** — 支持选择计价货币（默认美元），按最新汇率自动换算显示费用，无需手动改价格条目。