dsh-ssh-plugin: SSH 執行與持久化連接管理

前言¶

DeepSeek Harness (DSH) 是一個基於插件的智能體開發框架。在使用 DSH 構建代理時，經常需要讓模型直接操作遠程 Linux 服務器。雖然可以通過模型調用 shell 工具，但直接執行遠程命令需要額外的配置。dsh-ssh-plugin 插件提供了原生的 ssh_exec 工具，允許模型通過系統自帶的 SSH 客戶端直接在遠程服務器上運行命令。

插件介紹¶

該插件由維護者 YOLO-LZL 開發。它主要解決兩個問題：一是提供 ssh_exec 模型工具，允許直接在遠程 Linux 服務器上運行命令；二是支持持久化 SSH 連接，可以在工作區中保存連接配置，供後續調用使用。

核心功能¶

插件核心功能包括：
1. 模型工具集成：爲模型提供 ssh_exec 工具，支持自然語言指令（如 “ssh to root@10.0.0.5 and show disk usage”）或顯式參數調用。
2. 持久化連接管理：提供 ssh_connections 工具，支持保存、列出、刪除連接，並將連接綁定到工作區作爲默認連接。
3. 基於密鑰認證：僅支持 Key-based auth (BatchMode=yes)，沒有密碼/私鑰提示，避免因認證失敗導致的程序掛起。
4. 無遠程 Shell 引用層：遠程命令直接通過 bash -s 傳遞，不經過額外的 Shell 轉義層。
5. 會話沙箱感知：根據當前會話的安全策略運行，在 danger-full-access 策略下可不受限制運行。
6. 本地配置識別：自動識別並讀取本地的 ~/.ssh/config 文件，無需手動保存配置別名。
7. 雙端包設計：同時支持宿主端和瀏覽器端。
8. 優雅降級：當 Harness 的某些服務（如 settings 或 workspaceRegistry）缺失時，插件仍能正常工作。

安裝與啓用¶

從 npm 安裝插件：

dsh plugin --profile <name> add dsh-ssh-plugin

安裝後啓動 Harness 即可使用：

dsh --profile <name>

典型用法¶

插件爲模型提供了 ssh_exec 和 ssh_connections 兩個工具。

ssh_exec¶

模型可以直接使用自然語言，或傳遞顯式參數執行命令。

參數	必填	說明
`host`	是	遠程主機地址 `[user@]host`，或 `~/.ssh/config` 中定義的別名。
`command`	是	在遠程主機上通過 `bash -s` 運行的命令。
`port`	否	SSH 端口，默認 22。
`key_path`	否	私鑰的絕對路徑。省略則使用 `~/.ssh` 默認或 ssh-agent。
`timeout_ms`	否	前臺超時時間（毫秒），默認 30000。
`connection`	否	已保存連接的標籤，用於填充 host/port/user/keyPath。

ssh_connections¶

用於管理持久化連接，連接數據保存在 Harness 設置中，重啓後依然存在。

save: 保存連接（需提供 label、host，可選 port、user、keyPath）。
list: 列出已保存的連接，以及從 ~/.ssh/config 發現的只讀主機。
delete: 通過標籤刪除連接。
use: 將當前工作區綁定到指定連接標籤，後續調用 ssh_exec 可省略 host 參數。

適用場景與注意¶

目標環境：目標 Linux 服務器必須安裝 bash 並配置好基於密鑰的 SSH 訪問（~/.ssh/authorized_keys）。
Windows 環境：在 Windows 上運行時，會話的沙箱策略必須是 danger-full-access，否則受限令牌可能拒絕啓動 ssh.exe。
安全性：插件僅存儲密鑰路徑，密鑰內容不會離開本地磁盤。
許可證：插件採用 MIT 許可證。

短結尾¶

該插件通過封裝 SSH 客戶端調用，簡化了代理對遠程服務器的操作。配合持久化連接功能，可以減少重複配置。相關代碼位於 GitHub。