# dsh-damage-pulse

> 监控 DSH 每次模型调用的 Token 用量与金额，在余额悬浮卡上以扣血动画呈现每笔扣费，并自动校准 DeepSeek 账户实时余额。

## Metadata

- Author: [@wssfk12138](https://github.com/wssfk12138)
- Repo: <https://github.com/wssfk12138/dsh-damage-pulse.git>
- GitHub: [wssfk12138/dsh-damage-pulse](https://github.com/wssfk12138/dsh-damage-pulse)
- Stars: 73
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `balance-monitor`, `damage-animation`, `deepseek`, `deepseek-harness`, `dsh`, `dsh-plugin`, `token-monitor`, `token-usage`
- Forks: 2
- Open Issues: 0
- Last push: 2026-08-19T08:54:54.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:wssfk12138/dsh-damage-pulse
```

## Wiki

## 一句话定位
把 DeepSeek Harness（DSH）每次模型调用的 Token 用量与金额，以游戏式「扣血」动画直观呈现的余额监控插件；同时实时拉取 DeepSeek 官方账户余额并自动校准，让用户在聊天的过程中就能直观感受每一笔扣费。

## 核心能力
- 在每次模型调用结束后，对话流内插入一行单次用量明细（输入 / 缓存命中 / 输出 / 推理）与精确金额
- 输入框上方持续显示当前会话累计的 Token 数与累计金额
- 余额悬浮卡片按本地精确扣减每一笔费用，并在余额数字上飘出红色扣费数字、伴随受击回弹动画
- 缓存未命中或缓存写入时，触发更强的红色「未命中」动画与短促横向抖动；纯缓存命中走普通命中动画
- 每 60 秒拉取一次 DeepSeek 官方账户余额进行校准；检测到余额上涨时飘出绿色「加费」数字
- 余额卡片右下角显示「峰 / 谷」标识，结合北京时间峰谷时段带红绿灯发光效果
- 把每笔单次用量明细以 JSONL 追加到本地，便于历史查询与按会话过滤

## 技术实现
- **语言**: TypeScript + React 18
- **关键依赖**: `@deepseek-ai/cordis`、`@deepseek-ai/schemastery`、`zod`、`react`
- **架构模式**: 标准 DSH Host + Client 组合包；Host 通过 `cordis.patch.yml` 注入 `dsh-damage-pulse` 插件，Client 通过 package.json 的 `dsh.client.inject` 声明注入到 `dsh-client-runtime` / `dsh-client-ui-conversation` / `dsh-client-ui-layout`。Host 监听 `session/event` 采集每次调用 → 注册 `tokenCost` session projection → 注册余额 / 用量 / 扣费事件三个 HTTP 端点；Client 占用 `conversation.chat.node`、`conversation.composer.dock`、`shell.overlay` 三个 slot 渲染 UI。
- **入口文件**: `lib/index.js`（Host 打包产物，对应源码 `plugins/dsh-token-monitor/src/index.ts`）；`lib/client.js`（Client 打包产物，对应源码 `packages/client/ui-token-monitor/src/client/index.ts`）

## 适用场景
重度使用 DeepSeek 模型（尤其启用上下文缓存）的用户，希望在每次扣费时立即看到精确金额和扣血反馈，避免一天下来才发现累计消耗超出预算。普通用户也能用它在聊天过程中直观感受「这笔回答花了多少钱」、缓存命中率带来的省钱效应，以及峰谷时段差价。

## 前置依赖与兼容性

| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | ^0.1.0-rc.5 | Host 端需要 cordis、session-projection、session-projection-cache、session-persistence、host-webserver、credentials、session、llm、settings 等服务 |
| Node.js | ^22.19.0 或 >=24.0.0 | 仓库 engines 字段声明 |
| 平台 | 跨平台 | 浏览器 Web profile 使用，无原生二进制依赖 |
| 原生模块 | 无 | 不依赖 node-pty、sqlite、better-sqlite3 等 |

> 说明：本插件仅在 DSH 的 Web profile 中使用（`--profile web`），因为 Client bundle 是浏览器端 React 包。

## 安装方式
```bash
dsh plugin --profile web add github:wssfk12138/dsh-damage-pulse
```
安装后用 `dsh --profile web` 重启 Web profile，余额卡片、单次用量行、输入区会话累计、扣血动画即可生效。

## 配置项

| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `DEEPSEEK_API_KEY`（凭据） | 字符串 | 通过 DSH 凭据系统（~/.dsh/.credentials.yaml）配置；不配置时余额卡片显示「未配置」态，Token 计量与扣血动画仍正常工作 | 未配置 |
| settings namespace `dsh-token-monitor` → `priceTable` | 对象 | 自定义价格表，覆盖内置 2026-08-17 峰谷价；旧价格（2026-08-17 前）的历史费用不受影响 | 内置 PRICE_TABLE |
| 高峰时段（仅内置） | 时段数组 | 北京时间 9:00-12:00、14:00-18:00；峰谷用红 / 绿发光标识直接呈现 | 不可配置 |

> 说明：本插件没有运行开关；安装即启用，余额 / 用量 / 扣费事件三个 HTTP 端点由 Host 自动注册。

## 常见问题

**Q: 余额卡片显示「未配置 API Key」怎么办？**

A: 需要在 DSH 凭据系统里配置 `DEEPSEEK_API_KEY`（写入 `~/.dsh/.credentials.yaml`）。未配置只会让余额卡片显示未配置态，不会影响 Token 计量和扣血动画。

**Q: 每次扣费会立刻从余额里扣掉吗？**

A: 余额是按本地精确扣减的：每次模型调用结束后立刻减去精确金额并触发扣血动画；同时每 60 秒拉取一次 DeepSeek 官方余额进行校准。如果官方余额比本地显示的多，会自动出现绿色「加费」动画。

**Q: 缓存命中和缓存未命中有什么区别？**

A: 纯缓存命中只显示普通红色扣费数字；只要一次调用中存在缓存未命中输入或缓存写入，就会触发更强的红色「未命中 -x.xx¥」动画，并伴随短促横向抖动和更大的余额回弹。同一秒内合并的多笔扣费，只要有一笔属于未命中，整组按未命中播放。

**Q: 安装后看不到任何动画怎么办？**

A: 确认已用 `dsh --profile web` 重启安装目标的 profile。如果以前用过源码集成版，请先移除手工 patch 与重复挂载，避免同一插件加载两次。

**Q: 旧会话为什么一开始没有金额？**

A: 插件启动时会自动为缺失 Token 金额投影的历史会话触发一次冷读 fold，几秒后页面就会显示金额。投影一旦写入 checkpoint，下次启动无需再次补齐。

**Q: 左侧会话列表为什么没有累计金额？**

A: DSH 目前没有开放「左侧会话行尾部信息」的第三方 slot，因此标准包不会修改宿主 DOM。如果使用完整 DSH 源码并确实需要该功能，可以运行仓库里的侧边栏集成脚本修改源码，但这不是标准包的能力。

**Q: 可以自己覆盖价格表吗？**

A: 可以。在 settings namespace「dsh-token-monitor」的 `priceTable` 字段填入自定义价格即可覆盖内置表；旧价（2026-08-17 涨价前）的费用会按当时时间戳自动使用旧价，不会重算。

## 上手难度
入门 — 安装一行命令即可使用，所有功能默认开启；只有想覆盖价格表或调整峰谷时段时才需要进一步设置。

## 已知问题与限制
- 公开品牌虽已更名为 `dsh-damage-pulse`，但插件运行标识 / settings namespace / localStorage 键 / 数据目录 / API 路径仍沿用旧名 `dsh-token-monitor`，以保证已安装用户的兼容，暂未做全量重命名
- 缓存扣血动画会把同一秒内合并的多笔扣费合并成一次飘字；连续扣费最多同时保留三组飘字，多余的会被覆盖
- 标准包不会修改宿主 DOM，DSH 左侧会话列表尾部不显示累计金额；该功能只对完整 Harness 源码可用，且需要执行独立的侧边栏集成脚本
- 价格表内置版本为 2026-08-17 峰谷价（高峰：北京时间 9:00-12:00、14:00-18:00）；模型名按前缀匹配（如 `deepseek-v4-pro` 命中 `deepseek-v4-pro-xxx`），未匹配模型时按 flash 高峰价兜底
- 扣费明细按 JSONL 追加到本地 `~/.dsh/data/dsh-token-monitor/usage.jsonl`，冷启动自动回读；损坏行会静默跳过

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-damage-pulse](https://deepseek-plugin.org/plugins/wssfk12138/dsh-damage-pulse)
Wiki generated by AI (model: `MiniMax-M3`)