前言¶
在 DSH 中處理多個並行任務時，任務之間如果共用同一個倉庫工作區，容易出現變更污染、合併目標不清、收尾不一致的問題。JohnXu22786/worktree-mgr 是一個 dsh 插件，爲任務自動創建隔離的 git worktree 工作區，並管理創建、同步、收尾的全生命週期。
定位¶
該插件由 JohnXu22786 維護，許可證爲 MIT。它面向 dsh 提供任務隔離工作區，避免並行任務污染主工作區。插件提供 5 個模型工具與 1 個 CLI，並支持 --json 結構化輸出。運行環境要求 node >= 21，爲純 Node ESM，無構建步驟。
核心能力¶
- 任務驅動：根據任務名自動生成分支、工作區路徑和臺賬記錄。
- 分支名安全：任務名 slug 規範化，並做雙重 ref 有效性檢查；不同任務派生相同 slug 時拒絕創建。
- 未提交變更檢測：基分支有未提交變更時拒絕合併；任務工作區默認自動快照提交。
- 合併目標一致性：校驗主工作區當前分支與臺賬基分支、任務工作區當前分支與臺賬任務分支；不一致時拒絕。
- 同步與收尾分離：
wtm_merge只合並；wtm_finish提交、合併、刪除工作區、刪除分支、清理記錄。 - 批量收尾：
wtm_purge可批量處理多個任務，單任務失敗不中斷其餘任務，且失敗返回非零退出碼。 - 併發安全：臺賬寫入使用互斥鎖，鎖包含唯一 token 與心跳刷新，崩潰後回收舊鎖。
- 失敗恢復：創建失敗自動回滾 worktree 和分支；合併衝突提供
git merge --abort恢復指引。 - 跨平臺觸發器：支持 Windows(cmd) 與 POSIX(sh)，路徑比較規範化大小寫與分隔符。
- 倉庫級配置：
.wtm.json支持分支前綴、消息模板、種子文件（路徑逃逸保護）和生命週期觸發器（固定工作目錄）。
安裝與啓用¶
安裝到指定 profile：
dsh plugin --profile demo add github:JohnXu22786/worktree-mgr
移除：
dsh plugin --profile demo remove worktree-mgr
本地安裝：
dsh plugin --profile demo add ./worktree-mgr
package.json 中聲明 dsh.bundle.patch 爲 ./cordis.patch.yml。
overlay 加載：
dsh --profile demo --patch ./examples/overlay.yml
獨立 CLI：
npm link
wtm begin "Add Search Box"
典型用法¶
創建任務工作區：
wtm begin "Add Search Box"
查看狀態：
wtm status
只合並，不執行收尾刪除：
wtm merge "Add Search Box"
收尾：提交、合併、刪除工作區、刪除分支並清理記錄：
wtm finish "Add Search Box"
批量收尾：
wtm purge "Task A" "Task B"
wtm purge --all
幫助：
wtm help
所有命令支持 --json。WTM_* 環境變量同樣適用於 CLI。
安全邊界¶
- 基分支有未提交變更時，拒絕合併。
- 主工作區當前分支與臺賬基分支不一致，或任務工作區當前分支與臺賬任務分支不一致時，拒絕操作。
- 任務、分支或工作區已存在，或不同任務派生相同工作區路徑時，拒絕創建。
mode abandon會丟棄全部任務變更、強制清理工作區並刪除分支，不可恢復。
適用場景與注意¶
適合需要在多個任務之間隔離工作區、希望統一完成合並與清理的 dsh 使用場景。
從權限角度看，插件會以當前 dsh 進程權限運行，執行前需確認其對倉庫、文件系統與配置文件的訪問符合預期。安裝前應檢查源碼、許可證和 .wtm.json 等配置；本文所覈實許可證爲 MIT。
參考資料¶
- GitHub：https://github.com/JohnXu22786/worktree-mgr
- 目錄頁：https://www.skillhub.cn/plugins/JohnXu22786/worktree-mgr
