Shell 切换器 codel6i/dsh-shell-switch

dsh-shell-switch

给 dsh Windows 桌面端加一个 shell 切换面板：在「设置 → Shell」里选择智能体执行命令时用 PowerShell 还是 Git Bash。切换即时生效，不需要重启。

English: README.en.md

它到底切换了什么

dsh 在 Windows 上默认只给模型一个 pwsh 工具（@deepseek-ai/dsh-tool-pwsh + pwsh-sandbox 执行器），
Git Bash 没有任何入口。本插件补上这一档，并且让同一时刻只有一个 shell 工具对模型可见：

| 当前 shell | 模型看到的工具 | 模型收到的提示词 | 另一个工具 |
| pwsh（默认） | pwsh | “The active command shell is PowerShell…” | bash 从工具列表中移除，调用被拒绝 |
| gitbash | bash（Git Bash 5.x / MINGW64） | “The active command shell is Git Bash… Git Bash is D:\...\Git\bin\bash.exe” | pwsh 从工具列表中移除，调用被拒绝 |

真机实测（把开关切到 Git Bash 后，模型用 bash 工具执行）：

shell=5.2.37(1)-release
bash-path=/usr/bin/bash
MINGW64_NT-10.0-26200
cwd=/d/deepseek/deepseek-cli
env-style=/c/Users/lss

后台任务同样可用（隔离 realm 里的 bash 工具照样能拿到 jobs 注册表）：

// bash { run_in_background: true } → started background job bash-6
// job_output bash-6 →
"bg-start 10:55:47\ntick-1\ntick-2\ntick-3\nbg-done 10:55:50\nshell=5.2.37(1)-release" // exit 0

安装

插件已经按 dsh bundle 规范打包（package.json 的 dsh.bundle.patch 指向 cordis.patch.yml）。

方式 A：本地包（离线可用，推荐）

在插件目录构建出 lib/ 后打包
cd <插件目录>; npm install; npm run build; npm pack
安装进指定配置档
dsh plugin --profile desktop add file:<插件目录>\dsh-shell-switch-0.1.7.tgz

在本会话中也可以直接用内置的 plugin_manager 工具：install_bundle + file:...tgz。

方式 B：从 git 仓库安装

dsh plugin --profile desktop add github:codel6i/dsh-shell-switch

仓库里的 package.json 带 prepare: npm run build，所以从 git 安装时会自动构建出 lib/ （lib/ 本身不入库）。

pnpm 11 的前置条件：git 依赖要跑 prepare 必须先进白名单，否则安装会以
ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED 失败（错误信息里会给出确切的键）。把配置档的 pnpm-workspace.yaml 改成：

allowBuilds:
dsh-shell-switch@git+https://github.com/codel6i/dsh-shell-switch.git: true

顺带说明：dsh 界面里的"批准构建"只认 pnpm 写下的占位值 set this to true or false，而 git 依赖的 prepare 是硬失败、不会产生占位，所以这条路要先手工写白名单；安装 dshmarket 之后也可以用它界面里的批准入口。

方式 C：手动挂载

1. 把插件目录（含 lib/）复制到 <DSH_HOME>\profiles\<profile>\node_modules\dsh-shell-switch\；
2. 在配置档的 package.json 里把 "dsh-shell-switch" 加进 dsh.profile.bundles；
3. 重启 dsh（或触发一次配置重载）。

插件本身是一个 bundle：cordis.patch.yml 里插入了 3 行（见下文），不需要改动 dsh 源码。

使用

面板有两个入口，内容相同：

- 设置 → Shell：左下角账户/设置入口打开设置面板，左侧导航里的 Shell；
- 插件 → dsh-shell-switch → 点开 dsh-shell-switch 这一行：该行的配置页就是同一个面板（即 dsh 的 plugins.row.config 槽，key 为 dsh-shell-switch#shell-switch）。

面板内容：

1. 当前 shell 二选一：PowerShell / Git Bash；
2. （可选）Git Bash 可执行文件：留空即自动探测；探测失败时在这里填 bash.exe 绝对路径；
3. （可选）隐藏未启用的 shell 工具：默认开；关掉则两个工具都留在列表里，未启用的那个仍会拒绝调用。

面板下半部分随选择变化：选中哪一项，就换成那一项的说明卡片——执行器（含解析到的路径与来源）、路径风格、环境变量、模型当前拿到的工具，以及另一个工具的下场（已隐藏 / 仍列出但会被拒绝）；再下面是只影响 Git Bash 的路径设置与隐藏开关，最后一行是宿主实时状态。

面板下方那行是宿主实时状态（面板从 GET /shell-switch/status 读取，经 dsh 的连接鉴权），例如 已找到 Git Bash：D:\Application\DevTool\Git\bin\bash.exe（来自 git --exec-path）· 模型当前拿到的 shell 工具：pwsh。
它直接回答「到底认没认出来」：路径、来源，以及此刻模型手上的 shell 工具；读不到时明确写「读不到宿主状态」，不猜。

插件页里那行 cordis:group（id 是 shell-switch-bash）是容器行，它自身没有插件实现，所以点它的启用开关会报「找不到该插件」——这是正常的，不影响功能；真正在运行的是它下面两行：@deepseek-ai/dsh-bash-sandbox（执行器）和 @deepseek-ai/dsh-tool-bash（bash 工具）。
需要隔离 realm 才能让第二个 shell 服务与 dsh 自带的 pwsh-sandbox 共存，所以这一层容器去不掉。

写入落在配置档的 cordis.patch.yml：

- id: shell-switch
name: dsh-shell-switch
config:
activeShell: gitbash # pwsh | gitbash
gitBashPath: '' # 留空 = 自动探测 hideInactiveTool: true

怎么确认切换生效

- 让模型跑一条命令：pwsh 档会走 PowerShell，gitbash 档会走 Git Bash（uname -s 返回 MINGW64_NT-...）；
- 切换后模型手里的工具名会立刻换挡，系统提示词里也会写明当前 shell 与 Git Bash 的真实路径。

工作原理

cordis.patch.yml 插入 3 行：

| 行 id | 作用 |
| shell-switch | 本插件（宿主半 + 客户端半），activeShell 就是开关 |
| shell-switch-bash | 一个 cordis:group，用 isolate: { shell: true } 把 shell 服务隔离在组内 |
| ├ shell-switch-bash-exec | @deepseek-ai/dsh-bash-sandbox：Git Bash 的执行器（保留沙箱语义） |
| └ shell-switch-bash-tool | @deepseek-ai/dsh-tool-bash：官方 bash 工具，run_in_background 等能力原样保留 |

为什么必须隔离：一个 Cordis 上下文只允许一个 shell 服务实现。Windows 上部署自带的执行器是 pwsh-sandbox，它必须继续服务其他消费者，所以 Git Bash 执行器只能活在自己的 realm 里。

宿主半（src/index.ts）在开关之上做五件事：

1. 探测 Git Bash：gitBashPath → git --exec-path → where git 推导安装根 → PATH 中的 Git 目录 → 常见安装位置；顺手排除 C:\Windows\System32\bash.exe（那是 WSL 存根，不是 Git Bash）。
2. 让 bash 能被解析：把 Git 安装的 bin 目录插到进程 PATH 最前面；插件卸载时精确移除该项（不动其他项）。
3. 控制模型可见的工具：监听 system-prompt/assemble 瀑布，把当前不该出现的那一个 shell 工具从 assembly.tools 里剔除。
4. 兜底拒绝 + 说明当前 shell：tools.guard 拒绝调用未启用的 shell（覆盖「工具列表还是上一步缓存」的窗口），并用一个动态提示词段告诉模型当前 shell、方言和 Git Bash 的真实路径。
5. 把实时事实交给面板：GET /shell-switch/status 返回当前 shell、探测到的 bash.exe 与来源、可见/隐藏的工具。
路由只在有 web server 的部署里注册，且只回答通过 connection.requestRejection 的调用方（未鉴权 401）。

客户端半（src/client/）把同一个面板注册到两处：settings.section（设置 → Shell）与 plugins.row.config（本 bundle 的 shell-switch 行配置页，key dsh-shell-switch#shell-switch）。
读写走 dsh 官方的 configForms / settings Remote，不新增任何自定义 Remote；状态行走上面那条宿主路由。

为什么配置字段必须 volatile：dsh 的设置服务只服务含 volatile 字段的 Config
（settings.describe() 里 volatileForm(schema) 会丢弃其余字段，一个不剩就整行跳过）。
字段不是 volatile 时，这一行没有设置命名空间：面板绑不上、控件被锁、写入也会被拒。
同时 volatile 意味着配置改动就地更新，不必重挂载插件行。src/config.ts 里三个字段都标了 volatile，且宿主半在读哨兵、提示词、工具过滤、状态接口时都重新读取当前值。

配置项

| 字段 | 类型 | 默认 | 说明 |
| activeShell | pwsh \| gitbash | pwsh | 当前 shell，面板写入的就是它 |
| gitBashPath | string | '' | bash.exe 绝对路径；留空自动探测 |
| hideInactiveTool | boolean | true | 是否把未启用的 shell 工具从模型工具列表中隐藏 |

边界与已知取舍

- 仅 Windows 生效：其他平台上 dsh 本来就只有一个 shell，插件不注册任何东西（只写一行日志）。
- 探测不到 Git Bash 时自动降级：不会隐藏 pwsh、不会拒绝它，提示词也改回 PowerShell——宁可维持「能跑命令」，也不让模型手里没有可用 shell。日志里会写明原因（未安装 / 配置路径不存在）。
- 只切换智能体的执行 shell，不改 dsh 内置终端（terminal_open / 右侧终端）的 shell。
- PATH 副作用：启用 Git Bash 时会把 <Git>\bin 放在 PATH 首位（只加这一项，usr\bin 不加），于是进程内 bash/git 等解析到 Git for Windows；插件停用时移除。
- 工具列表会随开关变化：这是刻意的（hideInactiveTool: false 可以关掉），代价是切换后请求头里的 tool 列表会变一次。
- 受限权限模式下的 Git Bash 侧未在本机实测：本机是 danger-full-access，bash-sandbox 直接放行； workspace-write / read-only 下会走 dsh 自带的沙箱 runner 包裹 bash。若某个部署在这种模式下报 runner 失败，把 cordis.patch.yml 里 shell-switch-bash-exec 的 name 换成 @deepseek-ai/dsh-bash-local 即可（放弃 bash 侧的沙箱约束，其余行为不变）。
- 客户端半热更新，宿主半要重启：面板（浏览器半）由 dsh 的客户端 HMR 自动热更新，装完即生效；但宿主半的 schema 改动必须重启 dsh 进程（例如新增配置字段、把字段改成 volatile、新增 HTTP 路由）。
判断办法：Config.listConfigs({ entry: 'include:shell-switch' }) 的投影里出现 x-cordis.volatile: true
才算新模块已加载。

开发

npm install
npm run typecheck # tsc --noEmit（宿主 + 客户端）
npm test # 构建 lib/ 后跑全部单测
npm run check # 上面两步

src/ids.ts 两侧共用的 entry id 与工具名 src/config.ts 配置 schema 与显式 resolve src/detect.ts Git Bash 探测（环境/文件系统/git 探针全部可注入，便于测试） src/path.ts PATH 前缀插入与精确回滚 src/prompt.ts 模型可见的当前 shell 说明 src/index.ts 宿主半：探测 + PATH + 工具可见性 + 守卫 + 提示词段 src/client/ 客户端半：设置页（controller + 组件 + 中英词条） scripts/build.mjs esbuild：宿主 ESM + 客户端 __ModuleLoader__ bundle tests/ 单测：探测与 PATH、隐藏/拒绝、设置热更新、客户端注册与渲染、产物形状

构建产物：lib/index.js（宿主，@deepseek-ai/* 全部 external）与 lib/client.js
（window.__ModuleLoader__.load({ id, factory }) 包装，外部依赖只有平台模块表里的
react / react/jsx-runtime / @deepseek-ai/dsh-client-store / @deepseek-ai/dsh-client-ui-primitives）。

License

MIT