前言¶
DeepSeek Harness (DSH) 的設計理念是「一切皆插件」。在智能體開發場景中，經常需要同時操作多臺服務器。傳統的 SSH 客戶端或直接調用 subprocess 會破壞上下文隔離，而自行管理 SSH 隧道較爲繁瑣。這裏介紹的是 DSH 的社區插件 dsh-ssh-tunnel，它將多臺 SSH 主機收進一個主機庫，並提供按項目的授權機制。
這是什麼¶
dsh-ssh-tunnel 是一個掛在 DSH 官方右側欄的插件，由 OMSociety 維護。它提供了一個主機庫、按項目授權功能，並在側欄集成了 SSHManager 工具與雙欄 SFTP面板。
插件的核心邏輯是：模型用 SSHManager 工具執行命令或傳文件，你在側欄管理主機與授權。遠端操作只發生在你顯式調用的工具與面板裏，本地文件與遠端文件始終是兩側分明的東西。配套插件是 dsh-git-forge（Git 憑據與 push 策略）。
核心功能¶
- 主機庫：管理多臺主機，支持密碼或私鑰（含口令）。密鑰只存宿主側，不進入模型上下文。
- 按項目授權：授權 key 是 DSH 會話工作區（
projectPathKey）。連接前必須先授權，Connect 不會自動寫入授權。 - SSHManager 工具：提供遠端 exec、SFTP 列舉/讀寫/增刪改、上傳下載、交互式會話讀寫等功能。
- 中央面板：交互式終端（xterm）與雙欄 SFTP：左側是項目工作區，右側是遠端，可直接上傳下載。
- 斷線可續：掉線會話留作墓碑，可重連（同一 id）或關閉。意外斷開自動重連最多 3 次，ssh2 keepalive 30s × 3。
- 主機密鑰指紋：以 SHA256 hex 存入
known_hosts.json。首次連接或指紋變更時在側欄確認並展示指紋。 - 本地路徑守衛：上傳/下載/列舉/刪除的本機路徑限制在項目工作區根內，詞法 與 realpath 雙重校驗。
- 界面雙語：側欄與面板隨 DSH 界面語言在中文 / 英文間即時切換。
安裝與啓用¶
從 npm 安裝：
# 先停掉正在運行的 DSH（運行中的服務會鎖住依賴，裝完再起）
dsh plugin --profile <profile> add "dsh-ssh-tunnel"
安裝完成後，刷新一下瀏覽器頁面，「SSH 隧道」入口才會出現在右側欄——只重啓宿主不夠，客戶端產物是頁面加載時取的。
典型用法¶
- 打開右側欄「SSH 隧道」→ 主機庫 添加一臺主機（密碼或私鑰）。
- 切到 項目授權，給當前項目勾上這臺主機並保存（不授權連不上，這是有意爲之）。
- 回 隧道會話 點 Connect；首次連接會提示確認主機密鑰指紋。
- 點 終端 得到一個交互式 shell，或點 SFTP 打開雙欄面板。
- 讓模型用
SSHManager action=exec跑條命令、用sftp_list看目錄、sftp_upload/sftp_download傳文件，驗證整條鏈路。
安全與注意事項¶
- 信任邊界：插件的 HTTP API 掛在 DSH 宿主的本地 web 服務上，只接受本機迴環與配置的可信主機，並校驗瀏覽器
Origin。API 沒有鑑權 token——能在本機訪問該端口的進程都被視爲已授權用戶。會話 API 必須帶projectPathKey，跨項目不可見。 - 認證方式：只有密碼或私鑰。鍵盤交互式認證（含堡壘機網頁 MFA）不支持。
- 路徑守衛 fail-closed：上傳/下載/列舉/建目錄/刪除的本機路徑限制在項目工作區根內，詞法 與 realpath 雙重校驗，越界路徑與指向工作區外的符號鏈接一律拒絕。
- 授權撤銷即時生效：寫類操作在發起前與結果回報前各複檢一次授權。撤銷後輸出被丟棄並以
not authorized失敗，下載中的本地文件被刪除，受影響的存活會話被關閉。 - 工具結果：工具結果與列表 API 不返回 password / PEM / 口令。優先使用密鑰登錄；若
secrets.json可能泄露請立即輪換憑據。
生態背景¶
DSH 理念是「一切皆插件」。社區目錄與 DeepSeek / 幻方無官方從屬關係。插件遵循 MIT 許可證。
