🧮 dsh-cache-cost-monitor

让 DeepSeek 的每一分钱都花在刀刃上 —— 前缀缓存命中率、费用与健康度，一眼看穿。

DSH（DeepSeek Harness）v0.1.x 的 Cordis 插件：自动监听每一轮 Agent 的模型 API 调用，提取 prompt_cache_hit_tokens / prompt_cache_miss_tokens / completion_tokens，实时统计缓存命中率与按官方定价（含峰谷时段）预估的 API 费用，并给出缓存健康度评级与趋势火花线。

✨ 它为什么值得收藏

🏗️ 架构一览

flowchart LR
  A[Agent 会话] -->|"每次模型调用<br/>llm/stream 瀑布流"| B[dsh-cache-cost-monitor 宿主]
  B --> C[CacheStats 统计器<br/>累计/趋势/分桶/预算]
  C --> D[cache_report 工具<br/>模型可直接调用]
  B --> E[sessionProjections<br/>cacheCost 投影]
  E --> F[消息末尾页脚<br/>conversation.chat.turnTail]
  E --> G[常驻统计条<br/>conversation.composer.dock]

宿主侧（Node）负责监听与统计；浏览器侧（React）只读投影快照渲染 UI。两者通过 DSH 官方能力缝连接，无任何私有 API。

🎬 效果预览

输入框下方的常驻统计条（实时，随每轮更新）：

⌀ 1.2M tokens · ¥2.01 · 命中 68% ▂▅▇█

每条助手消息末尾的页脚（低调，hover 可看命中/未命中/输出明细）：

本轮 12.3K tokens · ¥0.0123

启动日志 banner（一眼确认插件状态）：

╔══════════════════════════════════════════════════════════╗
║   dsh-cache-cost-monitor  v0.3.0                         ║
║   缓存命中率 · 费用预估 · 峰谷计价 · 健康度评级          ║
╚══════════════════════════════════════════════════════════╝

cache_report 报表开头（模型一句话即可召唤）：

# 缓存命中率与成本报告（cache_report）

> 📊 **摘要**：命中率 68.4% · 费用 $0.0312（¥0.2122）· 12 轮 · 健康度 B 🟡

## 累计统计
- 模型调用次数：12
- 累计缓存命中率：68.4%
...

## 命中率趋势（最近 5 轮，右为最新）
> 火花线：▂▅▇█▅
| 轮次 | 模型 | ... | 单轮命中率 | 单轮费用 |
| --- | --- | --- | --- | --- |
...

📦 安装

前置

• Node.js >= 18
• pnpm（corepack enable 或 npm i -g pnpm）
• DSH v0.1.x

方式一：一键脚本（本地开发）

cd dsh-cache-cost-monitor
npm install && npm run build && npm test
powershell -ExecutionPolicy Bypass -File scripts\install-profile.ps1

方式二：从 GitHub 安装（仓库即发布源）

# 固定版本（推荐）
dsh plugin --profile web add https://github.com/eurt-nano/dsh-cache-cost-monitor.git#v0.3.0 --config.node-linker=isolated

# 或最新 main
dsh plugin --profile web add https://github.com/eurt-nano/dsh-cache-cost-monitor.git#main --config.node-linker=isolated

方式三：Release 附件

从 Releases 下载 dsh-cache-cost-monitor-0.3.0.tgz，本地解压后按方式一安装。

Windows 说明：pnpm workspace 对盘符绝对路径创建链接存在 bug，安装/移除命令请保留 --config.node-linker=isolated；git 安装时若 pnpm 拦截构建脚本，把 dsh-cache-cost-monitor 加入 profile 的 pnpm-workspace.yaml 的 allowBuilds 列表。

安装后 重启 DSH（dsh web），页脚与统计条需刷新浏览器页面。

🎮 使用

1. 召唤报表：对 Agent 说「调用 cache_report」，或让它「看看缓存命中率和花了多少钱」。 可选参数：{ "detail": true, "limit": 10 } 输出逐轮明细（含计价档位、实际单价、时间戳）。
2. 看常驻统计条：输入框下方实时累计消耗，无需任何操作。
3. 看页脚：每条助手回复末尾的灰字小标。
4. 看日志：[cache-monitor] 前缀的 warn/info 输出告警与启动信息。

⚙️ 配置参考（cordis.patch.yml）

内置定价（cacheHit / cacheMiss / output）：

未配置的模型按 0 计费并在报表中标注；deepseek-v4-* 变体按前缀回退。

📈 健康度评级规则

❓ FAQ

Q：数据存在哪？重启后还在吗？ cache_report 的进程内累计统计随 DSH 重启归零；每条消息的页脚数据来自会话投影（随会话落库，重启后历史轮次仍可显示）。

Q：为什么我的消息末尾没有页脚？ 页脚只显示插件安装之后、且 API 响应携带 usage 的轮次；产出了文件的轮次会让位给官方 "Produced" 行。tokens 直接读会话快照（引擎自带每轮 usage），人民币费用经 cacheCost 投影（v0.3.1 起宿主注入 sessionProjections，保证投影注册）；升级后请重启 DSH 并刷新页面。

Q：费用是精确的吗？ 按「配置定价 × 实际 token 数」估算，不含折扣、重试与网关加价；未配置定价的模型按 0 计。官方调价后在 config.pricing 覆盖即可。

Q：页脚不显眼，我想更醒目/更隐蔽？ 样式是 CSS 变量 + 透明度控制，可在浏览器端自行调整；也欢迎提 issue 增加配置项。

🗺️ Roadmap

• [ ] 跨会话累计统计持久化（重启不丢）
• [ ] 报表导出 Markdown / CSV / JSON 文件
• [ ] 缓存失效原因诊断（compaction/动态注入检测）
• [ ] 告警通道扩展（Webhook / 桌面通知）
• [ ] 峰谷时段本地化配置（自定义时区窗口）

有想法？欢迎 提 issue 或 PR。

🤝 贡献

npm run build    # tsc 宿主 + tsdown 客户端
npm test         # 42+ 项冒烟测试，改代码请保持全绿

• 宿主逻辑为纯 ESM，可脱离 DSH 用 test/smoke.mjs 的假 ctx 驱动验证；
• 客户端组件使用 React.createElement，平台模块由 shell 模块表提供。

📄 License

MIT © 2026 eurt-nano

English README：README.en.md