dsh-bash-terminal

一句话定位

DSH 的 Windows 插件：把 PowerShell、Git Bash、WSL 三种终端统一成一个 shell 工具，默认终端由用户在 Web UI 设置页决定，AI 模型无法绕过用户选择。再附送一个基于 PTY 的交互式 terminal 工具。

核心能力

• 在 Web UI「设置 → 通用」中选择默认终端（PowerShell / Git Bash / WSL），shell 工具始终按这个选择执行
• 提供 shell 工具，每次调用启动全新 shell 跑命令，遵守 DSH 沙箱策略（受限模式 fail-closed）
• 提供 terminal 工具，开启 PTY 交互会话（cwd / 变量 / 别名跨调用保持），适合 REPL / ssh / 交互式 CLI
• 支持后台任务：长命令可设为 run_in_background，得到 job id 后用 job_output / job_kill 收集输出或终止
• 沙箱拒绝时给出官方 [sandbox: file access denied] 标记，并允许同轮用 sandbox_permissions + justification 升级一次

技术实现

• 语言: JavaScript（ESM，主包）+ React JSX（客户端）
• 关键依赖: @deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-sandbox、node-pty、@deepseek-ai/dsh-shell
• 架构模式: Cordis 插件（通过 cordis.patch.yml 在 profile 加载时插入 tool-bash-terminal 节点），同时注册 host 端（shell + terminal 工具）和 client 端（设置页的"默认终端"下拉）
• 入口文件: lib/index.js（host 端）、src/client.jsx → dist/client.js（client 端）

适用场景

Windows 用户希望模型在 shell 工具里跑命令时用 Git Bash 或 WSL，而不是 PowerShell；或者需要保留会话状态跑交互式命令（REPL、ssh、长进程）。也适合经常在 PowerShell、Git Bash、WSL 之间切换、希望通过一个下拉统一管理的人。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:MAXeaglet/dsh-bash-terminal

首次安装后还需 powershell -ExecutionPolicy Bypass -File install.ps1 install 给 DSH 的 settings UI 白名单打补丁（加入 bash-terminal namespace），否则设置页改了不生效。升级 DSH 后需重跑此脚本。

配置项

用户在 Web UI 设置里改的"默认终端"会持久化到 settings.yaml，优先级高于这里的 defaultShell。

常见问题

Q: AI 模型能自己切换 PowerShell / Git Bash / WSL 吗？

A: 不能。终端选择由你在 Web UI「设置 → 通用 → 默认终端」下拉里改并持久化；shell 工具不暴露终端参数给模型。每次调用都按当前设置执行，模型看不到其他选项。

Q: 跟 DSH 自带的 pwsh 工具会冲突吗？

A: 不会。插件特意避开 ctx.shell 接缝，官方沙箱化的 pwsh 工具保持原样可用；本插件注册的是另一个名为 shell 的工具，是额外的多终端入口。

Q: 可以在 macOS 或 Linux 上装吗？

A: 可以装，但不会生效。apply 在 process.platform !== "win32" 时直接 return，不会注册任何工具。

Q: 怎么启用受限模式下的"升级一次"？

A: 命令被沙箱拒绝时，结果会带 [sandbox: file access denied under <mode> mode] 标记；模型可在同一轮用 sandbox_permissions（如 workspace-write / danger-full-access）+ justification 重试一次，会走 ctx.approval 用户审批。

Q: PowerShell 5.1 跑交互式 terminal 报错怎么办？

A: 这是 ConPTY 的已知限制（0x8009001d）。装 PowerShell 7 即可解决；一次性命令（shell 工具）不受影响。

Q: WSL 交互式 terminal 偶发 RPC 错误怎么办？

A: ConPTY 下偶发 0x8007072c。建议一次性命令继续用 shell 工具（wsl -e bash -lc ... 稳定），交互场景在 Windows Terminal 或 WSL 终端里直接跑，或重试。

Q: 升级 DSH 后设置面板不生效了？

A: DSH 升级会还原 settings UI 白名单补丁。重新运行 powershell -ExecutionPolicy Bypass -File install.ps1 install 即可。

上手难度

入门 — 普通用户只需要在 Web UI 设置里选一次默认终端就能用；要本地开发才需要懂 PowerShell、Junction 链接、install.ps1 等额外步骤。

已知问题与限制

• 仅在 Windows 上注册工具，macOS / Linux 安装后 shell 和 terminal 工具不会出现
• PowerShell 5.1 无法在 ConPTY 下启动交互会话（错误 0x8009001d），需装 PowerShell 7；一次性命令正常
• WSL 在 ConPTY 下交互模式可能触发 WSL 服务 RPC 错误（0x8007072c，偶发），一次性 wsl -e bash -lc ... 正常
• Windows 上 node-pty 不接受命名信号：只有 SIGINT 能映射为 Ctrl+C，其他信号（SIGTERM / SIGKILL / SIGTSTP / SIGHUP）退化为直接终止会话
• WSL 后台进程在超时 / 中断后可能在发行版内短暂残留（WSL 实例在最后一个进程退出后自动关闭）
• Git Bash 是 msys2 环境，与 WSL 的 Linux 行为存在差异（路径映射、可用包）
• DSH 的 Windows ACL 沙箱 launcher（node-addon-landlock-run-win32-x64）尚未在 npm 发布，本地沙箱后端暂不可用
• DSH 设置 UI 对第三方 settings namespace 有硬编码白名单限制，必须用 install.ps1 打补丁才能让用户在 UI 写入默认终端偏好

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

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

每次调用都启动全新 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。
• 前端设置页的「默认终端」是枚举（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. 让 profile 通过官方 bundle 挂载插件（install.ps1 install 会自动做；等价于在 dsh.profile.bundles 加 "dsh-bash-terminal"）
# 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 会还原。

当前已不再需要手动改 profile 的 cordis.patch.yml：插件包内自带 dsh.bundle.patch（包内 cordis.patch.yml），只要 profile 的 dsh.profile.bundles 里有 dsh-bash-terminal，DSH 就会自动挂载。

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

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 基准）：

发布（npm）

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

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

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

卸载

推荐直接运行：

powershell -ExecutionPolicy Bypass -File install.ps1 uninstall

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

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

交互式终端（terminal 工具）

terminal 工具在 PTY 接缝（node-pty；Windows 上因上游 spawnTerminal 的 process inspector 仅支持 POSIX，由 lib/terminal.js 直连 node-pty，非 Windows 仍走官方 ctx.subprocess.spawnTerminal）上提供持久交互会话：

• 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 工具的受限模式会经 ctx.sandbox.confine 包装（fail-closed），但它是额外的多终端入口，不享受官方 pwsh 工具的 ConstrainedLanguage 限制；danger-full-access 下与 dsh 进程同权限。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 终端，或重试。
• Windows 上 node-pty 不接受命名信号：signal 的 SIGINT 映射为 Ctrl+C（\x03），其他信号（SIGTERM / SIGKILL / SIGTSTP / SIGHUP）退化为终止会话。
• 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