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