前言¶
DeepSeek Harness（DSH）要求工作區對應本機上一個真實存在的目錄，而很多日常開發、運維任務實際跑在遠端 Linux 上。若只靠本機 Shell 或單獨開 SSH 客戶端，agent 會話與「當前在哪臺機器、哪個目錄」容易脫節；同時連接多臺服務器時，還存在命令誤發到別的主機的風險。下面介紹社區插件 dsh-plugin-ssh（維護者 JeremyLyc，MIT 許可證，當前 package 版本 0.4.0），它用工作區綁定、原生會話工具與側欄面板，在 DSH Host 與遠端之間架橋。
這是什麼¶
dsh-plugin-ssh 面向 DSH 桌面版：爲 DeepSeek Harness 提供 SSH 遠程工作區——會話級 agent 工具（ssh_exec / ssh_upload / ssh_download / ssh_workspace）、左側「SSH 遠程」面板、右側「服務器文件」頁籤、目錄選擇與密碼彈窗，並在輸入框下方用 composer pill 顯示 agent 實際工作的目錄（例如 prod:/srv/app 或本地工作區路徑）。
架構上，瀏覽器側 lib/index.js 經 HTTP /ssh-panel/api/* 調用 Host 側 lib/ssh.js（ssh2）連服務器；lib/tools.js 註冊原生工具，按工作區綁定取主機。倉庫在 GitHub：JeremyLyc/dsh-plugin-ssh；社區目錄頁：skillhub.cn 條目。分類爲客戶端插件。
核心功能¶
會話工具（無 host 參數）¶
模型可直接調用四個工具，均不接受 host 參數——目標主機只來自當前會話工作區下的 .dsh-ssh-workspace.json 綁定：
| 工具 | 作用 |
|---|---|
ssh_exec |
在綁定主機上執行命令，返回 stdout/stderr/退出碼；可選 workdir、timeoutMs |
ssh_upload |
本地文件經 SFTP 上傳到綁定主機（自動建父目錄） |
ssh_download |
從綁定主機 SFTP 下載到本地 |
ssh_workspace |
回報當前綁定的主機、登錄目錄與遠端工作目錄 |
非零退出碼以 [exit code: N] 返回，不算工具錯誤；超時會向遠端發 KILL 並標 [timed out after Nms]。
隔離：一個會話只碰自己的服務器¶
插件在工具契約層面限制跨機誤操作：工具簽名裏沒有 host，也沒有 defaultHost 兜底；每次調用由 exec.agent 讀工作區目錄下的 .dsh-ssh-workspace.json。未綁定的普通工作區會直接拒絕；綁定指向配置裏不存在的主機會拒絕，不會回退默認主機。
README 說明：MCP 路徑（server.mjs）拿不到會話身份，可能接受任意 host 別名，因此不要與原生工具同時啓用 MCP 條目，否則可能繞過隔離。原生工具因能拿到 exec.agent 而適合做隔離。
側欄與遠程工作區¶
- 左側欄「SSH 遠程」：選主機、執行命令、傳文件、一鍵創建遠程工作區。
- 右側欄「服務器文件」：瀏覽服務器任意目錄、預覽文本、切換工作目錄。
- 遠程工作區：本地佔位目錄 +
.dsh-ssh-workspace.json+ 自動生成的AGENTS.md；切換遠端目錄時只替換AGENTS.md裏<!-- dsh-ssh:root -->標記塊內的說明，不重複追加。 - 密碼彈窗：主機未配置密鑰或密碼時才詢問；密碼經
setRuntimePassword只存在於 Host 進程內存，不寫文件，DSH 重啓後需重新輸入。
HTTP 端點（面板用）¶
端點 kind: exact，僅接受本機/渲染進程請求，拒絕非迴環地址。主要包括：GET /ssh-panel/api/hosts、POST /ssh-panel/api/connect、POST /ssh-panel/api/exec、上傳/下載、建工作區、讀綁定、切換 root、ls、read 等（下載 ≤64 MB，讀文本 ≤512 KB）。
安裝與啓用¶
前置：DSH 桌面版（profile 目錄 ~/.dsh/profiles/desktop）、Node.js 20+。
- 克隆插件並安裝依賴：
git clone https://github.com/JeremyLyc/dsh-plugin-ssh ~/.dsh/plugins/dsh-plugin-ssh
cd ~/.dsh/plugins/dsh-plugin-ssh && npm install --omit=dev
- 讓 desktop profile 鏈接該包：
cd ~/.dsh/profiles/desktop
pnpm add "link:$HOME/.dsh/plugins/dsh-plugin-ssh" --ignore-scripts
- 在 profile 的
package.json裏把包名加入dsh.profile.bundles（包內cordis.patch.yml會插入ssh-panel條目，註冊面板與四個會話工具）：
{
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-plugin-ssh"]
}
}
}
- 日誌出現
ssh-panel: workspace-scoped tools registered (…)與ssh-panel: endpoints registered at /ssh-panel/api即表示 Host 側就緒；客戶端 bundle 改動後需刷新 DSH 窗口。
兼容性說明：作者在 DSH Desktop 0.2.1-rc.3 上驗證（依賴 sidebar.panellist、conversation.composer.dock 等 slot）。依賴包括 ssh2、@modelcontextprotocol/sdk、zod。
配置主機¶
配置文件默認路徑 ~/.dsh/ssh-hosts.json，可用環境變量 DSH_SSH_HOSTS 指定；會與 ~/.ssh/config 合併。示例：
{
"defaultHost": "prod",
"hosts": {
"prod": {
"host": "10.0.0.10",
"port": 22,
"username": "deploy",
"privateKeyPath": "~/.ssh/id_ed25519",
"remoteRoot": "/srv/app"
},
"legacy": {
"host": "10.0.0.11",
"username": "ops",
"password": "${LEGACY_SSH_PASSWORD}"
}
}
}
常用字段：host / port / username（或 user）、privateKeyPath（支持 ~）、password / passphrase（支持 ${ENV}）、hostKeySha256、strictHostKey、connectTimeoutMs（默認 10000）。未配私鑰且無密碼時會嘗試 id_ed25519 → id_rsa → id_ecdsa。
配置裏已有密鑰或密碼則連接時不彈窗；都沒有則面板彈密碼框。若在 JSON 裏寫密碼，請注意文件權限。
典型用法¶
- 按上文安裝並配置
ssh-hosts.json。 - 在「SSH 遠程」面板選擇主機、驗連；必要時在彈窗輸入密碼。
- 使用「一鍵建遠程工作區」：在本地生成佔位目錄與綁定文件，並在該工作區打開會話。
- 在對話中讓 agent 調用
ssh_exec等工具；README 建議在AGENTS.md生成的遠端目錄塊基礎上，對ssh_exec顯式傳workdir與遠端工作目錄一致。 - 用右側「服務器文件」瀏覽、預覽、切換遠端工作目錄；輸入框下方 pill 會跟隨當前目錄。
開發側可運行倉庫內測試，例如 node test/tools-isolation.mjs 校驗隔離契約；需已配置主機時設置 DSH_SSH_TEST_HOST 等環境變量（見 README「開發」一節）。
適用場景與注意¶
適合：已在用 DSH 桌面版、需要在對話裏操作固定遠端 Linux（部署、查日誌、傳文件），且希望多臺服務器之間由工作區綁定隔離的場景。
務必注意：
- 面板與工具能執行任意遠端命令，能力等價於本機
ssh；HTTP 端點雖限制迴環來源，仍應只在本機可信環境使用。 - 插件在 DSH Host 進程權限下運行；安裝前請閱讀源碼與 MIT 許可證，自行評估風險。
- 命令輸出與文件內容會進入模型上下文；上傳/下載有體積上限（下載 64 MB、請求體 96 MB）。
- 社區目錄 skillhub.cn 爲獨立生態站點，與 DeepSeek / 幻方無官方從屬關係；插件星標等以 GitHub 頁面爲準（README 展示爲社區 star 徽章）。
結尾¶
dsh-plugin-ssh 把「DSH 必須是本地目錄」與「agent 在遠端幹活」統一到遠程工作區綁定與無 host 參數的原生工具上，並輔以側欄文件瀏覽與密碼內存策略。需要細節、截圖與 issue 時，見 GitHub 倉庫 README 與 SkillHub 目錄頁。
