dsh-interactive-terminal

DeepSeek Harness (DSH) 的核心設計理念是「一切皆插件」。在 Web 端開發智能體時，如果需要讓模型直接執行 Shell 命令並保持會話狀態，傳統的方案往往需要跳轉到本地終端。dsh-interactive-terminal 插件通過在瀏覽器中嵌入一個持久化的 PTY 終端，解決了這一割裂問題，實現了模型與用戶在同一界面內的交互。

插件定位¶

這是一個由維護者 mingzhicode 開發的客戶端插件。它利用 xterm.js 在 DeepSeek Harness Web 界面中渲染終端，允許 Agent 通過工具調用（shared_terminal_send）運行程序，同時也支持人類用戶接管控制權繼續交互。插件的核心目標是提供單 Agent 終端控制機制，確保一次只有一個視圖可以寫入終端，其他視圖保持只讀。

核心功能¶

持久化 Bash 會話：在 DSH Web 中運行持久化 Bash 終端，面板摺疊或斷線重連不會結束 Shell。
模型與用戶共享：模型可以通過工具調用運行程序，人類用戶可以接管並繼續交互。
基於 xterm.js：使用標準的 Web 終端 UI 進行渲染。
單控制器機制：僅允許一個瀏覽器視圖控制 Agent 的終端，其他視圖爲只讀。
狀態恢復：支持 PTY 屏幕快照恢復與斷線重連。

安裝與啓用¶

安裝和啓動必須使用相同的 DSH_HOME（默認爲 ~/.dsh）。

前置要求：
* 操作系統：macOS 或 Linux
* Shell：Bash
* 工具：Node.js (^22.19 || >=24)、pnpm（需在 PATH 中，版本 10.18.3）
* DSH 版本：0.1.0-rc.8

安裝步驟：

在終端中執行以下命令安裝插件包到 Web 配置文件中：

    dsh plugin --profile web add dsh-interactive-terminal@0.1.0

啓動 DeepSeek Harness Web：

    dsh --profile web

在瀏覽器中打開打印出的 URL，配置模型和會話後，點擊 Open terminal。
在空閒提示符下輸入 echo hello 驗證瀏覽器輸入。

交互流程¶

插件接管終端後，存在明確的控制權流轉邏輯：

打開終端：點擊 Open terminal。首次展開或 Agent 調用工具時，Shell 會懶加載創建。
確認控制器：確認狀態顯示爲 Controller。在空閒提示符下直接輸入，首次按鍵請求人類輸入所有權，後續按鍵等待授權。
模型運行：模型調用 shared_terminal_send 運行程序。此時模型擁有操作隊列，普通鍵盤輸入會被忽略。
接管輸入：當程序請求輸入時，點擊 Take over input 並等待授權後再輸入。這種接管保留了進程，不發送信號，並移除模型的操作截止時間。
繼續交互：在同一個 PTY 中繼續輸入文本、換行或 UTF-8 字符。換行提交輸入但不會釋放所有權，直到 Shell 提示符確認或進程退出。
中斷：使用 Interrupt input 發送 SIGINT，這會中斷程序並保留所有權，直到提示符恢復。

配置說明¶

插件支持通過配置文件覆蓋默認行爲。配置文件路徑爲 ~/.dsh/profiles/web/cordis.patch.yml（或自定義的 $DSH_HOME/profiles/web/cordis.patch.yml）。

配置示例：

- id: dsh-interactive-terminal
  config:
    shellPath: /bin/bash
    shellArgs: [--noprofile, --norc, -i]
    rows: 40
    cols: 160

配置生效後需要重啓 DSH。以下是可配置字段的默認值與效果：

字段	默認值	效果
`shellPath`	`/bin/bash`	Bash 可執行文件，僅支持 Bash，其他 Shell 會被拒絕。
`shellArgs`	`--noprofile --norc -i`	交互式 Shell 參數，空參數會被拒絕。
`rows`	`40`	每個 PTY 生成固定的行數。
`cols`	`160`	每個 PTY 固定的列數。
`scrollbackLines`	`10000`	視口外的保留歷史行數。
`scrollbackMaxBytes`	`4194304`	序列化 ANSI 歷史記錄的字節限制。
`maxToolOutputBytes`	`262144`	工具結果 JSON 的完整限制。
`maxInputBytes`	`65536`	每次模型發送或接受的人類輸入租約的字節限制。
`maxQueuedOperations`	`128`	每個 Agent 允許的變更數（含當前操作）。
`maxSessions`	`32`	活躍的 Agent 終端最大數量。
`pollIntervalMs`	`50`	前臺進程檢查間隔。
`operationTimeoutMs`	`30000`	模型變更截止時間。
`interruptTimeoutMs`	`5000`	`SIGINT` 後受控提示符恢復截止時間。
`disconnectGraceMs`	`15000`	恢復連接前的寬限期。
`disposeGraceMs`	`3000`	重置或清理時的進程樹終止寬限期。

注意事項¶

環境一致性：安裝和啓動必須使用相同的 DSH_HOME，否則插件可能無法加載。
依賴檢查：如果 pnpm 報告沒有版本可用，請檢查是否使用了公共註冊表（如 registry.npmjs.org）。
視圖限制：一次只有一個瀏覽器視圖可以控制 Agent 的終端，其他視圖和移動視圖爲只讀。如果需要接管，必須關閉當前控制視圖並等待 disconnectGraceMs 後重連。
更新：修改配置文件後需要重啓 DSH 才能生效。

總結¶

dsh-interactive-terminal 爲 DSH 生態提供了一套標準化的終端交互方案。通過共享 PTY 和精細的輸入控制邏輯，它讓模型在 Web 界面中的自動化操作更加貼近真實的終端體驗，同時也爲開發者提供了靈活的配置空間。

插件目錄：dsh-interactive-terminal
源碼地址：mingzhicode/dsh-interactive-terminal