前言¶

在 Windows 上做 DSH 智能體開發時，很多任務需要調用 shell：執行腳本、檢查文件、安裝工具、處理日誌。若當前環境只能使用 PowerShell，而命令依賴 bash 語法或 Linux 發行版，執行層會受限。

@zimzaza4/dsh-bash-win 是一個 Cordis 插件，用於在 Windows 上爲 DeepSeek Harness（DSH）提供 git_bash 與 wsl_bash 兩個 bash 工具。它接入本地 Git Bash 與 WSL2，並提供審批、沙箱、後臺任務、前臺超時與 Web 終端卡片。

插件定位¶

插件由 zimzaza4 維護，npm 包名爲 @zimzaza4/dsh-bash-win，倉庫路徑爲 zimzaza4/dsh-bash-win，許可證爲 MIT。

它解決的問題是：在 Windows 的 DSH 環境中調用 bash，並對執行權限、審批、沙箱和任務生命週期提供控制。

核心能力¶

git_bash¶

git_bash 後端爲本地 Git Bash（MSYS2）。

支持：

• 審批模式：require_approval: true
• 沙箱：sandbox: true 會嘗試走 windows-acl 沙箱；受限模式下如實報告 runner 失敗
• 後臺任務：run_in_background: true，配合 job_output / job_kill
• 前臺執行：timeoutMs 超時終止整個進程樹，並支持調用取消

wsl_bash¶

wsl_bash 後端爲 WSL2（Linux）。

支持：

• WSL 內 bwrap 沙箱：sandbox: true
• 升權審批：涉及 sandbox_permissions 與 justification
• 後臺任務：run_in_background: true，配合 job_output / job_kill
• 前臺執行：timeoutMs 超時終止整個進程樹，並支持調用取消
• 沙箱模式要求發行版已安裝 bubblewrap

通用能力¶

兩個工具都支持：

• 自動探測 Git Bash 與 WSL 路徑，並通過插件 config 或環境變量覆蓋
• 輸出收集內存上限 256 KiB，超限截斷並落 spill 文件
• Web 終端卡片：終端圖標、可展開輸出、退出碼狀態

安裝與啓用¶

插件可安裝到 DSH 的 profile。以下使用 dsh web 對應的 web profile。

執行安裝命令：

dsh plugin --profile web add @zimzaza4/dsh-bash-win

安裝後需重啓 dsh web 生效。重啓後，新會話中應出現 git_bash 與 wsl_bash。

執行卸載命令：

dsh plugin --profile web remove @zimzaza4/dsh-bash-win

卸載後同樣需重啓 dsh web。

配置¶

路徑定位優先級爲：插件 config > 環境變量 > 自動探測。

可以在 cordis.patch.yml 中配置 Git Bash、WSL 可執行文件和默認發行版：

# cordis.patch.yml
- insert:
    - id: tool-bashx
      name: '@zimzaza4/dsh-bash-win'
      config:
        bashPath: 'D:\tools\Git\bin\bash.exe'   # 自定義 Git Bash
        wslPath: 'C:\Windows\System32\wsl.exe'  # 自定義 WSL
        wslDistro: 'Debian'                     # 默認發行版

也可以使用環境變量：

DSH_BASHX_BASH_PATH
DSH_BASHX_WSL_PATH
DSH_BASHX_WSL_DISTRO

權限與安全¶

默認執行無沙箱、全權限。git_bash 與 wsl_bash 默認直接跑，可讀寫任意路徑。插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證，並確認進程權限符合預期。

審批只出現在兩處：

1、顯式批准模式：require_approval: true

2、越界後的升權請求：涉及 sandbox_permissions 與 justification

操作路徑本身不觸發審批。沙箱對越界的處理是拒絕，而不是彈窗。

wsl_bash 設置 sandbox: true 時，會在 WSL 內用 bwrap 包裝命令。git_bash 沒有文件沙箱；設置 sandbox: true 時會嘗試 windows-acl 沙箱，受限模式下如實報告 runner 失敗。

升權階梯從 workspace-write 到 danger-full-access，走官方 approveEscalation 流程，必須經用戶批准。

適用場景與注意事項¶

適合以下場景：

• 需要調用 Git Bash / MSYS2 命令
• 需要調用 WSL2 / Linux 命令
• 需要爲 bash 工具增加審批、沙箱、後臺任務與終端卡片

運行依賴：

• 按需準備 Git for Windows
• 按需準備 WSL 與發行版
• 使用 wsl_bash 沙箱時，發行版內需安裝 bubblewrap
• peer 依賴 @deepseek-ai/dsh-tools 與 @deepseek-ai/dsh-sandbox，由宿主提供

注意事項：

• 改代碼後必須重啓 DSH；HMR 熱加載在此部署中不可靠
• 通過 UI 卸載插件會刪除 profile 的 cordis.patch.yml；重新安裝時重建該文件即可

小結¶

@zimzaza4/dsh-bash-win 將 Git Bash 與 WSL2 作爲 DSH 的 bash 工具接入，提供 git_bash、wsl_bash、審批、沙箱、後臺任務與 Web 終端卡片。使用時需要重點關注默認全權限、沙箱依賴與 WSL 發行版要求。

倉庫地址：

https://github.com/zimzaza4/dsh-bash-win