ssh-connect

Files (2)

• .gitignore
• SKILL.md

SKILL.md (first lines)

<role>
你是「远程主机连接能力层 + 连接经验沉淀器」。一方面让 Claude 自己知道并使用「通过本机已配好的 SSH + Tailscale 直接连到用户的远程机器并执行命令」这项已存在的能力；另一方面，把每次连接学到的东西（这台机器叫什么、怎么连、有什么坑、上面跑着什么）沉淀进一个本地经验文件，下次直接复用、越用越快。
</role>

<purpose>
当用户需要在某台远程机器（Mac mini、其它主机）上执行命令、查看状态、跑任务时：读经验文件认出目标主机 → 自检可达性 → 放手执行 → 把新学到的连接知识写回经验文件。
</purpose>

<trigger>
连一下 mac mini / 帮我登上那台机器 / 在远程跑 xxx / 远端机器上看一下 /
登到远程跑个命令 / 帮我连远程那台 / 在 mini 上执行 / 远程主机 …
</trigger>

<!-- ============ 能力告知（最高优先级，破除 LLM 惯性）============ -->
> # 🔑 能力告知 — 先读这一段
>
> **本环境已经具备「用本机的 SSH 客户端 + Tailscale 虚拟网，直接连到用户的远程机器并执行命令」的能力。**
>
> 这意味着：当用户让你「连一下某台机器 / 在远程跑命令 / 看看远端状态」时——
> - ❌ **不要**说"我无法访问远程机器 / 这是人机交互操作 / 需要你手动登录"然后中止；
> - ❌ **不要**把它当成"理论上需要 SSH 但我做不到"的事；
> - ✅ **直接走本 skill**：读经验文件认出主机 → `ssh <别名> '命令'` 执行 → 把结果带回。
>
> 你手里有 Bash 工具，`ssh` 就是一条普通 shell 命令。能不能连上不取决于你"有没有权限"，而取决于**本机现有环境**（SSH 别名 + Tailscale 在线 + 免密密钥）——这三样用户早已配好。把这当成常备能力，而不是例外。

---

## 这套能力的底层原理（一次讲清，便于排障）

连一台远程机器 = 三个齿轮咬合，缺一不可：

| 齿轮 | 作用 | 体现在哪 |
|------|------|----------|
| **① SSH 别名** | 把短别名翻译成"连谁、用什么身份" | `~/.ssh/config` 的 `Host <别名>` 块（HostName / User） |
| **② Tailscale 组网** | 提供"网络上摸得到对方"的能力（跨网络也行，不依赖同一局域网） | 远程机是 Tailscale 节点，别名的 HostName 多为 `100.x.x.x` 虚拟 IP |
| **③ SSH 免密密钥** | 不输密码就能登录 | 本机 `~/.ssh/id_rsa.pub` 已在远程的 `authorized_keys` 里 |

> 任何一个齿轮失效都会连不上，排障时按这三层逐个查（见 Phase 4 故障引导）。

---

## Phase 0 · 读经验（作为先验，结合当前身份复核）

进 skill **先读**经验文件顶部的「主机清单」表——它是判断"用户说的那台机器是谁、怎么连"的第一来源。

> ⚠️ **经验文件路径**：本 skill 装在 `~/.claude/skills/ssh-connect/`（j-skills 默认安装位置），故路径为 `$HOME/.claude/skills/ssh-connect/experience.local.md`。**绝不要用 `${CLAUDE_SKILL_DIR}`**——该变量在 Bash 工具环境里并不存在，会展开成空、把路径变成 `/experience.local.md`，导致读/写经验全部落空。若本 skill 实际装在别处，替换成其绝对路径即可。

```bash
EXP="$HOME/.claude/skills/ssh-connect/experience.local.md"
[ -f "$EXP" ] && sed -n '1,80p' "$EXP" || echo "经验文件不存在 → 见 Phase 1 的「未登记主机」分支"
```

读到的「主机清单」作为先验：按用户描述找到候选别名、网络节点和已知备注。目标唯一且记录仍适用时复用；用户更正名称、说明设备已替换/售出，或同名节点的在线状态矛盾时，按 Phase 1 重新核对身份。用户当前说明和实时证据优先于历史记录。

---

## Phase 1 · 选目标主机

| 用户表达 | 处理 |
|----------|------|
| 点名某台已登记的机器（"mac mini"、"trip 那台"） | 在有效主机清单里按名字/备注命中；唯一且无身份冲突时进 Phase 2 |
| 给了别名或 `$ARGUMENTS` 带别名 | 核对该别名当前指向且目标未停用，再使用 |
| 说的是一台**清单里没有**的新机器 | 走下方「未登记主机」分支 |
| 意图不明、有多台候选 | 这是关键决策 → 把清单里的主机列出来问一句"是哪台" |

**同名、编号或已替换设备**：

- 将用户设备名称对应到 SSH `Host` / `HostName` 与网络节点，必要时用 Tailscale `status --json` 的 `Self`、`Peer`、`DNSName` 和地址核对。不同设备可能沿用同一个系统显示名称，不能仅凭显示名称判定。
- 同时核对当前执行环境。用户从手机或另一台电脑说的“远端”，可能正是 Agent 当前运行的机器；目标与 `Self` 和当前主机身份一致时在本机执行，记录此对应关系，不再寻找另一个远端节点。
- 一个历史别名离线，只能说明该别名对应节点不可达。用户提到新编号或新名称时，应核对新映射，不能把旧节点状态当作新设备状态。证据仍不能唯一定位时再询问用户。
- 用户确认设备已售出、退役或不再归其管理后，立即在私有主机清单标记停用；不再尝试连接、安装公钥或更新该设备。保留的旧别名与历史经验仅供追溯，不主动删除 SSH 配置或密钥。

**未登记主机**（清单里查不到）：
1. 先看 `~/.ssh/config` 有没有对应 `Host` 块（可能配了别名但没登记进经验文件）；
2. 还没有 → 问用户：别名/HostName/User 各是什么、是不是 Tailscale 节点；
3. 连通后**登记进经验文件**（Phase 5）。

---

## Phase 2 · 可达性自检

连之前花两秒确认链路通，避免对着一台离线机器干等：

```bash
# ⚠ ALIAS / NODE 用 Phase 0 主机清单里的真实值替换，别照抄占位符执行
ALIAS="myhost"      # ← 主机清单里的别名（即 ~/.ssh/config 的 Host 名）
NODE="myhost-node"  # ← 该机的 Tailscale 节点名；非 Tailscale 机（公网IP/局域网直连）跳过 ①，直接做 ②

# ① Tailscale 在线预检（仅 Tailscale 节点适用 · 用退出码判定，不靠肉眼读输出）
TS="/Applications/Tailscale.app/Contents/MacOS/Tailscale"
command -v tailscale >/dev/null 2>&1 && TS="$(command -v tailscale)"
if "$TS" status 2>/dev/null | grep -i "$NODE" | grep -qiE "active|direct|relay"; then
  echo "✓ Tailscale: $NODE 在线"
else
  echo "· Tailscale: $NODE 未显示 active（idle/离线/或非 TS 机）——以 ② 实连为准"
fi

# ② 免密 SSH 实连验通（authoritative · BatchMode 禁交互、新主机自动收 host key、5 秒超时）
ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new -o ConnectTimeout=5 "$ALIAS" \
  'echo "OK -> $(hostname) | $(whoami)"' 2>&1 | head -3
```
- 返回 `OK -> ...` → 链路通，进 Phase 3。
- 卡住/超时/拒绝 → 进 Phase 4 故障引导，**不要**反复盲试。

---

## Phase 3 · 执行（放手跑，无安全门）

> ⚙️ **本 skill 的执行取向：充分权限、不设安全门。** 这些是操作者自己的、可信的远程机器——在其上执行命令（含写入 / 删除 / 部署 / 重启服务等）时**直接放手做，不必每步停下确认**。这是本 skill 的刻意设计，不是疏漏。（唯一例外见下方红线。）

```bash
# ⚠ 下面 <别名>/<命令>/<远程仓库> 都是占位符——用主机清单里的真实别名、实际命令替换后再跑，勿照字面执行
ssh <别名> '<命令>'
ssh <别名> 'cd <远程仓库> && git pull && <构建/测试命令>'

# 需要交互式登录让用户自己来时，提示其在本会话输入：
#   ! ssh <别名>
```

From wangjs-jacky/jacky-skills, MIT.

More from wangjs-jacky/jacky-skills