dsh-bash-terminal

dsh plugin --profile web add dsh-bash-terminal

dsh-bash-terminal

🌐 [English](README.en.md) · 社区交流：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。
• 前端设置页的「默认终端」是枚举（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. 重启 dsh web

⚠️ 不要在本项目里跑 npm install：它会删掉上面第 2 步的 junction，转而给插件装一份独立的

@deepseek-ai/* 副本 —— 插件和宿主就不再共用模块实例，宿主升级后插件会停在旧 API 上

（本项目曾因此停在 0.1.0-rc.6）。只刷新 lock 时用 npm install --package-lock-only。

兼容性：要求 DSH ≥ 0.1.5-rc.1。0.1.5 把浏览器模块表里的 @deepseek-ai/dsh-client-runtime

改名为 @deepseek-ai/dsh-client-store 且只按精确裸名命中；旧 bundle 在新宿主上会报

Failed to load plugins / require(...) missed the module table。

另：0.1.5 的 Web 设置面改为 settings.describe() 动态枚举，不再有 namespace 白名单

（settings-not-exposed 已不存在），install.ps1 里的白名单 patch 只是历史遗留、可忽略。

当前已不再需要手动改 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 基准）：

键 · 默认 · 说明

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。

卸载

推荐直接运行：

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 后端经

…(truncated)