dsh-wsl-suite
Verifieddsh-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 会话里:
- 源码树里
npm run verify(类型检查 + 构建 + 73 项检查)。 plugin_manager remove_bundle target=dsh-wsl-suite,然后plugin_manager install_bundle target=file:E:\DshConfig\dsh-wsl-suite。- 重启 DSH(重装返回
application: "restart-required")。 - 如果入口又消失了:先看
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 更快),人走侧栏终端,而侧栏终端现在 自己就能进发行版。