前言¶
DeepSeek Harness（DSH）在 Windows 上默认会组合 PowerShell 沙箱与 pwsh 工具：主机侧走 @deepseek-ai/dsh-pwsh-sandbox，智能体预设里挂载 @deepseek-ai/dsh-tool-pwsh。若只依赖上游的 dsh-bash-local，它会通过 PATH 解析裸 bash，在 Windows 上往往落到 C:\Windows\system32\bash.exe——那是 WSL 启动器，不是 Git Bash；文件系统视图与 C:\ 风格路径与常见 Windows 工作区不一致，无法当作 Windows 上的 drop-in shell。
若你希望在 Windows 上让模型使用熟悉的 Unix 风格命令（grep、sed、管道等），同时又保留 DSH 自带的 pwsh 工具不变，就需要显式解析 Git Bash 并单独挂载 bash 工具。dsh-win-bash 由社区维护者 MYiYang 提供，分类为客户端插件，在 pwsh 栈旁通过隔离的服务域补上这一块。
这是什么¶
dsh-win-bash 是面向 Windows 的 DSH 插件：提供基于 Git Bash 的 ctx.shell 执行器，以及模型侧可用的 bash 工具，与主机原有的 pwsh ctx.shell 并列组合，不替换、不复制 pwsh 栈。加载行通过 isolate: { shell: 'win-bash' } 把执行器与工具放进私有服务域，预设里的 pwsh 工具仍走主机侧实现。
源码与说明见 GitHub 仓库，社区目录页：SkillHub - dsh-win-bash。当前 npm 包版本为 0.3.0（MIT 许可证）。DSH 生态强调「一切皆插件」；SkillHub 等目录为独立社区站点，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
ctx.shell 与 bash 工具¶
插件会 spawn 显式解析到的 Git Bash 可执行文件，形式为 <git>\bin\bash.exe -c <command>，并继承上游常见机制：受管进程组、超时/中止分类、有界输出与 spill 文件、面向模型的环境变量（NO_COLOR、TERM=dumb、PAGER=cat）、后台任务，以及文件沙箱路径（在沙箱可用时）。
模型侧 bash 工具 接到该执行器上，与 pwsh 工具可同时存在。
与 pwsh 栈并列¶
主机在 Windows 上仍组合 pwsh 沙箱与 pwsh 工具；本插件只增加 win-bash 隔离域内的执行器与 bash 工具，不改动主机 ctx.shell（pwsh）。
Git Bash 发现顺序¶
当配置未指定绝对路径时，按 README 文档顺序探测：
- 行配置中的
bashPath； - 环境变量
DSH_GIT_BASH_PATH； - 注册表
GitForWindows的InstallPath（含 WOW6432Node）； - 常见安装根目录（如
%ProgramFiles%\Git、Chocolatey、scoop、MSYS2 等）； PATH中的候选（文档说明会跳过易误判为 WSL 的条目）。
可在行配置里用 bashPath 写死路径，避免自动探测歧义。
安装与启用¶
在 desktop 配置档下添加插件依赖（命令来自官方 README）：
dsh plugin --profile desktop add dsh-win-bash
若使用本地检出目录，可改为 link 形式：
dsh plugin --profile desktop add link:/path/to/dsh-win-bash
上述任一方式会写入 profile 依赖，并把 dsh-win-bash 追加到 dsh.profile.bundles；插件自带的 cordis.patch.yml 提供加载行。主机在下次启动时加载新 bundle；若应用已在运行，profile 协调会热加载该行。其他 profile 需将 --profile desktop 换成对应名称重复执行。
运行环境要求 Node >= 22.16.0（见 package.json 的 engines）。
配置项¶
所有开关在 win-bash 加载行上；也可在 profile 的 cordis.patch.yml 里用 - id: win-bash / config: {...} 覆盖（patch 会替换整段 config）。
| Key | 默认值 | 含义 |
|---|---|---|
bashPath |
'' |
bash.exe 绝对路径；空则自动探测 |
promptHint |
true |
是否在系统提示中增加一行，倾向使用 bash 而非 pwsh |
sandboxFallback |
auto |
已证实的「受限 spawn 初始化失败」在本机上的处理方式（见下节） |
timeoutMs |
120000 |
默认前台超时 |
maxTimeoutMs |
600000 |
单次调用超时上限 |
maxOutputBytes |
64000 |
单流内存输出上限，超出写入 spill |
maxSpillBytes |
67108864 |
单流 spill 总上限 |
graceMs |
3000 |
结束进程与管道 drain 的宽限 |
cwd |
(未设置) | 默认工作目录；单次调用仍以会话 workspace 为准 |
Windows 沙箱与 sandboxFallback¶
在 Windows 上，上游 ACL 沙箱（@deepseek-ai/dsh-sandbox-windows-acl）在 WRITE_RESTRICTED 令牌下 spawn 子进程时，Git Bash 目前无法正常初始化。文档记录两类典型失败（如 STATUS_DLL_INIT_FAILED / 退出码 0xC0000142，工具侧可能显示 (no output) [exit code: 3221225794]）：无控制台 GUI 主机下的控制台子进程问题，以及 msys 运行时无法在受限令牌下创建 \BaseNamedObjects\msys-* 等。同一命令在 danger-full-access 下可工作，因为不进入沙箱路径。因此在 Windows 上，sandboxFallback 往往不是临时权宜，而是让 bash 工具在文件沙箱会话中可用 的关键配置。
| 值 | 行为 |
|---|---|
fail |
给出明确错误与修复建议，从不非沙箱执行 |
unconfined |
从不调用沙箱；命令直接在 Git Bash 中运行，标记 enforcement: 'none'（适合无审批的 CI/无头环境） |
auto（默认） |
行激活时只读探测；若证实 0xC0000142 签名，受限调用会先返回沙箱 denial，模型需按提示用 sandbox_permissions 与简短理由重试一次，经 harness 审批通道；仅 allowed-once 时在更宽模式下非沙箱执行 |
auto 不会在沙箱仍可用时绕过沙箱；仅在出现已证实的死亡签名后才走 denial/审批流程。文档也说明：从控制台启动 DSH 不能 规避 msys 在受限令牌下的问题，因此在 Windows 上 auto 仍可能合法地触发 denial。
典型用法¶
安装并重启（或热加载）后，智能体预设中除 pwsh 工具 外会出现 bash 工具，命令经 Git Bash 执行。若 promptHint 为 true，系统提示会提示在适合 Unix 风格命令时优先 bash。
在 sandboxFallback: auto 且沙箱无法初始化 Git Bash 时，首次受限 bash 调用可能返回带 denial 标记的结果；按工具提示用 sandbox_permissions 重试并说明理由，等待用户审批后再执行——这是 README 描述的设计路径，而非插件 bug。
本地开发或调试解析逻辑时，包导出 ./resolve-bash 等模块，可供其他代码引用 Git Bash 路径解析（见 package.json 的 exports）。
适用场景与注意¶
适合： 在 Windows 上使用 DSH desktop（或其他 profile）且需要 Git Bash 语义、又不想拆掉默认 pwsh 栈的开发者；工作流里大量 shell 片段更适合 bash -c 而非 PowerShell 的场景。
注意：
- 插件以当前 DSH 进程权限运行；安装前请阅读 源码与 LICENSE，确认组织策略允许。
- 勿假设
PATH里的bash就是 Git Bash；本插件的价值正在于显式解析 Git Bash。 - Windows 受限沙箱与 Git Bash 的兼容性限制来自上游 runner 与 msys 行为；
sandboxFallback的三种模式需按安全要求选型，unconfined表示操作者持续同意非沙箱执行。 - 无 Git for Windows 或未正确配置
bashPath/DSH_GIT_BASH_PATH时，自动探测可能失败，需在行配置中指定路径。
结尾¶
dsh-win-bash 在 Windows 上为 DSH 补上「真正的 Git Bash」执行栈与 bash 工具，与 pwsh 并列，并文档化沙箱 fallback 与 Git Bash 发现顺序。若你在 Windows 上跑 Harness 智能体，又需要 bash 工具链，可按 README 安装到对应 profile，并根据环境调整 bashPath 与 sandboxFallback。
