kober-basket/dsh-cachescope

CacheScope

看懂一次模型调用究竟命中了多少 Prompt Cache，以及没命中时输入哪里变了。

CacheScope 将 Provider 回传的缓存 Token 用量与相邻 DSH 逻辑输入的变化放在同一页。它记录观察到的 llm/stream 调用，并在不修改模型请求、不注册模型可见工具的前提下提供桌面诊断页。

CacheScope 诊断页：Provider 缓存用量、相邻输入变化与层级输入检查器

截图使用合成调用数据，Provider 数字仅用于展示。

安装

将组合包安装到 Web profile，然后启动 DSH：

dsh plugin --profile web add @kober-basket/dsh-cachescope
dsh web

打开 http://127.0.0.1:3080/cachescope。

Prompt 隐私提醒：安装包默认启用 captureInput: full。默认情况下，DSH 进程内存最多保留最近 12 次完整逻辑输入，每次上限为 2,000,000 UTF-8 JSON 字节。如不需要检查完整输入，请在发送敏感 Prompt 前改为下面的仅元数据配置。

- id: cachescope
name: '@kober-basket/dsh-cachescope'
config:
captureInput: metadata

修改 profile 后请重启 DSH。

快速开始：比较两轮会话

1. 在一个 DSH 对话中发送第一条消息，建立本地比较基线。
2. 在同一 Session 中发送第二条消息，期间不要更换 Provider、模型、System Prompt 或已启用工具。
3. 在 CacheScope 中选择第二次对话调用。先看顶部该调用的 Provider Cache Read 比例，再检查相邻输入诊断和带颜色的输入树。

插件观察到的第一次调用没有本地比较基线。如果 Provider adapter 没有携带 Cache Read usage 字段，Cache Read 也会保持“未报告”；字段缺失不按零处理。

表格初始只筛选对话调用。清空用途筛选即可纳入标题生成、压缩和直接模型调用。

可以诊断什么

- 单次调用有多少 Prompt 被报告为 Cache Read，以及未缓存输入、Cache Write、输出和当前筛选内仍保留调用的 Token 加权聚合。
- 相邻可比较调用的未缓存 Token 桶为何变化：本次未缓存 = 上次未缓存 + ΔPrompt − ΔCache Read − ΔCache Write。
- DSH 逻辑输入是完全相同、仅末尾追加，还是发生了 System、Tools、路由或参数变化以及历史改写。
- 哪些输入区域是稳定前缀候选、本地首个差异、受前置变化影响的下游区域，或没有可比较基线的区域。
- Call TTFT、中位和 P95 Call TTFT、总耗时、状态、用途、Provider、模型、重试和可选本地成本估算。
- Session、Provider、模型、用途、生命周期和证据筛选，诊断排序、实时跟随，以及用于 Issue 或 Discussion 的可复制元数据。

如何理解证据

| 证据 | 来源与含义 | 不代表 |
|---|---|---|
| 选中调用的 Cache Read / Prompt | DSH adapter 对该次调用 Provider usage 的标准化结果。 | 本地 Diff 比例或 DeepSeek 控制台聚合。 |
| 当前筛选的加权比例 | 对当前仍保留且可见、并携带 Cache Read 的调用计算 Σ Cache Read / Σ Prompt。 | Provider 控制台可能采用的不同时间窗口和调用集合。 |
| 未缓存输入 | Adapter 标准化后的未缓存输入 Token 桶。 | 回复长度，或本轮新增、变化的 Token 数量。 |
| 输入树颜色 | 与同一 Session、同一用途的上一条进程内调用比较。 | Provider 将某区域用作 cache key，或这些具体 Token 确实来自缓存。 |
| Token 对账 | 解释相邻已报告 Token 桶如何变化的算术关系。 | Provider cache key、Token offset 或缓存决策原因。 |
| Call TTFT | 从 CacheScope 开始迭代模型流到首个非空 Token 的时间。 | 独立的 Provider Prefill 耗时；其中还包含排队和网络时间。 |

Output Token 不进入任何缓存比例。输入层级展示 Provider 专用序列化之前捕获的 DSH 逻辑模型输入，因此可能与实际 wire payload 不同。

配置

Schema 默认值用于直接挂载插件的场景。发布的可安装组合包只会将 captureInput 覆盖为 full；profile 自己的 patch 始终具有最终决定权。

| 配置键 | Schema 默认值 | 安装包实际值 | 作用 |
|---|---:|---:|---|
| captureInput | metadata | full | 只保留指纹和指标，或保留受限的完整逻辑输入。 |
| maxAttempts | 500 | 500 | 进程内存中最多保留的调用次数，超出后淘汰旧调用。 |
| rawRetentionAttempts | 12 | 12 | 最多允许保留完整输入的近期调用次数。 |
| maxRawInputBytes | 2000000 | 2000000 | 单次完整输入允许保留的最大 UTF-8 JSON 字节数。 |
| refreshMs | 1500 | 1500 | 诊断页轮询间隔，单位为毫秒。 |
| logAttempts | true | true | 每次调用后输出一条仅含元数据的摘要。 |
| includeAuxiliary | true | true | 纳入压缩、标题生成和直接调用。 |
| dashboard | true | true | WebServer 绑定到回环地址时注册诊断页。 |
| pricing | 未设置 | 未设置 | 用于本地成本估算的可选币种与每百万 Token 单价。 |

可选价格配置

请按当前 Provider 价格表填写全部四项费率；CacheScope 不内置或更新价格表。

- id: cachescope
name: '@kober-basket/dsh-cachescope'
config:
pricing:
currency: CNY
uncachedInputPerMillion: 0 # 请替换为当前费率
cacheReadPerMillion: 0 # 请替换为当前费率
cacheWritePerMillion: 0 # 请替换为当前费率
outputPerMillion: 0 # 请替换为当前费率

在依赖成本估算前，请替换全部零值。CacheScope 使用标准化 usage 字段和你填写的数值；示例不包含任何当前或推荐 Provider 价格。

数据处理与本机访问

- 调用记录和保留的完整输入位于 DSH 进程内存中。DSH 进程停止后，服务端副本消失。
- 完整输入可能包含 System Prompt 正文、工具 schema、消息和请求参数。设置 captureInput: metadata 可禁止保留 Prompt 正文。
- 元数据指纹使用每个进程随机生成的 HMAC 密钥，无法跨次启动比较。
- 轮询响应只包含元数据。诊断页通过独立接口读取当前选中的完整输入，响应使用 Cache-Control: no-store，展示期间内容会保留在当前页面的 JavaScript 内存中。
- 点击复制 JSON还会将选中的完整输入写入操作系统剪贴板；在内容被替换或清除前，它可能比页面和 DSH 进程存在得更久。
- logAttempts 只输出元数据摘要；这些日志是否持久保存取决于宿主日志配置。
- 只有 DSH WebServer 绑定到 127.0.0.1 时才注册诊断页。请求必须来自回环地址、使用预期的 127.0.0.1: Host，并在 Origin 和 Sec-Fetch-Site 请求头存在时通过检查。
- 这些检查用于降低浏览器跨站访问风险，不提供身份认证，也不能隔离能够构造合规回环请求的其他本机进程。

请将 captureInput: full 视为允许本机访问完整模型输入。

技术说明与限制

- Provider usage 只暴露 Token 总量，不提供 cache key 或 Token offset。前缀稳定只是诊断证据，不是 Provider 缓存结论。
- 本地比较无法观察其他进程、插件加载前或已从内存淘汰的调用。
- 插件优先使用 DSH 跨包共享的 AgentLoop 请求身份识别对话。对于身份注册表只在模块副本内有效的旧版 DSH，携带 Session id 的未分类请求按对话处理；没有 Session id 的未分类请求仍按直接调用处理。
- 每次重试作为独立调用保留。Call TTFT 是 Prefill 代理指标，不是 Prefill 执行时间的直接测量值。

卸载

dsh plugin --profile web remove @kober-basket/dsh-cachescope

修改 profile 后请重启 DSH。

开发

npm install
npm run typecheck
npm test
npm run build
npm pack --dry-run

许可证

MIT