@licity/qclaw-local-connector 1.1.0

package/index.js

@@ -0,0 +1,986 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const net = require('net');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execFile, spawn } = require('child_process');
+const readline = require('readline');
+const { promisify } = require('util');
+const qrcode = require('qrcode-terminal');
+
+// 优先从运行目录加载 .env（全局安装时从 CWD），否则从安装包目录加载
+const envFromCwd = path.join(process.cwd(), '.env');
+const envFromPkg = path.join(__dirname, '.env');
+require('dotenv').config({ path: fs.existsSync(envFromCwd) ? envFromCwd : envFromPkg });
+
+const pkg = require('./package.json');
+
+const apiBaseUrl = String(process.env.LICITY_API_BASE_URL || 'https://li.city').replace(/\/$/, '');
+const connectorKey = String(process.env.OPENCLAW_CONNECTOR_SECRET || '').trim();
+const provider = String(process.env.CONNECTOR_PROVIDER || 'qclaw-local').trim();
+const deviceName = String(process.env.DEVICE_NAME || os.hostname()).trim();
+const qclawPath = String(process.env.QCLAW_PATH || 'D:\\QClaw\\QClaw.exe').trim();
+const qclawInstallDir = path.dirname(qclawPath);
+const qclawCliWrapperPath = path.join(qclawInstallDir, 'resources', 'openclaw', 'config', 'skills', 'qclaw-openclaw', 'scripts', 'openclaw-win.cmd');
+const qclawStateDir = String(process.env.QCLAW_STATE_DIR || path.join(os.homedir(), '.qclaw')).trim();
+const qclawConfigPath = String(process.env.QCLAW_CONFIG_PATH || path.join(qclawStateDir, 'qclaw.json')).trim();
+const openclawConfigPath = String(process.env.OPENCLAW_CONFIG_PATH || path.join(qclawStateDir, 'openclaw.json')).trim();
+const openclawCliPath = String(process.env.OPENCLAW_CLI_PATH || path.join(qclawInstallDir, 'resources', 'openclaw', 'node_modules', 'openclaw', 'openclaw.mjs')).trim();
+const openclawAgentId = String(process.env.OPENCLAW_AGENT_ID || 'main').trim();
+const openclawCommandTimeoutMs = Number(process.env.OPENCLAW_COMMAND_TIMEOUT_MS || 60000);
+const heartbeatIntervalMs = Number(process.env.HEARTBEAT_INTERVAL_MS || 25000);
+const pollIntervalMs = Number(process.env.POLL_INTERVAL_MS || 3000);
+const maxEmbeddedMediaBytes = Number(process.env.MAX_EMBEDDED_MEDIA_BYTES || 8 * 1024 * 1024);
+const capabilityScopes = String(process.env.CAPABILITY_SCOPES || 'private_chat,neighbor,anchor,time_travel')
+  .split(',')
+  .map((item) => item.trim())
+  .filter(Boolean);
+const execFileAsync = promisify(execFile);
+
+if (!connectorKey) {
+  console.error('缺少 OPENCLAW_CONNECTOR_SECRET，无法启动本地 Connector。');
+  process.exit(1);
+}
+
+const state = {
+  shouldRun: true,
+  reconnectRequested: false,
+  mode: 'idle',
+  currentSessionId: null,
+  currentLobster: null,
+  heartbeatCount: 0,
+};
+
+// 全局安装时数据目录在运行目录下，本地开发时在包目录的 data/
+const isGlobalInstall = path.resolve(process.cwd()) !== path.resolve(__dirname);
+const dataDir = isGlobalInstall
+  ? path.join(process.cwd(), '.licity-connector')
+  : path.join(__dirname, 'data');
+const runtimeFile = path.join(dataDir, 'runtime.json');
+
+function ensureRuntimeId() {
+  fs.mkdirSync(dataDir, { recursive: true });
+
+  if (fs.existsSync(runtimeFile)) {
+    try {
+      const saved = JSON.parse(fs.readFileSync(runtimeFile, 'utf8'));
+      if (saved && typeof saved.runtimeId === 'string' && saved.runtimeId.trim()) {
+        return saved.runtimeId.trim();
+      }
+    } catch (error) {
+      console.warn('读取本地 runtime.json 失败，将重新生成 runtimeId。');
+    }
+  }
+
+  const runtimeId = crypto.randomUUID();
+  fs.writeFileSync(runtimeFile, JSON.stringify({ runtimeId, createdAt: new Date().toISOString() }, null, 2));
+  return runtimeId;
+}
+
+const runtimeId = ensureRuntimeId();
+const screenshotDir = path.join(dataDir, 'screenshots');
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function readJsonFileIfExists(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    console.warn(`读取 JSON 配置失败: ${filePath}`);
+    return null;
+  }
+}
+
+function toWebSocketUrl(rawUrl) {
+  const source = String(rawUrl || '').trim();
+  if (!source) return '';
+  if (source.startsWith('https://')) {
+    return `wss://${source.slice('https://'.length)}`;
+  }
+  if (source.startsWith('http://')) {
+    return `ws://${source.slice('http://'.length)}`;
+  }
+  return source;
+}
+
+function buildOpenClawChildEnv() {
+  const qclawConfig = readJsonFileIfExists(qclawConfigPath) || {};
+  const openclawConfig = readJsonFileIfExists(openclawConfigPath) || {};
+  const qclawGatewayBaseUrl = String(qclawConfig.authGatewayBaseUrl || '').trim();
+  const gatewayToken = String(openclawConfig?.gateway?.auth?.token || '').trim();
+  const modelBaseUrl = String(process.env.QCLAW_LLM_BASE_URL || qclawGatewayBaseUrl).trim();
+  const modelApiKey = String(process.env.QCLAW_LLM_API_KEY || gatewayToken).trim();
+  const wechatWsUrl = String(process.env.QCLAW_WECHAT_WS_URL || toWebSocketUrl(qclawGatewayBaseUrl)).trim();
+
+  return {
+    ...process.env,
+    OPENCLAW_CONFIG_PATH: openclawConfigPath,
+    OPENCLAW_STATE_DIR: qclawStateDir,
+    OPENCLAW_NIX_MODE: '1',
+    NODE_OPTIONS: '--no-warnings',
+    ...(modelBaseUrl ? { QCLAW_LLM_BASE_URL: modelBaseUrl } : {}),
+    ...(modelApiKey ? { QCLAW_LLM_API_KEY: modelApiKey } : {}),
+    ...(wechatWsUrl ? { QCLAW_WECHAT_WS_URL: wechatWsUrl } : {}),
+  };
+}
+
+function parseLoopbackPort(rawUrl) {
+  try {
+    const parsed = new URL(String(rawUrl || '').trim());
+    const host = String(parsed.hostname || '').toLowerCase();
+    if (!['127.0.0.1', 'localhost'].includes(host)) return null;
+    return Number(parsed.port || (parsed.protocol === 'https:' || parsed.protocol === 'wss:' ? 443 : 80));
+  } catch (error) {
+    return null;
+  }
+}
+
+function probeTcpPort(port, timeoutMs = 1500) {
+  return new Promise((resolve) => {
+    if (!port) {
+      resolve(false);
+      return;
+    }
+
+    const socket = new net.Socket();
+    let settled = false;
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(result);
+    };
+
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => finish(true));
+    socket.once('timeout', () => finish(false));
+    socket.once('error', () => finish(false));
+    socket.connect(port, '127.0.0.1');
+  });
+}
+
+async function probeGatewayAccess(baseUrl, apiKey) {
+  const source = String(baseUrl || '').replace(/\/$/, '').trim();
+  if (!source) {
+    return { ok: false, status: 0, message: '未配置模型网关地址' };
+  }
+
+  try {
+    const response = await fetch(`${source}/models`, {
+      method: 'GET',
+      headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
+    });
+    const rawText = await response.text();
+    let parsed = null;
+    try {
+      parsed = rawText ? JSON.parse(rawText) : null;
+    } catch (error) {
+      parsed = null;
+    }
+
+    if (response.ok) {
+      return {
+        ok: true,
+        status: response.status,
+        message: parsed?.data?.length ? `已返回 ${parsed.data.length} 个模型` : '模型网关可访问',
+      };
+    }
+
+    return {
+      ok: false,
+      status: response.status,
+      message: parsed?.error?.message || parsed?.message || rawText || `HTTP ${response.status}`,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      status: 0,
+      message: error.message || '探测模型网关失败',
+    };
+  }
+}
+
+async function runPreflightChecks() {
+  const childEnv = buildOpenClawChildEnv();
+  const modelBaseUrl = String(childEnv.QCLAW_LLM_BASE_URL || '').trim();
+  const modelApiKey = String(childEnv.QCLAW_LLM_API_KEY || '').trim();
+  const wsUrl = String(childEnv.QCLAW_WECHAT_WS_URL || '').trim();
+  const modelPort = parseLoopbackPort(modelBaseUrl);
+  const wsPort = parseLoopbackPort(wsUrl);
+  const gatewayProbe = modelPort ? await probeGatewayAccess(modelBaseUrl, modelApiKey) : { ok: false, status: 0, message: '未执行探测' };
+
+  return {
+    openclawConfigExists: fs.existsSync(openclawConfigPath),
+    openclawCliExists: fs.existsSync(openclawCliPath),
+    modelBaseUrl,
+    modelApiKey,
+    wsUrl,
+    modelPort,
+    wsPort,
+    modelPortReady: modelPort ? await probeTcpPort(modelPort) : null,
+    wsPortReady: wsPort ? await probeTcpPort(wsPort) : null,
+    gatewayProbe,
+  };
+}
+
+async function requestJson(endpoint, options = {}) {
+  const url = `${apiBaseUrl}${endpoint}`;
+  const response = await fetch(url, {
+    method: options.method || 'GET',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-connector-key': connectorKey,
+      ...(options.headers || {}),
+    },
+    body: options.body ? JSON.stringify(options.body) : undefined,
+  });
+
+  const rawText = await response.text();
+  let data = {};
+
+  if (rawText) {
+    try {
+      data = JSON.parse(rawText);
+    } catch (error) {
+      data = { raw: rawText };
+    }
+  }
+
+  if (!response.ok) {
+    const error = new Error(data.error || data.raw || `请求失败: ${response.status}`);
+    error.status = response.status;
+    throw error;
+  }
+
+  return data;
+}
+
+function printBanner() {
+  console.log('========================================');
+  console.log('  里世界 QClaw 本地龙虾 Connector');
+  console.log('========================================');
+  console.log(`API: ${apiBaseUrl}`);
+  console.log(`Provider: ${provider}`);
+  console.log(`Runtime ID: ${runtimeId}`);
+  console.log(`设备名: ${deviceName}`);
+  console.log(`QClaw 路径: ${qclawPath}`);
+  console.log(`OpenClaw 配置: ${openclawConfigPath}`);
+  console.log(`能力域: ${capabilityScopes.join(', ') || '无'}`);
+  console.log('命令: 输入 r 重新生成二维码，输入 s 查看状态，输入 q 退出');
+  console.log('');
+}
+
+function printPreflightResult(preflight) {
+  console.log('启动前检查:');
+  console.log(`- OpenClaw 配置文件: ${preflight.openclawConfigExists ? '已找到' : '未找到'}`);
+  console.log(`- OpenClaw CLI: ${preflight.openclawCliExists ? '已找到' : '未找到'}`);
+  if (preflight.modelBaseUrl) {
+    console.log(`- 模型网关: ${preflight.modelBaseUrl}`);
+    if (preflight.modelPort) {
+      console.log(`  本地端口 ${preflight.modelPort}: ${preflight.modelPortReady ? '已监听' : '未监听'}`);
+    }
+    console.log(`  网关访问: ${preflight.gatewayProbe.ok ? '成功' : '失败'}${preflight.gatewayProbe.message ? ` (${preflight.gatewayProbe.message})` : ''}`);
+  }
+  if (preflight.wsUrl) {
+    console.log(`- 微信通道: ${preflight.wsUrl}`);
+    if (preflight.wsPort) {
+      console.log(`  本地端口 ${preflight.wsPort}: ${preflight.wsPortReady ? '已监听' : '未监听'}`);
+    }
+  }
+  if (preflight.modelPort && !preflight.modelPortReady) {
+    console.log('! 检测到本地模型端口未启动。仅启动连接器不够，还需要先启动 QClaw 主程序并保持其本地网关可用。');
+  }
+  if (preflight.gatewayProbe?.message && String(preflight.gatewayProbe.message).includes('Access denied (PID)')) {
+    console.log('! 当前连接器进程访问 QClaw 模型代理时被本机 PID 策略拒绝。');
+    console.log('! 这说明端口虽然已监听，但普通问答任务仍无法由外部 node 进程真正执行。');
+  }
+  console.log('');
+}
+
+function extractLastJsonObject(rawText) {
+  const source = String(rawText || '').trim();
+  if (!source) return null;
+
+  for (let index = source.lastIndexOf('{'); index >= 0; index = source.lastIndexOf('{', index - 1)) {
+    const candidate = source.slice(index).trim();
+    try {
+      return JSON.parse(candidate);
+    } catch (error) {
+      continue;
+    }
+  }
+
+  return null;
+}
+
+function normalizeAgentReply(result) {
+  const payloads = Array.isArray(result?.result?.payloads) ? result.result.payloads : [];
+  const textParts = payloads
+    .map((payload) => String(payload?.text || '').trim())
+    .filter(Boolean);
+
+  if (textParts.length > 0) {
+    return textParts.join('\n\n');
+  }
+
+  const directReply = [
+    result?.result?.text,
+    result?.result?.output,
+    result?.text,
+    result?.message,
+  ].map((item) => String(item || '').trim()).find(Boolean);
+
+  if (directReply) {
+    return directReply;
+  }
+
+  return '';
+}
+
+function guessMimeTypeFromPath(filePath) {
+  const ext = path.extname(String(filePath || '')).toLowerCase();
+  if (['.jpg', '.jpeg'].includes(ext)) return 'image/jpeg';
+  if (ext === '.png') return 'image/png';
+  if (ext === '.gif') return 'image/gif';
+  if (ext === '.webp') return 'image/webp';
+  if (ext === '.pdf') return 'application/pdf';
+  if (ext === '.zip') return 'application/zip';
+  if (ext === '.json') return 'application/json';
+  if (ext === '.csv') return 'text/csv';
+  if (ext === '.txt') return 'text/plain';
+  if (ext === '.docx') return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+  if (ext === '.xlsx') return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+  return 'application/octet-stream';
+}
+
+function normalizeMediaType(mediaType, mimeType, fileName) {
+  const explicit = String(mediaType || '').toLowerCase().trim();
+  if (['image', 'video', 'file'].includes(explicit)) {
+    return explicit;
+  }
+  const mime = String(mimeType || '').toLowerCase().trim();
+  if (mime.startsWith('image/')) return 'image';
+  if (mime.startsWith('video/')) return 'video';
+  const ext = path.extname(String(fileName || '')).toLowerCase();
+  if (['.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp'].includes(ext)) return 'image';
+  if (['.mp4', '.mov', '.avi', '.mkv', '.webm'].includes(ext)) return 'video';
+  return 'file';
+}
+
+function extractAgentMedia(result) {
+  const payloads = Array.isArray(result?.result?.payloads) ? result.result.payloads : [];
+  for (const payload of payloads) {
+    if (!payload || typeof payload !== 'object') continue;
+
+    const mediaBase64 = payload.media_base64 || payload.mediaBase64 || payload.file_base64 || payload.fileBase64 || null;
+    const localPath = payload.media_file_path || payload.mediaFilePath || payload.file_path || payload.filePath || null;
+    const declaredName = payload.media_name || payload.mediaName || payload.file_name || payload.fileName || null;
+    const declaredMime = payload.media_mime_type || payload.mediaMimeType || payload.mime_type || payload.mimeType || null;
+    const derivedName = declaredName || (localPath ? path.basename(localPath) : 'connector-file');
+    const derivedMime = declaredMime || (localPath ? guessMimeTypeFromPath(localPath) : 'application/octet-stream');
+    const derivedType = normalizeMediaType(payload.media_type || payload.type, derivedMime, derivedName);
+
+    if (mediaBase64) {
+      return {
+        media_base64: mediaBase64,
+        media_type: derivedType,
+        media_mime_type: derivedMime,
+        media_name: derivedName,
+      };
+    }
+
+    if (localPath && fs.existsSync(localPath)) {
+      const stat = fs.statSync(localPath);
+      if (stat.size > maxEmbeddedMediaBytes) {
+        throw new Error(`附件过大，当前仅支持回传 ${Math.floor(maxEmbeddedMediaBytes / 1024 / 1024)}MB 以内文件：${path.basename(localPath)}`);
+      }
+
+      return {
+        media_base64: fs.readFileSync(localPath).toString('base64'),
+        media_type: derivedType,
+        media_mime_type: derivedMime,
+        media_name: derivedName,
+      };
+    }
+  }
+
+  return null;
+}
+
+function parseAgentSuccess(rawStdout) {
+  const parsed = extractLastJsonObject(rawStdout);
+  if (!parsed) {
+    return null;
+  }
+
+  const isSuccess = parsed.status === 'ok' || parsed.ok === true || parsed.success === true || parsed.type === 'result';
+  if (!isSuccess) {
+    return null;
+  }
+
+  const reply = normalizeAgentReply(parsed);
+  let media = null;
+  try {
+    media = extractAgentMedia(parsed);
+  } catch (error) {
+    return {
+      reply: `我已生成附件，但当前附件不能直接回传到里世界。原因：${error.message || '附件处理失败'}。`,
+      media: null,
+      raw: parsed,
+    };
+  }
+  if (!reply && !media) {
+    return null;
+  }
+
+  return {
+    reply,
+    media,
+    raw: parsed,
+  };
+}
+
+async function killProcessTree(pid) {
+  if (!pid) return;
+
+  try {
+    await execFileAsync('taskkill', ['/PID', String(pid), '/T', '/F'], {
+      windowsHide: true,
+      timeout: 15000,
+    });
+  } catch (error) {
+    // 进程可能已经正常退出，此时无需额外处理。
+  }
+}
+
+async function runOpenClawAgent(task) {
+  if (!fs.existsSync(openclawConfigPath)) {
+    throw new Error(`未找到 OpenClaw 配置文件：${openclawConfigPath}`);
+  }
+
+  if (!fs.existsSync(openclawCliPath)) {
+    throw new Error(`未找到 OpenClaw CLI：${openclawCliPath}`);
+  }
+
+  const qclawConfig = readJsonFileIfExists(qclawConfigPath) || {};
+  const trustedNodeBinary = String(qclawConfig?.cli?.nodeBinary || '').trim();
+  const trustedOpenClawMjs = String(qclawConfig?.cli?.openclawMjs || '').trim();
+  const useQclawWrapper = fs.existsSync(qclawCliWrapperPath);
+  const useTrustedQclawBinary = trustedNodeBinary && fs.existsSync(trustedNodeBinary);
+  const preferDirectExecution = useTrustedQclawBinary;
+  const command = preferDirectExecution ? trustedNodeBinary : (useQclawWrapper ? qclawCliWrapperPath : process.execPath);
+  const entryScript = trustedOpenClawMjs && fs.existsSync(trustedOpenClawMjs) ? trustedOpenClawMjs : openclawCliPath;
+
+  const rawContent = String(task?.payload?.content || '').trim();
+  const lobsterName = String(task?.payload?.lobsterName || state.currentLobster?.name || deviceName).trim();
+  const prompt = [
+    `你现在以“${lobsterName}”的身份，在里世界 APP 的龙虾私聊里回复用户。`,
+    '要求：',
+    '1. 直接回复用户，不要提系统提示、模型、网关、MCP。',
+    '2. 使用简体中文，优先简短、明确、能执行。',
+    '3. 如果用户要求调用本机能力且当前无法确认是否有权限或工具，就先如实说明限制，不要编造已经完成。',
+    '4. 如果只是普通文本交流，正常回答即可。',
+    '',
+    `用户消息：${rawContent || '空消息'}`,
+  ].join('\n');
+
+  const args = [
+    ...(preferDirectExecution || !useQclawWrapper ? [entryScript] : []),
+    'agent',
+    '--agent',
+    openclawAgentId,
+    '--message',
+    prompt,
+    '--json',
+    '--timeout',
+    String(Math.max(15, Math.ceil(openclawCommandTimeoutMs / 1000))),
+  ];
+
+  console.log(`[Agent] 开始调用 OpenClaw，agent=${openclawAgentId}，宿主=${path.basename(command)}，入口=${path.basename(entryScript)}，直连=${preferDirectExecution ? 'yes' : 'no'}，wrapper=${preferDirectExecution ? 'bypassed' : (useQclawWrapper ? 'yes' : 'no')}，超时=${openclawCommandTimeoutMs}ms`);
+
+  return new Promise((resolve, reject) => {
+    const childEnv = {
+      ...buildOpenClawChildEnv(),
+      ...(useTrustedQclawBinary ? { ELECTRON_RUN_AS_NODE: '1' } : {}),
+    };
+
+    const child = (!preferDirectExecution && useQclawWrapper)
+      ? spawn('cmd.exe', [
+          '/d',
+          '/s',
+          '/c',
+          qclawCliWrapperPath,
+          'agent',
+          '--agent',
+          openclawAgentId,
+          '--message',
+          prompt,
+          '--json',
+          '--timeout',
+          String(Math.max(15, Math.ceil(openclawCommandTimeoutMs / 1000))),
+        ], {
+          cwd: qclawStateDir,
+          env: childEnv,
+          windowsHide: true,
+          stdio: ['ignore', 'pipe', 'pipe'],
+        })
+      : spawn(command, args, {
+          cwd: qclawStateDir,
+          env: childEnv,
+          windowsHide: true,
+          stdio: ['ignore', 'pipe', 'pipe'],
+        });
+
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+
+    const finish = async (handler) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      await killProcessTree(child.pid);
+      handler();
+    };
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+      const success = parseAgentSuccess(stdout);
+      if (success) {
+        finish(() => resolve(success));
+      }
+    });
+
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+
+    child.on('error', (error) => {
+      finish(() => reject(error));
+    });
+
+    child.on('close', (code) => {
+      if (settled) return;
+
+      const success = parseAgentSuccess(stdout);
+      if (success) {
+        finish(() => resolve(success));
+        return;
+      }
+
+      const stderrText = String(stderr || '').trim();
+      const stdoutText = String(stdout || '').trim();
+      const fallbackMessage = code === null ? 'OpenClaw 进程异常结束' : `OpenClaw 退出码: ${code}`;
+      if (stderrText) {
+        console.log(`[Agent] stderr: ${stderrText.slice(0, 500)}`);
+      }
+      if (stdoutText) {
+        console.log(`[Agent] stdout: ${stdoutText.slice(0, 500)}`);
+      }
+      finish(() => reject(new Error(stderrText || stdoutText || fallbackMessage || 'OpenClaw 未返回可解析结果')));
+    });
+
+    const timer = setTimeout(() => {
+      const success = parseAgentSuccess(stdout);
+      if (success) {
+        finish(() => resolve(success));
+        return;
+      }
+
+      const stderrText = String(stderr || '').trim();
+      const stdoutText = String(stdout || '').trim();
+      if (stderrText) {
+        console.log(`[Agent] timeout 前 stderr: ${stderrText.slice(0, 500)}`);
+      }
+      if (stdoutText) {
+        console.log(`[Agent] timeout 前 stdout: ${stdoutText.slice(0, 500)}`);
+      }
+      finish(() => reject(new Error(stderrText || stdoutText || `OpenClaw 执行超时（${openclawCommandTimeoutMs}ms）`)));
+    }, openclawCommandTimeoutMs);
+  });
+}
+
+function shouldCaptureDesktop(rawText) {
+  const text = String(rawText || '').trim();
+  if (!text) return false;
+  return /(截图|截屏|截个图|抓图).*(桌面|屏幕|全屏)|帮我截.*(桌面|屏幕|全屏)/.test(text);
+}
+
+async function captureDesktopScreenshot() {
+  ensureDir(screenshotDir);
+  const filePath = path.join(screenshotDir, `desktop-${Date.now()}.png`);
+  const psScript = [
+    'Add-Type -AssemblyName System.Windows.Forms;',
+    'Add-Type -AssemblyName System.Drawing;',
+    '$bounds = [System.Windows.Forms.SystemInformation]::VirtualScreen;',
+    '$bitmap = New-Object System.Drawing.Bitmap $bounds.Width, $bounds.Height;',
+    '$graphics = [System.Drawing.Graphics]::FromImage($bitmap);',
+    '$graphics.CopyFromScreen($bounds.Left, $bounds.Top, 0, 0, $bitmap.Size);',
+    `$bitmap.Save('${filePath.replace(/\\/g, '\\\\')}', [System.Drawing.Imaging.ImageFormat]::Png);`,
+    '$graphics.Dispose();',
+    '$bitmap.Dispose();',
+  ].join(' ');
+
+  await execFileAsync('powershell.exe', ['-NoProfile', '-STA', '-Command', psScript], {
+    windowsHide: true,
+    timeout: 30000,
+  });
+
+  return filePath;
+}
+
+function printQrPayload(payload) {
+  const qrText = JSON.stringify(payload);
+  console.log('请在“里世界”APP里打开扫一扫，扫描下方二维码完成连接。');
+  qrcode.generate(qrText, { small: true });
+  console.log('二维码原文:');
+  console.log(qrText);
+  console.log('');
+}
+
+async function createScanSession() {
+  state.mode = 'creating-session';
+  state.currentSessionId = null;
+  state.currentLobster = null;
+  state.heartbeatCount = 0;
+
+  return requestJson('/api/openclaw/scan-session', {
+    method: 'POST',
+    body: {
+      runtimeId,
+      provider,
+      deviceName,
+      platform: `${os.platform()} ${os.release()}`,
+      version: pkg.version,
+      capabilityScopes,
+      metadata: {
+        connector: 'licity-qclaw-local-connector',
+        nodeVersion: process.version,
+        qclawPath,
+      },
+    },
+  });
+}
+
+async function waitForApproval(sessionId) {
+  state.mode = 'waiting-approval';
+  state.currentSessionId = sessionId;
+
+  while (state.shouldRun && !state.reconnectRequested) {
+    const result = await requestJson(`/api/openclaw/scan-session/${sessionId}`);
+    const session = result.session;
+
+    if (session.status === 'approved') {
+      state.mode = 'connected';
+      state.currentLobster = session.lobster || null;
+      return session;
+    }
+
+    if (session.status === 'expired') {
+      throw new Error('二维码已过期，准备重新生成。');
+    }
+
+    if (session.status === 'rejected') {
+      throw new Error('连接请求已被拒绝，准备重新生成二维码。');
+    }
+
+    await sleep(pollIntervalMs);
+  }
+
+  return null;
+}
+
+async function sendHeartbeat() {
+  const result = await requestJson('/api/openclaw/heartbeat', {
+    method: 'POST',
+    body: {
+      runtimeId,
+      metadata: {
+        connector: 'licity-qclaw-local-connector',
+        qclawPath,
+        heartbeatAt: new Date().toISOString(),
+      },
+    },
+  });
+
+  state.heartbeatCount += 1;
+  state.currentLobster = result.lobster || state.currentLobster;
+  return result;
+}
+
+async function pullNextTask() {
+  return requestJson(`/api/openclaw/tasks/next?runtimeId=${encodeURIComponent(runtimeId)}`);
+}
+
+async function reportTaskResult(taskId, status, result = {}, errorMessage = null) {
+  return requestJson(`/api/openclaw/tasks/${taskId}/result`, {
+    method: 'POST',
+    body: {
+      runtimeId,
+      status,
+      result,
+      errorMessage,
+    },
+  });
+}
+
+async function emitTaskReply(task, payloadOrContent) {
+  const payload = typeof payloadOrContent === 'string'
+    ? {
+        content: payloadOrContent,
+        type: 'text',
+        meta: {
+          taskId: task.id,
+          runtimeId,
+          qclawPath,
+        },
+      }
+    : {
+        ...payloadOrContent,
+        meta: {
+          ...(payloadOrContent?.meta || {}),
+          taskId: task.id,
+          runtimeId,
+          qclawPath,
+        },
+      };
+
+  return requestJson('/api/openclaw/events', {
+    method: 'POST',
+    body: {
+      lobsterId: task?.payload?.lobsterId || task?.lobsterId || null,
+      runtimeId,
+      requestId: task.requestId || task.id,
+      eventType: 'private_message_reply',
+      payload,
+    },
+  });
+}
+
+async function handleTask(task) {
+  if (!task || !task.id) return false;
+
+  console.log(`[Task] 收到任务 ${task.taskType} (${task.id})`);
+
+  try {
+    if (task.taskType === 'private_chat_message') {
+      const rawContent = String(task.payload?.content || '').trim();
+      const brief = rawContent ? rawContent.slice(0, 80) : '空消息';
+      let reply = '';
+      let taskResult = {
+        qclawPath,
+        openclawAgentId,
+      };
+
+      if (shouldCaptureDesktop(rawContent)) {
+        const screenshotPath = await captureDesktopScreenshot();
+        reply = `已为你截取当前桌面，图片已保存在本机：${screenshotPath}`;
+        const mediaBase64 = fs.readFileSync(screenshotPath).toString('base64');
+        taskResult = {
+          ...taskResult,
+          action: 'capture_desktop_screenshot',
+          screenshotPath,
+        };
+        await emitTaskReply(task, {
+          content: reply,
+          type: 'image',
+          media_base64: mediaBase64,
+          media_type: 'image',
+          media_mime_type: 'image/png',
+          media_name: path.basename(screenshotPath),
+        });
+      } else {
+        try {
+          console.log('[Task] 进入 OpenClaw 普通任务执行分支');
+          const agentResult = await runOpenClawAgent(task);
+          reply = agentResult.reply;
+          taskResult = {
+            ...taskResult,
+            openclawSessionId: agentResult.raw?.result?.meta?.agentMeta?.sessionId || null,
+            provider: agentResult.raw?.result?.meta?.agentMeta?.provider || null,
+            model: agentResult.raw?.result?.meta?.agentMeta?.model || null,
+            action: 'openclaw_agent_reply',
+          };
+          if (agentResult.media) {
+            taskResult.mediaType = agentResult.media.media_type;
+            taskResult.mediaName = agentResult.media.media_name;
+          }
+
+          const emitPayload = agentResult.media
+            ? {
+                content: reply || '',
+                type: agentResult.media.media_type === 'image' ? 'image' : 'file',
+                ...agentResult.media,
+              }
+            : reply;
+
+          const emitResult = await emitTaskReply(task, emitPayload);
+          console.log(`[Task] 私聊回写成功: lobsterId=${task?.payload?.lobsterId || task?.lobsterId || 'unknown'}, requestId=${task.requestId || task.id}, eventId=${emitResult?.event?.id || 'n/a'}`);
+        } catch (agentError) {
+          console.log(`[Task] OpenClaw 执行失败，转降级回复: ${agentError.message || '未知错误'}`);
+          reply = `我已收到你的消息，但本地智能引擎当前没有正常返回结果。原因为：${agentError.message || '未知错误'}。如果你要我执行桌面类操作，请直接描述具体动作，例如“帮我截图桌面”。`;
+          taskResult = {
+            ...taskResult,
+            action: 'fallback_text_reply',
+            openclawError: agentError.message || '未知错误',
+          };
+          const emitResult = await emitTaskReply(task, reply);
+          console.log(`[Task] 私聊回写成功: lobsterId=${task?.payload?.lobsterId || task?.lobsterId || 'unknown'}, requestId=${task.requestId || task.id}, eventId=${emitResult?.event?.id || 'n/a'}`);
+        }
+      }
+
+      await reportTaskResult(task.id, 'succeeded', {
+        reply,
+        ...taskResult,
+      });
+      console.log(`[Task] 私聊任务已执行并回写: ${brief}`);
+      return true;
+    }
+
+    await reportTaskResult(task.id, 'failed', {}, `暂不支持的任务类型: ${task.taskType}`);
+    console.warn(`[Task] 暂不支持的任务类型: ${task.taskType}`);
+    return false;
+  } catch (error) {
+    await reportTaskResult(task.id, 'failed', {}, error.message || '任务执行失败');
+    console.error(`[Task] 执行失败: ${error.message}`);
+    return false;
+  }
+}
+
+async function heartbeatLoop() {
+  state.mode = 'heartbeating';
+  console.log(`已连接龙虾: ${state.currentLobster?.name || '未知'} (${state.currentLobster?.id || 'n/a'})`);
+
+  let nextHeartbeatAt = 0;
+  let nextPollAt = 0;
+
+  while (state.shouldRun && !state.reconnectRequested) {
+    const now = Date.now();
+
+    if (now >= nextHeartbeatAt) {
+      try {
+        const result = await sendHeartbeat();
+        console.log(`[Heartbeat ${state.heartbeatCount}] 龙虾=${result.lobster?.name || '未知'} 权限快照已同步`);
+      } catch (error) {
+        console.error(`心跳失败: ${error.message}`);
+        if (error.status === 403 || error.status === 404) {
+          console.log('当前绑定已失效，准备重新进入扫码连接。');
+          return;
+        }
+      }
+      nextHeartbeatAt = Date.now() + heartbeatIntervalMs;
+    }
+
+    if (now >= nextPollAt) {
+      try {
+        const taskResult = await pullNextTask();
+        if (taskResult.task) {
+          await handleTask(taskResult.task);
+          nextPollAt = Date.now() + 500;
+          continue;
+        }
+      } catch (error) {
+        console.error(`拉取任务失败: ${error.message}`);
+        if (error.status === 403 || error.status === 404) {
+          console.log('当前绑定已失效，准备重新进入扫码连接。');
+          return;
+        }
+      }
+      nextPollAt = Date.now() + pollIntervalMs;
+    }
+
+    await sleep(1000);
+  }
+}
+
+function startConsoleCommands() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  rl.on('line', (line) => {
+    const command = String(line || '').trim().toLowerCase();
+    if (command === 'q' || command === 'quit' || command === 'exit') {
+      state.shouldRun = false;
+      state.reconnectRequested = true;
+      rl.close();
+      return;
+    }
+
+    if (command === 'r' || command === 'refresh') {
+      console.log('收到重连命令，准备重新生成二维码。');
+      state.reconnectRequested = true;
+      return;
+    }
+
+    if (command === 's' || command === 'status') {
+      console.log(JSON.stringify({
+        mode: state.mode,
+        runtimeId,
+        currentSessionId: state.currentSessionId,
+        currentLobster: state.currentLobster,
+        heartbeatCount: state.heartbeatCount,
+      }, null, 2));
+    }
+  });
+}
+
+async function mainLoop() {
+  printBanner();
+  const preflight = await runPreflightChecks();
+  printPreflightResult(preflight);
+  startConsoleCommands();
+
+  while (state.shouldRun) {
+    state.reconnectRequested = false;
+    try {
+      const created = await createScanSession();
+      console.log(`新的连接会话已创建: ${created.session.id}`);
+      printQrPayload(created.qrPayload);
+
+      const approvedSession = await waitForApproval(created.session.id);
+      if (!approvedSession || !state.shouldRun) {
+        continue;
+      }
+
+      await heartbeatLoop();
+    } catch (error) {
+      console.error(`连接循环失败: ${error.message}`);
+      if (!state.shouldRun) {
+        break;
+      }
+      await sleep(3000);
+    }
+  }
+
+  console.log('本地 Connector 已退出。');
+  process.exit(0);
+}
+
+process.on('SIGINT', () => {
+  state.shouldRun = false;
+  state.reconnectRequested = true;
+});
+
+process.on('SIGTERM', () => {
+  state.shouldRun = false;
+  state.reconnectRequested = true;
+});
+
+mainLoop().catch((error) => {
+  console.error('Connector 启动失败:', error);
+  process.exit(1);
+});