dsh-workspace-merge: 將多個本地項目根目錄合併爲統一操作

DSH 會話默認以一個工作目錄爲根，該目錄既是沙箱邊界，也是所有相對路徑的基礎。這個默認機制在大多數情況下是合理的，但處理一些特定佈局時會變得棘手：例如同一個產品的 PC 端和移動端、需要保持步調的 iOS 和 HarmonyOS 應用、或者一個共享庫及其消費者。這些目錄通常是兄弟節點，在它們之間同步修改同一個文件會導致絕對路徑、重複調用，甚至悄無聲息地偏離。

dsh-workspace-merge 插件爲 DSH 會話引入了一個命名工作區組。這是一個有序的本地項目根目錄集合，並提供了一組 ws_* 工具。這些工具將一個相對路徑視爲跨組內所有根目錄的單一操作，而非針對單一根目錄的操作，從而避免上述問題。

核心功能¶

該插件提供以下工具和機制：

ws_groups：列出已定義的組、每個組的根目錄 ID 以及當前會話處於哪個組中。
ws_group_set / ws_group_remove：維護組註冊表，用於添加或移除工作區組（此操作不修改項目文件）。
ws_ls：列出組內每個根目錄下的同一個相對目錄（如查找同名組件）。
ws_read：讀取組內每個根目錄下的同一個相對路徑內容。
ws_diff：在編輯前對比每個根目錄下同一文件的副本（以第一個根目錄爲基準）。
ws_edit：對組內每個根目錄應用一次字面量替換（old_string -> new_string）。如果替換內容在文件中多次出現，需配合 replace_all。
ws_write：向組內每個根目錄寫入完全相同的完整內容（用於創建新共享文件或強制同步）。
沙箱行爲：工具會先解析會話的 sandboxPolicy，不會放寬權限限制。支持 danger-full-access、workspace-write 和 read-only 模式。

安裝與啓用¶

使用官方插件管理命令安裝：

dsh plugin add dsh-workspace-merge

安裝後，可以通過編輯 $DSH_HOME/profiles/web 目錄下的包，並在 dsh.profile.bundles 中列出 dsh-workspace-merge 來手動添加到配置文件中。

典型用法¶

1. 配置工作區組¶

使用 ws_group_set 定義一個組。id 是後續工具調用的標識符，path 支持絕對路徑或以 ~ 開頭的路徑。

// ws_group_set {group:"ecam", description:"PC + mobile", roots:[
//   {id:"pc",     path:"~/Desktop/JLXY/ecam-ui"},
//   {id:"mobile", path:"~/Desktop/JLXY/ecam-mobile-ui"}
// ]}

該命令會在 $DSH_HOME/workspace-groups.json 中生成配置文件，該文件爲純 JSON，支持手動編輯。

2. 列出與查看¶

列出當前會話的所有組及狀態：

ws_groups

列出組內所有根目錄的同一個相對目錄（如 src/components），工具會自動跳過 .git 和 node_modules 目錄：

ws_ls src/components

讀取特定文件在各根目錄的內容：

ws_read src/components/AmountInput.vue

3. 對比與編輯¶

在編輯前使用 ws_diff 對比差異（行對齊限制在每側 4000 行）：

ws_diff src/components/AmountInput.vue

對每個根目錄執行字面量替換：

ws_edit src/components/AmountInput.vue old_string new_string

若需預覽變更而不實際寫入，可使用 dry_run 標誌：

ws_edit src/components/AmountInput.vue old_string new_string --dry_run

若只想操作組內的特定子集（例如僅 PC 端），可指定 roots：

ws_edit src/components/AmountInput.vue old_string new_string --roots ["pc"]

4. 調試¶

如果在配置中添加了插件但工具未出現，可啓用調試日誌：

WSM_DEBUG=1

適用場景與注意¶

非 Monorepo：工作區組不是 Monorepo。它改變的是 ws_* 工具的指向，但不會改變 DSH 會話的當前工作目錄。內置的 read、edit、write、bash 依然僅針對會話根目錄。
寫入機制：所有寫入操作通過 Harness 的文件系統服務 (ctx.fs) 進行。寫入前會觸發 fs/observed 事件，並遵循 replaceIfVersion 策略。如果該服務未掛載，會回退到 node:fs，此時結果會明確標註 via: node:fs (fs service failed: ...)。
權限限制：在 read-only 沙箱模式下，任何寫入操作（包括 ws_group_set 和 ws_group_remove）都會被拒絕。
測試要求：項目包含單元測試 (npm test)，但測試依賴本地安裝的 DSH 及其依賴 (@deepseek-ai/dsh-tools 等)，無法在純遠程環境中運行。

總結¶

dsh-workspace-merge 提供了一套在單一 DSH 會話中操作多個本地項目根目錄的標準化工具。它通過維護一個組註冊表，使得跨目錄的文件讀取、差異對比和批量字面量替換變得簡單且可審計。

插件目錄：https://www.skillhub.cn/plugins/LoserForLoser/dsh-workspace-merge
源碼地址：https://github.com/LoserForLoser/dsh-workspace-merge