前言¶

在 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