SSH Skill v3.3
高性能 SSH 操作技能，支持守护进程长连接、自动连接复用、跳板机、批量并发、服务器间直接传输、自动错误恢复。
快捷命令
当用户通过 /ssh-skill <参数> 调用本 skill 时，根据参数执行对应操作：
/ssh-skill list
列出所有已配置的服务器。执行以下步骤：
- 运行命令获取数据：
python ~/.claude/skills/ssh-skill/scripts/ssh_config_manager_v3.py list-servers- 解析返回的 JSON 数据
- 以 Markdown 表格 格式展示，列：序号、别名、备注(description)、标签(tags)、位置(location)、认证方式(auth)、用户名(user)
- 在表格末尾显示服务器总数
表格示例格式：
| # | 别名 | 备注 | 标签 | 位置 | 认证 | 用户名 |
|---|------|------|------|------|------|--------|
| 1 | mgmt-01 | 管理服务器 | 管理,Warpgate | 丰台机房 | 密钥 | root |/ssh-skill find <关键词>
查找匹配的服务器，格式同 list。
/ssh-skill help
展示 SSH Skill 的帮助文档。以 Markdown 格式输出以下内容：
SSH Skill v3.3 - 高性能 SSH 操作技能
核心特点：
- 守护进程长连接：首次连接后自动启动守护进程，后续命令响应时间从 ~0.45s 降至 ~0.12s
- 自动连接复用：多个 Claude Code 实例可共享同一守护进程
- SFTP 高级传输：支持断点续传、进度显示、目录递归上传/下载
- 服务器间直接传输：支持服务器到服务器的文件直接传输，无需本地中转
- SSH 隧道：支持本地端口转发，访问远程内网服务（数据库、Web 服务等）
- 跳板机支持：通过 ProxyJump 自动处理多级跳板机
- 批量并发操作：支持对多台服务器并发执行命令
- 自动错误恢复：SSH 连接断开自动重连（最多 3 次）
快捷命令：
/ssh-skill list- 列出所有已配置的服务器/ssh-skill find <关键词>- 查找匹配的服务器/ssh-skill transfer <源> <源路径> <目标> <目标路径>- 服务器间文件传输/ssh-skill tunnel <别名> <端口>- 启动 SSH 隧道/ssh-skill help- 显示此帮助信息
常用操作：
- 执行远程命令：
在 <别名> 上执行 <命令> - 上传文件：
上传 <本地路径> 到 <别名> 的 <远程路径> - 下载文件：
从 <别名> 下载 <远程路径> 到 <本地路径> - 服务器间传输：
从 <源别名> 传输 <路径> 到 <目标别名> 的 <路径> 将 <别名A> 的文件迁移到 <别名B> - SSH 隧道：
建立到 <别名> 的 MySQL 隧道 连接 <别名> 的数据库 访问 <别名> 的内部服务 - 批量操作：
在所有服务器上执行 <命令> 在生产环境服务器上执行 <命令>
配置管理：
- 配置文件位置：
~/.ssh/config - 使用标准 OpenSSH 格式 + 注释元数据
- 支持密钥认证和密码认证
- 支持 ProxyJump 跳板机配置
性能对比：
- 直连模式：单次命令 ~0.45s，连续 10 条 ~4.5s
- 守护进程模式：单次命令 ~0.12s，连续 10 条 ~1.2s
更多详细信息请参考 SKILL.md 文档。
其他参数
将参数作为用户意图理解，按照下方调用规则执行对应的 SSH 操作。
CRITICAL: 调用规则
路径说明
默认路径：~/.claude/skills/ssh-skill/scripts
~会自动展开为用户家目录（Windows 和 Linux 通用）- Windows:
C:\Users\用户名\.claude\skills\ssh-skill\scripts - Linux:
/home/用户名/.claude/skills/ssh-skill/scripts
项目目录中的 skill：如果 skill 放在项目的 .claude/skills/ssh-skill/ 中，使用相对路径：
.claude/skills/ssh-skill/scripts路径自动识别：Python 的 os.path.expanduser() 会自动处理 ~，无需手动替换。
调用格式（唯一正确方式）
MUST: 使用 python ~/.claude/skills/ssh-skill/scripts/脚本名.py 格式。使用别名（alias）标识服务器。
NEVER: 不要使用 cd 到脚本目录再执行，不要使用反斜杠 \，不要直接写 ssh 或 scp 命令。
执行远程命令
python ~/.claude/skills/ssh-skill/scripts/ssh_execute.py <别名> "<命令>"可选参数：--timeout <秒> --no-daemon
ssh_execute.py 会自动检测守护进程：有则走长连接（~0.12s），无则自动启动守护进程。
上传文件
MSYS_NO_PATHCONV=1 python ~/.claude/skills/ssh-skill/scripts/ssh_upload.py <别名> "<本地路径>" "<远程路径>"可选参数：--resume（断点续传） --recursive（目录递归上传） --no-progress（禁用进度输出）
下载文件
MSYS_NO_PATHCONV=1 python ~/.claude/skills/ssh-skill/scripts/ssh_download.py <别名> "<远程路径>" "<本地路径>"可选参数：--resume（断点续传） --recursive（目录递归下载） --no-progress（禁用进度输出）
CRITICAL: 上传/下载命令必须加 MSYS_NO_PATHCONV=1 前缀，防止 Windows MSYS bash 将远程路径（如 /tmp/file）转换为 Windows 路径。
服务器间传输
# 自动模式（推荐）- 根据文件大小和网络环境自动选择最优方式
MSYS_NO_PATHCONV=1 python "~/.claude/skills/ssh-skill/scripts/ssh_server_transfer.py" <源别名> "<源路径>" <目标别名> "<目标路径>"
# 强制直连模式（大文件推荐，数据直接在服务器间传输）
MSYS_NO_PATHCONV=1 python "~/.claude/skills/ssh-skill/scripts/ssh_server_transfer.py" <源别名> "<源路径>" <目标别名> "<目标路径>" --mode direct
# 强制流式转发（小文件或服务器间网络不通时）
MSYS_NO_PATHCONV=1 python "~/.claude/skills/ssh-skill/scripts/ssh_server_transfer.py" <源别名> "<源路径>" <目标别名> "<目标路径>" --mode stream
# 混合模式（先尝试直连，失败后自动降级到流式）
MSYS_NO_PATHCONV=1 python "~/.claude/skills/ssh-skill/scripts/ssh_server_transfer.py" <源别名> "<源路径>" <目标别名> "<目标路径>" --mode hybrid
# 使用 rsync（仅直连模式，支持增量同步）
MSYS_NO_PATHCONV=1 python "~/.claude/skills/ssh-skill/scripts/ssh_server_transfer.py" <源别名> "<源路径>" <目标别名> "<目标路径>" --use-rsync可选参数：--mode <auto|direct|stream|hybrid>（传输模式） --use-rsync（使用 rsync） --no-progress（禁用进度） --size-threshold <MB>（大小阈值，默认 10） --timeout <秒>（超时，默认 300）
传输模式说明：
| 模式 | 适用场景 | 数据流向 | 优点 |
|---|---|---|---|
| 直连 (direct) | 大文件、服务器间网络通 | 源服务器 → 目标服务器 | 速度快，不占本地带宽 |
| 流式 (stream) | 小文件、网络不通 | 源 → 本地 → 目标（流式） | 无需服务器间配置 |
| 混合 (hybrid) | 不确定环境 | 先尝试直连，失败降级 | 自动适应 |
| 自动 (auto) | 默认 | 智能判断 | 最优选择 |
CRITICAL: 服务器间传输命令也必须加 MSYS_NO_PATHCONV=1 前缀。
批量操作
# 对所有服务器执行
python "~/.claude/skills/ssh-skill/scripts/ssh_cluster.py" "<命令>" --parallel
# 对指定别名列表执行
python "~/.claude/skills/ssh-skill/scripts/ssh_cluster.py" "<命令>" --hosts "DEV-002,DEV-003" --parallel
# 按环境过滤
python "~/.claude/skills/ssh-skill/scripts/ssh_cluster.py" "<命令>" --environment production --parallel
# 按标签过滤
python "~/.claude/skills/ssh-skill/scripts/ssh_cluster.py" "<命令>" --tags "web,nginx" --parallel可选参数：--timeout <秒> --health-check --max-workers <数量>
配置管理
# 列出所有服务器
python "~/.claude/skills/ssh-skill/scripts/ssh_config_manager_v3.py" list-servers
# 按环境过滤
python "~/.claude/skills/ssh-skill/scripts/ssh_config_manager_v3.py" list-servers --environment production
# 查找服务器（支持别名和描述模糊查找）
python "~/.claude/skills/ssh-skill/scripts/ssh_config_manager_v3.py" find "<关键词>"
# 创建配置
python "~/.claude/skills/ssh-skill/scripts/ssh_config_manager_v3.py" create --alias <别名> --host <IP> --user <用户名> --key <密钥文件> --environment <环境>
# 更新配置（只更新提供的字段，其他字段保持不变）
python "~/.claude/skills/ssh-skill/scripts/ssh_config_manager_v3.py" update <别名> --description "新描述" --tags tag1 tag2 tag3
python "~/.claude/skills/ssh-skill/scripts/ssh_config_manager_v3.py" update <别名> --environment production --location "新位置"
python "~/.claude/skills/ssh-skill/scripts/ssh_config_manager_v3.py" update <别名> --host <新IP> --port <新端口>
# 删除配置
python "~/.claude/skills/ssh-skill/scripts/ssh_config_manager_v3.py" delete <别名>SSH Tunnel（端口转发）
本地端口转发 - 通过 SSH 隧道访问远程服务
# 启动 tunnel（自动分配本地端口）
python "~/.claude/skills/ssh-skill/scripts/ssh_tunnel.py" start <别名> --remote-port <端口>
# 指定本地端口
python "~/.claude/skills/ssh-skill/scripts/ssh_tunnel.py" start <别名> --local-port <本地端口> --remote-port <远程端口>
# 转发到远程的其他主机
python "~/.claude/skills/ssh-skill/scripts/ssh_tunnel.py" start <别名> --remote-host <远程主机> --remote-port <端口>
# 列出所有活动的 tunnel
python "~/.claude/skills/ssh-skill/scripts/ssh_tunnel.py" list
# 查看 tunnel 状态
python "~/.claude/skills/ssh-skill/scripts/ssh_tunnel.py" status <tunnel-id>
# 停止 tunnel
python "~/.claude/skills/ssh-skill/scripts/ssh_tunnel.py" stop <tunnel-id>
# 停止服务器的所有 tunnel
python "~/.claude/skills/ssh-skill/scripts/ssh_tunnel.py" stop-all <别名>使用场景：
- 连接远程数据库（MySQL、PostgreSQL、Redis）
- 访问内部 Web 服务（管理后台、监控面板）
- 调试内部 API 接口
- 访问其他内部服务（Elasticsearch、RabbitMQ）
特性：
- 守护进程模式运行
- 自动重连和心跳检测
- 空闲 30 分钟自动退出
- 支持跳板机（ProxyJump）
- 只监听 localhost（安全）
示例：
# 连接远程 MySQL
python ssh_tunnel.py start prod-db-01 --remote-port 3306
# 返回：本地端口 10001
# 使用 tunnel 连接数据库
mysql -h 127.0.0.1 -P 10001 -u root -p
# 访问内部 Web 服务
python ssh_tunnel.py start prod-web-01 --remote-port 8080
# 然后在浏览器访问 http://127.0.0.1:10002配置文件
存储位置
~/.ssh/config（标准 OpenSSH 配置文件）
配置格式
每个服务器由 Host 块和注释元数据组成：
# ===== prod-web-01 =====
# description: 生产环境 Web 服务器
# environment: production
# tags: web,nginx,production
# location: 阿里云-北京
# password:
# created_at: 2026-03-01 12:00:00
# updated_at: 2026-03-01 12:00:00
Host prod-web-01
HostName 192.168.1.100
User root
IdentityFile ~/.ssh/id_rsa
Port 22密码认证配置
密码存储在注释中（SSH config 不原生支持密码字段）：
# ===== dev-server =====
# description: 开发服务器
# environment: development
# password: your-password
Host dev-server
HostName 192.168.1.200
User root
Port 22注意：密码认证性能较低，建议升级为密钥认证。
跳板机配置
使用标准 ProxyJump：
Host bastion
HostName bastion.example.com
User jumpuser
IdentityFile ~/.ssh/jump_key
Host internal-server
HostName 10.0.1.100
User appuser
IdentityFile ~/.ssh/id_rsa
ProxyJump bastionAI 只需要知道 internal-server 这个别名，底层自动处理跳转。
守护进程（长连接模式）
工作原理
守护进程在本地维护到远程服务器的 Paramiko 长连接，通过本地 TCP 接受命令请求。 ssh_execute.py 自动检测守护进程：有则复用长连接，无则自动启动。
自动模式（推荐）
ssh_execute.py 首次调用时会自动启动守护进程，无需手动操作。 守护进程空闲 30 分钟后自动退出。
手动管理
# 启动守护进程（通常不需要手动启动）
python "~/.claude/skills/ssh-skill/scripts/ssh_daemon.py" start <别名>
# 查看守护进程状态
python "~/.claude/skills/ssh-skill/scripts/ssh_daemon.py" status <别名>
# 停止守护进程
python "~/.claude/skills/ssh-skill/scripts/ssh_daemon.py" stop <别名>可选参数：--idle-timeout <秒>（默认 1800，即 30 分钟）
守护进程特性
- 每台服务器独立守护进程，按别名隔离
- 多个对话（多个 Claude Code 实例）可共享同一守护进程
- SSH 连接断开自动重连（最多 3 次）
- 每 60 秒心跳检测连接状态
- 空闲超时自动退出，无需手动清理
性能对比
| 模式 | 单次命令 | 连续 10 条 | 连续 30 条 |
|---|---|---|---|
| 直连 | ~0.45s | ~4.5s | ~13.5s |
| 守护进程 | ~0.12s | ~1.2s | ~3.6s |
性能优化建议
命令合并
对同一服务器的多个独立查询，优先合并为一次调用：
# 好：一次调用获取多个信息
python "SCRIPTS/ssh_execute.py" DEV-002 "hostname && uptime && df -h && free -m"
# 差：多次调用分别获取
python "SCRIPTS/ssh_execute.py" DEV-002 "hostname"
python "SCRIPTS/ssh_execute.py" DEV-002 "uptime"
python "SCRIPTS/ssh_execute.py" DEV-002 "df -h"
python "SCRIPTS/ssh_execute.py" DEV-002 "free -m"何时合并，何时分开
- 合并：多个只读查询、状态检查、信息收集
- 分开：命令之间有依赖关系、需要根据前一个结果决定下一步、需要独立的错误处理
输出格式
所有脚本输出 JSON 格式：
{
"success": true,
"exit_code": 0,
"stdout": "命令输出",
"stderr": ""
}故障排查
连接超时
检查：网络连接、服务器是否在线、防火墙规则、跳板机是否可达。
长命令可加 --timeout 300 延长超时。
守护进程问题
如果守护进程异常，可手动停止后重试：
python "~/.claude/skills/ssh-skill/scripts/ssh_daemon.py" stop <别名>或使用 --no-daemon 参数跳过守护进程直连：
python "~/.claude/skills/ssh-skill/scripts/ssh_execute.py" <别名> "<命令>" --no-daemon别名不存在
如果提示别名不存在，可通过配置管理工具查找：
python "~/.claude/skills/ssh-skill/scripts/ssh_config_manager_v3.py" find "<关键词>"强制规则
- 所有 SSH 操作必须通过本 skill 的 Python 脚本
- 禁止直接写
ssh或scp命令（首次配置公钥除外） - 路径必须使用正斜杠
/，不要使用反斜杠\ - 不要用
cd切换到脚本目录，直接用完整路径调用 - 使用别名（alias）标识服务器，不再使用 JSON 配置文件路径
- 对同一服务器的多个只读查询，优先合并为一次调用
依赖
- Python 3.8+
- paramiko（SSH 连接和文件传输）