前言¶
在 DSH（DeepSeek Harness）裏做智能體開發時，工具和上下文多半落在本機工作區；真正要改的服務、跑命令的環境往往在另一臺 SSH 可達的機器上。常見做法是再開一個終端和 SFTP 客戶端，或在編輯器裏裝 Remote SSH，但那些界面與 DSH 的會話、better-sidebar 並不天然連在一起。
下面介紹社區插件 dsh-remote-ssh（維護者 LinHao100076，MIT 許可）。它在 DSH 右側邊欄（或與 dsh-better-sidebar 聯動的「遠程 SSH」標籤頁）裏提供遠端文件樹、終端、按方向配置的編輯同步、SFTP 傳輸，以及本地 -L、動態 -D、反向 -R 轉發與多跳跳板鏈路。README 將當前重點版本寫爲 0.7.3（無密鑰首次建連、堡壘機多跳、密碼與 2FA 等）；倉庫 package.json 中版本號爲 0.7.4，安裝時以你拿到的發佈包爲準。
插件在 SkillHub 分類爲「客戶端」，GitHub 星標約 3。目錄頁：https://www.skillhub.cn/plugins/LinHao100076/dsh-remote-ssh；源碼與說明：https://github.com/LinHao100076/dsh-remote-ssh。
這是什麼¶
一句話定位：這不是獨立的通用 SSH 客戶端，而是「本地 DSH 工作區旁掛一條遠端通道」——文件、終端、同步和轉發都收在同一個 Workspace 面板裏（主機頭 + 文件 / 終端 / 同步 / 轉發 / 設置 + 狀態欄）。
設計文檔（docs/design.md）裏的核心判斷是：agent 與 better-sidebar 的執行世界在本地，因此 v0.x 走「本地鏡像 + 旁掛遠端」，而不是把整個 harness 搬到遠端。主機配置與映射狀態落在插件自己的 ~/.dsh/storages/dsh-remote-ssh/state.json；密碼和口令不落盤，只在瀏覽器內存裏、連接時現取。
核心功能¶
入口與界面¶
兩種入口互斥，面板是同一套組件：
| 裝了什麼 | 出現在哪 | 怎麼打開 |
|---|---|---|
有 dsh-better-sidebar |
better-sidebar 側欄里名爲「遠程 SSH」的一個標籤頁 | 側欄點「遠程 SSH」 |
| 沒有 / 停用了 better-sidebar | DSH 自帶右側邊欄 | 會話頭部右上角服務器圖標 |
界面寬度跟隨右側欄；可先本地打開 ui/prototype.html 對照佈局（轉發視圖晚於原型，改 UI 以 client/forward-view.jsx 爲準）。
文件與傳輸¶
- 側邊欄瀏覽遠端目錄：單擊展開、雙擊進入；麪包屑與「上傳位置」表示當前目錄；回到文件頁會刷新，頁面可見時每約 4 秒刷新當前目錄與已展開子目錄。
- 上傳按 256 KB 分塊，避免大塊文件塞進 JSON；支持取消（發佈階段不可取消）；空閒 15 分鐘任務自動清理。
- 下載可填本機絕對路徑（含文件名），也可「下載到映射目錄」；此處的「本地」是 DSH 宿主所在機器（桌面版即當前電腦，遠程 Web 部署則是跑 DSH 的服務器）。
- 0.5.0 起支持 SFTP 斷點續傳；0.7.2 起加強覆蓋與自動同步邊界（不完整傳輸、源變化時保留目標；OpenSSH 原子 rename 等，詳見 CHANGELOG）。
遠端搜索¶
放大鏡默認在當前目錄及子目錄按文件名包含關鍵詞查找；可切到「文件內容」模式，在遠端執行 rg（無則 grep -r），不把整庫拉到本地索引。內容模式支持 smart-case 與有限正則；結果上限 200 條並在遠端截斷。
終端與 tmux¶
遠端有 tmux 時執行 tmux new -A -s dsh-<host>，刷新或斷線後可接回同一會話；沒有 tmux 則用普通 shell，並提示刷新後會話進程會結束。新建終端標籤對應獨立 tmux 會話。
同步（鏡像編輯）¶
「同步」標籤頁按映射配置方向（本地 ↔ 遠端）做文件鏡像與 watcher；與 agent 在本地改動上傳、遠端文件下載等流程配合。相對映射路徑按會話目錄解析；下載不能越過本地映射目錄。具體衝突策略與 0.7.2 的變更見 README 與 CHANGELOG。
端口轉發與跳板¶
| 方式 | 監聽端 | 典型用途 |
|---|---|---|
本地 -L |
DSH 宿主 | 經 SSH 主機訪問其可達的內網服務（如 B:22、數據庫、Web） |
動態 -D |
宿主 SOCKS5 | 支持 SOCKS5 的客戶端訪問多個內網目標 |
反向 -R |
SSH 主機側 | 讓服務器訪問宿主上的服務 |
| 跳板鏈路（推薦連內網 B） | 無額外固定監聽 | 在主機 B 的設置裏串起 A→B，插件完成 本機 → A → B，文件與終端屬於 B |
經 A 連 B 時：跳板鏈路會替你完成到 B 的 SSH 登錄；僅開 -L 到 B 的 22 端口只提供 TCP 隧道，仍要再用 B 的地址與憑據建主機，且 A 的連接須保持運行。遠程 Web 部署時，表中的「宿主」指運行 DSH 的服務器，不是打開瀏覽器的電腦。
0.6.0 起補充 SOCKS5 動態轉發與 -R；0.7.0 起支持密碼 / keyboard-interactive（2FA）與多跳跳板；0.7.0 起強調無密鑰也能首次建連。
認證與依賴¶
Node ≥ 20（CI 在 20 / 22 / 24 上跑測試）；宿主端 lib/server.mjs 將 ssh2、ws、chokidar 等打進 bundle，發佈包無運行期 npm 依賴（0.3.1 起）。客戶端通過 @deepseek-ai/dsh-client-ui-slots 等注入 Web 側欄。
安裝與啓用¶
不要使用裸包名 dsh plugin add dsh-remote-ssh：npm 上存在同名但歸屬不同的包，會佔同一 node_modules/dsh-remote-ssh 目錄。安裝須用 GitHub Release 的 tgz 完整路徑或按倉庫說明取用；認準倉庫 LinHao100076/dsh-remote-ssh。
推薦用發佈包安裝（DSH 會寫入 profile 的 dsh.profile.bundles）：
npm run pack:rel # 生成 dist/dsh-remote-ssh-<版本>.tgz
dsh plugin --profile <profile> add -w "/path/to/plugin.tgz"
-w 不能省略：profile 含 pnpm-workspace.yaml 時，不帶 -w 可能報 ERR_PNPM_ADDING_TO_ROOT。
不要解壓 tgz 後把目錄當路徑裝進去（pnpm 可能寫成 link:，歷史上會導致宿主端 import 缺依賴）；當前發佈包已把依賴打進 lib/server.mjs，用 tgz 路徑即可。
CLI 啓動示例（app 參數直接跟在後面，不要寫 web）：
dsh --profile <name> --no-open --port 4987
desktop profile 由桌面應用獨佔，CLI 會拒絕；應在應用內插件頁安裝，或手工改 package.json 的 bundles 與 cordis.patch.yml 後重啓。桌面版升級插件後請完全退出再啓動，只關側欄可能仍加載舊客戶端代碼。
開發期也可僅在 cordis.patch.yml 插入插件 id（需已構建 lib/client.js），見 README「裝到 profile 裏」一節。
典型用法¶
1. 第一次連上主機¶
- 打開「遠程 SSH」面板，新建連接，填寫地址、端口、用戶與認證（密鑰、密碼或 2FA）。
- 若目標在內網，在「跳板鏈路」裏按順序添加堡壘機卡片（支持多跳；
~/.ssh/config的ProxyJump會展開爲多跳）。 - 連接成功後，在「文件」頁瀏覽、預覽、上傳或下載；在「終端」頁執行命令。
2. 經堡壘機訪問內網 B（推薦跳板）¶
- 新建主機 B：填 B 內網地址、端口、用戶與 B 的認證。
- 在 B 的跳板鏈路中添加 A，填 A 的 SSH 地址與認證。
- 連接後文件樹與終端即 B 的環境，無需先手動配
-L再二次建連。
若必須用轉發：先在 A 上添加本地 -L 監聽 127.0.0.1:2222，目標爲 A 能訪問的 B:22；再建主機 B，地址 127.0.0.1、端口 2222，用戶與認證仍填 B 的，並保持 A 連接與轉發運行。
3. 搜索與編輯¶
- 在文件視圖選目錄，用搜索默認可查文件名；切「文件內容」則在遠端
rg/grep。 - 在「同步」頁配置映射方向，讓本地 agent 改動按規則上傳到遠端或拉取遠端文件；注意映射目錄邊界與衝突說明（見 0.7.2 README 段落）。
4. 端口轉發¶
在「轉發」頁爲已連接主機添加 -L、-D 或 -R 規則，在宿主（或 Web 部署時的 DSH 服務器）上監聽，把流量導向 SSH 對端可達的服務。
適用場景與注意¶
適合誰：已經在用 DSH 做本地智能體開發，需要頻繁在側邊欄看遠端目錄、開 shell、同步一小段映射目錄，或臨時做 SSH 隧道，又不想在 DSH 外再維護一套 Remote 工具鏈的人。
權限與安全：插件在當前 DSH 宿主進程權限下執行 SSH、讀寫本地映射路徑與轉發監聽；安裝前應閱讀源碼、SECURITY.md 與 MIT 許可證，確認憑據存儲模型是否符合你的環境。社區目錄 SkillHub 與 DeepSeek / 幻方無官方從屬關係，插件屬社區貢獻。
其他注意：
- 與 dsh-better-sidebar 聯動時側欄更集中；無 better-sidebar 時用原生右側欄入口即可。
- 遠端 Web 部署時，下載目標路徑、
-L/-D監聽端都在 DSH 服務器上，不是瀏覽器所在電腦。 - 上傳中斷或異常可能留下遠端
.dsh-tmp-*臨時文件；大文件上傳請留意分塊與取消行爲。
結尾¶
經過上面的步驟，可以把 dsh-remote-ssh 理解成：在 DSH 裏給遠端機器做一塊固定的「影子工作區」——文件、終端、定向同步和三種轉發收在同一面板，並支持多跳與無密鑰首次建連。細節與版本差異以倉庫 README、CHANGELOG 和 ROADMAP 爲準。
