Skip to content

dsh-wsl-suite

Verified

dsh-wsl-suite · v0.1.8 · MIT · Web UI

WSL workspaces for DeepSeek Harness, served by one persistent in-distro agent instead of 9P polling.

Install

dsh plugin add dsh-wsl-suite

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Readme

dsh-wsl-suite

DeepSeek Harness 的 WSL 工作区插件。对 dsh-wsl-workspace 的重写,基座不同:发行版内一个常驻 agent 进程,走 JSON-lines 管道通信, 而不是 9P 文件共享加每次命令一个 spawn。

(本文为 README.md 的中文版,内容对应;以英文版为准。)

English · 中文

版本 0.1.8
宿主 DeepSeek Harness 0.2.1-rc.5(桌面版与 Web 版)
Node >= 22
发行版 任意 WSL2 发行版(在 Ubuntu 26.04 上测试)
对等依赖 @deepseek-ai/cordis ^4.0.5 · @deepseek-ai/dsh-fs / dsh-shell / dsh-sandbox / dsh-subprocess / dsh-tools ^0.2.1-rc.5 · @deepseek-ai/schemastery ^3.18.5
客户端注入 @deepseek-ai/dsh-client-ui-slots · @deepseek-ai/dsh-client-ui-sidebar

致谢

本插件离不开 dsh-wsl-workspace 及其作者 刘云韬(@6Mikao9) 与各位维护者的工作。 那个插件验证了本插件所服务的完整工作流——从侧栏添加 WSL 工作区、让整个会话 跑在发行版内——它的客户端设计(标题栏入口挂载、添加工作区弹窗、footer 席位回退)正是 src/client/ 遵循的蓝图。本插件换的是基座,不是想法: 向原作者与维护者致谢。

dsh-wsl 的问题请在本仓库提 issue;dsh-wsl-workspace 本身的问题请到它 自己的仓库反馈。

浏览器 ──POST /dsh-wsl/api──▶ 宿主插件 ──管道──▶ node agent.mjs(发行版内)
                                    │                       │
                                    └── ctx.fs / ctx.shell ◀─┘

为什么换基座

在本机对真实 Ubuntu 发行版实测:

操作 9P 共享(//wsl.localhost/…) 每次调用一个 wsl.exe spawn 本 agent
stat 4.3 ms 212–282 ms 0.20 ms
readdir 2.8 ms 212–282 ms 0.25 ms
跑一条命令 — 212–282 ms 13–20 ms
对 5.2 GB 仓库 glob(64,625 个文件) 44 s(且漏掉约一半目录树) — 0.59 s

由此带来三个后果,也是重写要达到的全部目的:

  • 不再轮询。 旧插件每 3 s 扫一遍共享、每 30 s 走一遍目录树来感知变化。 对共享而言每轮巡检都是一串多毫秒的元数据调用,会伸进发行版,而且 WSLg 开着时每半分钟把焦点拉到 Windows 桌面一次。现在 agent 是按需被问询的, 所以这些定时器是被删掉而不是被调优——空闲时没有任何东西碰发行版。
  • /mnt/<盘符> 可用。 9P 共享只服务 ext4,drvfs 挂载对它不可见, 这逼得旧插件把这些路径改路由到 Windows 盘符、靠探测每个盘来合成 /mnt 条目。在发行版内 /mnt/c 只是个目录,改路由和探测随之删掉,连同 「工作区键与它的路径不一致」这一类 bug 一起消失。
  • 搜索在发行版内执行。 旧插件的 grep/glob 是宿主工具,靠打包的 Windows ripgrep 对共享跑:整仓走一遍 44 s(9P)对比发行版内 0.29 s,内容搜索 150 s 对比 0.79 s,而且 9P 那次返回 22,436 行、原生返回 41,838 行——悄悄漏了约一半目录树。所以 WSL 变体换上 search-wsl,通过 agent 跑发行版自己的 rg。同一个 glob '*.toml' 查询 2.3 s 返回 891 个文件。

它为你做什么

  • 从侧栏添加 WSL 工作区。 在「工作区」分区标题栏,按自带「添加工作区」 控件旁的 W 按钮(标题栏不存在时回退到底部列表入口)。弹窗列出已安装 的发行版并浏览 Linux 文件系统;「添加此文件夹」通过宿主自己的工作区 注册表登记——WSL 工作区只是路径为 UNC( \\wsl.localhost\Ubuntu\home\you\…)的宿主工作区,只有这一条记录, 没有会漂移的私有存储。
  • 侧栏终端跟着会话进发行版。 工作区是 WSL 路径的会话,其终端在发行版 内打开——真正的 bash 配真正的 pty(输入、输出、resize 全部回环)。 Windows cwd 的会话原样不动。
  • 模型拿到 WSL 原生工具。 每个健康预设都有一个 wsl-<mode> 孪生变体 (standard → wsl-standard),把 shell/fs 工具换成 WSL 版,并新增跑 发行版自带 ripgrep 的 grep/glob——覆盖 /mnt/<盘符>,对不可读目录 宽容(exit 2 保留部分结果而不是让整次调用失败)。
  • 已本地化。 弹窗跟随 navigator.language:zh-* 显示简体中文, 其余英文。

目录里有什么

文件 职责
agent/agent.mjs 发行版内运行的零依赖 Node 脚本:stat、lstat、readdir、read、readRange、write、mkdir、remove、realpath、exec、kill、ping,走 JSON lines。启动时重建一次登录环境,--exec 也能看到 ~/.local/bin。
src/channel.ts 管道的宿主侧:拉起 agent、按 id 配对回复、10 分钟空闲即关(空闲 = 无未完成请求,30 分钟的测试跑不会被杀)、每个发行版一条通道、死后重开。
src/shell.ts WslShellExecutor extends ShellExecutor——退出码、流分离、实时流、杀进程组的超时、保尾输出上限、后台句柄(其未观察的 rejection 永远不会杀死宿主)。
src/fs.ts WslFileSystem extends FileSystem——12 个原语、版本守卫写入、FS_STALE_VERSION/FS_AMBIGUOUS_EDIT/FS_NOT_TEXT 处理、沙盒围栏、rename 原子写,以及逐字节保真的 CRLF:接缝的 LF 归一化只作用于上报的 before/after,永不动磁盘字节。
src/search.ts grep 和 glob 工具,ripgrep 在发行版内执行。
src/terminal.ts 让侧栏终端跟着 WSL 会话进去:包装宿主唯一的 subprocess.spawnTerminal,UNC cwd 改写为 wsl.exe -d <distro> --cd <linux> -- <shell>。
src/client/index.tsx 浏览器半边:W 标题栏入口(经 src/client/hostEntry.ts),底部列表入口作回退兼发现锚点;添加工作区弹窗(src/client/styles.ts 负责样式,src/client/locale.ts 放中英文字符串)。
src/client/baseline.ts 设计基线(dsh-design-baseline v1.1.0)的 vendored 副本:六个 accent 色,中性色面映射自宿主的 --dsw-alias-*。client bundle 无法 require 文件路径,所以是内联而非 import。
src/host/variants.ts 预设变换:把 agent 预设改写成它的 WSL 变体。只操作解析后的行,不碰缩进。
src/rows.ts wsl-world 组:shell-wsl + fs-wsl + search-wsl,置于 isolate: {shell: true, fs: true} 下。
src/index.ts 宿主入口:发行版发现、wsl-<mode> 物化、DSH_WSL_DISTRO、一条仅回环的 POST 路由。

侧栏席位

W 控件挂在「工作区」分区标题栏里自带添加按钮旁——旧 dsh-wsl-workspace 插件的处理方式。标题栏是宿主私有的(没有任何 slot 声明 它),所以 src/client/hostEntry.ts 沿用参考插件的手法:从 footer action 自己的 DOM 元素向上走到 [class*="_sectionHeader"] / [class*="_headerActions"],注入一个 <span class="dww-header-slot">,用添加按钮自己的类名列表把 HostEntryButton React 渲染进去,并观察该条带(React 重渲染会丢弃陌生 子节点)。条带 60 px 的宽度上限在入口就位期间放宽到 92 px( src/client/styles.ts 里的 max-width: 92px),否则第三个按钮被裁切; shipped-hidden 变体则保持收起。

底部入口仍注册在 sidebar.footer.action(list 型 slot、 replaceRisk: "none"、新 id dsh-wsl-suite)——标题栏席位在场时隐藏,标题栏 缺席时作回退(rail 侧栏、发版改了类名)。它也是标题栏发现向上走的锚点。

快捷键

这个入口也能用键盘打开。apply() 向宿主自己的快捷键服务注册一条命令 (workspace.wsl-add,Ctrl+Shift+W / ⌘⇧W)——这是普通注册,不是自建的按键 监听,所以绑定由宿主保存、出现在设置 → 通用 → 快捷键里,用户可以像内置命令 一样重新绑定。web:linux 一项故意不声明:浏览器白名单在该平台不接受双修饰键 绑定,而缺省的 profile 只是未绑定,不会导致整条注册失败。tooltip 里的键帽取自 宿主解析后的结果(ctx.shortcuts.catalog),用户改键后会重绘,按钮上也带着同一 个值的 aria-keyshortcuts。

配色

弹窗遵循设计基线(dsh-design-baseline,以 src/client/baseline.ts vendored 进包里): 所有中性色面取自宿主自己的 --dsw-alias-* 令牌,颜色只来自六个 accent——绿表添加成功、 玫红表失败、蓝表聚焦,别无其他。主按钮用反色而不是彩色,因为颜色留给状态。基线把中性色 映射在 .dsb-root 而不是 :root 上,深色主题的覆盖才能真正生效,所以遮罩层带着这个类。 外壳部分(底部按钮与标题栏入口)仍直接用 --dsw-*,保持和宿主自己的图标按钮同一个样子。

src/client/baseline.ts 第一行是一条 /*! >>> dsh-design-baseline v1.1.0 sha256 … */ 标记注释。它不是装饰:基线的 check-all.mjs 用这条标记区分「带着编译好整份样式表的插件」 (此后会拿 dist/theme.js 比对漂移)与「只手工抄了几个令牌的插件」。基线重新构建后要 重新生成这个文件——标记里的哈希必须跟着动。

终端

侧栏终端不由 terminals 注册表驱动,加终端后端够不着它。 terminalController 从 agent.ctx.get('subprocess') 取环境,直接调 subprocess.spawnTerminal(...)。该服务是单槽的,agent.ctx 在任何预设组 之外,所以预设无法提供 WSL 版——隔离只向后代传播,预设注册表还会拒绝泄进 宿主域的服务。

它能做的是原地包装宿主 provider 的 spawnTerminal,src/terminal.ts 就是 这么干的。判别信息本来就在请求里:发行版内的会话 cwd 是 UNC,包装器把这一 次调用改写成

wsl.exe -d <发行版> --cd <linux cwd> -- <shell>

于是宿主自己的 ConPTY 带起一个真正的 Linux pty——输入、输出、resize 全部 回环。Windows cwd 的会话逐字节原样通过。

resolveExecutable 和 terminalEnvironment 有意不动:它们回答的是宿主级 问题(Windows 上哪个 bash.exe 存在),只参与 shell 发现和参数拼装。真正启动的 shell 在这里决定——请求的 POSIX shell 名会被带进发行版(/bin/zsh、/bin/fish……, 找不到就退回 /bin/bash),发行版自己的 shell 都能跟随。

预设变体,不是全局模式

shell 方言必须随世界改变:发行版外 agent 跑 pwsh,发行版内跑 bash。 所以不做全局路由 provider,而是给 profile 里每个健康预设一个 wsl-<mode> 孪生(standard → wsl-standard),其 shell 与文件工具换成 WSL 版。 预设其余部分——人设、技能、任务、委派——原样带过。

从 WSL 工作区新建会话现在会默认进入 wsl-standard 孪生变体,而不是宿主的 Windows standard:插件包装了会话创建服务,当调用方未指定预设、且目标路径是 WSL UNC 路径时,自动填入 wsl-standard。在新会话界面显式选择的预设始终优先, Windows 工作区不受影响。配置项 defaultPreset(默认 wsl-standard)指定该孪生; 设为空字符串可保留宿主默认行为。若该孪生尚未发布,请求会原样透传。

变换按 id 在解析后的文档里匹配行,因此对原版那种「嵌套 subagent 行 不可见」(tool "subagent" is already registered in this scope)的缩进脆弱 性免疫。它还会把被抬进 world 的行上的 disabled: !!js process.platform === 'win32' 门清掉:该表达式由加载器在宿主上求值,带过去 会恰好禁用这个变体要提供的工具。

!!js 表达式以 {__jsExpr: …} 节点形状在往返中保留——这正是宿主加载器 自己测试的形状,所以重新注册的预设仍会求值自己的门。

安装、更新、验证

从 npm 安装(常规方式)。 发布名是 dsh-wsl-suite(dsh-wsl 因 npm 防山寨规则不可注册),bundle 与其中各行同名。在 profile 目录里:

# 在 C:\Users\<你>\.dsh\profiles\desktop\ 下
pnpm add dsh-wsl-suite          # 或:npm install dsh-wsl-suite

然后在同一文件的 dsh.profile.bundles 里加 "dsh-wsl-suite" 并重启 harness。

从 GitHub 安装。 结果相同,适合版本还没发到 registry 之前:

pnpm add "dsh-wsl-suite@github:stallenlu/dsh-wsl-suite"

github: 规格按 tarball 拉取,每次推送整体替换副本——没有 file: 那套 remove/reinstall 流程。

预构建 Release tarball。 每个 Release 还挂了一个可直接安装的 dsh-wsl-suite.tgz(无需构建,因此跳过 allowBuilds 授权):

pnpm add https://github.com/stallenlu/dsh-wsl-suite/releases/download/v0.1.8/dsh-wsl-suite.tgz

资产名不含版本号、URL 钉死在 tag 上,后续发版不会让链接失效。 awesome-dsh-plugin 目录条目把这个 URL 作为 tarball: 备选。

有一条命名规则必须知道,违反它会让启动静默失败:客户端 bundle 的注册 id 必须等于包名。 宿主按包名给客户端 boot 图建 key(dsh-client-modules/lib/index.js 的 this.table.set(packageName, …)), 其 arrive() 只接受在该 id 下注册了 factory 的 bundle——否则 entry 永不激活,渲染端报 client-modules: duplicate factory registration。tsdown.config.ts 把这个 id 写进 bundle banner, tests/client.test.ts 断言它与 package.json 一致。

本地检出(开发):

# 真源——在这里改
E:\DshConfig\dsh-wsl-suite\
# harness 实际加载的副本(是文件复制,不是符号链接)
C:\Users\GT14\.dsh\profiles\desktop\node_modules\dsh-wsl-suite\

因为安装副本是复制,每处源码改动都要重装;在 DeepSeek Harness 会话里:

  1. 源码树里 npm run verify(类型检查 + 构建 + 73 项检查)。
  2. plugin_manager remove_bundle target=dsh-wsl-suite,然后 plugin_manager install_bundle target=file:E:\DshConfig\dsh-wsl-suite。
  3. 重启 DSH(重装返回 application: "restart-required")。
  4. 如果入口又消失了:先看 C:\Users\GT14\.dsh\profiles\desktop\package.json 的 dsh.profile.bundles 是否还含 dsh-wsl-suite(并发的 profile 改写曾把它 掉过),再 plugin_manager set_bundle target=dsh-wsl-suite enabled=true 热挂载——启动稳定且没有其他 HMR 事务时无需重启。

不进 UI 的快速宿主侧自检:

curl -X POST http://127.0.0.1:<gui-port>/dsh-wsl/api \\
  -H "content-type: application/json" -d '{"method":"listDistros"}'
# → {"ok":true,"value":{"distros":[{"name":"Ubuntu","default":true}]}}

check 和 listDir 走发行版内的常驻 agent,所以 200 加真实条目即可证明 整条管道通。

开发

npm install          # devDependencies 钉住 0.2.1-rc.5 宿主接口
npm run typecheck    # 还需 @deepseek-ai/dsh-llm(已钉在 devDependencies)
npm run build        # lib/{index,fs,shell,search,client}.js + paths-*.js
npm test             # 73 项检查;live 的在没有发行版时跳过而非失败
npm run verify       # 类型检查,然后 build + test

tests/live.test.ts 对真实发行版运行,wsl.exe -l -q 无输出时跳过—— 所以在没有 WSL 的机器上套件依然诚实。tests/client.test.ts 按宿主加载器 的方式加载构建产物,所以 npm test 先构建(pretest);那是浏览器半边 唯一被检查的地方,因为 tsconfig.json 排除了它。

有意不做

  • 不做 fs.watch。 宿主侧无法监听发行版的文件系统;侧栏文件浏览器会 吞掉随之产生的 workspace-file/watch-unsupported 码并做一次性刷新。 参考插件同样没有 watch。
  • sandboxMode 保持 undefined。 WSL 虚拟机本身就是边界,宿主沙盒 策略在它内部没有可围栏的东西。
  • 不做 wsl_terminal 模型工具 / persistent-shell 终端门 / 工作区右键 菜单项。 旧插件的模型侧终端和菜单 hack 已被取代:模型走常驻管道 (结构化退出码与流,比驱动 pty 更快),人走侧栏终端,而侧栏终端现在 自己就能进发行版。