dsh-readcache：DSH read 工具的版本令牌校验缓存

长会话中，智能体会反复重读未变更的文件。在上下文压缩恢复、并行子代理、编辑前后对比等场景下，每一次重复都要进行文件 I/O 和行号渲染，而读取到的字节内容完全相同。dsh-readcache 为 DSH read 工具提供版本令牌校验的进程内结果缓存，拦截 tools/execute 事件瀑布，让这些重复读取直接命中缓存，从而减少 I/O 和渲染开销。

核心功能¶

结果缓存：为 DSH read 工具提供结果缓存，未变更文件的重复读取跳过文件 I/O。
版本令牌校验：每次命中缓存时，都会重新 stat 文件，要求版本令牌精确匹配（本地后端为 dev:ino:size:mtimeNs:ctimeNs）。任何写路径（如 edit/write 工具、bash、外部编辑器）都会改变令牌并立即失效对应条目。
代理隔离：缓存键包含代理 id。文件系统的观察门要求每个代理编辑前必须自己读过该文件；按代理隔离键值保证每次命中都以该代理自己的先前观察为凭据。
内存管理：采用 LRU 策略，上限为 300 条 / 总量 16 MiB / 单条 4 MiB。
安全防护：
无写入竞态：未命中时，执行结果只有在二次 stat 仍报告执行前令牌的情况下才会入缓存（双 stat 防护）。
仅缓存有效结果：只有 read 工具的成功、非中止、可无损 JSON 序列化的结果才会入缓存；失败结果原样透传。

安装与启用¶

使用官方命令安装：

dsh plugin --profile web add dsh-readcache

或从本地检出安装：

cd dsh-readcache && npm pack
dsh plugin --profile web add ../dsh-readcache/dsh-readcache-1.0.1.tgz

安装后重启 DeepSeek Harness 生效。

典型用法¶

插件注册了一个模型可见的工具 readcache，action 可为 "stats" 或 "clear"。

查看统计信息¶

输入以下内容查看缓存命中情况：

{
  "action": "stats"
}

stats 输出包含 hits, misses, savedChars, entries 等统计信息。示例：

{
  "hits": 2,
  "misses": 4,
  "hitRatio": 33.3,
  "stale": 1,
  "stores": 4,
  "evictions": 0,
  "savedChars": 1210,
  "clearedEntries": 0,
  "entries": 3,
  "cachedChars": 1662,
  "maxEntries": 300
}

清空缓存¶

输入以下内容清空所有缓存条目：

{
  "action": "clear"
}

适用场景与注意事项¶

适用场景：长会话、上下文压缩、并行子代理、编辑前后对比等需要频繁重复读取同一文件的场景。
注意事项：
仅支持可无损 JSON 序列化的结果入缓存。
缓存完全在宿主进程内运行。
客户端仪表盘功能在 v1.1 路线图。
插件以当前 DSH 进程的权限运行，安装前应检查源码与许可证。

链接¶

GitHub：https://github.com/yongshuai0314/dsh-readcache
目录：https://www.skillhub.cn/plugins/yongshuai0314/dsh-readcache