@xyagent/cli 0.0.1

package/src-ext/core/openclawGatewayClient.mjs

@@ -0,0 +1,230 @@
+/**
+ * openclawGatewayClient.mjs — 轻量 openclaw gateway WebSocket 客户端
+ *
+ * 用途：bridge 收到 sessions.abort / chat.abort RPC 时，直连本地
+ * openclaw gateway WS 发送 chat.abort 命令真正中断 run。
+ *
+ * 函数设计均支持依赖注入（_readJsonFn / _tokenFn / _portFn / _wsFactory），
+ * 便于单元测试隔离文件系统和网络。
+ *
+ * 限定行数 ≤ 200 行。
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// ── 内部工具 ──────────────────────────────────────────────────────────────────
+
+/**
+ * 读 JSON 文件，失败（文件不存在/JSON 语法错）返回 null，永不抛。
+ * @param {string} filePath
+ * @returns {object|null}
+ */
+function _readJsonFileSafe(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+const DEFAULT_GATEWAY_PORT = 18789;
+
+// ── 公开 API ──────────────────────────────────────────────────────────────────
+
+/**
+ * 从 ~/.openclaw/devices/paired.json 读取持有 operator.write scope 的 operator token。
+ *
+ * @param {{ log?: object, _readJsonFn?: Function }} opts
+ * @returns {Promise<string|null>}
+ */
+export async function readOpenclawOperatorToken({ log, _readJsonFn } = {}) {
+  const readJson = _readJsonFn ?? ((path) => _readJsonFileSafe(path));
+  const pairedPath = join(homedir(), ".openclaw", "devices", "paired.json");
+
+  let paired;
+  try {
+    paired = await readJson(pairedPath);
+  } catch (err) {
+    log?.warn?.("openclawGatewayClient.readToken.err", "paired.json read failed", { err: err?.message });
+    return null;
+  }
+
+  if (!paired) return null;
+
+  // 支持两种 schema：{ devices: [...] } 或直接是 devices 数组
+  const devices = Array.isArray(paired.devices)
+    ? paired.devices
+    : Array.isArray(paired)
+      ? paired
+      : [];
+
+  for (const device of devices) {
+    const scopes = Array.isArray(device?.scopes) ? device.scopes : [];
+    if (!scopes.includes("operator.write")) continue;
+    const token = device?.tokens?.operator?.token;
+    if (token && typeof token === "string") return token;
+  }
+
+  log?.warn?.("openclawGatewayClient.readToken.notFound", "no operator.write device with token in paired.json");
+  return null;
+}
+
+/**
+ * 从 ~/.openclaw/openclaw.json 读取 gateway.port，默认 18789。
+ *
+ * @param {{ log?: object, _readJsonFn?: Function }} opts
+ * @returns {Promise<number>}
+ */
+export async function readOpenclawGatewayPort({ log, _readJsonFn } = {}) {
+  const readJson = _readJsonFn ?? ((path) => _readJsonFileSafe(path));
+  const cfgPath = join(homedir(), ".openclaw", "openclaw.json");
+
+  let cfg;
+  try {
+    cfg = await readJson(cfgPath);
+  } catch (err) {
+    log?.warn?.("openclawGatewayClient.readPort.err", "openclaw.json read failed", { err: err?.message });
+    return DEFAULT_GATEWAY_PORT;
+  }
+
+  const port = cfg?.gateway?.port;
+  return typeof port === "number" && port > 0 ? port : DEFAULT_GATEWAY_PORT;
+}
+
+/**
+ * 通过 openclaw gateway WebSocket 发送 chat.abort。
+ *
+ * 整体超时 5s；失败返回 { ok: false, limited, error }，不抛。
+ *
+ * @param {{
+ *   sessionKey: string,
+ *   log?: object,
+ *   _tokenFn?: () => Promise<string|null>,
+ *   _portFn?: () => Promise<number>,
+ *   _wsFactory?: (url: string) => WebSocket,
+ * }} opts
+ * @returns {Promise<{ ok: true, aborted: number } | { ok: false, limited: string, error: string }>}
+ */
+export async function openclawChatAbort({
+  sessionKey,
+  log,
+  _tokenFn,
+  _portFn,
+  _wsFactory,
+} = {}) {
+  // 读取 token
+  const getToken = _tokenFn ?? (() => readOpenclawOperatorToken({ log }));
+  const getPort = _portFn ?? (() => readOpenclawGatewayPort({ log }));
+
+  const token = await getToken();
+  if (!token) {
+    return { ok: false, limited: "openclaw-no-token", error: "no operator token found in paired.json" };
+  }
+
+  const port = await getPort();
+  const url = `ws://127.0.0.1:${port}`;
+
+  // WS 通信（带超时）
+  return await Promise.race([
+    _performWsAbort({ url, token, sessionKey, log, _wsFactory }),
+    _timeout(5000, "openclaw-gateway-unreachable", "WS operation timed out after 5s"),
+  ]);
+}
+
+// ── 内部实现 ──────────────────────────────────────────────────────────────────
+
+async function _performWsAbort({ url, token, sessionKey, log, _wsFactory }) {
+  let ws;
+  try {
+    ws = _wsFactory ? _wsFactory(url) : new WebSocket(url);
+  } catch (err) {
+    return {
+      ok: false,
+      limited: "openclaw-gateway-unreachable",
+      error: `WS connect failed: ${err?.message || String(err)}`,
+    };
+  }
+
+  return new Promise((resolve) => {
+    let phase = "connecting"; // connecting → hello → abort → done
+
+    function cleanup() {
+      try { ws.close(); } catch {}
+    }
+
+    function fail(limited, error) {
+      cleanup();
+      resolve({ ok: false, limited, error });
+    }
+
+    ws.addEventListener("error", (evt) => {
+      const msg = evt?.message || String(evt?.error || "ws error");
+      if (phase === "connecting" || phase === "hello") {
+        fail("openclaw-gateway-unreachable", `WS error: ${msg}`);
+      } else {
+        fail("openclaw-gateway-unreachable", `WS error during abort: ${msg}`);
+      }
+      phase = "done";
+    });
+
+    ws.addEventListener("open", () => {
+      phase = "hello";
+      // 发送握手 connect
+      ws.send(JSON.stringify({
+        type: "req",
+        id: "1",
+        method: "connect",
+        params: {
+          minProtocol: 4,
+          maxProtocol: 4,
+          token,
+        },
+      }));
+    });
+
+    ws.addEventListener("message", (evt) => {
+      let msg;
+      try {
+        msg = JSON.parse(typeof evt.data === "string" ? evt.data : evt.data.toString());
+      } catch {
+        return; // 忽略不可解析帧
+      }
+
+      if (phase === "hello") {
+        const msgType = msg?.type ?? "";
+        if (msgType === "hello-ok" || msgType === "hello_ok") {
+          // 握手成功，发 chat.abort
+          phase = "abort";
+          ws.send(JSON.stringify({
+            type: "req",
+            id: "2",
+            method: "chat.abort",
+            params: { sessionKey },
+          }));
+        } else if (msgType === "hello-err" || msgType === "hello_err") {
+          phase = "done";
+          fail("openclaw-auth-failed", `gateway hello-err: ${msg?.error || "auth failed"}`);
+        }
+        return;
+      }
+
+      if (phase === "abort") {
+        // 等待 chat.abort 响应（id="2" 或任意 res）
+        const isResponse = msg?.id === "2" || msg?.type === "res";
+        if (isResponse) {
+          phase = "done";
+          cleanup();
+          resolve({ ok: true, aborted: 1 });
+        }
+      }
+    });
+  });
+}
+
+function _timeout(ms, limited, error) {
+  return new Promise((resolve) =>
+    setTimeout(() => resolve({ ok: false, limited, error }), ms)
+  );
+}

package/src-ext/core/pairCodeClient.mjs

@@ -0,0 +1,331 @@
+// pair code consume + 本地持久化。
+//
+// 升级后的协议(对齐服务端 internal/handler/pair_code/handler.go):
+//
+//   POST /v1/pair-codes/<code>/consume
+//   Body: {"client_user_id":"<...>", "runtime":"hermes|claude|codex|openclaw"}
+//   Response: {"status":"ok", "gw_id":"...", "bridge_token":"...", "runtime":"..."}
+//
+// session_id 现在是 gw_id —— 服务端 BridgeStore.Issue 颁发的 gateway 身份。
+// bridge 走 long-poll worker 模式,所有通讯都用 (gw_id, bridge_token) 鉴权,
+// 不再走 SSE 订阅 / 不再有"unified thread_id"概念,session 概念退化。
+//
+// 兼容路径:服务端仍保留 /api/ext/pair-codes/<code>/consume(legacy 老 cli 用),
+// 这里默认调新端点;失败回退老端点(让用户在升级期间不会全炸)。
+//
+// 存储位置: ~/.agentlink/ext-<runtime>-last.json,内容兼容老格式
+// (新增 gw_id,session_id 仍保留作 legacy 兼容,值与 gw_id 相同)。
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import process from "node:process";
+import relayDefaults from "../../src-shared/relay-defaults.json" with { type: "json" };
+import { CLI_STATE_DIR_NAME } from "./attachAuditLog.mjs";
+
+/**
+ * Normalize a raw hostname for reporting to the server.
+ *
+ * Rules (applied in order):
+ *   1. trim whitespace
+ *   2. strip `.local` or `.localdomain` suffix (case-sensitive — macOS produces lowercase)
+ *   3. truncate to 64 graphemes (unicode-safe)
+ *   4. if empty → return "unknown-host"
+ *
+ * The function is pure — it takes a string and never calls os.hostname().
+ * Callers pass os.hostname() themselves so this is unit-testable without monkey-patching.
+ *
+ * @param {string} raw  e.g. os.hostname()
+ * @returns {string}
+ */
+export function normalizeHostName(raw) {
+  let s = String(raw ?? "").trim();
+  if (s.endsWith(".local")) s = s.slice(0, -".local".length);
+  else if (s.endsWith(".localdomain")) s = s.slice(0, -".localdomain".length);
+  const graphemes = Array.from(s);
+  if (graphemes.length > 64) s = graphemes.slice(0, 64).join("");
+  return s || "unknown-host";
+}
+
+/** 默认 relay URL。 */
+export const DEFAULT_RELAY_URL = relayDefaults.defaultRelayUrl;
+
+/** 4 种合法 runtime — 与服务端 util.IsValidRuntimeKind 对齐。 */
+export const VALID_RUNTIMES = Object.freeze(["hermes", "claude", "codex", "openclaw"]);
+
+/** 按优先级解析 relay url:显式 --relay > env > 默认。永远有值。 */
+export function resolveRelayUrl(optionsRelay) {
+  const opt = typeof optionsRelay === "string" ? optionsRelay.trim() : "";
+  if (opt) return opt;
+  const env = process.env.AGENTLINK_RELAY_URL?.trim() || "";
+  if (env) return env;
+  return DEFAULT_RELAY_URL;
+}
+
+// 唯一来源：目录名 CLI_STATE_DIR_NAME 来自 attachAuditLog.mjs
+// 改名 agentlink 时只改那里；这里动态计算确保测试注入 HOME 时路径正确。
+//
+// 必须认 AGENTLINK_HOME —— native 侧（bin/agentlink 的 resolveAgentlinkHome）优先
+// 读 AGENTLINK_HOME 来定位 ~/.agentlink；ext 侧若只用 os.homedir()，当用户/ service
+// 设了 AGENTLINK_HOME≠$HOME/.agentlink 时两侧分叉 —— reset 的孤儿探测（bin 的
+// runtimeHasLocalState）与 ext 的实际清理读写不同文件，导致漏检/空操作。统一优先
+// AGENTLINK_HOME（其值即 .agentlink 目录全路径），保持四端 pair state 定位一致。
+function stateDir() {
+  const fromEnv = process.env.AGENTLINK_HOME?.trim();
+  if (fromEnv) return fromEnv;
+  return path.join(os.homedir(), CLI_STATE_DIR_NAME);
+}
+function stateFile(runtime) { return path.join(stateDir(), `ext-${runtime}-last.json`); }
+function configJsonFile() { return path.join(stateDir(), "config.json"); }
+function ensureDir() {
+  try { fs.mkdirSync(stateDir(), { recursive: true }); return true; }
+  catch { return false; }
+}
+
+// openclaw / hermes 的 pair 凭证由 `agentlink pair` 命令写到
+// ~/.agentlink/config.json (key: relayGatewayId/Token、hermesRelayGatewayId/Token),
+// 与 claude/codex 用的 ext-<runtime>-last.json 是两套独立存储。bridge 历史只读
+// ext 文件,导致 openclaw/hermes 新版 pair 后 bridge 启动报"尚未配对"。
+// 这里加一层 fallback:ext 文件不存在 / 字段不全时,从 config.json 兜底。
+function readPairStateFromConfig(runtime) {
+  if (runtime !== "hermes" && runtime !== "openclaw") return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(configJsonFile(), "utf8"));
+  } catch { return null; }
+  if (!parsed || typeof parsed !== "object") return null;
+  const idKey = runtime === "hermes" ? "hermesRelayGatewayId" : "relayGatewayId";
+  const tokKey = runtime === "hermes" ? "hermesRelayGatewayToken" : "relayGatewayToken";
+  const gwId = String(parsed[idKey] || "").trim();
+  const relayUrl = String(parsed.relayUrl || "").trim();
+  const bridgeToken = String(parsed[tokKey] || "").trim();
+  if (!gwId || !relayUrl) return null;
+  return {
+    gw_id: gwId,
+    runtime,
+    relay_url: relayUrl,
+    bridge_token: bridgeToken,
+    saved_at: null,
+  };
+}
+
+/**
+ * 读本地保存的 pair 状态。
+ * 老格式只有 session_id,新格式同时有 gw_id;读时兼容(gw_id 缺时用 session_id 兜底)。
+ *
+ * @returns {{gw_id, runtime, relay_url, bridge_token, saved_at} | null}
+ */
+export function readPairState(runtime) {
+  try {
+    const raw = fs.readFileSync(stateFile(runtime), "utf8");
+    const obj = JSON.parse(raw);
+    if (!obj || typeof obj !== "object") return readPairStateFromConfig(runtime);
+    if (obj.runtime !== runtime) return readPairStateFromConfig(runtime);
+    const gwId = String(obj.gw_id || obj.session_id || "").trim();
+    const relayUrl = String(obj.relay_url || "").trim();
+    if (!gwId || !relayUrl) return readPairStateFromConfig(runtime);
+    const result = {
+      gw_id: gwId,
+      runtime: obj.runtime,
+      relay_url: relayUrl,
+      bridge_token: String(obj.bridge_token || "").trim(),
+      saved_at: obj.saved_at || null,
+    };
+    // hermesProfileName: hermes-profile-isolation 新字段，旧 pair state 无此字段
+    if (obj.hermesProfileName != null) {
+      result.hermesProfileName = String(obj.hermesProfileName);
+    }
+    return result;
+  } catch { return readPairStateFromConfig(runtime); }
+}
+
+/**
+ * 写入 pair 状态。同时写 gw_id 与 session_id(后者为 legacy 字段,与 gw_id 同值)。
+ * hermesProfileName 可选字段，hermes runtime 配对时写入，供 bridge 启动时读取。
+ */
+export function writePairState(runtime, { gw_id, relay_url, bridge_token, hermesProfileName }) {
+  if (!ensureDir()) return false;
+  const id = String(gw_id || "").trim();
+  if (!id) return false;
+  const obj = {
+    gw_id: id,
+    session_id: id, // legacy 字段保留,服务管理脚本读老格式时不报错
+    runtime,
+    relay_url,
+    bridge_token: bridge_token || "",
+    saved_at: new Date().toISOString(),
+  };
+  // hermes profile name: 写入时携带，供 bridge 启动读取 profileHome
+  if (hermesProfileName != null) {
+    obj.hermesProfileName = String(hermesProfileName);
+  }
+  try {
+    fs.writeFileSync(stateFile(runtime), JSON.stringify(obj, null, 2) + "\n", "utf8");
+    return true;
+  } catch { return false; }
+}
+
+export function clearPairState(runtime) {
+  try { fs.unlinkSync(stateFile(runtime)); return true; }
+  catch { return false; }
+}
+
+/**
+ * 已废弃 — 旧的 SSE cursor 概念。新 worker 模式不需要;保留空函数避免外部 import 报错。
+ */
+export function clearCursor() { return false; }
+
+/**
+ * 向 server 消费 pair code。
+ *
+ * runtime 必填 — 服务端复合主键(code, runtime)允许同 code 复用到不同 runtime。
+ * 优先调新端点 /v1/pair-codes/<code>/consume,404/410 时回退老端点
+ * /api/ext/pair-codes/<code>/consume(让升级期同时存在新老服务端的环境工作)。
+ *
+ * 返回 server 响应:
+ *   { status:"ok", gw_id, bridge_token, runtime }
+ *
+ * 老端点的响应字段 session_id 会被规范化为 gw_id。
+ *
+ * @param {{relayUrl:string, code:string, runtime:string, clientUserId?:string, fetchImpl?:Function}} args
+ */
+export async function consumePairCode({ relayUrl, code, runtime, clientUserId, fetchImpl }) {
+  const f = fetchImpl || globalThis.fetch;
+  if (typeof f !== "function") throw new Error("fetch unavailable");
+  const rt = String(runtime ?? "").trim().toLowerCase();
+  if (!VALID_RUNTIMES.includes(rt)) {
+    throw new Error(`consumePairCode: runtime must be one of ${VALID_RUNTIMES.join(", ")}`);
+  }
+  const cuid = String(clientUserId ?? "").trim() || `cli-${rt}`;
+  const base = relayUrl.replace(/\/+$/, "");
+
+  const hostName = normalizeHostName(os.hostname());
+
+  // 1. 优先打新端点
+  const v1 = `${base}/v1/pair-codes/${encodeURIComponent(code)}/consume`;
+  const v1Body = JSON.stringify({ client_user_id: cuid, runtime: rt, hostName });
+  const v1Res = await f(v1, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: v1Body,
+  });
+  const v1Text = await v1Res.text();
+  if (v1Res.ok) {
+    return parseConsumeBody(v1Text, rt);
+  }
+  if (v1Res.status !== 404) {
+    // 404 = 端点不存在 → 老服务,回退;其它(400/410/500)直接抛。
+    throw makeConsumeError(v1Res.status, v1Text);
+  }
+
+  // 2. 回退老端点 /api/ext/pair-codes/<code>/consume
+  const legacy = `${base}/api/ext/pair-codes/${encodeURIComponent(code)}/consume?runtime=${rt}`;
+  const legacyRes = await f(legacy, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ runtime: rt, client_user_id: cuid, hostName }),
+  });
+  const legacyText = await legacyRes.text();
+  if (!legacyRes.ok) throw makeConsumeError(legacyRes.status, legacyText);
+  return parseConsumeBody(legacyText, rt);
+}
+
+function parseConsumeBody(text, expectedRuntime) {
+  let obj;
+  try { obj = JSON.parse(text); }
+  catch (err) { throw new Error(`consume: bad json response: ${err?.message}`); }
+  if (!obj || typeof obj !== "object") throw new Error("consume: empty response");
+  // 新端点返回 gw_id;老端点返回 session_id(也是 gw_id 值)。统一成 gw_id。
+  const gwId = String(obj.gw_id || obj.session_id || "").trim();
+  if (!gwId) throw new Error("consume: response missing gw_id/session_id");
+  const bridgeToken = String(obj.bridge_token || "").trim();
+  const rt = String(obj.runtime || expectedRuntime).toLowerCase();
+  return { status: "ok", gw_id: gwId, bridge_token: bridgeToken, runtime: rt };
+}
+
+function makeConsumeError(status, text) {
+  const snippet = String(text || "").slice(0, 200);
+  if (status === 404) {
+    const err = new Error(`pair code invalid or expired: ${snippet}`);
+    err.code = "PAIR_NOT_FOUND";
+    return err;
+  }
+  if (status === 410) {
+    const err = new Error(`pair code already consumed or expired: ${snippet}`);
+    err.code = "PAIR_GONE";
+    return err;
+  }
+  return new Error(`consume failed: HTTP ${status} ${snippet}`);
+}
+
+/**
+ * 一站式:根据 CLI 参数解析出最终要用的 { gwId, relayUrl, bridgeToken }。
+ *
+ * 规则:
+ *   1. options.pair 有值: 调 consume,写本地状态,返回新结果
+ *   2. options["session-id"] 有值: 直接返回(需要 options.relay 或 env 给 relay)
+ *      —— bridge_token 缺失时返回空,worker 启动会失败,提示用户重新 pair
+ *   3. 否则:读本地状态(上次 pair 过的)
+ *   4. 找不到就抛错
+ */
+export async function resolveSession({ runtime, options, log }) {
+  const relay = resolveRelayUrl(options.relay);
+  if (options.pair) {
+    log?.info("pair.consume.start", "consuming pair code", { code: options.pair, relay });
+    const res = await consumePairCode({
+      relayUrl: relay,
+      code: String(options.pair),
+      runtime,
+      clientUserId: options["client-user-id"] ? String(options["client-user-id"]) : undefined,
+    });
+    if (res.runtime !== runtime) {
+      throw new Error(
+        `pair code is for runtime=${res.runtime}, but you ran agentlink-agent ${runtime}`,
+      );
+    }
+    writePairState(runtime, {
+      gw_id: res.gw_id,
+      relay_url: relay,
+      bridge_token: res.bridge_token,
+    });
+    log?.info("pair.consumed", "pair code accepted", {
+      gw_id: res.gw_id, runtime, has_bridge_token: !!res.bridge_token,
+    });
+    return {
+      gwId: res.gw_id,
+      relayUrl: relay,
+      source: "pair",
+      bridgeToken: res.bridge_token || "",
+    };
+  }
+  if (options["session-id"] || options["gw-id"]) {
+    return {
+      gwId: String(options["gw-id"] || options["session-id"]),
+      relayUrl: relay,
+      source: "explicit",
+      bridgeToken: "",
+    };
+  }
+  const saved = readPairState(runtime);
+  if (saved) {
+    log?.info("pair.state.reuse", "reusing saved pair state", {
+      gw_id: saved.gw_id, relay: saved.relay_url, has_bridge_token: !!saved.bridge_token,
+    });
+    const savedResult = {
+      gwId: saved.gw_id,
+      relayUrl: saved.relay_url,
+      source: "saved",
+      bridgeToken: saved.bridge_token || "",
+    };
+    // N2.3: 透传 hermesProfileName（hermes-profile-isolation）
+    if (saved.hermesProfileName != null) {
+      savedResult.profileName = saved.hermesProfileName;
+    }
+    return savedResult;
+  }
+  throw new Error(
+    "尚未配对。请在 App 上创建会话,然后运行:\n" +
+      `  agentlink pair <4位码> -r ${runtime}\n` +
+      "配对成功后 CLI 会自动在后台保活运行。",
+  );
+}

package/src-ext/core/pairInventory.mjs

@@ -0,0 +1,59 @@
+/**
+ * pairInventory.mjs — pair-all host-inventory Phase 2 辅助
+ *
+ * 把 runPairAll 的 summary 数组与 detectInstalledRuntimes 的 detected 数组
+ * 合并成 relay /v1/pair-sessions/:code/host-inventory Phase 2 POST 所需的
+ * results 数组。
+ *
+ * outcome 映射规则（与 spec-delta cli-pair-session-result 对齐）：
+ *   summary ok=true  && !skipped → "paired_new"
+ *   summary skipped=true         → "paired_existing"
+ *   summary ok=false             → "failed"
+ *   未出现在 summary（未安装）     → "not_installed"
+ */
+
+/** 所有被扫描的 runtime 名（固定 4 个）。 */
+const SCANNED_RUNTIMES = ["openclaw", "hermes", "claude", "codex"];
+
+/**
+ * buildPairSessionResults 从 summary + detected 构建 per-runtime outcome 列表。
+ *
+ * @param {Array<{kind: string, ok: boolean, skipped?: boolean}>} summary
+ *   runPairAll 内的 summary 数组，只包含已安装的 runtime。
+ * @param {Array<{kind: string, installed: boolean}>} detected
+ *   detectInstalledRuntimes 的返回值，含全部 4 个 runtime。
+ * @returns {Array<{runtime: string, outcome: string}>}
+ *   长度为 4，覆盖全部 scanned runtimes。
+ */
+export function buildPairSessionResults(summary, detected) {
+  // 构建 summaryMap：kind → summary entry（方便 O(1) 查找）
+  const summaryMap = new Map(summary.map((s) => [s.kind, s]));
+
+  // 构建 installedSet：已安装的 runtime 集合
+  const installedSet = new Set(
+    (detected || []).filter((d) => d.installed).map((d) => d.kind),
+  );
+
+  return SCANNED_RUNTIMES.map((rt) => {
+    const s = summaryMap.get(rt);
+    let outcome;
+
+    if (s) {
+      // 出现在 summary → 已安装且参与过配对流程
+      if (s.skipped) {
+        outcome = "paired_existing";
+      } else if (s.ok) {
+        outcome = "paired_new";
+      } else {
+        outcome = "failed";
+      }
+    } else if (!installedSet.has(rt)) {
+      outcome = "not_installed";
+    } else {
+      // 已安装但没有出现在 summary（理论上不应发生）→ 保守标 failed
+      outcome = "failed";
+    }
+
+    return { runtime: rt, outcome };
+  });
+}

package/src-ext/core/pathExpand.mjs

@@ -0,0 +1,34 @@
+/**
+ * pathExpand.mjs — ~ 展开工具
+ *
+ * expandHome(p): 展开路径中的 ~ 前缀（~ 或 ~/），再 path.resolve 为绝对路径。
+ * 四种 runtime 共用，是统一路径规范化的基础。
+ *
+ * 规则：
+ *   "~"      → os.homedir()
+ *   "~/"     → os.homedir() + "/"（join 后 resolve）
+ *   "~/foo"  → path.join(os.homedir(), "foo")
+ *   其他      → path.resolve(p)（绝对路径不变，相对路径基于 cwd 解析）
+ *
+ * 注意：~foo（非 ~/）不展开，视为普通路径（与 bash 行为一致，~foo 是他人 home）。
+ */
+
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * 展开路径中的 ~ 前缀，再 path.resolve 到绝对路径。
+ *
+ * @param {string} p  输入路径（可能含 ~ 前缀）
+ * @returns {string}  绝对路径字符串
+ */
+export function expandHome(p) {
+  if (typeof p !== "string") p = String(p ?? "");
+  if (p === "~") {
+    return path.resolve(os.homedir());
+  }
+  if (p.startsWith("~/")) {
+    return path.resolve(path.join(os.homedir(), p.slice(2)));
+  }
+  return path.resolve(p);
+}