@omdp/dsh-gitbash-win

Overview

DSH (DeepSeek Harness) 全局 Git Bash 工具插件（Windows）。

注册一个全局 gitbash 工具：通过 Git for Windows 的 bash.exe（bash -c）执行命令， 让模型在 Windows 上获得真正的 POSIX shell —— 无需 WSL、无需 node-pty、轻量无负担。

Windows 上推荐使用 Git Bash：提供标准的 grep/sed/awk/管道/通配符等 POSIX 环境， 模型在这种环境下训练效果更好（对齐 Unix 语义，可迁移到 Linux/macOS）。

适合：Windows 用户想让 DSH 模型用真正的 POSIX shell（而非 PowerShell）， 且不想要 WSL / node-pty 的重量级方案。

Quick start

# 1. 安装（npm）
dsh plugin --profile web add @omdp/dsh-gitbash-win
#    如果 dsh 不在 PATH（例如用 npx 装的 dsh），改用：
#    npx @deepseek-ai/dsh plugin --profile web add @omdp/dsh-gitbash-win

# 2. 确认 Git for Windows 已装（bash.exe 存在，插件自动探测）
#    C:\Program Files\Git\bin\bash.exe

# 3. 重启 dsh web
# 4. 在任意会话里，模型即可调用 gitbash 工具

最小可复现：安装 + 重启后，让模型执行 gitbash(command: "echo hello from git bash", description: "Test git bash") → 应返回 hello from git bash。

特性

• 全局可用：注册为 gitbash 工具，与 pwsh 平级，任何会话/预设都能用（不需要选预设）
• 轻量：无 node-pty、无 WSL、无额外运行时依赖（只复用 DSH 官方 seam 包）
• 沙箱感知：受限模式走 sandbox provider 的 confine；被拒时给出升级提示（danger-full-access）
• 超时控制：SIGTERM → grace → SIGKILL 进程树终止
• 输出截断：溢出时写 spill 文件，不丢输出
• 后台任务：run_in_background / job_output / job_kill
• 卡片 UI：Web UI 里 gitbash 调用显示专属终端卡片

安装

dsh plugin --profile web add @omdp/dsh-gitbash-win

安装命令前提：上面的 dsh plugin add 需要 dsh 已在 PATH（即全局安装过 npm i -g @deepseek-ai/dsh）。 如果你是按官方文档用 npx 运行 dsh（没有全局 dsh 命令），上面这行会报 command not found: dsh。 改用下面这行等价命令即可（不要求 dsh 在 PATH）：

npx @deepseek-ai/dsh plugin --profile web add @omdp/dsh-gitbash-win

然后重启 dsh web。插件通过 dsh.bundle（包内 cordis.patch.yml）自动挂载， 无需手动改 profile 配置。

前置依赖：Git for Windows（提供 bash.exe）。安装后确认以下任一路径存在 （插件自动探测，也可用 GIT_BASH 环境变量指定）：

• C:\Program Files\Git\bin\bash.exe
• C:\Program Files\Git\usr\bin\bash.exe

卸载

# 1. 从依赖移除
dsh plugin --profile web remove @omdp/dsh-gitbash-win

# 2. 若 bundles 里还有残留，手动从 profiles/web/package.json 的 dsh.profile.bundles 删掉

禁用（临时）：从 dsh.profile.bundles 移除后重启（无需删包）， 或在 cordis.patch.yml 加 - id: tool-gitbash\n disabled: true。

使用

模型获得 gitbash 工具后，直接传命令即可：

gitbash(command: "git status", description: "Show working tree status")

参数：

| 参数 | 说明 | | --- | --- | | command | 要执行的 Git Bash 命令（bash -c） | | description | 命令用途的一句话描述（界面展示用） | | timeoutMs | 超时（默认 120s，上限 600s） | | workdir | 工作目录，默认会话目录 | | run_in_background | 后台运行，立即返回 jobId | | sandbox_permissions / justification | 沙箱升级（配置了沙箱时可用） |

路径同时支持 Windows 原生形式（C:\...）与 Git Bash 形式（/c/...）。

为什么不用官方 tool-bash？

DSH 官方 code/standard 预设里，tool-bash 带有 disabled: !!js process.platform === 'win32' —— 官方在 Windows 上默认禁用了 bash （因为 Git Bash 不在标准 PATH、PTY 不支持）。本插件把 bash 映射到 Git for Windows， 并去掉这个平台禁用，让 Windows 上真正能用 Git Bash。

配置

可选：GIT_BASH 环境变量指向自定义的 bash.exe（默认自动探测常见安装路径）。

Troubleshooting

| 问题 | 原因 / 解决 | |---|---| | Git Bash not found | 未装 Git for Windows，或 bash.exe 不在常见路径。装 Git 或设 GIT_BASH | | workspace-write 下报 CreateFileMapping / fatal error | 已知限制：MSYS 运行时无法在 Windows ACL 受限令牌沙箱内启动（官方 dsh-gitbash-preset 同）。用 sandbox_permissions: "danger-full-access" 升级，或把会话切到完全访问 | | 之前报 windows-acl-run: --temp is not an existing directory | DSH 上游 bug（Discussion #758）：手动重建同名目录即可恢复 | | 工具不出现在模型工具列表 | bundle 未挂载：确认 dsh.profile.bundles 含 @omdp/dsh-gitbash-win，重启 dsh | | 命令无输出 / 被截断 | 输出超 64KB 会截断并写 spill 文件，看完整输出需读 spill 路径 |

日志：DSH 启动的 stderr（profile 下 dsh-boot.err）。回滚：卸载/禁用（见上）。

Permissions & data

| 数据 | 访问方式 | 说明 | |---|---|---| | bash.exe（Git for Windows） | 执行 | 每次调用 bash -c <command> | | 工作区 / 指定 workdir | 读写（取决于命令） | 命令在沙箱策略下运行（受限或全权限） | | 环境变量 | 读取 | $DSH_* 环境事实 + 继承的环境 | | 沙箱 / 审批 | 调用 DSH 服务 | ctx.sandbox / ctx.sandboxPolicy / approval |

不收集：无遥测、无外部网络请求（gitbash 只执行本地命令，不联网）。 注意：命令完全按模型意图执行——沙箱/审批是唯一防线；danger-full-access 下命令拥有完整权限。

Development

# 本地开发：link: 安装，改源码 → 重启 dsh 即生效
cd ~/.dsh/profiles/web
pnpm add "link:D:/WorkSpace/omdp/dsh-gitbash-win"

# 语法检查
node --check D:/WorkSpace/omdp/dsh-gitbash-win/lib/index.js
node --check D:/WorkSpace/omdp/dsh-gitbash-win/lib/client.js

# 发布（GitHub Actions 自动发包）
# 改 dsh-gitbash-win/package.json 的 version → git tag vX.Y.Z → push

结构：lib/index.js（host，动态加载 @deepseek-ai/*）/ lib/client.js（toolview 卡片）/ cordis.patch.yml。 贡献：PR 到 https://github.com/XJungit/omdp。

兼容性

架构：为抗崩溃而设计

本插件采用三层保护，确保 DSH 更新时绝不导致 DSH 崩溃：

| 层 | 做法 | 效果 | |---|---|---| | 顶层零依赖 | 模块顶层只 import Node 内置模块（node:*），不静态引用任何 @deepseek-ai/* | DSH 怎么更新都不会在加载阶段失败 | | 动态加载依赖 | 所有 @deepseek-ai/* 在 apply() 内 await import() 按序加载 | 依赖解析失败时干净报错，插件不加载，DSH 照常运行 | | 失败隔离 | 每个依赖加载都 try/catch，失败仅影响 gitbash 工具 | 单个 API 变化不会拖垮 DSH 或影响其他插件 |

依赖的 DSH 接口

运行时会动态使用以下 @deepseek-ai/* 包（均为 DSH 内部 API，版本锁定 ^0.1.0-rc.8）：

| 包 | 用到的 API | |---|---| | dsh-tools | defineTool / TOOL_ABORTED（工具定义） | | dsh-sandbox | confine / approveEscalation / ESCALATION_TARGETS（沙箱与权限） | | dsh-llm | HarnessError（错误类型） | | dsh-shell | parseExitStatus（退出码解析） | | dsh-timeout | clampTimeout / deadline / timeoutOf（超时） |

另外通过 ctx 使用：ctx.tools.register、ctx.subprocess.spawn、ctx.shellEnv.collect、ctx.systemPrompt.section、ctx.get('sandbox') / ctx.get('sandboxPolicy') / ctx.get('jobs')。

兼容性结论

| 场景 | 是否会导致崩溃 | |---|---| | DSH 小更新 / 补丁（rc.6 → rc.8） | ✅ 不会崩（API 逐项核对通过，且失败隔离兜底） | | DSH 大版本（0.1 → 0.2） | ✅ DSH 不崩；gitbash 工具可能需适配新 API（更新插件版本即可） | | @deepseek-ai/* 解析失败 | ✅ 干净失败，插件不加载，DSH 正常启动 | | 其他插件（connector / vision-bridge / undo） | ✅ 互不影响（各自独立加载） |

一句话：实现把"崩溃"降级为"功能不可用"——DSH 永远不会因为本插件崩溃（硬保证），最坏情况只是 gitbash 工具需要跟随 DSH 版本更新适配。已知的 Windows 沙箱问题（dsh-sandbox-windows-acl 的 koffi bug）为 DSH 上游问题，与本插件无关；沙箱修复后本插件自动受益（动态跟随 ctx.sandbox 服务）。

最后验证：DSH 0.1.0-rc.8（2026-08-20，全部依赖 API 已逐项核对 defineTool / TOOL_ABORTED / confine / approveEscalation / ESCALATION_TARGETS / HarnessError / parseExitStatus / clampTimeout / deadline / timeoutOf 均存在且签名匹配）。

License & security

MIT License。安全问题请通过 GitHub Issues 私密报告（https://github.com/XJungit/omdp/issues）。 本插件执行模型提供的任意命令——请确保沙箱/审批策略已配置（尤其 danger-full-access 下）。