ssh-dev-suite

SSH远程开发套件 -- 连接管理、命令执行、文件传输、项目部署、端口隧道、远程调试、长耗时任务管理。

功能概述

ssh-dev-suite 是一个面向远程开发场景的综合工具套件，通过 SSH 协议为 AI Agent 提供完整的远程服务器操作能力。支持多 profile 管理、ControlMaster 会话复用、容器感知（docker/kubectl）、跨会话任务恢复。

模块概览

模块	功能	路由方式	说明
connect	连接管理、命令执行、文件传输、后台任务	自动路由	核心模块，其他模块依赖
deploy	项目部署与回滚	显式调用	高副作用，必须用户明确指示
tunnel	端口转发与代理	自动路由	网络失败时自动触发proxy
debug	结构化远程问题排查	自动路由	服务异常时自动进入
long-task	长耗时任务管理、checkpoint记忆、跨会话恢复	自动路由	耗时>2min自动启用

自动路由 = Agent可根据上下文自动选择该模块。 显式调用 = Agent必须等待用户明确指示后才能执行，不可自动触发。

安装

Claude Code

将本仓库克隆到本地，在 Claude Code 的 settings.json 中添加为 skill：

git clone <repo-url> /path/to/ssh-dev-suite

# 在 Claude Code settings.json 中添加：
# "skills": ["/path/to/ssh-dev-suite"]

Codex

将本仓库作为 skill 目录挂载到 Codex 工作区：

git clone <repo-url> /path/to/ssh-dev-suite

# 在 Codex 配置中引用 skill 路径

依赖

• 必需：Python 3、PyYAML（pip install pyyaml）、SSH 客户端
• 推荐：rsync（文件传输优先使用，回退 scp）、sshpass（密码认证时需要）

兼容性

• 平台：
  • 客户端：Windows（Git Bash/MSYS2）、macOS、Linux
  • 服务端：Linux
• AI Agent 兼容：Claude Code + Codex（Tier A）
• Windows 客户端注意：ControlMaster 不可用（脚本已自动跳过）、PATH 环境变量展开差异

快速开始

配置连接

帮我配置SSH连接到我的开发服务器

Agent会引导填写服务器信息，自动生成config.yaml。参考 config.example.yaml。

命令包装器

命令	用途
/ssh-connect [profile] [command]	连接测试、远程执行、文件传输
/ssh-tunnel [profile] [mode]	端口转发、代理管理
/ssh-deploy [profile] [environment]	项目部署与回滚（显式调用）
/ssh-debug [profile] [symptom]	远程问题排查
/ssh-long-task [profile] [task]	长耗时任务管理

常用Prompt示例

连接与执行：

• 测试一下 dev-server 的连接
• 在 dev-server 上执行 ls -la
• 帮我在远程启动一个后台训练任务

部署：

• 帮我把当前项目部署到dev-server
• 回滚上一次部署
• 帮我配置部署流程

隧道：

• 帮我把远程服务器的5432端口映射到本地
• 服务器没有外网，帮我设置代理
• 看看现在有哪些隧道在运行

调试：

• 服务器上的 my-app 服务挂了，帮我排查
• 检查一下 dev-server 的资源使用情况
• 帮我看看 GPU 状态

长耗时任务：

• 帮我在远程启动模型训练，预计2小时
• 检查任务 job-20260306-143022 的状态
• 把远程任务日志流式输出到本地文件

环境变量设置

密码通过环境变量管理，不写入配置文件。

Windows：

setx SSH_DEV_PASSWORD "你的密码"

macOS / Linux：

echo 'export SSH_DEV_PASSWORD="你的密码"' >> ~/.bashrc
source ~/.bashrc

认证方式

方式	说明
SSH密钥（推荐）	config.yaml设置identity_file，最安全便捷
密码	config.yaml设置env_password为环境变量名，依赖sshpass

优先级：SSH密钥 > 环境变量密码 > 交互式提示

目录结构

ssh-dev-suite/
  SKILL.md                  # 套件入口（Agent读取）
  README.md                 # 本文档
  LICENSE                   # MIT
  config.example.yaml       # 配置模板
  _lib/
    _python.sh              # Python检测与平台适配
    ssh-config.py           # 配置解析
  connect/
    SKILL.md                # 连接模块说明
    scripts/
      ssh-test.sh           # 连接测试
      ssh-exec.sh           # 远程命令执行
      ssh-upload.sh         # 文件上传
      ssh-download.sh       # 文件下载
      ssh-job.sh            # 后台任务管理
  deploy/
    SKILL.md                # 部署模块说明
    scripts/
      ssh-deploy.sh         # 部署与回滚
  tunnel/
    SKILL.md                # 隧道模块说明
    scripts/
      ssh-tunnel.sh         # 隧道管理
  debug/
    SKILL.md                # 调试模块说明
  long-task/
    SKILL.md                # 长任务模块说明
    scripts/
      checkpoint.sh         # Checkpoint读写
  references/
    skill-manifest.md       # 元数据清单
  evals/
    trigger-eval.json       # 触发评估数据
    task-prompts/           # 代表性场景
    acceptance.md           # 通过标准

注意事项

• 配置由agent引导生成，无需手动编辑
• config.yaml含敏感信息不入库（已在.gitignore中排除）
• 会话复用：首次连接后SSH保持连接（默认600秒）
• 容器支持：配置container字段后命令自动在容器内执行
• 跳板机：配置jump_host后自动中转
• 网络问题自动处理：远程命令因网络不通失败时，Agent 会自动使用 tunnel 模块建立反向代理

许可证

MIT License