@fengye404/termpilot 0.1.5 → 0.1.7

package/README.md

@@ -2,6 +2,10 @@
 
 TermPilot 是一个终端优先的远程控制工具。电脑上跑 `tmux` 会话，手机直接打开 relay 域名查看和控制同一批会话。
 
+如果你已经准备长期部署，直接看完整运维文档：
+
+- [部署与运维指南](/Users/fengye/workspace/TermPilot/docs/operations-guide.md)
+
 ## 产品形态
 
 - 一个 npm 包：`@fengye404/termpilot`
@@ -10,7 +14,112 @@ TermPilot 是一个终端优先的远程控制工具。电脑上跑 `tmux` 会
 - 手机端不安装，直接打开 relay 域名
 - relay 同时负责消息中继和网页托管
 
-## 快速开始
+## 5 分钟快速上手
+
+### 1. 启动 relay
+
+在云服务器或一台能被手机访问到的机器上执行：
+
+```bash
+npm install -g @fengye404/termpilot
+termpilot relay
+```
+
+默认情况下，`termpilot relay` 会直接在后台启动 relay，不占当前窗口。
+
+常用 relay 管理命令：
+
+```bash
+termpilot relay
+termpilot relay stop
+termpilot relay run
+```
+
+- `termpilot relay` 或 `termpilot relay start`：后台启动
+- `termpilot relay stop`：停止后台 relay
+- `termpilot relay run`：前台运行，适合看日志和排查问题
+
+如果你只是先本地体验，也可以直接在自己电脑上跑 relay，然后让手机走局域网访问。
+
+### 2. 启动电脑 agent
+
+在你的电脑上执行：
+
+```bash
+npm install -g @fengye404/termpilot
+termpilot agent
+```
+
+如果这是第一次运行，`termpilot agent` 会直接在终端里引导你：
+
+1. 输入 relay 域名或 IP
+2. 输入端口，直接回车默认 `8787`
+3. 自动保存本机配置
+4. 后台启动 agent
+5. 输出一次性配对码
+
+以后日常只需要继续执行：
+
+```bash
+termpilot agent
+```
+
+这条命令会根据当前状态自动处理：
+
+- 没有后台 agent：按本机已保存配置启动
+- 已经有后台 agent：直接显示当前状态
+- 想重新给手机配对：执行 `termpilot agent --pair`
+
+常用管理命令：
+
+```bash
+termpilot agent status
+termpilot agent stop
+termpilot agent --pair
+```
+
+### 3. 手机完成配对
+
+手机浏览器直接打开 relay 域名：
+
+- `http://your-domain.com:8787`
+- 或反代后的 `https://your-domain.com`
+
+然后：
+
+1. 输入电脑端刚打印出来的配对码
+2. 点“配对”
+3. 成功后直接进入会话列表
+
+### 4. 直接跑一个可同步的任务
+
+日常最短路径是：
+
+```bash
+termpilot claude code
+```
+
+或者：
+
+```bash
+termpilot open code
+```
+
+这会直接：
+
+- 创建一个受 TermPilot 管理的 `tmux` 会话
+- 把命令写进这个会话
+- 当前终端自动 attach 进去
+- 手机端同步看到同一个会话
+
+### 5. 你现在应该能做到什么
+
+此时你可以：
+
+- 在电脑上看 `claude code` / `open code` 的流式输出
+- 在手机上看同一份输出
+- 在手机上补一条命令、发快捷键、关闭会话
+- 随时在电脑和手机之间切换
 
 ### 服务器
 
@@ -33,7 +142,9 @@ termpilot relay
 常用参数：
 
 ```bash
-termpilot relay --host 0.0.0.0 --port 8787
+termpilot relay
+termpilot relay run
+termpilot relay stop
 DATABASE_URL=postgresql://user:pass@127.0.0.1:5432/termpilot termpilot relay
 ```
 
@@ -41,19 +152,13 @@ DATABASE_URL=postgresql://user:pass@127.0.0.1:5432/termpilot termpilot relay
 
 ```bash
 npm install -g @fengye404/termpilot
-termpilot agent --relay ws://your-domain.com/ws
+termpilot agent
 ```
 
-这条命令现在会：
-
-- 在后台启动 agent
-- 判断这台电脑是否已经有本地 agent 在运行
-- 直接输出一次性配对码
-
 如果你只是想看调试日志，可以显式前台运行：
 
 ```bash
-termpilot agent --relay ws://your-domain.com/ws --foreground
+termpilot agent --foreground
 ```
 
 查看后台状态：
@@ -71,7 +176,7 @@ termpilot agent stop
 本地测试：
 
 ```bash
-termpilot agent --relay ws://127.0.0.1:8787/ws
+termpilot agent
 ```
 
 ### 手机
@@ -80,7 +185,7 @@ termpilot agent --relay ws://127.0.0.1:8787/ws
 
 - `https://your-domain.com`
 
-首次使用时，直接执行上面的 `termpilot agent --relay ...` 就会拿到配对码；`termpilot pair` 现在只是补充入口，用于你已经有后台 agent、但想重新生成一次配对码的场景。
+首次使用时，直接执行上面的 `termpilot agent` 就会进入配置引导并拿到配对码；如果你已经跑着后台 agent、只是想重新给手机配对，用 `termpilot agent --pair`。
 
 配对成功后：
 
@@ -89,29 +194,24 @@ termpilot agent --relay ws://127.0.0.1:8787/ws
 - 点进一个会话后才进入终端详情页
 - 连接信息和设备设置都在页面底部折叠区
 
-## 最短使用路径
-
-电脑上直接启动后台 agent：
-
-```bash
-termpilot agent --relay ws://your-domain.com/ws
-```
+## 日常使用
 
-拿到配对码以后，在手机上完成配对。然后你日常最简单的启动方式就是：
+### 直接把命令交给 TermPilot
 
 ```bash
+termpilot agent
 termpilot claude code
+termpilot open code
 ```
 
-或者：
+如果你想跑别的命令，也可以直接：
 
 ```bash
-termpilot open code
+termpilot npm run dev
+termpilot python worker.py
 ```
 
-这会直接创建一个受 TermPilot 管理的 tmux 会话，并在当前终端里 attach 进去。手机上会同步看到同一个会话。
-
-## 日常使用
+### 手动管理会话
 
 创建会话并进入：
 
@@ -121,13 +221,7 @@ termpilot list
 termpilot attach --sid <sid>
 ```
 
-如果你不想手动 `create + attach`，可以直接把命令交给 TermPilot：
-
-```bash
-termpilot claude code
-```
-
-在会话里运行：
+进入会话以后，你仍然可以自己手动运行：
 
 ```bash
 claude code
@@ -141,10 +235,12 @@ open code
 
 ```bash
 termpilot relay
-termpilot agent --relay ws://127.0.0.1:8787/ws
+termpilot relay stop
+termpilot relay run
+termpilot agent
+termpilot agent --pair
 termpilot agent status
 termpilot agent stop
-termpilot pair
 termpilot create --name claude-main
 termpilot list
 termpilot attach --sid <sid>
@@ -158,12 +254,24 @@ termpilot doctor
 ## 最佳实践
 
 1. 需要跨端同步的任务，一开始就用 `termpilot create` 创建，不要先在普通终端里跑再想着接管。
-2. 一个长期任务用一个独立会话，名称直接写任务语义，比如 `claude-main`、`deploy-watch`。
-3. 电脑前重操作优先 `termpilot attach`，手机更适合看进度、补命令和关闭会话。
-4. 手机优先走一次性配对码，不要长期依赖共享 `client token`。
-5. 要长期使用 relay，优先接 PostgreSQL；本地演示可以先用内存模式。
-6. 换手机或访问权变更时，先 `termpilot grants`，再 `termpilot revoke --token ...`。
-7. 想排查控制历史时先看 `termpilot audit --limit 30`。
+2. 第一次先跑一次 `termpilot agent` 完成本机配置，之后日常就只需要记住这一条命令。
+3. 如果只是想“开一个会话然后立刻跑起来”，优先用 `termpilot claude code` 这类直达命令，不必手动 `create + attach`。
+4. 一个长期任务用一个独立会话，名称直接写任务语义，比如 `claude-main`、`deploy-watch`、`batch-fix`。
+5. 电脑前重操作优先 `termpilot attach`；手机更适合看进度、发短命令、补快捷键和关闭会话。
+6. 普通 iTerm / Terminal 标签页不是 TermPilot 管理对象，不要指望后面“无缝接管”进来。
+7. 手机优先走一次性配对码，不要长期传播访问令牌。
+8. 要长期使用 relay，优先放到 HTTPS/WSS 域名后面，并接 PostgreSQL；本地演示可以先用内存模式。
+9. 换手机或访问权变更时，先 `termpilot grants`，再 `termpilot revoke --token ...`。
+10. 想排查控制历史时先看 `termpilot audit --limit 30`。
+11. 服务器上日常用 `termpilot relay` 后台运行；只有排查问题时才用 `termpilot relay run`。
+
+## 常见坑
+
+- `termpilot agent` 不会停在前台，这是正常的；它默认就是后台守护进程。
+- `termpilot relay` 默认也不会停在前台；想看日志请用 `termpilot relay run`。
+- 手机上看不到任务时，先确认这个任务是不是通过 `termpilot ...` 或 `termpilot create` 启动的。
+- 首次配对优先用 `termpilot agent` 拿配对码；重新给手机配对时用 `termpilot agent --pair`。
+- 外网正式使用时，不要长期直接裸奔 `ws://IP:8787/ws`，最好上域名和反代。
 
 ## 本地开发
 

package/dist/cli.js

@@ -1,13 +1,10 @@
 #!/usr/bin/env node
 
-// src/cli.ts
-import path3 from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-
 // agent/src/cli.ts
 import { spawn as spawn2 } from "child_process";
 import { openSync as openSync2 } from "fs";
 import { cwd as processCwd2 } from "process";
+import { createInterface } from "readline/promises";
 import { setTimeout as delay2 } from "timers/promises";
 
 // agent/src/daemon.ts
@@ -53,6 +50,9 @@ function getAgentRuntimeFilePath() {
 function getAgentLogFilePath() {
   return path.join(getAgentHome(), "agent.log");
 }
+function getAgentConfigFilePath() {
+  return path.join(getAgentHome(), "config.json");
+}
 function getStateLockPath() {
   return `${getStateFilePath()}.lock`;
 }
@@ -175,6 +175,29 @@ function clearAgentRuntime(expectedPid) {
   }
   rmSync(getAgentRuntimeFilePath(), { force: true });
 }
+function loadAgentConfig() {
+  ensureAgentHome();
+  try {
+    const raw = readFileSync(getAgentConfigFilePath(), "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.relayUrl !== "string" || typeof parsed.deviceId !== "string") {
+      return null;
+    }
+    const relayUrl = parsed.relayUrl.trim();
+    const deviceId = parsed.deviceId.trim();
+    if (!relayUrl || !deviceId) {
+      return null;
+    }
+    return { relayUrl, deviceId };
+  } catch {
+    return null;
+  }
+}
+function saveAgentConfig(config) {
+  ensureAgentHome();
+  writeFileSync(getAgentConfigFilePath(), `${JSON.stringify(config, null, 2)}
+`, "utf8");
+}
 
 // agent/src/tmux-backend.ts
 import { randomUUID as randomUUID2 } from "crypto";
@@ -716,6 +739,7 @@ function printHelp() {
   console.log(`TermPilot agent \u7528\u6CD5\uFF1A
 
   termpilot agent
+  termpilot agent --pair
   termpilot agent --foreground
   termpilot agent status
   termpilot agent stop
@@ -813,10 +837,130 @@ async function runDoctor() {
 }
 function getDeviceId(argv) {
   const args = parseArgs(argv);
-  return resolveDeviceId(typeof args.deviceId === "string" ? args.deviceId : void 0);
+  const explicitDeviceId = typeof args.deviceId === "string" ? args.deviceId : void 0;
+  if (explicitDeviceId) {
+    return resolveDeviceId(explicitDeviceId);
+  }
+  const saved = loadAgentConfig();
+  return resolveDeviceId(saved?.deviceId);
+}
+function isLocalRelayHost(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || /^10\./.test(hostname) || /^192\.168\./.test(hostname) || /^172\.(1[6-9]|2\d|3[0-1])\./.test(hostname);
+}
+function normalizeRelayUrl(rawHost, rawPort) {
+  const hostInput = rawHost.trim();
+  const portInput = rawPort.trim() || "8787";
+  const normalizedPort = Number(portInput);
+  if (!Number.isFinite(normalizedPort) || normalizedPort <= 0 || normalizedPort > 65535) {
+    throw new Error("\u7AEF\u53E3\u65E0\u6548\uFF0C\u8BF7\u8F93\u5165 1 \u5230 65535 \u4E4B\u95F4\u7684\u6570\u5B57\u3002");
+  }
+  if (hostInput.includes("://")) {
+    const parsed = new URL(hostInput);
+    if (parsed.protocol === "http:") {
+      parsed.protocol = "ws:";
+    } else if (parsed.protocol === "https:") {
+      parsed.protocol = "wss:";
+    }
+    if (!parsed.port) {
+      parsed.port = String(normalizedPort);
+    }
+    if (!parsed.pathname || parsed.pathname === "/") {
+      parsed.pathname = "/ws";
+    }
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString();
+  }
+  const protocol = isLocalRelayHost(hostInput) ? "ws:" : "wss:";
+  return `${protocol}//${hostInput}:${normalizedPort}/ws`;
+}
+async function promptForAgentConfig(deviceId) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  try {
+    console.log("\u8FD8\u6CA1\u6709\u627E\u5230\u672C\u673A\u7684 relay \u914D\u7F6E\uFF0C\u5148\u505A\u4E00\u6B21\u521D\u59CB\u5316\u3002");
+    const host = (await rl.question("\u8BF7\u8F93\u5165 relay \u57DF\u540D\u6216 IP: ")).trim();
+    if (!host) {
+      throw new Error("\u672A\u8F93\u5165 relay \u57DF\u540D\u6216 IP\uFF0C\u5DF2\u53D6\u6D88\u3002");
+    }
+    const port = await rl.question("\u8BF7\u8F93\u5165 relay \u7AEF\u53E3\uFF08\u76F4\u63A5\u56DE\u8F66\u9ED8\u8BA4 8787\uFF09: ");
+    const relayUrl = normalizeRelayUrl(host, port);
+    console.log(`\u5C06\u4F7F\u7528 relay: ${relayUrl}`);
+    return { relayUrl, deviceId };
+  } finally {
+    rl.close();
+  }
 }
-function getRelayUrl() {
-  return process.env.TERMPILOT_RELAY_URL ?? "ws://127.0.0.1:8787/ws";
+function getResolvedConfig(argv) {
+  const args = parseArgs(argv);
+  const deviceId = getDeviceId(argv);
+  const cliRelayUrl = typeof args.relay === "string" ? args.relay.trim() : "";
+  if (cliRelayUrl) {
+    return {
+      source: "cli",
+      config: {
+        relayUrl: cliRelayUrl,
+        deviceId
+      }
+    };
+  }
+  const envRelayUrl = process.env.TERMPILOT_RELAY_URL?.trim();
+  if (envRelayUrl) {
+    return {
+      source: "env",
+      config: {
+        relayUrl: envRelayUrl,
+        deviceId
+      }
+    };
+  }
+  const saved = loadAgentConfig();
+  if (saved) {
+    return {
+      source: "saved",
+      config: {
+        relayUrl: saved.relayUrl,
+        deviceId
+      }
+    };
+  }
+  return null;
+}
+async function ensureConfigured(argv) {
+  const resolved = getResolvedConfig(argv);
+  if (resolved) {
+    return resolved;
+  }
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(`\u8FD8\u6CA1\u6709\u914D\u7F6E relay\uFF0C\u8BF7\u5148\u6267\u884C\uFF1Atermpilot agent --relay wss://\u4F60\u7684\u57DF\u540D/ws\uFF0C\u6216\u5728\u4EA4\u4E92\u7EC8\u7AEF\u91CC\u76F4\u63A5\u8FD0\u884C termpilot agent\u3002`);
+  }
+  const config = await promptForAgentConfig(getDeviceId(argv));
+  saveAgentConfig(config);
+  return { config, source: "prompt" };
+}
+function applyAgentConfig(config) {
+  process.env.TERMPILOT_RELAY_URL = config.relayUrl;
+  process.env.TERMPILOT_DEVICE_ID = config.deviceId;
+}
+function printRuntimeStatus(runtime = readRuntimeStatus().runtime) {
+  if (!runtime) {
+    console.log("\u540E\u53F0 agent \u5F53\u524D\u672A\u8FD0\u884C\u3002");
+    console.log(`\u72B6\u6001\u76EE\u5F55: ${getAgentHome()}`);
+    console.log(`\u914D\u7F6E\u6587\u4EF6: ${getAgentConfigFilePath()}`);
+    console.log(`\u65E5\u5FD7: ${getAgentLogFilePath()}`);
+    return;
+  }
+  const sessions = loadState().sessions.filter((session) => session.deviceId === runtime.deviceId);
+  const runningSessions = sessions.filter((session) => session.status === "running").length;
+  console.log("\u540E\u53F0 agent \u6B63\u5728\u8FD0\u884C\u3002");
+  console.log(`PID: ${runtime.pid}`);
+  console.log(`\u8BBE\u5907: ${runtime.deviceId}`);
+  console.log(`relay: ${runtime.relayUrl}`);
+  console.log(`\u542F\u52A8\u65F6\u95F4: ${runtime.startedAt}`);
+  console.log(`\u65E5\u5FD7: ${getAgentLogFilePath()}`);
+  console.log(`\u4F1A\u8BDD: ${runningSessions} \u4E2A\u8FD0\u884C\u4E2D / ${sessions.length} \u4E2A\u603B\u8BA1`);
 }
 function isProcessAlive(pid) {
   try {
@@ -855,23 +999,37 @@ async function waitForPairingCode(deviceId) {
 }
 async function runStart(argv) {
   const args = parseArgs(argv);
+  const shouldPair = Boolean(args.pair);
+  const { config, source } = await ensureConfigured(argv);
+  applyAgentConfig(config);
+  if (source === "cli" || source === "prompt") {
+    saveAgentConfig(config);
+  }
   if (args.foreground) {
     await runDaemon();
     return;
   }
-  const deviceId = getDeviceId(argv);
-  const relayUrl = getRelayUrl();
+  const deviceId = config.deviceId;
+  const relayUrl = config.relayUrl;
   const existing = readRuntimeStatus();
   if (existing.runtime && existing.alive) {
-    console.log(`\u540E\u53F0 agent \u5DF2\u5728\u8FD0\u884C\uFF0CPID: ${existing.runtime.pid}`);
-    console.log(`\u8BBE\u5907: ${existing.runtime.deviceId}`);
-    console.log(`relay: ${existing.runtime.relayUrl}`);
-    const pairing2 = await waitForPairingCode(deviceId);
-    if (pairing2) {
-      console.log(`\u914D\u5BF9\u7801: ${pairing2.pairingCode}`);
-      console.log(`\u6709\u6548\u671F\u81F3: ${pairing2.expiresAt}`);
+    const sameRuntime = existing.runtime.relayUrl === relayUrl && existing.runtime.deviceId === deviceId;
+    if (!sameRuntime) {
+      console.log("\u68C0\u6D4B\u5230\u540E\u53F0 agent \u5DF2\u5728\u8FD0\u884C\uFF0C\u4F46\u914D\u7F6E\u548C\u5F53\u524D\u547D\u4EE4\u4E0D\u4E00\u81F4\uFF0C\u6B63\u5728\u91CD\u542F\u3002");
+      await runStop();
+    } else {
+      printRuntimeStatus(existing.runtime);
+      if (shouldPair) {
+        const pairing = await waitForPairingCode(deviceId);
+        if (pairing) {
+          console.log(`\u914D\u5BF9\u7801: ${pairing.pairingCode}`);
+          console.log(`\u6709\u6548\u671F\u81F3: ${pairing.expiresAt}`);
+        }
+      } else {
+        console.log("\u5982\u9700\u91CD\u65B0\u7ED9\u624B\u673A\u914D\u5BF9\uFF0C\u8BF7\u6267\u884C\uFF1Atermpilot agent --pair");
+      }
+      return;
     }
-    return;
   }
   clearAgentRuntime();
   const logFilePath = getAgentLogFilePath();
@@ -895,11 +1053,18 @@ async function runStart(argv) {
   console.log(`\u8BBE\u5907: ${deviceId}`);
   console.log(`relay: ${relayUrl}`);
   console.log(`\u65E5\u5FD7: ${logFilePath}`);
-  const pairing = await waitForPairingCode(deviceId);
-  if (pairing) {
-    console.log(`\u914D\u5BF9\u7801: ${pairing.pairingCode}`);
-    console.log(`\u6709\u6548\u671F\u81F3: ${pairing.expiresAt}`);
-    console.log("\u624B\u673A\u7AEF\u76F4\u63A5\u6253\u5F00 relay \u9875\u9762\u5E76\u8F93\u5165\u8FD9\u4E2A\u914D\u5BF9\u7801\u5373\u53EF\u3002");
+  if (source === "prompt") {
+    console.log("\u672C\u6B21 relay \u914D\u7F6E\u5DF2\u4FDD\u5B58\u3002\u4EE5\u540E\u76F4\u63A5\u8FD0\u884C termpilot agent \u5373\u53EF\u3002");
+  }
+  if (shouldPair || source !== "saved") {
+    const pairing = await waitForPairingCode(deviceId);
+    if (pairing) {
+      console.log(`\u914D\u5BF9\u7801: ${pairing.pairingCode}`);
+      console.log(`\u6709\u6548\u671F\u81F3: ${pairing.expiresAt}`);
+      console.log("\u624B\u673A\u7AEF\u76F4\u63A5\u6253\u5F00 relay \u9875\u9762\u5E76\u8F93\u5165\u8FD9\u4E2A\u914D\u5BF9\u7801\u5373\u53EF\u3002");
+    }
+  } else {
+    console.log("\u5982\u9700\u91CD\u65B0\u7ED9\u624B\u673A\u914D\u5BF9\uFF0C\u8BF7\u6267\u884C\uFF1Atermpilot agent --pair");
   }
 }
 function runStatus() {
@@ -907,18 +1072,21 @@ function runStatus() {
   if (!runtime || !alive) {
     console.log("\u540E\u53F0 agent \u5F53\u524D\u672A\u8FD0\u884C\u3002");
     console.log(`\u72B6\u6001\u76EE\u5F55: ${getAgentHome()}`);
+    console.log(`\u914D\u7F6E\u6587\u4EF6: ${getAgentConfigFilePath()}`);
     console.log(`\u65E5\u5FD7: ${getAgentLogFilePath()}`);
+    const config2 = loadAgentConfig();
+    if (config2) {
+      console.log(`\u5DF2\u4FDD\u5B58 relay: ${config2.relayUrl}`);
+      console.log(`\u5DF2\u4FDD\u5B58\u8BBE\u5907: ${config2.deviceId}`);
+    }
     return;
   }
-  const sessions = loadState().sessions.filter((session) => session.deviceId === runtime.deviceId);
-  const runningSessions = sessions.filter((session) => session.status === "running").length;
-  console.log("\u540E\u53F0 agent \u6B63\u5728\u8FD0\u884C\u3002");
-  console.log(`PID: ${runtime.pid}`);
-  console.log(`\u8BBE\u5907: ${runtime.deviceId}`);
-  console.log(`relay: ${runtime.relayUrl}`);
-  console.log(`\u542F\u52A8\u65F6\u95F4: ${runtime.startedAt}`);
-  console.log(`\u65E5\u5FD7: ${getAgentLogFilePath()}`);
-  console.log(`\u4F1A\u8BDD: ${runningSessions} \u4E2A\u8FD0\u884C\u4E2D / ${sessions.length} \u4E2A\u603B\u8BA1`);
+  printRuntimeStatus(runtime);
+  const config = loadAgentConfig();
+  if (config && (config.relayUrl !== runtime.relayUrl || config.deviceId !== runtime.deviceId)) {
+    console.log(`\u5DF2\u4FDD\u5B58 relay: ${config.relayUrl}`);
+    console.log(`\u5DF2\u4FDD\u5B58\u8BBE\u5907: ${config.deviceId}`);
+  }
 }
 async function runStop() {
   const { runtime, alive } = readRuntimeStatus();
@@ -962,8 +1130,10 @@ async function runManagedCommand(argv) {
 }
 async function runDaemon() {
   await ensureTmuxAvailable();
-  const relayUrl = getRelayUrl();
-  const deviceId = resolveDeviceId();
+  const config = await ensureConfigured([]);
+  applyAgentConfig(config.config);
+  const relayUrl = config.config.relayUrl;
+  const deviceId = config.config.deviceId;
   saveAgentRuntime({
     pid: process.pid,
     relayUrl,
@@ -985,6 +1155,8 @@ async function runDaemon() {
   await daemon.start();
 }
 async function runPair(argv) {
+  const config = await ensureConfigured(argv);
+  applyAgentConfig(config.config);
   const deviceId = getDeviceId(argv);
   const payload = await createPairingCode(deviceId);
   console.log(`\u8BBE\u5907: ${payload.deviceId}`);
@@ -993,6 +1165,8 @@ async function runPair(argv) {
   console.log("\u8BF7\u5728\u624B\u673A\u7AEF\u8F93\u5165\u8FD9\u4E2A\u914D\u5BF9\u7801\uFF0C\u6362\u53D6\u8BBE\u5907\u8BBF\u95EE\u4EE4\u724C\u3002");
 }
 async function runGrants(argv) {
+  const config = await ensureConfigured(argv);
+  applyAgentConfig(config.config);
   const deviceId = getDeviceId(argv);
   const payload = await listDeviceGrants(deviceId);
   if (payload.grants.length === 0) {
@@ -1013,12 +1187,16 @@ async function runRevoke(argv) {
   if (!accessToken) {
     throw new Error("\u8BF7\u901A\u8FC7 --token \u6307\u5B9A\u8981\u64A4\u9500\u7684\u8BBF\u95EE\u4EE4\u724C\u3002");
   }
+  const config = await ensureConfigured(argv);
+  applyAgentConfig(config.config);
   const deviceId = getDeviceId(argv);
   await revokeDeviceGrant(deviceId, accessToken);
   console.log(`\u5DF2\u64A4\u9500\u8BBE\u5907 ${deviceId} \u7684\u8BBF\u95EE\u4EE4\u724C ${accessToken}`);
 }
 async function runAudit(argv) {
   const args = parseArgs(argv);
+  const config = await ensureConfigured(argv);
+  applyAgentConfig(config.config);
   const deviceId = getDeviceId(argv);
   const parsedLimit = typeof args.limit === "string" ? Number(args.limit) : 20;
   if (!Number.isFinite(parsedLimit) || parsedLimit <= 0) {
@@ -1099,9 +1277,75 @@ async function runAgentCli(argv = process.argv.slice(2)) {
   }
 }
 
+// relay/src/cli.ts
+import { spawn as spawn3 } from "child_process";
+import { openSync as openSync3 } from "fs";
+import { setTimeout as delay3 } from "timers/promises";
+
+// relay/src/config.ts
+function loadConfig() {
+  return {
+    host: process.env.HOST ?? "0.0.0.0",
+    port: Number(process.env.PORT ?? 8787),
+    agentToken: process.env.TERMPILOT_AGENT_TOKEN ?? DEFAULT_AGENT_TOKEN,
+    clientToken: process.env.TERMPILOT_CLIENT_TOKEN ?? DEFAULT_CLIENT_TOKEN,
+    databaseUrl: process.env.DATABASE_URL?.trim() || void 0,
+    pairingTtlMinutes: Number(process.env.TERMPILOT_PAIRING_TTL_MINUTES ?? 10)
+  };
+}
+
+// relay/src/runtime-store.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import path2 from "path";
+function getRelayHome() {
+  return process.env.TERMPILOT_HOME ?? path2.join(homedir2(), ".termpilot");
+}
+function ensureRelayHome() {
+  const dir = getRelayHome();
+  mkdirSync2(dir, { recursive: true });
+  return dir;
+}
+function getRelayRuntimeFilePath() {
+  return path2.join(getRelayHome(), "relay-runtime.json");
+}
+function getRelayLogFilePath() {
+  return path2.join(getRelayHome(), "relay.log");
+}
+function loadRelayRuntime() {
+  ensureRelayHome();
+  try {
+    const raw = readFileSync2(getRelayRuntimeFilePath(), "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.pid !== "number" || typeof parsed.host !== "string" || typeof parsed.port !== "number" || typeof parsed.startedAt !== "string") {
+      return null;
+    }
+    return {
+      pid: parsed.pid,
+      host: parsed.host,
+      port: parsed.port,
+      startedAt: parsed.startedAt
+    };
+  } catch {
+    return null;
+  }
+}
+function saveRelayRuntime(runtime) {
+  ensureRelayHome();
+  writeFileSync2(getRelayRuntimeFilePath(), `${JSON.stringify(runtime, null, 2)}
+`, "utf8");
+}
+function clearRelayRuntime(expectedPid) {
+  const current = loadRelayRuntime();
+  if (expectedPid !== void 0 && current?.pid !== expectedPid) {
+    return;
+  }
+  rmSync2(getRelayRuntimeFilePath(), { force: true });
+}
+
 // relay/src/server.ts
 import { createReadStream, existsSync, statSync as statSync2 } from "fs";
-import path2 from "path";
+import path3 from "path";
 import { fileURLToPath } from "url";
 import Fastify from "fastify";
 import websocket from "@fastify/websocket";
@@ -1403,18 +1647,6 @@ var PostgresAuditStore = class {
   }
 };
 
-// relay/src/config.ts
-function loadConfig() {
-  return {
-    host: process.env.HOST ?? "0.0.0.0",
-    port: Number(process.env.PORT ?? 8787),
-    agentToken: process.env.TERMPILOT_AGENT_TOKEN ?? DEFAULT_AGENT_TOKEN,
-    clientToken: process.env.TERMPILOT_CLIENT_TOKEN ?? DEFAULT_CLIENT_TOKEN,
-    databaseUrl: process.env.DATABASE_URL?.trim() || void 0,
-    pairingTtlMinutes: Number(process.env.TERMPILOT_PAIRING_TTL_MINUTES ?? 10)
-  };
-}
-
 // relay/src/session-store.ts
 var MemorySessionStore = class {
   mode = "memory";
@@ -1588,24 +1820,24 @@ var STATIC_CONTENT_TYPES = {
   ".webmanifest": "application/manifest+json; charset=utf-8"
 };
 function getMimeType(filePath) {
-  return STATIC_CONTENT_TYPES[path2.extname(filePath).toLowerCase()] ?? "application/octet-stream";
+  return STATIC_CONTENT_TYPES[path3.extname(filePath).toLowerCase()] ?? "application/octet-stream";
 }
 function createStaticPath(webDir, urlPath) {
   const requestPath = decodeURIComponent(urlPath.split("?")[0] ?? "/");
   const relativePath = requestPath === "/" ? "index.html" : requestPath.replace(/^\/+/, "");
-  const resolvedPath = path2.resolve(webDir, relativePath);
-  if (!resolvedPath.startsWith(path2.resolve(webDir))) {
-    return path2.join(webDir, "index.html");
+  const resolvedPath = path3.resolve(webDir, relativePath);
+  if (!resolvedPath.startsWith(path3.resolve(webDir))) {
+    return path3.join(webDir, "index.html");
   }
   if (!existsSync(resolvedPath)) {
-    return path2.join(webDir, "index.html");
+    return path3.join(webDir, "index.html");
   }
   try {
     if (statSync2(resolvedPath).isDirectory()) {
-      return path2.join(webDir, "index.html");
+      return path3.join(webDir, "index.html");
     }
   } catch {
-    return path2.join(webDir, "index.html");
+    return path3.join(webDir, "index.html");
   }
   return resolvedPath;
 }
@@ -2080,6 +2312,129 @@ async function startRelayServer(options = {}) {
   return app;
 }
 
+// relay/src/cli.ts
+function isProcessAlive2(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function readRuntimeStatus2() {
+  const runtime = loadRelayRuntime();
+  if (!runtime) {
+    return { runtime: null, alive: false };
+  }
+  const alive = isProcessAlive2(runtime.pid);
+  if (!alive) {
+    clearRelayRuntime(runtime.pid);
+    return { runtime: null, alive: false };
+  }
+  return { runtime, alive };
+}
+function printRuntime(runtime = readRuntimeStatus2().runtime) {
+  if (!runtime) {
+    console.log("\u540E\u53F0 relay \u5F53\u524D\u672A\u8FD0\u884C\u3002");
+    console.log(`\u8FD0\u884C\u65F6\u6587\u4EF6: ${getRelayRuntimeFilePath()}`);
+    console.log(`\u65E5\u5FD7: ${getRelayLogFilePath()}`);
+    return;
+  }
+  console.log("\u540E\u53F0 relay \u6B63\u5728\u8FD0\u884C\u3002");
+  console.log(`PID: ${runtime.pid}`);
+  console.log(`\u76D1\u542C: http://${runtime.host}:${runtime.port}`);
+  console.log(`\u542F\u52A8\u65F6\u95F4: ${runtime.startedAt}`);
+  console.log(`\u65E5\u5FD7: ${getRelayLogFilePath()}`);
+}
+async function runForeground() {
+  const config = loadConfig();
+  saveRelayRuntime({
+    pid: process.pid,
+    host: config.host,
+    port: config.port,
+    startedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  process.on("exit", () => {
+    clearRelayRuntime(process.pid);
+  });
+  await startRelayServer({ webDir: resolveDefaultWebDir(import.meta.url), config });
+  await new Promise(() => {
+  });
+}
+async function runStart2() {
+  const config = loadConfig();
+  const existing = readRuntimeStatus2();
+  if (existing.runtime && existing.alive) {
+    const sameConfig = existing.runtime.host === config.host && existing.runtime.port === config.port;
+    if (sameConfig) {
+      printRuntime(existing.runtime);
+      return;
+    }
+    console.log("\u68C0\u6D4B\u5230\u540E\u53F0 relay \u5DF2\u5728\u8FD0\u884C\uFF0C\u4F46\u76D1\u542C\u914D\u7F6E\u548C\u5F53\u524D\u547D\u4EE4\u4E0D\u4E00\u81F4\uFF0C\u6B63\u5728\u91CD\u542F\u3002");
+    await runStop2();
+  }
+  clearRelayRuntime();
+  const logFilePath = getRelayLogFilePath();
+  const logFd = openSync3(logFilePath, "a");
+  const child = spawn3(process.execPath, [process.argv[1], "relay-daemon"], {
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+    env: process.env
+  });
+  child.unref();
+  if (!child.pid) {
+    throw new Error("\u540E\u53F0 relay \u542F\u52A8\u5931\u8D25\uFF0C\u672A\u83B7\u53D6\u5230\u5B50\u8FDB\u7A0B PID\u3002");
+  }
+  saveRelayRuntime({
+    pid: child.pid,
+    host: config.host,
+    port: config.port,
+    startedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  console.log(`\u540E\u53F0 relay \u5DF2\u542F\u52A8\uFF0CPID: ${child.pid}`);
+  console.log(`\u76D1\u542C: http://${config.host}:${config.port}`);
+  console.log(`\u65E5\u5FD7: ${logFilePath}`);
+  await delay3(300);
+}
+async function runStop2() {
+  const { runtime, alive } = readRuntimeStatus2();
+  if (!runtime || !alive) {
+    console.log("\u540E\u53F0 relay \u5F53\u524D\u672A\u8FD0\u884C\u3002");
+    clearRelayRuntime();
+    return;
+  }
+  process.kill(runtime.pid, "SIGTERM");
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    if (!isProcessAlive2(runtime.pid)) {
+      clearRelayRuntime(runtime.pid);
+      console.log(`\u540E\u53F0 relay \u5DF2\u505C\u6B62\uFF0CPID: ${runtime.pid}`);
+      return;
+    }
+    await delay3(100);
+  }
+  process.kill(runtime.pid, "SIGKILL");
+  clearRelayRuntime(runtime.pid);
+  console.log(`\u540E\u53F0 relay \u5DF2\u5F3A\u5236\u505C\u6B62\uFF0CPID: ${runtime.pid}`);
+}
+async function runRelayCli(argv = process.argv.slice(2)) {
+  const [command] = argv;
+  if (!command || command === "start") {
+    await runStart2();
+    return;
+  }
+  switch (command) {
+    case "run":
+    case "daemon":
+      await runForeground();
+      return;
+    case "stop":
+      await runStop2();
+      return;
+    default:
+      throw new Error(`\u672A\u77E5 relay \u5B50\u547D\u4EE4: ${command}`);
+  }
+}
+
 // src/cli.ts
 var AGENT_ENV_FLAGS = [
   { flag: "--relay", envName: "TERMPILOT_RELAY_URL" },
@@ -2099,8 +2454,11 @@ var RELAY_ENV_FLAGS = [
 function printHelp2() {
   console.log(`TermPilot \u7528\u6CD5\uFF1A
 
-  termpilot relay [--host 0.0.0.0] [--port 8787]
-  termpilot agent [--relay ws://127.0.0.1:8787/ws] [--device-id pc-main]
+  termpilot relay
+  termpilot relay start
+  termpilot relay stop
+  termpilot relay run
+  termpilot agent [--pair] [--relay ws://127.0.0.1:8787/ws] [--device-id pc-main]
   termpilot agent status
   termpilot agent stop
   termpilot claude code
@@ -2135,9 +2493,6 @@ function applyEnvFlags(argv, mappings) {
   }
   return rest;
 }
-function resolveBundledWebDir() {
-  return path3.resolve(path3.dirname(fileURLToPath2(import.meta.url)), "../app/dist");
-}
 async function main(argv = process.argv.slice(2)) {
   const normalizedArgv = argv[0] === "--" ? argv.slice(1) : argv;
   const [command, ...rest] = normalizedArgv;
@@ -2152,7 +2507,10 @@ async function main(argv = process.argv.slice(2)) {
         printHelp2();
         return;
       }
-      await startRelayServer({ webDir: resolveBundledWebDir() });
+      if (relayArgs[0] === "status") {
+        throw new Error("\u672A\u77E5 relay \u5B50\u547D\u4EE4: status");
+      }
+      await runRelayCli(relayArgs);
       return;
     }
     case "agent": {
@@ -2168,6 +2526,10 @@ async function main(argv = process.argv.slice(2)) {
       await runAgentCli(["daemon", ...rest]);
       return;
     }
+    case "relay-daemon": {
+      await runRelayCli(["daemon", ...rest]);
+      return;
+    }
     case "pair":
     case "create":
     case "list":

package/docs/README.md

@@ -1,6 +1,7 @@
 # 文档索引
 
 - [README.md](/Users/fengye/workspace/TermPilot/README.md)：用户安装、启动和日常使用
+- [operations-guide.md](/Users/fengye/workspace/TermPilot/docs/operations-guide.md)：部署、反代、运维和排障手册
 - [development.md](/Users/fengye/workspace/TermPilot/docs/development.md)：仓库开发、测试和发布流程
 - [architecture.md](/Users/fengye/workspace/TermPilot/docs/architecture.md)：当前代码架构和运行时数据流
 - [protocol.md](/Users/fengye/workspace/TermPilot/docs/protocol.md)：三端协议和 HTTP 接口

package/docs/architecture.md

@@ -91,8 +91,10 @@ PC 端常驻进程和本地命令实现：
 
 1. 服务器执行 `termpilot relay`
 2. relay 监听 HTTP/WebSocket，并托管 `app/dist`
-3. 电脑执行 `termpilot agent --relay ...`
-4. 手机上直接打开 relay 域名
+3. 电脑第一次执行 `termpilot agent`，在终端里输入 relay 域名和端口
+4. agent 保存本地配置，并在后台启动常驻进程
+5. 以后电脑直接执行 `termpilot agent`，自动按已保存配置启动或显示状态
+6. 手机上直接打开 relay 域名
 
 ### 会话创建
 
@@ -112,11 +114,12 @@ PC 端常驻进程和本地命令实现：
 
 ### 配对与访问控制
 
-1. 电脑端执行 `termpilot agent --relay ws://你的 relay 地址`
-2. relay 创建一次性配对码
-3. 手机端输入配对码，兑换设备访问令牌
-4. client WebSocket 以后携带设备令牌
-5. relay 只向该 client 暴露允许访问的设备和会话
+1. 电脑端执行 `termpilot agent`
+2. 如果本机还没有配置 relay，agent 会提示输入域名和端口，并保存到本地配置文件
+3. relay 创建一次性配对码
+4. 手机端输入配对码，兑换设备访问令牌
+5. client WebSocket 以后携带设备令牌
+6. relay 只向该 client 暴露允许访问的设备和会话
 
 ## 4. 当前实现边界
 

package/docs/operations-guide.md

@@ -0,0 +1,445 @@
+# TermPilot 部署与运维指南
+
+这份文档面向准备长期使用 TermPilot 的用户。它不重复 `README` 里的 5 分钟快速上手，而是把部署、反代、日常运维、排障和安全边界收成一份更完整的运行手册。
+
+文档风格参考了成熟开源项目常见的写法：先说明适用场景，再给推荐拓扑、部署步骤、运维动作、排障清单和安全边界。你可以把它当成 TermPilot 的管理员手册来用。
+
+## 0. 阅读这份文档前，你应该已经知道什么
+
+建议你已经完成过下面这件事中的至少一件：
+
+- 在本地把 `termpilot relay`、`termpilot agent` 跑通过一次
+- 已经看过 [README.md](/Users/fengye/workspace/TermPilot/README.md) 里的快速上手
+
+如果你还没有跑通过最小链路，请先回到 [README.md](/Users/fengye/workspace/TermPilot/README.md)。
+
+## 1. 适用场景
+
+适合下面这些情况：
+
+- 你已经确认 TermPilot 的基本流程可用，准备长期跑在自己的服务器上
+- 你希望用域名和 HTTPS/WSS 暴露 relay，而不是直接用裸 IP 和端口
+- 你需要给自己或团队整理一份可维护的运行说明
+
+不适合下面这些情况：
+
+- 第一次体验产品
+- 只想在局域网里临时试一下
+
+第一次使用请先看 [README.md](/Users/fengye/workspace/TermPilot/README.md)。
+
+## 2. 部署清单
+
+开始之前，先确认下面这些前置条件：
+
+- 一台能被手机访问到的服务器
+- 一个已经解析到服务器的域名
+- 服务器已经放行 `80` 和 `443`
+- 电脑端已经安装 `tmux`
+- 服务器和电脑都已经安装 `@fengye404/termpilot`
+
+推荐你按这个顺序推进：
+
+1. 先让服务器上的 `termpilot relay` 跑起来
+2. 再让域名和 HTTPS 反代跑起来
+3. 再在电脑执行 `termpilot agent`
+4. 最后用手机完成第一次配对
+
+## 3. 运行模型
+
+TermPilot 由三部分组成：
+
+- `relay`：运行在云服务器上，负责网页托管、WebSocket 中继、配对、设备权限和会话元数据
+- `agent`：运行在你的电脑上，负责管理本地 `tmux` 会话并连接 relay
+- `app`：手机浏览器直接打开 relay 域名，不需要单独安装 App
+
+推荐拓扑：
+
+```text
+手机浏览器  --https/wss-->  域名 / 反向代理  -->  relay
+                                               ^
+                                               |
+                                     agent --wss--> /ws
+```
+
+## 4. 推荐部署模式
+
+### 模式 A：最低成本验证
+
+- 服务器上直接运行 `termpilot relay`
+- 对外暴露 `8787`
+- 手机访问 `http://your-ip:8787`
+- 电脑连接 `ws://your-ip:8787/ws`
+
+适合：
+
+- 自己先试通链路
+- 不想先配置域名和 HTTPS
+
+缺点：
+
+- 没有 HTTPS/WSS
+- 不适合长期使用
+
+### 模式 B：推荐生产模式
+
+- 服务器上运行 `termpilot relay`
+- 前面放一个反向代理，例如 Caddy
+- 域名直接指向服务器
+- 手机访问 `https://your-domain.com`
+- 电脑连接 `wss://your-domain.com/ws`
+
+适合：
+
+- 个人长期使用
+- 多设备跨网络访问
+- 想降低手机端访问阻力
+
+## 5. 生产部署步骤
+
+### 5.1 域名解析
+
+把你的域名 A 记录指向服务器公网 IP，例如：
+
+- `fengye404.top -> 你的服务器公网 IP`
+
+### 5.2 服务器启动 relay
+
+最简单的后台启动：
+
+```bash
+termpilot relay
+```
+
+常用命令：
+
+```bash
+termpilot relay
+termpilot relay stop
+termpilot relay run
+```
+
+说明：
+
+- `termpilot relay` 或 `termpilot relay start`：后台启动
+- `termpilot relay stop`：停止后台 relay
+- `termpilot relay run`：前台运行，适合看日志
+
+默认监听：
+
+- `host=0.0.0.0`
+- `port=8787`
+
+### 5.3 反向代理
+
+推荐用 Caddy。最小配置如下：
+
+```caddyfile
+fengye404.top {
+    reverse_proxy 127.0.0.1:8787
+}
+```
+
+这会同时转发：
+
+- 网页请求 `/`
+- WebSocket `/ws`
+
+### 5.4 电脑启动 agent
+
+第一次：
+
+```bash
+termpilot agent
+```
+
+然后在终端里输入：
+
+1. relay 域名或 IP
+2. 端口，直接回车默认 `8787`
+
+TermPilot 会自动：
+
+- 保存本地配置
+- 后台启动 agent
+- 输出一次性配对码
+
+以后日常：
+
+```bash
+termpilot agent
+```
+
+如果你只想重新生成一个配对码：
+
+```bash
+termpilot agent --pair
+```
+
+### 5.5 首次上线后的验收
+
+如果你刚完成一套新部署，建议按下面顺序验收：
+
+1. 服务器执行 `termpilot relay`，确认后台已启动
+2. 服务器本机执行 `curl http://127.0.0.1:8787/health`
+3. 手机打开 `https://your-domain.com`
+4. 电脑执行 `termpilot agent`
+5. 确认终端里已经打印出配对码
+6. 手机输入配对码并进入会话列表
+7. 电脑执行 `termpilot claude code`
+8. 确认手机端能看到同一个会话的输出
+
+## 6. 目录、数据与状态文件
+
+默认状态目录：
+
+```text
+~/.termpilot
+```
+
+常见文件：
+
+- `config.json`：agent 本地保存的 relay 配置
+- `agent-runtime.json`：后台 agent 运行时状态
+- `relay-runtime.json`：后台 relay 运行时状态
+- `agent.log`：agent 日志
+- `relay.log`：relay 日志
+- `state.json`：本地会话状态
+
+如果你想切换状态目录，可以设置：
+
+```bash
+TERMPILOT_HOME=/your/path termpilot agent
+TERMPILOT_HOME=/your/path termpilot relay
+```
+
+## 7. 推荐的日常工作流
+
+### 7.1 服务器
+
+长期保持：
+
+```bash
+termpilot relay
+```
+
+只有排障时才用：
+
+```bash
+termpilot relay run
+```
+
+### 7.2 电脑
+
+日常只记住：
+
+```bash
+termpilot agent
+```
+
+如果你要跑任务，最短路径是：
+
+```bash
+termpilot claude code
+```
+
+或者：
+
+```bash
+termpilot open code
+```
+
+### 7.3 手机
+
+长期固定访问：
+
+- `https://your-domain.com`
+
+第一次用配对码，之后正常重连不应该要求重新配对。
+
+## 8. 运维动作速查
+
+### 8.1 relay
+
+后台启动：
+
+```bash
+termpilot relay
+```
+
+查看前台日志：
+
+```bash
+termpilot relay run
+```
+
+停止后台 relay：
+
+```bash
+termpilot relay stop
+```
+
+### 8.2 agent
+
+按本机配置启动或查看状态：
+
+```bash
+termpilot agent
+```
+
+重新生成配对码：
+
+```bash
+termpilot agent --pair
+```
+
+查看后台状态：
+
+```bash
+termpilot agent status
+```
+
+停止后台 agent：
+
+```bash
+termpilot agent stop
+```
+
+### 8.3 会话
+
+直接启动常见任务：
+
+```bash
+termpilot claude code
+termpilot open code
+```
+
+手动管理会话：
+
+```bash
+termpilot create --name my-task --cwd /path/to/project
+termpilot list
+termpilot attach --sid <sid>
+termpilot kill --sid <sid>
+```
+
+## 9. 故障排查
+
+### 9.1 手机打开域名，但页面进不去
+
+优先检查：
+
+- DNS 是否已经生效
+- `80` / `443` 是否放行
+- 反向代理是否已启动
+- `termpilot relay` 是否真的在跑
+
+服务器检查：
+
+```bash
+termpilot relay
+curl http://127.0.0.1:8787/health
+```
+
+### 9.2 电脑端执行 `termpilot agent` 后手机还是看不到设备
+
+优先检查：
+
+- 电脑是否真的能连到 relay
+- agent 是否已经后台运行
+- 是否第一次配对还没完成
+
+电脑检查：
+
+```bash
+termpilot agent
+termpilot agent status
+```
+
+### 9.3 手机端看不到某个任务
+
+最常见原因：
+
+- 这个任务不是通过 TermPilot 管理的会话启动的
+
+正确做法：
+
+```bash
+termpilot claude code
+```
+
+或：
+
+```bash
+termpilot create --name my-task --cwd /path/to/project
+termpilot attach --sid <sid>
+```
+
+### 9.4 想重新绑定手机
+
+```bash
+termpilot agent --pair
+```
+
+如果要撤销旧设备访问令牌：
+
+```bash
+termpilot grants
+termpilot revoke --token <accessToken>
+```
+
+### 9.5 relay 或 agent 想看实时日志
+
+relay：
+
+```bash
+termpilot relay run
+```
+
+agent：
+
+```bash
+termpilot agent --foreground
+```
+
+### 9.6 我改了域名或端口，电脑还是连旧地址
+
+先停掉后台 agent，再重新执行一次交互配置：
+
+```bash
+termpilot agent stop
+termpilot agent
+```
+
+如果你使用了自定义状态目录，也要确认是不是改到了另一个 `TERMPILOT_HOME`。
+
+## 10. 安全建议
+
+- 正式环境优先使用域名 + HTTPS/WSS，不要长期裸露 `ws://ip:8787/ws`
+- 不要长期传播手机端访问令牌
+- 换手机或多人共享设备后，及时撤销旧令牌
+- 如果准备长期保存会话元数据，relay 建议接 PostgreSQL
+- 不要把外网入口直接暴露到非预期端口和无 TLS 配置上
+
+## 11. 升级建议
+
+推荐的升级节奏：
+
+1. 先在一台日常不关键的机器上升级验证
+2. 确认 `termpilot relay` 和 `termpilot agent` 都能正常启动
+3. 用手机完成一次真实配对和会话查看
+4. 再升级主力机器
+
+如果升级后出现异常，优先检查：
+
+- `~/.termpilot/relay.log`
+- `~/.termpilot/agent.log`
+- `curl http://127.0.0.1:8787/health`
+- `termpilot agent status`
+
+## 12. 建议的文档阅读顺序
+
+1. [README.md](/Users/fengye/workspace/TermPilot/README.md)
+2. [architecture.md](/Users/fengye/workspace/TermPilot/docs/architecture.md)
+3. [protocol.md](/Users/fengye/workspace/TermPilot/docs/protocol.md)
+4. 本文档

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fengye404/termpilot",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "packageManager": "pnpm@10.31.0",
   "description": "一个基于 tmux 的终端会话跨端查看与控制原型。",