通过 SSH 进行远程工作
连接详情存储在项目文件夹中的 ssh.md 文件中。每次远程会话前请先读取它。切勿猜测主机、用户、端口、密钥路径或密码。
何时激活
- 用户要求连接、登录或在远程机器上运行某些操作
- 用户要求检查、编辑、构建或测试远程项目
- 用户提到服务器、VPS 或远程主机，并期望使用 SSH 访问
步骤 1：定位 ssh.md
项目文件夹通过 git rev-parse --show-toplevel 获取，如果该命令失败则使用当前目录。ssh.md 始终位于 <项目文件夹>/ssh.md。
如果该文件不存在，则根据模板创建并告知用户填写：
- 查找
ssh.example.md。它位于此技能文件夹中，具体路径取决于代理。按顺序检查以下路径并使用第一个存在的路径：.agents/skills/remote-work-ssh/、.claude/skills/remote-work-ssh/、.opencode/skills/remote-work-ssh/、~/.agents/skills/remote-work-ssh/、~/.claude/skills/remote-work-ssh/、~/.config/opencode/skills/remote-work-ssh/。如果都不存在，运行find ~ -path '*remote-work-ssh*' -name ssh.example.md 2>/dev/null | head -n 1。 - 将其复制到
<项目文件夹>/ssh.md。 - 将
ssh.md添加到项目的.gitignore文件中（如果尚未添加）。如果需要，创建.gitignore。 - 停止并告知用户填写
ssh.md。
步骤 2：验证配置
ssh.md 包含一个 YAML 块。检查以下字段：
auth必须是alias、key或password。remote_project_path必须设置。- 所选方法对应的字段必须设置：
auth | 必填字段 |
|---|---|
alias | alias |
key | host、user、identity_file（port 默认为 22） |
password | host、user、password_env（port 默认为 22） |
如果缺少必填字段或 auth 未知，停止并报告具体哪个字段有误。不要回退到其他方法。
步骤 3：连接
alias
首先解析别名，然后连接：
ssh -G <alias> | grep -E '^(hostname|user|port) '
ssh -o BatchMode=yes <alias> 'hostname && whoami'
key
- 确认
identity_file存在。如果不存在，停止。 - 仅使用该密钥：
ssh -o BatchMode=yes -o IdentitiesOnly=yes -i <identity_file> -p <port> <user>@<host> 'hostname && whoami'
- 如果设置了
proxy_jump，添加-J <proxy_jump>。
password
- 使用
command -v sshpass检查sshpass是否已安装。如果缺失，停止并告知用户安装它。 - 检查由
password_env命名的环境变量是否已设置，无需打印其值。 - 通过
SSHPASS环境变量和-e将值传递给sshpass。不要将密码放在命令行参数或任何输出中。 - 禁用基于密钥的尝试，仅使用密码：
SSHPASS="$(printenv <password_env>)" sshpass -e ssh -o PubkeyAuthentication=no -o PreferredAuthentications=password -p <port> <user>@<host> 'hostname && whoami'
- 如果设置了
proxy_jump，添加-J <proxy_jump>。 - 此处不要使用
BatchMode=yes，因为它会禁用密码认证。
主机密钥（所有方法）
- 如果主机密钥未知或已更改，停止。显示指纹并要求用户验证。
- 切勿设置
StrictHostKeyChecking=no或类似跳过验证的选项。
步骤 4：在远程项目中工作
- 每个命令都在
remote_project_path内执行，例如ssh ... 'cd <remote_project_path> && <command>'。对路径使用引号。 - 在假设远程机器上存在某个工具之前，先检查其清单或运行
command -v <tool>。 - 除非用户要求，否则不要在
remote_project_path之外写入。
安全规则
- 在执行破坏性命令（如
rm -rf、强行推送、删除数据库、磁盘操作或服务重启）之前，先询问用户。 - 切勿打印、复制、记录或提交密码、密钥内容或令牌。
- 不要将凭据存储在本项目的
ssh.md或环境变量之外的任何文件中。 - 不要在远程机器上运行用户未要求的命令。
不支持的操作
- 将密码存储在受跟踪的文件或此技能中
- 代表用户处理交互式 MFA 或一次性验证码
- 禁用主机密钥验证
- 连接到未在
ssh.md中定义的主机