dsh-plugin-cost

Readme

# dsh-plugin-cost

会话费用估算插件，用于 DeepSeek Harness（DSH）Web UI：把 token-meter 的 `tokenUsage` 投影（输入 / 缓存命中 / 缓存写入 / 输出四个桶）乘以可配置的价格表，在聊天输入框下方的统计条旁显示 `费用 ≈ ¥X.XX（估算）`，并提供"刷新价格"按钮手动拉取 DeepSeek 官方最新价格（Windows 更新时间式，平时不联网）。

**适合谁**：想直观了解每次会话大概花了多少钱的 DSH Web 用户；对 token 用量有概念的开发者也能看到四桶拆分（输入/缓存命中/缓存写入/输出）。

## Compatibility

- **DSH 版本**：`0.1.0-rc.6`（web profile，Node.js ≥ 22，实测 Node 24）
- **最后验证日期**：2026-08-15
- **安装方式已验证**：本地目录 / tarball（`pnpm pack`）/ `github:yweilai77-dev/dsh-plugin-cost` 三种均通过 `dsh plugin add` 实测（全新 profile → 启动 → 插件生效）
- 依赖：`@deepseek-ai/cordis`、`@deepseek-ai/dsh-typert-protocol`、`@deepseek-ai/schemastery`（安装时自动从 npm 拉取）

## Quick start

```sh
# 1. 安装到你的 profile
dsh plugin --profile web add github:yweilai77-dev/dsh-plugin-cost

# 2. 重启 dsh web
# 3. 打开 Web UI，聊天输入框下方的统计条下会出现：
#    费用 ≈ ¥0.0123（估算）  [刷新价格]
# 4. 点"刷新价格"→ 显示"已更新 HH:MM"（从官方中文价格页拉取最新价）
```

默认价格表为 deepseek-v4-flash 官方当前价（每百万 tokens）：输入（缓存未命中）¥1、输入（缓存命中）¥0.02、输出 ¥2。DeepSeek 于 2026-08-17 起切换峰谷定价，届时点一次"刷新价格"即可拿到新价格。

## 安装 / 卸载 / 禁用

| 操作 | 命令 / 方式 |
|---|---|
| 安装 | `dsh plugin --profile web add github:yweilai77-dev/dsh-plugin-cost` |
| 升级 | 重新执行上面的 `add`（或改用固定 commit：`github:yweilai77-dev/dsh-plugin-cost#<sha>`） |
| 禁用 | 在 profile 的 `cordis.patch.yml` 中把 `cost` 行改为 `disabled: true` |
| 彻底卸载 | `dsh plugin --profile web remove dsh-plugin-cost` + 重启 `dsh web` |

## 配置

插件行 `cost` 的 `config` 可覆盖默认价格表（每百万 tokens）：

| 字段 | 默认 | 含义 |
|---|---|---|
| `prices.input` | `1` | 输入（缓存未命中）CNY/百万 tokens |
| `prices.cacheRead` | `0.02` | 输入（缓存命中）CNY/百万 tokens |
| `prices.cacheWrite` | `1` | 缓存写入（按未命中输入计）CNY/百万 tokens |
| `prices.output` | `2` | 输出 CNY/百万 tokens |
| `prices.currency` | `CNY` | 币种（`CNY` → ¥，`USD` → $） |
| `fetchUrl` | 官方中文价格页 | "刷新价格"拉取地址；可指向 JSON（`{input, cacheRead, cacheWrite, output, currency?}`） |

在你的 profile 的 `cordis.patch.yml` 里按行 id 覆盖，例如：

```yaml
- id: cost
  name: dsh-plugin-cost
  config:
    prices:
      input: 1.5
      cacheRead: 0.05
      cacheWrite: 1.5
      output: 4.5
      currency: CNY
    fetchUrl: 'https://api-docs.deepseek.com/zh-cn/quick_start/pricing/'
```

> 注意：覆盖整行时需重述全部键（补丁替换整行 config，不做深合并）。

## 工作原理

- **Host 面**（`lib/index.js`）：`CostService`（Typert Remote 域 `cost`，方法 `prices()` / `fetch()`）。`fetch()` 从 `fetchUrl` 拉取页面并解析价格——JSON 源直接读取；官方 Docusaurus 价格页按关键词近邻解析（中英文均支持，全量扫描关键词出现的每个位置）。
- **Client 面**（`lib/client.js`）：统计条旁的费用行。费用在浏览器端计算：`tokenUsage` 投影 × localStorage 中的价格表（默认值随包发布）；"刷新价格"通过自挂载的 `cost` Remote 调用 host 拉取最新价格并存入 localStorage。挂载失败时优雅降级：估算照常显示，按钮报错。

## 权限与数据

- **网络**：仅在你点击"刷新价格"时访问 `fetchUrl`（默认 DeepSeek 官方价格页）；其余时间不发起任何网络请求。
- **本地存储**：浏览器 localStorage 保存价格表（键 `dsh.cost.prices`）；host 侧无持久化状态。
- **凭据**：不读取、不存储任何凭据。
- **文件**：解析失败时会把页面内容转储到 `.dsh-cost-debug\` 目录（可删除）。

## Troubleshooting

| 现象 | 原因 / 处理 |
|---|---|
| 界面没有费用行 | 安装后未重启；或 profile 的 patch 覆盖了 `cost` 行并禁用 |
| 点"刷新价格"显示"拉取失败：无法解析" | 官方价格页结构变更或 `fetchUrl` 不可达；保留旧价格继续显示，可改 `fetchUrl` 指向 JSON 源；解析失败时页面会转储到 `.dsh-cost-debug\` 便于排查 |
| 点"刷新价格"显示 "remote unavailable" | 浏览器端 Remote 挂载失败（罕见）；刷新页面重试 |
| 想回到未安装状态 | `dsh plugin --profile web remove dsh-plugin-cost` + 重启 |

## Development

```sh
# 仓库结构
#   lib/index.js   host 面（CostService / Remote / 价格解析）
#   lib/client.js  client 面（费用行 UI / 自挂载 Remote）
#   cordis.patch.yml  bundle 层（插入 cost 行）
pnpm test   # 冒烟：host 面可加载
```

想贡献：fork 本仓库 → 修改 → PR。主要可扩展方向：多模型价格表、按会话/按天汇总、账单导出。

## License

MIT