前言¶
在 DeepSeek Harness（DSH）裏做聯網或運維相關能力時，常見做法是自己在對話裏拼 SSH 命令，或另開終端窗口切主機。主機一多，在線狀態、資源佔用和文件傳輸就分散在不同工具裏，會話上下文也很難和「當前連的是哪臺機」對齊。
下面介紹社區插件 dsh-server-box（維護者 hoshino114）：在 DSH Web 側提供服務器卡片儀表盤、指標趨勢、xterm 交互終端和 SFTP 文件傳輸，臺賬與密鑰落在本機 ~/.dsh/。項目原名 dsh-server-deck（meyaomiao/DSH-server-deck），現倉庫爲 hoshino114/dsh-server-box；SkillHub 分類爲「聯網工具」。許可證爲 MIT，當前 package 版本 0.5.0，主線對應 DSH 0.1.5-rc.1 / 0.1.5-rc.2 及之後 0.1.5 線。
這是什麼¶
dsh-server-box 是 DSH 的 host + web client 能力插件：Host 半區提供僅迴環放行的 REST、WebSocket PTY 橋和 SFTP 接口；Client 半區在側邊欄（或獨立抽屜）展示「服務器」頁籤，用 React 渲染卡片、趨勢圖、終端和文件瀏覽器。
它解決的是：在本機 DSH 進程權限下，集中維護 SSH 主機臺賬、週期性採集快照、本地落盤趨勢，並在瀏覽器裏點卡片進 shell 或傳文件——與純對話工具互補，但不替代你在遠端的真實運維流程。
卡片儀表盤與自動刷新¶
每臺主機一張卡，元素包括：
- 狀態點：在線（帶呼吸光暈）、離線、探測中、未知。
- 系統信息：OS 名稱、運行時長、CPU 核數、握手延遲。
- CPU / 內存 / 磁盤三條用量條（<60% 綠、≥60% 黃、≥85% 紅）。
- 網速與本月流量（Linux 約 1s 採樣；跳過 lo、docker、veth 等虛擬網卡）。
- 離線時內聯展示失敗原因。
刷新策略可選 手動 / 10s / 15s / 30s / 60s；讀的是主機側快照，不再爲刷新單獨現場 SSH。「刷新」按鈕會強制立即探測一輪。
趨勢視圖與本地指標¶
卡片視圖與趨勢視圖可切換（不在卡片內疊圖）。每臺主機 CPU、內存、磁盤各一張獨立圖。
| 能力 | 說明 |
|---|---|
| 時間窗口 | 1 小時（滾動，默認）、24 小時（滾動）、一週、一個月（本地自然日 0 點起，含今天）、自定義（≤31 天） |
| 粒度 | 自動 / 10s / 30s / 1m / 5m / 15m / 1h；單次查詢上限 1200 點，超限自動升檔 |
| 採集 | 主機側常駐，默認 10s（可選 30s / 1m / 5m），與面板是否打開無關 |
| 落盤 | ~/.dsh/server-box-metrics/{hostId}/；刪除主機會級聯清理 |
打開「服務器」頁籤 → 工具欄點「📈 趨勢」。剛啓用時曲線可能只有右側一小段，等幾個採集週期會鋪開。窗口早於本地記錄時，可嘗試用 sar -u / sar -r（sysstat）回填 CPU / 內存；磁盤容量無法回填。
交互終端與文件傳輸¶
終端：點卡片進入 xterm.js 終端（5000 行回滾、256 色、尺寸同步）。Node 側用 WebSocket ↔ ssh2 shell 橋接。Web 端 WS 按頁面 Host origin 派生；DSH 桌面端（dsh-app://app）按 __DSH_TRANSPORT__.streamBaseUrl 派生 ws://127.0.0.1:<port>/server-box/ws/pty（0.5.x 修復桌面端 WebSocket 報錯）。
SFTP：卡片或趨勢卡上的「📁 文件」、終端頁頭快捷入口，進入遠端目錄瀏覽器——列目錄、上傳、下載、新建目錄、刪除（非空目錄會先提示再遞歸）。傳輸在連接池內另開 SFTP 通道，用完即關；API 掛在 /server-box/api/hosts/<id>/files*，與 REST / PTY 一樣 僅迴環放行。
對話工具（同一條 SSH 連接池，不經過卡片 xterm）：
server_box_upload：本機 → 遠端server_box_download：遠端 → 本機
深鏈 #sd-files/<hostId> 可直開某臺主機的文件視圖。
主機臺賬：導入與添加¶
- 一鍵導入
~/.ssh/config：解析Host/HostName/User/Port/IdentityFile/ProxyJump；跳過Host *、已存在主機，以及 Git 託管平臺密鑰別名（如Host github.com-xxx、User git）；多別名行優先用語義化別名做展示名。 - 手動添加：支持密碼、私鑰文件（含口令）、SSH Agent；提供連接測試與延遲反饋。
臺賬文件：~/.dsh/server-box.json；密碼與私鑰口令：~/.dsh/server-box.secrets.json（0600）。從舊名 dsh-server-deck 升級時，首次啓動會自動遷移 server-deck.json → server-box.json、指標目錄 server-deck-metrics/ → server-box-metrics/，路由前綴由 /server-deck/* 改爲 /server-box/*，對話工具由 server_deck_* 改爲 server_box_*。
頁籤掛載方式¶
| 環境 | 形態 |
|---|---|
| DSH 0.1.5+ | 優先註冊官方原生右側欄（ctx.sidebarRightTabs） |
| 安裝了 dsh-better-sidebar | 也可作爲側邊欄「🖥 服務器」頁籤（order 45） |
| 未安裝上述擴展 | 自繪右側可展開/收起面板，寬度可拖曳並持久化 |
裝載順序無關；client 不聲明強制依賴，由內層等待服務就緒後註冊頁籤。
安裝與啓用¶
插件以 web profile 安裝；安裝後需 重啓 dsh web（Host 半新增路由與常駐採集器），瀏覽器 Ctrl+F5 強刷。側邊欄「+」菜單出現「服務器」頁籤即表示裝載成功。
# 方式一：從 GitHub 直接裝（dsh CLI，推薦）
dsh plugin --profile web add github:hoshino114/dsh-server-box
# 方式三：npm（發佈到 npm 後可用）
dsh plugin --profile web add dsh-server-box
README 還給出克隆倉庫後 pnpm install && pnpm build 再 dsh plugin --profile web add . 的本地掛載方式；日常安裝以上述 CLI 命令爲準即可。
典型用法¶
- 按上一節安裝並重啓
dsh web，強刷頁面。 - 在「服務器」頁籤導入 ssh config 或手動添加主機，用連接測試確認可達。
- 在卡片視圖查看在線狀態與 CPU / 內存 / 磁盤；按需改自動刷新間隔。
- 需要歷史曲線時切到「趨勢」，選 1h / 24h / 7d / 30d 或自定義窗口。
- 點卡片打開 xterm；傳文件用「📁 文件」或在對話裏調用
server_box_upload/server_box_download。 - 其它對話工具（同池、非交互）：
server_box_hosts、server_box_exec等，見倉庫 README 與安全模型說明。
適用場景與注意¶
適合：已在 DSH Web 或桌面端日常開發、需要在同一界面維護少量到中等數量 Linux / macOS / BSD / Windows OpenSSH 主機，並希望指標與終端、文件操作不離開 DSH 的用戶。
務必注意：
- 插件運行在 當前
dsh進程的權限 下；SSH 臺賬與 secrets 在本機磁盤，安裝前請閱讀源碼與 MIT 許可證。 - 所有
/server-box/api/*、PTY、文件接口 僅允許迴環（127.0.0.1/::1），降低 DNS rebinding 與局域網直連風險；API 永不回傳 密碼與私鑰口令。 - 指標探針：Linux / macOS / BSD 走只讀 POSIX sh；Windows OpenSSH 無 sh 時用 PowerShell CIM；解析失敗字段顯示「—」。
- 版本線：0.5.x 爲當前主線（含 SFTP、桌面 WS 修復）；更老的 DSH（≤0.1.2-rc.1）需對照 README 兼容性表選擇 0.2.x 等維護分支。
DSH 生態強調「一切皆插件」；SkillHub 目錄 是社區站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-server-box 把多臺 SSH 主機的狀態、趨勢、終端和 SFTP 收進 DSH 右側「服務器」頁籤，臺賬與指標留在本機，API 與傳輸走回環與連接池。若要安裝或提 Issue，見 GitHub 倉庫 與 SkillHub 插件頁。
