@dsh-electron/dsh-plugin-multi-root-workspace

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

<div align="center">

<img src="public/multi-root-mark.svg" width="120" />

dsh-plugin-multi-root-workspace

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

</div>

项目简介

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 视图呈现，打开文件、在外部应用打开、自动刷新等操作完全一致。
• 可选 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.15。各版本的用户可见变更见 [CHANGELOG](./CHANGELOG.md)；进度与发布状态见[路线图 §进度总账](./docs/plans/active/2026-09-12-multi-root-workspace.md#进度总账)。

快速开始

插件已发布到 npm。在 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（🗂）动作，或直接在会话里：

/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-<version>.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.15/dsh-electron-dsh-plugin-multi-root-workspace-0.1.15.tgz
dsh plugin --profile web add ./dsh-electron-dsh-plugin-multi-root-workspace-0.1.15.tgz

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

从 GitHub 安装

dsh plugin --profile web add github:cherrchen/dsh-plugin-multi-root-workspace

GitHub 来源装的是源码，add 时会自动构建，不需要手动编译；但 allowBuilds 要写两行——本包自身和 koffi：

allowBuilds:
  '@dsh-electron/dsh-plugin-multi-root-workspace': true
  koffi: true

建议锁定版本（如 #v0.1.15），让后续推送无法悄悄改变实际运行的内容：

dsh plugin --profile web add github:cherrchen/dsh-plugin-multi-root-workspace#v0.1.15

从本地源码安装

git clone https://github.com/cherrchen/dsh-plugin-multi-root-workspace.git
cd dsh-plugin-multi-root-workspace
export CI=true
pnpm install
pnpm build
dsh plugin --profile web add /path/to/repo

[!TIP]

dsh 不在 PATH 里时（例如用源码仓库跑 DSH），把命令里的 dsh 换成 pnpm dsh。

运行方法

开发自检：

pnpm lint && pnpm typecheck
pnpm test
pnpm kernel:probe
pnpm smoke
pnpm docs:check

安装进 DSH 运行时并验证组合：

dsh plugin --profile web add /path/to/repo
dsh --profile web --dump-config | grep -A3 'multi-root'

预期输出：

# == @deepseek-ai/dsh-base, patched by @dsh-electron/dsh-plugin-multi-root-workspace
- id: sandbox
  name: '@deepseek-ai/dsh-sandbox-local'
  disabled: true
--
# == @deepseek-ai/dsh-base, patched by @dsh-electron/dsh-plugin-multi-root-workspace
- id: fs-sandbox
  name: '@deepseek-ai/dsh-fs-sandbox'
  disabled: true
--
# == @dsh-electron/dsh-plugin-multi-root-workspace
- id: multi-root-compat
  name: '@dsh-electron/dsh-plugin-multi-root-workspace/compat'
- id: multi-root-fs
  name: '@dsh-electron/dsh-plugin-multi-root-workspace/fs'
- id: multi-root-sandbox
  name: '@dsh-electron/dsh-plugin-multi-root-workspace/sandbox'
- id: multi-root-providers
  name: '@dsh-electron/ds

…(truncated)