前言¶
在 DeepSeek Harness (DSH) 的開發場景中，智能體往往需要訪問遠程服務器進行部署、調試或數據交互。dsh-ssh-tunnel 是一個社區插件，旨在解決多主機 SSH 訪問的權限管理、會話維護和交互界面問題。它爲 dsh-better-sidebar 提供了 SSHManager 工具，並實現了多主機隧道管理。
插件定位¶
- 名稱：dsh-ssh-tunnel
- 類型：DeepSeek Harness 社區插件
- 維護者：thirsty5034
- 定位：多主機 SSH 隧道 + SSHManager 工具
- 兼容性：面向 dsh-better-sidebar (>= 0.12)
核心功能¶
該插件提供了一套完整的 SSH 管理機制，核心能力如下：
- 主機清單與密鑰管理：在本地維護主機清單（
hosts.json）和密鑰（secrets.json）。這些敏感信息不會暴露給模型，僅用於插件內部處理。 - 項目範圍授權：支持基於項目的權限控制。通過
projectPathKey（通常爲工作區目錄）關聯可訪問的主機列表，實現細粒度的訪問控制。 - 模型工具 SSHManager：爲模型提供標準化的工具接口。支持
exec（執行命令）、sftp_list（列出文件）等操作，並支持會話策略（如複用或新建會話）。 - 側邊欄管理：提供側邊欄選項卡，用於管理主機 CRUD、項目授權以及會話的連接/斷開。
- 交互式界面：在中心覆蓋層提供交互式終端（基於 xterm）和雙面板 SFTP 文件管理界面。
- 非侵入式設計：插件不嘗試用單一遠程磁盤替換全局的
fs或subprocess，保持 DSH 原有的文件系統架構。
安裝與啓用¶
安裝建議通過 CLI 官方源進行，確保版本與 DSH 環境匹配。
export DSH_HOME=${DSH_HOME:-$HOME/.dsh}
dsh plugin --profile web add "dsh-ssh-tunnel@github:thirsty5034/dsh-ssh-tunnel"
安裝完成後，需要重啓 DSH Web 進程，並在瀏覽器中執行硬刷新（Ctrl+Shift+R 或 Cmd+Shift+R）以加載新的插件界面。
典型用法¶
模型通過調用 SSHManager 工具與遠程主機交互。以下是標準的工具調用示例：
- 列出所有主機：
SSHManager action=list_hosts
- 在指定主機執行命令：
SSHManager action=exec host_id=<id> command="uname -a"
- 通過 SFTP 列出目錄：
SSHManager action=sftp_list host_id=<id> path=/
會話策略：
在調用工具時，可以通過參數指定會話策略：
* reuse_or_create：默認策略，嘗試複用已存在的會話，失敗則新建。
* new：強制新建會話。
* require_existing：僅使用已存在的會話，不存在則報錯。
* session_id：顯式指定會話 ID。
數據與安全¶
插件的數據存儲在 $DSH_HOME/ssh-tunnel/ 目錄下（權限爲 0700）：
- hosts.json：存儲主機元數據。
- secrets.json：存儲密碼、PEM 私鑰或短語（權限
0600）。 - grants.json：存儲項目路徑到主機 ID 列表的映射。
- known_hosts.json：存儲已驗證的主機密鑰指紋（SHA256 十六進制格式）。
安全限制：
* 認證方式：僅支持密碼或私鑰認證。鍵盤交互 認證已廢棄，需編輯主機配置改用密碼或私鑰。不支持 Bastion Web MFA。
* 文件路徑限制：本地上傳/下載/列表操作限制在 /workspace 目錄，且進行詞法路徑檢查和 realpath 檢查，拒絕符號鏈接。
* API 安全：HTTP API 僅監聽本地迴環地址，且依賴 trusted-hosts 配置。瀏覽器 Origin 必須與配置匹配，會話 API 必須提供 projectPathKey。
* 密鑰輪換：如果懷疑 secrets.json 泄露，應立即輪換密鑰。
注意事項¶
- 不替換全局文件系統：插件提供的是會話級和工具級的 SSH 訪問，不會改變 DSH 的全局文件系統權限模型。
- 依賴環境：確保 DSH Web 配置了
dsh-better-sidebar(>= 0.12) 且 Node.js 版本爲 18+。 - 會話保活：插件內置了 ssh2 keepalive 機制（30秒間隔），意外掉線後會自動嘗試重連，最多重試 3 次。
- 前端依賴：終端依賴的
@xterm/xterm@5.5.0和@xterm/addon-fit@0.11.0通過同源路由加載，無 CDN 回退機制。
總結¶
dsh-ssh-tunnel 爲 DSH 生態提供了一套標準化的 SSH 管理方案，通過項目級授權和模型工具接口，解決了多主機遠程操作的安全性和易用性痛點。開發者在配置好主機清單和密鑰後，可直接在對話中使用 SSHManager 工具進行操作。
- 目錄頁：SkillHub 插件目錄
- 源碼倉庫：GitHub
