dsh-gitbash-shell

dsh plugin --profile web add dsh-gitbash-shell

dsh-gitbash-shell


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

Unreleased／实验性实现讨论：下述 fail-closed 与两个显式工具尚未正式发布，不是发布候选；安装公开 npm 包不保证包含这些变更。详见[设计、接口与待讨论决定](<docs/experimental-native-execution.md>)、[验证矩阵与复现](<docs/experimental-native-verification.md>)及 CHANGELOG。

让 DeepSeek Harness (dsh) 在 Windows 上默认用 Git Bash 跑命令的官方风格插件

—— 不替换宿主执行器(官方 PowerShell 执行器原样保留):新增自有 bash 工具

(私有 Git Bash 执行器实例,不注册为服务),并为所有模式注册对应的 Git Bash 版

agent preset。

它解决什么

官方 Windows 组合默认把 dsh-pwsh-sandbox 作为 ctx.shell(PowerShell 执行器),

且各 preset 的 tool-bash 行在 win32 上被禁用——因为在 Windows 上裸 bash

会解析到 C:\Windows\System32\bash.exe(WSL 占位)。本插件不替换这个执行器:

它新增一个自有 bash 工具,执行在私有的 Git Bash 执行器实例上(继承官方

@deepseek-ai/dsh-bash-sandbox,bashPath 只认 Git for Windows)。沙箱语义在

POSIX 宿主上完整保留;

**Windows 宿主上受限模式有一处重要例外——见下方

[「安全语义:Windows 上的受限模式」](#安全语义windows-上的受限模式)**。

安装本插件后(v0.35.0 起,默认):

• 官方四个模式直接获得 Git Bash——模式列表保持官方原样,不再新增变体:

每个会话创建时,本插件探测该模式的工具面,「有 pwsh 无 bash」(官方 Windows

组合的形态)即在该会话内注册自有 bash 工具(对官方 tool-bash 逐调用镜像:

后台任务、审批升级、渲染行为不变)。宿主官方 pwsh 工具是**真正的

PowerShell**(v0.39.0 起,本插件不再替换执行器),默认被隐藏、开关显示——见下一条。

• bash 工具说明附带路由规则:能用 Git Bash 就用 Git Bash;只有必须用到

Windows 原生能力(cmdlet/注册表/服务/WMI)时才用 PowerShell;bash 出错在

bash 里修,禁止在 bash 里嵌 pwsh -Command(变量展开与输出编码会在那里坏掉)。

• pwsh 工具(官方 PowerShell,默认隐藏,开关显示):宿主官方的 pwsh 工具

就是真正的 PowerShell(官方解析器自动优先 PowerShell 7),可直接用于 Windows

原生操作(cmdlet/注册表/服务/WMI)。默认关闭(pwshTool 开关):该工具对本插件

会话隐藏,主机保持 bash 优先;开启后它直接可见可用——无需安装任何额外组件。

旧 PowerShell 7 旁路工具(v0.37–v0.38.5 的独立工具)已随 v0.39.0 新架构退役;

命令仍然首选 bash 工具。pwshTool 与 experimentalNative 的工具面可见性只影响新会话或重启后的

会话:运行中的会话会保持它创建时的工具面,保存开关只在宿主日志留一行提示,不会中途重建。

实验原生工具的执行门禁仍按当前开关立即生效。

• **gb_* FastCtx 文件工具(默认关,v0.39.4 起弃用)**:gb_inspect_local_file/gb_grep/

gb_glob/gb_replace(Rust 实现:批量范围读取带 token 预算、grep 截断

标注、编码探测)。它们是官方 read/grep/glob/edit 的补充——官方工具接

文件沙箱,仍是默认推荐。**dsh-ops 0.3.0 起原生 ops_* 文件工具取代了

FastCtx 上游,本组默认关闭**(fastctxTools 显式开启可恢复);已安装

dsh-ops 时无论开关如何都会自动让位。与 dsh-ops 并存时本插件继续负责

/c/ 方言统一:ops_* 的入参(含 root/operations[].path/protect)

自动转换、返回与报错路径自动回流 /c/。

• 与 dsh-ops 0.5.0 并存:bash 只留一份(v0.50.0;只支持 0.5.0 单行):宿主机制决定「可见但拒绝」到不了「看不见」——

tools.restrict 只能过滤继承面,而 ops_bash 注册在 agent 自有层。0.5.0 把 0.4.x 的组件行/mode 行收成

一行 dsh-ops,shell 发布改由四个内置模式 section 的 bash 开关控制。于是本插件经官方 configEditor 通道

给 minimal/standard/ptc/cordis 各写 bash:false:安装本插件时这四个模式的 ops_bash 不再注册;

global.bash、presets.<自定义 id>、ops 的 pwsh7 overlay、文件/后台增强全部不动

——bash 门只套在 mountSessionBash 上,pwsh 走 mountBundledPwsh 独立路径。

0.5.0 已移除旧 dsh-ops-shell/dsh-ops-file/dsh-ops-mode-* 行,本版也删掉对应接管逻辑:

旧 dsh-ops 的 profile 不再被本插件去重,请先升级 dsh-ops 0.5.0(或留在本插件 v0.49.0)。

停用或卸载本插件的瞬间自动还原(dispose 钩子只撤回自己写的 bash:false,同 section 的其它设置原样保留),

重新启用又会自动接管。三个边界:①关机状态下卸载的残余覆盖,可用 dsh-ops 设置卡恢复默认,或重新安装/停用本插件

触发还原;②停用时若覆盖值已被你手动改回 true,视为你的选择、不动它;③0.5.0 只对四个内置模式生效:

dsh-ops 不再全局接入未列出的自定义 preset,本插件的 ptc-cordis 与「· Git Bash」变体 id 不在四个内置模式中,

那些会话里 dsh-ops 不会发布 ops_bash;dsh-ptc-cordis-preset v0.26.0 自己挂 dsh-ops/integration 取文件工具,

但保持 shell:false,所以我们的 bash 仍是唯一命令工具。

无设置开关——想用 ops_bash 就停用本插件,还原是自动的。

后台任务与文件/PTC 增强全部让给 dsh-ops(2026-10-19 用户决策):剔除清单被守卫测试

锁死为 ops_bash + ops_run 两项,永不含 ops_run_background/ops_job_*——你启用

dsh-ops 的「后台任务」组件后,这组全局工具在普通会话与 PTC 创造模式下原样可见可用,

本插件不做任何 deny。bash 归 gitbash,后台与增强归 dsh-ops,职责互不越界。

四个「· Git Bash」变体 preset 仍保留,默认关闭(variantPresets 开关,

设置卡可开):开启后注册 standard-gitbash/minimal-gitbash/code-gitbash/

cordis-gitbash 四个变体并停用官方模式的工具补位(两者互斥)。

⚠️ 从 0.34.x 升级:变体默认关闭。全局默认模式会自动迁移——若你之前把默认设成

某个变体(*-gitbash),升级后首次启动会经官方设置通道切到对应官方模式

(standard-gitbash→standard、minimal-gitbash→minimal、code-gitbash→ptc、

cordis-gitbash→cordis);打开 variantPresets 则不迁移、一切照旧。钉在变体上的

旧会话无法被迁移(官方 agent-preset/locked 锁定),请新建会话。

原有 标准模式/极简模式/PTC 模式/创造模式(shipped)与

dsh-ptc-cordis-preset 的 PTC 创造模式 用户 preset 均不受影响、自动受益。

宿主要求与 preset 对齐

自 v0.49.0 起宿主下限为 dsh >= 0.2.2-rc.1:门禁读 engines.dsh(rc.1 的 app-boot 只要见到该字段就忽略 peer,semver 以 includePrerelease: true 求值),peerDependencies 同步声明并标 optional;只服务这一代宿主。四个变体的行集是 src/compositions.js

里已提交的 JS 数据,镜像官方 0.2.2-rc.1 的 standard/minimal/ptc/cordis 行切分并叠加

Git Bash 增量;跟随 dsh 升级的对齐由冒烟测试

compositions: dsh >=0.2.2-rc.1 executor shape and profile-context gates 锁住。

preset id 保持 code-gitbash 不变——会话钉在 id 上,dsh 0.1.2 把内置 code

改名 ptc 时本插件的变体 id 就没有跟随(改名会让已固定的会话报 preset not found)。

可选官方行按包探测接入:rc.1 全工具 preset 自带时间上下文(time-context)与

提醒工具(schedule_*),极简 preset 自带 image-only tool-fs 与专属 compaction 组,

全工具 preset 另有插件市场(tool-plugin-market)。本插件在挂载时按 ctx.baseUrl

探测这些包,可用才纳入对应变体;剥掉某个包的 profile 只降级该行,不会拒绝整棵

preset 挂载。

0.2.2-rc.1 基线:官方全工具 preset 的 tool-fs 行带

config: { applyPatch: false },本插件的 standard/cordis/ptc 变体同步,极简变体不加;

插件管理/市场行按 rc.1 门控(cordis 两者跟 profileContext,standard 仅 manager 跟

profileContext,ptc 两者恒禁用)。dsh.compatibility.dshReleases 只登记

0.2.2-rc.1。

安装(公开 npm 插件,推荐)

npm: dsh-gitbash-shell，

源码与 Release: github.com/KannaKuron/dsh-gitbash-shell

# web 图形界面
dsh plugin --profile web add dsh-gitbash-shell

dsh plugin add 会自动:① pnpm 安装 npm 包 dsh-gitbash-shell;

② 检测到包声明的 dsh.bundle 后把它追加进该 profile 的

dsh.profile.bundles。重启该 profile 的 host 后生效。

它做了什么

bundle patch(cordis.patch.yml)是纯新增(v0.39.0 起):只插入本插件行

gitbash-shell,不禁用、不替换任何官方行——宿主官方 PowerShell 执行器与全部

官方组件保持原位。旧版「替换执行器」的三步 patch 在 route B 下变成运行时工作:

1. 不再撤 pwsh-sandbox、不再插执行器行:插件不再替换宿主执行器,官方

pwsh 工具重新是真正的 PowerShell;

2. 自有 bash 工具跑在私有执行器实例上(src/bash-tool.js + src/shell.js):

GitBashSandboxExecutor 继承官方 @deepseek-ai/dsh-bash-sandbox,仅把内层

argv 换成 <git-bash.exe> -c <command>,在私有 cordis scope 中构造

…(truncated)