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