前言¶
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 進程。
