dsh-plugin-multi-root-workspace

dsh-plugin-multi-root-workspace

中文 | [English](./README.en.md)

项目简介

[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 默认把新建工作区所在的目录作为 Agent 的主目录，在默认的工作区读写模式（workspace-write）下，沙箱的读写范围也仅覆盖这一个目录。本插件将 DSH 的工作区范围拓展到“一个主目录 + 多个附加目录”。

并非所有项目都是 monorepo。一个开发项目往往由多个独立 Git 仓库组成，跨仓库干活原本得反复换会话。同类工具早已支持在一个工作区添加多个文件夹，本插件把同样的能力带给 DSH：把其他仓库登记为附加根，并按需授予只读、读写或不受限的访问级别，Agent 即可在授权范围内读写。

• 不新增工具：Agent 照旧使用原生 read / write / edit / bash，只是授权的目录变多了。
• 沙箱约束：附加根可继承会话（主目录）的权限设置，也可单独固定为只读或读写；在只读与读写下，约束不靠系统提示词，而由进程内文件围栏 + 内核级沙箱（macOS Seatbelt / Linux bwrap / Landlock / Windows ACL）执行，经本插件围栏的原生文件与 bash 共享同一份授权范围；自行启动 Worker 的第三方工具须单独验证，dsh-ops 的现存缺口见下方已知限制。
• Files 页签浏览附加根：Files 页签头部可直接在主根与任一已登记附加根之间切换，附加根的目录树以与主根相同的原生 Files 视图呈现，打开文件、在外部应用打开、自动刷新等操作完全一致；文件预览页的 Folder 导航树同样落在被预览文件所在的根，定位、展开与高亮与原生一致。
• 可选 Auto review（默认关闭）：fork 上游实验性「自动授权审查」，向 Reviewer 补充附加目录的审查上下文——当前工作区拓扑、各根访问级别与实时指令文件；出厂关闭，需在插件管理器的行列表中显式打开 @dsh-electron/dsh-plugin-multi-root-workspace/auto-review 行后生效，启用时接管官方同名 bundle。
• 附属根 Skills：发现附属目录的 .dsh/skills 与 .agents/skills，附属根经 /alias-id:skill-name 命名空间调用原生 skill 工具；每根独立开关、可编辑 aliasId，全局设置默认开启。
• 不配等于没装：未登记附加根时行为与未装插件逐项一致；配置错误一律明确报错，从不静默降级。

当前发布版本 v0.1.16。各版本的用户可见变更见 [CHANGELOG](./CHANGELOG.md)；进度与发布状态见[路线图 §进度总账](./docs/plans/active/2026-09-12-multi-root-workspace.md#进度总账)。

快速开始

插件已发布到 [npm](https://www.npmjs.com/package/@dsh-electron/dsh-plugin-multi-root-workspace)。在 DSH 侧栏的插件页点添加插件、填入包名 @dsh-electron/dsh-plugin-multi-root-workspace 即可安装；也可以用命令行两步装完：

dsh plugin --profile web add @dsh-electron/dsh-plugin-multi-root-workspace
dsh --profile web       # --profile 按你的启动方式选择，可选值见 DSH 文档

tarball、GitHub、本地源码等其他安装方式见[安装](#安装)。

启动后侧栏底部出现 Folders（🗂）动作；在 DSH 0.2.1-alpha.3 及更新的运行时上，新会话页工作区行右端也会出现同一入口（与相邻的工作区/模式选择器同高同字号，无下拉箭头，窄窗口只显示图标）。也可以直接在会话里：

/workspace-folders add ~/code/another-repo [--inherit|--read-only|--read-write]

之后 Agent 即可在该目录读写、跑 bash——默认 inherit，访问级别跟随会话模式。DSH 的动态 working directory 只影响新操作的相对路径和执行目录，切换 cwd 不会新增授权，也不会改变注册表归属。

环境要求

使用本插件：一个下表中的 DSH 版本（精确匹配，不是范围）。dsh plugin 负责安装，无需本地 Node 工具链。

| DSH 系列 | 受支持的版本 |

| --- | --- |

| 0.1.5 | 0.1.5-rc.2 |

| 0.1.6 | 0.1.6-alpha.1、0.1.6-alpha.2 |

| 0.1.7 | 0.1.7-alpha.1、0.1.7-alpha.2、0.1.7-rc.1、0.1.7-rc.2 |

| 0.2.0 | 0.2.0-rc.1、0.2.0-rc.2 |

| 0.2.1 | 0.2.1-alpha.1、0.2.1-alpha.2、0.2.1-alpha.3、0.2.1-alpha.4、0.2.1-alpha.5、0.2.1-rc.1、0.2.1-rc.2、0.2.1-rc.3、0.2.1-rc.4、0.2.1-rc.5 |

| 0.2.2 | 0.2.2-alpha.2、0.2.2-alpha.3、0.2.2-rc.1 |

DSH 版本不在表内、或 @deepseek-ai/dsh-* 各包版本不一致时，插件不会启动，行为等同没装。

从源码构建 / 贡献：Node.js ^22.19.0 || >=24，pnpm 11.25.0（建议经 corepack 启用）；开发 pin 的 DSH 为 0.2.2-rc.1（Node ≥24.9）。

运行平台：macOS（Seatbelt）、Linux（bwrap / Landlock）、Windows（root-set ACL runner）。

安装

不使用命令行时，DSH 侧栏的插件页提供同一安装入口：点添加插件，填入 npm 包名（或 Git 地址、tarball、本地绝对路径）。

dsh plugin 支持四种安装来源。以下均以 web profile 为例；桌面端（Electron）把 --profile web 换成 --profile desktop，安装方式同源。

| 来源 | 命令 | 说明 |

| --- | --- | --- |

| npm 注册表（推荐） | dsh plugin --profile web add @dsh-electron/dsh-plugin-multi-root-workspace | 预构建产物，即装即用 |

| GitHub | dsh plugin --profile web add github:cherrchen/dsh-plugin-multi-root-workspace | 安装时自动从源码构建；allowBuilds 需含本包，建议锁定版本 |

| tarball | dsh plugin --profile web add ./dsh-electron-dsh-plugin-multi-root-workspace-.tgz | 预构建离线包，适合内网/离线 |

| 从源码安装 | dsh plugin --profile web add /path/to/package/dsh-plugin-multi-root-workspace | pnpm link: 链接本地 checkout，适合开发调试；无需 allowBuilds |

首次安装时 dsh plugin add 会以 [ERR_PNPM_IGNORED_BUILDS] 失败：在该 profile 的 pnpm-workspace.yaml 里补上下面这行，再执行一次 add 即可：

allowBuilds:
  koffi: true

如果重跑 退出 0 但插件没有进入 dsh.profile.bundles，做一次 remove + add。更多排查见[故障排查](./docs/troubleshooting/install-stops-at-build-approval.md)。

从 npm 安装（推荐）

dsh plugin --profile web add @dsh-electron/dsh-plugin-multi-root-workspace

安装的是预构建产物，首次安装需要添加 allowBuilds。

从 tarball 安装

pnpm pack @dsh-electron/dsh-plugin-multi-root-workspace
# 或从 GitHub Release 资产下载，例如：
# https://github.com/cherrchen/dsh-plugin-multi-root-workspace/releases/download/v0.1.16/dsh-electron-dsh-plugin-multi-root-workspace-0.1.16.tgz
dsh plugin --profile web add ./dsh-electron-dsh-plugin-multi-root-workspace-0.1.16.tgz

同样是预构建产物，适合内网或离线环境交付；首次安装同样需要添加 allowBuilds。