Passer au contenu principal
K

dsh-gitbash-shell

kannakuron/dsh-gitbash-shell

Plugin Windows qui remplace l'exécuteur de shell du host par Git for Windows bash à travers tous les modes d'agent, matérialise les variantes Git Bash des préréglages standard, minimal, PTC et Cordis (marquées par sha256 par fichier, modifications utilisateur préservées), et expose une capacité gitBash pour que les préréglages compagnons choisissent Git Bash automatiquement ; lorsque dsh-better-sidebar est installé il adopte aussi le shell terminal de cette barre latérale (onglets UI et outils terminal_* face au modèle) via sa couture de paramètres officielle.

Installer

dsh plugin --profile web add github:kannakuron/dsh-gitbash-shell

README

dsh-gitbash-shell

Awesome DSH Plugin

简体中文 | English

v0.53.0:新增「路径工具」独立开关(issue #45)。关闭后只隐藏/禁用 gitbash_to_native_path,gitbash_native 与 fail-closed 安全兜底不受影响;修改即时作用于后续调用,工具面可见性重启 DSH 后更新。设计背景见设计、接口与决定与验证矩阵。

让 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 上的受限模式」。

安装本插件后(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.x 并存: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(0.5.3 起若该行还带 ops-ptc section,也写): 安装本插件时这些模式的 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 的其它设置原样保留), 重新启用又会自动接管。接管前会在 profile 目录的 .gitbash-ops-ownership.json 中原子记录实际修改字段的原值, 重启后仍可精确恢复;用户原先设置的 bash:false 不会被认领或删除。升级前留下且没有记录的 false 保持原样, 不猜测它属于用户还是旧插件。三个边界:①关机状态下卸载的残余覆盖,可用 dsh-ops 设置卡恢复默认,或重新安装/停用本插件 触发还原;②停用时若覆盖值已被你手动改回 true,视为你的选择、不动它;③0.5.0+ 只对内置模式生效: 0.5.0–0.5.2 是四个,0.5.3 起新增第五个 ops-ptc(OPS (PTC));只有 editor row 实际带该 section 时本插件 才写 bash:false,所以老行不会被塞未知键。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.2 的 standard/minimal/ptc/cordis 行切分并叠加 Git Bash 增量(rc.1 宿主只少可选行,由探测降级);跟随 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);rc.2 又新增原生 Office 工具 (tool-office)。本插件在挂载时按 ctx.baseUrl 探测这些包,可用才纳入对应变体; 剥掉某个包的 profile 只降级该行,不会拒绝整棵 preset 挂载。tool-office 探针同时 兼作 rc.2 行方言探针:只有能解析该包时才给 tool-subagent-control 写 config: { interrupt: false },rc.1 不会收到这个新配置键。

0.2.2-rc.2 基线:官方全工具 preset 的 tool-fs 行带 config: { applyPatch: false },本插件的 standard/cordis/ptc 变体同步,极简变体不加; standard 的 skill-filesystem 行在解析到官方 preset 包旁 skills 时带 customSkillDirs;standard/ptc 在 present 之后携带 tool-office,其 tool-subagent-control 行带 interrupt: false。rc.1 宿主由探测降级:没有 office 包就不写该行与 interrupt 键。插件管理/市场行按 rc.1 门控(cordis 两者跟 profileContext,standard 仅 manager 跟 profileContext,ptc 两者恒禁用)。 dsh.compatibility.dshReleases 登记 0.2.2-rc.1 与 0.2.2-rc.2。

安装(公开 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 后生效。

日志

健康启动保持静默:preset 注册/退役、工具面接线、侧栏终端接管等生命周期说明默认不打印。需要排查时用 DSH_GITBASH_DEBUG=1 启动 host,才会看到这些调试行。真正的降级与失败(schemastery 不可解析、注册或接线失败、拒绝执行)始终写到 stderr,不受该变量影响,也不会被静默(issue #46)。

它做了什么

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 中构造、永不 注册为 ctx.shell 服务。沙箱策略/拒绝分类/后台任务/超时/设置节沿用官方 实现;full-access 分支单独接 Git Bash(父类那里硬编码裸 bash); Windows 上受限分支有一处例外,见下一节;
  3. gitbash-shell 行(dsh-gitbash-shell):v0.35.0 起双形态—— 默认(variantPresets: false)不注册变体,由行内工具补位 (src/inline-tools.js)在 agent/created 时按工具面注册自有 bash 工具; 官方 pwsh(真 PowerShell)默认隐藏(pwshTool 开关显示);gb_* 工具 (src/fastctx-bridge.js)随行发布。开关打开时按 v0.32.0 起的声明式注册 (ctx.agentPresets.register)提供上表 4 个 preset 变体—— 行集是仓库里已提交、可 diff 的 JS 数据(src/compositions.js),不再物化 任何目录;旧版本遗留在磁盘上的物化树,启动时仅当 marker 判定为 「未被用户改过」才单向清理,用户改过的绝不碰(清理不受开关影响)。

环境变量:bash.exe 经 host 的托管 subprocess provider 直接启动(不经登录壳); 父环境经过宿主凭据清洗,再合入受保护的 DSH_* 快照,不提供完整未过滤环境或绕过凭据保护。

安全语义:Windows 上的受限模式

POSIX 宿主:自有执行器的受限路径仍继承官方后端与拒绝分类。本节只讲 Windows。

Windows 自有 bash/native 工具在 experimentalNative 开启时(默认)采用 fail-closed:read-only、 workspace-write 或缺失/未解析的策略在执行前拒绝;仅真实解析为 danger-full-access 的调用可以执行。受限请求不会登记/启动无围栏进程,也不会自动 回退 pwsh/cmd/WSL、切模式或绕过文件工具拒绝。用户可在设置中关闭 experimentalNative,恢复明确标注 unconfined 的兼容 Bash 行为。

  • 拒绝不是沙箱修复:当前仍无已验证的受限 Git Bash。历史失败为 Win32 error 5 / 0xC0000142;匹配本机 MSYS 源码后发现 signal pipe 显式 SD 缺 restricting SID, 现代 cygheap 使用 VirtualAlloc,Core 已补 TokenDefaultDacl。不能继续宣称 “只补默认DACL就修好”或“所有未来版本无解”;真正 IPC/OS 方案仍需隔离环境验收。
  • 策略按调用解析:默认 full 不会放宽另一个只读会话;原生入口的准备、异步边界与 spawn seam 重验策略。取消、owner dispose 和主动 kill 会标输出不完整,不伪装自然完成。
  • 文件工具是另一层:官方 write/edit 仍按其 policy 判断;读取不一定只限工作区。 路径 helper 只转换字符串,不检查存在性、不授予读写权。不得用任一工具绕过已发生的拒绝。
  • 范围:此门控覆盖本插件自有 bash/native 工具;侧栏交互终端、minimal 的持久 PTY 和其他插件执行器不因此获得围栏。官方 root PowerShell 执行器没有被替换。

旧 unconfined 记录/渲染兼容仍保留供历史结果使用,不代表新调用可降级。历史见 CHANGELOG v0.13.2,当前行为及验证见 CHANGELOG。

配置

gitbash-shell 行(行 id 自 v0.24.0 起与设置命名空间同串;≤ v0.23.0 为 gitbash-presets) 支持 presets 数组,只注册你常用的模式(未列出的变体不再进入名录;改动经 volatile-update 触发重注册):

- id: gitbash-shell
  config:
    presets: [standard-gitbash, minimal-gitbash]   # 默认注册全部 4 个
    suppressPeerCordis: false                       # 与 dsh-ptc-cordis-preset 去重,默认关

去重开关 suppressPeerCordis(布尔,默认 false)只在两个事实同时成立时才把 创造模式 · Git Bash(cordis-gitbash)从名录里摘掉:开关为 true 且 dsh-ptc-cordis-preset 报告它的 PTC 创造模式 已经是 Git Bash 版。默认关 ⇒ 名录与 0.24.x 的四个变体逐字不变;判定细节、生效时机与两侧同步方式见下方 「与 dsh-ptc-cordis-preset 联动」。

子代理/队员是否也用 Git Bash:subagentDialect(默认开,v0.27.0)

- id: gitbash-shell
  config:
    subagentDialect: true   # 默认;false = 方言只对主代理生效

默认开启时,子代理、团队队员(含嵌套子代理)与主代理走同一条方言链路:提示词里的路径同样是 /c/... 形式、 路径参数同样被翻译、结果与报错同样回显为 MSYS 形式、run_code 程序里的路径字面量同样被翻译,DSH_PATH_DIALECT 环境事实也照常下发。 关闭后这些只对主代理生效:委托出去的请求保持官方 shell 语义(提示词不改写、路径参数原样传递),适合"子代理要跑原生 Windows 工具链"的场景。

能力边界(如实说明):dsh 每个进程只有一个 shell 执行器(ctx.shell 是单例服务),所以 Git Bash 二进制本身仍是全局的, 这个开关管的是方言/翻译层,不是"换一个 shell"。关闭后委托代理见到与写出的是 Windows 形式路径(C:/...),Git Bash 同样接受,行为自洽。 委托身份的判据用会话头的 origin === 'subagent' / delegationDepth > 0(与 dsh 自身一致),判定不出来时按主代理处理(保留方言)。

配合 agent-presets 的 default,新会话直接落在 Git Bash 模式,免去每次在 模式选择器里翻找(原版 shipped 模式无法替换或隐藏——部署级、只读):

- id: agent-presets
  config:
    default: ptc-cordis   # 或 standard-gitbash / minimal-gitbash

bash 初始化脚本:initScript(默认空 = 不启用,v0.45.0,issue #37)

- id: gitbash-shell
  config:
    initScript: "~/.dsh/bash-env.sh"   # 默认 "";填一个脚本路径即可

填写后,本插件每次执行 bash 命令都会把它作为 BASH_ENV 传给 Git Bash —— 这是 bash 自己为非交互 shell 准备的钩子:bash -c 会先 source 它,而且没有 -l(登录 shell)的任何副作用(cd $HOME、PATH 重排、profile 输出混进 stdout 都不会发生)。典型用途是 fnm / nvm 这类需要初始化的 node 管理器:在脚本里写一行 eval "$(fnm env)",node / npm 就会在每条工具命令里可见。

两点边界:①脚本自身打印的任何内容都会混进命令输出,请不要在脚本里 echo;②路径必须存在——bash 对不存在的 BASH_ENV 静默忽略,所以填错的效果看起来和"没启用"一样。~ 会展开为家目录。

bash 从哪里来:解析链与失败引导(v0.28.0,issue #11;懒化与 exec-path 层 v0.33.0,issue #13)

bashPath 默认留空 = 自动探测;解析顺序就是契约:

  1. 设置里填的(显式值优先,失败也不会被别的路径顶替): gitbash-executor 行 config 的 bashPath > gitbash-shell 行 / 设置卡的「Git Bash 路径」;
  2. 默认安装位置:C:/Program Files/Git/bin/bash.exe、%ProgramFiles(x86)%\Git、%ProgramW6432%\Git、 %LOCALAPPDATA%\Programs\Git\bin\bash.exe;
  3. PATH(用户 PATH + 系统 PATH,进程内已合并)逐目录找 bash.exe;
  4. PATH 上的 git.exe 反推 <gitdir>/../bin/bash.exe;
  5. git --exec-path 反推 + GitForWindows 注册表(v0.33.0):对 PATH 上的 git.exe(Scoop / choco 的 shim 也照常启动真身)跑 --exec-path,从输出向上找 Git 根 —— 兼容 mingw64 / ucrt64 两种运行时 布局,补上「Scoop 安装、PATH 上只有 shims、没有 bash.exe」的盲区;随后兜底读注册表 HKLM\SOFTWARE\GitForWindows 的 InstallPath;
  6. 注册表 Path(HKCU\Environment、HKLM\...\Session Manager\Environment)——覆盖"GUI 启动时 PATH 快照过期";
  7. 全落空 ⇒ 报错 + 引导(启动日志一份完整报告,客户端弹一次引导框)。

解析结果是活的,不是启动时判一次(v0.33.0,issue #13):启动那一刻插件行可能还没全部挂载,显式配置 会被短暂读成空 —— 现在启动日志、状态接口、弹窗与侧栏终端接管都在使用时实时重读,执行器能用, 它们就不会再说「解析失败」;启动日志也会在行挂载稳定后补一份最终结论。

只认 Git for Windows 的 bash。 WSL(C:\Windows\System32\bash.exe,永远在 PATH 且排序靠前)、 WindowsApps 别名、MSYS2、Cygwin 的 bash 一律拒绝;候选还要通过 Git 布局(usr/bin + cmd\git.exe + mingw64)、git --version 的 .windows 指纹(.windows.1 与自定义构建的 - 后缀都接受),以及实跑 bash -c "uname -s" 必须是 MINGW*_NT-*。

本插件不会回退到 PowerShell / cmd / 任何其它 shell。 找不到 Git Bash 就是找不到:设计如此 —— 装了本插件就是要用 Git Bash,偷偷换一个能跑的顶上是错的。失败时弹窗给两件事:在弹窗里直接填 bashPath (写入设置卡同一字段)或去下载 Git for Windows;同一 boot 只弹一次,可关闭。

官方侧栏终端(「新建终端」)自动切到 Git Bash(v0.29.0)

DSH 自己的「新建终端」不经过本插件的执行器:它由官方的 terminal-controller 决定 shell,未配置时用 「执行环境的默认 shell」——而在 PATH 里 bash 指向 C:\Windows\System32\bash.EXE(WSL 启动器)的机器上, 新终端跑起来就是 Ubuntu。本插件现在会自动把它切过来:

  • 仅 Windows、且已解析出通过验证的 Git Bash 时;设置开关 「自动接管侧栏终端」默认开启(autoTerminalShell)。
  • 只在官方那一行没有自己的 shell 时写入 { path: <Git Bash>, name: 'Git Bash', args: ['-i'] } (-i 就是官方对 bash 的默认参数;显示名固定为 Git Bash,这样菜单里不会与那条解析到 WSL 的候选 bash 混淆)。 已经由 v0.29.0 写入过、名字还是 bash 的历史配置会在启动时只改名字(path/args 原样保留,幂等); 只迁移我们自己写的那个旧默认名 bash —— 你自己起的名字(例如 My Bash)一律不动(它本来也不会与 WSL 候选混淆)。 你已经手动指定过别的 shell(例如某个 WSL 配置)⇒ 绝不覆盖,只在宿主日志里提示,并告诉你如何交还给 Git Bash(清空该字段)。
  • 写入走官方配置编辑器(设置 UI 用的同一个 API),落到 profile 的 patch 层;新终端立即生效,已打开的终端保持原样。
  • 不需要重启,也不会写坏「新建终端」:只写我们验证过存在的 Git Bash(官方对无法解析的路径没有回退,会直接启动失败)。
  • 失败时 fail-loud:日志写清原因,并通过读回校验确认值真的落进去了(不出现"假成功")。
  • ⚠️ 如实说明:我们没有改 shellCandidates,所以「新建终端」的 shell 选择菜单里仍可能列出一条解析到 WSL 的 候选 bash —— 被改掉的是默认项/首项(它现在是我们写入的 Git Bash),不是整条菜单。想彻底不让 WSL 出现在菜单里, 需要另外调整 terminal-controller 行的 shellCandidates(本插件本轮不做,以免覆盖别人的部署配置)。

三步复验(Windows):

  1. 装好 Git for Windows,重启 DSH,打开本插件设置卡:开关「自动接管侧栏终端」为开;宿主日志出现 official sidebar terminal switched to Git Bash: …。
  2. 新建终端,在终端里确认它确实是 Git Bash(两条判据任选,uname -s 最硬):
    • uname -s ⇒ MINGW64_NT-10.0-<build>(Git Bash 的 system name;WSL 这里是 Linux);
    • echo $MSYSTEM ⇒ MINGW64(最简)。 ⚠️ 不要用 uname -r 判定:Git Bash / MSYS2 下它是 MSYS 运行时版本(形如 3.6.9-b4195d69.x86_64, 真实用户实测就是这个值),而 WSL 的 uname -r 才是 6.x.y.z-microsoft-standard-WSL2 —— 两者都不能单独用来判定。
  3. 回退:⚠️ 关掉设置卡里的开关只阻止以后的自动写入,不会删除已经写进配置的字段。要彻底恢复原样, 请把 profile 的 patch 里 terminal-controller 行的 shell 字段删掉,再重启 DSH(终端随即回到原来的 shell); 只想让它别再自动改、但不介意保留现状的话,关开关即可。

配置(自有 bash 工具)

bashPath 经设置卡「Git Bash 路径」(= gitbash-shell 行 config 的 bashPath 字段)配置;pre-v0.39 旧 profile 遗留的 gitbash-executor 行配置仍被读取 (兼容,优先级更高):

- id: gitbash-shell
  config:
    bashPath: "D:/Tools/Git/bin/bash.exe"   # 默认空 = 自动探测链

验证

npm test

重启 host 后新会话:

  • 工具列表里出现自有 bash 工具(执行在 Git Bash 上);官方 pwsh 工具默认隐藏, 设置卡开启「pwsh 工具」开关后可见(真正的 PowerShell);
  • echo \$BASH_VERSION 有输出、command -v bash 指向 Git 安装目录。

卸载

dsh plugin --profile web remove dsh-gitbash-shell

或删除 profilepackage.json 中依赖 + dsh.profile.bundles 中的条目后 dsh plugin --profile web install。卸载并重启后,未改过的 * -gitbash preset 会被插件自动清理;宿主官方 PowerShell 执行器原样保留(本插件从未替换它), 官方 pwsh 工具不再被隐藏。

与 dsh-ptc-cordis-preset 联动

本插件在 host 上发布 gitBash 能力服务({ active, bashPath },仅 Windows 为 active)。 dsh-ptc-cordis-preset v0.5.0+ 在注册 PTC 创造模式 时会检测该信号:两个插件都安装时,PTC 创造模式自动注册为 Git Bash 版 (tool-bash 启用、tool-pwsh 禁用),无需新增模式、无需手工修改 preset; 只装本插件时 PTC 创造模式保持原样(由它自己的插件管理)。

去重开关:suppressPeerCordis(默认关,v0.25.0)

联动生效后,创造模式 · Git Bash(本插件的 cordis-gitbash)与对方已经 Git Bash 化的 PTC 创造模式 面向的是同一件事,而两插件同装时它们默认并列出现。把本插件行 Config 上的 suppressPeerCordis 打开,本插件才会把自己的那个变体摘掉(需求与取舍见 issue #7)。

判定 = 两个事实同时成立,缺一不可:

  • 开关为 true;
  • 且对方通过 host 能力服务 ptcCordisPreset 报告 gitBashActive: true(即它的 PTC 创造模式 确实按 Git Bash 版生效)。

对方没装 / 尚未挂载 / 没生效 / 版本低于 0.14.0 ⇒ 一律不摘:宁可名录里多一个条目, 也绝不因为"探测不到对方"就少给用户一个模式。默认关,所以不主动打开就没有任何行为变化。

生效时机:

  • 开关是实时的:走行 Config 的 volatile 通道,对方的能力则经 ctx.inject(['ptcCordisPreset']) 观察(与插件行激活顺序无关),两边任一变化都当场 reconcile——摘掉打日志 preset 'cordis-gitbash' retired (dsh-ptc-cordis-preset covers Creation mode on Git Bash),恢复打 preset 'cordis-gitbash' registered declaratively。已经挂载的会话 钉在自己的组合快照上,不受影响;名录变化从新会话开始可见。

两侧设置卡上是同一份状态:权威值只有本插件这一行 Config 一份;对方的设置卡通过 ctx.configForms.get('gitbash-shell') 绑定同一行、写同一个字段(DSH 官方支持编辑另一个 插件所拥有的命名空间),所以任一侧改动另一侧立即同步——不存在两份拷贝,也没有同步逻辑。

依赖版本:去重开关本体在本插件 ≥ 0.25.0;对方的协作能力在 dsh-ptc-cordis-preset ≥ 0.14.0。

全局 PTC SDK:globalPtcSdk(默认关)

设置卡的「Global PTC SDK」控制 profile 的 root executor。默认关闭时不新增任何覆盖;开启后写入 tool-executor-native: { disabled: true } 与 tool-executor-ptc: { disabled: false },让未显式挂载 scoped native executor 的 agent 通过 run_code SDK 调用工具。SDK 内含本插件的 Git Bash,不发布独立 pwsh。 写入的是 profile patch,重启 DSH 后生效。

  • 不覆盖 preset-minimal:minimal 的 persona.complete: true 会在 prompt 组装时抹掉 PTC SDK, 得到没有可用 SDK 的 run_code。本开关不支持 minimal,也不替部署复述该 preset(避免冻结官方行集); 要在 minimal 使用 PTC,需自行维护对应 preset 覆盖,或改用 standard/ptc/cordis。
  • 只撤回自己写且未被改过的行:patch 旁的 .gitbash-global-ptc-ownership.json 记录本开关写入的行 id 与「数据 + YAML 注释」指纹。关闭开关、禁用或卸载插件时,只 lift receipt 认领且指纹仍一致的行; 用户手写同值行、后续改值/加配置/加注释的行一律保留。
  • 组合安全的逐行恢复:splice 前按 base 默认(native 开、PTC 关)与将保留的行模拟最终组合, 必须仍能证明恰好一个 enabled executor;一行被用户改过时,另一行只有在满足该不变量时才撤回, 结果日志为 lifted-partial。若删除会造成「双 executor」或「无 executor」(含 !!js 等无法判定的行), 对应行及其 receipt 都保留,日志返回 kept-user-choice 并明确要求手工处理。
  • 失败边界:receipt 损坏时拒绝猜测所有权;写入与回读使用宿主原子写和同一把 profile 文件锁, 校验失败回滚原 patch 字节。卸载恢复只记录失败日志,不阻断宿主关闭。
  • 卸载前先关开关:dispose 只在宿主运行、插件 fiber 被销毁时执行。若先停宿主再从命令行卸载/禁用插件, 插件代码不会加载,已写入的 executor 行会留在 patch。请在设置卡关闭 globalPtcSdk(该字段非 volatile, 会重挂插件并执行归还),确认日志后再停服;已停服时按 receipt 手工删除两行。

run_code 后端开关:pythonRuntime(默认关,v0.26.0)

dsh 有一个实验性 CPython 后端用于 PTC 的 run_code (@deepseek-ai/dsh-experimental-ptc-runtime-python)。它换掉的是 profile 级的 ptc-runtime 行(不是 preset 里的行),所以权威开关属于 dsh-ptc-cordis-preset:它那一行 Config 的布尔字段 pythonRuntime(默认 false),由它在 profile 组合期决定挂哪个后端。

本插件做的是第二张设置卡——同装 dsh-ptc-cordis-preset 时,本插件的设置页也会出现这一行, 通过 ctx.configForms.get('ptc-cordis') 读写同一个字段,任一侧改动两侧立即同步 (与 suppressPeerCordis 同构,方向相反)。对方没装、或版本低于 0.15.0(没有该字段)时, 这一行不显示。

  • 开关关闭(默认):run_code 用官方 Node/TypeScript 后端,组合与官方逐字节一致。
  • 开关开启:run_code 的语言、生成的 SDK 提示词与工具呈现整体切到 Python(由后端实例的 language/executionInstructions 决定,组合文本不变)。
  • 生效时机:重启 dsh 之后生效(后端行的替换在 profile 组合期求值);设置卡上的状态 两侧即时同步,只有后端切换需要重启。若开启后没有生效,原因见 dsh 启动日志。
  • "想开"与"真的开了"是两件事:后端不可用(包被移除 / 解释器低于 3.10 / Windows)时,开关的 意图仍可为"开",但组合照旧跑 Node —— 此时 workflow 侧不再被连带禁用(v0.26.1:互斥只看 实际生效的后端;v0.26.0 只看意图,会让用户白丢 workflow 能力),原因见 dsh 启动日志。

    关于卡片上的"后端不可用,当前仍为 Node"这行提示:本插件已实现该降级文案(21 语言),但它要等 对方把生效态投影进行 Config 快照后才会亮起 —— 浏览器只读得到那份快照,而生效态目前只在 宿主侧的能力服务里(见 AGENTS.md §4f)。在此之前:对方卡片显示"已开启 + 原因",本插件卡片 显示"已开启"(hint 指向宿主日志)。

  • 平台:该后端仅支持 POSIX——它在 Windows 上构造即抛错,所以 Windows 上开关显示为 禁用并注明原因,宿主侧也会拒绝写入。
  • 与 workflow 互斥:workflow-ptc 硬要求 TypeScript 后端(ctx.ptcRuntime.language === 'typescript'),官方 Python 组合同样把 workflow-ptc / tool-workflow 一起禁用。因此开启 期间本插件四个变体的这两行一律禁用(用户自己的 workflow 设置值保留,关掉后端后下次启动 恢复)——不这样做,选标准/创造模式会因一行构造失败而拒绝整棵 preset 挂载。
  • 依赖:python 运行时包由 dsh-ptc-cordis-preset 声明(optionalDependencies, 0.1.7-rc.2);本插件不声明该依赖、也不 insert 任何运行行(两个插件各插一行会造成 ptcRuntime 二次注册)。

POSIX 路径方言(v0.7.0 引入,受 posixPaths 开关门控)

Windows 上本插件让命令默认走自有 Git Bash 工具的同时,让模型看到的路径统一成 MSYS 盘根 POSIX 形式(/c/Users/...、/c/Program Files/...)。开关是 settings 命名空间 gitbash-shell 的布尔字段 posixPaths,默认开启(v0.10.0 起),可在 设置 → 插件 里本插件的「Git Bash 路径方言」卡片上随时切换;不修改任何 preset / 组合文件,标准/极简/ PTC/创造及用户自建模式一律覆盖。

开启时(仅 Win32),posixPaths 门控以下全部行为:

  • 提示词源头替换:组装期(system-prompt/assemble)把官方提示词 sections / contexts / variables 里的 Windows 绝对路径原位改写成 /c/...——不增删任何内容、不动工具 schema;
  • 一句话指示:经 systemPrompt.context(order 126)注入全局指示——shell 是 Git for Windows bash,路径用 MSYS 盘根,所有工具都直接接受这种写法——含 ~、/tmp、/dev/null、 /usr 等 bash 原生习惯(v0.17.0 起与 Git Bash 挂载表一致地解析);
  • 参数翻译:tools/execute 上把工具的路径参数(file_path / path / workdir,含 present 的嵌套 files[].path)由 /c/... 翻回 C:/... 交给 Node 文件工具;bash 的 command 字段 不动——那是 Git Bash 母语;bash 虚拟路径按 Git Bash 挂载表解析(v0.17.0):/tmp → 用户 TEMP、/dev/null → Windows NUL 空设备、~ → 家目录、/usr /bin /etc 等 → Git 安装根, 与 bash 写入/读取同一物理位置;glob 的绝对 pattern(/c/.../*.md)自动拆成 path + 相对 pattern(原先静默匹配空); /c/... 翻回 C:/... 交给 Node 文件工具;bash 的 command 字段不动——那是 Git Bash 母语;
  • 结果回流:成功结果里的路径元数据(read/read_image/write/edit 的 path、glob 的 paths[]、grep 的 matches[].path、present 的 files[].path)改写回 MSYS 形式,其中落在 用户 TEMP 下的路径回显为 /tmp/...(与 bash 的 $TMP 一致);文件内容与错误结果不动; grep 的 matches[].path)改写回 MSYS 形式;文件内容与错误结果不动;
  • 运行时事实:向官方 dsh-shell-env 注册表贡献 DSH_PATH_DIALECT=msys,模型可在执行时 核验(随开关实时生效);
  • 右侧栏文件链接(v0.31.0):对话里的文件链接带着 /c/... 拼写进入 dsh 原生右侧栏 (ui-sidebar-documentpreview),而宿主文件系统只认 Windows 盘符/UNC 拼写 —— /c/... 会被 解析成 <当前盘符>:\c\...,于是显示「文件不存在,可能已被移动或删除」。插件在右侧栏的唯一 入口(ctx.sidebarRight.openResource)上把地址还原成宿主拼写,~ / /tmp / /dev/null / /usr 等挂载点按与工具参数翻译同一张表处理;宿主事实经只读路由 GET /dsh-gitbash-shell/api/pathmap 提供,只有宿主自报 win32 时才改写 (macOS/Linux 宿主永不翻译,事实未到时也不翻译)。没有改动任何 dsh 源码,包装随插件卸载还原。

关闭后回到 dsh 原生行为:指示文本为空(组装期直接丢弃,零提示噪声),路径参数与结果元数据 都不再改写,文件工具收 Windows 路径。bash 始终是 Git Bash,不受此开关影响——它只决定 跨工具的路径方言。

显式工具

运行时开关 experimentalNative(默认 true): 设置 → 插件 → dsh-gitbash-shell →「实验原生执行 / fail-closed」。开启时 Windows 受限/未确定模式拒绝 Bash,提供可用的两个显式工具;关闭立即禁用两个工具的执行;已有 eager native 槽位保留当前会话的 schema,下一会话应用新工具面,并恢复明确标注 unconfined 的兼容 Bash(不执行 shell 文件写入限制)。修改作用于现有会话后续调用,无需重启,不终止已启动的任务。拒绝时用户也可在会话访问模式控件选择 danger-full-access;Agent 不得自行放宽权限。与路径方言及 codePaths 开关独立。

路径工具开关 pathTool(默认 true): 设置 → 插件 → dsh-gitbash-shell →「路径工具」。它只控制 gitbash_to_native_path:关闭后该工具从当前会话工具面注销并立即拒绝执行;gitbash_native、fail-closed 安全兜底与路径方言完全不受影响。修改作用于现有会话后续调用,无需重启;工具面对新会话或重启后的会话生效。与 experimentalNative 是叠加关系——总闸关闭时两者都不可用。

两个工具随 Windows 的自有 bash 工具挂入同一 agent-owned scope;不替换官方工具或 root provider,已有同名工具不覆盖。旧 Core 缺少公开 native executor/OutputCollector 能力时不 注册 native 工具,bash/path 不受影响;minimal 的持久终端不通过此补位通道。

gitbash_native 从 agent/created 起就同步注册稳定槽位:挂载期预解析宿主的 defineTool 与 native 能力,槽位与真实 executor 使用同一个 nativeToolDefinition() 构造器;真实模块 到达后只在同一条注册下换实现,不做 remove/add,所以每一步的工具名、描述与 schema 一致 (issue #38)。宿主没有 jobs 或预检失败时不宣告槽位,保留旧的晚挂载路径;experimentalNative 关闭、agent 销毁或工具面不再需要时注销。

  • gitbash_to_native_path:{ msys_path: 完整值 } → { native_path },复用共享且新鲜的 挂载事实;Windows/cwd-relative 值可原样,未知 MSYS 根/缺 mount、URL、空值/NUL 显式拒绝。 独立于自动方言与 codePaths 开关,不猜程序字符串用途、不授文件权限。
  • gitbash_native:description、绝对 executable: { kind: 'path', value }、 argv: [{ kind: 'literal'|'path', value }];literal 不经 MSYS 转换,path 明确转换并规范化。 可选绝对 typed cwd;不支持裸 command、model env、隐式脚本、.cmd/.bat 或 escalation。 已知解释器须显式 entrypoint: 'interpreter';这不是二进制鉴定,也不保证任意 cmd/非CRT parser quoting。
  • 每流 stdoutEncoding/stderrEncoding:utf8(默认)、gbk、utf16le、raw; errors: 'replace'(默认)或显式 strict。同流未知混合字节应选 raw,不能自动猜码。 解码/存储问题独立于真实 exitCode:命令已执行不等于输出可靠,不应因此重复副作用操作。
  • 现有 Jobs 提供后台与 timeout promotion(须有 controller);缺能力明确拒绝,不静默忽略参数。 没有 Jobs 时为前台 kill deadline。准备阶段也有取消/有界预算;owner dispose/kill 标为中止。
  • 产物存放在 host 自有临时目录,不是 model cwd。默认两流 raw+decoded 总磁盘上限8MiB, 适配器自有载荷预算16MiB;不是OS/RSS或跨任务硬限。完成产物保留便于读取,无自动purge承诺。 sourceComplete、管线 complete、tail lossy、artifact.complete 是不同事实,须联合读取。

Agent 路由指引:提示组装与工具说明会明确区分:shell语法/管道/重定向/POSIX脚本用 bash;原生.exe精确argv或已知逐流编码用可见的 gitbash_native;Node I/O需要完整MSYS 运行时路径时才用可见的 gitbash_to_native_path;真正cmdlet/服务/WMI用可见且开关允许的 pwsh。按实际工具面引导,不推荐未注册/隐藏的工具,重复组装随可见性更新、不堆叠。 权限拒绝必须停止,不能换工具/模式;解码失败不等于命令没执行,不能盲目重跑副作用。

PTC 模式只直调 run_code,里面使用已提供的 tools.gitbash_to_native_path / tools.gitbash_native。 run_code描述给出SDK选路规则,实际绑定各自说明适用场景;不编造未提供的绑定名称。 已验证实际Core普通/PTC提示与SDK文案送达;未运行真实LLM自主选择验收,不保证每次选择正确。 假设已取得完整 inputPath,直接 Node I/O 可写:

const resolved = await tools.gitbash_to_native_path({ msys_path: inputPath });
const fs = await import('node:fs/promises');
return await fs.readFile(resolved.native_path, 'utf8');

若程序含路径状路由/搜索数据,选择 codePaths: false 避免 legacy 自动误改;工具参数翻译仍在。

原生 Windows 程序与 run_code 的兼容边界

工具描述始终警示下面的参数、编码和安全限制;这些限制不随路径方言关闭而消失。 插件不会自动改写 command、全局关闭 MSYS 参数转换或猜测输出编码。

  • 斜杠开关:MSYS 在启动原生 Windows 程序时可能把 /all、/c 当路径。 本机已验证 ipconfig //all、cmd //c 或单命令 MSYS2_ARG_CONV_EXCL='/all' ipconfig /all 可保留开关。 排除值是前缀:排除 /c 也会影响真正的 /c/... 路径,该次原生调用应明确用 Windows drive-letter 路径。例如 schtasks /run /tn X 的 /run 会被改写成 C:/Program Files/Git/run;此时用逐命令 MSYS2_ARG_CONV_EXCL='*' schtasks /run /tn X, 或改用 gitbash_native 直接执行原生程序。不要把 MSYS2_ARG_CONV_EXCL='*' 写进全局环境。 cmd /c 被转换后可能 exit0 却没有执行所需命令,应检查预期效果而非只看退出码。
  • 输出编码:宿主按 UTF-8 解码;原生 Windows 程序可能输出 CP936/GBK 或其他代码页。 先使用程序自己的 UTF-8 输出选项,或在捕获前按已知编码显式转换字节,保持原退出状态。 LANG/LC_ALL 不保证改变原生程序的代码页。不要全流默认 GBK 或依替换字符数自动猜码: 同一 Bash 调用可能混合 UTF-8/GBK,已有乱码字符串也不能可靠恢复原字节。
  • run_code:codePaths 默认开,与 posixPaths/委托 gate 同时生效时,完整、可判定的 普通路径字面量按共享挂载表尽力转换,包括中文/组合字符/空格/# 文件名。 EOF 行注释不再阻止转换;tagged template(包括 String.raw)保持原样,避免破坏 raw/tag 语义。 插值模板、转义路径、不确定的正则/除法语法仍可能不改;不确定时整份 no-op。 直接调用 Node fs/path 时优先明确的 Windows drive-letter 或 cwd-relative 路径; 工具 path/file_path 字段仍走工具参数翻译。词法扫描不能识别路由、搜索数据或 shell command 的用途;此类字符串不要依赖自动重写,必要时关闭 codePaths(提示同步标为 OFF)。
  • 沙箱:参见上方安全章节。实验原生执行在 experimentalNative 开启时改为受限请求执行前拒绝,不是恢复了真实围栏;文件工具拒绝不授权 shell/native 重试。

与 dsh-better-sidebar 联动

装了 dsh-better-sidebar(v0.15.2+) 时,Windows 上本插件会把它打开的终端 shell 指向 Git Bash——UI 终端标签与模型侧 terminal_* 工具统一生效,不改对方一行代码、新开的终端即生效。通道随对方版本分两代:

  • v0.15.2–v0.19.1:通过对方的运行时 terminalShell 设置接管;启动时无条件写入 Git Bash,新终端立即生效。bundle patch 还会给对方的行补 config.shell(启动期解析,连 tab 标题也显示 bash;对方未安装时该行无害跳过)。
  • v0.21.0+:terminalShell 已从对方的行 Config 中删除(issue #47 在 0.32.1 上实测报错)。宿主半探测到字段不存在就不再写旧设置,也不再每次启动告警;客户端半在 Windows 且解析出已验证 Git Bash 时调用终端服务的 selectShell(),把当前浏览器的终端选择指向它。这是终端服务自己的浏览器本地偏好(与 Side card / 官方终端菜单是同一个),换浏览器或清 localStorage 后需要再选一次;adoptSidebar: false 仍然关闭这条接管。
  • 卸载本插件:v0.31 及更早会还原接管前的值;v0.32+ 的浏览器本地选择不会自动还原,可在终端菜单里重新选择。
  • 想关掉本联动 → 本插件 row 配置加 adoptSidebar: false(默认 true)。

许可

MIT © KannaKuron。参考与致敬:dsh-ptc-cordis-preset。

运行时兼容性与配置保留

  • run_code 的程序字面量转换和 JavaScript TEMP 前置代码只适用于当前会话实际使用的 TypeScript 运行时;Python 或未知运行时的源码保持原样,普通工具路径参数仍独立转换。
  • 自动补全持久终端的 shellPath 保留已有 shellArgs、超时、回滚行数等设置及注释,并与宿主配置编辑器使用同一个 profile 锁。
  • 同名工具的全局、祖先和当前 agent 所有权均被检查;隐藏的外部工具也不会被插件重新注册覆盖。
  • Bash 路由提示通过插件自有工具定义进入普通模式及 PTC SDK;PTC 程序指引通过独立提示段提供,不再修改宿主返回的 schema 副本。

Plugins associés