前言¶

DeepSeek Harness (DSH) 採用「一切皆插件」的架構。在 Web UI 環境中調試智能體或執行本地命令時，一個真實的終端是剛需。dsh-terminal 插件通過宿主端的 node-pty 和客戶端的 xterm.js，爲 Web UI 提供了一個開箱即用的交互式 shell 面板。

這是什麼¶

dsh-terminal 是 DeepSeek Harness 的一個 Web UI 終端面板插件。它由 giiiiiithub 維護，採用 MIT 許可證。

插件包含宿主端和客戶端兩部分。宿主端利用 node-pty 在 DSH 服務進程中拉起真實的 shell（Windows 下走 ConPTY），客戶端使用 xterm.js 進行渲染，從而實現全功能的瀏覽器終端體驗。

核心功能¶

• 真實 PTY：基於 node-pty，提供真實的 shell 環境，而非簡單的模擬器。
• 瀏覽器渲染：使用 xterm.js（@xterm/xterm 6），支持全色彩、光標、滾動回看（5000 行）以及 Ctrl+Shift+C/V 複製粘貼。
• 多標籤會話：支持同時打開多個終端標籤。摺疊面板後，宿主端的會話會繼續運行。
• 窗口交互：支持停靠模式（可拖動邊緣調整高度）和浮動模式（可移動窗口並八向縮放）。
• 隨項目打開：首個會話默認在 DSH 的第一個 workspace path 啓動；找不到時回退到配置目錄或用戶主目錄。

安裝與啓用¶

安裝前需確保已安裝 DeepSeek Harness，且 dsh web 能正常啓動。同時，DSH 的 profile 使用 pnpm 管理依賴，需滿足 pnpm >= 9。

第一步：安裝¶

在 DSH profile 目錄下執行以下命令：

dsh plugin --profile web add dsh-terminal

注意： 若安裝環境使用 pnpm >= 10，可能會攔截 node-pty 的構建腳本。此時需將 node-pty 加入 profile 目錄 pnpm-workspace.yaml 的 allowBuilds 配置中，然後重新執行安裝命令。

第二步：重啓服務¶

插件包含宿主端代碼，必須重啓 dsh web 進程才能加載：

# 停止當前進程（如 Ctrl+C），然後啓動
dsh web

第三步：驗證¶

刷新瀏覽器頁面。在會話頭部出現 >_ 終端按鈕後點擊展開。首次展開會自動啓動一個默認 shell 會話（Windows 下爲 cmd.exe）。

配置¶

默認配置可通過 profile 目錄下的 cordis.patch.yml 覆蓋。配置項會在插件 bundle 層之後應用。

- id: terminal
  config:
    shell: cmd.exe          # 默認 shell（Windows 下默認即 cmd.exe，也可填完整路徑）
    cwd: <工作目錄>           # 新會話默認工作目錄
    env:                     # 追加到進程環境
      LANG: "zh_CN.UTF-8"

已知限制¶

• 會話管理：活會話上限爲 64 個。超出後 open 操作會先逐出已退出的會話，仍滿則返回 session-limit 錯誤。已退出會話在宿主端保留 60 秒供讀取退出碼，之後轉入 tombstone（上限 64 條）。
• 服務重啓：DSH 服務重啓會終止所有 PTY 會話。
• Kill 命令：kill 命令在 Windows 和 Linux 下的行爲有差異。Windows 上會先執行 taskkill 強制清理進程樹，再走 node-pty 正常終止；Linux 下按進程組終止。僅當子進程以 CREATE_NEW_CONSOLE 啓動等特殊情況時，可能仍會殘留。
• 摺疊面板：摺疊面板或非活動標籤的會話輸出在宿主端緩衝（上限 2MB），重新激活時會一次性回放。

結語¶

dsh-terminal 插件解決了 Web UI 環境下調試與執行命令的痛點，提供了真實、低延遲的終端體驗。通過配置 shell、cwd 和 env，可以將其適配到不同的開發場景中。

更多細節可參考插件目錄或GitHub 倉庫。