前言¶
在 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 插件页。
