ssh-lab — 远程服务器 SSH 工作台

面向远程 GPU 服务器管理的结构化 SSH 操作工具。 将通用能力（GPU / 磁盘 / 进程）标准化，交由 LLM 解释具体语义。

适用场景

• 用户询问 GPU 状态、服务器健康状况、远程进程信息
• 需检查训练是否正在运行、磁盘是否已满、GPU 是否空闲
• 在远程服务器上执行命令
• 实时追踪远程日志文件、列出 checkpoint 文件
• 在本地与远程之间传输文件（基于 rsync）
• 并排对比多台主机（GPU、磁盘、进程状态）
• 为 GPU 空闲、磁盘满载、进程异常退出等事件配置告警
• 任何提及以下关键词的场景：ssh-lab、gpu status、server status、nvidia-smi、remote server

安装与构建

cd /path/to/ssh-lab && npm run build

构建完成后，可通过以下任一方式使用 CLI：

ssh-lab status all          # 若已通过 npm link 或全局安装
npx ssh-lab status all      # 通过 npx 调用
node dist/cli.js status all # 直接执行编译产物

CLI 自动读取 ~/.ssh/config —— 对于已有 SSH 主机，无需额外配置。

命令列表

列出主机

ssh-lab hosts [--json]

服务器状态（GPU + 磁盘 + 进程）

ssh-lab status [host|all] [--json] [--timeout ms] [--heartbeat] [--quiet]

返回结构化的探测数据：GPU 利用率 / 显存占用 / 温度、磁盘使用率、活跃进程列表。 内置自动告警机制：GPU 空闲、磁盘满载（>90%）、温度过高（>85°C）。 --heartbeat 输出精简的一行格式，适用于 agent 集成；--quiet 抑制“一切正常”类输出（适合 cron 场景）。

执行远程命令

ssh-lab run   [--json] [--timeout ms]

支持 all 参数，在所有主机上并行执行命令。

追踪远程日志文件

ssh-lab tail   [-n lines] [--json]

默认显示最后 50 行；内容超过 50KB 时智能截断。

列出远程目录内容

ssh-lab ls   [--sort time|size|name] [--json]

显示文件大小、修改时间、权限等元信息，特别适用于 checkpoint 目录查看。

磁盘使用情况

ssh-lab df  [path] [--json]

显示所有挂载文件系统的磁盘使用情况；若指定 path，则对目标目录执行 du -sh。

文件同步（rsync）

ssh-lab sync    [--direction up|down] [--dry-run] [--exclude pat1,pat2]

传输方向：down（远程 → 本地，默认），up（本地 → 远程）。 务必先使用 --dry-run 预览操作！

监控文件变更（快照式轮询）

ssh-lab watch   [-n lines] [--prev-hash hash] [--json]

捕获文件内容及元数据（如大小、修改时间等）。当提供 --prev-hash 时，返回 changed: true/false。 Agent 可通过 cron 或 heartbeat 频繁调用该命令——本工具自身无状态。

主机间对比（并排展示）

ssh-lab compare   [--probes gpu,disk,process] [--json]
ssh-lab compare all [--probes gpu]
ssh-lab compare GMI4 GMI5 GMI6 --probes gpu,disk

跨主机并排对比 GPU、磁盘、进程等维度的数据。 --probes 默认为 gpu,disk,process，支持任意数量主机。 采用有界并发池（bounded concurrency pool）实现并行数据采集。

诊断工具（doctor）

ssh-lab doctor  [--json] [--timeout ms]

对指定主机运行连通性与健康诊断：检查 SSH 可达性、认证有效性、命令执行能力，以及基础系统健康状态。

告警管理

# 列出已配置的告警规则
ssh-lab alert list [--json]

# 添加一条告警规则
ssh-lab alert add   [--threshold N] [--process-pattern regex]

# 删除一条告警规则
ssh-lab alert remove 

# 基于当前实时状态评估告警
ssh-lab alert check [host|all] [--json] [--quiet]

支持的告警类型：gpu_idle、disk_full、process_died、ssh_unreachable、oom_detected、high_temp

使用示例：

ssh-lab alert add disk_full all --threshold 90
ssh-lab alert add process_died GMI4 --process-pattern "torchrun|deepspeed"
ssh-lab alert check all --json

添加自定义主机

ssh-lab add   [--port N] [--tags a,b] [--notes "desc"]

输出模式

所有命令均支持三种输出格式：

• summary（默认）：带格式的人类可读文本
• json（--json 或 -j）：结构化 JSON，便于程序解析
• raw（--raw 或 -r）：仅返回原始命令输出

超时分级策略

各命令采用预设的超时分级（用户显式指定 --timeout 将始终覆盖默认值）：

• quick（5 秒）：hosts、add、doctor —— 用于连通性检测
• standard（15 秒）：status、run、ls、df、alert、compare —— 常规探测任务
• stream（30 秒）：tail、watch —— 流式日志追踪
• transfer（60 秒）：sync —— rsync 批量传输

架构设计

• 探测系统（Probe system）：插件化探测模块（gpu / disk / process），采集结构化数据
• 基于 child_process 的 SSH 调用：直接调用系统原生 ssh 命令，继承用户的 SSH 配置、密钥及 ProxyJump 设置
• ControlMaster 复用机制：通过 /tmp/ssh-lab-%r@%h:%p 套接字复用持久化 SSH 连接；自动清理陈旧套接字（通过 ssh -O check 检测）、优雅关闭连接（ssh -O exit），并在重试前移除失效套接字文件
• 重试与错误分类：瞬态失败自动指数退避重试；错误按类型分类（如 AUTH_FAILED / TIMEOUT 等），并附带修复提示
• 分级超时策略：按命令类型设定默认超时值 —— quick（5s）用于 doctor/add，standard（15s）用于 status/run/ls/df/compare/alert，stream（30s）用于 tail/watch，transfer（60s）用于 sync；--timeout 始终优先
• 并行执行支持：status all 和 run all 使用 withPool（默认并发数为 5）并发查询全部主机
• 告警系统：内置 6 类可配置阈值的告警规则
• 零运行时依赖：无任何生产环境 npm 依赖，仅含开发依赖（typescript、@types/node）
• SSH 配置主机使用别名：来自 ~/.ssh/config 的主机直接使用其 SSH 别名，完整兼容 ProxyJump / Match / Include 等高级配置规则

心跳集成（Heartbeat Integration）

参见 HEARTBEAT.md：

- [ ] 执行：ssh-lab status all --heartbeat
  检查项：GPU 空闲、磁盘 >90%、进程异常退出
- [ ] 执行：ssh-lab alert check all --json
  对任意触发的关键告警及时响应

配置文件

自定义主机信息存储于 ~/.config/ssh-lab/config.json（自动创建，符合 XDG Base Directory 规范）。 ~/.ssh/config 中定义的 SSH 主机通过 ssh -G 自动发现。 可通过环境变量 SSH_LAB_CONFIG 覆盖默认配置路径。