@riverzh/dsh-gitbash

dsh plugin --profile web add @riverzh/dsh-gitbash

dsh-gitbash

[English](README.md) | 简体中文

一个面向 DeepSeek Harness（DSH） 的 Windows 终端桥：把模型侧的 pwsh

工具换成真正的 bash，并同时支持、可选 Git for Windows 与 MSYS2，保留官方

终端工具的全部行为（cwd、后台任务、超时转后台、提权、终端卡片、PTC、meta.cwd）。

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

最低 DSH：0.2.2。 仅 Windows 10/11。替换只对新会话生效；已存在的会话

保持创建时的工具目录。

---

目录

• [功能](#功能)
• [环境要求](#环境要求)
• [安装](#安装)
• [快速开始](#快速开始)
• [安全边界（先读）](#安全边界先读)
• [使用 bash 工具](#使用-bash-工具)
• [Shell profile（Git / MSYS2）](#shell-profilegit--msys2)
• [设置页](#设置页)
• [常用操作](#常用操作)
• [排障](#排障)
• [诊断](#诊断)
• [兼容与升级](#兼容与升级)
• [开发](#开发)
• [限制与非目标](#限制与非目标)
• [License](#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。

详见[安全边界](#安全边界先读)。

• 已验证：97 个单元/集成用例，加上 DSH 0.2.2-rc.1 上的 Git 与 MSYS2 真机

冒烟（直连、promote、后台、子智能体；0.2.4 审计轮 31/31 场景检查 + 15/15

设置页检查，含 strict 实机拒绝；0.2.5 手动路径 UI 流程 13/13；0.2.6 的

read-only 拒绝、审批允许/拒绝、恶意 BASH_ENV/导出函数清除、大输出 spill、

job kill 与干净最终设置行）。

---

环境要求

项 · 要求

DSH · >= 0.2.2（已在桌面运行时 0.2.2-rc.1 实测）

Windows · Windows 10/11 x64；MSYS2 arm64 环境也可用

bash 提供方 · Git for Windows 和/或 MSYS2

Node.js · >= 24.9，仅构建/开发需要（DSH 0.2.2 的工作区下限）

可选 · Cygwin，best-effort，不推荐

• Git Bash 与 MSYS2 共用 MSYS2 运行时；该运行时无法在 DSH 的 Windows ACL 沙箱中

启动。这是 OS 层约束，不是插件 bug（证据见

[docs/DESIGN.md](docs/DESIGN.md) §2）。

• WSL 的 bash.exe 被有意排除：WSL 不是 Git Bash，也不符合本插件的

profile/环境模型。

---

安装

使用 DSH Desktop 自带的 CLI

不要用 npm 全局的旧 dsh（例如 0.1.7），它不认识 0.2.2 的

plugin/profile 契约。使用桌面安装目录里的 CLI：

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

修改 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.6

最新版可用 @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，闭控件和

展开列表都保持可读：

---

安全边界（先读）

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 都写明；每个未受

沙箱约束的结果也带 [compat: ...] 尾注。

• 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 的跨

…(truncated)