kober-basket/dsh-cachescope

CacheScope

English | 中文

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

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

截图使用合成调用数据，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 的可复制元数据。

如何理解证据

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

配置

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

可选价格配置

请按当前 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:<port> 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