ai-lab-bridge 0.1.1

package/index.js

@@ -0,0 +1,1333 @@
+#!/usr/bin/env node
+/**
+ * ai-lab-bridge —— AI Lab 平台设备桥接进程（Bridge Protocol v1，daemon 模式对齐 coze-bridge）
+ *
+ * 用法：
+ *   npx -y ai-lab-bridge@latest connect --server=wss://<host>/api/bridge/ws --token=dev-xxx
+ *       首次连接：保存配置并以后台 daemon 运行（命令执行完即可关闭终端）
+ *   npx -y ai-lab-bridge@latest connect            # 后台运行/复用已有 daemon（读取已保存配置）
+ *   npx -y ai-lab-bridge@latest connect --foreground   # 前台运行（调试用，Ctrl+C 退出）
+ *   npx -y ai-lab-bridge@latest status             # 查看后台进程与平台连接状态
+ *   npx -y ai-lab-bridge@latest stop               # 停止后台进程
+ *
+ * 机制：
+ *   - 主动外连平台 WSS（只出不进，穿透 NAT），连接即鉴权（token 走 query 参数）
+ *   - ready 后上报本机 CLI 能力（register），每 30s 心跳保活
+ *   - 收到 execute 后 spawn 本地 CLI headless 进程，stdout JSONL 逐行归一化为事件回传
+ *   - 断线指数退避重连；cancel 中断当前执行
+ *   - daemon 控制面（对齐 coze-bridge）：pid/port/token 三件套落盘 ~/.ai-lab/bridge/，
+ *     status/stop/配置投递通过本地回环 HTTP（Bearer token 鉴权）操作常驻进程
+ */
+
+const { spawn, spawnSync } = require("child_process");
+const http = require("http");
+const crypto = require("crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const WebSocket = require("ws");
+
+// ---------------------------------------------------------------------------
+// 命令行参数与本地状态目录
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (const raw of argv.slice(2)) {
+    const m = raw.match(/^--([a-z-]+)(?:=(.*))?$/i);
+    if (m) args[m[1]] = m[2] === undefined ? true : m[2];
+    else args._.push(raw);
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv);
+// 子命令：connect（默认，兼容裸 --server/--token 形式）/ status / stop / help
+const SUBCOMMAND = (args._ && args._[0]) || "connect";
+
+// 本地状态目录（对齐 coze-bridge 的 ~/.coze/bridge）：
+//   config.json              连接凭据落盘（0600）
+//   bridge.pid/port/token    控制面三件套：daemon 进程寻址 + 本机 IPC 鉴权
+//   logs/                    daemon 运行日志（按天滚动）
+const STATE_DIR = path.join(os.homedir(), ".ai-lab", "bridge");
+const CONFIG_FILE = path.join(STATE_DIR, "config.json");
+const PID_FILE = path.join(STATE_DIR, "bridge.pid");
+const PORT_FILE = path.join(STATE_DIR, "bridge.port");
+const CTL_TOKEN_FILE = path.join(STATE_DIR, "bridge.token");
+const LOGS_DIR = path.join(STATE_DIR, "logs");
+
+function loadPersistedConfig() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+    if (parsed && parsed.server && parsed.token) return parsed;
+  } catch {}
+  return null;
+}
+
+function persistConfig(server, token) {
+  try {
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify({ server, token }, null, 2), { mode: 0o600 });
+  } catch (err) {
+    console.warn(`[bridge] 配置落盘失败（不影响本次连接）: ${err.message}`);
+  }
+}
+
+/** 读取控制面三件套（pid/port/token 任一缺失视为未运行）。 */
+function readCtlState() {
+  try {
+    const pid = Number(fs.readFileSync(PID_FILE, "utf8").trim());
+    const port = Number(fs.readFileSync(PORT_FILE, "utf8").trim());
+    const ctlToken = fs.readFileSync(CTL_TOKEN_FILE, "utf8").trim();
+    if (pid && port && ctlToken) return { pid, port, ctlToken };
+  } catch {}
+  return null;
+}
+
+/** 判断 pid 对应进程是否存活（signal 0 探活，Windows/Unix 通用，零子进程）。 */
+function isPidAlive(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err && err.code === "EPERM") return true; // 进程存在但无权限
+    return false;
+  }
+}
+
+function removeCtlFiles() {
+  for (const f of [PID_FILE, PORT_FILE, CTL_TOKEN_FILE]) {
+    try { fs.unlinkSync(f); } catch {}
+  }
+}
+
+function todayLogFile() {
+  return path.join(LOGS_DIR, `bridge-${new Date().toISOString().slice(0, 10)}.log`);
+}
+
+function printUsage() {
+  console.log(`ai-lab-bridge —— AI Lab 平台设备桥接进程
+
+用法:
+  npx -y ai-lab-bridge@latest connect --server=<wss://host/api/bridge/ws> --token=dev-xxx   # 首次连接（保存配置并后台运行）
+  npx -y ai-lab-bridge@latest connect              # 后台运行/复用 daemon（终端可关闭）
+  npx -y ai-lab-bridge@latest connect --foreground # 前台运行（调试用）
+  npx -y ai-lab-bridge@latest status               # 查看运行状态
+  npx -y ai-lab-bridge@latest stop                 # 停止后台进程
+
+其他:
+  help     显示本帮助`);
+}
+
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const RECONNECT_BASE_MS = 2_000;
+const RECONNECT_MAX_MS = 60_000;
+
+// 版本号从 package.json 读取（--version / status / daemon 日志均输出）
+const BRIDGE_VERSION = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__dirname, "package.json"), "utf8")).version || "";
+  } catch {
+    return "";
+  }
+})();
+
+// 连接参数由各子命令解析填充（connect/daemon 需要，status/stop 不需要）
+let SERVER = "";
+let TOKEN = "";
+
+// ---------------------------------------------------------------------------
+// CLI 能力探测
+// ---------------------------------------------------------------------------
+
+function runVersionProbe(cmd, versionFlag) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (version) => {
+      if (done) return;
+      done = true;
+      resolve(version);
+    };
+    try {
+      const child = spawn(cmd, [versionFlag], { shell: process.platform === "win32", windowsHide: true });
+      let out = "";
+      child.stdout.on("data", (d) => (out += d.toString()));
+      child.on("error", () => finish(null));
+      child.on("close", (code) => finish(code === 0 ? out.trim().split(/\r?\n/)[0] || "unknown" : null));
+      setTimeout(() => {
+        try { child.kill(); } catch {}
+        finish(null);
+      }, 8000);
+    } catch {
+      finish(null);
+    }
+  });
+}
+
+let cursorBinary = "agent";
+
+async function detectCapabilities() {
+  // Cursor CLI 的二进制名是 agent（较老版本为 cursor-agent），探测并记录实际可用的那个。
+  const probeCursor = async () => {
+    const v = await runVersionProbe("agent", "--version");
+    if (v) {
+      cursorBinary = "agent";
+      return v;
+    }
+    const fallback = await runVersionProbe("cursor-agent", "--version");
+    if (fallback) cursorBinary = "cursor-agent";
+    return fallback;
+  };
+  const [claudeVersion, codexVersion, opencodeVersion, codefreeVersion, cursorVersion, geminiVersion, qwenVersion, iflowVersion] = await Promise.all([
+    runVersionProbe("claude", "--version"),
+    runVersionProbe("codex", "--version"),
+    runVersionProbe("opencode", "--version"),
+    runVersionProbe("codefree-o", "--version"),
+    probeCursor(),
+    runVersionProbe("gemini", "--version"),
+    runVersionProbe("qwen", "--version"),
+    runVersionProbe("iflow", "--version"),
+  ]);
+  return [
+    { cli: "claude", version: claudeVersion, available: !!claudeVersion },
+    { cli: "codex", version: codexVersion, available: !!codexVersion },
+    { cli: "opencode", version: opencodeVersion, available: !!opencodeVersion },
+    { cli: "codefree-o", version: codefreeVersion, available: !!codefreeVersion },
+    { cli: "cursor", version: cursorVersion, available: !!cursorVersion },
+    { cli: "gemini", version: geminiVersion, available: !!geminiVersion },
+    { cli: "qwen", version: qwenVersion, available: !!qwenVersion },
+    { cli: "iflow", version: iflowVersion, available: !!iflowVersion },
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// CLI 适配器：把各 CLI 输出归一化为统一事件
+// ---------------------------------------------------------------------------
+
+class Session {
+  constructor(requestId, send) {
+    this.requestId = requestId;
+    this.send = send;
+    this.seq = 0;
+    this.child = null;
+    this.cancelled = false;
+    this.cliSessionId = null;
+    this.textParts = [];
+    this.usage = null;
+    this.finished = false;
+    this.stderrTail = [];
+    this.cliError = null; // CLI 输出的最后一条可读错误（优先于 stderr 原始 JSON）
+    this.thinkOpen = false; // <think> 区间状态：思考内容包标签后按普通文本增量下发
+    this.options = {};
+    this.seenTools = new Set(); // 工具 callID 去重（opencode 会对同一 part 按状态多次推送）
+    this.fileDir = null; // 附件下载临时目录
+  }
+
+  emitEvent(kind, payload = {}) {
+    this.send({ type: "event", request_id: this.requestId, seq: ++this.seq, kind, ...payload });
+  }
+
+  emitText(text) {
+    if (!text) return;
+    this.textParts.push(text);
+    this.emitEvent("text_delta", { text });
+  }
+
+  emitSession(cliSessionId) {
+    if (!cliSessionId || this.cliSessionId) return;
+    this.cliSessionId = cliSessionId;
+    this.emitEvent("session", { cli_session_id: cliSessionId });
+  }
+
+  /**
+   * 任务结束后把附件目录迁移到 CLI 会话 id 键下（首轮以 request_id 作键）。
+   * 必须在 CLI 进程退出后执行：--file 参数在启动时已指向旧路径，提前重命名会竞态。
+   * 迁移后续接轮（session_ref = 会话 id）复用同一目录，跨轮读取上一轮附件。
+   */
+  migrateFileDirToSession() {
+    if (!this.fileDir || !this.cliSessionId) return;
+    const canonicalDir = path.join(FILE_DIR_ROOT, String(this.cliSessionId).replace(/[\\/:*?"<>|]/g, "_"));
+    if (path.resolve(this.fileDir) === path.resolve(canonicalDir)) return;
+    try {
+      if (fs.existsSync(canonicalDir)) {
+        // 已存在同名目录（如异常重发）：把本轮文件并入后删掉本轮目录
+        for (const name of fs.readdirSync(this.fileDir)) {
+          try { fs.renameSync(path.join(this.fileDir, name), path.join(canonicalDir, name)); } catch {}
+        }
+        fs.rmSync(this.fileDir, { recursive: true, force: true });
+      } else {
+        fs.renameSync(this.fileDir, canonicalDir);
+      }
+      this.fileDir = canonicalDir;
+    } catch (err) {
+      console.log(`[bridge] 附件目录迁移失败: ${err.message}`);
+    }
+  }
+
+  emitUsage(usage) {
+    if (usage && typeof usage === "object") {
+      this.usage = usage;
+      this.emitEvent("usage", { usage });
+    }
+  }
+
+  emitToolUse(summary) {
+    if (summary) this.emitEvent("tool_use", { summary: String(summary).slice(0, 300) });
+  }
+
+  /** 思考内容标注：进入 <think> 区间（幂等，标签不嵌套），由各 CLI 适配器共用 */
+  beginThink() {
+    if (!this.thinkOpen) {
+      this.thinkOpen = true;
+      this.emitText("<think>\n");
+    }
+  }
+
+  /** 退出 <think> 区间（幂等）：正文/工具事件前调用，避免后续内容被吞进思考块 */
+  endThink() {
+    if (this.thinkOpen) {
+      this.thinkOpen = false;
+      this.emitText("\n</think>\n");
+    }
+  }
+
+  /** 追加一段思考内容（自动维护区间开合） */
+  emitThink(text) {
+    if (!text) return;
+    this.beginThink();
+    this.emitText(String(text));
+  }
+
+  finish(status, error = null) {
+    if (this.finished) return;
+    this.finished = true;
+    if (this.timer) clearTimeout(this.timer);
+    // 思考区间未闭合（CLI 结束时仍在思考态）：补闭合标签，避免前端 think 渲染悬挂
+    this.endThink();
+    const output = this.textParts.join("");
+    send({
+      type: "result",
+      request_id: this.requestId,
+      status,
+      output,
+      usage: this.usage || undefined,
+      error: error || undefined,
+    });
+    if (typeof activeSessions !== "undefined") {
+      activeSessions.delete(this.requestId);
+    }
+  }
+
+  kill() {
+    this.cancelled = true;
+    if (this.promptFile) {
+      try { fs.unlinkSync(this.promptFile); } catch {}
+    }
+    if (this.child && this.child.pid) {
+      try {
+        if (process.platform === "win32") {
+          spawn("taskkill", ["/pid", String(this.child.pid), "/T", "/F"], { windowsHide: true });
+        } else {
+          this.child.kill("SIGTERM");
+          setTimeout(() => { try { this.child.kill("SIGKILL"); } catch {} }, 3000);
+        }
+      } catch {}
+    }
+  }
+}
+
+/** 解析一行 JSON；失败返回 null。 */
+function safeJsonLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("{")) return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+function handleClaudeLine(session, obj) {
+  if (!obj || typeof obj !== "object") return;
+  if (obj.session_id) session.emitSession(obj.session_id);
+  if (obj.type === "assistant" && obj.message && Array.isArray(obj.message.content)) {
+    for (const block of obj.message.content) {
+      if (block.type === "text" && block.text) {
+        session.endThink();
+        session.emitText(block.text);
+      } else if (block.type === "thinking" && block.thinking) {
+        // Claude 扩展思考块：包 <think> 标签按文本增量下发，平台/前端已支持渲染
+        session.emitThink(block.thinking);
+      } else if (block.type === "tool_use") {
+        session.endThink();
+        session.emitToolUse(block.name);
+      }
+    }
+  } else if (obj.type === "user" && obj.message && Array.isArray(obj.message.content)) {
+    for (const block of obj.message.content) {
+      if (block.type === "tool_result" && !block.is_error) session.emitToolUse("tool_result");
+    }
+  } else if (obj.type === "result") {
+    session.emitSession(obj.session_id);
+    session.emitUsage(obj.usage);
+    if (obj.subtype === "success") {
+      // result 字段是最终完整回复；stream-json 模式下 assistant 文本已回传，这里只兜底。
+      if (typeof obj.result === "string" && obj.result && !session.textParts.length) {
+        session.emitText(obj.result);
+      }
+      session.finish("completed");
+    } else {
+      session.finish("failed", obj.result || obj.error || `claude 执行异常: ${obj.subtype}`);
+    }
+  } else if (obj.type === "system" && obj.subtype && obj.subtype !== "init") {
+    // 其他系统事件忽略
+  }
+}
+
+function handleCodexLine(session, obj) {
+  if (!obj || typeof obj !== "object") return;
+  if (obj.type === "thread.started" && obj.thread_id) session.emitSession(obj.thread_id);
+  else if (obj.type === "item.completed" && obj.item) {
+    const item = obj.item;
+    if (item.item_type === "agent_message" && item.text) {
+      session.endThink();
+      session.emitText(item.text);
+    } else if (item.item_type === "command_execution") {
+      session.endThink();
+      session.emitToolUse(item.command || "command");
+    } else if (item.item_type === "reasoning") {
+      // Codex 推理摘要：不再丢弃，包 <think> 标签下发
+      session.emitThink(item.text || (Array.isArray(item.summary) ? item.summary.join("\n") : "") || "");
+    }
+  } else if (obj.type === "turn.completed") {
+    session.emitUsage(obj.usage);
+    session.finish("completed");
+  } else if (obj.type === "turn.failed" || obj.type === "error") {
+    const message = (obj.error && obj.error.message) || obj.message || "codex 执行失败";
+    session.finish("failed", message);
+  } else if (obj.session_id) {
+    session.emitSession(obj.session_id);
+  }
+}
+
+/**
+ * OpenCode 事件解析（`opencode run --format json` 的 raw JSON 事件流）。
+ * 字段命名在不同版本间有差异（sessionID/session_id、part.type 等），这里做宽松归一化；
+ * 非 JSON 行（老版本不支持 --format 时输出纯文本）按文本增量兜底。
+ *
+ * 工具事件（{type:"tool", part:{type:"tool", tool, callID, state:{status, input, output}}}）
+ * 升级为结构化 tool_call/tool_result：callID 配对，args/output 随事件回传，
+ * 平台侧按 tool_call_id 渲染工具块（call 建块、result 更新）。
+ */
+function handleOpencodeLine(session, obj) {
+  if (!obj || typeof obj !== "object") return;
+  const sid = obj.sessionID || obj.session_id || (obj.info && (obj.info.sessionID || obj.info.id));
+  if (sid) session.emitSession(sid);
+
+  const part = obj.part || obj;
+  const ptype = part.type || obj.type;
+  if (ptype === "text" && part.text) {
+    session.endThink();
+    session.emitText(part.text);
+  } else if (ptype === "reasoning" || ptype === "thinking") {
+    // OpenCode 系推理 part（codefree-o 同源）：不再丢弃，包 <think> 标签下发
+    session.emitThink(part.text || part.thinking || "");
+  } else if (ptype === "tool" || ptype === "tool_use" || ptype === "tool-invocation") {
+    session.endThink();
+    const callId = String(part.callID || part.call_id || part.id || "");
+    const name = String(part.tool || part.name || "tool");
+    const state = part.state || {};
+    if (callId && !session.seenTools.has(callId)) {
+      session.seenTools.add(callId);
+      session.emitEvent("tool_call", {
+        call_id: callId,
+        name,
+        args: JSON.stringify(state.input || {}),
+      });
+    }
+    if (callId && state.status === "completed") {
+      const output = state.output;
+      session.emitEvent("tool_result", {
+        call_id: callId,
+        name,
+        output: typeof output === "string" ? output : JSON.stringify(output ?? ""),
+      });
+    }
+    if (callId && state.status === "error") {
+      // 工具调用失败：opencode 系以 tool part state.status="error" 上报（带 callID），
+      // 直接配对成错误型 tool_result，平台按失败状态渲染工具块。
+      const errOutput = state.error || state.output || "tool 执行失败";
+      session.emitEvent("tool_result", {
+        call_id: callId,
+        name,
+        output: typeof errOutput === "string" ? errOutput : JSON.stringify(errOutput),
+        status: "error",
+      });
+    }
+    if (!callId) {
+      // 无 callID 的极端情况退化为 summary 事件
+      session.emitToolUse(part.tool || part.name || (state && state.title));
+    }
+  }
+  if (obj.type === "error" || (obj.error && typeof obj.error === "object")) {
+    const err = obj.error && typeof obj.error === "object" ? obj.error : null;
+    // 提取可读错误消息（opencode 系: error.data.message / error.message；附带 name/ref 便于定位）
+    const msg = (err && ((err.data && err.data.message) || err.message)) || obj.message;
+    const meta = err && err.name ? err.name : "";
+    const ref = err && err.data && err.data.ref ? err.data.ref : "";
+    const readable = [meta, msg, ref ? `ref: ${ref}` : ""].filter(Boolean).join(" | ") || JSON.stringify(obj).slice(0, 500);
+    // 只收集、不立即定责：error 可能是局部异常（如读取二进制 --file 失败后 CLI 继续运行），
+    // 也可能是致命错误（认证失败/模型不可用后随即退出）。两者由进程退出时的行为判定
+    // （见 child.on("close")）：error 之后 CLI 仍有输出 → 局部错误，以错误型工具块展示；
+    // error 之后无任何输出 → 致命错误，任务判 failed。
+    session.cliError = readable;
+    session.cliErrors = session.cliErrors || [];
+    session.cliErrors.push(readable);
+    session._lastErrLine = session._rawLineCount || 0;
+    session.stderrTail.push(JSON.stringify(obj.error || obj).slice(0, 500));
+  }
+}
+
+/**
+ * 将执行过程中收集的 CLI 局部错误以错误型工具块回传展示（call + result 配对），
+ * 平台侧渲染为 "CLI → 失败结果" 工具块。仅在按完成收尾时调用。
+ */
+function flushCliErrorTools(session) {
+  for (const readable of session.cliErrors || []) {
+    const callId = `cli_err_${(session._errSeq = (session._errSeq || 0) + 1)}`;
+    session.emitEvent("tool_call", {
+      call_id: callId,
+      name: "CLI",
+      args: JSON.stringify({ error_name: String(readable).split(" | ")[0] || "UnknownError" }),
+    });
+    session.emitEvent("tool_result", {
+      call_id: callId,
+      name: "CLI",
+      output: readable,
+      status: "error",
+    });
+  }
+  session.cliErrors = [];
+}
+
+/**
+ * Cursor CLI 事件解析（`agent -p --output-format stream-json`，NDJSON）。
+ * 格式与 Claude Code stream-json 高度同构：
+ *   {type:"system", subtype:"init", session_id} / {type:"assistant", message:{content:[{type:"text",text}]}}
+ *   / {type:"tool_call", tool_call:{...}} / {type:"result", subtype:"success", result, session_id}
+ */
+function handleCursorLine(session, obj) {
+  if (!obj || typeof obj !== "object") return;
+  if (obj.session_id) session.emitSession(obj.session_id);
+  if (obj.type === "assistant" && obj.message && Array.isArray(obj.message.content)) {
+    for (const block of obj.message.content) {
+      if (block.type === "text" && block.text) {
+        session.endThink();
+        session.emitText(block.text);
+      } else if (block.type === "thinking" && block.thinking) {
+        session.emitThink(block.thinking);
+      }
+    }
+  } else if (obj.type === "tool_call") {
+    const tc = obj.tool_call || {};
+    const variant = tc.writeToolCall || tc.readToolCall || tc.executeToolCall || {};
+    const summary = (variant.args && (variant.args.path || variant.args.command)) || tc.toolName || "tool";
+    session.emitToolUse(summary);
+  } else if (obj.type === "result") {
+    session.emitSession(obj.session_id);
+    if (obj.is_error || (obj.subtype && obj.subtype !== "success")) {
+      session.finish("failed", obj.error || (typeof obj.result === "string" ? obj.result : undefined) || `cursor 执行异常: ${obj.subtype}`);
+    } else {
+      if (typeof obj.result === "string" && obj.result && !session.textParts.length) {
+        session.emitText(obj.result);
+      }
+      session.finish("completed");
+    }
+  }
+}
+
+/**
+ * Gemini CLI 家族事件解析（gemini / qwen / iflow 的 `-p --output-format stream-json`，JSONL）。
+ * 事件类型：init(session id) / message / tool_use / tool_result / result(stats)。
+ * 各 fork 字段命名可能有差异，做宽松归一化；终态以进程退出码兜底。
+ */
+function handleGeminiLine(session, obj) {
+  if (!obj || typeof obj !== "object") return;
+  const sid = obj.session_id || obj.sessionId || (obj.init && (obj.init.session_id || obj.init.sessionId));
+  if (sid) session.emitSession(sid);
+
+  if (obj.type === "message" || obj.type === "assistant") {
+    const role = obj.role || (obj.message && obj.message.role);
+    if (role === "user") return;
+    let text = obj.text;
+    if (!text && obj.content) {
+      if (typeof obj.content === "string") text = obj.content;
+      else if (Array.isArray(obj.content)) {
+        text = obj.content
+          .filter((b) => (b && b.type === "text") || typeof b === "string")
+          .map((b) => (typeof b === "string" ? b : b.text))
+          .join("");
+      }
+    }
+    if (text) session.emitText(text);
+  } else if (obj.type === "tool_use" || obj.type === "tool_call") {
+    session.emitToolUse(obj.name || obj.tool_name || obj.tool || "tool");
+  } else if (obj.type === "result") {
+    session.emitUsage(obj.stats);
+    if (obj.error) {
+      const msg = typeof obj.error === "string" ? obj.error : (obj.error.message || JSON.stringify(obj.error));
+      session.finish("failed", msg);
+      return;
+    }
+    if (typeof obj.response === "string" && obj.response && !session.textParts.length) {
+      session.emitText(obj.response);
+    }
+    session.finish("completed");
+  }
+}
+
+/**
+ * 启动 CLI 子进程。
+ * @returns {Session}
+ */
+
+// 启动参数模板中 prompt 的占位符：Windows 下替换为临时文件读取表达式，其余平台直接替换为 prompt 文本。
+const PROMPT_TOKEN = "\u0000PROMPT\u0000";
+
+function launchCli(cli, argsTemplate, prompt, requestId) {
+  if (process.platform === "win32") {
+    // Windows 下 cmd 对引号/换行的转义不可靠：prompt 写临时文件，经 PowerShell 注入。
+    const promptFile = path.join(os.tmpdir(), `ai-lab-bridge-prompt-${requestId}.txt`);
+    fs.writeFileSync(promptFile, prompt, "utf8");
+    const safeFile = promptFile.replace(/'/g, "''");
+    const parts = argsTemplate.map(a => {
+      if (a === PROMPT_TOKEN) return `(Get-Content -Raw -Encoding UTF8 '${safeFile}')`;
+      return `'${String(a).replace(/'/g, "''")}'`;
+    });
+    return { argv: ["powershell.exe", ["-NoProfile", "-Command", `${cli} ${parts.join(" ")}`]], promptFile };
+  }
+  const argvArgs = argsTemplate.map(a => (a === PROMPT_TOKEN ? prompt : a));
+  return { argv: [cli, argvArgs], promptFile: null };
+}
+
+/** 从 execute.options 推导平台 HTTP base（WS 地址 → http 地址）。 */
+function platformHttpBase() {
+  return SERVER.replace(/^ws/i, "http").replace(/\/api\/bridge\/ws.*$/i, "");
+}
+
+/** 附件目录根：按 CLI 会话复用（跨轮保留），孤儿目录按 TTL 清理。 */
+const FILE_DIR_ROOT = path.join(os.tmpdir(), "ai-lab-bridge-files");
+/** 附件目录保留时长（毫秒）：超过后由周期清理删除。 */
+const FILE_DIR_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * 清理过期的附件目录（TTL）：孤儿会话目录占用的磁盘空间定期回收。
+ * 活跃会话目录 mtime 会随文件写入刷新，24h 内不会被误删。
+ */
+function cleanupStaleFileDirs() {
+  try {
+    if (!fs.existsSync(FILE_DIR_ROOT)) return;
+    const now = Date.now();
+    for (const name of fs.readdirSync(FILE_DIR_ROOT)) {
+      const dir = path.join(FILE_DIR_ROOT, name);
+      try {
+        const st = fs.statSync(dir);
+        if (!st.isDirectory()) continue;
+        if (now - st.mtimeMs > FILE_DIR_TTL_MS) {
+          fs.rmSync(dir, { recursive: true, force: true });
+          console.log(`[bridge] 已清理过期附件目录: ${name}`);
+        }
+      } catch {}
+    }
+  } catch {}
+}
+
+/**
+ * 下载用户附件到本地临时目录（平台 /api/bridge/files，device token 鉴权）。
+ * 文件路径形如 /{task_id}/upload/xxx，task_id 从中提取。
+ * 目录按 CLI 会话复用：续接轮（带 session_ref）直接用会话 id 作键；
+ * 首轮用 request_id 作键，CLI 上报会话 id 后重命名（见 Session.emitSession），
+ * 保证下一轮 CLI 仍能读取上一轮的附件路径。任务结束不删除，孤儿目录按 TTL 清理。
+ * 返回 {files: [{filename, localPath}], promptNote}；失败返回 {error}。
+ */
+async function downloadAttachments(message) {
+  const files = (message.options && message.options.files) || [];
+  const firstPath = String(files[0]?.path || "");
+  const taskMatch = firstPath.match(/^\/?([^/]+)\/upload\//);
+  const taskId = taskMatch ? taskMatch[1] : "";
+  const base = platformHttpBase();
+  if (!base || !taskId) return { error: "无法推导平台地址或任务 ID，附件下载失败" };
+  const dirKey = String(message.session_ref || message.request_id || "").replace(/[\\/:*?"<>|]/g, "_");
+  const dir = path.join(FILE_DIR_ROOT, dirKey);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const downloaded = [];
+  for (const file of files.slice(0, 10)) {
+    const safeName = String(file.filename || "file").replace(/[\\/:*?"<>|]/g, "_");
+    const localPath = path.join(dir, safeName);
+    const url = `${base}/api/bridge/files?token=${encodeURIComponent(TOKEN)}&task_id=${encodeURIComponent(taskId)}&file_path=${encodeURIComponent(file.path)}`;
+    let res;
+    try {
+      res = await fetch(url);
+    } catch (err) {
+      return { error: `附件 ${safeName} 下载请求失败: ${err.message}` };
+    }
+    if (!res.ok) {
+      return { error: `附件 ${safeName} 下载失败（HTTP ${res.status}）` };
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    fs.writeFileSync(localPath, buf);
+    const entry = { filename: safeName, localPath };
+    // 文档类附件平台侧会转换出 Markdown 版本（file.md_path），一并下载供 CLI 优先读取；
+    // md 下载失败不阻断任务（降级为仅原始文件）。
+    const mdPath = String(file.md_path || "").trim();
+    if (mdPath) {
+      const mdSafeName = String(mdPath.split("/").pop() || "file.md").replace(/[\\/:*?"<>|]/g, "_");
+      const mdLocalPath = path.join(dir, mdSafeName);
+      try {
+        const mdUrl = `${base}/api/bridge/files?token=${encodeURIComponent(TOKEN)}&task_id=${encodeURIComponent(taskId)}&file_path=${encodeURIComponent(mdPath)}`;
+        const mdRes = await fetch(mdUrl);
+        if (mdRes.ok) {
+          fs.writeFileSync(mdLocalPath, Buffer.from(await mdRes.arrayBuffer()));
+          entry.mdLocalPath = mdLocalPath;
+        } else {
+          console.log(`[bridge] Markdown 版本下载失败（HTTP ${mdRes.status}），仅使用原始文件: ${safeName}`);
+        }
+      } catch (err) {
+        console.log(`[bridge] Markdown 版本下载失败（${err.message}），仅使用原始文件: ${safeName}`);
+      }
+    }
+    downloaded.push(entry);
+  }
+  const note = downloaded
+    .map(f => {
+      const lines = [`- ${f.localPath}${f.mdLocalPath ? "（原始文件）" : ""}`];
+      if (f.mdLocalPath) lines.push(`- ${f.mdLocalPath}（同一文件的 Markdown 转换版，优先读取此文件）`);
+      return lines.join("\n");
+    })
+    .join("\n");
+  return {
+    dir,
+    files: downloaded,
+    promptNote: `\n\n[用户上传的附件已下载到本机以下路径，可直接读取]\n${note}`,
+  };
+}
+
+function startSession(message) {
+  const { request_id: requestId, cli, prompt, session_ref: sessionRef, options = {} } = message;
+  const session = new Session(requestId, send);
+  session.options = options;
+  session.cli = cli;
+  session.sessionRef = sessionRef || null; // 会话续接占用判定（同 session_ref 互斥）
+
+  const timeoutSeconds = Number(options.timeout_seconds) > 0 ? Number(options.timeout_seconds) : 0;
+  const cwd = typeof options.cwd === "string" && options.cwd ? options.cwd : process.cwd();
+  let argv;
+
+  let promptViaStdin = true;
+  let launch = null;
+  if (cli === "claude") {
+    argv = ["claude", ["-p", "--output-format", "stream-json", "--verbose"]];
+    if (sessionRef) argv[1].push("--resume", sessionRef);
+    if (options.permission_mode) argv[1].push("--permission-mode", String(options.permission_mode));
+    if (options.model) argv[1].push("--model", String(options.model));
+  } else if (cli === "codex") {
+    argv = ["codex", ["exec", "--json", "-"]];
+    if (sessionRef) argv = ["codex", ["exec", "resume", sessionRef, "--json", "-"]];
+    if (options.sandbox_mode) argv[1].push("--sandbox", String(options.sandbox_mode));
+    if (options.model) argv[1].push("--model", String(options.model));
+  } else if (cli === "opencode" || cli === "codefree-o") {
+    // codefree-o 为 OpenCode 同源发行版，CLI 面兼容，复用同一解析器。
+    const runArgs = ["run", "--format", "json"];
+    if (sessionRef) runArgs.push("--session", sessionRef);
+    // codefree-o 与 opencode 同源支持 --auto：远程 bridge 无交互终端，权限确认无法通过，
+    // 敏感工具调用（读文件/执行命令）会被自动拒绝。未显式配置时默认启用 auto
+    //（--auto 只自动批准"未显式拒绝"的权限，设备本地显式 deny 的规则仍然生效）。
+    if (options.permission_mode !== "default") runArgs.push("--auto");
+    if (options.model) runArgs.push("--model", String(options.model));
+    // 注意参数顺序：--file 是可变长参数（--file a b c），若放在 prompt 之前会把 prompt 吞成文件值，
+    // 因此 prompt（位置参数 message）必须紧跟子命令，--file 选项放在其后。
+    runArgs.push(PROMPT_TOKEN);
+    for (const f of message._localFiles || []) {
+      // md 转换版在前：codefree-o/opencode 按顺序读取 --file，优先读到可读的 md 内容；
+      // 原始二进制（docx/pdf）读取会报 UnknownError，CLI 通常继续处理后续文件。
+      if (f.mdLocalPath) runArgs.push("--file", f.mdLocalPath);
+      runArgs.push("--file", f.localPath);
+    }
+    launch = launchCli(cli, runArgs, prompt, requestId);
+    promptViaStdin = false;
+  } else if (cli === "cursor") {
+    // Cursor CLI：-p 非交互模式；permission_mode=force 允许直接改文件，plan 仅规划。
+    const args = ["-p", "--output-format", "stream-json"];
+    if (sessionRef) args.push("--resume", sessionRef);
+    if (options.permission_mode === "force") args.push("--force");
+    else if (options.permission_mode === "plan") args.push("--plan");
+    if (options.model) args.push("--model", String(options.model));
+    args.push(PROMPT_TOKEN);
+    launch = launchCli(cursorBinary, args, prompt, requestId);
+    promptViaStdin = false;
+  } else if (cli === "gemini" || cli === "qwen" || cli === "iflow") {
+    // Gemini CLI 及其同源 fork（Qwen Code / iFlow CLI）。
+    const args = ["-p", PROMPT_TOKEN, "--output-format", "stream-json"];
+    if (options.model) args.push("--model", String(options.model));
+    launch = launchCli(cli, args, prompt, requestId);
+    promptViaStdin = false;
+  } else {
+    session.finish("failed", `不支持的 CLI 类型: ${cli}`);
+    return session;
+  }
+  if (launch) {
+    argv = launch.argv;
+    session.promptFile = launch.promptFile;
+  }
+
+  const [cmd, cmdArgs] = argv;
+  console.log(`[bridge] 启动 CLI: ${cmd} ${cmdArgs.join(" ").slice(0, 800)}`);
+  let child;
+  try {
+    child = spawn(cmd, cmdArgs, {
+      cwd,
+      shell: process.platform === "win32",
+      windowsHide: true,
+      env: { ...process.env },
+    });
+  } catch (err) {
+    session.finish("failed", `无法启动 ${cmd}: ${err.message}`);
+    return session;
+  }
+  session.child = child;
+
+  const opencodeLike = cli === "opencode" || cli === "codefree-o";
+  const handler = cli === "claude" ? handleClaudeLine
+    : cli === "codex" ? handleCodexLine
+      : cli === "cursor" ? handleCursorLine
+        : (cli === "gemini" || cli === "qwen" || cli === "iflow") ? handleGeminiLine
+          : (session, obj, rawLine) => {
+            // OpenCode / codefree-o：JSON 事件宽松解析；非 JSON 行按纯文本兜底（不支持 --format json 的版本）。
+            if (obj) handleOpencodeLine(session, obj);
+            else if (opencodeLike && rawLine && rawLine.trim()) session.emitText(rawLine + "\n");
+          };
+  let stdoutBuf = "";
+  child.stdout.setEncoding("utf8");
+  child.stdout.on("data", (chunk) => {
+    stdoutBuf += chunk;
+    let idx;
+    while ((idx = stdoutBuf.indexOf("\n")) >= 0) {
+      const line = stdoutBuf.slice(0, idx);
+      stdoutBuf = stdoutBuf.slice(idx + 1);
+      // 诊断日志：前 3 行原始输出，便于排查 CLI 事件格式差异
+      session._rawLineCount = (session._rawLineCount || 0) + 1;
+      if (session._rawLineCount <= 3) {
+        console.log(`[bridge][cli stdout #${session._rawLineCount}] ${line.slice(0, 240)}`);
+      }
+      handler(session, safeJsonLine(line), line);
+    }
+  });
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk) => {
+    for (const line of chunk.split(/\r?\n/)) {
+      if (line.trim()) session.stderrTail.push(line.trim());
+    }
+    if (session.stderrTail.length > 20) session.stderrTail.splice(0, session.stderrTail.length - 20);
+  });
+
+  child.on("error", (err) => session.finish("failed", `进程启动失败: ${err.message}`));
+  child.on("close", (code, signal) => {
+    console.log(`[bridge] CLI 退出: code=${code} signal=${signal || "-"} 输出行=${session._rawLineCount || 0}`);
+    if (session.promptFile) {
+      try { fs.unlinkSync(session.promptFile); } catch {}
+    }
+    // 附件目录按 CLI 会话保留（迁移到会话 id 键下，供续接轮复用），不再任务结束即删；
+    // 孤儿目录由 cleanupStaleFileDirs 按 TTL 回收。
+    session.migrateFileDirToSession();
+    if (session.finished) return;
+    if (session.cancelled || signal) {
+      session.finish("cancelled", session.cancelled ? "任务被取消" : `进程被信号终止: ${signal}`);
+    } else if (code === 0) {
+      flushCliErrorTools(session);
+      session.emitUsage(session.usage);
+      session.finish("completed");
+    } else if (session.textParts.length > 0 && session._rawLineCount > (session._lastErrLine || 0)) {
+      // 局部错误容忍：CLI（如 codefree-o 读二进制 --file 失败）报错后仍继续执行并产出回复，
+      // 退出码非 0 只是局部失败的外显 —— 按完成收尾，错误以工具块展示，不全局判失败。
+      // 若 error 后 CLI 无任何后续输出（认证失败/崩溃等致命错误），仍走 failed 分支。
+      flushCliErrorTools(session);
+      session.emitUsage(session.usage);
+      session.finish("completed");
+    } else {
+      const tail = session.cliError || session.stderrTail.slice(-3).join(" | ");
+      session.finish("failed", `CLI 退出码 ${code}${tail ? `: ${tail}` : ""}`);
+    }
+  });
+
+  // claude / codex 的 prompt 走 stdin，避免 shell 引号转义问题；opencode 系的 prompt 已在启动参数中。
+  // 注意：无论哪种方式都必须关闭 stdin —— Windows 下 npm 的 .ps1 shim 会把父进程 stdin
+  // 通过 $input 管道接给 CLI，若不关闭，CLI 会一直等待 EOF 而挂起（表现为收到任务但无任何返回）。
+  try {
+    if (promptViaStdin) {
+      child.stdin.write(prompt);
+    }
+    child.stdin.end();
+  } catch {}
+
+  if (timeoutSeconds > 0) {
+    session.timer = setTimeout(() => {
+      session.kill();
+      session.finish("failed", `执行超时（${timeoutSeconds}s），进程已终止`);
+    }, timeoutSeconds * 1000);
+  }
+
+  return session;
+}
+
+// ---------------------------------------------------------------------------
+// WebSocket 连接管理（反连 + 指数退避重连）
+// ---------------------------------------------------------------------------
+
+let ws = null;
+let heartbeatTimer = null;
+let reconnectAttempt = 0;
+let shuttingDown = false;
+let platformName = ""; // 鉴权 ready 时由平台下发（status 展示用）
+const activeSessions = new Map(); // request_id -> Session
+// 设备并发任务上限：不同会话的任务可并行（CLI 会话级互斥另有限制）
+const MAX_CONCURRENT_SESSIONS = 3;
+
+function send(payload) {
+  if (ws && ws.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify(payload));
+  }
+}
+
+function scheduleReconnect() {
+  if (shuttingDown) return;
+  const delay = Math.min(RECONNECT_BASE_MS * 2 ** reconnectAttempt, RECONNECT_MAX_MS);
+  reconnectAttempt += 1;
+  console.log(`[bridge] ${delay / 1000}s 后重连（第 ${reconnectAttempt} 次）...`);
+  setTimeout(connect, delay);
+}
+
+function startHeartbeat() {
+  stopHeartbeat();
+  heartbeatTimer = setInterval(() => send({ type: "heartbeat" }), HEARTBEAT_INTERVAL_MS);
+}
+
+function stopHeartbeat() {
+  if (heartbeatTimer) {
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
+  }
+}
+
+async function connect() {
+  const url = `${SERVER}${SERVER.includes("?") ? "&" : "?"}token=${encodeURIComponent(TOKEN)}`;
+  console.log(`[bridge] 连接平台: ${SERVER}`);
+  const socket = new WebSocket(url, { maxPayload: 16 * 1024 * 1024 });
+  ws = socket;
+
+  socket.on("open", async () => {
+    reconnectAttempt = 0;
+    console.log("[bridge] 连接已建立，等待平台鉴权...");
+  });
+
+  socket.on("message", async (data) => {
+    let message;
+    try {
+      message = JSON.parse(data.toString());
+    } catch {
+      return;
+    }
+    if (message.type === "ready") {
+      platformName = message.platform_name || "";
+      console.log(`[bridge] 鉴权通过（device_id=${message.device_id}），上报本机能力...`);
+      const capabilities = await detectCapabilities();
+      for (const cap of capabilities) {
+        console.log(`[bridge]   ${cap.cli}: ${cap.available ? `可用 (${cap.version})` : "未安装"}`);
+      }
+      send({ type: "register", capabilities });
+      startHeartbeat();
+    } else if (message.type === "registered") {
+      console.log("[bridge] 能力注册完成，等待任务下发");
+    } else if (message.type === "execute") {
+      // 并发模型：CLI 会话级互斥（同 session_ref 串行）+ 设备并发总量上限；
+      // 不同会话的任务各自独立 CLI 会话，可并行。
+      const sessionConflict = message.session_ref
+        && [...activeSessions.values()].some((s) => s.sessionRef === message.session_ref);
+      if (sessionConflict) {
+        send({
+          type: "result",
+          request_id: message.request_id,
+          status: "failed",
+          error: "该 CLI 会话正在被其他任务使用，请稍后再试",
+        });
+        return;
+      }
+      if (activeSessions.size >= MAX_CONCURRENT_SESSIONS) {
+        send({
+          type: "result",
+          request_id: message.request_id,
+          status: "failed",
+          error: `设备并发任务数已达上限（${MAX_CONCURRENT_SESSIONS}），请稍后再试`,
+        });
+        return;
+      }
+      console.log(`[bridge] 收到任务 ${message.request_id.slice(0, 8)} cli=${message.cli}`);
+      // 用户附件：先从平台下载到本地临时目录，随后以 --file（opencode 系）
+      // 或 prompt 路径注记（其他 CLI）传给 CLI
+      let effectiveMessage = message;
+      if (Array.isArray(message.options?.files) && message.options.files.length) {
+        const download = await downloadAttachments(message);
+        if (download.error) {
+          send({ type: "result", request_id: message.request_id, status: "failed", error: download.error });
+          return;
+        }
+        console.log(`[bridge] 已下载 ${download.files.length} 个附件`);
+        effectiveMessage = {
+          ...message,
+          _localFiles: download.files,
+          _fileDir: download.dir,
+          prompt: ["claude", "codex", "gemini", "qwen", "iflow", "cursor"].includes(message.cli)
+            ? message.prompt + download.promptNote
+            : message.prompt,
+        };
+      }
+      const session = startSession(effectiveMessage);
+      if (effectiveMessage._fileDir) session.fileDir = effectiveMessage._fileDir;
+      activeSessions.set(message.request_id, session);
+    } else if (message.type === "cancel") {
+      const session = activeSessions.get(message.request_id);
+      if (session) {
+        console.log(`[bridge] 取消任务 ${message.request_id.slice(0, 8)}`);
+        session.kill();
+      }
+    } else if (message.type === "error") {
+      console.error(`[bridge] 平台错误: ${message.code} ${message.message}`);
+      if (message.code === "BRIDGE_AUTH_FAILED") process.exit(1);
+    }
+  });
+
+  socket.on("close", () => {
+    stopHeartbeat();
+    for (const session of activeSessions.values()) session.kill();
+    activeSessions.clear();
+    if (!shuttingDown) scheduleReconnect();
+  });
+
+  socket.on("error", (err) => {
+    console.error(`[bridge] 连接错误: ${err.message}`);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Daemon 控制面：本地回环 HTTP（Bearer token 鉴权），支撑 status/stop/配置投递
+// ---------------------------------------------------------------------------
+
+let ctlToken = "";
+let ctlServer = null;
+let logStream = null;
+let logDate = "";
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    let data = "";
+    req.on("data", (c) => (data += c));
+    req.on("end", () => resolve(data));
+    req.on("error", () => resolve(""));
+  });
+}
+
+/** daemon 模式下 console 重定向到按天滚动日志文件（前台模式不启用）。 */
+function initDaemonLogging() {
+  const origLog = console.log.bind(console);
+  const origErr = console.error.bind(console);
+  const origWarn = console.warn.bind(console);
+  const write = (level, parts) => {
+    try {
+      const today = new Date().toISOString().slice(0, 10);
+      if (today !== logDate || !logStream) {
+        if (logStream) logStream.end();
+        fs.mkdirSync(LOGS_DIR, { recursive: true });
+        logStream = fs.createWriteStream(todayLogFile(), { flags: "a" });
+        logDate = today;
+      }
+      logStream.write(`[${new Date().toISOString()}] [${level}] ${parts.map(String).join(" ")}\n`);
+    } catch {}
+  };
+  console.log = (...p) => { origLog(...p); write("INFO", p); };
+  console.error = (...p) => { origErr(...p); write("ERROR", p); };
+  console.warn = (...p) => { origWarn(...p); write("WARN", p); };
+}
+
+function startControlServer() {
+  return new Promise((resolve, reject) => {
+    ctlToken = crypto.randomBytes(32).toString("hex");
+    ctlServer = http.createServer(async (req, res) => {
+      if (String(req.headers.authorization || "") !== `Bearer ${ctlToken}`) {
+        res.writeHead(401).end();
+        return;
+      }
+      if (req.url === "/status" && req.method === "GET") {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({
+          pid: process.pid,
+          version: BRIDGE_VERSION,
+          platform: ws && ws.readyState === WebSocket.OPEN ? "connected" : "disconnected",
+          platform_name: platformName,
+          server: SERVER,
+          active_tasks: activeSessions.size,
+          uptime_s: Math.floor(process.uptime()),
+        }));
+      } else if (req.url === "/stop" && req.method === "POST") {
+        res.writeHead(200).end('{"ok":true}');
+        setTimeout(shutdown, 100);
+      } else if (req.url === "/connect" && req.method === "POST") {
+        // pair 语义：向运行中的 daemon 投递（可能更新的）连接配置；变更时重拨
+        try {
+          const cfg = JSON.parse((await readBody(req)) || "{}");
+          if (!cfg.server || !cfg.token) {
+            res.writeHead(400).end(JSON.stringify({ error: "server/token 缺失" }));
+            return;
+          }
+          const changed = cfg.server !== SERVER || cfg.token !== TOKEN;
+          SERVER = cfg.server;
+          TOKEN = cfg.token;
+          persistConfig(SERVER, TOKEN);
+          if (changed && ws) {
+            try { ws.close(); } catch {}
+          }
+          res.writeHead(200).end(JSON.stringify({ ok: true, connected: !!(ws && ws.readyState === WebSocket.OPEN) }));
+        } catch (err) {
+          res.writeHead(400).end(JSON.stringify({ error: err.message }));
+        }
+      } else {
+        res.writeHead(404).end();
+      }
+    });
+    // 只监听回环地址：控制面不对局域网暴露
+    ctlServer.on("error", reject);
+    ctlServer.listen(0, "127.0.0.1", () => resolve(ctlServer.address().port));
+  });
+}
+
+function writeCtlFiles(port) {
+  fs.mkdirSync(STATE_DIR, { recursive: true });
+  fs.writeFileSync(PID_FILE, String(process.pid), { mode: 0o600 });
+  fs.writeFileSync(PORT_FILE, String(port), { mode: 0o600 });
+  fs.writeFileSync(CTL_TOKEN_FILE, ctlToken, { mode: 0o600 });
+}
+
+function shutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  for (const session of activeSessions.values()) session.kill();
+  if (ws) { try { ws.close(); } catch {} }
+  removeCtlFiles();
+  if (ctlServer) { try { ctlServer.close(); } catch {} }
+  if (logStream) { try { logStream.end(); } catch {} }
+  setTimeout(() => process.exit(0), 200);
+}
+
+// ---------------------------------------------------------------------------
+// 子命令实现
+// ---------------------------------------------------------------------------
+
+/** daemon 主流程：写控制面文件 + 启动日志 + 连接平台（由 connect 拉起或 --foreground 内联运行）。 */
+async function daemonMain() {
+  SERVER = args.server || process.env.AI_LAB_BRIDGE_SERVER || SERVER;
+  TOKEN = args.token || process.env.AI_LAB_BRIDGE_TOKEN || TOKEN;
+  if (!SERVER || !TOKEN) {
+    console.error("[bridge] 后台进程缺少连接参数");
+    process.exit(1);
+  }
+  persistConfig(SERVER, TOKEN);
+  const foreground = !!args.foreground;
+  if (!foreground) initDaemonLogging();
+  // 启动即清理过期附件目录，并按 6 小时周期回收孤儿会话目录（TTL 24h）
+  cleanupStaleFileDirs();
+  setInterval(cleanupStaleFileDirs, 6 * 60 * 60 * 1000).unref();
+  const port = await startControlServer();
+  writeCtlFiles(port);
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  try { process.on("SIGHUP", shutdown); } catch {}
+  if (!foreground) {
+    console.log(`[bridge] 后台进程已启动 v${BRIDGE_VERSION}（pid=${process.pid}，控制端口=${port}）`);
+    console.log(`[bridge] 日志文件: ${todayLogFile()}`);
+  }
+  connect();
+}
+
+/** connect：解析配置 → 复用或拉起后台 daemon → 等待就绪。 */
+async function cmdConnect() {
+  const persisted = loadPersistedConfig();
+  SERVER = args.server || process.env.AI_LAB_BRIDGE_SERVER || (persisted && persisted.server) || "";
+  TOKEN = args.token || process.env.AI_LAB_BRIDGE_TOKEN || (persisted && persisted.token) || "";
+  if (!SERVER || !TOKEN) {
+    console.error("[bridge] 未找到已保存的连接配置，请使用创建设备时平台提供的完整命令执行一次。");
+    printUsage();
+    process.exit(1);
+  }
+  persistConfig(SERVER, TOKEN);
+
+  if (args.foreground) {
+    await daemonMain();
+    return;
+  }
+
+  // 已有 daemon 在跑：投递配置（可能更新 server/token）并复用，不重复拉起
+  const ctl = readCtlState();
+  if (ctl && isPidAlive(ctl.pid)) {
+    try {
+      const statusRes = await fetch(`http://127.0.0.1:${ctl.port}/status`, {
+        headers: { authorization: `Bearer ${ctl.ctlToken}` },
+      });
+      const running = await statusRes.json();
+      const res = await fetch(`http://127.0.0.1:${ctl.port}/connect`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${ctl.ctlToken}`, "content-type": "application/json" },
+        body: JSON.stringify({ server: SERVER, token: TOKEN }),
+      });
+      const data = await res.json();
+      console.log(`[bridge] 后台进程已运行（pid=${ctl.pid}${running.version ? `，v${running.version}` : ""}），配置已投递并复用。`);
+      if (running.version && BRIDGE_VERSION && running.version !== BRIDGE_VERSION) {
+        console.log(`[bridge] 提示: 后台进程为 v${running.version}，本次拉起的是 v${BRIDGE_VERSION}。`);
+        console.log("[bridge] 如需升级请执行: npx -y ai-lab-bridge stop && npx -y ai-lab-bridge connect");
+      }
+      console.log(`[bridge] 平台连接: ${data.connected ? "在线" : "连接中（断线自动重连）"}`);
+      console.log("[bridge] 查看状态: npx -y ai-lab-bridge status    停止: npx -y ai-lab-bridge stop");
+      return;
+    } catch {
+      // 控制面不可达（进程僵死等），清理残留文件后重新拉起
+      removeCtlFiles();
+    }
+  }
+
+  // 分离式拉起 daemon：脱离终端，父进程退出后继续运行
+  const child = spawn(process.execPath, [__filename, "--daemon"], {
+    detached: true,
+    stdio: "ignore",
+    env: { ...process.env, AI_LAB_BRIDGE_SERVER: SERVER, AI_LAB_BRIDGE_TOKEN: TOKEN },
+    windowsHide: true,
+  });
+  child.unref();
+  console.log(`[bridge] 正在启动后台进程 v${BRIDGE_VERSION} (pid=${child.pid})...`);
+  const ok = await waitForDaemonReady(child.pid, 15000);
+  if (ok) {
+    console.log("[bridge] 后台运行中，本终端可以关闭。");
+    console.log(`[bridge] 平台地址: ${SERVER}`);
+    console.log("[bridge] 查看状态: npx -y ai-lab-bridge status    停止: npx -y ai-lab-bridge stop");
+    console.log(`[bridge] 日志文件: ${todayLogFile()}`);
+  } else {
+    console.error("[bridge] 后台进程启动超时，请用 connect --foreground 在前台查看日志排查。");
+    process.exit(1);
+  }
+}
+
+async function waitForDaemonReady(pid, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const ctl = readCtlState();
+    if (ctl && ctl.pid === pid) {
+      try {
+        const res = await fetch(`http://127.0.0.1:${ctl.port}/status`, {
+          headers: { authorization: `Bearer ${ctl.ctlToken}` },
+        });
+        if (res.ok) return true;
+      } catch {}
+    }
+    await new Promise((r) => setTimeout(r, 300));
+  }
+  return false;
+}
+
+/** 将秒数格式化为人类可读时长，如 "3小时47分"、"2天5小时"、"45秒"。 */
+function formatDuration(totalSeconds) {
+  const s = Math.max(0, Math.floor(totalSeconds));
+  const days = Math.floor(s / 86400);
+  const hours = Math.floor((s % 86400) / 3600);
+  const minutes = Math.floor((s % 3600) / 60);
+  const seconds = s % 60;
+  if (days > 0) return `${days}天${hours}小时`;
+  if (hours > 0) return `${hours}小时${minutes}分`;
+  if (minutes > 0) return `${minutes}分${seconds}秒`;
+  return `${seconds}秒`;
+}
+
+async function cmdStatus() {
+  const ctl = readCtlState();
+  if (!ctl || !isPidAlive(ctl.pid)) {
+    console.log("[bridge] 后台进程未运行。执行 npx -y ai-lab-bridge connect 启动。");
+    return;
+  }
+  try {
+    const res = await fetch(`http://127.0.0.1:${ctl.port}/status`, {
+      headers: { authorization: `Bearer ${ctl.ctlToken}` },
+    });
+    const s = await res.json();
+    console.log(`[bridge] 后台进程 v${s.version || "?"}（pid=${s.pid}）已运行 ${formatDuration(s.uptime_s)}`);
+    if (s.platform_name) console.log(`[bridge] 平台: ${s.platform_name}`);
+    console.log(`[bridge] 平台地址: ${s.server}`);
+    console.log(`[bridge] 连接状态: ${s.platform === "connected" ? "在线" : "连接中/断线（自动重连）"}`);
+    console.log(`[bridge] 执行中任务: ${s.active_tasks}`);
+    if (s.version && BRIDGE_VERSION && s.version !== BRIDGE_VERSION) {
+      console.log(`[bridge] ⚠ 版本不一致: 后台进程 v${s.version}，本命令 v${BRIDGE_VERSION}。`);
+      console.log("[bridge] 升级到最新版: npx -y ai-lab-bridge stop && npx -y ai-lab-bridge connect");
+    }
+  } catch (err) {
+    console.error(`[bridge] 状态查询失败: ${err.message}`);
+  }
+}
+
+async function cmdStop() {
+  const ctl = readCtlState();
+  if (!ctl || !isPidAlive(ctl.pid)) {
+    removeCtlFiles();
+    console.log("[bridge] 后台进程未运行。");
+    return;
+  }
+  try {
+    await fetch(`http://127.0.0.1:${ctl.port}/stop`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${ctl.ctlToken}` },
+    });
+  } catch {}
+  const deadline = Date.now() + 5000;
+  while (Date.now() < deadline && isPidAlive(ctl.pid)) {
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  if (isPidAlive(ctl.pid)) {
+    // 优雅退出超时，强杀兜底
+    try {
+      if (process.platform === "win32") {
+        spawnSync("taskkill", ["/pid", String(ctl.pid), "/T", "/F"], { windowsHide: true });
+      } else {
+        process.kill(ctl.pid, "SIGKILL");
+      }
+    } catch {}
+  }
+  removeCtlFiles();
+  console.log(`[bridge] 后台进程已停止 (pid=${ctl.pid})`);
+}
+
+// ---------------------------------------------------------------------------
+// 命令分发
+// ---------------------------------------------------------------------------
+
+(async () => {
+  if (args.version || args.v || SUBCOMMAND === "version" || SUBCOMMAND === "-v") {
+    console.log(`ai-lab-bridge v${BRIDGE_VERSION || "(未知，package.json 缺失)"}`);
+    return;
+  }
+  if (args.daemon) return daemonMain();
+  switch (SUBCOMMAND) {
+    case "connect": return cmdConnect();
+    case "status": return cmdStatus();
+    case "stop": return cmdStop();
+    case "help": case "--help": case "-h": printUsage(); return;
+    default:
+      console.error(`未知命令: ${SUBCOMMAND}`);
+      printUsage();
+      process.exit(1);
+  }
+})();