前言¶
在 Windows 上给 DSH 智能体配终端时，常见做法是固定一种后端：要么全程 Git Bash，要么全程 PowerShell，要么单独走 WSL。真实任务里却经常在同一轮对话里混用——POSIX 管道适合 grep/sed，PowerShell 适合查注册表或 .NET，Linux 工具链又更适合 WSL 里的发行版环境。若只能在设置里选「默认终端」，模型无法按命令语法逐次切换，容易写出在错误 shell 里跑不通的脚本。
dsh-multi-shell 是社区维护者 deepseekv41flash 发布的 DSH 工作流类插件（npm 包名 dsh-multi-shell，当前 README 对应版本 0.1.2，MIT 许可证）。它只向宿主注册一个名为 shell 的工具，但在每次调用时通过参数 shell 让模型在 Git Bash（默认）、PowerShell、WSL 之间自行选择后端，并在 profile 里用普通对象配置覆盖超时、路径探测等默认值。下文按「是什么 → 能力 → 安装 → 用法 → 注意」说明，事实均来自 GitHub 仓库 README 与 npm 包说明。
这是什么¶
一句话：dsh-multi-shell 把「跑 shell 命令」收敛成单一工具面，把「用哪种 Windows/Linux 执行环境」交给模型在每次调用里决定。
与同属终端方向的 dsh-bash-terminal 相比，README 只强调两点差异：
| dsh-bash-terminal | dsh-multi-shell | |
|---|---|---|
| 选后端的人 | 用户在设置页选「默认终端」，模型不能改 | 模型通过 shell 参数逐次选择 |
| 跨 DSH 版本 | peerDependencies 声明较窄的版本范围 |
全部 peerDependencies: "*，模块内无版本门控；可选服务按调用解析，缺一项只影响单次调用 |
插件本体是纯 ESM、零构建：package.json、lib/、cordis.patch.yml 即可运行；Node 要求 >=20。
核心功能¶
单一 shell 工具与参数¶
模型可见的主要参数如下（必填与默认值以 README 为准）：
| 参数 | 必填 | 说明 |
|---|---|---|
command |
是 | 命令正文；语法须匹配所选后端 |
description |
是 | 5–10 词的主动语态说明（供 UI 展示） |
shell |
否 | gitbash（默认）/ powershell / wsl |
distro |
否 | 仅与 shell=wsl 同用；WSL 发行版名，缺省为系统默认 |
workdir |
否 | 工作目录；相对路径按会话目录展开 |
timeoutMs |
否 | 前台超时（毫秒），默认 120000、上限 600000 |
run_in_background |
否 | 后台任务，返回 job id，配合 job_output / job_kill |
sandbox_permissions + justification |
否 | 沙箱升级，仅 powershell 后端有意义，经 ctx.approval 审批 |
三个后端实际执行的 argv 概要：
- gitbash：
<Git>\bin\bash.exe -lc <command>（POSIX；$VAR；PATH 含/usr/bin、/mingw64/bin） - powershell：
pwsh -NoLogo -NoProfile -NonInteractive -Command <UTF-8 前导 + command>；前导固定控制台与管道为 UTF-8，并带LanguageMode守卫，避免只读沙箱下每次往 stderr 打两条InvalidOperation - wsl：
wsl [-d <distro>] -e bash -lc <command>；DSH_*经WSLENV传入
非零退出在输出末行以 [exit code: N] 标记；超时以 [timed out after Nms] 开头且仍带退出码；输出超过 64 KiB 会截尾并给出完整 spill 文件路径。
沙箱与审批¶
- PowerShell：在
read-only/workspace-write下经ctx.sandbox.confine包装 argv（fail-closed）；无可用 provider 时拒绝执行，不会裸跑。 - Git Bash / WSL：README 说明 DSH 的 Windows ACL 受限令牌 runner 无法稳定启动 Cygwin/MSYS2 bash，WSL 亦仅为进程隔离、
/mnt/c仍可写，故这两路不隔离；受限会话下结果中会追加模型可见的[sandbox: …]提示行。 - 沙箱升级：
sandbox_permissions只对powershell开放；对 gitbash/wsl 传该参数会报错。
工具描述中还写入了宿主机启用 Sudo for Windows 内联模式 时，从 gitbash 提权跑管理员 PowerShell 的模板（每次 UAC、无凭据缓存；不要用 UI 自动化点 UAC）。
可配置项¶
在 profile 的 patch 里可按需覆盖（普通对象，无 schemastery schema）：
- id: tool-multi-shell
config:
defaultShell: gitbash # 模型不传 shell 时的后端
pwshPath: '' # 留空则自动探测
gitBashPath: ''
wslPath: ''
timeoutMs: 120000
maxTimeoutMs: 600000
maxOutputBytes: 65536
maxSpillBytes: 67108864
graceMs: 3000
enableRunInBackground: true
apply() 启动时会校验数值配置（须为正有限数等），非法值在启动阶段报错并指明字段名。
README 记载在 DSH 0.2.1-rc.4 / desktop-next 2.0.21-next 环境下做过多项验证（默认 gitbash、pwsh UTF-8、WSL 路径映射、超时、后台 job、沙箱探针、审批 allow-once/rejected、sudo 模板等）；未验证项（如审批 cancelled、workspace-write 升级后的实际执行在特定宿主布局下受限）也在 README 中单独列出。
安装与启用¶
从 npm 安装到某个 profile（把包加入该 profile 并登记到 bundles，重启 DSH 后生效）：
dsh plugin --profile desktop add dsh-multi-shell
# 然后把 "dsh-multi-shell" 加进该 profile package.json 的 dsh.profile.bundles 数组
# （或用 DSH 设置页的插件管理器安装，它会同时写 dependencies + bundles）
npm 包地址：https://www.npmjs.com/package/dsh-multi-shell。
回滚时从 profile 的 dsh.profile.bundles 与 dependencies 移除 dsh-multi-shell 并删除 junction；若要恢复 dsh-bash-terminal，需去掉 cordis.patch.yml 里对 tool-bash-terminal 的 disabled: true。两个插件都注册 shell 工具名，同时只能启用一个。
社区目录页（与 DeepSeek / 幻方无官方从属关系）：https://www.skillhub.cn/plugins/deepseekv41flash/dsh-multi-shell。
典型用法¶
用法即模型（或你在调试时）对 shell 工具的调用约定，没有单独的 CLI 子命令。
1、默认 Git Bash 跑 POSIX 命令（不传 shell 或 shell: gitbash）：
{
"command": "echo \"$PATH\" | head -c 80",
"description": "Show PATH prefix in Git Bash"
}
2、需要 PowerShell 语法或 .NET 时显式选后端：
{
"command": "Get-Location | Select-Object -ExpandProperty Path",
"description": "Print current directory via pwsh",
"shell": "powershell"
}
3、在指定 WSL 发行版里跑 Linux 命令（distro 仅在与 wsl 同用时有效）：
{
"command": "uname -a && pwd",
"description": "Check Linux kernel and cwd in WSL",
"shell": "wsl",
"distro": "Debian",
"workdir": "C:\\Users\\Admin\\project"
}
4、长时间任务可设 run_in_background: true，再用宿主提供的 job_output / job_kill 跟踪；前台命令用 timeoutMs 控制上限（默认 120000 ms）。
5、只读沙箱下若 PowerShell 写盘被拒，可按 README 流程携带 sandbox_permissions 与 justification 请求升级；用户拒绝后应停止绕行。gitbash/wsl 不支持该升级参数。
适用场景与注意¶
适合谁：主要在 Windows 上跑 DSH、又希望模型在同一会话里按命令性质切换 Git Bash / pwsh / WSL 的开发者；愿意接受 gitbash 与 wsl 路径不受 DSH ACL 沙箱同等约束、并在输出里看到明确 [sandbox: …] 提示的场景。
务必知晓：
- 插件以当前 DSH 进程权限执行命令；安装前请自行查看 GitHub 源码 与 MIT 许可证。
- 与
dsh-bash-terminal工具名冲突，切换插件前按 README 处理 bundle 与disabled标记。 peerDependencies为*，意在减少宿主小版本升级时的安装门控；仍建议在目标 DSH 版本上按 README「已验证」表做一次冒烟。- 社区插件目录 skillhub.cn 是独立生态站点，不等同于官方应用商店。
结尾¶
dsh-multi-shell 用「一个 shell 工具 + 按次 shell 参数」把 Windows 上常见的三种执行面交给模型调度，并在 PowerShell 侧保留沙箱 confine、UTF-8 前导与可选审批升级；与固定默认终端的方案相比，差在控制权在模型侧、版本依赖更宽。进一步了解可打开 SkillHub 目录页 与 GitHub 仓库。
