在 DSH 環境下開發多倉庫項目時，智能體容易因忘記切換目錄或分支而將代碼寫入錯誤位置。該插件通過構建多倉庫功能工作區，確保每個功能在獨立目錄中運行，且所有組件倉庫同步在同一個功能分支上。
插件介紹¶
這是一個 DSH 插件，用於多倉庫功能工作區編排，由 TY-ang 維護。它將一組倉庫綁定爲一個“集”（Set），存儲在 $DSH_HOME/worktree-flow/sets/<name>.json。在創建功能時，插件會爲每個組件倉庫創建一個 git worktree，所有 worktree 共享同一個功能分支。功能根目錄被自動註冊爲 DSH 工作區，會話沙盒將精確落在這個功能範圍內。
核心功能¶
- 多倉庫功能工作區：每個功能對應一個目錄，每個組件倉庫對應一個 git worktree。
- 共享功能分支：所有組件 worktree 複用同一個功能分支，避免分支混亂。
- 自動註冊爲 DSH 工作區：功能根目錄自動註冊，會話可在此範圍內操作。
- 沙盒隔離：會話只能寫入功能根目錄，無法觸及主倉庫或其他功能目錄。
- 預創建分支：創建功能時即 checkout 到指定分支，寫入默認落對位置。
- 身份說明注入：會話啓動時自動注入當前功能佈局和分支約束。
- 環境醫生：診斷環境完整性，包括目錄歸屬、Git 所有權、分支引用等。
- 自動發現：掃描參考目錄鄰近的 Git 倉庫，支持批量綁定組件。
- 實時共享文檔：支持配置項目級文檔源，會話可直接讀取最新內容。
- 分支類型自定義：支持自定義分支命名規則（如 Bugfix/功能/發佈）。
安裝與啓用¶
使用以下命令安裝插件（需指定 profile）：
dsh plugin --profile web add github:TY-ang/dsh-worktree-flow
安裝後重啓 dsh web。該包聲明瞭 dsh.bundle，會自動加入配置文件堆棧。這是一個私有包，未發佈到 npm registry。
典型用法¶
配置¶
進入 Settings → Worktree Flow 頁面。在配置頁創建“集”，綁定組件路徑。支持選擇非 Git 目錄並初始化倉庫。配置包含共享文檔源、分支類型定義等。
命令操作¶
# 查看功能狀態
/worktree status [feature]
# 創建新功能
/worktree create [name] --branch <full-branch> [--components a,b] [--base ref] [--set name] [--dry-run] [--register-components]
# 診斷環境
/worktree doctor [--set name]
# 同步現有功能，遷移舊版清單
/worktree sync
# 打開指定功能（確保已註冊）
/worktree open <feature>
# 完成並歸檔功能
/worktree finish <feature> [--cleanup] [--force] [--keep-registered]
# 顯示當前配置
/worktree config show [--set name]
適用場景與注意¶
適用場景：多倉庫前端/後端/API 聯合開發，需要嚴格的功能隔離和分支管理。
注意事項：
* 需要 Node.js >= 22。
* Worktree-root 和組件路徑必須是絕對路徑，支持 ~。
* Windows 環境下有嚴格限制：
* DSH 進程不能是高完整性或系統級別，需以普通用戶身份運行。
* 組件創建依賴原生 git worktree add，需確保 Git 驗證通過。
* 插件不會修改全局 git config、更改 Owner/ACL 或切換 Windows 用戶。
* 請確保 DSH、Codex 和 IDE 運行在同一 Windows 賬戶下。
* 環境醫生僅提供只讀診斷，不自動修復環境或信任問題。
* 歸檔（finish）僅移除註冊記錄，不會刪除文件和分支。
該插件通過物理隔離和預配置分支，解決了多倉庫開發中的路徑與分支混亂問題。適合需要嚴格功能隔離的開發流程。更多詳情請訪問 GitHub 或 SkillHub。
