前言¶

在 Windows 上使用 DSH（DeepSeek Harness）时，模型往往要面对三套不同的命令语法：PowerShell 用 $env:NAME 和 C:\... 路径，Git Bash 走 POSIX 语法和 /d/WorkSpace 映射，WSL 则是 Linux 路径 /mnt/d/...。官方自带的 pwsh 工具只覆盖 PowerShell；若你日常开发混用 Git Bash 或 WSL，模型每次选错终端都会导致命令失败或路径解析错误。

下面介绍社区插件 dsh-bash-terminal：它在 DSH 中提供一个额外的 shell 工具，按你在 Web UI 里选择的默认终端执行命令，并附带交互式 terminal 工具用于跨轮保持会话状态。

这是什么¶

dsh-bash-terminal 由 MAXeaglet 维护，源码托管于 GitHub，许可证 MIT，当前 npm 版本 0.3.14，要求 Node.js >= 20。插件仅在 win32 平台注册工具。

定位可以概括为：一个 shell 工具，在 Windows 上统一执行 PowerShell、Git Bash、WSL 三种终端命令；终端类型由用户在设置页选定，模型无法通过工具参数自行切换。

三种后端如何执行¶

每次调用 shell 都会启动全新 shell，不保留 cwd、变量或别名。需要切换工作目录时，应传 workdir 参数，而不是在命令里 cd。

核心功能¶

用户选定终端，模型不可更改¶

Web UI 设置页（设置 → 通用）提供「默认终端」下拉，可选 PowerShell、Git Bash、WSL。shell 工具永远只使用该设置，不暴露终端参数给模型。设置通过 DSH settings 系统持久化到 settings.yaml。

不占用官方 pwsh 工具¶

DSH 自带的沙箱化 pwsh 工具保持原样可用；本插件的 shell 是额外的多终端入口。

进程管理与后台任务¶

插件通过共享的 ctx.subprocess seam 派生进程，进程树终止（Windows taskkill /T）、SIGTERM→grace→SIGKILL、输出 spill 文件等行为与官方 dsh-tool-bash / dsh-tool-pwsh 一致。后台任务注册进通用 jobs registry，支持 run_in_background、job_output、job_kill。

交互式 terminal 工具¶

terminal 工具在 PTY 接缝上提供持久交互会话，会话状态跨调用保持（cwd、变量、别名），适合 REPL、ssh、交互式 CLI：

• action: open 启动会话，返回 sessionId；WSL 可传 distro 指定发行版
• action: send 写入输入并读新输出；action: read 只读不写
• action: signal 向前台进程组发信号（SIGINT 映射为 Ctrl+C）
• action: close 终止会话

send 会等待输出稳定（300ms 静默，上限 5s）后返回完整回复；输出超 1MB 时报 truncated 提示。输入用 \n（或 \r）结尾表示回车。

沙箱对接¶

shell 走 DSH 官方沙箱接缝（ctx.sandboxPolicy + ctx.sandbox）：

• danger-full-access 会话直接执行，不包装
• PowerShell 后端经 ctx.sandbox.confine 包装 argv，fail-closed：受限模式但无可用后端时抛 SandboxUnavailableError
• Git Bash 不经沙箱包装（DSH Windows ACL 受限令牌与 Cygwin/MSYS2 不兼容），结果报告 enforcement: gitbash-unconfined
• WSL 不经沙箱包装（独立 Linux VM 隔离），结果报告 enforcement: wsl-isolation
• 受限模式下被拒绝时，模型可凭 sandbox_permissions + justification 发起一次升级，经 ctx.approval 用户审批

安装与启用¶

插件带官方 dsh.bundle manifest（包内 cordis.patch.yml），profile 列出本包后 DSH 自动应用挂载。

标准安装步骤如下：

# 1. 安装插件包
npm install -g dsh-bash-terminal
dsh plugin --profile web add dsh-bash-terminal   # 自动加进 profile 的 bundles 并应用 patch

# 2. patch DSH 设置白名单（DSH 限制，见下方说明）
powershell -ExecutionPolicy Bypass -File install.ps1 install

# 3. 重启 dsh web

DSH 的 api-gateway 对 Web 设置客户端暴露的 settings namespace 有硬编码白名单，第三方插件设置默认会被 settings-not-exposed 拒绝。install.ps1 会自动 patch 白名单（加入 bash-terminal 并备份原文件）。升级 DSH 后需重新运行 install.ps1；卸载时 install.ps1 uninstall 会还原。

验证组合树（无需重启）：

node "$env:APPDATA\nvm\v24.16.0\node_modules\@deepseek-ai\dsh\lib\bin.js" --profile web --dump-config | Select-String dsh-bash-terminal

典型用法¶

在 Web UI 设置默认终端¶

打开设置（齿轮）→ 通用 →「默认终端」下拉，选择 PowerShell、Git Bash 或 WSL。改动即时生效并持久化。

shell 一次性命令¶

模型看到 shell 工具后，执行命令时自动使用你选择的终端：

shell(command: "git status", description: "查看 git 状态")

默认终端为 WSL 时可指定发行版：

shell(command: "ls -la /mnt/d/WorkSpace", description: "列出目录")

默认终端为 PowerShell 时：

shell(command: "Get-Process node", description: "查看 node 进程")

terminal 跨轮保持状态¶

terminal(action: "open")                    # 记下 sessionId
terminal(action: "send", sessionId, input: "cd /d/project\n")
terminal(action: "send", sessionId, input: "npm run dev\n")
terminal(action: "close", sessionId)

其他操作：terminal(action: "list") 查看活动会话；terminal(action: "signal", sessionId, signal: "SIGINT") 中断运行中的程序；沙箱拒绝后可用 shell(command: ..., sandbox_permissions: "workspace-write", justification: "...") 升级权限。

配置项¶

Web UI 设置（推荐）：设置 → 通用 →「默认终端」。

插件 config 默认值：

适用场景与注意¶

适合谁：在 Windows 上使用 DSH，且日常开发混用 PowerShell、Git Bash、WSL 的开发者；需要模型按你习惯的终端语法执行命令，而不希望模型自行选择后端。

安全说明：shell 是额外的多终端入口，不享受官方 pwsh 工具的 ConstrainedLanguage 限制。Git Bash 在受限模式下不经沙箱包装，与 dsh 进程同权限；WSL 依赖独立 VM 隔离。需要受沙箱保护的 PowerShell 时请继续使用官方 pwsh 工具。DSH 的文件操作工具（read/write/edit）仍受文件沙箱约束。仅在你信任的会话中使用；安装前应检查源码与许可证。

交互终端已知限制（ConPTY）：

• PowerShell 5.1 无法在 ConPTY 启动交互会话，需安装 PowerShell 7；一次性命令不受影响
• wsl.exe 交互模式在 ConPTY 下可能偶发 RPC 错误；一次性 wsl -e bash -lc ... 正常
• Windows 上 node-pty 的 signal 仅 SIGINT 映射为 Ctrl+C，其他信号退化为终止会话
• Git Bash 交互会话正常

其他限制：

• WSL 后台进程在超时或中断后可能在发行版内短暂残留
• Git Bash 是 msys2 环境，与 WSL Linux 行为存在差异（路径映射、包可用性）
• 本插件仅在 Windows 注册工具

卸载¶

推荐运行：

powershell -ExecutionPolicy Bypass -File install.ps1 uninstall

它会删除 junction、恢复设置白名单、清理遗留挂载块，并从 dsh.profile.bundles 移除 dsh-bash-terminal。之后重启 dsh web。

手动卸载时，除删除 node_modules\dsh-bash-terminal，还需从 profile package.json 的 dsh.profile.bundles 中移除 dsh-bash-terminal。

结尾¶

dsh-bash-terminal 把 Windows 上三套常用终端收敛到一个 shell 工具：你在设置页选定默认终端，模型按该后端执行命令；配合 terminal 工具可跨轮保持交互会话。它不替代官方 pwsh，而是为混用多终端环境的开发者提供额外入口。

• 社区目录页：https://www.skillhub.cn/plugins/MAXeaglet/dsh-bash-terminal
• GitHub 仓库：https://github.com/MAXeaglet/dsh-bash-terminal