ssh-skill

SSH 技能 v4

用途

在 Windows、macOS 和 Linux 上通过 SSH 在 Codex 和 Claude Code 中执行工作时，使用此约定。确定性 Python CLI 负责传输、重试、输出限制、主机密钥策略和兼容行为。

中文意图示例：连接服务器、远程执行、上传文件、下载日志、通过跳板机、建立隧道。继续使用用户所用的语言与用户交流。

范围

适用于：

• 在远程主机上执行命令或检查。
• 上传、下载、SFTP、等效 SCP 操作或服务器间传输。
• SSH 别名、密钥、代理、跳板机、ProxyJump、隧道和端口转发。
• 远程部署、通过隧道访问远程数据库，以及集群工作。

请勿用于：

• 本地命令、localhost、当前计算机上的服务或本地 Docker。
• 不经过 SSH 的浏览器或 HTTP 下载。
• Git 远程操作；请改用相应的 Git 工作流。
• 无需 SSH 隧道的直接数据库连接。

硬性规则

1. 找到包含当前已加载 SKILL.md 的根目录；在当前任务中将其称为 <SSH_SKILL_ROOT>。
2. 调用 <SSH_SKILL_ROOT>/scripts/ssh_skill.py；不要构造原始的 ssh、scp、sftp 或 rsync 命令。
3. 将参数作为独立的进程参数传递。绝不要在远程命令文本外再添加本地 shell 包装器。
4. 在决定下一步操作前，先解析 stdout 上的那一份 JSON 文档。
5. 将 outcome_unknown 视为停止条件。报告其请求 ID，不要自动重复执行命令。
6. 未获得新证据且用户未表示意图时，不要重试身份验证失败的操作、破坏性命令或部分完成的多主机操作。
7. 绝不要泄露密码、私钥内容、令牌或 askpass 数据。
8. 执行多主机和不可逆操作前，先预览。

只解析一次技能根目录

• 优先使用激活此技能的 SKILL.md 所在目录。
• 如果运行时提供了明确的已加载技能路径，请直接使用。
• 不要假定技能位于 .agents、.codex、.claude 或任何用户主目录路径下。
• 如果根目录不明确、缺少依赖，或可能存在内容有差异的多个已安装副本，请运行 doctor --json。
• 不要在每次操作前运行 doctor。同一任务中重复使用已解析的根目录，除非环境发生变化。
• 如果 doctor 报告存在多个副本，请继续使用当前已加载的副本，并说明版本或内容差异；绝不要自动复制或覆盖。

仅在需要调用语法时，阅读一份对应平台的指南：

• Windows：references/platforms-windows.md
• macOS：references/platforms-macos.md
• Linux：references/platforms-linux.md

标准工作流

1. 将请求归类为 exec、transfer、cluster、config、tunnel 或 doctor。
2. 只解析一次 <SSH_SKILL_ROOT>。
3. 确定 SSH 别名。如果未知，请使用 config list-servers 或 config find；不要根据 IP 或相似名称猜测。
4. 将只读信息收集与变更操作分开。只有在缺少目标或范围会实质影响操作时，才询问相关信息。
5. 预览多主机、生产环境、删除或覆盖操作。
6. 用最精简且完整的操作调用统一 CLI 一次。
7. 解析 success、data、error 和 meta，然后报告实际结果。

除非结果表明确有必要，否则不要添加连接测试、重复的状态调用或守护进程重启。

调用约定

使用适用于平台的 Python 可执行文件和路径语法：

<PYTHON> "<SSH_SKILL_ROOT>/scripts/ssh_skill.py" <operation> <arguments>

• 远程路径保持 POSIX 格式，例如 /var/log/app.log。
• 将整个远程命令作为一个参数。
• 优先使用一条远程命令收集密切相关的只读信息。
• 将相互依赖或风险各异的变更操作分开执行。
• 仅在进度事件对用户有用时使用 --progress。
• 需要干净的非交互式 stderr 时，使用 --no-progress。

完整语法请参阅 references/commands.md。

操作

操作	用途
exec	在一个 SSH 别名上运行一条命令。
upload	将本地文件或目录复制到远程 POSIX 路径。
download	将远程文件或目录复制到本地路径。
transfer	在两个 SSH 别名之间移动数据。
cluster	预览或对已解析的主机目标执行一条命令。
config	列出、查找、创建、更新、删除或导出 SSH 别名。
tunnel	启动、列出、检查或停止本地 SSH 隧道。
daemon	检查或管理可选的连接守护进程。
doctor	诊断本地运行时、文件复制、OpenSSH、Agent 和配置。

执行与传输

• exec 仅在安全时复用守护进程；--no-daemon 是用于诊断的显式退出选项，并非常规的首选操作。
• 通过 OpenSSH、Paramiko 或集群执行发送请求后发生超时，意味着远程端可能已执行命令。CLI 会返回 outcome_unknown，且 retryable=false；请停止操作并询问用户如何验证状态。
• 对于上传和下载，请区分本地原生路径与远程 POSIX 路径。仅对目录使用 --recursive。
• 继续已知的中断传输时，使用 --resume。
• 服务器到服务器直连模式可能会向源主机开放 SSH Agent。除非显式指定 --allow-agent-forwarding，否则 Agent 转发会保持关闭。

集群与配置门控

• 不带 --apply 的 cluster 操作仅预览目标，不会建立 SSH 连接。
• 检查预览中的 targets、target_count 和 production_targets。
• 只有在确认所请求的目标集合后，才添加 --apply。
• 任何目标被归类为生产环境时，都要添加 --confirm-production。
• 不带 --apply 的配置删除操作只是预览。执行删除时，会在原子替换前创建带时间戳的备份。
• 不要在 SSH 配置元数据中加入新的明文密码。

隧道与守护进程

• 启动隧道后，返回分配的本地端口和隧道 ID。
• 仅按工具的安全默认设置绑定本地转发。
• 标识符不明确时，停止隧道前优先查看状态或列表。
• 不要仅仅因为第一条命令之后紧接着执行了第二条命令，就重启守护进程。该守护进程旨在供兼容的调用复用。

结果约定

CLI 会向 stdout 写入且仅写入一个带版本号的 JSON 文档：

• schema_version：结果架构，目前为 1.0。
• success：所请求的操作是否成功完成。
• operation：稳定的操作标识符。
• data：有界的操作特定数据。
• error：失败时提供稳定的代码、消息、是否可重试以及结果状态。
• meta：请求 ID、平台、传输方式、耗时和警告。

顶层 stdout 结果上限为 256 KiB。递归传输详情最多保留 100 条首尾样本，同时总数字段仍会保留实际规模。显式启用进度后，进度信息会以实时、有界且 ASCII 安全的 JSONL 格式写入 stderr。不要将其与 stdout 合并。如果输出被截断，请说明截断情况，并使用保留的诊断尾部信息，而不要仅为获取更多输出而重新运行。

安全默认设置

• 主机密钥默认设置为 accept-new；已知密钥若发生变更，则会被拒绝。
• 日常使用中不要禁用主机密钥验证，也不要丢弃 known_hosts。
• 可以读取现有的旧版密码，但必须显示警告并保持脱敏。
• 优先使用密钥和平台 SSH Agent；绝不索取私钥值。
• 生产环境和多主机范围操作必须使用可观察的确认标志。
• 更改凭据、处理生产环境、启用 Agent 转发、删除配置或遇到结果不确定的情况前，请阅读 references/safety.md。

错误处理决策

• invalid_alias：列出或查找别名一次；不要暴力尝试名称。
• config_not_found：运行 doctor，然后报告预期的本地配置路径。
• 身份验证失败：报告所用方法和补救措施；不要反复尝试。
• outcome_unknown：停止操作，保留请求 ID，并单独验证状态。
• 集群部分失败：按主机报告结果；不要重放已成功的操作。
• 缺少依赖项：使用相关平台指南，不要改用其他 shell。

兼容性

• Codex 和 Claude Code 共用此文件和同一 Python CLI。
• Windows、macOS 和 Linux 的核心行为相同；只有本地调用方式和依赖项补救措施不同。
• 在 v4 迁移期间，旧版脚本文件名仍作为兼容入口保留。
• --legacy-json 仅供已确认的旧版使用方使用。新的 AI 调用使用 v1 信封，绝不请求旧版输出。

最终检查

• 使用了正确加载的根目录和平台语法。
• 使用了正确的别名、远程路径和目标范围。
• 已完成所需的预览和生产环境确认。
• 已解析一条 stdout JSON；已保留警告和请求 ID。
• 未泄露任何密钥，也未重放任何结果不确定的操作。