KannaKuron/dsh-gitbash-shell

dsh-gitbash-shell

简体中文 | 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 可写：