dsh-monitor

Readme

# DEEPSEEK 监控插件（峰谷时段版）· DSH 版

> 🌐 **English version:** [README.en.md](README.en.md)

DSH 原生插件，实时监控 DSH 会话的真实 Token 消耗与费用，按 **DeepSeek 官方峰谷定价** 计算，
并在 DSH 页面右上角显示毛玻璃悬浮窗（与浏览器扩展版 UI 完全一致）。

![插件形态](docs/panel.png)

---

## 一、功能总览

| 功能 | 说明 |
|------|------|
| 🧾 今日 Token | 实时累计当日全部会话的真实 Token 消耗（输入 + 缓存命中 + 输出） |
| 💰 今日费用 | 按官方价格表 + 峰谷时段计算（谷时段自动半价） |
| 💬 交互次数 | 今日你发了多少条消息（`turn/start` 事件计数，每次交互一个 turn，不含工具调用 step） |
| 📈 平均消耗 | 今日平均每次交互的 Token 数 |
| 🔴🟢 峰谷状态圈 | 48px 呼吸状态圈：绿色 = 谷时段（半价），红色 = 高峰（全价） |
| 🕐 实时时钟 | 北京时间（自动处理夏令时无关的 +8 时区），显示时分秒与星期 |
| 📊 配额进度条 | 今日费用 vs 配额上限（默认 ¥10，可通过插件配置 `quotaLimit` 修改），超 70% 变黄、90% 变红 |
| 🟢🔴 峰谷图例 | 谷 0.5× / 峰 1.0× 及官方时段说明 |
| 📋 复制报告 | 一键复制今日用量文字报告到剪贴板 |
| 🔄 刷新 | 立即重新拉取数据（默认每 2 秒自动轮询） |
| 🖱️ 拖拽 | 按住标题栏可拖动悬浮窗到任意位置 |
| ➖ 折叠 | 折叠成小药丸（显示当前费用 + 时段） |
| ✕ 隐藏 | 隐藏悬浮窗（记住状态，F5 后不自动弹出） |

---

## 二、峰谷时段与定价（官方规则）

> 数据来源：<https://api-docs.deepseek.com/zh-cn/quick_start/pricing/>

### 峰谷时段（2026-08-23 官方新规）

| 时段 | 规则 | 系数 |
|------|------|------|
| **工作日** | 峰：北京 09:00–12:00、14:00–18:00；谷：其余时段 | 峰全价 1.0× / 谷半价 0.5× |
| **周末（周六、周日）** | **全天不区分峰谷，统一按低谷价** | 半价 0.5× |

### 官方价格表（元 / 百万 tokens）

| 模型 | 计费项 | 峰 1.0× | 谷 0.5× |
|------|--------|--------:|--------:|
| **deepseek-v4-flash** | 缓存命中 cache-hit | 0.10 | 0.05 |
| | 未命中 cache-miss（输入） | 3.00 | 1.50 |
| | 输出 output | 9.00 | 4.50 |
| **deepseek-v4-pro** | 缓存命中 cache-hit | 0.30 | 0.15 |
| | 未命中 cache-miss（输入） | 9.00 | 4.50 |
| | 输出 output | 27.00 | 13.50 |

> 说明：DeepSeek 计费按实际调用时刻的时段计价（同一请求不拆分）。插件按事件发生时刻判定峰谷。

---

## 三、数据来源（真实，非模拟）

插件在 DSH **服务端**监听会话事件流：

```
DSH 会话事件（session/event）
  └─ assistant/message 事件（携带 TokenUsage：inputTokens / outputTokens / cacheReadTokens / cacheWriteTokens）
       └─ dsh-monitor 累计到今日统计
            ├─ 内存状态（实时 API 响应）
            └─ ~/.dsh/dsh-monitor.json（持久化，每日 00:00 滚存）
```

- 数据来自 DSH 内部事件系统，**不需要浏览器扩展**，不经过页面网络层
- 每次模型调用完成（`assistant/message` 事件）累计一次 Token/费用，不重复计数
- 交互次数按 `turn/start` 事件计数（agent-loop 每次用户交互开启一个 turn），
  一次对话即使包含多步工具调用也只算 1 次；重启后从持久化文件恢复，自然日累计，与 Token 口径一致
- 重启 DSH 后从持久化文件恢复今日累计，继续实时累计

---

## 四、安装（已安装则跳过）

### 4.1 插件源码位置

```
dsh-monitor\
├── package.json          # 插件清单（name/main/exports）
├── lib\
│   ├── index.js          # 服务端：事件监听 + 计费 + 数据 API + UI 注入
│   ├── ui.js             # 前端：悬浮窗 UI（轮询 /api/dsh-monitor）
│   └── types\index.d.ts  # 类型声明
└── README.md             # 本文档
```

### 4.2 注册到 DSH Web 配置

1. **`~/.dsh/profiles/web/package.json`** — 添加依赖：

```json
{
  "name": "dsh-profile-web",
  "private": true,
  "dependencies": {
    "dsh-monitor": "file:./dsh-monitor"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app"
      ]
    }
  }
}
```

> ⚠️ `bundles` 数组只放 bundle 组装包（`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-web-app`），**不要**把单个插件加进 bundles，否则 DSH 启动会卡住。

2. **`~/.dsh/profiles/web/cordis.patch.yml`** — 通过 insert 加载插件：

```yaml
# 你的 profile 补丁层（追加到末尾）
- insert:
    - id: dsh-monitor
      name: 'dsh-monitor'
      config:
        quotaLimit: 50   # 可选：今日配额上限（元），默认 10
```

3. **安装依赖**（在 profile 目录执行）：

```powershell
cd ~/.dsh/profiles/web
corepack pnpm install
```

4. **重启 DSH**：`dsh web`（或你常用的 DSH 启动方式）

### 4.3 验证安装

- 打开 <http://127.0.0.1:3080/>，按 **F5** 刷新
- 右上角出现悬浮窗即安装成功
- 直接访问 <http://127.0.0.1:3080/api/dsh-monitor> 应返回 JSON 数据

---

## 五、使用说明

1. **打开**：启动 DSH 后按 F5 刷新页面，悬浮窗出现在右上角
2. **拖动**：按住面板标题栏（「DEEPSEEK · 监控」一行）拖动到任意位置
3. **折叠**：点标题栏右侧 `–`，收成小药丸（显示当前费用 + 峰谷）
4. **隐藏**：点 `✕`，完全隐藏（状态记忆在 localStorage，F5 后不自动弹出）
5. **复制报告**：点「📋 复制报告」，剪贴板获得今日报告，例如：

```
【DEEPSEEK 用量报告】2026-08-21 · 谷时段·半价
今日 Token: 270,647（输入 2,849 / 缓存命中 266,112 / 输出 1,686）
今日费用: ¥0.0252（高峰 ¥0 / 谷时 ¥0.0252）
交互次数: 3 次
平均消耗: 90,216 Token/次
配额使用: 0%（¥0.0252 / ¥10）
峰谷规则: 峰 北京 09:00-12:00/14:00-18:00 ×1.0 | 谷 其余时段 ×0.5（每天）
模型: deepseek-v4-flash · 单价(当前时段): 缓存命中 ¥0.05/1M · 未命中 ¥1.5/1M · 输出 ¥4.5/1M
```

6. **刷新**：点「🔄 刷新」立即更新（平时每 2 秒自动更新）

---

## 六、数据与持久化

### 6.1 数据结构（`~/.dsh/dsh-monitor.json`）

```json
{
  "date": "2026-08-21",          // 当前统计日（北京时区）
  "tokens": 270647,               // 今日总 Token
  "cost": 0.0252,                 // 今日总费用（元）
  "sessions": 3,                  // 今日交互次数（按 turn/start 计数）
  "inputTokens": 2849,            // 未缓存输入
  "outputTokens": 1686,           // 输出（含推理 token）
  "cacheReadTokens": 266112,      // 缓存命中
  "peakCost": 0,                  // 高峰时段费用
  "valleyCost": 0.0252,           // 谷时段费用
  "history": {                    // 历史记录（保留 90 天）
    "2026-08-20": { "...": "..." }
  }
}
```

### 6.2 每日滚存

- 北京时区 **00:00** 自动把昨日数据存入 `history`，重置今日计数
- 历史保留 **90 天**，超出自动裁剪
- 修改系统时间不会影响（以事件时间戳计算）

### 6.3 费用计算

```
费用 = 缓存命中/1e6 × 缓存单价 + 输入/1e6 × 未命中单价 + 输出/1e6 × 输出单价
（单价按事件时刻的峰谷判定：峰 1.0× / 谷 0.5×）
```

---

## 七、数据 API

前端悬浮窗通过以下接口获取数据，也可供其他用途调用：

```
GET /api/dsh-monitor
```

响应示例：

```json
{
  "ok": true,
  "isValley": true,
  "tier": "valley",
  "stats": {
    "date": "2026-08-21",
    "tokens": 270647,
    "cost": 0.0252,
    "sessions": 3,
    "avgPerSession": 90216,
    "inputTokens": 2849,
    "outputTokens": 1686,
    "cacheReadTokens": 266112,
    "peakCost": 0,
    "valleyCost": 0.0252
  },
  "quota": { "used": 0.0252, "limit": 10, "pct": 0 },
  "prices": {
    "model": "deepseek-v4-flash",
    "peak":    { "cached": 0.10, "uncached": 3.0, "output": 9.0 },
    "offpeak": { "cached": 0.05, "uncached": 1.5, "output": 4.5 }
  },
  "demoMode": false,
  "updatedAt": 1787286745749,
  "peakHours": "北京 9:00-12:00、14:00-18:00（每天）",
  "valleyHours": "北京其余时段（半价 0.5×）"
}
```

---

## 八、配置项

插件当前内置默认值，如需调整请修改 `lib/index.js`：

| 配置 | 位置 | 默认值 | 说明 |
|------|------|--------|------|
| 价格表 | `PRICING` 常量 | flash/pro 官方价 | 官方调价时更新 |
| 配额上限 | `buildPayload()` 中 `quota.limit` | `10`（元） | 配额进度条分母 |
| 统计模型 | `buildPayload()` 中 `model` | `deepseek-v4-flash` | 报告中的模型名与单价 |
| 轮询间隔 | `lib/ui.js` 中 `pollTimer` | 2000ms | 悬浮窗刷新频率 |
| 历史保留 | `maybeRollover()` 中 `90` | 90 天 | 滚动窗口 |

---

## 九、常见问题（FAQ）

**Q1：悬浮窗没出现？**
A：F5 刷新页面；确认 index.html 已注入（查看源码搜 `dsh-monitor/ui.js`）；确认 DSH 是重启后的新实例（`Get-NetTCPConnection -LocalPort 3080` 看进程启动时间）。

**Q2：数字一直是 0？**
A：确认发生了真实对话（发一条消息）；访问 `/api/dsh-monitor` 看 `_diag` 字段：
- `eventsSeen` 为 0 → 事件监听未生效（插件未加载，检查 cordis.patch.yml）
- `eventsSeen > 0` 但 `assistantMessages` 为 0 → 没有完成过模型回复
- `withUsage` 为 0 → 模型适配器未上报 usage
- `accumulated > 0` → 正常累计

**Q3：重启 DSH 后今日数据还在吗？**
A：在。启动时从 `~/.dsh/dsh-monitor.json` 恢复。若文件缺失（如手动删除），从 0 开始。

**Q4：费用是模拟数据吗？**
A：不是。全部来自 DSH 会话事件的真实 `TokenUsage`（input/output/cacheRead），按官方价格表与峰谷规则计算。

**Q5：和浏览器扩展版有什么区别？**
A：浏览器扩展版依赖注入页面网络层，在 DSH 上无法捕获（DSH 模型请求走 Node 后端）。DSH 插件版直接在服务端读事件流，数据更准确，且无需浏览器扩展。**DSH 环境下请使用本插件**；浏览器扩展版仍适用于 chat.deepseek.com 网页端。

---

## 十、卸载

1. 从 `cordis.patch.yml` 删除 `- insert: [...] dsh-monitor` 条目（或整体还原为 `[]`）
2. 从 `package.json` 的 `dependencies` 删除 `"dsh-monitor": "file:..."` 行
3. `corepack pnpm install`（清理 node_modules 链接）
4. 重启 DSH

---

## 十一、开发与调试

```powershell
# 语法检查
node --check lib/index.js
node --check lib/ui.js

# 单独启动测试实例（不影响正式 3080 实例）
dsh web --port 3090 --no-open
# 然后访问 http://127.0.0.1:3090/api/dsh-monitor

# 修改插件源码后同步到 profile（file: 链接）：
cd ~/.dsh/profiles/web
corepack pnpm install
# 再重启 DSH
```

> ⚠️ 修改 `lib/index.js` 后，必须 `corepack pnpm install` 同步链接 + 重启 DSH 才生效（`lib/ui.js` 是运行时读取的，但 `index.js` 的注入逻辑也需要重启）。

---

## 版本记录

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.3.0 | 2026-08-23 | 适配官方新规：周末（周六/周日）全天低谷价，工作日维持原峰谷时段 |
| 1.2.1 | 2026-08-21 | 修复交互次数重启清零；交互口径改为 `turn/start`（每次交互一个 turn，web 直连消息也能可靠计数） |
| 1.2.0 | 2026-08-21 | 配额上限改为可配置（`config.quotaLimit`，默认 10），无需改代码 |
| 1.1.0 | 2026-08-21 | 交互次数改为按用户消息计数（`user/message` + `source.kind=user` 过滤），修复多步工具调用虚高问题 |
| 1.0.0 | 2026-08-21 | 首个 DSH 插件版：真实事件累计、官方峰谷定价、悬浮窗 UI、每日滚存 |