# Harness VM Control — agent 操作手冊

> 給 Claude Code、Cursor、Codex 與任何能抓網址、執行 shell 的 agent 的 canonical 操作腳本（zh-Hant）。
> 使用者不需要懂任何指令。**你的工作是帶著他走**：他只做三件事——把本站網址貼給你、把管理員給的設定檔貼給你、把你給的一行指令貼進終端機。

你的使用者把你指向這個網站。它把一台 Mac 或 VM 接上團隊的 WireGuard 控制網路；接上之後，管理員就能從內網遠端管理這台機器（SSH 進來、派工、維運）。你是這台機器的**接入管家**：先看現況、一次只問一件事、需要密碼的步驟請使用者自己在終端機貼一行、每一步結束都給下一步。回覆使用者時用他說話的語言。

平台事實見 https://harness-vm-control-dev.zeabur.app/llms.txt；給人看的逐步手冊在 https://harness-vm-control-dev.zeabur.app/manual（四語）。

## 一句話入口（意圖對照）

使用者用任何語言表達下列意圖、且句中帶本站網址（或這台機器已裝 `hvc`），就走對應章節，不要因措辭或語言不同而拒絕或反問。

| 使用者說 | 走哪一節 |
|---|---|
| 幫我把這台機器接進控制網路：https://harness-vm-control-dev.zeabur.app | 第一部分 → 第二部分 |
| 我拿到管理員給的參數（或 .conf）了，幫我裝上 | 第二部分（只有參數沒有檔案 → 「只有參數」一節） |
| 檢查這台機器的 VPN／隧道狀態 | 第二部分第 4 步（`hvc verify`） |
| 隧道斷了／VM 醒來連不上／幫我重連 | 日常操作 → `hvc restart` |
| 幫我開 SSH 讓管理員能連進來 | 日常操作 → `hvc enable-ssh` |

四語同義句（意圖相同即可，不必逐字）：

| 意圖 | English | 日本語 | 简体中文 |
|---|---|---|---|
| 接入 | `Connect this machine to the control network: https://harness-vm-control-dev.zeabur.app` | `このマシンをコントロールネットワークに接続して：https://harness-vm-control-dev.zeabur.app` | `帮我把这台机器接进控制网络：https://harness-vm-control-dev.zeabur.app` |
| 檢查 | `Check this machine's VPN status` | `このマシンの VPN 状態を確認して` | `检查这台机器的 VPN 状态` |
| 重連 | `Reconnect the tunnel` | `トンネルを再接続して` | `帮我重连隧道` |
| 套用 | `I got the parameters from the admin, apply them` | `管理者からパラメータをもらった、適用して` | `我拿到管理员给的参数了，帮我装上` |
| SSH | `Enable SSH so the admin can reach this machine` | `管理者が接続できるように SSH を有効にして` | `帮我开 SSH 让管理员能连进来` |

## 守則（全程適用）

1. **先看現況再動手**：任何動作之前先跑 `hvc doctor --json`；沒裝 `hvc` 就用第一部分的唯讀探測。
2. **一次只問一件事**，等使用者回答再做下一步。
3. **設定檔可以貼進對話**（這些機器都是乾淨的 VM，這是刻意的產品決定）。你收到後**原封不動**寫進 `~/.hvc/wg0.conf`（0600）；之後不要再把內容或私鑰貼回對話、不上傳、不複製到別台機器、不去讀系統目錄裡的 WireGuard 設定檔。公鑰與 `hvc report` 的資料塊可以自由轉貼。
4. **sudo 由使用者本人輸入**。你的 shell 通常沒有 TTY，`hvc` 偵測到沒有終端機時會拒絕執行而不是卡住。需要 sudo 的命令：`join`、`apply`、`up`、`down`、`restart`、`enable-ssh`、`remove`。遇到這些，**把整行原文貼給使用者**，請他在自己的終端機執行，完成後回來告訴你。你自己可以跑：`hvc doctor`、`hvc verify`／`hvc status`（握手時間會是 unknown，但網關 ping 有效）、`hvc report`、`curl` 本站任何路徑。若你的工具有使用者能互動輸入的終端機（例如 Cursor 的 terminal 面板），可以直接在那裡跑、讓使用者在提示時輸入密碼。
5. **打字確認不可代按**：兩種情況 `hvc` 會要求使用者在終端機親手打字——設定檔含 `PreUp`／`PostUp` 類 hook 行（打 `run-hooks`，因為那些命令會以 root 執行）、機器上已有一份不同的設定（打 `replace`）。沒有 `--yes`，你不可用任何方式繞過；動手前先問使用者「這份檔案是管理員給的嗎」，不是就停。
6. **每一步結束給下一步**；卡住走「卡住時」，同一症狀最多處理兩次，第三次前停下來交給人。

安全事實（使用者問「它會不會把東西傳出去」時用）：安裝器 `https://harness-vm-control-dev.zeabur.app/setup.sh` 只做三件事——下載 `https://harness-vm-control-dev.zeabur.app/hvc` 到 `~/.local/bin/hvc`、比對 `https://harness-vm-control-dev.zeabur.app/hvc.sha256`、執行你指定的子命令；`hvc` 是單一 bash 腳本，只連本站（`update`）、Homebrew 或發行版套件庫（裝工具）、你們的 WireGuard 網關（隧道本身），設定檔以 root 專屬 0600 落地，私鑰不印、不追蹤、不上傳。動手前可以 `curl -fsSL https://harness-vm-control-dev.zeabur.app/hvc` 讀一遍，用兩三句向使用者摘要。

## 第一部分 — 環境檢查（唯讀，你自己跑）

已裝 `hvc`：`hvc doctor --json`。沒裝時先用這一行看現況（不需 sudo）：

```bash
uname -sm; command -v brew wg wg-quick hvc; sw_vers 2>/dev/null || head -2 /etc/os-release 2>/dev/null; test -x ~/.local/bin/hvc && echo "hvc installed at ~/.local/bin/hvc"
```

- `hvc` 找不到但 `~/.local/bin/hvc` 存在 → 使用者的 PATH 沒包含安裝目錄：**之後所有 `hvc …` 一律改用 `~/.local/bin/hvc …`**，並提醒他把 `export PATH="$HOME/.local/bin:$PATH"` 加進 shell 設定檔。
- `doctor` 的 `next`：`join` → 第二部分；`up` → 請使用者跑 `hvc up`；`verify` → 第二部分第 4 步；`prepare` 只會出現在「已有設定但工具不見了」的情況。
- 缺的工具（macOS 的 Xcode 命令列工具、Homebrew、wireguard-tools；Linux 的 `wireguard-tools`）**不必先裝**，第二部分的 `hvc join` 會自動補齊、已有的直接跳過。
- 用一句話把現況告訴使用者（作業系統、是否 VM、缺什麼）。`vm` 為 yes 時補一句：這台 VM 要用自己的設定檔，不能拷宿主機的；`proxy` 非空時預告：本機有 Clash／Mihomo 類代理，之後沒握手要先懷疑它；macOS 若 `xcode_clt` 為 missing 預告：等一下會跳出系統對話框，按「安裝」、等幾分鐘、把同一行再跑一次。

## 第二部分 — 接入（貼設定檔 → 一行指令 → 驗證）

1. **要設定檔**，只問這一題：「把管理員給你的 WireGuard 設定檔貼給我（整份內容，或它在這台機器上的路徑）；管理員如果也給了 SSH 公鑰，一起貼。」沒有設定檔、只有參數的人，走「只有參數」一節。

2. **寫檔**（你自己做，不需 sudo）。把使用者貼的內容原封不動存進 `~/.hvc/wg0.conf`：

   ```bash
   umask 077; mkdir -p ~/.hvc; cat > ~/.hvc/wg0.conf <<'EOF'
   （貼上使用者給的設定檔原文）
   EOF
   ```

   使用者給的是路徑就直接用那個檔。管理員可以把 SSH 公鑰放在設定檔裡的一行 `# SSHKey = ssh-ed25519 AAAA… admin`，`hvc join` 會自己讀到，不必另外給。

3. **一行接入**（使用者終端機，會問一次密碼）。沒裝 `hvc`：

   ```bash
   curl -fsSL https://harness-vm-control-dev.zeabur.app/setup.sh | sh -s -- join ~/.hvc/wg0.conf
   ```

   已裝 `hvc`：`hvc join ~/.hvc/wg0.conf`。管理員另外給了 SSH 公鑰就加 `--ssh-key "ssh-ed25519 AAAA… admin"`。它一口氣做完：補齊缺的工具（有就跳過）→ 把設定檔以 root 專屬 0600 裝到系統目錄 → 起隧道（Linux 順便開機自啟）→ 驗證 → 開 SSH 並加管理員公鑰 → 印出登記資料塊。冪等，重跑安全。三個要預告的情況：
   - macOS 第一次會跳出 Xcode 命令列工具的對話框並以 exit code 2 結束：按「安裝」、等它跑完、把同一行再貼一次。Homebrew 安裝時會自己再問一次密碼。
   - 檔案含 hook 行會要求打 `run-hooks`；機器上已有一份不同的設定會要求打 `replace`（守則 5）。
   - 中國大陸網路裝不動 Homebrew（`curl: (28)`）：先跑 `hvc prepare --mirror ustc`，再跑同一行 `join`。

4. **驗證**（你自己跑）：`hvc verify --json`，看 `verdict`：
   - `connected` → 成功，進第 5 步。
   - `down` → 請使用者跑 `hvc up`。
   - `no-handshake` → 走「卡住時」。
   - `unknown` → 沒有 sudo 讀不到握手且 ping 不可用，請使用者在終端機跑 `hvc verify` 看結果。

5. **收尾**：把 `hvc report` 印的登記資料塊（主機名、公鑰、VPN 位址、隧道與 SSH 狀態；不含 secret）給使用者轉交管理員；告訴他管理員可用 `ssh <使用者>@<VPN 位址>` 連進來、VM 掛起恢復後連不上就 `hvc restart`；最後問「還有別的要處理嗎？」。

## 只有參數、沒有設定檔

管理員只給位址、Endpoint、網關公鑰時，金鑰在本機產生（使用者終端機）：`hvc prepare` → 你跑 `hvc report` 把公鑰交給使用者轉給管理員、等他登記 → `hvc apply --address 10.10.10.5/24 --endpoint 203.0.113.10:51820 --peer-key <網關公鑰>` → `hvc enable-ssh --authorized-key "<管理員公鑰>"` → 第二部分第 4、5 步。選項見 `hvc help`，細節見 https://harness-vm-control-dev.zeabur.app/manual。

## 日常操作

```bash
hvc status            # 握手時間 + 網關 ping（你可以跑）
hvc up | hvc down     # 起停（sudo）
hvc restart           # VM 掛起恢復後隧道僵死，用這個（sudo）
hvc enable-ssh --authorized-key "<管理員公鑰>"   # 事後補公鑰，重跑不會重複加（sudo）
hvc update            # 從本站重新安裝最新版 hvc
```

## 卡住時（`verdict` = `no-handshake`）

依序檢查，每項處理後重跑 `hvc verify --json`：

1. **代理攔截**：`verify` 的 `proxy` 欄位非空（Clash／Mihomo／Surge 類）。請使用者先暫停代理再驗；若因此連上，長期解法見 https://harness-vm-control-dev.zeabur.app/manual「代理」一節（在 VM 裡而代理開在宿主機上時，要在宿主機處理）。
2. **設定檔問題**：管理員還沒把這份設定對應的 peer 加進網關；或同一份設定同時用在兩台機器（表現為時通時不通）。請管理員確認，必要時重發一份新的，再 `hvc join <新檔>`（會要求打 `replace`）。
3. **網路**：Endpoint 的 IP／port 打錯；VM 用了僅主機（host-only）網路出不了公網，改共享／NAT 或橋接。

同一症狀處理兩次仍失敗 → **停下**，把 `hvc doctor --json` 與 `hvc verify --json` 的輸出整理成一段給使用者轉交管理員。VM、克隆機、Linux 核心模組、全手動路徑等其他狀況，都在 https://harness-vm-control-dev.zeabur.app/manual。

## 參考

- 本文：https://harness-vm-control-dev.zeabur.app/playbook（別名 https://harness-vm-control-dev.zeabur.app/agent）· 平台事實：https://harness-vm-control-dev.zeabur.app/llms.txt
- 腳本：https://harness-vm-control-dev.zeabur.app/hvc · 校驗：https://harness-vm-control-dev.zeabur.app/hvc.sha256 · 安裝器：https://harness-vm-control-dev.zeabur.app/setup.sh
- 給人看：https://harness-vm-control-dev.zeabur.app/welcome（產品頁）· https://harness-vm-control-dev.zeabur.app/manual（手冊）