DeepSeek Harness 插件：CacheScope - Prompt 缓存可观测性与输入诊断

在开发 DeepSeek 智能体或使用 DeepSeek Harness（DSH）进行模型调优时，调试 Prompt 缓存命中率往往依赖于 Provider 控制台的反馈，难以在本地快速定位是哪部分输入变化导致了缓存未命中。CacheScope 插件直接在 DSH 侧记录 llm/stream 尝试，并提供桌面仪表盘，展示 Provider 报告的缓存 Token 使用量，并对比 DSH 侧相邻逻辑输入的差异。

核心功能¶

CacheScope 主要提供以下能力：

• 桌面仪表盘：记录并展示已观察到的 LLM 调用尝试，无需修改模型请求或注册模型可见的工具。
• 诊断能力：
  • 对比两轮对话，分析 Provider 缓存读取率。
  • 检查相邻输入诊断和彩色输入树。
• 筛选与管理：支持按会话、提供商、模型、目的、生命周期和证据进行筛选，支持诊断排序、实时跟随以及复制元数据。

安装与启用¶

在 Web 配置文件中安装该插件并启动 DSH：

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

安装完成后，在浏览器打开 http://127.0.0.1:3080/cachescope 即可访问仪表盘。

典型用法：快速开始¶

以「快速开始：比较两轮对话」为例：

1. 在 DSH 对话中发送第一条消息。这一步会创建本地的比较基线。
2. 在同一个 Session 中发送第二条消息，保持 Provider、模型、System Prompt 和启用的工具不变。
3. 在 CacheScope 中选中第二次对话调用。查看顶部的 Provider Cache Read 比率，然后检查相邻输入诊断和彩色输入树。

适用场景与注意¶

• 适用场景：需要直观了解 Prompt 缓存使用情况，排查缓存命中率变化原因的开发者。
• 隐私注意：安装的插件包默认开启 captureInput: full。默认情况下，DSH 进程内存中最多保留最近的 12 个完整逻辑输入，每个输入最大 2,000,000 UTF-8 JSON 字节。如果不需要检查完整输入，建议在配置中使用 captureInput: metadata。

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

• 数据与访问：
  • 尝试记录和保留的完整输入仅存在于 DSH 进程内存中，DSH 进程停止后，服务器端的副本会消失。
  • 仪表盘仅在 DSH WebServer 绑定到 127.0.0.1 时注册。
  • 复制 JSON 功能会将选中的完整输入写入操作系统剪贴板。
• 指纹说明：元数据指纹使用进程内的随机 HMAC 密钥生成，无法跨进程重启进行比较。

CacheScope 提供了本地 Prompt 缓存的可观测性，帮助开发者在不依赖外部控制台的情况下快速诊断输入变化与缓存策略的关系。更多详情请查阅插件目录或 GitHub 仓库。