WSL 工作区 LyuYuxin/dsh-wsl-folder

dsh-wsl-folder

一个 DeepSeek Harness（DSH）插件，适用于 Windows 上的 Desktop 和 dsh web：在侧栏的「添加工作区」按钮里加入 WSL 文件夹，浏览 WSL 发行版，把任意 Linux 目录添加为工作区；这个工作区的侧栏终端会直接开在发行版里对应的 Linux 路径。当前版本 1.1.1。

这个插件解决什么问题

在 Windows 上用 DSH 时，工作区默认只能是 C:\、D:\ 这些 Windows 目录，而 WSL 里的项目放在 Linux 文件系统上，DSH 本身没有把两者接起来：

- 添加工作区进不了 WSL。 「添加工作区」只提供 Windows 的目录选择器，没有浏览 \\wsl.localhost 的入口。
- 终端还是 Windows 的。 即使手动把 \\wsl.localhost\<发行版>\... 填成工作区，侧栏终端仍然启动 PowerShell/pwsh，cwd 也是 Windows 路径。
- 写文件会失败。 智能体的写入/编辑工具在 WSL 的 9P 共享上会报错：新建文件 ENOTSUP，修改文件 GetFileSecurityW EIO。
- 有的路径读不到。 少数组件会把 UNC 路径开头的分隔符弄丢，于是读 AGENTS.md、侧栏文档预览时报 C:\wsl.localhost\... 不存在。

dsh-wsl-folder 补的就是这几处：添加工作区、侧栏终端和文件读写都能正确落在 WSL 里。它不会把智能体的工具搬到 Linux 侧（见「已知限制」），而是在 DSH 现有的工作方式上补上 WSL 支持。

它做什么（跟着截图走）

1. 入口不变，多一个来源。 点侧栏工作区标题栏的「+」（或新会话页工作区的「添加工作区」），弹窗先问文件夹在哪里：选「Windows 文件夹」就是原来的系统选择器，选「WSL 文件夹」打开下面的浏览器。弹窗下方还有最近用过的 WSL 位置和两条使用提示。

添加工作区：选择 Windows 文件夹或 WSL 文件夹

图 1：第一步，选择文件夹来源。

2. 浏览发行版里的目录。 右上角下拉框切换发行版（默认是 WSL 的默认发行版），从发行版默认用户的主目录开始。点文件夹进入下一级，点面包屑回到上级，点铅笔图标可以直接输入 Linux 路径并回车，「显示隐藏文件」切换点目录；底部显示将要注册的路径。

选择 WSL 目录对话框

图 2：第二步，浏览 WSL 目录。

3. 点「打开」，目录成为工作区。 Linux 目录注册为 \\wsl.localhost\<发行版>\...；如果目录在 /mnt/<盘符>/... 下（WSL 挂载进来的 Windows 盘，\\wsl.localhost 共享读不了它们），则注册成真实的 Windows 路径（如 /mnt/d/proj → D:\proj），并记住它来自哪个发行版。

4. 侧栏终端开在发行版里。 在这个工作区里打开侧栏终端，运行的是 wsl.exe -d <发行版> --cd <Linux 路径>，也就是发行版的登录 shell，起始目录就是工作区，标签为 WSL · <发行版>。Windows 工作区和智能体自己启动的终端不受影响。

WSL 工作区的侧栏终端

图 3：打开后，侧栏终端直接进入发行版。

5. 智能体正常读写工作区文件。 智能体通过 \\wsl.localhost 共享访问 Linux 目录，通过真实 Windows 路径访问 /mnt 下挂载的盘目录；插件只对共享上的目标换用共享支持的发布方式，版本校验、不覆盖别人新建的文件、原子替换这些语义保持不变。要跑 Linux 命令时，让智能体调用 wsl.exe -e <命令>，或者直接在侧栏终端里操作。

使用提示：

- 第一步的「最近的 WSL 位置」可以一键重新添加用过的目录。
- 发行版处于停止状态时，第一次打开会稍等一两秒让它启动；插件在弹出第一个对话框时就已经在后台唤醒它。
- 在插件之外（比如 DSH 自带的系统选择器）添加的 Windows 目录不会被记住，它们的终端仍是 Windows shell。

功能

- 一个按钮、两种来源。 点工作区标题栏原有的「+」（新会话页的工作区选择器同理），先选 Windows 文件夹（与原来一样的系统选择器）或 WSL 文件夹。
- WSL 目录浏览器。 选发行版、点面包屑跳转、点铅笔直接输入 Linux 路径、显示或隐藏点目录，最后点「打开」。Linux 目录以 \\wsl.localhost\<发行版>\... 的形式注册为工作区。
- 挂载进来的 Windows 盘也能选。 /mnt/c、/mnt/d 等目录（WSL 的 \\wsl.localhost 共享读不了它们）直接读对应的 Windows 盘；选中后注册成真实的 Windows 路径（如 /mnt/d/proj → D:\proj），智能体的工具可以原生读写。插件会记住它是从哪个发行版选的，所以这个工作区的侧栏终端同样开在 WSL 里。
- 最近位置。 用过的 WSL 目录会出现在第一步的列表里，点一下直接添加。
- 终端开在 WSL 里。 在 WSL 工作区里打开侧栏终端，得到的是 wsl.exe -d <发行版> --cd <Linux 路径>，也就是发行版的登录 shell，起始目录就是工作区；标签名为 WSL · <发行版>。Windows 工作区和智能体自己的工具不受影响。
- 智能体能在 WSL 工作区里写文件。 DSH 自带的写入和编辑工具在 \\wsl.localhost 上会失败（新建文件报 ENOTSUP，修改文件报 GetFileSecurityW EIO），因为 WSL 的 9P 共享不支持硬链接和 Windows 安全描述符。插件只对这类路径改用共享支持的等价操作，写入行为（版本校验、不覆盖别人新建的文件、原子替换）保持不变。
- 快。 发行版列表读注册表，主目录从发行版的 /etc/wsl.conf 与 /etc/passwd 解析，目录列表走 \\wsl.localhost 共享，热路径上不再调用 wsl.exe（每次调用要 1–3 秒）。打开对话框时就在后台唤醒发行版并预取主目录，列表结果会缓存，返回上一级时立即显示。
- 原生外观。 对话框沿用 DSH 自带 Modal、按钮、菜单项和「选择工作区目录」对话框的结构与样式，只用 --dsw- 主题变量，深浅色主题和皮肤都会跟随。

要求

- Windows 10/11，已安装 WSL（WSL2 推荐）。
- DeepSeek Harness >= 0.2.1-rc.3（Desktop 或 dsh web）。内部接口已对工作区里的 0.2.1-rc.3 源码核对，并用 npm pack 把 0.2.1-rc.5 的官方 @deepseek-ai/ 包临时下载到系统临时目录逐类比对（临时文件用完即删，仓库里没有 rc.5 源码）。
- 发行版里不需要安装任何东西。

安装

在 DSH 的「插件」页面按包名 dsh-wsl-folder 安装；或在终端执行：

dsh plugin --profile desktop add dsh-wsl-folder

也可以直接从 GitHub 安装（跟仓库源码，不经过 npm）：

dsh plugin --profile desktop add github:LyuYuxin/dsh-wsl-folder

装好后完全退出并重启 DSH，侧栏终端的重定向需要在 Host 启动时挂上。

配置

插件行的 config 有四个字段：

| 字段 | 默认 | 说明 |
| terminal | true | WSL 工作区的侧栏终端是否开在发行版里。设为 false 时终端保持 DSH 默认的 Windows shell |
| write | true | 是否让智能体的写入、编辑工具能写 \\wsl.localhost 上的文件。设为 false 时保持 DSH 原样（在 WSL 工作区里写文件会失败） |
| paths | true | 是否修复丢了开头分隔符的 WSL 路径（见下方「路径修复」）。设为 false 时保持 DSH 原样，同时关闭对 Node 文件系统函数的进程级补丁 |
| remote | false | 是否允许非本机客户端调用插件的 5 个 Host 路由。默认只接受回环地址（127.0.0.1/::1）；DSH 的 Web 服务监听在局域网地址时，其他机器无法通过本插件浏览或注册 WSL 目录，只有显式设为 true 才放开 |

在配置档的 cordis.patch.yml 里覆盖：

- id: dsh-wsl-folder
name: 'dsh-wsl-folder'
config:
terminal: false

工作原理

- 按钮。 DSH 的工作区浏览器在「+」后面声明了一个目录选择插槽（sidebar.workspaces.directoryFlow，新会话页是 conversation.hero.workspace.directoryFlow）。本插件以更低的优先级占住这两个插槽，自己的对话框画在 shell.overlay 里；选 Windows 文件夹时调用的正是 DSH 原生选择器那一个接口。
- Host 路由。 GET /dsh-wsl-folder/{distros,home,list,warm} 和 POST /dsh-wsl-folder/pick（JSON 请求体，决定要注册的路径），都拒绝跨站请求，并且默认只接受来自回环地址（127.0.0.1/::1）的客户端；Web 服务监听在局域网地址时，其他机器无法借这些路由浏览目录、写记忆文件或唤醒发行版。需要远程访问时把插件行的 remote 设为 true。
- Windows 盘与兜底。 路径落在自动挂载根（默认 /mnt/，读 /etc/wsl.conf 的 [automount] root）下的盘符目录时，直接读 Windows 路径；\\wsl.localhost 共享读不了的其他目录，改在发行版里用 find 列出。从 WSL 选中的 Windows 盘目录记在 <DSH 主目录>/dsh-wsl-folder.json。
- 终端。 侧栏终端由 DSH 的 terminal controller 通过 subprocess.spawnTerminal({ argv, cwd }) 创建。插件只在「正在分配侧栏终端」这一段调用里（用 AsyncLocalStorage 标记）检查 cwd：如果是 \\wsl.localhost\<发行版>\<路径>，或位于记录过的 Windows 盘目录里，就把 shell 换成 wsl.exe -d <发行版> --cd <路径>。插件卸载时恢复原方法。
- 写文件。 DSH 的本地文件系统（LocalFileSystem，沙箱版本继承自它）先把内容写进同目录下的临时文件，再「发布」：新建文件用硬链接（目标已存在就失败，避免覆盖别人刚建的文件），在 Windows 上修改文件则先复制安全描述符再调用 ReplaceFileW。插件包装它的 writeText / editText：目标在 \\wsl.localhost 上时，这一次调用改用排他复制（同样在目标已存在时失败）和 rename 覆盖；其他路径不经过任何改动。
- 路径修复。 Windows 上以单个 \ 开头的路径是「当前盘根目录」，所以 \wsl.localhost\... 会被解析成 C:\wsl.localhost\...——一个不可能存在的路径。WSL 工作区里读 AGENTS.md 时报的就是这个错。DSH 自身不会生成这种写法，是某处调用链把开头的一个分隔符弄丢了；插件在文件系统唯一的入口 resolve（以及 lstat）上做修复：只对「开头一个分隔符 + wsl.localhost/wsl$ + 已安装的发行版名」的路径补回分隔符，其他路径原样通过。另有一层「最后一公里」修复：进程级包装 node:fs 与 node:fs/promises 的一组读取函数（stat/lstat/readFile/readdir/open/access/realpath 及其同步版本），让已经自己解析过路径的组件（如侧栏文档预览）也走修复，并调用 syncBuiltinESMExports() 刷新 DSH 模块的具名导入。这是进程全局的副作用：paths: false 会同时关闭这两层修复和诊断日志。

已知限制

- 智能体的工具仍是 Windows 的。 本插件管添加工作区、侧栏终端和共享上的写入；智能体的 shell 和文件工具照常在 Windows 侧运行，Linux 目录通过 \\wsl.localhost 共享访问（速度比原生 Linux 慢）。
- WSL 共享上新建文件不是原子的。 排他复制在极短时间内可能让别的程序看到写了一半的新文件（修改已有文件仍是原子的 rename）。
- 共享读不了的非 Windows 盘目录（例如权限受限的目录）改由发行版里的 find 列出，每次要 1–3 秒；没有读权限时会明确提示。
- 在插件之外（比如 DSH 自带的系统选择器）直接添加的 Windows 目录不会被记录，它们的终端仍是 Windows shell。
- WSL 工作区的终端总是开在 WSL 里，即使在终端菜单里选了 PowerShell。需要 Windows shell 时把 terminal 设为 false。
- 终端里的 DSH_SESSION_ID 环境变量不会传进发行版。
- 终端重定向、写入修复和路径修复依赖 DSH 内部的 TerminalController.spawn、spawnTerminal、LocalFileSystem 的 writeText / editText / internals / resolve（路径修复还会进程级包装 Node 的 fs / fs/promises 读取函数）；DSH 改了这些地方时对应功能会退回 DSH 原样（终端变回 Windows shell、或在 WSL 工作区写文件、读 AGENTS.md 再次失败），添加 WSL 工作区仍然可用。

测试

node --check index.js
node --check client.js
node --test

纯函数、/etc/wsl.conf 与注册表解析、HTTP 路由（用 mock 的 req/res 覆盖方法、跨站、回环限制、Content-Type、JSON 体积上限和错误映射）、终端重定向、写入修复、路径修复（含进程级 fs 包装的挂载/还原）和诊断日志轮转都有不依赖 DSH 的单元测试；在装有 WSL 的 Windows 上，还会对真实发行版跑一遍路由，并在真实的 9P 共享上验证新建、不覆盖、修改文件——WSL 不可用时这一节显示为 skipped，其余测试照常通过。CI 在 windows-latest + Node 22/24 上运行同样的命令，并用 npm pack --dry-run 校验发布文件清单（workflow）。

许可证

MIT