前言¶

在 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