前言¶
DeepSeek Harness (DSH) 是一個基於插件擴展的系統。在進行智能體開發或調試時，在網頁界面內直接執行命令是剛需。現有的方案往往依賴外部窗口彈窗，或者只是模擬輸出的文本框，無法滿足實時交互的需求。
dsh-plugin-terminal-panel 解決了這個問題。它通過側欄入口在 DSH 網頁中增加一個終端面板。與「對話」面板同級，內部使用真實的 PTY（僞終端）技術，支持回放最近 256K 字符輸出，且終端進程跑在 DSH 宿主進程中，刷新頁面不會斷開連接。
核心能力¶
側欄入口與活躍計數¶
插件加載後，側欄面板圖標區會出現終端圖標。圖標右上角實時顯示運行中的終端數量，數量爲 0 時自動隱藏。
真實 PTY 與回放¶
面板內運行的是真實的 PTY（node-pty / ConPTY），不是假的輸出框。終端輸出通過 SSE 實時推送給頁面。由於終端在宿主進程，刷新頁面後 PTY 依然存活，並回放最近 256K 字符的輸出。
按設備認終端類型¶
插件不寫死終端列表，而是根據當前設備實測可用的 shell。Windows 上列出 PowerShell 7 / cmd / Git Bash / WSL 各發行版；macOS 列出登錄 shell / zsh / bash / fish 等；Linux 列出 /etc/shells 中的類型。未安裝的類型會顯示在「未安裝」區塊。
選擇 shell 與默認工作目錄¶
新建終端時，可以選擇 shell 類型和工作目錄（支持 ~ 和相對路徑）。默認工作目錄爲用戶主目錄（~）。設置面板可以指定默認終端類型和注入 Agent 工具的開關。
多標籤、重命名與交互¶
面板支持多標籤（上限 12 個）。雙擊標籤名或點擊 ✎ 圖標可重命名（支持中文和 emoji）。雙擊標籤上的 ✕ 可關閉終端（進程樹終止）。面板寬度變化會自動 resize PTY。
自繪終端、主題跟隨與輸入¶
內置小型 VT 引擎，支持 ANSI 顏色（16/256/真彩）、光標定位、寬字符。支持亮/暗兩套 ANSI 調色板，跟隨 DSH 主題。支持文本選擇模式和中文輸入（IME 組合輸入）。
Agent 工具¶
插件向 DSH 工具註冊表註冊了 9 個 terminal_* 工具（如 terminal_create, terminal_exec, terminal_read 等），模型和用戶共用同一批終端。可在設置面板中一鍵關閉注入。
熱重載¶
修改 impl.js 後，通過 POST /__reload 即可生效，工具定義隨之更新，無需重啓 DSH。已經開着的終端不會被替換。
安裝與啓用¶
環境要求：DSH >= 0.2.0-rc.2，Node ^22.19.0 || >=24.0.0。
執行以下命令安裝：
dsh plugin --profile web add dsh-terminal-panel
安裝後刷新頁面，側欄面板圖標區會出現終端圖標。
使用步驟¶
- 點擊左欄的終端圖標，主區域打開終端面板。
- 點擊 + 新建終端，默認在主目錄開啓一個 PTY；點擊右側 ▾ 可展開菜單，選擇 shell 或修改工作目錄。
- 在面板內直接輸入命令，支持中文輸入。
- 重命名：雙擊標籤名或點擊標籤上的 ✎。
- 關閉：雙擊標籤上的 ✕，進程樹終止。
- 調整：面板隨窗口變化自動 resize。
Agent 工具說明¶
插件加載後註冊的工具列表：
terminal_shells：探測本機可用 shell 及未安裝類型。terminal_list：列出當前所有終端。terminal_create：新建終端，可指定 shell、cwd、尺寸。terminal_read：讀取終端輸出（按 offset 增量讀）。terminal_write：往終端發送原始按鍵。terminal_exec：執行命令並等待跑完。terminal_resize：改變終端行列數。terminal_rename：重命名終端。terminal_close：關閉終端。
技術架構與安全¶
插件爲純 JS 實現，無構建步驟與運行時依賴。文件結構包含 host.js（宿主入口）、impl.js（PTY 生命週期、工具定義）、client.js（終端面板、側欄圖標）。
寫操作（POST 請求）必須帶 x-dsh-terminal: 1 請求頭。這是因爲跨站頁面無法自定義請求頭，以此作爲安全底線，防止第三方頁面驅動你的終端。
結語¶
這個插件爲 DSH 增加了原生的終端能力，讓網頁操作和命令行交互在同一界面無縫結合。適合需要在網頁中直接調試、運行腳本或進行智能體開發場景。
