MAXeaglet/dsh-bash-terminal

🌐 English · 社区交流：LINUX DO · GitHub

DSH（DeepSeek Harness）插件：一个 shell 工具，在 Windows 上统一执行 PowerShell / Git Bash / WSL 三种终端命令。

后端	实际执行	语法 / 路径	环境变量
powershell（默认）	pwsh -NoLogo -NoProfile -NonInteractive -Command <cmd>	PowerShell；C:\...	$env:NAME
gitbash	Git for Windows bash -lc <cmd>	POSIX；/d/WorkSpace；PATH 含 /usr/bin、/mingw64/bin	$NAME
wsl	wsl [-d <distro>] -e bash -lc <cmd>	Linux；/mnt/d/...	$NAME（经 WSLENV）

每次调用都启动全新 shell：不保留状态（cwd / 变量 / 别名）——请传 workdir 而不是用 cd。

设计要点

• 终端由用户决定，AI 无法更改：Web UI 设置页（设置 → 通用）出现"默认终端"下拉（PowerShell / Git Bash / WSL）；shell 工具永远只使用该设置，不暴露终端参数给模型。设置通过 DSH settings 系统持久化（settings.yaml）。
• 不占用 ctx.shell 能力接缝：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。
• 工具参数 shell 是枚举（UI 自动渲染为下拉），模型每次调用自行选择终端。

安装（web profile）

标准安装（npm 发布后，官方 bundle 机制）

插件带官方 dsh.bundle manifest（包内 cordis.patch.yml），profile 列出本包时 DSH 自动应用挂载，无需手改 profile 配置：

# 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

已用临时 profile 实测：bundles: [dsh-bash-terminal] → dump-config 自动出现 tool-bash-terminal entry。

本地开发安装（junction 直连，改源码即时生效）

1. 链接插件包到 profile 的 node_modules（junction，改源码即时生效）

$profile = "$env:USERPROFILE.dsh\profiles\web" New-Item -ItemType Junction -Path "$profile\node_modules\dsh-bash-terminal" -Target "D:\WorkSpace\projects\dsh-bash-terminal" | Out-Null

2. 让插件能解析 @deepseek-ai/* 依赖（junction 到 profile 的依赖树）

New-Item -ItemType Junction -Path "D:\WorkSpace\projects\dsh-bash-terminal\node_modules@deepseek-ai" -Target "$profile..\node_modules@deepseek-ai" | Out-Null

3. 在 cordis.patch.yml 追加挂载行（见下方 patch 片段）

4. （仅修改前端源码后）重新打包 client bundle:

cd D:\WorkSpace\projects\dsh-bash-terminal && node scripts/build-client.mjs

5. 让设置 UI 接受本插件的设置写入（DSH 限制，见下方说明）

6. 重启 dsh web

> **DSH 设置 UI 白名单限制**：DSH 的 api-gateway（dsh-host-apiproxy）对
> Web 设置客户端暴露的 settings namespace 有**硬编码白名单**（第三方插件
> 的设置默认会被 `settings-not-exposed` 拒绝，UI 里改了不生效）。
> install.ps1 会自动 patch 该白名单（加入 `bash-terminal`，先备份原文件）。
> **升级 DSH 后需重新运行 install.ps1** 恢复 patch。卸载时 install.ps1 会还原。

`cordis.patch.yml` 追加：

```yaml
- insert:
    - id: tool-bash-terminal
      name: 'dsh-bash-terminal'

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

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 工具后，执行命令时自动使用你选择的终端（工具不暴露终端参数，模型无法更改你的选择）：

• 默认终端 = Git Bash 时：shell(command: "git status") 走 Git Bash
• 默认终端 = WSL 时：shell(command: "ls -la /mnt/d/WorkSpace") 走 WSL；传 distro: "Ubuntu" 可指定发行版
• 默认终端 = PowerShell 时：shell(command: "Get-Process node") 走 PowerShell

模型使用示例

• 一次性命令（默认终端）：shell(command: "git status", description: "查看 git 状态")
• 跨轮保持状态（交互式）：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: "signal", sessionId, signal: "SIGINT")
• 查看活动会话：terminal(action: "list")
• 沙箱拒绝后升级：shell(command: ..., sandbox_permissions: "workspace-write", justification: "...")

配置

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

插件 row 的 config（覆盖默认，作为设置的 composition 基准）：

键	默认	说明
defaultShell	powershell	设置未覆盖时的后端
timeoutMs	120000	默认超时
maxTimeoutMs	600000	调用方 timeoutMs 上限
pwshPath	自动探测	固定 pwsh.exe 路径
gitBashPath	自动探测	固定 git bash.exe 路径
wslPath	自动探测	固定 wsl.exe 路径

发布（npm）

npm 账号已启用 2FA 发布验证，需一次性验证码：

cd D:\WorkSpace\projects\dsh-bash-terminal
npm publish --otp <验证码>   # 验证码来自你的认证器

发布前先 npm pack --dry-run 检查内容、跑 node scripts/build-client.mjs 重建 client bundle。

卸载

Remove-Item "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-bash-terminal" -Force
# 并从 cordis.patch.yml 删掉 insert 块，重启 dsh web

交互式终端（terminal 工具）

terminal 工具在官方 PTY 接缝（ctx.subprocess.spawnTerminal，node-pty）上提供持久交互会话：

• action: open 启动一个真实终端会话（按你设置的默认终端；wsl 可传 distro），返回 sessionId
• action: send 写入输入并读新输出；action: read 只读不写；action: signal 向前台进程组发信号（SIGINT = Ctrl+C）
• action: close 终止会话
• 会话状态跨调用保持（cwd / 变量 / 别名），适合 REPL、ssh、交互式 CLI
• send 会等待输出稳定（300ms 静默，上限 5s）返回完整回复；输出超 1MB 时报 truncated 提示
• 输入用 \\n（或 \r）结尾表示回车

沙箱（官方机制对接）

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

• 每次调用解析当前沙箱策略；danger-full-access 会话直接执行（不包装）。
• PowerShell / Git Bash 后端经 ctx.sandbox.confine 包装 argv —— 与官方 executor 相同的 fail-closed 语义：请求受限模式但无可用后端时抛 SandboxUnavailableError，拒绝裸跑。
• WSL 后端不包装：WSL 独立 Linux 虚拟机本身就是隔离（结果报告 enforcement: wsl-isolation）。
• 受限模式下被沙箱拒绝时，结果携带官方标记 [sandbox: file access denied under <mode> mode] 与同轮升级提示；模型可凭 sandbox_permissions + justification 发起一次升级（经 ctx.approval 用户审批），与官方 bash/pwsh 工具完全一致。
• 注意：DSH 的 Windows ACL 沙箱 launcher（node-addon-landlock-run-win32-x64）当前尚未在 npm 发布，本机沙箱后端暂不可用；架构已就绪，DSH 发布后自动生效。

⚠️ 安全说明

shell 工具的命令在 DSH 沙箱之外运行，与 dsh 进程同权限（等同完整访问的命令执行）， 不享受 pwsh 工具的 ConstrainedLanguage 限制。DSH 的文件操作工具（read/write/edit）仍受文件沙箱约束。 仅在你信任的会话中使用；需要受沙箱保护的 PowerShell 时请继续使用官方 pwsh 工具。

交互终端已知限制（ConPTY）

• PowerShell 5.1 无法在 ConPTY 启动（0x8009001d）—— 交互式 PowerShell 需要安装 PowerShell 7（一次性命令不受影响）。
• wsl.exe 交互模式在 ConPTY 下可能触发 WSL 服务 RPC 错误（0x8007072c，偶发）—— 一次性 wsl -e bash -lc ... 命令正常；交互会话建议直接用 Windows Terminal / WSL 终端，或重试。
• Git Bash 交互会话完全正常。

已知限制

• WSL 后台进程在超时/中断后可能在发行版内短暂残留（WSL 实例在最后一个进程退出后自动关闭）。
• Git Bash 是 msys2 环境，与 WSL 的 Linux 行为存在差异（路径映射、包可用性）。
• 本插件仅在 win32 平台注册工具。

测试

cd D:\WorkSpace\projects\dsh-bash-terminal
node test\unit.mjs    # 纯函数单测（路径解析/argv/env/渲染/校验）
node test\apply.mjs   # apply + execute mock 集成测试（用户设置决定后端、workdir、WSLENV、超时）
node test\client.mjs  # client 插件逻辑测试（slot 注册/初始快照/setShell 写透）
node scripts/build-client.mjs  # 打包前端设置项 bundle → dist/client.js