first commit

2026-03-23 17:27:15 +08:00
commit a6742336bc
8 changed files with 1352 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,189 @@
+# Linux SSH Operator
+
+通过 SSH 连接并操作 Linux 服务器的 Claude Code 技能——执行远程命令、查看日志、管理 systemd 服务、传输文件。
+
+## 触发场景
+
+当你说这些时会激活此技能：
+- `ssh` / `scp` / `rsync`
+- 远程服务器 IP 和端口
+- `systemctl` / `journalctl`
+- 部署到服务器
+- 在服务器上运行命令
+- 向/从远程服务器拷贝文件
+
+## 快速上手
+
+### 1. 配置 SSH 密钥（推荐）
+
+```bash
+# 生成 ed25519 密钥
+ssh-keygen -t ed25519 -C "codex" -f ~/.ssh/id_ed25519
+
+# 将公钥复制到服务器
+ssh-copy-id -i ~/.ssh/id_ed25519.pub -p 22 USER@SERVER_IP
+
+# 可选：在 ~/.ssh/config 中添加主机别名
+Host my-server
+  HostName SERVER_IP
+  Port 22
+  User USER
+  IdentityFile ~/.ssh/id_ed25519
+  IdentitiesOnly yes
+```
+
+### 2. 执行远程命令
+
+```bash
+# 直接执行
+ssh my-server uname -a
+
+# 使用 sudo（需要 TTY）
+ssh -tt my-server sudo systemctl restart nginx
+
+# 通过包装脚本执行（统一选项）
+~/.claude/skills/linux-ssh-operator/scripts/ssh_run.sh my-server -- uname -a
+~/.claude/skills/linux-ssh-operator/scripts/ssh_run.sh --tty --sudo my-server -- systemctl restart nginx
+```
+
+### 3. 传输文件
+
+```bash
+# 上传（push）
+~/.claude/skills/linux-ssh-operator/scripts/ssh_copy.sh push my-server ./local.txt /tmp/local.txt
+
+# 下载（pull）
+~/.claude/skills/linux-ssh-operator/scripts/ssh_copy.sh pull my-server /var/log/syslog ./syslog
+
+# 强制 rsync 方式同步目录
+~/.claude/skills/linux-ssh-operator/scripts/ssh_copy.sh --method rsync -r push my-server ./dir /tmp/dir
+
+# 强制 tar 打包传输（大量小文件）
+~/.claude/skills/linux-ssh-operator/scripts/ssh_copy.sh --tar push my-server ./many-small-files/ /tmp/
+
+# Rsync 排除文件并同步
+~/.claude/skills/linux-ssh-operator/scripts/ssh_copy.sh --method rsync -r \
+  --exclude '.git' --exclude 'node_modules' --exclude '*.log' \
+  --delete push my-server ./project/ /tmp/project/
+
+# 显示传输进度和统计
+~/.claude/skills/linux-ssh-operator/scripts/ssh_copy.sh --method rsync -r \
+  --progress --stats push my-server ./dir /tmp/
+
+# 预演模式（不执行，只显示命令）
+~/.claude/skills/linux-ssh-operator/scripts/ssh_copy.sh --method tar \
+  --dry-run push my-server ./dir /tmp/
+```
+
+## 脚本说明
+
+### ssh_run.sh
+
+统一选项的远程命令执行脚本。
+
+```bash
+ssh_run.sh [选项] 主机 -- 命令 [参数...]
+
+选项：
+  -u, --user 用户名           指定 SSH 用户
+  -p, --port 端口             SSH 端口（默认 22）
+  -i, --key 路径              私钥文件路径
+  -t, --tty                   强制分配 pseudo-tty
+      --sudo                  命令前加 sudo
+      --sudo-non-interactive  使用 sudo -n（密码需要时失败）
+      --connect-timeout 秒    连接超时（默认 10 秒）
+      --dry-run               仅打印 ssh 命令，不执行
+  -h, --help                  显示帮助
+
+环境变量默认值：
+  REMOTE_USER, REMOTE_PORT, REMOTE_KEY, REMOTE_CONNECT_TIMEOUT
+```
+
+### ssh_copy.sh
+
+统一选项的文件传输脚本（支持 scp/rsync/sftp，自动选择最优方式）。
+
+```bash
+ssh_copy.sh [选项] push 主机 本地路径 远程路径
+ssh_copy.sh [选项] pull 主机 远程路径 本地路径
+
+选项：
+  -u, --user 用户名           指定 SSH 用户
+  -p, --port 端口             SSH 端口（默认 22）
+  -i, --key 路径              私钥文件路径
+      --connect-timeout 秒    连接超时（默认 10 秒）
+  -r, --recursive             递归拷贝目录
+      --accept-new            设置 StrictHostKeyChecking=accept-new
+
+  # 传输方式
+  -m, --method {auto,scp,rsync,sftp}
+                              传输方式（默认 auto）
+      --tar                   强制 tar+scp 打包传输
+      --tar-format {tar,tar.gz,tar.xz}
+                              tar 格式（默认 tar.gz）
+      --tar-threshold N       触发打包的文件数量阈值（默认 20）
+
+  # 压缩
+      --compress {auto,yes,no}
+                              启用压缩（默认 auto）
+      --compress-level N      压缩级别 1-9（默认 6）
+
+  # Rsync 专用
+      --exclude 模式          排除匹配（可多次指定）
+      --delete                同步后删除目标多余文件
+      --whole-file            强制全量传输
+
+  # 输出
+      --progress              显示传输进度
+      --stats                 显示传输统计
+      --dry-run               仅打印命令，不执行
+  -h, --help                  显示帮助
+
+环境变量默认值：
+  REMOTE_USER, REMOTE_PORT, REMOTE_KEY, REMOTE_CONNECT_TIMEOUT
+
+自动选择规则：
+  - 单文件 → scp
+  - 目录同步 → rsync -a
+  - 大量小文件 (>20个) → tar.gz + scp
+  - 大文件 (>100MB) → rsync -z
+  - 需要排除文件 → rsync --exclude
+
+注意：`--tar` 与 `--method rsync/scp/sftp` 不要混用。
+
+## 常用操作
+
+| 任务 | 命令 |
+|------|------|
+| 磁盘使用 | `df -h`, `du -sh /路径/* \| sort -h` |
+| 内存/进程 | `free -h`, `ps aux --sort=-%mem \| head` |
+| 查看日志 | `journalctl -u 服务名 -n 200 --no-pager` |
+| 服务状态 | `systemctl status 服务名 --no-pager` |
+| 重启服务 | `systemctl restart 服务名`（需要 sudo + tty） |
+| 网络状态 | `ss -lntp`, `ip a`, `ip r` |
+
+## 安全规范
+
+- **禁止** 在文件或聊天记录中存储密码
+- **避免** `StrictHostKeyChecking=no`——优先验证 host key，或仅对临时主机使用 `accept-new`
+- **破坏性命令**（rm、shutdown、防火墙变更）需要用户明确确认，并先展示完整命令
+- **先读后写**——先做只读检查，再执行变更，最后验证
+
+## 项目结构
+
+```
+linux-ssh-operator/
+├── SKILL.md              # 技能定义和触发条件
+├── README.md             # 本文件
+├── agents/
+│   └── openai.yaml       # Agent 接口配置
+├── references/
+│   └── ssh-playbook.md   # SSH 操作参考文档
+└── scripts/
+    ├── ssh_run.sh        # 远程命令执行包装脚本
+    └── ssh_copy.sh       # 文件传输包装脚本（scp/rsync/sftp）
+```
+
+## 参考资料
+
+- [SSH 操作参考](references/ssh-playbook.md) — 常用 SSH 任务、故障排查和安全最佳实践