前言¶

在 DeepSeek Harness（DSH）裏，多個會話可能同時處理同一個 workspace。如果沒有顯式協調，兩個會話可能編輯同一個文件，造成覆蓋；會話崩潰後也可能留下過期的佔用狀態；另一個會話想修改已被佔用的文件時，只能等待或猜測。

dsh-file-claim 面向這個問題：它爲併發 DSH 會話提供文件 claim/保護，包括 claim/release、心跳過期接管、異步待合併區（git 3-way merge）。下面介紹它的定位、核心能力、安裝方式和典型用法。

這是什麼¶

dsh-file-claim 是一個 DSH Host 插件，由 Nwflower 維護，採用 MIT 許可證。

它把文件佔用聲明、釋放、狀態查詢、pending 合併等能力做成 tools，並通過 DSH 生命週期事件刷新心跳、釋放離開會話的 claim。

核心功能¶

claim / release¶

• claim_files：會話在編輯前聲明文件/目錄路徑的獨佔所有權。
• 重複 claim 會冪等合併。
• 目錄 claim 覆蓋子級路徑。
• 對 '.' 的 claim 表示整個 workspace。
• release_files：釋放 claim；owner release 後，pending 區可按規則合併。

heartbeat 與 stale 接管¶

• agent/created / agent/status 事件刷新心跳。
• agent/disposed 自動釋放離開會話的所有 claim。
• 崩潰/強殺會話的 claim 在下次活動時清理，並由心跳間隔清掃。
• staleMs 過期和 --force takeover 作爲慢速兜底；staleMs 默認 2h，適用於無 pid 記錄的場景。

async pending merge area¶

• 對已被其他會話佔用的文件，寫入 pending 區，而不是直接阻塞。
• owner release 後，無衝突時通過 git 3-way merge 自動合併。
• 衝突時使用 pending_apply 手動合併。
• 輔助工具包括 pending_show 查看條目、pending_drop 丟棄條目。

write guard¶

• tools/pre-execute 守衛拒絕寫入被其他會話 active claim 的文件。
• 被拒絕時給出 wait / takeover when stale / pend 提示。
• 可選 commit guard。
• 該守衛屬於 cooperative tool-layer guardrail，標註爲 fail-open，並匹配該類別 de-facto standard。

audit 與輕量運行¶

• claim/release/takeover/pending 變更追加爲 JSON line，用於追溯和崩潰後 reconciliation。
• 插件爲 pure Host plugin、zero dependencies，無 Browser 側、無 build step，僅 node: builtins，Windows-friendly。

安裝與啓用¶

先確認環境滿足：

• DSH with node >= 18
• git 在 PATH 中；git 僅用於 3-way merge

然後執行安裝命令：

dsh plugin add dsh-file-claim

安裝後，插件提供以下 tools：claim_files、release_files、who_claims、claim_status、pending_write、pending_apply、pending_show、pending_drop。

典型用法¶

先 claim，再編輯，最後 release¶

先聲明所有權：

claim_files({ paths: ["README.md"] })

然後執行 write/edit。完成後釋放：

release_files({ paths: ["README.md"] })

經過上面的步驟，本會話的 claim 被釋放，pending 區中的相關條目會進入合併流程。

查看 claim 狀態¶

查看某個路徑被誰 claim：

who_claims({ paths: ["README.md"] })

查看 registry、claims、pending area 和 audit：

claim_status()

寫入被其他會話佔用的文件¶

寫入被其他會話 claim 的文件會被 DENIED，並提示等待、stale 時 takeover 或 pend。

如果要把編輯內容先放到 pending 區：

pending_write({ path: "README.md", content: "..." })

owner release 後，無衝突時自動 git 3-way merge；衝突時運行：

pending_apply

也可以查看或丟棄 pending 條目：

pending_show
pending_drop

接管 stale claim¶

發現其他會話 claim stale 後，可用 takeover：

claim_files({ paths: ["README.md"], force: true })

適用場景與注意¶

適合：

• 多個 DSH 會話併發編輯同一個 workspace。
• 希望減少同一文件被併發覆蓋的情況。
• 希望被佔用文件可以寫入 pending 區，而不是隻能等待。
• 希望用 JSON line audit 追溯 claim/release/takeover/pending 變更。

注意：

• 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。
• write guard 是 cooperative tool-layer guardrail，且標註爲 fail-open；它用於協作約束，不要把它當作強隔離邊界。
• staleMs 默認 2h，--force takeover 是慢速兜底。
• git 僅用於 3-way merge；自動合併依賴該流程。
• 插件無 Browser 側、無 build step、zero dependencies，部署時主要關注 DSH、node、git 和源碼審查。

結尾¶

dsh-file-claim 把併發 DSH 會話中的文件 claim、release、pending 合併和 audit 放到同一組 tools 中，讓「先 claim、再編輯、最後 release」成爲可執行的協作流程。

插件名：dsh-file-claim

倉庫地址：https://github.com/Nwflower/dsh-file-claim

目錄頁可按插件名 dsh-file-claim 查詢。