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 长会话的冷读开销已被消除。插件通过常驻解析和增量扩展，配合严格的正确性校验，实现了长会话按进程只解析一次的目标。相关代码与文档可参考下方链接。