🇺🇸English

SSH Skill v3.2

高性能 SSH 操作技能，支持守护进程长连接、自动连接复用、跳板机、批量并发、服务器间直接传输、自动错误恢复。

快捷命令

当用户通过 /ssh-skill <参数> 调用本 skill 时，根据参数执行对应操作：

/ssh-skill list

列出所有已配置的服务器。执行以下步骤：

1. 运行命令获取数据：

python ~/.claude/skills/ssh-skill/scripts/ssh_config_manager_v3.py list-servers

1. 解析返回的 JSON 数据
2. 以 Markdown 表格 格式展示，列：序号、别名、备注(description)、标签(tags)、位置(location)、认证方式(auth)、用户名(user)
3. 在表格末尾显示服务器总数

表格示例格式：

| # | 别名 | 备注 | 标签 | 位置 | 认证 | 用户名 |
|---|------|------|------|------|------|--------|
| 1 | mgmt-01 | 管理服务器 | 管理,Warpgate | 丰台机房 | 密钥 | root |

/ssh-skill find <关键词>

查找匹配的服务器，格式同 list。

/ssh-skill help

展示 SSH Skill 的帮助文档。以 Markdown 格式输出以下内容：

SSH Skill v3.2 - 高性能 SSH 操作技能

核心特点：

• 守护进程长连接：首次连接后自动启动守护进程，后续命令响应时间从 ~0.45s 降至 ~0.12s
• 自动连接复用：多个 Claude Code 实例可共享同一守护进程
• SFTP 高级传输：支持断点续传、进度显示、目录递归上传/下载
• 服务器间直接传输：支持服务器到服务器的文件直接传输，无需本地中转
• 跳板机支持：通过 ProxyJump 自动处理多级跳板机
• 批量并发操作：支持对多台服务器并发执行命令
• 自动错误恢复：SSH 连接断开自动重连（最多 3 次）

快捷命令：

• /ssh-skill list - 列出所有已配置的服务器
• /ssh-skill find <关键词> - 查找匹配的服务器
• /ssh-skill transfer <源> <源路径> <目标> <目标路径> - 服务器间文件传输
• /ssh-skill help - 显示此帮助信息

常用操作：

1. 执行远程命令：

   在 <别名> 上执行 <命令>
   

2. 上传文件：

   上传 <本地路径> 到 <别名> 的 <远程路径>
   

3. 下载文件：

   从 <别名> 下载 <远程路径> 到 <本地路径>
   

4. 服务器间传输：

   从 <源别名> 传输 <路径> 到 <目标别名> 的 <路径>
   将 <别名A> 的文件迁移到 <别名B>
   

5. 批量操作：

   在所有服务器上执行 <命令>
   在生产环境服务器上执行 <命令>
   

配置管理：

• 配置文件位置：~/.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）

传输模式说明：

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/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 bastion

AI 只需要知道 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 秒心跳检测连接状态
• 空闲超时自动退出，无需手动清理

性能对比

性能优化建议

命令合并

对同一服务器的多个独立查询，优先合并为一次调用：

# 好：一次调用获取多个信息
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 连接和文件传输）

Weekly Installs

1

Repository

badseal/ssh-skill

GitHub Stars

7

First Seen

1 day ago

Security Audits

Gen Agent Trust HubFailSocketFailSnykWarn

Installed on

opencode1

codex1

claude-code1

codebuddy1