前言¶
在 DeepSeek Harness（DSH）的 web profile 裏，agent 執行前臺 shell 時，默認往往只有工具返回的文本摘要，看不到提示符、命令回顯和 ANSI 着色。排查構建失敗、長時間跑測試或需要與 agent 共用同一交互 shell 時，這種「黑盒執行」會增加溝通成本。
下面介紹的 dsh-web-terminal（維護者 fightingFirefox）把 agent 的前臺 pwsh / bash 調用送進常駐真實 PTY，右側欄顯示的就是該終端本身——提示符、回顯、輸出與退出碼由 shell 產生，插件不拼接、不回放輸出。同時向模型暴露 17 個 live_terminal_* 工具，便於讀屏、截圖與交互控制。桌面版 desktop profile 不在本倉庫範圍，需使用上游 dsh-live-terminal。
這是什麼¶
dsh-web-terminal 是 DSH 生態中的客戶端類插件（當前 GitHub 星標爲 0）。host 側通過 ctx.subprocess.spawnTerminal 與 webServer / connection 服務註冊 PTY；客戶端注入 @deepseek-ai/dsh-client-ui-sidebar-right，在瀏覽器右側欄渲染 Claude 風格終端面板（ANSI 調色板可隨宿主淺色/深色主題切換）。邏輯 fork 自 dsh-live-terminal 1.3.1（MIT），本倉庫改動集中在視覺層、包名與安裝鏈路。許可證 MIT，當前 package 版本 1.1.3。
適用範圍與環境¶
| 項 | 要求 |
|---|---|
| DSH | >= 0.2.1-alpha.3 且 < 0.3.0-0 |
| profile | web（~/.dsh/profiles/web） |
| Node.js | ^22.19.0 \|\| >=24.0.0 |
| 系統 | Windows 爲當前測試平臺；macOS / Linux 複用同一 spawnTerminal 路徑 |
面板數據經宿主 HTTP/SSE（前綴 /dsh-terminal-panel）在本地瀏覽器與宿主之間傳輸，不訪問外部服務。
核心功能¶
可見終端面板¶
- 同一 DSH 對話複用一個常駐 PTY；命令串行排隊，不併發寫同一 shell。
- 僅攔截 agent 前臺 shell 調用；帶
run_in_background或sandbox_permissions的調用不攔截，保持 DSH 原生語義。 - 出現新的可見終端時自動打開右側欄；命令結束後終端停在提示符上（無默認自動關閉；可通過配置調整延遲）。
- 面板內可直接鍵入，與 agent 共用同一 shell；
+可新建獨立交互終端。
live_terminal_* 工具（17 個）¶
模型側可調用例如 live_terminal_list、live_terminal_run、live_terminal_read、live_terminal_screenshot（支持 text / ansi / png）、live_terminal_send、live_terminal_wait、live_terminal_open / live_terminal_close 等。完整列表見倉庫 README「工具接口」一節。
實現要點（與面板所見一致）¶
攔截路徑不創建一次性「命令終端」，而是把命令寫入常駐交互 shell：逐行發送並單獨發送回車；完成判定依賴屏幕最後一行爲提示符且靜置 140 ms；輸出通過命令前後屏幕差異抽取。初始化或運行失敗時回退內置工具，命令語義不變。
安裝與啓用¶
官方 README 說明：dsh plugin add 可能因 engines 校驗被拒絕，本倉庫推薦用手工安裝路徑。
方式一：倉庫內腳本（推薦）¶
在已獲取源碼的目錄中執行（也可下載 Release v1.1.3 源碼包解壓後執行同一份腳本）：
pwsh -NoProfile -File install.ps1
腳本會備份 profile 的 package.json 與 cordis.patch.yml，複製插件文件到 ~/.dsh/profiles/web/node_modules/dsh-web-terminal，安裝 @xterm/headless、@xterm/addon-serialize，在 dsh.profile.bundles 註冊 dsh-web-terminal，並在 cordis.patch.yml 寫入默認 interceptShellTools: true。
方式二：手動安裝¶
$dest = "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-web-terminal"
New-Item -ItemType Directory -Force $dest | Out-Null
Copy-Item lib, package.json, cordis.patch.yml, LICENSE, NOTICE, icon.svg $dest -Recurse
cd $dest; npm install --omit=dev
在 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles 加入 "dsh-web-terminal"，並在 cordis.patch.yml 追加：
- id: dsh-web-terminal
name: dsh-web-terminal
config:
interceptShellTools: true
卸載：
pwsh -NoProfile -File uninstall.ps1
安裝後必須完全退出 DSH 再啓動（dsh web），host 插件與 client bundle 在啓動時加載。
安裝後驗證¶
- 重啓 DSH 後，右側欄應出現終端標籤頁（kind：
web-terminal-panel）。 - 在對話中觸發一次前臺 shell（例如讓 agent 運行
npm test）：右側欄自動打開pwsh標籤頁，命令以PS <cwd>> <命令>形式出現；結束後回到提示符，下一條命令在同一屏追加。 - 模型可通過
live_terminal_list查看當前終端。
配置¶
覆蓋位置：~/.dsh/profiles/web/cordis.patch.yml 中 dsh-web-terminal 的 config。常用項包括：
| 鍵 | 默認 | 說明 |
|---|---|---|
interceptShellTools |
true |
是否攔截 agent 前臺 shell |
autoCloseCommandDelayMs |
8000 |
成功結束後自動關閉延遲；-1 爲永不 |
requireSandbox |
false |
true 時在非 danger-full-access 下拒絕接管 |
scrollback |
2000 |
單終端回滾行數 |
commandTimeoutMs |
180000 |
live_terminal_run(wait:true) 默認超時 |
其餘鍵（歷史、輸出上限、會話數、shellPath 等）見 README「配置」表。
適用場景與注意¶
適合：主要在 DSH web profile 下開發、希望肉眼看到 agent 命令在真實 shell 中執行、或需要 live_terminal_screenshot 等工具輔助模型讀終端的場景。可與 dsh-claude-style 主題共存。
務必知曉的安全屬性：面板終端與 agent 終端以當前系統用戶權限運行，PTY 不套用 DSH 文件沙箱；該信息會出現在面板狀態欄與工具結果的 sandbox 字段中。安裝並啓用前，應自行審閱 源碼與 LICENSE。requireSandbox: true 時，非 danger-full-access 環境不會接管，回退內置沙箱工具。
排障簡述：沒有 live_terminal_* 工具時檢查 dsh.profile.bundles 與是否完整重啓；面板不出現則查 cordis.patch.yml 與瀏覽器控制台 client bundle 報錯；命令不上屏則查 interceptShellTools、是否後臺/升權調用、以及 requireSandbox 與沙箱模式組合。
鏈接¶
- 社區目錄頁：https://www.skillhub.cn/plugins/fightingFirefox/dsh-web-terminal
- GitHub 倉庫：https://github.com/fightingFirefox/dsh-web-terminal
DSH 生態強調「一切皆插件」；SkillHub 等目錄爲社區站點，與 DeepSeek / 幻方無官方從屬關係。本文事實均來自上述倉庫 README 與 package 元數據。
