前言¶

DeepSeek Harness (DSH) 进程在并发运行时，特别是 dsh web 与 CLI 同时运行，或多个实例共享同一 $DSH_HOME 时，容易出现会话日志损坏。这是因为每个进程维护独立的内存序列号，第二个写入进程会提交已被第一个进程确认的序列号，导致日志中出现 seq gap in committed region 错误，从而永久无法加载该会话的历史记录。DSH 目前缺乏跨进程锁机制，直接写入会静默破坏历史数据。下面介绍一款用于解决该问题的插件。

它是什么¶

dsh-session-guard 是由 po-et 维护的 DeepSeek Harness 插件。它的核心作用是在 DSH 进程之间添加跨进程的会话级咨询锁，防止并发写入导致的日志损坏。通过强制冲突步骤失败并报错，确保在冲突发生时日志保持完整，而不是静默覆盖。

核心功能¶

该插件提供以下功能：
1. Per-session advisory locks：为每个会话提供咨询锁机制。
2. 防止并发写入损坏：拦截并阻止两个进程同时写入同一会话日志。
3. 自动接管死锁：当持有锁的进程崩溃后，锁会自动被其他进程接管。
4. 心跳刷新机制：持有锁的进程需要定期发送心跳以保持锁的有效性。
5. 过期机制：未经验证的所有者（例如其他主机上的进程）如果在 90 秒内未刷新心跳，锁将自动过期。
6. 零运行时依赖：除了必要的 peer 依赖外，插件不依赖其他运行时库。

安装与启用¶

插件尚未发布到 npm，需直接通过 GitHub 安装。

dsh plugin --profile web add github:po-et/dsh-session-guard

安装后，插件会自动加载。它需要 @deepseek-ai/cordis ^4.0.1 作为对等依赖。

典型用法¶

安装完成后，可以通过配置文件对插件的行为进行调整。所有配置项均为可选，放置在 profile patch 的插件行中：

- id: session-guard
  name: "@po-et/dsh-session-guard"
  config:
    mode: enforce        # enforce (默认) 会强制冲突步骤失败；warn 仅记录日志
    heartbeatMs: 15000   # 持有锁的心跳刷新间隔（毫秒）
    staleAfterMs: 90000  # 未经验证的所有者无心跳后过期时间（毫秒）
    # lockDir: /custom   # 自定义锁目录（默认为 $DSH_HOME/session-locks）

适用场景与注意¶

1. 咨询锁特性：该锁是咨询性质的，仅保护加载了该插件的 DSH 进程。如果某些进程未安装此插件，它们仍可能与其他进程冲突。建议在所有运行 DSH 的 profile 中安装此插件。
2. 保护范围：插件仅拦截活跃的“写入路径”（agent/session-start, agent/pre-step）。对于冷加载修复路径（dsh 内部在步骤运行前提交合成中断关闭符）无法拦截，该修复需在 DSH 核心层解决。
3. 锁存储位置：锁文件默认存储在 $DSH_HOME/session-locks 目录下。
4. 不可逆性：如果会话日志已经损坏，该插件无法修复，需要配合 dsh-session-rescue 使用。
5. 许可证：MIT License。

结语¶

dsh-session-guard 通过在 DSH 进程间引入咨询锁，将并发写入导致的静默损坏转变为明确的错误提示，从而保护会话历史不被破坏。对于需要稳定运行 DSH 的环境，这是一个必要的防护措施。

更多细节与源码，请访问：https://github.com/po-et/dsh-session-guard