前言¶

在 DSH（DeepSeek Harness）裏讓 Agent 連多臺 Linux 機器，常見做法是手寫腳本或把 SSH 細節塞進提示詞。密碼和私鑰一旦進入模型上下文，就很難收回；rm -rf、sudo 這類命令也缺少統一審批。dsh-plugin-ssh-hosts 把多機 SSH 收成一組 Host 工具：清單、遠程執行、文件讀寫、SFTP 上傳下載、按機 sudo 策略、會話級授權與高風險命令審批，憑據 AES-256-GCM 存在本機，工具參數不接受密碼或私鑰正文。下面介紹它是什麼、怎麼裝、怎麼配、怎麼用。

這是什麼¶

dsh-plugin-ssh-hosts 是可獨立安裝的 DSH Host-only 插件（dsh.bundle.patch），由 zh-Littlebird 維護，npm 包名 dsh-plugin-ssh-hosts，社區分類 admin-security。實現基於純 JS 的 ssh2（無需本機 ssh.exe），支持密碼、私鑰與帶口令私鑰；傳輸走 SFTP。插件通過 @deepseek-ai/dsh-tools 的 defineTool 註冊到 ctx.tools，不改動 Harness 核心。README 記載已在 DSH 0.2.1-rc.2、Node 24.x、Windows 11 下驗證。

核心功能¶

主機清單與認證¶

• 多臺主機、別名唯一，支持增刪改查與 TOFU 主機密鑰。
• 私鑰只按路徑讀取，不復制、不打印；支持 passphrase。
• 每臺主機可配置 allowedPaths（讀）、editablePaths（寫/上傳）、deniedPaths（始終拒絕），並對路徑做 realpath 校驗。
• readOnly: true 時只允許讀/下載，拒絕 ssh_exec 與遠端寫入。

遠程命令與 sudo¶

• ssh_exec 返回退出碼、stdout、stderr、耗時、超時、截斷與原始字節數。
• 每臺服務器可配置 sudo：nopasswd（推薦）或 password（密碼僅本機加密存儲，經 SSH stdin 交給 sudo）。
• 傳 privileged: true 或命令前導 sudo 會走插件託管的提權包裝。

文件與 SFTP¶

• ssh_read_file / ssh_write_file：文本、UTF-8，拒絕二進制。
• ssh_upload / ssh_download：SFTP 流式傳輸，臨時文件落盤後改名。
• 全局 tempDir 默認 /tmp，自動併入每臺主機的可讀可寫策略，適合 Agent 過程文件；設爲空字符串可關閉。

服務目錄說明¶

主機記錄可聲明 services（服務名、目錄、啓動/日誌/端口說明）。Agent 用 ssh_services 直接定位，無需反覆 ls 猜路徑。

授權、審批與審計¶

• 會話/服務器授權：每個新會話首次訪問某臺服務器（或操作主機清單）會向用戶申請一次；換機或新會話需重新申請。處於「完全權限」的會話可按配置自動放行。
• 人工審批：rm -rf、sudo、shutdown、mkfs、dd、防火牆清空、DROP DATABASE 等命中時請求一次性批准；策略可由 highRiskPolicy 設爲 ask / deny / allow。
• 審計：audit.log 記錄動作、主機、用戶、命令/路徑、退出碼、耗時、截斷、審批結果，不含憑據。
• Web 側：命令歷史抽屜（篩選、約 5 秒刷新）、「SSH 服務器」頁面可手動增刪改、測試、錄入或清除密碼/口令（寫接口僅接受本機迴環）。

憑據隔離¶

任何工具參數均不接收密碼、私鑰內容；憑據單獨加密存儲，secretsBackend 可選 file、env 或 none（僅適合無私鑰口令、無密碼的主機）。

安裝與啓用¶

前置條件¶

• DeepSeek Harness >=0.2.1-rc.2 且 <0.3.0（package.json 中 engines.dsh）。
• Node.js >=22.19（推薦 24）。
• 能訪問 npm registry（安裝 ssh2 與 @deepseek-ai/schemastery）。

從源碼構建（可選）¶

維護者文檔中的構建與測試步驟如下：

cd dsh-plugin-ssh-hosts
npm install --legacy-peer-deps
npm run build
npm test

npm run build 輸出到 lib/；npm test 編譯測試到 dist-test/ 並運行 54 個用例。

安裝到 profile¶

建議先裝獨立開發 profile，確認無誤後再裝日常 profile：

# 創建一個獨立的 headless profile（只創建一次）
dsh --profile ssh-dev --from-default-profile headless

# 安裝進該 profile
dsh plugin --profile ssh-dev add dsh-plugin-ssh-hosts

# 確認 bundle 層已出現
dsh --profile ssh-dev --dump-config | Select-String ssh-hosts

# 確認模塊可導入且 Config schema 可讀
dsh --profile ssh-dev --dump-config-schema

Web/Desktop 日常 profile 將 ssh-dev 換成 desktop：

dsh plugin --profile desktop add dsh-plugin-ssh-hosts

也可在 Web 側欄 Plugins 頁面安裝，或由 Agent 調用 plugin_manager 的 install_bundle，target 傳包名 dsh-plugin-ssh-hosts 或本地目錄絕對路徑。

安裝後若 Desktop 已在運行，需重啓 Harness 進程，Host 插件纔會加載。卸載：

dsh plugin --profile desktop remove dsh-plugin-ssh-hosts

插件數據默認在 $DSH_HOME/ssh-hosts（Windows：C:\Users\<你>\.dsh\ssh-hosts）；卸載不會自動刪除該目錄。

配置¶

cordis.patch.yml 自帶默認可用片段，例如：

- insert:
    - id: ssh-hosts
      name: dsh-plugin-ssh-hosts
      config:
        maxOutputBytes: 131072
        timeoutMs: 60000
        maxTimeoutMs: 300000
        highRiskPolicy: ask
        sessionConsent: ask
        trustFullAccess: true
        audit: true
        tempDir: /tmp
        debug: false

常用字段包括：dataDir（可用環境變量 DSH_SSH_HOSTS_DATA_DIR 覆蓋）、timeoutMs / maxTimeoutMs、highRiskPolicy、sessionConsent、trustFullAccess、audit、tempDir、guardCommandEdits、strictCommandPaths 等。修改方式：編輯 profile 的 cordis.patch.yml，或在 Web 插件設置裏改 config。不要把密碼寫進 YAML。

典型用法¶

添加服務器¶

讓 Agent 調用 ssh_host_add（示例字段如下；不接受 password、privateKey、passphrase）：

{
  "name": "ssh_host_add",
  "arguments": {
    "alias": "web-1",
    "host": "10.0.0.10",
    "port": 22,
    "username": "deploy",
    "authType": "password",
    "defaultCwd": "~/app",
    "allowedPaths": ["~/app", "/tmp"],
    "editablePaths": ["~/app"],
    "services": [
      {
        "name": "api",
        "directory": "~/app/api",
        "description": "對外 HTTP API，構建後由 systemd 啓動",
        "startCommand": "sudo systemctl restart api",
        "logPath": "~/app/logs/api.log",
        "port": 8080
      }
    ],
    "tags": ["prod", "web"],
    "fingerprintPolicy": "accept-new"
  }
}

添加成功後通常會得到 credentialStatus: "missing"，需在下一步在本機錄入憑據。

在本機錄入密碼或口令¶

1. Web：「SSH 服務器」→ 編輯目標主機 → 填寫密碼/口令後保存。
2. 本機終端（非 Agent 會話），在插件目錄執行：

node scripts/dsh-ssh.mjs set web-1 --password
node scripts/dsh-ssh.mjs set web-1 --passphrase

經上述步驟後，Agent 即可調用 ssh_exec、ssh_read_file、ssh_upload 等工具，具體工具名以安裝後 dump-config-schema 爲準。

適用場景與注意¶

適合：需要在 DSH 會話裏對多臺 Linux 做運維排查、讀日誌、受限目錄內改配置、SFTP 傳文件，且希望憑據與高風險命令與模型隔離的團隊或個人。

注意：

• 插件以當前 DSH 進程的權限訪問本機數據目錄與網絡；安裝前建議閱讀 GitHub 倉庫 源碼與 MIT 許可證。
• 默認 /tmp 全局可讀，勿把敏感內容直接寫在共享臨時路徑；可按任務建私有子目錄並在結束後刪除。
• 社區目錄 skillhub.cn 插件頁 與 DeepSeek / 幻方無官方從屬關係；DSH 生態主張「一切皆插件」，本介紹事實以倉庫 README 與 package.json（當前版本 1.2.0）爲準。

鏈接¶

• 社區目錄：https://www.skillhub.cn/plugins/zh-Littlebird/dsh-plugin-ssh-hosts
• 源碼與完整說明：https://github.com/zh-Littlebird/dsh-plugin-ssh-hosts