WSL 远程工作区 MFJip612/dsh-remote-wsl

dsh-remote-wsl

在 DeepSeek Harness（DSH）里直接连接 WSL 发行版里的项目：点「添加工作区」时多一个 连接 WSL 入口，选发行版、浏览 Linux 文件夹，选中后该目录成为 DSH 工作区。这个工作区里的侧栏终端开在发行版里，agent 的 bash / read / write / edit / glob / grep 也都在 Linux 侧执行。

目标环境：Windows 10/11 + WSL2。插件只调用 DSH 官方服务，不依赖也不调用任何第三方 WSL 插件。

它做什么

1. 入口。 侧栏工作区标题栏的「+」、新会话页的「添加工作区」都走同一个添加流程。现在弹窗先问文件夹在哪里：

- 本地文件夹：原来的 Windows 目录选择器，行为不变。
- 连接 WSL：在「本地文件夹」下面的一行，点开后选择发行版。

2. 选发行版。 「连接 WSL」弹窗列出本机全部发行版（含已停止的），显示运行状态，右上角可以刷新。发行版通过 wsl.exe -l -v --all 枚举，UTF-16LE 输出自动识别，* 为默认发行版，列表缓存 5 秒。

3. 选项目。 选中发行版后从该发行版默认用户的 $HOME 开始浏览：

- 面包屑（Ubuntu / home / me）可点击跳转；
- 搜索框过滤当前层，也可以直接输入 Linux 路径跳转；
- 可切换显示隐藏文件夹；
- 选中当前文件夹点「确认」即可。

4. 登记为工作区。

- Linux 文件系统里的项目登记为 \\wsl.localhost\<发行版>\<路径>（自动探测 \\wsl$ 备用形态）。
- /mnt/<盘符>/... 下的项目登记为真实的 Windows 路径（例如 D:\work\proj）——WSL 的 9P 共享拒绝访问 /mnt，只有真实盘符路径可读写；插件会记住它来自哪个发行版。
- 之后在新会话里，工作区就是普通的 DSH 工作区；区别只在执行面。

5. 终端在发行版里。 在这个工作区打开侧栏终端，实际执行的是 wsl.exe -d <发行版> --cd <Linux 路径>，也就是发行版的登录 shell，起始目录就是项目目录。

6. agent 工具在发行版里。 这个工作区的会话里：

| 工具 | 行为 |
| bash | 在发行版里执行 bash -lc，默认目录是工作区；每次调用是新 shell |
| read / write / edit | 使用 Linux 路径；写入/编辑用临时文件 + rename 原子发布（WSL 的 9P 共享不支持 DSH 原生的硬链接发布方式） |
| glob / grep | 在发行版里用 globstar / GNU grep 搜索 |

Windows 的 PowerShell 工具在 WSL 工作区里会被隐藏，普通 Windows 工作区完全不受影响。

安装

在 DSH 的「插件」页面安装本地目录，或者：

dsh plugin --profile web add github:MFJip612/dsh-remote-wsl

仓库只保存 TypeScript 源码，安装本地目录前请运行 npm ci（自动构建）或 npm run build。GitHub 安装通过 prepare 构建；如果 pnpm 阻止构建脚本，按安装器提示在对应 profile 的 pnpm-workspace.yaml 中允许它报告的准确包键，然后重试。也可先运行 npm pack，安装已包含构建产物的 tarball。

也可以在会话里让 agent 用插件管理器安装该目录。link: 只保证读取本目录的文件，不保证已经运行的 Host 重载代码。默认配置下，Host 侧代码更新后需要完全退出并重启 DSH；浏览器侧代码更新后刷新页面即可。DSH 的默认 HMR 配置是 root: []，只监听配置文件。如果退出提示有任务正在运行，请先等任务完成再重启。

文件变更和交付卡片

WSL 的 write / edit 在发布文件前进入官方 fs/write-intent / fs/edit-intent，让 DSH 捕获修改前内容；成功后记录 fs/observed。工具结果复用原生 write/edit 的输出格式、元数据和 diff 展示，回合结束时由官方 workspace-changes 生成修改列表与比较。只读、越界、未观察和版本过期的写入仍会拒绝。

present 继续使用官方执行器与 deliverables/presented 事件；插件把 Linux 绝对路径、相对路径、~/ 和挂载盘路径转换为 Windows 可访问的路径，保留说明、文件限额、普通文件校验和点击预览/打开行为。指向其它发行版的 UNC 路径会拒绝。

修改列表会自动汇总文件工具的成功修改；独立文件卡片仍由模型调用 present 发布交付文件，不会自动为每个源码改动发布卡片。仅通过 bash 修改文件时，非 Git 目录没有文件工具的前置捕获；需要独立卡片时仍可明确要求模型调用 present。

配置字段

在 profile 的 cordis.patch.yml 里覆盖插件行的 config：

- id: dsh-remote-wsl
name: 'dsh-remote-wsl'
config:
terminal: true
tools: true

| 字段 | 默认 | 说明 |
| terminal | true | WSL 工作区的侧栏终端是否开在发行版里 |
| tools | true | 是否为 WSL 工作区的会话启用 Linux 侧工具 |
| execTimeoutMs | 15000 | 单次 wsl.exe 调用超时（毫秒） |
| distroCacheMs | 5000 | 发行版列表缓存时间 |
| maxEntries | 2000 | 目录选择器单层最多返回的条目数 |
| maxReadBytes | 2000000 | read 工具单次最多返回的字节数 |
| defaultDistro | '' | 预留：默认发行版覆盖（空 = 使用 WSL 默认） |
| mountRoot | '' | automount 根（空 = 读发行版 /etc/wsl.conf，回退 /mnt） |
| remote | false | 是否允许非回环地址的客户端调用插件路由 |

工作原理

- 入口：占用官方工作区组件声明的两个 single 插槽 sidebar.workspaces.directoryFlow 与 conversation.hero.workspace.directoryFlow，用比官方占用者更低的 priority 渲染自己的「本地文件夹 / 连接 WSL」选择框；弹窗画在 shell.overlay 里。选「本地文件夹」时调用官方 ctx.uiWorkspace.pickDirectory()（或桌面注入的 __DSH_DIRECTORY_PICKER__），所以原生选择器行为不变。
- Host 路由：GET /dsh-remote-wsl/{status,distros,warm,list} 与 POST /dsh-remote-wsl/connect。全部同源 JSON、拒绝跨站、默认只接受回环地址；connect 通过官方 workspaceRegistry.create() 登记工作区。
- 身份探测：wsl.exe -d <发行版> --exec bash --noprofile --norc -c "printf '%s\n' '<哨兵>' \"$WSL_DISTRO_NAME\" \"$(id -un)\" \"$HOME\""，失败时回退读 /etc/wsl.conf 与 /etc/passwd。
- 目录浏览：直接走 \\wsl.localhost 共享；共享拒绝时回退到发行版里的 find。
- 终端：包装官方 subprocess.spawnTerminal，只替换 cwd 落在 WSL 工作区时的 argv；其它终端原样通过。官方升级若改了这个内部方法，终端退回 Windows shell，连接流程不受影响。
- 工具：在 agent/created 时解析会话 cwd，命中 WSL 工作区就在该 agent 作用域内注册 Linux 工具（作用域工具遮蔽全局同名工具，不影响其它会话），并用 tools.restrict 隐藏 Windows shell。写操作按 ctx.sandboxPolicy.resolve() 的门禁执行：read-only 拒绝写入与 bash，workspace-write 只允许工作区（或临时目录）内的目标，danger-full-access 放行。

工具的目录门禁只检查 write / edit 的目标路径，不是 Linux 进程隔离：workspace-write 下的 bash 仍以发行版用户权限运行，不能当作操作系统沙箱使用。

已知限制

- agent 进程仍在 Windows 上。DSH 没有在 WSL 里运行 Host/Agent 的协议；本插件把该会话的 shell 与文件工具代理到 wsl.exe，其它工具（web、subagent、todo 等）仍是 DSH 原生实现。
- bash 每次调用是新 shell，cd / export 不跨调用保留；请在同一条命令里串联，或使用 workdir。
- 不支持后台 bash（没有 run_in_background）。
- working_directory 工具不识别 Linux 路径（v1 限制）；需要换目录时在 bash 命令里 cd。
- 写入不触发 DSH 的越权写审批升级：超出工作区的写入直接拒绝，需要时请把会话权限切到「完全权限」。
- WSL 1 不支持：/mnt 之外的共享路径不可靠，选择器会提示升级到 WSL 2。
- 文件树、代码预览、变更记录等仍由 DSH 在 Windows 侧通过 9P 共享读取，目录很大时会比原生 Linux 慢。
- 发行版第一次被访问时会自动启动（可能等待数秒）。

TypeScript 开发

维护源码位于 src/。Host 入口、WSL 服务与工具为 TypeScript ESM；浏览器源码是 src/client.ts，编译后仍通过 DSH 的模块加载器使用宿主 React；恢复 CLI 为 src/scripts/repair-legacy.cts。

npm ci
npm run check # 构建插件，再严格检查 TypeScript 测试与构建脚本
npm run build # 生成 DSH 可直接加载的 JavaScript 和 Host 类型声明
npm test # 构建、入口/配置检查及现有行为回归
npm pack # 打包前自动构建

要求 Node.js >= 24.9.0。业务源码、构建脚本和测试全部使用 TypeScript；先前根目录与 lib/ 下的 JavaScript 文件已删除。所有 JavaScript 和 Host 声明只生成到 Git 忽略的 dist/，不提交生成产物。package.json 的公开入口指向 dist/，打包前自动构建，安装包只携带运行所需的编译产物和静态资源。构建不依赖旁边的 DSH 源码仓库。

恢复 CLI 的源码是 src/scripts/repair-legacy.cts，运行入口是构建后的 dist/scripts/repair-legacy.cjs；它仍默认只报告，只有显式 --apply 才修改日志。

插件导出 Cordis 支持的 Standard Schema Config，保留原有配置字段、默认值和输入归一化。开发类型依赖使用与验证用 Desktop 相同的 Cordis 4.0.5；Host 与浏览器运行时均使用 DSH 提供的服务实例。

本地链接安装后，源码修改需要先构建；Host 更新仍需完全退出并重启 DSH，浏览器更新后刷新页面。npm test 中真实 WSL 部分在 WSL 不可用时会跳过；下面两个 Desktop 集成测试要求真实 WSL，缺少环境时失败。

测试

$env:ELECTRON_RUN_AS_NODE='1'
$exe = "$env:LOCALAPPDATA\Programs\DeepSeek Harness\DeepSeek Harness.exe"
& $exe test\pure.test.ts # 纯函数（发行版解析、路径映射、wsl.conf/passwd） & $exe test\run.ts # Host 服务 + 真实 WSL（身份、目录、bash） & $exe test\tools.test.ts # 工具运行时 + 真实 WSL（write/read/edit/glob/grep/bash/沙箱门禁） & $exe test\registration.test.ts # 注册层（agent 作用域工具集、终端路由包装） & $exe test\desktop-runtime.cts | Out-String # 已安装 DSH 的真实 Agent/工具执行链 + 真实 WSL；无模型费用 & $exe test\desktop-deliveries.cts | Out-String # 真实文件变更摘要、diff、present 交付事件；独立 WSL 测试目录

没有 node.exe 在 PATH 上时用 DSH Desktop 自带的 Electron 以 Node 模式运行（如上）。真实 WSL 不可用时相应小节显示 skipped。

test/desktop-runtime.cts 必须通过已安装的 DSH Desktop 可执行文件运行，要求可访问 WSL，缺少环境时失败而不跳过。测试替换模型网络响应，保留 DSH 的真实 Cordis、Agent 循环、inbox、工具注册、工具执行和 subprocess 服务，覆盖新会话完成对话、内存 inbox 恢复，以及多帧 Zstd 磁盘损坏拒绝、写锁互斥、备份、修复后官方读取。对话在内存中创建，在 Linux HOME 执行只读命令；磁盘测试只使用临时目录，不改变桌面端会话和用户项目。

更新日志

版本变更见 CHANGELOG.zh.md。

许可证

MIT