前言¶
在 Windows 上使用 DeepSeek Harness（DSH）时，模型默认拿到的命令执行工具往往是 pwsh。若本机已经装了 WSL，这个默认顺序会带来额外成本：模型更习惯写 bash 与 POSIX 管道，被迫切到 PowerShell 时，引号、路径和管道语义容易来回翻译，失败一次就多一轮重试，消耗 token。输出形态也不一致——Linux 命令多为紧凑纯文本，PowerShell 默认常带表格与对象属性，同样信息占用的上下文更长。
下面介绍社区插件 dsh-wsl-first（维护者 yishuiliufang），分类为工作流。它不新增工具、也不禁用任何工具，只在系统提示里插入一段可配置的「Shell 路由」说明，引导模型优先调用 wsl，需要 Windows 原生能力时再退到 pwsh。DSH 生态是「一切皆插件」；插件目录站点 SkillHub 为社区独立维护，与 DeepSeek / 幻方无官方从属关系。
这是什么¶
dsh-wsl-first 是一个基于 systemPrompt 服务的可配置路由器：在系统提示中追加「优先用 wsl 执行命令」的段落，改变默认选择顺序，而不是替换或隐藏 pwsh。路由文案只会列出当前 profile 里已注册的执行器；未安装的工具不会出现在提示里，避免模型被指示调用不存在的工具。
插件自身不注册任何 tool，路由目标由其他插件提供。没有 dsh-wsl-tool 时，就没有 wsl 可优先，对应段落会渲染为空。
核心功能¶
- 优先 WSL：默认
preferred为wsl，discouraged含pwsh，模型被引导先走 Linux 侧 bash。 - 保留 Windows 出口：
pwsh仍在工具列表中，仅作为「确实需要 Windows 原生能力」时的最后手段。 - 可配置顺序：可把首选改为
bash，或只宣传wsl、清空备选与 discouraged 列表。 - 动态工具表：段落内的任务—工具表随当前已注册工具生成；例如 profile 未注册
bash时，渲染结果里不会出现bash行。 - 进程级 patch：包内自带
cordis.patch.yml，通过 profile 的 bundle 挂载后，各 agent preset 无需单独声明即可带上该段提示。
环境与依赖¶
| 项 | 要求 |
|---|---|
| DSH | >=0.1.7-rc.2（package.json 中 engines.dsh） |
| 服务 | systemPrompt（标准 profile 自带） |
| 依赖插件 | dsh-wsl-tool（提供 wsl / wsl-path / wsl-env / wsl-doctor） |
| WSL | WSL2，至少一个已注册发行版，wsl.exe 在 PATH 上 |
| 平台 | 路由逻辑与平台无关；主要动机场景是 Windows |
安装与启用¶
先用 npm 安装包（与 README 一致，勿自行拼接其他安装命令）：
npm install dsh-wsl-first
在 profile 的 package.json 里把 bundle 加入 dsh.profile.bundles：
{
"dsh": {
"profile": {
"bundles": ["...", "dsh-wsl-first"]
}
}
}
bundle 会加载自带的 cordis.patch.yml，在进程范围内插入路由行。修改 bundle 后需要重启 DSH（或重启 profile），loader 在启动时读取组合关系。
若尚未安装 wsl 工具，先安装依赖插件：
npm install dsh-wsl-tool
版本兼容说明：本插件未声明 @deepseek-ai/* peer dependency。DSH 启动时会对 bundle 做兼容性检查；若某 peer 范围不匹配运行版本，整个 bundle 可能被跳过，表现为「装了但没效果」。升级 DSH 大版本后若失效，可在 stderr 中查找 skipping profile bundle，并确认 engines.dsh 仍覆盖当前版本。
插件以当前 DSH 进程权限运行；安装前建议阅读 GitHub 仓库 源码与 MIT 许可证（package.json 当前版本 0.1.0）。
配置¶
字段均可写在 profile patch（- id: wsl-first-routing / config:）或环境变量中。优先级：行内 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、不写备选（未装 wsl 的环境整段不出现）：
- id: wsl-first-routing
config:
preferred: wsl
alternatives: []
discouraged: []
改首选为 bash（插件本质是通用执行器路由器，wsl 只是默认）：
- id: wsl-first-routing
config:
preferred: bash
alternatives: []
discouraged: []
配置约束：同一工具不能既在首选/备选又在 discouraged，否则会抛错；preferred 重复出现在 alternatives 中会被去重。
系统提示中的效果¶
启用后，系统提示中会插入类似下面的段落（实际内容随已注册工具变化；下列示例来自 README 中 live session 读回，该 profile 未注册 bash，故无 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.
dsh-wsl-tool 会在 wsl 侧处理 C:\... 到 /mnt/c/... 的路径转换，模型在多数场景下无需手动换算。
适用场景与注意¶
适合：Windows 上已装 WSL2 与 dsh-wsl-tool，希望 agent 默认在 Linux 环境跑 git、构建、管道与常见 CLI，减少 PowerShell 语法摩擦与重试。
不适合或需额外准备：无 WSL、或未装 dsh-wsl-tool 的环境——路由段为空或无法指向 wsl。
已知问题（不影响运行逻辑）：在插件管理器中开关本插件时，可能出现「停用失败: dsh: profile reload requires the root Include entry」或「启用失败: dsh: warning: 1 entry did not activate」。路由段仍会生效；重启 DSH 后开关状态与提示会按启动加载恢复正常。运行中直接改 profile 的 cordis.patch.yml 可能从 live session 剥离工具，改完后应重启而非依赖热重载。
若希望硬性去掉 pwsh（而非仅路由），需在 profile patch 中自行禁用对应 sandbox 行（例如 - id: pwsh-sandbox / disabled: true，以 loader 树中真实 id 为准）——这与本插件「只改默认顺序、不隐藏工具」的设计是不同层级的选择。
结尾¶
dsh-wsl-first 用一段动态生成的系统提示，把命令执行默认顺序从 pwsh 调到 wsl，在不剥夺 Windows 原生能力的前提下，让模型按更自然的 bash 习惯工作。目录与详情见 SkillHub 插件页，源码与完整说明见 GitHub：yishuiliufang/dsh-wsl-first。
