Git Bash 终端桥 riverzhou/dsh-gitbash-new

dsh-gitbash

一个面向 DeepSeek Harness（DSH） 的 Windows 终端桥：把模型侧的 pwsh 工具换成真正的 bash，并同时支持、可选 Git for Windows 与 MSYS2，保留官方终端工具的全部行为（cwd、后台任务、超时转后台、提权、终端卡片、PTC、meta.cwd）。

本文是完整使用手册：安装、日常用法、安全边界、设置、排障与开发。

最低 DSH：0.2.1。 仅 Windows 10/11。替换只对新会话生效；已存在的会话保持创建时的工具目录。

目录

- 功能
- 环境要求
- 安装
- 快速开始
- 安全边界（先读）
- 使用 bash 工具
- Shell profile（Git / MSYS2）
- 设置页
- 常用操作
- 排障
- 诊断
- 兼容与升级
- 开发
- 限制与非目标
- License

功能

- 模型目录里只有 bash、没有 pwsh：tools.restrict 隐藏 pwsh，压掉 tool:pwsh 提示词，并注册本插件的 bash。只对新会话生效，旧会话不追溯。
- 两套 shell、一个选择器：Git for Windows（默认优先）与 MSYS2（UCRT64 / MINGW64 / CLANG64 / CLANGARM64 / MINGW32 / MSYS）。发现流程会查注册表、where.exe、PATH 与常见安装根目录，用 bash --version 校验候选，且不会把 WSL 的 bash.exe 当成候选。
- 与官方 terminal tool 同形的契约：description / command / timeoutMs / workdir / run_in_background / sandbox_permissions / justification，同时接受 POSIX 与 Windows 形式的 workdir，结果标记（[exit code: N] / [stderr] / 截断 spill）与终端卡片用的 meta.cwd 都保持一致。
- 后台任务：run_in_background 返回 job id，用 job_output 收集、 job_kill 停止；前台超时会转后台（promote），而不是被杀掉。
- 隔离而非拼凑：过滤另一套 bash 家族带来的 PATH 条目，MSYSTEM 始终与所选 profile 一致；Git 的 bin\bash.exe launcher 会归一化为 usr\bin\bash.exe，确保实际运行的就是你组合出来的环境。
- Windows 专有的正确性：signalNumber << 8 的退出编码会归一化为 [killed by signal: SIGTERM]；继承来的 Windows PWD / OLDPWD 用 tombstone 删除，pwd 保持 POSIX。
- DSH 原生显示：终端卡片、标题栏 1 个后台任务 / 1 个子智能体、 job 卡片和子智能体卡片都由 DSH 渲染。插件只注册 bash 工具并给出 meta.cwd，不自绘聊天 UI。
- 紧凑设置页：自动发现、即时 profile 选择、兼容模式、一行安全提示，路径/测试/环境/诊断折叠在“高级与诊断”。
- 显式安全：绝不静默放宽权限——workspace-write 下以完全访问运行并在结果里标注 [compat: ...]，read-only 拒绝，strict 只允许 danger-full-access。
详见安全边界。
- 已验证：75 个单元/集成用例，加上 Git 与 MSYS2 的真机冒烟（直连、后台、子智能体；设置页浅色与深色）。

环境要求

| 项 | 要求 |
| DSH | >= 0.2.1（已在桌面运行时 0.2.1-rc.2 实测） |
| Windows | Windows 10/11 x64；MSYS2 arm64 环境也可用 |
| bash 提供方 | Git for Windows 和/或 MSYS2 |
| Node.js | ^22.19.0 或 >=24，仅构建/开发需要 |
| 可选 | Cygwin，best-effort，不推荐 |

- Git Bash 与 MSYS2 共用 MSYS2 运行时；该运行时无法在 DSH 的 Windows ACL 沙箱中启动。这是 OS 层约束，不是插件 bug（证据见 docs/DESIGN.md §2）。
- WSL 的 bash.exe 被有意排除：WSL 不是 Git Bash，也不符合本插件的 profile/环境模型。

安装

使用 DSH Desktop 自带的 CLI

不要用 npm 全局的旧 dsh（例如 0.1.7），它不认识 0.2.1 的 plugin/profile 契约。使用桌面安装目录里的 CLI：

set "DSH_CLI=%LOCALAPPDATA%\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd"
%DSH_CLI% --version
:: 应为 0.2.1-rc.2 或更高

修改 profile 前先完全退出 DSH Desktop。

从本地目录安装（开发）

%DSH_CLI% plugin --profile desktop add link:D:/GitHub/dsh-gitbash-new

重新打开 DSH，浏览器硬刷新（Ctrl+Shift+R）。

从 GitHub 安装（发布后）

%DSH_CLI% plugin --profile desktop add github:riverzhou/dsh-gitbash-new

从 npm 安装（已发布）

%DSH_CLI% plugin --profile desktop add @riverzh/dsh-gitbash@0.2.2

最新版可用 @riverzh/dsh-gitbash@latest。

升级

%DSH_CLI% plugin --profile desktop remove @riverzh/dsh-gitbash
%DSH_CLI% plugin --profile desktop add link:D:/GitHub/dsh-gitbash-new

发布版把 link:... 换成 @riverzh/dsh-gitbash@<version>。升级后重启 DSH 并硬刷新。

卸载

%DSH_CLI% plugin --profile desktop remove @riverzh/dsh-gitbash

重启 DSH。设置项随插件消失；profile 的 cordis.patch.yml 里残留的 dsh-gitbash 配置不会再生效，可手动删除。

不要同时装两个“用 bash 换掉 pwsh”的插件

dsh-tweaks 的 git-bash-terminal-tool 也会隐藏 pwsh 并注册 bash。
如果它已经装了，先移除或禁用：

%DSH_CLI% plugin --profile desktop remove dsh-tweaks-git-bash-terminal-tool

两者同时存在时，先加载的一方完成替换；后加载的一方通常因 pwsh 已不可限制而跳过，日志里会出现 skipped ... pwsh is not restrictable。

快速开始

1. 安装并重启 DSH。
2. 打开 设置 → 通用 → 终端工具（Git Bash / MSYS2）。
3. Shell 保持 自动（推荐），或选一个具体的 Git/MSYS2 profile。
4. 兼容 保持 兼容模式（推荐）；需要更严格时选严格模式。
5. 新建一个会话，让模型执行： “用 bash 打印 shell、cwd 和 git status。”
6. 确认模型调用的是 bash（不是 pwsh），结果的 cwd 正确。

设置页长这样：

设置页：终端工具

Shell、兼容模式和 MSYS2 环境下拉都跟随 DSH 的浅色/深色 surface token，闭控件和展开列表都保持可读：

深色主题下的 Shell 下拉浅色主题下的 Shell 下拉

安全边界（先读）

MSYS2 运行时无法在 DSH 的 Windows ACL 沙箱里启动：受限令牌会让它的命名共享内存、signal 管道和 BaseNamedObjects 创建失败；把当前用户 SID 加进 restricting 列表会击穿写隔离；降到 Low 完整性又会再次卡在 BaseNamedObjects。不存在 “既能跑 Git Bash、又被这个沙箱约束”的配置。

因此插件把代价显式化：

| 会话权限 | compat: auto（默认） | compat: strict |
| danger-full-access | bash 正常执行 | bash 正常执行 |
| workspace-write | bash 以完全访问执行，结果带 [compat: ...] | 拒绝 |
| read-only | 拒绝 | 拒绝 |

- 文件工具仍由 DSH 沙箱保护；只有 bash 进程不受该沙箱约束。
- workspace-write + auto 下，bash 可以写工作区外的文件。除非用户明确要求，应把工作区外路径当作只读。
- 插件不会静默放宽权限：设置页红字、工具描述、system prompt、结果文本四处都写明。
- read-only 宁可拒绝，也不破坏“只读”承诺。
- strict 给安全敏感用户：只在 danger-full-access 下允许 bash。
- 被策略阻止的调用可以用 sandbox_permissions + 一句 justification 重试； DSH 会询问用户，批准只对本次调用生效。

使用 bash 工具

参数

| 参数 | 类型 | 必填 | 说明 |
| description | string | 是 | 5–10 个词的清晰描述，显示在 UI |
| command | string | 是 | 以 bash -c '<command>' 执行；使用 POSIX 语法 |
| timeoutMs | number | 否 | 正数；默认 120000，上限 600000 |
| workdir | string | 否 | 工作目录；相对路径基于会话 cwd |
| run_in_background | boolean | 否 | 立即返回 job id；不设超时 |
| sandbox_permissions | workspace-write \| danger-full-access | 否 | 被策略阻止时申请更宽模式 |
| justification | string | 提权时必填 | 一句话说明为什么本次需要更宽权限 |

run_in_background / sandbox_permissions 是特性探测的：标准 Web preset 组合了 job 服务与 sandboxing executor，因此都可用；极简组合可能只有基础参数。

每次调用都是新的 shell（bash -c），不是持久 PTY。需要换目录请用 workdir，不要在命令里依赖 cd 的跨调用状态。

结果格式

- stdout 原样返回；stderr 追加在 [stderr] 段头下。
- 无输出时为 (no output)。
- 非零退出码在最后一行加 [exit code: N]；信号加 [killed by signal: X]。成功的前台结果通常没有退出标记，终端卡片会显示退出码 pill。
- 超时被杀：[timed out after Nms]。
- 超时转后台： [still running after Nms; moved to background job <id>]。
- 输出过大时截断尾部（默认每路 64,000 字节），并给出 [output truncated; full output: <file>]；完整输出在 spill 文件里（最多 64 MiB）。
- 兼容提示： [compat: bash runs outside the DSH file sandbox (session mode workspace-write)]。
这是部署提示，不是命令 stderr。
- 后台启动只返回 started background job <id>，没有 stdout；之后用 job_output 读取。

tool/result.meta.cwd 是实际使用的 Windows 绝对路径。bash 里的 pwd 是 MSYS 的 POSIX 形式（如 /d/project）。

工作目录与路径

- 不传 workdir：使用 DSH 当前会话工作目录。
- 相对 workdir：基于会话 cwd 解析。
- 接受 Windows 绝对路径（C:\...）和 POSIX 盘符路径（/c/...、/d/...）； /tmp 映射到 Windows 临时目录。
- 其它 POSIX 绝对路径（如 /home/...）会明确报错，不猜测映射。
- 命令内优先用 POSIX 路径；用 $VAR / ${VAR:?}，不要用 PowerShell 语法。

后台任务

- run_in_background: true 返回 job id，本轮对话继续。
- 用 job_output（wait: true 可阻塞等待）读取，用 job_kill 停止。
它们是 DSH 内置 job 工具；本插件注册的 job kind 是 bash。
- Web UI 在会话标题栏显示后台任务徽章，在工作步骤里显示 job 卡片。
- 后台任务没有超时，需要显式停止。

超时与转后台

- 普通前台调用受 timeoutMs 约束（默认 120 秒，上限 10 分钟）。
- job 服务可用时，前台超时会转成后台 job，而不是杀掉；结果会给出 job id。
- job 服务不可用时，到点杀掉并报告超时。

权限提权

如果会话策略阻止命令，用最窄的更宽模式 + 理由重试：

sandbox_permissions: "workspace-write" // 或 "danger-full-access" justification: "需要写 <路径> 下的构建缓存，因为 ..."

DSH 会请求用户批准；批准只对本次调用生效。strict 下 workspace-write 会被拒绝，提权目标必须是 danger-full-access。

子智能体、PTC 与 UI

- DSH 子智能体继承父会话的工具层。父会话完成替换后，新子会话有 bash、没有 pwsh；Git 与 MSYS2 都已在真机验证。
- 子代理在自己的会话里执行 bash；父会话收到子智能体卡片/通知，标题栏显示 1 个子智能体。点“查看子智能体”可进入子会话。
- PTC（run_code）看到同一个 bash 工具；插件提供 presenter 与 presentationMeta.cwd。Web UI 从工具名、参数、结果标记和 meta.cwd 反推终端卡片。

Shell profile（Git / MSYS2）

一个 profile 不只是 bash.exe 路径，还包含 flavor、安装根、MSYS2 环境和 PATH 规则。

| Flavor | 选择器文案 | MSYSTEM | bash 路径 |
| Git for Windows | Git for Windows | 固定 MINGW64 | <root>\usr\bin\bash.exe |
| MSYS2 | MSYS2 UCRT64、MSYS2 MINGW64 … | 所选环境 | <root>\usr\bin\bash.exe |
| Cygwin | Cygwin（experimental） | 不设置 | <root>\bin\bash.exe |

- 自动优先 Git for Windows；没有 Git 时选已安装的最佳 MSYS2 环境（UCRT64 优先，然后 MINGW64、CLANG64、MSYS）。
- Git for Windows 只有一个 profile；MSYS2 每个已安装环境一个 profile。所有 MSYS2 环境共用同一个 usr\bin\bash.exe，所以只存 bashPath 不够，必须同时存 msystem。
- MSYS2 环境必须真实存在（<root>\ucrt64\bin 等）；缺失时该 profile 无效，不会静默回退。

Git 的 bin\bash.exe 会被归一化

Git for Windows 有两个入口：

- bin\bash.exe 是 launcher，会按安装自带的运行时重置 MSYSTEM/PATH （Git 2.56 是 UCRT64），覆盖我们设置的环境。
- usr\bin\bash.exe 才是运行时，会遵守我们组合的环境。

如果手填 <root>\bin\bash.exe，插件会把 profile 归一化为 <root>\usr\bin\bash.exe，生效路径会显示在设置页。这是真机抓到的 bug：归一化前 Git profile 报 MSYSTEM=UCRT64，归一化后为 MINGW64。

环境隔离

| Profile | MSYSTEM | PATH 前缀（继承 PATH 之前） |
| Git | MINGW64 | <root>\bin、<root>\usr\bin，以及存在的 <root>\ucrt64\bin / mingw64\bin / mingw32\bin |
| MSYS2 | 所选环境 | <environmentRoot>\bin、<root>\usr\bin、<root>\usr\local\bin |
| Cygwin | 不设置 | <root>\bin |

- 公共覆盖：NO_COLOR=1、TERM=dumb、PAGER=cat、GIT_PAGER=cat、 CHERE_INVOKING=1。
- MSYS2 额外设置 MSYS2_PATH_TYPE=inherit。
- 另一套系统的根会被过滤：Git 会话不继承 C:\msys64\usr\bin；MSYS2 会话不继承 Git 的 usr\bin。
- DSH_* 最后合并，保证优先；HOME、TMP、TEMP、LANG 不覆盖。

发现顺序

1. 配置的 bashPath + msystem（最高优先；无效就明确报错，不回退）。
2. Git 注册表 InstallPath（HKLM / HKCU）。
3. 已知根：Git（Program Files、LocalAppData、C:\Git、D:\Git）、MSYS2 （C:\msys64、D:\msys64、LocalAppData、C:\msys32）、Cygwin （C:\cygwin64、C:\cygwin）。
4. where git（从 git.exe 反推根）与 where bash。
5. PATH 上的 bash.exe / git.exe。

WSL 一律排除：System32\bash.exe、Sysnative、WindowsApps、\\wsl$、 wsl.exe 都不会成为候选。版本探测只在点 刷新 或 测试 时发生；打开设置页直接用缓存，不等待扫描。

设置页

打开 设置 → 通用 → 终端工具（Git Bash / MSYS2）。默认视图刻意保持很小：

- Shell：自动（推荐）、Git for Windows，或具体的 MSYS2 环境。选中即写入 path + msystem。
- 刷新：重新扫描根目录并探测 bash --version 版本/健康状态。
- 兼容：兼容模式 / 严格模式；下面一行红字说明当前代价。
- 高级与诊断：手动路径、使用此路径、恢复自动、测试、MSYS2 环境，以及平台 / 沙箱能力 / 后台任务 / 最近替换。

右上角徽章显示当前生效的 profile；手填的 Git bin 路径归一化后，徽章可能与输入框不同，这是正常的。

存了什么、何时生效

配置存在 profile 的 cordis.patch.yml：

- id: dsh-gitbash
config:
bashPath: 'C:\Program Files\Git\usr\bin\bash.exe'
msystem: MINGW64
compat: auto

- bashPath: '' = 自动。
- msystem 为 auto 或具体 MSYS2 环境；Git 忽略它并固定 MINGW64。
- compat 为 auto 或 strict。
- 配置在新 agent 创建时读取；已存在的会话不会热切换。开始新会话即可（子智能体会继承父会话）。
- 正常用设置表单；手改 patch 也可以，但需要重启 DSH。

常用操作

确认模型实际用的 shell

让模型执行：

用 bash 打印 $MSYSTEM、command -v bash、bash --version、pwd 和
git status。

预期：Git 为 MSYSTEM=MINGW64，MSYS2 为所选环境；bash 指向选中的安装； pwd 是 POSIX 形式，终端卡片显示 Windows cwd。

跑长时间服务

让模型用 run_in_background: true 启动，之后用 job_output 收日志、用 job_kill 停止。会话标题栏会出现后台任务徽章。

使用 MSYS2 工具链

1. 在 MSYS2 里安装环境，例如 pacman -S --needed mingw-w64-ucrt-x86_64-gcc。
2. 设置页 Shell 选 MSYS2 UCRT64。
3. 让模型执行 command -v gcc，应命中 C:\msys64\ucrt64\bin。

让子智能体干活

让父会话用 subagent 派一个子任务，子任务里用 bash 执行命令。子代理有自己的 bash；父会话收到子代理报告，并显示子智能体卡片。点“查看子智能体”可看子会话。

修“Git 会话显示 UCRT64”

把 Shell 改回 自动（或选 Git for Windows）并刷新。手填的 bin\bash.exe 会归一化到 usr\bin\bash.exe；如果仍显示 UCRT64，通常是旧构建或旧会话。

排障

| 现象 | 处理 |
| 设置页说没找到 bash | 安装 Git for Windows 或 MSYS2；点 刷新；或手填 <root>\usr\bin\bash.exe（不要加引号） |
| 新会话仍有 pwsh | 确认 DSH >= 0.2.1、插件在 profile bundles 里、DSH 已重启；看 %TEMP%\dsh-gitbash.log 的 replace: |
| 只有旧会话没有 bash | 替换按 agent 生效；新建会话。子代理从父会话继承 |
| Git 会话显示 MSYSTEM=UCRT64 | 旧 bin\bash.exe 路径/旧构建；用自动/刷新；当前构建会归一化到 usr\bin\bash.exe |
| MSYS2 环境不存在 | 在 MSYS2 里安装该环境；profile 只列出 bin 存在的环境 |
| CreateFileMapping ... Win32 error 5 / couldn't create signal pipe | 进程被放进了 Windows ACL 沙箱。本插件在 compat: auto 下不 confine bash；移除自定义 confine 或换标准 preset |
| read-only 拒绝 bash | 设计如此；切到 workspace-write / danger-full-access，或提权 |
| 严格模式拒绝 workspace-write | 把兼容改成 auto，切到 danger-full-access，或提权到 danger-full-access |
| 装了另一个插件后 pwsh/bash 都没了 | 两个 bash 替换插件冲突；只保留一个（见安装） |
| 后台任务不可用 | preset 没有组合 ctx.jobs；用标准 Web preset，或前台加超时 |
| 找不到 job_kill / job_output | 它们是 DSH 的独立工具，不属于 bash；确认 jobs 工具组在 preset 里 |
| 设置行不显示 | DSH 太旧、插件未加载，或 Web 客户端未重建/刷新；重启并硬刷新 |
| 找不到 Git/MSYS2 选择，或切换后当前会话没变 | 选择器只在 设置 → 通用 → 终端工具（Git Bash / MSYS2）；内置 终端 卡片是独立的 UI 终端插件。切换会立即保存，但只对新会话生效 |
| 路径含空格失败 | 填完整路径，不要加引号；表单会原样保存 |
| WSL 的 bash 不出现 | 有意排除；WSL 不符合本插件的 profile/环境模型 |
| 输出像被截断 | 长输出只保留尾部；用结果里给的 spill 路径看完整文件 |

诊断

- 插件日志：%TEMP%\dsh-gitbash.log（通常是 C:\Users\<你>\AppData\Local\Temp\dsh-gitbash.log）。一行一条： apply、能力探测、replace: applied ... 或 skipped ... pwsh is not restrictable。
- 设置状态：/api/dsh-gitbash/state（需要认证），设置行用它； /discover、/validate 也是客户端接口，不是公开无认证 API。
- DSH 开发者工具：查看原始 session 事件、消息分组和 Node 后端，是 job / 子智能体卡片的最终依据。
- 契约核对：pnpm compatcheck 对比部署的官方 bundle 与本插件依赖的字符串。

完整的真机原始事件见 docs/SMOKE.md。

兼容与升级

- 最低 DSH 0.2.1。插件只使用官方服务的结构性投影（ctx.subprocess、 ctx.jobs、ctx.sandboxPolicy、ctx.shellEnv、ctx.workingDirectory、 ctx.approval、ctx.configForms 等），不 import 私有 DSH 包。
- 关键集成点：agent/created、tools.restrict、tool:bash / tool:pwsh 的 section 名、结果标记、meta.cwd。事件名写错是静默 no-op，所以测试会断言这些裸字符串。
- DSH 升级后：
1. pnpm compatcheck
2. pnpm test
3. 改了 src/ 就 pnpm build；提交的 lib/ 必须与 src/ 同步
4. 重启 DSH，硬刷新 Web UI
- 非 Windows 不注册任何行为（cordis.patch.yml 在 process.platform !== 'win32' 时禁用 entry）。

2026-10-18 真机验证：DSH 0.2.1-rc.2、Git for Windows 2.56、MSYS2 5.3.20（UCRT64）；直接 bash、后台任务、子智能体、设置页切换和原生 UI 卡片均已跑过。原始事件见 docs/SMOKE.md。

开发

pnpm install
pnpm build # lib/index.js + lib/client.js
pnpm check # tsc --noEmit
pnpm test # node:test；75 个用例，含真实 Git/MSYS2（存在时）
pnpm selftest # 纯逻辑自测，不需要 DSH
pnpm compatcheck # 对已安装 DSH 做契约字符串核对

真实集成测试会自动发现本机 Git/MSYS2；没有时跳过。覆盖 MSYSTEM、PATH 隔离、退出码、stderr、真实子 bash、超时，以及 compat 下“工作区外可写”的预期行为。

目录

src/index.ts host 入口：apply、Config、路由、替换 src/shared/protocol.ts host/client 共用 wire 类型 src/host/ 发现、环境、执行器、jobs、渲染、工具、路由 src/client/ 设置行、store、API、locales tests/ 单元 + 真实集成测试 scripts/ selftest、compatcheck docs/ 设计、真机记录、截图 lib/ 构建产物，供 link: 安装

src/ 与 lib/ 必须同步；link: 安装实际加载 lib/。docs/ 的唯一索引是 docs/README.md，未登记的文档视为不存在。

打包

pnpm build
pnpm check
pnpm test
pnpm pack

npm 包名 @riverzh/dsh-gitbash（DSH entry id 仍是 dsh-gitbash），engines.dsh = ">=0.2.1-0"，engines.node = "^22.19.0 || >=24.0.0"。
包含 host 入口、client bundle、lib/、src/、cordis.patch.yml、docs 与两份 README。

限制与非目标

- one-shot bash：每次调用都是 bash -c，不是持久 shell/PTY；minimal preset 的 persistent shell 不保留。
- Windows 沙箱不兼容：bash 无法被 confine；见安全边界。
不存在让 MSYS2 安全跑在 ACL 沙箱里的开关。
- 不选 WSL；Cygwin 只是 best-effort、experimental。
- 旧会话不迁移；设置只对新 agent 生效。
- 后台任务无超时；需要显式停止。
- 输出只保留尾部；完整内容看 spill 文件。
- 替换按 agent 生效：子代理从父会话继承，但插件启用前已存在的子代理不会热改。

License

GNU General Public License v3.0 only（GPL-3.0-only），见 LICENSE。