dsh-coldread-cache：DSH 長會話解析優化插件

DeepSeek Harness（DSH）插件：保留會話的已解析事件日誌常駐，以便本地擴展擴展常駐解析而非使其失效——長會話按主機進程解析一次，而非每次讀取一次。

前言¶

DSH 的 session-persistence-jsonl 後端緩存限制只有兩條，且以 stat 推導出的 revision 作爲鍵。每次追加都會改變 revision，導致正在寫入的會話幾乎每次讀都緩存未命中。未命中意味着一次整份冷讀：整個文件讀取、逐幀解碼、逐行解析。長會話隨着輪次增加，這種開銷會直接導致界面卡頓。

本插件旨在解決這個問題。它不修改 DSH 安裝目錄裏的任何文件，僅在運行中的持久化後端實例上寫入自有屬性。

核心功能¶

常駐會話解析日誌：爲每個會話保留一個常駐解碼器。
追加時擴展常駐解析而非重建：文件未變時直接返回；文件變長時只讀新增字節，解碼後餵給常駐解碼器追加。
長會話按進程只解析一次：同一個文件在進程生命週期內只解析一次。
處理 freezeStoredEvents：後端在返回結果前會調用 freezeStoredEvents 凍死事件數組。插件必須讓常駐解碼器保持未凍結，每次讀發一份凍結副本，避免報錯“object is not extensible”。
正確性保證：僅在能夠證明等價時才複用常駐結果。文件路徑相同、只增長、尾部幀完整、格式約束成立等條件滿足時才走擴展路徑。

安裝與啓用¶

插件由 profile 加載。推薦使用 DSH 自帶的插件命令安裝：

dsh plugin --profile <name> add dsh-coldread-cache

手工掛載需同時修改三處：
* <profile>/package.json：在 dependencies 和 dsh.profile.bundles 中添加本包。
* <profile>/cordis.patch.yml：添加插入行。

配置說明¶

插件提供以下配置項：

鍵	默認值	含義
`enabled`	`true`	允許從常駐結果直接返回
`maxEntries`	`8`	本進程常駐的會話數
`maxResidentBytes`	`134217728`	常駐源字節總量
`statusFile`	`""`	可選的實時診斷文件路徑

內存預算計算：預算按壓縮後的源字節計算，但實際佔用的是堆。實測一份解析出來的日誌約等於源字節的 8 倍。默認 128 MB 預算大約值 1 GB 堆。

淘汰順序：被寫入過的會話優先於只被讀過的會話。同級之間按最近讀取淘汰，最後一條永不淘汰。

行爲與監控¶

插件運行時會在日誌中輸出統計信息，格式如下：

hits=4 ext=0 cold=1

hits：命中常駐。
ext：擴展常駐解析（追加後讀同一會話）。
cold：整份冷讀（文件結構變化或無法證明等價）。

任何無法證明等價的情況會回退，最壞情況是和沒裝一樣慢，不會更慢。

適用場景與注意¶

本插件適用於長會話場景。對於短會話或無追加操作的場景，擴展次數爲 0 是正常現象。

權限：插件以當前 dsh 進程權限運行。
許可：MIT 許可證。

總結¶

經過上面的步驟，DSH 長會話的冷讀開銷已被消除。插件通過常駐解析和增量擴展，配合嚴格的正確性校驗，實現了長會話按進程只解析一次的目標。相關代碼與文檔可參考下方鏈接。