@fengye404/termpilot 0.1.9 → 0.2.1

package/dist/cli.js

@@ -649,7 +649,10 @@ function createDaemonFromEnv() {
 }
 
 // agent/src/relay-admin.ts
-function getRelayBaseUrl() {
+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 getRelayBaseCandidates() {
   const relayUrl = process.env.TERMPILOT_RELAY_URL ?? "ws://127.0.0.1:8787/ws";
   let url;
   try {
@@ -657,10 +660,31 @@ function getRelayBaseUrl() {
   } catch {
     throw new Error("TERMPILOT_RELAY_URL \u65E0\u6548\uFF0C\u8BF7\u63D0\u4F9B\u5B8C\u6574\u7684 ws:// \u6216 wss:// \u5730\u5740\u3002");
   }
+  const wsUrl = new URL(url.toString());
+  wsUrl.search = "";
+  wsUrl.hash = "";
+  if (!wsUrl.pathname || wsUrl.pathname === "/") {
+    wsUrl.pathname = "/ws";
+  }
   url.protocol = url.protocol === "wss:" ? "https:" : "http:";
   url.pathname = "/";
   url.search = "";
-  return url.toString();
+  url.hash = "";
+  const candidates = [{
+    baseUrl: url.toString(),
+    relayUrl: wsUrl.toString()
+  }];
+  if (!isLocalRelayHost(url.hostname) && url.port === "8787") {
+    const fallbackBase = new URL(url.toString());
+    fallbackBase.port = "";
+    const fallbackRelay = new URL(wsUrl.toString());
+    fallbackRelay.port = "";
+    candidates.push({
+      baseUrl: fallbackBase.toString(),
+      relayUrl: fallbackRelay.toString()
+    });
+  }
+  return candidates;
 }
 function getAgentToken() {
   return process.env.TERMPILOT_AGENT_TOKEN ?? DEFAULT_AGENT_TOKEN;
@@ -675,18 +699,31 @@ async function readJsonOrThrow(response, message) {
   return response.json();
 }
 async function fetchJson(input, init, message) {
-  let response;
-  try {
-    response = await fetch(input, init);
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : "\u672A\u77E5\u7F51\u7EDC\u9519\u8BEF";
-    throw new Error(`${message}: \u65E0\u6CD5\u8FDE\u63A5 relay (${input.origin})\uFF0C${detail}`);
+  const candidates = getRelayBaseCandidates();
+  let lastError = null;
+  let lastOrigin = input.origin;
+  for (const candidate of candidates) {
+    const target = new URL(input.pathname + input.search, candidate.baseUrl);
+    lastOrigin = target.origin;
+    let response;
+    try {
+      response = await fetch(target, init);
+    } catch (error) {
+      lastError = error;
+      continue;
+    }
+    const payload = await readJsonOrThrow(response, message);
+    if (process.env.TERMPILOT_RELAY_URL !== candidate.relayUrl) {
+      process.env.TERMPILOT_RELAY_URL = candidate.relayUrl;
+    }
+    return payload;
   }
-  return readJsonOrThrow(response, message);
+  const detail = lastError instanceof Error ? lastError.message : "\u672A\u77E5\u7F51\u7EDC\u9519\u8BEF";
+  throw new Error(`${message}: \u65E0\u6CD5\u8FDE\u63A5 relay (${lastOrigin})\uFF0C${detail}`);
 }
 async function createPairingCode(deviceId) {
   return fetchJson(
-    new URL("/api/pairing-codes", getRelayBaseUrl()),
+    new URL("/api/pairing-codes", "https://placeholder.invalid"),
     {
       method: "POST",
       headers: {
@@ -700,7 +737,7 @@ async function createPairingCode(deviceId) {
 }
 async function listDeviceGrants(deviceId) {
   return fetchJson(
-    new URL(`/api/devices/${deviceId}/grants`, getRelayBaseUrl()),
+    new URL(`/api/devices/${deviceId}/grants`, "https://placeholder.invalid"),
     {
       headers: {
         authorization: `Bearer ${getAgentToken()}`
@@ -711,7 +748,7 @@ async function listDeviceGrants(deviceId) {
 }
 async function revokeDeviceGrant(deviceId, accessToken) {
   await fetchJson(
-    new URL(`/api/devices/${deviceId}/grants/${accessToken}`, getRelayBaseUrl()),
+    new URL(`/api/devices/${deviceId}/grants/${accessToken}`, "https://placeholder.invalid"),
     {
       method: "DELETE",
       headers: {
@@ -724,7 +761,7 @@ async function revokeDeviceGrant(deviceId, accessToken) {
 async function listAuditEvents(deviceId, limit) {
   const constrainedLimit = Math.max(1, Math.min(limit, 100));
   return fetchJson(
-    new URL(`/api/devices/${deviceId}/audit-events?limit=${constrainedLimit}`, getRelayBaseUrl()),
+    new URL(`/api/devices/${deviceId}/audit-events?limit=${constrainedLimit}`, "https://placeholder.invalid"),
     {
       headers: {
         authorization: `Bearer ${getAgentToken()}`
@@ -844,7 +881,7 @@ function getDeviceId(argv) {
   const saved = loadAgentConfig();
   return resolveDeviceId(saved?.deviceId);
 }
-function isLocalRelayHost(hostname) {
+function isLocalRelayHost2(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) {
@@ -863,7 +900,7 @@ function normalizeRelayUrl(rawHost, rawPort) {
         throw new Error("\u7AEF\u53E3\u65E0\u6548\uFF0C\u8BF7\u8F93\u5165 1 \u5230 65535 \u4E4B\u95F4\u7684\u6570\u5B57\u3002");
       }
       parsed.port = String(normalizedPort2);
-    } else if (!parsed.port && parsed.protocol === "ws:" && isLocalRelayHost(parsed.hostname)) {
+    } else if (!parsed.port && parsed.protocol === "ws:" && isLocalRelayHost2(parsed.hostname)) {
       parsed.port = "8787";
     }
     if (!parsed.pathname || parsed.pathname === "/") {
@@ -873,7 +910,7 @@ function normalizeRelayUrl(rawHost, rawPort) {
     parsed.hash = "";
     return parsed.toString();
   }
-  const protocol = isLocalRelayHost(hostInput) ? "ws:" : "wss:";
+  const protocol = isLocalRelayHost2(hostInput) ? "ws:" : "wss:";
   if (!portInput) {
     if (protocol === "ws:") {
       return `${protocol}//${hostInput}:8787/ws`;
@@ -956,6 +993,27 @@ function applyAgentConfig(config) {
   process.env.TERMPILOT_RELAY_URL = config.relayUrl;
   process.env.TERMPILOT_DEVICE_ID = config.deviceId;
 }
+function persistMigratedRelayUrl(deviceId) {
+  const migratedRelayUrl = process.env.TERMPILOT_RELAY_URL?.trim();
+  if (!migratedRelayUrl) {
+    return;
+  }
+  const saved = loadAgentConfig();
+  if (saved && saved.deviceId === deviceId && saved.relayUrl !== migratedRelayUrl) {
+    saveAgentConfig({
+      relayUrl: migratedRelayUrl,
+      deviceId
+    });
+    console.log(`\u5DF2\u81EA\u52A8\u66F4\u65B0 relay \u5730\u5740\u4E3A: ${migratedRelayUrl}`);
+  }
+  const runtime = loadAgentRuntime();
+  if (runtime && runtime.deviceId === deviceId && runtime.relayUrl !== migratedRelayUrl) {
+    saveAgentRuntime({
+      ...runtime,
+      relayUrl: migratedRelayUrl
+    });
+  }
+}
 function printRuntimeStatus(runtime = readRuntimeStatus().runtime) {
   if (!runtime) {
     console.log("\u540E\u53F0 agent \u5F53\u524D\u672A\u8FD0\u884C\u3002");
@@ -998,7 +1056,9 @@ async function waitForPairingCode(deviceId) {
   let lastError = null;
   for (let attempt = 0; attempt < 12; attempt += 1) {
     try {
-      return await createPairingCode(deviceId);
+      const payload = await createPairingCode(deviceId);
+      persistMigratedRelayUrl(deviceId);
+      return payload;
     } catch (error) {
       lastError = error;
       await delay2(500);
@@ -1171,6 +1231,7 @@ async function runPair(argv) {
   applyAgentConfig(config.config);
   const deviceId = getDeviceId(argv);
   const payload = await createPairingCode(deviceId);
+  persistMigratedRelayUrl(deviceId);
   console.log(`\u8BBE\u5907: ${payload.deviceId}`);
   console.log(`\u914D\u5BF9\u7801: ${payload.pairingCode}`);
   console.log(`\u6709\u6548\u671F\u81F3: ${payload.expiresAt}`);
@@ -1181,6 +1242,7 @@ async function runGrants(argv) {
   applyAgentConfig(config.config);
   const deviceId = getDeviceId(argv);
   const payload = await listDeviceGrants(deviceId);
+  persistMigratedRelayUrl(deviceId);
   if (payload.grants.length === 0) {
     console.log(`\u8BBE\u5907 ${payload.deviceId} \u5F53\u524D\u6CA1\u6709\u4EFB\u4F55\u5DF2\u7ED1\u5B9A\u8BBF\u95EE\u4EE4\u724C\u3002`);
     return;
@@ -1203,6 +1265,7 @@ async function runRevoke(argv) {
   applyAgentConfig(config.config);
   const deviceId = getDeviceId(argv);
   await revokeDeviceGrant(deviceId, accessToken);
+  persistMigratedRelayUrl(deviceId);
   console.log(`\u5DF2\u64A4\u9500\u8BBE\u5907 ${deviceId} \u7684\u8BBF\u95EE\u4EE4\u724C ${accessToken}`);
 }
 async function runAudit(argv) {
@@ -1216,6 +1279,7 @@ async function runAudit(argv) {
   }
   const limit = Math.floor(parsedLimit);
   const payload = await listAuditEvents(deviceId, limit);
+  persistMigratedRelayUrl(deviceId);
   if (payload.events.length === 0) {
     console.log(`\u8BBE\u5907 ${payload.deviceId} \u5F53\u524D\u6CA1\u6709\u5BA1\u8BA1\u65E5\u5FD7\u3002`);
     return;

package/docs/getting-started.md

@@ -7,7 +7,7 @@
 - 一台服务器，或者一台手机能访问到的局域网机器
 - 一台作为主力开发机的电脑
 - 电脑上已经安装 `tmux`
-- 两端都安装了 `Node.js`
+- 两端都安装了 `Node.js 22+`
 
 安装 TermPilot：
 

package/docs/tech-selection-2026.md

@@ -5,7 +5,7 @@
 这次技术选型只保留已经拍板的方案，不再保留多余备选。
 
 - 语言：TypeScript
-- 运行时：Node.js 24 LTS
+- 运行时：Node.js 22+（推荐 24 LTS）
 - 包管理：pnpm workspace
 
 手机端 `app/`：
@@ -74,4 +74,4 @@ TermPilot 现在要的不是“技术看起来完整”，而是：
 
 ## 一句话总结
 
-**TermPilot 当前最合理、最 AI 友好的全栈方案，就是 `TypeScript + Node.js 24 LTS + pnpm workspace`，在此基础上，手机端用 `React + Vite + Tailwind CSS + xterm.js`，中继服务用 `Fastify + WebSocket + PostgreSQL`，PC 端围绕 `tmux`。**
+**TermPilot 当前最合理、最 AI 友好的全栈方案，就是 `TypeScript + Node.js 22+ + pnpm workspace`，在此基础上，手机端用 `React + Vite + Tailwind CSS + xterm.js`，中继服务用 `Fastify + WebSocket + PostgreSQL`，PC 端围绕 `tmux`。推荐运行在 Node.js 24 LTS 上，但不强制要求。**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fengye404/termpilot",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "type": "module",
   "packageManager": "pnpm@10.31.0",
   "description": "一个基于 tmux 的终端会话跨端查看与控制原型。",
@@ -15,7 +15,7 @@
     ".env.example"
   ],
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"