dsh-cost-tracker

Readme

# dsh-cost-tracker

DeepSeek Harness（DSH）的 **DeepSeek API 费用实时统计插件**。挂在 `llm/stream` 事件上，逐次模型调用累加 token 与费用，右下角悬浮面板实时展示，数据跨进程持久化，程序启动即自动加载。

> 计量口径对齐 DeepSeek 官方 V4 定价：缓存命中/未命中分档、高峰/空闲双档、按模型区分单价，并折算为人民币展示。

## 功能特性

- **实时计费**：监听 `llm/stream`，每次模型调用拿到精确 `usage` 后即时累加（输入未命中 / 缓存命中 / 输出三类 token 分开计量）。
- **精确计价模型**
  - 缓存命中、缓存未命中、输出三档单价独立计算；
  - 高峰/空闲双档，按北京时间 9:00–12:00、14:00–18:00 自动判定，也可手动锁定档位；
  - 按模型匹配单价（内置 V4 全系，未知模型回退 `deepseek-v4-pro`）。
- **纯人民币展示**：内部以官方美元价 × 汇率（默认 7.2，面板可调），全程 `¥` 展示。
- **后台余额管理**：输入充值金额后，实时显示「余额 / 本周期消耗 / 剩余额度」，额度用完标红提示并支持重新充值。
- **项目/对话汇总**：顶部固定显示「当前对话所在项目（工作区）的费用总和」，下方逐对话明细（对话简称 · 模型缩写 · 费用 · 时间），可滚动查看。
- **悬浮面板**：可拖拽、可折叠、跟随 DSH 明暗主题配色。
- **模型可查**：注册 `deepseek_cost` 工具，直接问 agent「我花了多少钱 / 还剩多少额度」即可。
- **跨进程持久化**：状态写入 `$DSH_HOME/storages/cost-tracker-state.json`，重启后在此前累计值上继续累加。
- **零侵入自动启动**：作为 profile 插件随 DSH 启动加载，无需每次手动激活。

## 安装

1. 把本包放入 profile 的 `node_modules`：

   ```bash
   mkdir -p "$DSH_HOME/profiles/web/node_modules"
   cp -R . "$DSH_HOME/profiles/web/node_modules/dsh-cost-tracker"
   ```

2. 在 `$DSH_HOME/profiles/web/cordis.patch.yml` 末尾追加一行 insert：

   ```yaml
   - insert:
       - id: cost-tracker
         name: dsh-cost-tracker
   ```

3. 重启 DSH：

   ```bash
   pkill -f "dsh/lib/bin.js web"
   dsh web
   ```

重启后打开页面，右下角即出现「DeepSeek 费用」悬浮面板。

## 使用说明

| 操作 | 方式 |
| --- | --- |
| 查看累计费用 / 余额 / 剩余 | 面板主读数，或问模型「我花了多少钱」 |
| 设置后台余额（充值） | 面板输入框输入金额后点「充值」 |
| 切换计费档位 | 面板「自动 / 空闲 / 高峰」按钮 |
| 修改汇率 | 面板底部「汇率」输入框 |
| 清零重新统计 | 面板「清零」按钮 |
| 拖动面板 | 按住标题栏拖动 |
| 折叠/展开 | 单击标题栏 |

## 计费口径

内置价格表（美元 / 1M tokens，来自 DeepSeek 官方「Models & Pricing」页）：

| 模型 | 输入·缓存命中 | 输入·未命中 | 输出 |
| --- | --- | --- | --- |
| `deepseek-v4-pro` | 空闲 0.022 / 高峰 0.044 | 空闲 0.66 / 高峰 1.32 | 空闲 1.98 / 高峰 3.96 |
| `deepseek-v4-flash` | 空闲 0.007 / 高峰 0.014 | 空闲 0.22 / 高峰 0.44 | 空闲 0.66 / 高峰 1.32 |
| `deepseek-v4-flash-vision-exp` | 空闲 0.007 / 高峰 0.014 | 空闲 0.22 / 高峰 0.44 | 空闲 0.66 / 高峰 1.32 |

- 高峰时段 = 北京时间 9:00–12:00、14:00–18:00，其余为空闲（空闲价为高峰的一半）。
- 未知模型名按 `flash`/`vision` 关键字回退 flash 价，否则回退 `deepseek-v4-pro` 价。

## 注意事项（重要）

1. **这是本机估算，不是官方账单**：插件按「本进程内真实发生的模型调用」累加，以 DeepSeek API 后台账单为准。因重试、上下文缓存、官方价格调整等因素，估算与账单可能存在偏差。
2. **只统计插件加载后的调用**：历史消息、插件安装前的消耗不计入。
3. **价格需手动同步**：价格表硬编码在 `lib/index.js` 的 `BASE_PRICES`，官方调价后需更新该常量。
4. **状态文件即账本**：删除 `$DSH_HOME/storages/cost-tracker-state.json` 即清零；该文件只在本机，不会同步到 API 后台。
5. **必须重启 DSH 才生效**：修改 `cordis.patch.yml` 或插件源码后，需要重启 `dsh web`（页面刷新只对 client 端热更新，Host 端需重启）。
6. **client 端 React 来自 harness 模块表**：浏览器半必须用 `factory: function (require)` + `require("react")` 获取 React，**不能用全局 `React`**，否则面板渲染会抛错。
7. **依赖**：Host 端 `tools`、`webServer`；Client 端 `slots`（由 `@deepseek-ai/dsh-client-runtime` 提供）。

## 目录结构

```
dsh-cost-tracker/
├── package.json          # 包元数据 + dsh.client 声明
├── cordis.patch.yml      # bundle patch（insert 本插件）
├── lib/
│   ├── index.js          # Host 端：计费、持久化、/cost-tracker API、deepseek_cost 工具
│   └── client.js         # Client 端：悬浮面板 + fetch 轮询
└── README.md
```

## License

MIT