dsh-wsl-folder

dsh plugin --profile web add dsh-wsl-folder

dsh-wsl-folder

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





一个 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 路径。
• 写文件会失败。 agent 的写入/编辑工具在 WSL 的 9P 共享上会报错：新建文件 ENOTSUP，修改文件 GetFileSecurityW EIO。
• 有的路径读不到。 少数组件会把 UNC 路径开头的分隔符弄丢，于是读 AGENTS.md、侧栏文档预览时报 C:\wsl.localhost\... 不存在。

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

它做什么（跟着截图走）

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

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

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

图 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 工作区和 agent 自己启动的终端不受影响。

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

5. agent 正常读写工作区文件。 agent 通过 \\wsl.localhost 共享访问 Linux 目录，通过真实 Windows 路径访问 /mnt 下挂载的盘目录；插件只对共享上的目标换用共享支持的发布方式，版本校验、不覆盖别人新建的文件、原子替换这些语义保持不变。要跑 Linux 命令时，让 agent 调用 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），agent 的工具可以原生读写。插件会记住它是从哪个发行版选的，所以这个工作区的侧栏终端同样开在 WSL 里。
• 最近位置。 用过的 WSL 目录会出现在第一步的列表里，点一下直接添加。
• 终端开在 WSL 里。 在 WSL 工作区里打开侧栏终端，得到的是 wsl.exe -d <发行版> --cd <Linux 路径>，也就是发行版的登录 shell，起始目录就是工作区；标签名为 WSL · <发行版>。Windows 工作区和 agent 自己的工具不受影响。
• agent 能在 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 · 是否让 agent 的写入、编辑工具能写 \\wsl.localhost 上的文件。设为 false 时保持 DSH 原样（在 WSL 工作区里写文件会失败）

paths · true · 是否修复丢了开头分隔符的 WSL 路径（见下方「路径修复」）。设为 false 时保持 DSH 原样，同时关闭对 Node 文件系统函数的进程级补丁

remote · false · 是否允许非本机客户端调用插件的 5 个 Host 路由。默认只接受回环地址（127.0.0.1/::1）；DSH 的 Web 服务监听在局域网地址时，其他机器无法通过本插件浏览或注册 WSL 目录，只有显式设为 true 才放开

在 profile 的 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。插

…(truncated)