WSL 优先路由 yishuiliufang/dsh-wsl-first

dsh-wsl-first

让 DSH 在 Windows 上优先用 WSL 执行命令。

🎯 装了 WSL 就先用 WSL，别让模型默认去写 PowerShell。

理念

DSH 在 Windows 上给模型的默认命令工具是 pwsh。这本身没什么问题，但如果机器上已经装了 WSL，这个默认就有点亏。

模型写 bash 比写 PowerShell 顺手，它的命令习惯基本是 POSIX 那一套。硬切到 PowerShell，就得在管道、转义、路径之间来回换算，换算错了还得重来一遍。每多一次重试，就是白烧掉的 token。

输出也是一样。Linux 那边的命令输出大多紧凑；PowerShell 默认给你带表格、带对象属性，同样的信息占的地方明显更大。

路径同理。WSL 工具会自动把 C:\... 转成 /mnt/c/...，不需要模型自己操心。

所以这个插件做的事情很简单：往系统提示词里加一段，写明执行命令先找 wsl。不加能力、不禁用工具，只是把默认顺序调过来。

那段提示词里只列真实注册了的工具。哪个工具没装，里面就不会出现它，也就不会出现"让模型去用一个不存在的工具"这种事。静态的指令文件做不到这点，它只会照抄。

特性

| 🚀 省 token | 少一次语法换算，就少一次重试 |
| 🐧 对准 WSL | 模型按 bash 来写，直接跑在 Linux 侧 |
| 🪟 留退路 | 真需要 Windows 原生功能时，pwsh 还在工具表里 |
| 🔧 可配置 | 想改成 bash 优先，或者只想提 wsl，改配置就行 |
| 🩺 不乱说 | 只宣传真实注册的工具，没装的不写 |
| 🖥 侧栏面板 | 左侧栏有入口，一眼看到当前首选/退路/是否发布 |

侧栏面板

插件在左侧栏注册一个入口（图标 + WSL first 标签），点开是只读面板，显示当前生效的路由：

| 面板显示 | 含义 |
| Reach for first | 首选执行器（对应 preferred） |
| Fall back to | 备选（对应 alternatives，去掉与首选重复的） |
| Last resort | 明确劝退的（对应 discouraged） |
| Prompt section | 提示词段是否在发布，以及它的 order |

面板是只读的：路由由 bundle 行的 cordis.patch.yml 决定，再给一个表单入口等于让同一个设置有两个能互相打脸的主人。要改路由就改那个文件，然后重启 profile。

面板优先读行自己的覆盖值，其次读继承来的 bundle 默认值 —— 和宿主解析同一行的顺序一致。

首次启用要重启 DSH。 客户端包的判定结果会被宿主缓存：如果某个 profile 在装上带 dsh.client 的版本之前，装过同一个包的不带客户端版本，宿主会把「这不是客户端包」也缓存下来，重启前不会重新评估。重装、刷新页面、HMR 都不会让它回心转意 —— 只有重启。之后改动客户端产物，HMR 会自己接上。

依赖

| DSH | >=0.1.7-rc.2 |
| 必需服务 | systemPrompt，标准 profile 都自带 |
| 必需插件 | dsh-wsl-tool，提供 wsl / wsl-path / wsl-env / wsl-doctor |
| WSL | WSL2，至少一个已注册的发行版，wsl.exe 在 PATH 上 |
| 平台 | 任意。Windows 是动机场景，路由器本身与平台无关 |

本插件自己不注册任何工具，只在别的插件提供的工具之间做路由。没有 dsh-wsl-tool 就没有 wsl 可首选，那段提示词会渲染成空。

安装

npm install dsh-wsl-first

装完加进 profile 的 package.json：

{
"dsh": {
"profile": {
"bundles": ["...", "dsh-wsl-first"]
}
}
}

bundle 自带 cordis.patch.yml，会把这个路由行进程级插进去，每个 agent preset 都能拿到这段提示词，不用各自声明。需要重启 profile，loader 在启动时读组合配置。

如果 wsl 工具本身还没装，先装它：

npm install dsh-wsl-tool

DSH 版本兼容

package.json 里声明了 engines.dsh: ">=0.1.7-rc.2"。

本插件没有声明任何 @deepseek-ai/* peer dependency，也不 import 它们的值。这是一条刻意的设计：DSH 启动时会用 evaluatePluginCompatibility 逐个校验 profile bundle 的 peer 区间，只要有一个不覆盖当前运行时版本，整个 bundle 会被跳过，cordis.patch.yml 不生效，表现就是"插件装了但没反应"。本插件没有任何 peer 区间可校验，也就不会因为这种原因被跳过。

升级 DSH 大版本后如果本插件突然没了动静，先看 stderr 有没有 skipping profile bundle 字样，再查 engines.dsh 是否还覆盖。

已知问题

在插件管理器里切换开关可能报错

在插件管理器里关闭（或重新开启）本插件时，可能弹出下面其中之一：

停用失败: dsh: profile reload requires the root Include entry 启用失败: dsh: warning: 1 entry did not activate

这不影响插件正常工作。 路由段仍在系统提示词里，插件照常运行 —— 只是这一次的开关没有生效，配置也不会丢失。

重启 DSH 即可：关掉应用再打开。改动会在启动时生效，之后一切正常。

在同一个 profile 里切换其他插件时，也可能出现同样的提示。

另外值得留意：DSH 运行期间编辑 profile 的 cordis.patch.yml，可能会让正在进行的会话丢失部分工具。改完这个文件请重启，不要依赖热重载。

配置

每个字段都可选，写在 profile patch（- id: wsl-first-routing / config:）或环境变量里。优先级：行配置 > 环境变量 > 内置默认值。

| 字段 | 默认值 | 环境变量 | 说明 |
| preferred | wsl | DSH_WSL_FIRST_PREFERRED | 最先尝试的工具 |
| alternatives | ['bash'] | DSH_WSL_FIRST_ALTERNATIVES | 首选项之后依次尝试（逗号分隔） |
| discouraged | ['pwsh'] | DSH_WSL_FIRST_DISCOURAGED | 压到"最后手段"的工具（逗号分隔） |
| promptPolicy | true | — | 是否发布这一段 |
| sectionOrder | 3260 | — | 段的排序位置 |
| sectionName | dsh-wsl-first:shell-routing | — | 段的稳定名称 |
| extraGuidance | '' | — | 追加到段末尾的额外文字 |
| labels | 内置 | — | 表格里 {工具: 任务描述} |
| requirePreferred | false | — | 仅当 preferred 可见时才发布 |

只提 wsl，别的都不要

- id: wsl-first-routing
config:
preferred: wsl
alternatives: []
discouraged: []

这样那段只写 wsl，在没装 wsl 的环境里干脆不出现。

改成 bash 优先

- id: wsl-first-routing
config:
preferred: bash
alternatives: []
discouraged: []

wsl 只是默认值，这插件本质是个通用的执行器路由器。

两条配置规则

同一个工具既当执行器又当"最后手段"是矛盾，会直接报错，不让某个静默的胜者决定。而 preferred 在 alternatives 里重复出现不算矛盾，那只是冗余（把 preferred 指到 bash 时会自然发生），直接去重。

渲染出来的提示词

Shell routing: wsl first

For every command execution, call wsl as the first and default tool.

| Task | Tool |
| Any command, build, git, pipeline, script, file listing, search | wsl |
| Windows-native only: registry, services, COM, cmdlets with no Linux equivalent | pwsh (last resort) |

Rules

- wsl is the primary command executor. Reach for it first, every time.
- Use pwsh only when the task genuinely requires functionality no other available tool provides — and say why in the same reply.
- Never use pwsh merely because it appears first in a tool list, and never as a fallback when a wsl command fails: fix the command and retry there.
- Do not mix shell syntaxes. A wsl call contains the syntax of the shell that tool runs; each executor has its own quoting and path rules.
- wsl paths are Linux paths (/mnt/c/...). Windows paths in command/workdir are translated automatically; pass translatePaths: false to hand a native path to a Windows program.

上面这份是从真实会话的系统提示词里读回来的。注意里面没有 bash 那一行：在实测的那个 profile 里 bash 工具没注册，路由器就把它去掉了。

它刻意不做的事

不隐藏、不禁用任何工具。 目标是让 wsl 被优先选中，而不是让 pwsh 消失。隐藏工具改变的是模型能做什么，路由段改变的只是它默认先够哪个。

想要硬版本（把 pwsh 整个摘掉）是你自己 profile patch 的事：

- id: pwsh-sandbox
disabled: true

改之前先在活着的 loader 树里确认那一行的真实 id，写错会静默失效。

项目结构

dsh-wsl-first
├── index.js # Host 端插件：注册 systemPrompt 段 ├── endpoint.js # Client 端：侧栏入口与面板 ├── lib/ │ ├── config.js # 配置解析、优先级、校验 │ └── policy.js # 层级排序与提示词渲染 ├── test/ │ ├── smoke.mjs # 配置与渲染（27 项） │ ├── mount.mjs # 真实 apply() 挂载（8 项） │ ├── docs.mjs # 断言两份 README 引用的是真实渲染（3 项） │ └── panel.mjs # 客户端挂载：注册与渲染（15 项） ├── cordis.patch.yml # bundle 层：进程级插入路由行 ├── dsh-plugin.json # 插件清单 ├── CHANGELOG.md # 更新说明 └── package.json

更新说明

每个版本改了什么见 CHANGELOG.md。

测试

npm test

lib/ 下两个模块都是纯函数，所以测试不需要 DSH 宿主。mount.mjs 用假的 cordis context 跑 index.js 里真实的 apply，断言注册出的段名、顺序和渲染文本。docs.mjs 重新渲染一次，逐字节比对两份 README 里引用的那段，所以文档里的输出不可能和代码实际产出脱节。

许可证

MIT