@xyagent/cli 0.0.1 → 1.0.0

package/bin/agentlink

@@ -30,6 +30,7 @@ import {
   formatHostForUrl,
   generatePairCode,
   generateRelayGatewayId,
+  generateScanPairCode,
   isTransientNetworkError,
   normalizeBaseUrl,
   normalizeChatTransportMode,
@@ -62,6 +63,9 @@ import { scanWorkspacesByRuntime } from "../src-ext/core/scanWorkspaces.mjs";
 import { createWorkspace } from "../src-ext/core/createWorkspace.mjs";
 import { normalizeHostName } from "../src-ext/core/pairCodeClient.mjs";
 import { buildPairSessionResults } from "../src-ext/core/pairInventory.mjs";
+import { SCAN_QR_PNG_OUTPUT_PATH, clearQRImage } from "../src-ext/core/scanPairFlow.mjs";
+import { renderQrToTerminal } from "../src-ext/core/scanQrRenderer.mjs";
+import { buildScanDeeplink, renderScanQrPng } from "../src-ext/core/scanDeeplink.mjs";
 
 // Minimum Node.js 22+ — required for the built-in WebSocket client and the
 // runtime surface we rely on for bridge/service behavior across platforms.
@@ -102,6 +106,12 @@ const SERVICE_UNIT_NAME = "agentlink-bridge.service";
 const SERVICE_TASK_NAME = "Agentlink Bridge";
 const RUNTIME_KIND_OPENCLAW = "openclaw";
 const RUNTIME_KIND_HERMES = "hermes";
+// scan-capable runtimes (unify-scan-pairing): openclaw/hermes read their gateway
+// credentials locally (~/.agentlink/config.json via ensureRelayBridgeCredentials)
+// and can host-claim immediately. claude/codex credentials are issued by the
+// server at consume-time — no host-claim path exists for them this cycle (see
+// spec "术语" + Non-goals; S2b covers the explicit unsupported-runtime notice).
+const SCAN_CAPABLE_RUNTIME_KINDS = Object.freeze([RUNTIME_KIND_OPENCLAW, RUNTIME_KIND_HERMES]);
 
 function serviceNames(runtimeKind) {
   const kind = normalizeRuntimeKind(runtimeKind, RUNTIME_KIND_OPENCLAW);
@@ -774,6 +784,7 @@ function printHelp() {
       `  ${CLI_COMMAND_NAME} pair <4-digit|6-digit|8-alnum> [-r|--runtime <openclaw|hermes|claude|codex|all>] [--mode <relay>] [--strict-plugin]  # default: all`,
       `  ${CLI_COMMAND_NAME} reset [-r|--runtime <openclaw|hermes|claude|codex|all>] [--relay <url>] [--gateway <url>] [--json]  # default: all`,
       `  ${CLI_COMMAND_NAME} bridge [--relay <url>] [--gateway <url>] [-r|--runtime <openclaw|hermes|claude|codex>] [--json]`,
+      `  ${CLI_COMMAND_NAME} scan [-r|--runtime <openclaw|hermes>] [--relay <url>] [--json] [--no-serve] [--qr-path <path>] [--strict-plugin]  # 扫码配对：出二维码 → App 扫码 → 本机 scan-capable runtime(openclaw/hermes)收发；claude/codex 不支持，请改用 pair`,
       `  ${CLI_COMMAND_NAME} service <status|install|stop|uninstall|restart> [--relay <url>] [--gateway <url>] [--runtime <openclaw|hermes>] [--json]`,
       `  ${CLI_COMMAND_NAME} reload [-r|--runtime <openclaw|hermes|claude|codex>] [--json]`,
       `  ${CLI_COMMAND_NAME} pair-url [<4-digit|6-digit|8-alnum>] [--account <id>] [--code <4-digit|6-digit|8-alnum>] [--json]`,
@@ -838,6 +849,13 @@ function parseArgs(argv) {
     doctorAction: undefined,
     mcpSubcommand: undefined,
     mcpRuntime: undefined,
+    noServe: false,
+    qrPath: undefined,
+    // Internal plumbing flag — not advertised in --help. Set by `runScan`'s
+    // per-runtime host-claim child spawn (`--pair-mode scan`), never expected
+    // from a human-typed `agentlink pair` invocation. See runPair()'s
+    // pairMode branch (unify-scan-pairing).
+    pairMode: "",
   };
 
   while (args.length > 0) {
@@ -893,6 +911,31 @@ function parseArgs(argv) {
       options.fix = true;
       continue;
     }
+    if (token === "--no-serve") {
+      // `agentlink scan` 专属：只配对不起 worker（spec S5）。与已有的
+      // --no-serve-relay（options.serveRelay，pair 命令的"配完对不装后台服务"
+      // 语义）刻意分开——scan 这里是"不启动前台 bridge worker"，不是装/不装
+      // service，两者不通用。
+      options.noServe = true;
+      continue;
+    }
+    if (token === "--qr-path") {
+      const value = args.shift();
+      if (!value || value.startsWith("--")) fail(t("err_missing_value", { flag: "--qr-path" }));
+      options.qrPath = value.trim();
+      continue;
+    }
+    if (token === "--pair-mode") {
+      // Internal — see options.pairMode default comment above.
+      const value = args.shift();
+      if (!value || value.startsWith("--")) fail(t("err_missing_value", { flag: "--pair-mode" }));
+      const normalized = value.trim().toLowerCase();
+      if (normalized !== "" && normalized !== "scan") {
+        fail(`--pair-mode must be "scan" (got ${value})`);
+      }
+      options.pairMode = normalized;
+      continue;
+    }
 
     if (token === "--relay") {
       const value = args.shift();
@@ -4199,6 +4242,14 @@ async function publishPairToRelay({
   relayClientToken,
   relayGatewayToken,
   accountId,
+  // unify-scan-pairing: "" (default, pair code path) | "scan". Threaded into
+  // the request body so the server can allow an empty clientUserId for the
+  // scan host-claim branch (spec "服务端支持 scan 模式的 pending 归属").
+  // Never persisted server-side — request-only semantics (spec L81).
+  pairMode = "",
+  // scan pending rows SHALL expire within 5 minutes (spec 安全信封 §2); the
+  // pair-code path keeps its existing 600s default.
+  ttlSeconds = 600,
 }) {
   const url = `${relayUrl}/v1/pair-sessions`;
   const headers = {
@@ -4220,9 +4271,10 @@ async function publishPairToRelay({
       ...(relayClientToken ? { relayClientToken } : {}),
       ...(relayGatewayToken ? { relayGatewayToken } : {}),
       accountId,
-      ttlSeconds: 600,
+      ttlSeconds,
       source: "agentlink-cli",
       hostName: normalizeHostName(os.hostname()),
+      ...(pairMode ? { pairMode } : {}),
     }),
   });
   const text = await response.text();
@@ -5645,10 +5697,14 @@ async function handleUnifiedRunDispatch({
   // 每轮都是全新 session → 上下文断裂（实测 "go on" 不知道前文是什么）。
   // 用 thread_id 后，同一 agentlink thread 内的所有 turn 落到 openclaw 的
   // 同一个 session bucket，上下文自然续接。
+  // unify-scan-pairing 全量移除了上一代扫码硬件的命名空间归一 hack:扫码路径
+  // 现在与 pair code 共用同一套真实 runtime binding(openclaw/hermes),不再有
+  // App 以合成命名空间 agent 绑定的场景,agentId 直接原样使用。
+  const agentId = String(inner.agent_id || request.agentId || "main").trim() || "main";
   const headers = {
     "content-type": "application/json",
     "accept": "text/event-stream",
-    "x-openclaw-agent-id": inner.agent_id || request.agentId || "main",
+    "x-openclaw-agent-id": agentId,
     "x-openclaw-session-key": thread_id,
     "x-openclaw-scopes": DEFAULT_GATEWAY_SCOPES,
   };
@@ -5664,7 +5720,7 @@ async function handleUnifiedRunDispatch({
   // (which lives in agents.defaults.model.primary). The accepted forms are
   // `openclaw` (default agent) or `openclaw/<agentId>`. The agentId comes from
   // the dispatch payload's agent_id (or "main" if absent).
-  const agentId = inner.agent_id || request.agentId || "main";
+  // (agentId 已在上方解析,缺省回退 "main"。)
   if (!jsonMode) {
     const blockSummary = blocks.map((b) => {
       const kind = b?.source?.kind ? `/${b.source.kind}` : "";
@@ -6531,6 +6587,176 @@ function detectInstalledRuntimes({ probeVersion = true } = {}) {
   return results;
 }
 
+// ─── per-runtime local pair-state helpers ───────────────────────────────────
+// 抽出自 runPairAll（原为其内部闭包）：unify-scan-pairing 的 runScan 复用同一套
+// "本机已有凭证 + 服务端 binding 是否还活着" 判定逻辑（spec S3），避免两套配对
+// 代码漂移。纯函数/无 runPairAll 局部状态捕获，提到顶层不改变行为。
+
+// openclaw + hermes 的 pair state 都存在 ~/.agentlink/config.json：
+//   openclaw → relayGatewayId/relayGatewayToken
+//   hermes  → hermesRelayGatewayId/hermesRelayGatewayToken
+// claude/codex 存在 ~/.agentlink/ext-<runtime>-last.json。
+//
+// 返回 { gw_id, token, relay_url } 或 null。
+function readLocalPairState(kind) {
+  try {
+    const home = process.env.HOME || "";
+    if (!home) return null;
+    if (kind === "claude" || kind === "codex") {
+      const p = `${home}/.agentlink/ext-${kind}-last.json`;
+      if (!fs.existsSync(p)) return null;
+      const j = JSON.parse(fs.readFileSync(p, "utf8"));
+      const gw = j?.gw_id || "";
+      const tok = j?.bridge_token || "";
+      if (!gw || !tok) return null;
+      return { gw_id: gw, token: tok, relay_url: j?.relay_url || "" };
+    }
+    if (kind === "openclaw" || kind === "hermes") {
+      const p = `${home}/.agentlink/config.json`;
+      if (!fs.existsSync(p)) return null;
+      let j;
+      try { j = JSON.parse(fs.readFileSync(p, "utf8")); }
+      catch { return null; }
+      const idKey = kind === "openclaw" ? "relayGatewayId" : "hermesRelayGatewayId";
+      const tokKey = kind === "openclaw" ? "relayGatewayToken" : "hermesRelayGatewayToken";
+      const gw = j?.[idKey] || "";
+      const tok = j?.[tokKey] || "";
+      if (!gw) return null;
+      return { gw_id: gw, token: tok, relay_url: j?.relayUrl || "" };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// 删本机 state 文件（App 删除后 server 没了，CLI 需要清干净本机才能 re-pair）。
+function clearLocalPairState(kind) {
+  try {
+    const home = process.env.HOME || "";
+    if (!home) return;
+    if (kind === "claude" || kind === "codex") {
+      const p = `${home}/.agentlink/ext-${kind}-last.json`;
+      if (fs.existsSync(p)) {
+        try { fs.unlinkSync(p); } catch {}
+      }
+      return;
+    }
+    if (kind === "openclaw" || kind === "hermes") {
+      const p = `${home}/.agentlink/config.json`;
+      if (!fs.existsSync(p)) return;
+      let j;
+      try { j = JSON.parse(fs.readFileSync(p, "utf8")); } catch { return; }
+      const idKey = kind === "openclaw" ? "relayGatewayId" : "hermesRelayGatewayId";
+      const tokKey = kind === "openclaw" ? "relayGatewayToken" : "hermesRelayGatewayToken";
+      const clientTokKey = kind === "openclaw" ? "relayClientToken" : "hermesRelayClientToken";
+      delete j[idKey];
+      delete j[tokKey];
+      delete j[clientTokKey];
+      try { fs.writeFileSync(p, JSON.stringify(j, null, 2)); } catch {}
+    }
+  } catch {}
+}
+
+// 服务端探"绑定状态"：GET /v1/gateways/<gw>/binding 返回当前 active
+// (consumed=1) 的 app-user 绑定。
+//   - 404/401/410          → 服务端 pair_session 已不存在/无权 → 视为已删
+//   - 200 且 binding=null   → 网关 session 还在但没有 active 绑定（典型：App
+//                             删除了智能体把 pair_session 软删；或网关重连
+//                             host-claim 复活出一条 consumed=0 的行）→ 视为已删
+//   - 200 且 binding!=null  → 仍有 active 绑定 → 还在
+//   - 5xx / 超时            → 网络/服务端问题，保守按"还在"处理，不误删本机 state
+//
+// 不要用 /meta 探活：那只校验网关 bridge_token / 进程是否存活，网关还在跑就返
+// 200，**不反映 app-user 绑定是否已被删**。openclaw/hermes 网关常驻，App 删除
+// 智能体后 /meta 仍 200 → 误判"已配对"、跳过重配对（这正是删 openclaw 后再添加
+// 显示"已配对"的根因）。
+//
+// 也不要比对 binding.code 跟用户传的 code —— pair code 每次扫码新生成，用户拿
+// 新 code 重跑 pair 时 binding 里仍是旧 code，对不上是常态；只判断 binding 是否
+// 存在即可，避免把"换码重配对"误判成需要 re-pair。
+async function probeRelayBinding(state) {
+  if (!state || !state.gw_id) {
+    return { alive: true, reason: "no_probe_url" };
+  }
+  // 老 state 缺 relay_url（典型 openclaw 老格式）→ 回退 env / 内置默认 relay
+  // 再探，而不是直接按"已配对"跳过：那条逃逸正是 P0#18 ReOpen 的残留路径——
+  // App 删除智能体后用户重新 pair，老 state 机器永远卡在「已配对，跳过」。
+  let relayUrl = String(state.relay_url || "").trim();
+  if (!relayUrl) {
+    relayUrl =
+      String(process.env.OPENIM_RELAY_URL || "").trim() ||
+      String(process.env.AGENTLINK_RELAY_URL || "").trim() ||
+      DEFAULT_RELAY_URL;
+  }
+  if (!state.token) {
+    // 没有网关凭证 → 探不了也证明不了 binding 存活。用户此刻正在主动
+    // `pair <code>`，重配对幂等且是用户意图；按 stale 走清理+重配对，
+    // 比误判「已配对」把用户卡死安全。
+    return { alive: false, reason: "no_gateway_token" };
+  }
+  const base = relayUrl.replace(/\/$/, "");
+  const url = `${base}/v1/gateways/${encodeURIComponent(state.gw_id)}/binding`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 3000);
+  try {
+    const resp = await fetch(url, {
+      method: "GET",
+      signal: controller.signal,
+      headers: {
+        "Authorization": `Bearer ${state.token}`,
+      },
+    });
+    clearTimeout(timer);
+    // 401 (token 无效) / 404 (gateway session 不存在) / 410 → server 端已删
+    if (resp.status === 401 || resp.status === 404 || resp.status === 410) {
+      return { alive: false, reason: `http_${resp.status}` };
+    }
+    if (resp.ok) {
+      let body = null;
+      try {
+        body = await resp.json();
+      } catch {
+        // 解析失败时保守按"还在"处理，不误删
+        return { alive: true, reason: "binding_parse_failed_assume_alive" };
+      }
+      const binding =
+        body && typeof body === "object" ? body.binding : undefined;
+      // binding 为 null/缺失 → 没有 active 绑定 → 视为已删
+      if (binding == null) {
+        return { alive: false, reason: "binding_null" };
+      }
+      return { alive: true, reason: `http_${resp.status}` };
+    }
+    // 500/503 等服务端错误 → 保守不删
+    return { alive: true, reason: `http_${resp.status}_assume_alive` };
+  } catch (err) {
+    clearTimeout(timer);
+    // 网络超时 / DNS 失败 → 保守不删
+    return { alive: true, reason: `network_err_assume_alive` };
+  }
+}
+
+// 对应 runtime 的"重置后重新配对"命令提示。
+function resetHintFor(kind, code) {
+  if (kind === "claude" || kind === "codex") {
+    return `agentlink uninstall -r ${kind} && agentlink pair ${code} -r ${kind}`;
+  }
+  // openclaw / hermes 走 reset 子命令
+  return `agentlink reset -r ${kind} && agentlink pair ${code} -r ${kind}`;
+}
+
+// 每 runtime 一次 host-claim 子进程 spawn（unify-scan-pairing 抽出，供
+// runPairAll 与 runScan 共用，"出码方式"通过 extraArgv 注入 —— pair code
+// 路径转发原始 argv 不变；scan 路径注入 `pair <code> --pair-mode scan
+// --no-serve-relay ...`，见 runScan()）。隔离 fail()/process.exit：单个
+// runtime 失败不影响其余 runtime（每个都是独立子进程）。
+function spawnPairChildForRuntime({ argvTail, runtimeKind, env }) {
+  const argv = [CLI_ENTRY, ...argvTail, "--runtime", runtimeKind];
+  const child = spawnSync(process.execPath, argv, { stdio: "inherit", env });
+  return { kind: runtimeKind, ok: child.status === 0, status: child.status ?? null };
+}
+
 // `agentlink pair <code>` 默认批量配对所有已安装 runtime。
 // 也兼容 `agentlink pair <code> --runtime all` 显式写法。
 // 检测本机安装的 4 种 runtime（openclaw / hermes / claude / codex），
@@ -6642,159 +6868,8 @@ async function runPairAll(options) {
     AGENTLINK_AGENT_LOG_LEVEL: process.env.AGENTLINK_AGENT_LOG_LEVEL || "warn",
   };
 
-  // openclaw + hermes 的 pair state 都存在 ~/.agentlink/config.json：
-  //   openclaw → relayGatewayId/relayGatewayToken
-  //   hermes  → hermesRelayGatewayId/hermesRelayGatewayToken
-  // claude/codex 存在 ~/.agentlink/ext-<runtime>-last.json。
-  //
-  // 返回 { gw_id, token, relay_url } 或 null。
-  function readLocalPairState(kind) {
-    try {
-      const home = process.env.HOME || "";
-      if (!home) return null;
-      if (kind === "claude" || kind === "codex") {
-        const p = `${home}/.agentlink/ext-${kind}-last.json`;
-        if (!fs.existsSync(p)) return null;
-        const j = JSON.parse(fs.readFileSync(p, "utf8"));
-        const gw = j?.gw_id || "";
-        const tok = j?.bridge_token || "";
-        if (!gw || !tok) return null;
-        return { gw_id: gw, token: tok, relay_url: j?.relay_url || "" };
-      }
-      if (kind === "openclaw" || kind === "hermes") {
-        const p = `${home}/.agentlink/config.json`;
-        if (!fs.existsSync(p)) return null;
-        let j;
-        try { j = JSON.parse(fs.readFileSync(p, "utf8")); }
-        catch { return null; }
-        const idKey = kind === "openclaw" ? "relayGatewayId" : "hermesRelayGatewayId";
-        const tokKey = kind === "openclaw" ? "relayGatewayToken" : "hermesRelayGatewayToken";
-        const gw = j?.[idKey] || "";
-        const tok = j?.[tokKey] || "";
-        if (!gw) return null;
-        return { gw_id: gw, token: tok, relay_url: j?.relayUrl || "" };
-      }
-      return null;
-    } catch {
-      return null;
-    }
-  }
-
-  // 删本机 state 文件（App 删除后 server 没了，CLI 需要清干净本机才能 re-pair）。
-  function clearLocalPairState(kind) {
-    try {
-      const home = process.env.HOME || "";
-      if (!home) return;
-      if (kind === "claude" || kind === "codex") {
-        const p = `${home}/.agentlink/ext-${kind}-last.json`;
-        if (fs.existsSync(p)) {
-          try { fs.unlinkSync(p); } catch {}
-        }
-        return;
-      }
-      if (kind === "openclaw" || kind === "hermes") {
-        const p = `${home}/.agentlink/config.json`;
-        if (!fs.existsSync(p)) return;
-        let j;
-        try { j = JSON.parse(fs.readFileSync(p, "utf8")); } catch { return; }
-        const idKey = kind === "openclaw" ? "relayGatewayId" : "hermesRelayGatewayId";
-        const tokKey = kind === "openclaw" ? "relayGatewayToken" : "hermesRelayGatewayToken";
-        const clientTokKey = kind === "openclaw" ? "relayClientToken" : "hermesRelayClientToken";
-        delete j[idKey];
-        delete j[tokKey];
-        delete j[clientTokKey];
-        try { fs.writeFileSync(p, JSON.stringify(j, null, 2)); } catch {}
-      }
-    } catch {}
-  }
-
-  // 服务端探"绑定状态"：GET /v1/gateways/<gw>/binding 返回当前 active
-  // (consumed=1) 的 app-user 绑定。
-  //   - 404/401/410          → 服务端 pair_session 已不存在/无权 → 视为已删
-  //   - 200 且 binding=null   → 网关 session 还在但没有 active 绑定（典型：App
-  //                             删除了智能体把 pair_session 软删；或网关重连
-  //                             host-claim 复活出一条 consumed=0 的行）→ 视为已删
-  //   - 200 且 binding!=null  → 仍有 active 绑定 → 还在
-  //   - 5xx / 超时            → 网络/服务端问题，保守按"还在"处理，不误删本机 state
-  //
-  // 不要用 /meta 探活：那只校验网关 bridge_token / 进程是否存活，网关还在跑就返
-  // 200，**不反映 app-user 绑定是否已被删**。openclaw/hermes 网关常驻，App 删除
-  // 智能体后 /meta 仍 200 → 误判"已配对"、跳过重配对（这正是删 openclaw 后再添加
-  // 显示"已配对"的根因）。
-  //
-  // 也不要比对 binding.code 跟用户传的 code —— pair code 每次扫码新生成，用户拿
-  // 新 code 重跑 pair 时 binding 里仍是旧 code，对不上是常态；只判断 binding 是否
-  // 存在即可，避免把"换码重配对"误判成需要 re-pair。
-  async function probeRelayBinding(state) {
-    if (!state || !state.gw_id) {
-      return { alive: true, reason: "no_probe_url" };
-    }
-    // 老 state 缺 relay_url（典型 openclaw 老格式）→ 回退 env / 内置默认 relay
-    // 再探，而不是直接按"已配对"跳过：那条逃逸正是 P0#18 ReOpen 的残留路径——
-    // App 删除智能体后用户重新 pair，老 state 机器永远卡在「已配对，跳过」。
-    let relayUrl = String(state.relay_url || "").trim();
-    if (!relayUrl) {
-      relayUrl =
-        String(process.env.OPENIM_RELAY_URL || "").trim() ||
-        String(process.env.AGENTLINK_RELAY_URL || "").trim() ||
-        DEFAULT_RELAY_URL;
-    }
-    if (!state.token) {
-      // 没有网关凭证 → 探不了也证明不了 binding 存活。用户此刻正在主动
-      // `pair <code>`，重配对幂等且是用户意图；按 stale 走清理+重配对，
-      // 比误判「已配对」把用户卡死安全。
-      return { alive: false, reason: "no_gateway_token" };
-    }
-    const base = relayUrl.replace(/\/$/, "");
-    const url = `${base}/v1/gateways/${encodeURIComponent(state.gw_id)}/binding`;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 3000);
-    try {
-      const resp = await fetch(url, {
-        method: "GET",
-        signal: controller.signal,
-        headers: {
-          "Authorization": `Bearer ${state.token}`,
-        },
-      });
-      clearTimeout(timer);
-      // 401 (token 无效) / 404 (gateway session 不存在) / 410 → server 端已删
-      if (resp.status === 401 || resp.status === 404 || resp.status === 410) {
-        return { alive: false, reason: `http_${resp.status}` };
-      }
-      if (resp.ok) {
-        let body = null;
-        try {
-          body = await resp.json();
-        } catch {
-          // 解析失败时保守按"还在"处理，不误删
-          return { alive: true, reason: "binding_parse_failed_assume_alive" };
-        }
-        const binding =
-          body && typeof body === "object" ? body.binding : undefined;
-        // binding 为 null/缺失 → 没有 active 绑定 → 视为已删
-        if (binding == null) {
-          return { alive: false, reason: "binding_null" };
-        }
-        return { alive: true, reason: `http_${resp.status}` };
-      }
-      // 500/503 等服务端错误 → 保守不删
-      return { alive: true, reason: `http_${resp.status}_assume_alive` };
-    } catch (err) {
-      clearTimeout(timer);
-      // 网络超时 / DNS 失败 → 保守不删
-      return { alive: true, reason: `network_err_assume_alive` };
-    }
-  }
-
-  // 对应 runtime 的"重置后重新配对"命令提示。
-  function resetHintFor(kind, code) {
-    if (kind === "claude" || kind === "codex") {
-      return `agentlink uninstall -r ${kind} && agentlink pair ${code} -r ${kind}`;
-    }
-    // openclaw / hermes 走 reset 子命令
-    return `agentlink reset -r ${kind} && agentlink pair ${code} -r ${kind}`;
-  }
+  // readLocalPairState / clearLocalPairState / probeRelayBinding / resetHintFor
+  // 已提到顶层（供 runScan 复用，见其上方注释），行为不变。
 
   const summary = [];
   for (const kind of installedKinds) {
@@ -6825,12 +6900,10 @@ async function runPairAll(options) {
       clearLocalPairState(kind);
     }
     console.log(t("pair_all_pairing_runtime", { kind }));
-    const argv = [CLI_ENTRY, ...forwardedArgv, "--runtime", kind];
-    const child = spawnSync(process.execPath, argv, { stdio: "inherit", env: quietEnv });
-    const ok = child.status === 0;
-    summary.push({ kind, ok, status: child.status ?? null });
+    const { ok, status } = spawnPairChildForRuntime({ argvTail: forwardedArgv, runtimeKind: kind, env: quietEnv });
+    summary.push({ kind, ok, status });
     if (!ok) {
-      console.warn(t("pair_all_runtime_pair_failed", { kind, status: child.status ?? "?" }));
+      console.warn(t("pair_all_runtime_pair_failed", { kind, status: status ?? "?" }));
     }
   }
 
@@ -7040,7 +7113,12 @@ async function runPair({
   runtime,
   strictPlugin,
   allowRebind,
+  // unify-scan-pairing: "" (default, pair code manual-entry path) | "scan".
+  // Set internally by runScan's per-runtime host-claim child spawn
+  // (`--pair-mode scan`) — never by a human-typed `agentlink pair` call.
+  pairMode = "",
 }) {
+  const isScanMode = pairMode === "scan";
   if (!explicitCode || !String(explicitCode).trim()) {
     fail(t("pair_usage_missing"));
   }
@@ -7067,11 +7145,24 @@ async function runPair({
     );
   }
 
-  const currentSession = await readPairSessionFromRelay({
-    relayUrl,
-    code,
-    runtimeKind: requestedRuntime,
-  });
+  // scan 模式 SHALL 不做 host-ready 预检(spec P1-4):code 由 CLI 本地生成、
+  // 无 App 预建行,readPairSessionFromRelay 的 GET 预检会因"行不存在"误挡。
+  // 直接以合成的空会话继续,走下面统一的 publishPairToRelay(pairMode=scan)
+  // Upsert 建 pending 行。
+  const currentSession = isScanMode
+    ? {
+        accountId: "",
+        runtimeKind: requestedRuntime,
+        transportMode: "relay",
+        clientUserID: "",
+        bindUrl: "",
+        consumed: false,
+      }
+    : await readPairSessionFromRelay({
+        relayUrl,
+        code,
+        runtimeKind: requestedRuntime,
+      });
   if (!currentSession) {
     fail(
       [
@@ -7092,15 +7183,18 @@ async function runPair({
   const runtimeKind = requestedRuntime;
   // 复合主键升级后,GET 已经按 runtimeKind 精确取了对应的行,server 不会
   // 再返回其他 runtime 的数据,这里 mismatch 不可能发生 —— 保留旧检查仅作冗余防护。
-  if (runtime && runtimeKind !== sessionRuntimeKind) {
+  // scan 模式没有真实 GET 结果(currentSession 是本函数合成的),该检查天然满足,跳过即可。
+  if (!isScanMode && runtime && runtimeKind !== sessionRuntimeKind) {
     fail(t("pair_runtime_mismatch", { app: sessionRuntimeKind, cli: runtimeKind }));
   }
   const transportMode = normalizeChatTransportMode(
     mode,
     normalizeChatTransportMode(currentSession.transportMode, "relay"),
   );
+  // scan 模式:clientUserId 由 App scan-claim 时从 Bearer 派生,host-claim 阶段
+  // 天生为空(spec「服务端支持 scan 模式的 pending 归属」)——不是错误,不 fail()。
   const clientUserId = String(currentSession.clientUserID ?? "").trim().toLowerCase();
-  if (!clientUserId) {
+  if (!isScanMode && !clientUserId) {
     fail(
       [
         t("pair_missing_client_user_id"),
@@ -7176,8 +7270,13 @@ async function runPair({
     process.env.OPENCLAW_CUSTOM_IM_PUBLIC_BASE_URL?.trim() ||
     "";
 
+  // scan 模式:gateway.port 可能尚未配置(真机上通常已配置,但 host-claim 本身
+  // 不依赖它——scan 是 CLI-bridge 模型,relay-worker 轮询,不像 pair code 那条
+  // legacy 直连 webhook 路径需要一个外部可达的 bindUrl)。optional:true 让
+  // resolveGatewayBaseUrl 缺配置时返回 null 而不是 fail()/exit;pair code 路径
+  // (isScanMode=false)行为完全不变。
   const localGatewayBaseUrl = runtimeNeedsOpenClaw(runtimeKind)
-    ? resolveGatewayBaseUrl({ gateway }, config)
+    ? resolveGatewayBaseUrl({ gateway, optional: isScanMode }, config)
     : normalizeBaseUrl(gateway) || "";
   const gatewayAuthToken = runtimeNeedsOpenClaw(runtimeKind)
     ? resolveGatewayAuthToken(config)
@@ -7196,8 +7295,8 @@ async function runPair({
     accountId,
     code,
   });
-  const relayBindUrl = currentSession.bindUrl || publicBindUrl || localBindUrl;
-  if (!relayBindUrl) {
+  const relayBindUrl = currentSession.bindUrl || publicBindUrl || localBindUrl || (isScanMode ? "" : null);
+  if (!isScanMode && !relayBindUrl) {
     fail(t("pairurl_bind_url_unknown"));
   }
 
@@ -7291,16 +7390,24 @@ async function runPair({
         c.startsWith("gateway.http.endpoints.responses.enabled") ||
         c.startsWith("gateway.auth."),
     );
-  if (runtimeNeedsOpenClaw(runtimeKind) && prepared.changed) {
+  // scan 模式跳过重启宽限等待:出码循环追求"CLI 秒起二维码",这段睡眠/探测只是
+  // "让日志更友好"的诊断性等待(gatewayProbe.ok=false 只 warn,从不 fail() ——
+  // 不影响 publishPairToRelay 是否成功),对 pair code 手输路径行为不变
+  // (isScanMode 为 false 时,下面两处判断与改动前完全一致)。
+  if (runtimeNeedsOpenClaw(runtimeKind) && prepared.changed && !isScanMode) {
     await new Promise((resolve) => setTimeout(resolve, 2000));
   }
 
-  if (runtimeNeedsOpenClaw(runtimeKind)) {
+  // scan 模式且 gateway.port 未配置(localGatewayBaseUrl=null,见上方 optional:true)
+  // 时完全跳过探测——没有 URL 可探,buildGatewayResponsesUrlOrFail 遇 null 会
+  // fail()/exit,而这段探测本就只是诊断性的(见上方注释),跳过不影响正确性。
+  if (runtimeNeedsOpenClaw(runtimeKind) && (!isScanMode || localGatewayBaseUrl)) {
     // 90s covers the observed ~35s restart with ample margin; ~7s handles the
-    // steady-state case where openclaw is already serving.
-    const PROBE_ATTEMPTS = criticalChange ? 90 : prepared.changed ? 15 : 6;
+    // steady-state case where openclaw is already serving. scan 模式只探测
+    // 1 次、不重试(见上方注释)。
+    const PROBE_ATTEMPTS = isScanMode ? 1 : criticalChange ? 90 : prepared.changed ? 15 : 6;
     const PROBE_INTERVAL_MS = 1000;
-    const announcedStart = criticalChange;
+    const announcedStart = !isScanMode && criticalChange;
     if (announcedStart) {
       console.log(t("gateway_wait_restart"));
     }
@@ -7353,6 +7460,7 @@ async function runPair({
     relayClientToken: relayCredentials?.clientToken,
     relayGatewayToken: relayCredentials?.gatewayToken,
     accountId,
+    ...(isScanMode ? { pairMode: "scan", ttlSeconds: 300 } : {}),
   });
 
   const output = {
@@ -7960,6 +8068,270 @@ function runPairUrl({ json, account, code: explicitCode }) {
   console.log(resolvedBindUrl);
 }
 
+// `agentlink scan`：统一扫码配对（unify-scan-pairing，取代 add-openclaw-scan-pairing
+// 的上一代扫码硬件方案）——CLI 本地出一个高熵 code → 对每个 scan-capable
+// runtime（openclaw/hermes）host-claim → 渲染中性 deeplink 二维码 → 等 App
+// scan-claim → 起 worker。配对后效果与 pair code 路径完全一致（同一
+// `pair_sessions` 底座，同一 App 侧工作区选择流程），只有出码方式不同。
+//
+// `scan --json` 跨多阶段持续输出（探测 → 等待扫码 → 配对成功 → 起 worker），
+// 采用 NDJSON：每阶段一行紧凑 JSON object（见 printScanEvent）。
+function printScanEvent(fields) {
+  console.log(JSON.stringify({ command: "scan", ...fields }));
+}
+
+// claude/codex 在 scan 模式下没有 host-claim 路径（gateway 凭证由服务端在
+// consume 时才下发，host-claim 阶段无来源——spec 术语 + Non-goals，本期不做
+// pending 预分配子系统）。检测到时打印明确提示，不静默、不失败（S2b）。
+function scanUnsupportedRuntimeMessage(kinds) {
+  return `⚠️  ${kinds.join("/")} 暂不支持扫码配对（scan-capable runtime 仅 openclaw/hermes）。请改用 \`${CLI_COMMAND_NAME} pair <code> -r ${kinds[0]}\` 手动配对。`;
+}
+
+// env 覆盖仅供测试加速 S4(过期重出码)场景用——与既有
+// AGENTLINK_SCAN_QR_PNG_PATH 同一约定(见 scanPairFlow.mjs)。生产默认值:
+// 2s 轮询间隔、300s TTL(与 host-claim 请求的 ttlSeconds 对齐,安全信封 §2)。
+const SCAN_CLAIM_POLL_INTERVAL_MS = parseNonNegativeInt(process.env.AGENTLINK_SCAN_CLAIM_POLL_INTERVAL_MS) || 2000;
+// 轮询超过这个窗口还没等到 scan-claim,视为码已过期,重新出码(S4)，而不是无限等下去。
+const SCAN_CLAIM_TTL_MS = (parseNonNegativeInt(process.env.AGENTLINK_SCAN_CLAIM_TTL_SEC) || 300) * 1000;
+
+// 轮询等待 App scan-claim 完成。复用既有 readPairSessionFromRelay(GET
+// /v1/pair-sessions/:code)——scan-claim 会把该 code 下全部 pending 行标记
+// consumed=1(spec「新增端点」),任取其中一个已 host-claim 的 runtimeKind
+// 查询即可代表整组的归属状态,不需要新端点。
+async function waitForScanClaim({ relayUrl, code, representativeRuntimeKind, ttlMs, sleepImpl }) {
+  const sleep = sleepImpl || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const deadline = Date.now() + ttlMs;
+  for (;;) {
+    const session = await readPairSessionFromRelay({
+      relayUrl,
+      code,
+      runtimeKind: representativeRuntimeKind,
+    });
+    if (session && session.consumed) {
+      return true;
+    }
+    if (Date.now() >= deadline) {
+      return false;
+    }
+    await sleep(SCAN_CLAIM_POLL_INTERVAL_MS);
+  }
+}
+
+// 起本地已装 scan-capable runtime 的 worker：单 runtime 用既有前台 runBridge
+// （与 revoke 时既有 selfUninstallOnRevoke 退出路径完全一致，S6）；多 runtime
+// 复用 runPair `--serve-relay` 分支已经在用的后台服务安装机制（安装成功后各自
+// 独立常驻，不受本进程退出影响）。S1 的多 runtime 场景是 manual-device 验收
+// 载体（spec 执行载体声明），这里不额外发明新机制，只编排既有函数。
+async function startScanWorkers({ kinds, relayUrl, gateway, json }) {
+  if (kinds.length === 1) {
+    await runBridge({ json, relay: relayUrl, noRelay: false, gateway, runtime: kinds[0] });
+    return;
+  }
+  for (const kind of kinds) {
+    const gatewayBaseUrl = runtimeNeedsOpenClaw(kind)
+      ? resolveGatewayBaseUrl({ gateway, optional: true }, ensureObject(readOptionalJsonFile(resolveOpenClawConfigPath()))) || ""
+      : relayUrl; // hermes 占位:installBridgeService 契约要求非空,hermes 分支不读它。
+    try {
+      const serviceStatus = getBridgeServiceStatus(kind);
+      (serviceStatus.installed ? restartBridgeService : installBridgeService)({
+        relayUrl, gatewayBaseUrl, runtimeKind: kind,
+      });
+      if (!json) console.log(t("service_installed"));
+    } catch (err) {
+      if (!json) console.warn(`⚠️  ${kind} bridge service 安装失败：${err?.message || err}`);
+    }
+  }
+}
+
+async function runScan({ json, relay, noRelay, gateway, qrPath, noServe, strictPlugin, runtime }) {
+  // S2b（显式 -r claude/codex）：不出码、不联系 relay，直接提示 + 非零退出。
+  if (runtime === "claude" || runtime === "codex") {
+    const message = scanUnsupportedRuntimeMessage([runtime]);
+    if (json) {
+      printScanEvent({ phase: "unsupported_runtime", unsupportedRuntimes: [runtime], hint: message });
+    } else {
+      console.error(message);
+    }
+    process.exit(1);
+  }
+
+  const config = ensureObject(readOptionalJsonFile(resolveOpenClawConfigPath()));
+  const section = readChannelSection(config);
+  const relayUrl = resolveRelayUrl({ relay, noRelay }, section);
+  if (!relayUrl) {
+    fail(
+      [
+        t("relay_url_required"),
+        t("relay_url_missing_detail"),
+        t("relay_url_hint"),
+      ].join("\n"),
+    );
+  }
+
+  // ── 探测本机已装 runtime，划出「scan-capable 候选集」（S1/S2）───────────
+  const detected = detectInstalledRuntimes();
+  const installedKinds = new Set(detected.filter((d) => d.installed).map((d) => d.kind));
+  const unsupportedDetected = detected
+    .filter((d) => d.installed && (d.kind === "claude" || d.kind === "codex"))
+    .map((d) => d.kind);
+
+  let candidateKinds;
+  if (runtime) {
+    // -r openclaw|hermes：只配这一个（S2）。校验值域已在 CLI 参数解析阶段完成
+    // （openclaw/hermes/claude/codex/all），claude/codex 已在上面提前返回。
+    if (!installedKinds.has(runtime)) {
+      fail(`${CLI_COMMAND_NAME} scan -r ${runtime}: runtime not installed on this host`);
+    }
+    candidateKinds = [runtime];
+  } else {
+    candidateKinds = SCAN_CAPABLE_RUNTIME_KINDS.filter((k) => installedKinds.has(k));
+  }
+  if (candidateKinds.length === 0) {
+    fail(t("pair_all_no_runtimes"));
+  }
+
+  if (unsupportedDetected.length > 0) {
+    const message = scanUnsupportedRuntimeMessage(unsupportedDetected);
+    if (json) {
+      printScanEvent({ phase: "unsupported_runtime_detected", unsupportedRuntimes: unsupportedDetected, hint: message });
+    } else {
+      console.log(message);
+    }
+  }
+
+  // ── S3：已有有效凭证 + 服务端 binding 仍存活的 runtime 直接跳过出码 ──────
+  const quietEnv = {
+    ...process.env,
+    AGENTLINK_AGENT_LOG_LEVEL: process.env.AGENTLINK_AGENT_LOG_LEVEL || "warn",
+  };
+  const alreadyAliveKinds = [];
+  const needsClaimKinds = [];
+  for (const kind of candidateKinds) {
+    const state = readLocalPairState(kind);
+    if (state) {
+      const probe = await probeRelayBinding(state);
+      if (probe.alive) {
+        alreadyAliveKinds.push(kind);
+        if (kind === RUNTIME_KIND_HERMES) {
+          try {
+            const hLog = _createBubLogger({ comp: "scan" }).child({ rt: "hermes" });
+            await ensureHermesEnvAndProbe(hLog);
+          } catch (err) {
+            console.warn(`⚠️  hermes env/gateway 自检失败：${err?.message || err}`);
+          }
+        }
+        continue;
+      }
+      clearLocalPairState(kind);
+    }
+    needsClaimKinds.push(kind);
+  }
+
+  let claimedKinds = [];
+  if (needsClaimKinds.length === 0) {
+    if (!json) {
+      console.log(`ℹ️  ${alreadyAliveKinds.join("、")} 已有有效凭证，跳过扫码，直接启动 bridge…`);
+    } else {
+      printScanEvent({ phase: "skip_pairing", relayUrl, runtimes: alreadyAliveKinds });
+    }
+  } else {
+    // ── 出码循环（S1 前半段 + S4）：本地生成高熵 code → 对 needsClaimKinds
+    // 逐个 host-claim(子进程,与 pair-all 同一隔离机制)→ 渲染二维码 → 轮询
+    // scan-claim；超时/过期则清二维码、重新出码，进程不退出。
+    const resolvedQrPath = qrPath || SCAN_QR_PNG_OUTPUT_PATH;
+    for (;;) {
+      const code = generateScanPairCode();
+      const argvTail = [
+        "pair", code,
+        "--relay", relayUrl,
+        "--pair-mode", "scan",
+        "--no-serve-relay",
+        ...(json ? ["--json"] : []),
+        ...(strictPlugin ? ["--strict-plugin"] : []),
+      ];
+      const roundResults = needsClaimKinds.map((kind) =>
+        spawnPairChildForRuntime({ argvTail, runtimeKind: kind, env: quietEnv }),
+      );
+      const roundClaimed = roundResults.filter((r) => r.ok).map((r) => r.kind);
+      const roundFailed = roundResults.filter((r) => !r.ok).map((r) => r.kind);
+      if (roundFailed.length > 0 && !json) {
+        console.warn(`⚠️  以下 runtime host-claim 失败，不会出现在本轮二维码中：${roundFailed.join("、")}`);
+      }
+      if (roundClaimed.length === 0) {
+        fail(`agentlink scan: host-claim failed for all candidate runtimes (${needsClaimKinds.join(", ")})`);
+      }
+
+      const deeplink = buildScanDeeplink({ code, relay: relayUrl });
+      const pngResult = await renderScanQrPng({ payload: deeplink, outputPath: resolvedQrPath });
+      if (json) {
+        printScanEvent({
+          phase: "waiting_for_scan",
+          code,
+          deeplink,
+          runtimes: roundClaimed,
+          qr_png_path: pngResult.ok ? pngResult.path : null,
+          qr_png_error: pngResult.ok ? null : pngResult.error,
+        });
+      } else {
+        console.log(`\n扫码配对（${roundClaimed.join("、")}）：用 App 扫描下方二维码` +
+          (pngResult.ok ? `（或打开 ${pngResult.path} 用图片扫码）` : "") + "\n");
+        renderQrToTerminal(deeplink);
+        console.log(`\n扫不到？把这段贴到浏览器/App 输入框也可以：${deeplink}\n`);
+      }
+
+      const claimedInTime = await waitForScanClaim({
+        relayUrl,
+        code,
+        representativeRuntimeKind: roundClaimed[0],
+        ttlMs: SCAN_CLAIM_TTL_MS,
+      });
+      clearQRImage(resolvedQrPath);
+      if (claimedInTime) {
+        claimedKinds = roundClaimed;
+        if (json) {
+          printScanEvent({ phase: "paired", relayUrl, runtimes: claimedKinds });
+        } else {
+          console.log(`✅ 配对成功（${claimedKinds.join("、")}）`);
+        }
+        break;
+      }
+      // 过期/超时（S4）：重新生成 code，重新 host-claim，刷新二维码，不退出。
+      if (!json) {
+        console.log("⏳ 配对码已过期，重新生成二维码…");
+      } else {
+        printScanEvent({ phase: "code_expired_retrying", runtimes: roundClaimed });
+      }
+    }
+  }
+
+  const finalKinds = [...alreadyAliveKinds, ...claimedKinds];
+
+  // ── --no-serve：只配对不起 worker（S5 命令签名之一）─────────────────────
+  if (noServe) {
+    if (json) {
+      printScanEvent({ phase: "done", serve: false, runtimes: finalKinds, relayUrl });
+    } else {
+      console.log("ℹ️  --no-serve：已完成配对，不启动 bridge worker。");
+    }
+    return;
+  }
+
+  // ── 起 worker；revoke 由既有共享路径清凭证 + exit（S6，不逆改）──────────
+  if (json) {
+    printScanEvent({
+      phase: "starting_worker",
+      runtimes: finalKinds,
+      relayUrl,
+      note: `on revoke this process/service clears credentials and exits; re-run \`${CLI_COMMAND_NAME} scan\` to re-pair`,
+    });
+  } else {
+    console.log(
+      `若之后在 App 端解绑（或凭证失效），worker 会自动清凭证并退出 —— 到时重跑 \`${CLI_COMMAND_NAME} scan\` 即可重新配对。`,
+    );
+  }
+  await startScanWorkers({ kinds: finalKinds, relayUrl, gateway, json });
+}
+
 async function runBridge({ json, relay, noRelay, gateway, runtime }) {
   const configPath = resolveOpenClawConfigPath();
   // 先容忍读（缺文件 → null）：runtimeKind 可能来自 ~/.agentlink state 的
@@ -8534,6 +8906,9 @@ async function main() {
     case "bridge":
       await runBridge(options);
       return;
+    case "scan":
+      await runScan(options);
+      return;
     case "service":
       await runService(options);
       return;