dsh-conversation-cost

Readme

# dsh-conversation-cost

DeepSeek Harness（`dsh`）插件：**实时统计当前对话（当前会话）花费了多少钱**。

基于会话日志中每条 `assistant/message` 携带的**真实 usage**（provider 返回的 token 数），
按内置 DeepSeek V4 官方价（元/百万 tokens）估算费用，并**按每条调用实际发生时间区分高峰 / 空闲时段**分别计价。

## 特性

- **实时金额**：侧边栏底部常驻显示 `¥X.XX · N 次`，每 5 秒自动刷新，随对话增长实时更新（**完全替代出厂 Cordis 面板徽标位，侧边栏底部只显示金额**）。
- **真实数据**：读的是会话日志里的权威 usage（`inputTokens / outputTokens / cacheReadTokens / cacheWriteTokens / reasoningTokens`），不是估算出来的 token 数。
- **分段计费**：每条调用按自身 `event.time` 归属高峰（每日 9:00–14:00，价 ×2）或空闲时段，分别累加，不做整段统一价。
- **缓存命中计价**：输入计费 = 未命中输入 + 缓存写入（未命中价）+ 缓存命中（命中价，仅为未命中价的 1/30）。
- **模型工具**：`conversation_cost`，模型可主动调用，返回逐次明细 + 汇总。
- **技能**：`conversation-cost`，出现在技能目录，指导模型何时调用与如何汇报。

## 目录结构

```
dsh-conversation-cost/
├── package.json        # npm 包清单 + dsh.bundle / dsh.client 声明 + prepare 构建脚本
├── tsconfig.json       # 严格模式类型检查配置（tsc --noEmit）
├── tsdown.config.ts    # 构建配置：Node 库（lib/）+ 浏览器 client bundle（lib/client.js）
├── cordis.patch.yml    # bundle 配置层：插入插件行
├── src/
│   ├── index.ts        # 主插件：费用计算 + conversation_cost 工具 + 技能 + HTTP route
│   └── client.ts       # 浏览器半边：侧边栏底部费用读数（sidebar.footer.action 插槽，完全替代 Cordis 面板位）
└── pnpm-workspace.yaml # 独立 workspace 声明
```

## 安装

```sh
# 本地目录
dsh plugin --profile demo add /path/to/dsh-conversation-cost

# 从 GitHub 安装（拉源码并自动构建 lib/）
dsh plugin --profile demo add github:you/dsh-conversation-cost
```

安装后验证配置层并启动：

```sh
dsh --profile demo --dump-config   # 应看到 "# == dsh-conversation-cost" 层
dsh --profile demo
```

> 侧边栏读数（client 半边）只在插件以**包名**安装进带完整界面的 profile 时加载
> （如 `dsh plugin --profile web add ...`）；`--patch` 源码路径挂载只加载 host 半边。

## conversation_cost 工具

用户问"这个对话/会话花了多少钱、费用、成本"时，模型会自动调用：

```json
{
  "timeBucket": "auto"
}
```

`timeBucket` 可选：`auto`（默认，按每条调用实际时间分别计费）、`peak`（全部按高峰价）、`off-peak`（全部按空闲价）。

返回示例（工具渲染后）：

```
当前对话（会话 session-xxx）模型费用估算（按每次调用实际时段）
- 模型调用：171 次，其中可计价 171 次
- 总费用：¥3.8600
  · 空闲时段：¥3.8600（171 次调用）
  · 高峰时段：¥0.0000（0 次调用）
- 输入 tokens：759975（缓存命中 20600448，缓存写入 0）
- 输出 tokens：140346
```

## 计费口径

- 价格表内置 DeepSeek V4 系列官方价（元/百万 tokens，[2026-08-17 起生效](https://news.qq.com/rain/a/20260817V03S1500)）：

| 模型 | 时段 | 输入未命中 | 缓存命中 | 输出 |
| --- | --- | --- | --- | --- |
| deepseek-v4-flash | 空闲 | 1.5 | 0.05 | 4.5 |
| deepseek-v4-flash | 高峰 | 3.0 | 0.10 | 9.0 |
| deepseek-v4-pro | 空闲 | 4.5 | 0.15 | 13.5 |
| deepseek-v4-pro | 高峰 | 9.0 | 0.30 | 27.0 |

- 高峰时段为每日 9:00–14:00（按事件实际时间判断），其余为空闲时段；高峰价 = 空闲价 ×2。
- 输入计费 = 未命中输入 + 缓存写入（未命中价）+ 缓存命中（命中价）；输出按输出价（DeepSeek `completion_tokens` 已含 reasoning tokens，不会重复计）。
- 金额为**估算值**，实际以平台账单为准；未知模型会单独列出（token 照常统计，费用不计入）。

## 架构

```mermaid
flowchart LR
    subgraph dsh["DeepSeek Harness (dsh)"]
        P["dsh-conversation-cost"]
        P -->|"会话日志 assistant/message usage"| C["费用计算<br/>按 event.time 分高峰/空闲"]
        C -->|"conversation_cost 工具"| M["模型主动查询"]
        C -->|"GET /dsh-conversation-cost/summary"| W["webServer route"]
        W -->|"fetch 轮询 5s"| F["侧边栏底部读数"]
    end
```

## 本地开发

```sh
pnpm install
pnpm typecheck
pnpm build
```

在 deepseek-harness 源码根目录用 overlay 直接加载 host 半边：

```sh
pnpm dsh web --patch /absolute/path/to/dsh-conversation-cost/cordis.patch.yml
```

> ⚠️ `--patch` overlay 只加载 host 半边（发现不了包级 `dsh.client` 声明），
> 侧边栏读数不会出现；要测试 client 半边，必须把包按**包名**安装进带 GUI 的 profile：
> `pnpm dsh plugin --profile web add /absolute/path/to/dsh-conversation-cost && pnpm dsh web`

## 发布

- **npm**：`pnpm publish`（`files` 已包含构建产物与补丁）
- **tarball**：`pnpm pack`，用户 `dsh plugin --profile demo add ./dsh-conversation-cost-0.1.0.tgz`
- **git**：`dsh plugin add github:you/dsh-conversation-cost`。pnpm ≥10/11 对 git 依赖的
  `prepare` 构建脚本有白名单限制，首次安装会报 `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`，
  需要把该仓库加进 profile 的 `pnpm-workspace.yaml` 的 `allowBuilds`：

  ```yaml
  allowBuilds:
    dsh-conversation-cost@git+https://github.com/you/dsh-conversation-cost.git: true
  ```

## 相关文档

- [插件开发入门](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/user/develop/basic/index.zh.md)
- [打包与安装插件](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/user/develop/basic/publish.zh.md)