前言¶
DSH 使用插件扩展工作流。在多轮 Agent 调用中，模型 API 通常会返回 token 用量，但开发者还想知道前缀缓存是否命中、每一轮大约花了多少钱、累计费用是否接近预算。dsh-cache-cost-monitor 是 DSH v0.1.x 的 Cordis 插件，用于把这些信息从日志和响应字段里整理成可观察的指标。
这是什么¶
eurt-nano/dsh-cache-cost-monitor 是一个 MIT 许可的 DSH 插件。它监听每一轮 Agent 的模型 API 调用，提取 prompt_cache_hit_tokens、prompt_cache_miss_tokens 和 completion_tokens，实时统计缓存命中率，并按官方定价（含峰谷时段）预估 API 费用。
插件会注册 cache_report 工具，让 Agent 可以主动查看缓存命中率和费用。它也在浏览器侧显示常驻统计条和每条助手回复末尾的本轮 tokens、人民币消耗。
核心功能¶
统计缓存与费用¶
插件提取以下字段：
prompt_cache_hit_tokens
prompt_cache_miss_tokens
completion_tokens
基于这些字段，它实时统计缓存命中率，并按官方定价（含峰谷时段）预估 API 费用。
提供 cache_report 工具¶
cache_report 是插件注册给 Agent 的工具。它可以输出缓存命中率、费用和缓存健康度信息，并给出趋势火花线。
显示常驻统计条¶
在浏览器中，插件可以在输入框下方显示常驻统计条，实时显示 tokens、费用和命中率。
在消息末尾显示本轮消耗¶
插件会在每条助手回复末尾显示本轮 tokens 与人民币消耗。
阈值与预算告警¶
插件支持 threshold 与 cumulativeThreshold 阈值告警，也支持 budgetUsd 费用预算与超支告警。
异常时降级¶
字段缺失、无定价、服务不可用等异常情况下，插件只记录日志，不拖垮主程序。
安装与启用¶
前置要求：
Node.js >= 18
pnpm
DSH v0.1.x
固定版本安装命令：
dsh plugin --profile web add https://github.com/eurt-nano/dsh-cache-cost-monitor.git#v0.3.0 --config.node-linker=isolated
安装后需要重启 DSH：
dsh web
页脚与统计条需要刷新浏览器页面。
Windows 下安装或移除时，需要保留：
--config.node-linker=isolated
如果 git 安装时 pnpm 拦截构建脚本，需要把 dsh-cache-cost-monitor 加入 profile 的 pnpm-workspace.yaml 的 allowBuilds 列表。
典型用法¶
可以直接对 Agent 说：
调用 cache_report
也可以让它：
看看缓存命中率和花了多少钱
如果需要逐轮明细，可以传可选参数：
{ "detail": true, "limit": 10 }
该参数用于输出逐轮明细，包含计价档位、实际单价和时间戳。
也可以直接看插件提供的界面：
- 看常驻统计条：输入框下方实时累计消耗，无需任何操作。
- 看页脚：每条助手回复末尾显示本轮 tokens 与人民币消耗。
- 看日志：
[cache-monitor]前缀的 warn/info 输出告警与启动信息。
适用场景与注意¶
这个插件适合使用 DSH v0.1.x、希望观察缓存命中率和 API 费用估算的开发者。插件以当前 dsh 进程权限运行，安装前建议先检查源码与许可证。
费用按“配置定价 × 实际 token 数”估算，不含折扣、重试与网关加价；未配置定价的模型按 0 计。
cache_report 的进程内累计统计随 DSH 重启归零；每条消息页脚数据来自会话投影，重启后历史轮次仍可显示。页脚只显示插件安装之后且 API 响应携带 usage 的轮次。
参考¶
仓库地址：
https://github.com/eurt-nano/dsh-cache-cost-monitor
