前言¶

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