前言¶
DeepSeek Harness (DSH) 采用插件化架构。在 Windows 平台上，默认配置仅提供 PowerShell (pwsh) 作为命令执行 Shell，Git Bash 没有任何入口。本插件通过添加一个切换面板，允许在同一时刻只有一个 shell 工具对模型可见，解决模型在 Windows 环境下无法使用 Git Bash 执行命令的问题。
核心能力¶
- Shell 切换：在 PowerShell 和 Git Bash 之间切换 dsh agent 的命令执行 shell。
- 单一可见性：同一时刻只有一个 shell 工具对模型可见，避免工具冲突。
- 后台任务：支持后台任务执行，隔离 realm 里的工具能正常拿到
jobs注册表。 - 自动探测：支持自动探测 Git Bash 路径，未探测到时允许手动配置。
- 工具隐藏：支持隐藏未启用的 shell 工具，保持工具列表整洁。
- 平台限制：仅 Windows 平台生效。
安装¶
插件已按 dsh bundle 规范打包。可通过以下方式安装：
dsh plugin --profile desktop add github:codel6i/dsh-shell-switch
若需本地构建安装：
cd <插件目录>
npm install
npm run build
npm pack
dsh plugin --profile desktop add file:<插件目录>\dsh-shell-switch-0.1.7.tgz
注：从 git 仓库安装时，若遇到 pnpm 11 的 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED 错误，需在 profile 的 pnpm-workspace.yaml 中将对应 git 依赖设为 allowBuilds: true。
使用¶
安装后，面板有两个入口：
1. 设置 → Shell：在左下角账户/设置入口打开设置面板，左侧导航选择 Shell。
2. 插件 → dsh-shell-switch：在插件列表中找到该行，点击进入配置页。
面板操作：
1. 当前 shell：在 PowerShell 和 Git Bash 之间二选一。
2. Git Bash 路径：留空自动探测；探测失败时手动填入绝对路径。
3. 隐藏未启用工具：默认开启，关闭则两个工具均保留在列表中。
切换后，模型工具列表会随之变化。若模型执行命令，PowerShell 档会走 PowerShell，Git Bash 档会走 Git Bash（uname -s 返回 MINGW64_NT-...）。
后台任务示例：
// bash { run_in_background: true }
// 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"
工作原理¶
插件通过 cordis.patch.yml 向宿主注入配置：
1. 隔离 Realm：创建一个隔离的 realm（shell-switch-bash），其中包含 @deepseek-ai/dsh-bash-sandbox 执行器和 @deepseek-ai/dsh-tool-bash 工具，避免与默认的 pwsh-sandbox 冲突。
2. PATH 注入：启用 Git Bash 时，将 Git 安装的 bin 目录插入进程 PATH 最前面；插件卸载时移除。
3. 工具可见性控制：监听提示词组装流程，将未启用的 shell 工具从模型可见列表中剔除。
4. 提示词注入：在提示词中动态注入当前 shell 状态及 Git Bash 路径，引导模型正确使用工具。
5. 状态上报：通过 GET /shell-switch/status 接口向面板汇报探测状态、路径及当前工具可见性。
配置与注意事项¶
配置项：
* activeShell：当前 shell，默认 pwsh。
* gitBashPath：Git Bash 绝对路径，留空自动探测。
* hideInactiveTool：是否隐藏未启用的 shell 工具，默认 true。
注意事项：
* 仅 Windows 生效：其他平台不注册任何功能。
* 自动降级：探测不到 Git Bash 时，不隐藏 pwsh，保证模型有可用 Shell。
* 内置终端不受影响：仅切换 Agent 执行 shell，不改 dsh 内置终端。
* 权限限制：受限权限模式下 Git Bash 行为未实测。
* 热更新：面板由客户端 HMR 自动热更新，但宿主半的 schema 改动需重启 dsh 进程。
