dsh-gitbash-preset

一句话定位

为 DSH 极简模式提供 Windows 可用的变体：把 bash 工具的调用从无法在 Windows 启动的持久 PTY 改走 Git for Windows 自带的 bash（MSYS），解决官方极简模式在 Windows 上跑不起来的问题。

核心能力

启动时把打包的「极简模式 (Git Bash)」预设复制到用户预设根目录，已存在则跳过，避免覆盖用户已有文件
自动定位 Git for Windows 的 bash 路径：优先看 GIT_BASH 环境变量，其次扫描常见安装目录和 PATH，且会跳过 Windows 自带的 WSL 启动器避免误用
把 bash 命令以 bash -c <command> 形式每次新启一个 shell 执行，统一处理超时、后台、输出截断与错误诊断
通过沙箱策略门控保证安全：非「完全访问」沙箱下拒绝执行，并提示用 sandbox_permissions: "danger-full-access" 做单次升级
保留极简模式的 persona 和 str_replace_editor 工具表面，使用体验与官方极简模式一致

技术实现

语言: JavaScript（ESM，原生 Node.js）
关键依赖: 仅使用 Node 内置模块（node:fs / node:path / node:os / node:url）；预设由宿主已有的 @deepseek-ai/dsh-persona / dsh-tool-bash / dsh-fs-local / dsh-tool-str-replace-editor 组成
架构模式: 通过 cordis.patch.yml 把插件行插入 web profile，启动时 lib/index.js 的 apply(ctx, config) 把预设文件复制到用户目录；预设内部用 entry-local realm 注册 shell 服务和 bash / str_replace_editor 两个工具
入口文件: lib/index.js（安装器）+ agent-presets/minimal-gitbash/agent.cordis.yml（预设组合）+ agent-presets/minimal-gitbash/gitbash-executor.mjs（bash 执行器）

适用场景

Windows 用户在 DSH Web 端使用「极简模式」时，原本的持久 bash 会因 PTY 限制和找不到 bash 失败，本插件提供一个一键可装的替代预设，让 Windows 也能像 macOS/Linux 一样在极简模式下使用 bash 工具。

前置依赖与兼容性

依赖	最低版本	说明
DSH	未声明	通过 `@deepseek-ai/dsh-*` 宿主包运行；未在 manifest 中声明版本范围
Node.js	>=20	来自 `package.json` 的 `engines.node`
操作系统	Windows	预设用 `process.platform !== 'win32'` 直接禁用，仅在 Windows 启用；执行器在非 Windows 上退化为 `bash` 但预设本身不会激活
Git for Windows	推荐	未安装时执行器会兜底走 PATH 或裸 `bash` 名，可能无法启动
原生模块	无	仅使用 Node 内置模块，无任何 npm 原生依赖

安装方式

dsh plugin --profile web add github:liceses/dsh-gitbash-preset

配置项

配置	类型	说明	默认值
`shellPath`	字符串	显式指定 bash.exe 路径，留空则自动探测（`GIT_BASH` → 常见安装目录 → PATH）	自动探测
`timeoutMs`	毫秒	单次命令默认超时时间	120000
`maxTimeoutMs`	毫秒	单次命令允许的最大超时时间	600000
`maxOutputBytes`	字节	单个流（stdout/stderr）保留的最大字节数，超出写入溢出文件	64000
`maxSpillBytes`	字节	溢出文件总大小上限	67108864 (64MB)
`graceMs`	毫秒	终止进程时从 SIGTERM 到 SIGKILL 的宽限时间	3000
`force`	布尔	插件级配置：已存在预设时是否用包内文件覆盖	false

常见问题

Q: 这个插件是给谁用的？

A: 主要是 Windows 上使用 DSH 极简模式的普通用户。官方极简模式在 Windows 上跑不起来，本插件提供一个可替代的预设变体。

Q: macOS 或 Linux 需要装吗？

A: 不需要。预设内部用 process.platform !== 'win32' 直接禁用，在其他系统上即使装了也不会激活，继续用官方极简模式即可。

Q: 装完之后需要做什么？

A: 重启 DSH 让插件把预设写入用户目录（约 ~/.dsh/.agent-presets/minimal-gitbash/），然后在 Web 界面新建会话时选择「极简模式 (Git Bash)」即可。

Q: 会话沙箱是 workspace-write 时能用吗？

A: 不能直接用。bash 工具会因为沙箱限制拒绝执行；要么把会话切到「完全访问」沙箱模式，要么让模型按错误提示用 sandbox_permissions: "danger-full-access" 加 justification 做单次升级。

Q: 它会改我电脑上已有的 bash 工具吗？

A: 不会。它只在选用了「极简模式 (Git Bash)」的会话作用域内替换 shell 提供者，其他会话与系统 bash 完全不受影响。

Q: 如何强制覆盖已经装好的预设？

A: 在插件配置里把 force 设为 true，插件会用包内预设文件覆盖用户目录下的版本（不会删除你额外放进去的文件）。

Q: 怎么卸载？

A: 用 dsh plugin --profile web remove 移除插件，然后手动删除用户目录下的 minimal-gitbash 文件夹即可。

Q: 它和官方极简模式有什么区别？

A: persona、str_replace_editor 工具表面完全一致；唯一区别是 bash 工具每次调用都新启一个 shell，不保留 cd / export 状态，这是 Windows 上无法用持久 PTY 之后的折中设计。

上手难度

入门 — 装好插件、重启 DSH、选预设即可使用，不需要写代码或改配置；只有想固定 bash 路径或调整超时的高级用户才需要看 agent.cordis.yml。

已知问题与限制

会话沙箱为 workspace-write 或更严格时，Git Bash 无法在 Windows 受限令牌沙箱内启动（MSYS 运行时无法创建 signal pipe），需切换到「完全访问」或单次升级 — 这是沙箱边界，插件不绕过
bash 调用每次新启一个 shell，不保留 cd / export 等会话状态（与官方极简模式的持久 PTY shell 不同），需要模型在每条命令里带全路径或自行维护工作目录
仅在 Windows 平台启用预设；macOS / Linux 上即使安装也会被 agent.cordis.yml 中的 disabled 条件禁用
预设禁用后台任务（enableRunInBackground: false），长任务需要通过单次超时来管理
极端情况下，PATH 中同时存在 Git Bash 与 WSL 启动器（System32 下的 bash.exe）时执行器会主动跳过 WSL 启动器目录，避免拿到一个不存在的发行版的 stub

环节	说明
插件行	`cordis.patch.yml` 在 web profile 组合中插入 `dsh-gitbash-preset`，启动时安装预设文件
预设组合	`agent.cordis.yml` 中 `gitbash-shell` 组以 entry-local realm 提供 `shell` 服务，`tool-bash` 注册模型工具
执行器	`gitbash-executor.mjs` 通过 host 的 `subprocess` 服务执行 `bash -c`，处理超时、后台、输出截断与错误诊断
沙箱门控	`run`/`start` 校验策略：仅 `danger-full-access`（或部署无沙箱）放行，否则抛出带指引的错误