Imported from wlc952/gssh (
.claude/skills/gssh/SKILL.md). Install upstream withnpx skills add wlc952/gssh --skill gssh. Copyright stays with the author.
gssh 能力与使用技能
技能产出
调用本技能时，应产出：
- 针对当前场景的能力说明（简短、可决策）。
- 最小可执行命令序列（可直接复制运行）。
- 仅在必要时补充高级参数和变体。
- 可验证的完成检查清单。
适用场景
当用户出现以下诉求时使用：
- 想知道 gssh 是什么、适不适合 agent 自动化。
- 需要从零开始的上手路径。
- 需要连接 SSH 或创建本地会话。
- 需要安全执行命令（sudo、超时、流式输出、JSON 结构化输出）。
- 需要管理会话生命周期（list/use/kill）。
- 需要端口转发、SFTP/SCP 传输、重连恢复、健康检查。
能力地图
将 gssh 总结为“非交互、脚本优先、CLI 与 ssh/scp 对齐”的会话复用工具，核心能力包括：
- ssh 风格用法：
gssh user@host连接、gssh user@host "cmd"直接执行、gssh scp src session:/dst传输。 - 默认密钥认证：ssh-agent +
~/.ssh默认密钥自动尝试，与 ssh 一致。 - 命名 SSH 会话与本地会话。
- daemon 免管理：任何命令需要时自动启动，崩溃后自动恢复（socket 残留自动清理）。
- 结构化命令执行：非流式默认输出
{"stdout","stderr","exit_code"}JSON（--raw切回原始输出，--stream实时推送）。 - 长任务流式输出（
--stream）。 - 通过 stdin 的安全 sudo 执行。
- 本地与远程端口转发（
-L/-R与 ssh 语义一致）。 - SCP/SFTP 文件传输（scp 风格
session:path语法）。 - 会话切换与重连（
use智能切换默认，自动恢复断开的 SSH 连接）。 - 指数退避自动重连与转发恢复；daemon 重启后密钥会话自动重连。
工作流
1. 澄清目标与约束
先确认：
- 目标是远程还是本地。
- 一次性操作还是重复操作。
- 是否需要长时间流式输出或 JSON 结构化结果。
- 是否需要 sudo、转发或文件传输。
- 安全策略：优先密钥认证（默认自动尝试 agent 和默认密钥），密码为备选。
2. daemon 无需手动管理
daemon 会在任何命令需要时自动启动，一般跳过此步。仅在需要显式控制时：
gssh ping # 检查 daemon 状态（不会触发自动启动）
gssh start # 显式启动（等待就绪后返回）
gssh server # 前台运行（调试用）故障排查时查看 daemon 日志：~/.gssh/server.log。
3. 连接或选择会话
SSH 连接（默认密钥认证，与 ssh 一致）：
gssh <user>@<host> # 自动尝试 ssh-agent + 默认密钥
gssh <user>@<host> -p <port> # 指定端口
gssh <user>@<host> -i <ssh_key_path> # 指定密钥
gssh <user>@<host> -n <session> # 指定会话名（默认 user@host）密码认证备选：
gssh <user>@<host> --pswd <password>本地会话：
gssh local -n <session>可选：设置默认会话或恢复断开的会话：
gssh use <session> # 切换默认（已连接的会话仅切换默认）
gssh use <session> --pswd <password> # 恢复离线会话（密码）
gssh use <session> -i <ssh_key_path> # 恢复离线会话（密钥）4. 执行命令
ssh 风格直接执行（自动连接/复用会话，默认 JSON 输出）：
gssh <user>@<host> "<command>"
gssh <user>@<host> --raw "<command>" # 原始输出（给人看/接管道）
gssh <user>@<host> --stream "<command>" # 实时流式命名会话内执行：
gssh exec -n <session> "<command>" # 默认 JSON：{"stdout","stderr","exit_code"}
gssh exec -n <session> -t <seconds> "<command>" # 带超时
gssh exec -n <session> --raw "<command>" # 原始输出
gssh exec -n <session> --stream "<command>" # 长任务流式输出安全 sudo 执行：
gssh exec -n <session> --sudo --pswd <password> "<command>"一次性本地执行（不建会话）：
gssh run "<command>"5. 可选高级操作
本地转发（localPort:remotePort，与 ssh -L 语义一致）：
gssh forward -n <session> -L <local_port>:<remote_port>远程转发（remotePort:localPort，与 ssh -R 语义一致）：
gssh forward -n <session> -R <remote_port>:<local_port>查看与关闭转发（ID 可用列表中显示的 8 位前缀）：
gssh forwards
gssh forward-close <forward_id_or_prefix>文件传输（scp 风格，一侧为 session:path）：
gssh scp <local_path> <session>:<remote_path> # 上传
gssh scp <session>:<remote_path> <local_path> # 下载
gssh sync <local_dir> <session>:<remote_dir> # 增量同步SFTP 操作（位置参数）：
gssh sftp -n <session> ls <remote_dir>
gssh sftp -n <session> mkdir <remote_dir>
gssh sftp -n <session> rm <remote_path>6. 管理会话生命周期
gssh list # 或 gssh list --json
gssh use <session> # 切换默认 / 恢复断开的会话
gssh use <session> --pswd <pw> # 恢复离线会话（提供认证）
gssh kill <session>7. 完成验证
每次都要确认：
gssh ping可成功返回。- 目标会话在
gssh list中状态符合预期。 - 命令输出与退出码符合预期（默认 JSON 输出可精确读取 exit_code）。
- 转发或传输结果可在
gssh forwards或目标路径中验证。
决策逻辑
- 一次性本地命令：优先
gssh run。 - 一次性远程命令：
gssh <user>@<host> "cmd"（自动复用会话连接）。 - 同一目标重复执行：命名会话 +
gssh exec -n <session>。 - 需要程序解析结果：非流式默认即 JSON；给人看或接管道用
--raw。 - 需要实时可见输出或输出可能超过 4MB：加
--stream。 - daemon 重启后密钥会话自动重连；密码会话离线时使用
gssh use <session> --pswd <password>恢复。 - 需要远程暴露反向转发：使用
-R，仅在确有必要时使用--public。
质量标准
- 连接示例优先使用
gssh <user>@<host>简写形式。 - 认证优先密钥（默认自动），密码作为备选（
--pswd）。 - 明确提示 gssh 为非交互模式，不适合依赖 TTY 的全屏交互程序；密码短语密钥需先 ssh-add。
- 回答先给最小路径，再给可选高级方案。
输出模板
调用本技能时，按以下结构输出：
- 一句话场景总结。
- 最小命令序列。
- 可选高级变体。
- 验收检查清单。
- 下一步安全动作（kill 会话或保持）。
