前言¶
在 DSH 環境下，智能體常需操作多個 Git 倉庫。如果當前工作區與預期的分支不一致，或者與遠程存在分歧，後續的提交和推送會導致數據丟失或覆蓋。dsh-checkout-guard 是一個 DSH 插件，用於在編輯、提交或推送之前進行預檢。它確認當前工作區是否符合預期，防止在錯誤的狀態下進行寫入。
插件簡介¶
名稱：lesliewylie/dsh-checkout-guard
維護者：LeslieWylie
類別：admin-security
許可證：MIT
核心定位：這是一個只讀、默認離線的 DSH 插件。它讀取 Git 工作區，檢查分支身份、與遠程的分歧情況、下一個提交將攜帶的身份、索引中的工作內容，以及同一機器上是否存在其他導致衝突的重複克隆。
安裝與啓用¶
通過 npm 安裝該插件，並在 DSH 的配置文件中啓用。
- 安裝
npm install dsh-checkout-guard
- 啓用
在cordis.yml中添加以下條目：
- id: checkout-guard
name: 'dsh-checkout-guard'
核心功能¶
該插件提供以下檢查項，默認爲只讀模式：
- 分支身份與遠程分歧：檢查當前分支是否與預期的分支匹配，並計算相對於遠程的差異（ahead/behind）。
- 下一個提交身份：驗證下一次提交將使用的作者信息（需配合
expectIdentity參數使用）。 - 工作區索引檢查：檢查索引中是否已存在待提交的工作。
- 重複克隆檢測：在同一機器上檢測是否有其他倉庫克隆了相同的遠程，並判斷它們是否領先於當前工作區。
- 寫入防護：如果上述檢查失敗，插件會阻止寫入操作。
工具使用¶
插件提供了兩個主要工具，分別用於單倉庫檢查和批量掃描。
checkout_guard：檢查單個工作區¶
用於檢查單個倉庫路徑的狀態。
參數：
* path (必需)：工作區的絕對路徑。
* expectBranch：期望所在的分支，不匹配會觸發阻斷。
* fetch：是否先執行 git fetch 以獲取最新的遠程狀態（默認 false，這是唯一涉及網絡操作的功能）。
* expectIdentity：期望的作者郵箱，用於驗證提交身份。
返回值：
檢查結果包含 safeToWrite 字段。只有當該字段爲 true 時才允許寫入。其他字段如 blockers 會列出阻止寫入的原因，warnings 則提供非阻斷性的狀態提示。
checkout_guard_scan：批量掃描根目錄¶
用於掃描根目錄下所有的工作區，並返回概覽。
參數：
* roots：要掃描的根目錄列表。
* maxDepth：掃描深度。
輸出：
返回每個工作區的分支、上游、ahead/behind、未提交數量、fetch 時間等信息，並標記出 needsAttention（需要關注）的倉庫和 duplicateRemotes（重複遠程）。
安全與注意事項¶
瞭解插件的邊界有助於正確使用。
- 不判斷身份：插件本身不會判斷你的身份是否正確，除非你顯式指定了
expectIdentity。它只會報告作者信息來自哪裏。 - 不修復任何問題：插件不會自動拉取、變基或暫存。它只負責報錯和阻斷。如果發現狀態異常，需要手動處理。
- 無寫入操作：插件不會向任何倉庫寫入數據。即使在
fetch: true模式下，也僅執行git fetch --dry-run，不會修改索引或鎖文件。 - 避免鎖衝突：插件使用
GIT_OPTIONAL_LOCKS=0運行，避免與其他智能體或進程爭奪.git/index.lock。 - 不檢測遠程歸檔：插件無法通過 API 告知遠程倉庫是否已被歸檔。
配置¶
在 cordis.yml 中可以配置插件的作用範圍。
- id: checkout-guard
name: 'dsh-checkout-guard'
config:
roots:
- /path/to/projects
roots 參數限定了插件會掃描的目錄範圍。如果不設置，默認爲用戶的主目錄。
結尾¶
dsh-checkout-guard 作爲一個預檢工具，通過阻斷錯誤的寫入操作，降低了智能體在多倉庫環境中因狀態誤判導致的數據風險。它不承諾解決衝突，但能確保在狀態不明時停止操作。
