chatccc 0.2.251 → 0.2.253

package/dist/src/index.js

@@ -0,0 +1,833 @@
+/**
+ * ChatCCC — Feishu Bot Bridge for AI Coding Tools (TypeScript)
+ * =================================================================
+ * Supported tools: Claude Code, Cursor, Codex (OpenAI).
+ *
+ * When a user sends "/new [tool]" to the bot (omitting tool uses the configured default Agent):
+ *   1. Create an AI tool session via the corresponding adapter, get session ID
+ *   2. Create a new Feishu group chat and add the user
+ *   3. Rename the group (name + description) to the session ID
+ *   4. Reply to the new group with session info and welcome message
+ *
+ * Auto-resume: when any message is received in a session group
+ * (group description contains a tool-specific prefix), the bot extracts the
+ * session ID, resumes the session, sends the user's text, and
+ * streams the response to the session's jsonl file.
+ *
+ * Buttons: progress cards have a 停止 button; help messages have /new and /restart buttons.
+ *
+ * Usage:
+ *   npm run dev
+ *   npm run start
+ *   npm run demo:create-group -- --local   (local relay mode)
+ */
+import { createServer } from "node:http";
+import { WSClient, EventDispatcher, Domain } from "@larksuiteoapi/node-sdk";
+import WebSocket from "ws";
+import { appendStartupTrace, attachRelayWebSocket, ensureSingleInstance, freeRelayListenPort, installCrashLogging, installEpipeGuard, waitForPortFree } from "./shared.js";
+import { createUiRouter, setExtraApiHandler, setReloadConfigHook, startSetupMode } from "./web-ui.js";
+import { buildWebUiUrl, createServiceLifecycleGuard, INTERNAL_RESTART_ENV_VAR, openWebUiInDefaultBrowser, shouldAutoOpenWebUi, } from "./startup-lifecycle.js";
+import { buildPlatformStartupPlan } from "./platform-startup.js";
+import { makeTraceId, logTrace } from "./trace.js";
+import { CHATCCC_PORT, config, APP_ID, APP_SECRET, FEISHU_ENABLED, FEISHU_PLATFORM_TYPE, ILINK_ENABLED, ILINK_REUSE_TOKEN_ON_START, BASE_URL, LOCAL_RELAY_URL, PID_FILE, PROJECT_ROOT, USE_LOCAL, USE_SIMULATE, appendChatLog, fileLog, reportEnvironmentVariableReadout, maskAppId, resolveDefaultAgentTool, toolDisplayName, ts, } from "./config.js";
+import { printServiceDidNotStart, printServiceRunningHint } from "./exit-banner.js";
+import { addReaction, createGroupChat, extractSessionInfo, formatDelayNotice, getChatInfo, getTenantAccessToken, recallMessage, sendCardReply, sendRawCard, sendTextReply, setChatAvatar, updateCardMessage, updateChatInfo, disbandChat, sendRestartCard, verifyAllPermissions, reportPermissionResults, setPlatform, consumeCodexRateLimitResetCredit, } from "./feishu-platform.js";
+import { SimulatedPlatform, SIM_DEFAULT_CHAT_ID } from "./sim-platform.js";
+import { setMessageHandler } from "./sim-store.js";
+import { handleAgentImageRequest } from "./agent-image-rpc.js";
+import { handleAgentFileRequest } from "./agent-file-rpc.js";
+import { handleAgentDelegateTaskRequest } from "./agent-delegate-task-rpc.js";
+import { handleAgentStopStuckRequest } from "./agent-stop-stuck.js";
+import { handleAgentReloadConfigRequest } from "./agent-reload-config-rpc.js";
+import { handleChatGptSubscriptionRequest } from "./chatgpt-subscription-rpc.js";
+import { applyPrivacy } from "./privacy.js";
+import { createCardKitCard, sendCardKitMessage, updateCardKitCard, } from "./cardkit.js";
+import { loadSessionRegistryForBinding, rebuildBindingsFromRegistry, resetState, setSessionPlatform, startUnifiedDisplayLoop, } from "./session.js";
+import { startChromeDevtoolsGuard, stopChromeDevtoolsGuard } from "./chrome-devtools-guard.js";
+import { rebuildSessionChatsFromRegistry, setQueueConsumer, } from "./session-chat-binding.js";
+import { fixStaleStreamStates } from "./stream-state.js";
+import { handleCommand } from "./orchestrator.js";
+import { createWechatAdapter, startWechatPlatform } from "./wechat-platform.js";
+import { handleCodexResetCardAction } from "./codex-reset-actions.js";
+import { resolveFeishuCardActionChatType } from "./card-action-routing.js";
+import { reloadRuntimeConfig } from "./runtime-reload.js";
+import { createAckFirstEventHandler, feishuMessageLedger, } from "./feishu-message-ingress.js";
+// ---------------------------------------------------------------------------
+// Feishu 平台适配器
+// ---------------------------------------------------------------------------
+function createFeishuAdapter() {
+    const auth = () => getTenantAccessToken();
+    return {
+        kind: "feishu",
+        // ---- 基础消息 ----
+        async sendText(chatId, text) {
+            return sendTextReply(await auth(), chatId, text);
+        },
+        async sendCard(chatId, title, content, template) {
+            return sendCardReply(await auth(), chatId, title, content, template);
+        },
+        async sendRawCard(chatId, cardJson) {
+            return sendRawCard(await auth(), chatId, cardJson);
+        },
+        // ---- 群聊管理 ----
+        async createGroup(name, userIds) {
+            return createGroupChat(await auth(), name, userIds);
+        },
+        async updateChatInfo(chatId, name, description) {
+            return updateChatInfo(await auth(), chatId, name, description);
+        },
+        async getChatInfo(chatId) {
+            return getChatInfo(await auth(), chatId);
+        },
+        async disbandChat(chatId) {
+            return disbandChat(await auth(), chatId);
+        },
+        async setChatAvatar(chatId, tool, status, usageHints) {
+            return setChatAvatar(await auth(), chatId, tool, status, usageHints);
+        },
+        extractSessionInfo(description) {
+            return extractSessionInfo(description);
+        },
+        // ---- 进度展示（CardKit 委托） ----
+        async cardCreate(cardJson) {
+            return createCardKitCard(await auth(), applyPrivacy(cardJson));
+        },
+        async cardSend(chatId, cardId) {
+            return sendCardKitMessage(await auth(), chatId, cardId);
+        },
+        async cardUpdate(cardId, cardJson, sequence) {
+            return updateCardKitCard(await auth(), cardId, applyPrivacy(cardJson), sequence);
+        },
+    };
+}
+const feishuPlatform = createFeishuAdapter();
+const wechatPlatform = createWechatAdapter();
+setSessionPlatform(feishuPlatform);
+// 注册队列消费回调：session 生成完成后自动处理缓存消息
+setQueueConsumer((platform, msg) => {
+    handleCommand(platform, msg.text, msg.chatId, msg.openId, msg.msgTimestamp, msg.chatType, msg.traceId).catch(err => console.error(`[${ts()}] Queue consume failed: ${err.message}`));
+});
+function getInnerEvent(data) {
+    return (data.event ?? data);
+}
+import { formatMessageContent } from "./format-message.js";
+import { buildUpdateCommandId, extractFeishuEventId, } from "./update-command-guard.js";
+function parseCardAction(data) {
+    const raw = data?.event ?? data;
+    const action = raw?.action;
+    if (!action?.value)
+        return null;
+    let cmd;
+    if (typeof action.value === "object" && action.value !== null) {
+        cmd = action.value.action;
+    }
+    else if (typeof action.value === "string") {
+        try {
+            let v = JSON.parse(action.value);
+            if (typeof v === "string")
+                v = JSON.parse(v);
+            cmd = v.cmd ?? v.action;
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!cmd)
+        return null;
+    const CMD_MAP = { stop: "/stop", cancel: "/cancel", new: "/new", "new claude": "/new claude", "new cursor": "/new cursor", "new codex": "/new codex", restart: "/restart", update: "/update", state: "/state", cd: "/cd", sessions: "/sessions", newh: "/newh" };
+    let text = CMD_MAP[cmd] ?? "";
+    if (cmd === "cd" && typeof action.value === "object" && action.value !== null) {
+        const path = action.value.path;
+        if (path)
+            text = `/cd ${path}`;
+    }
+    // cmd 本身就是以 / 开头的完整指令时，直接使用（如 /model <name> 动态按钮）
+    if (!text && cmd.startsWith("/"))
+        text = cmd;
+    if (!text)
+        return null;
+    const chatId = raw.open_chat_id ??
+        raw.context?.open_chat_id ??
+        raw.message?.chat_id ??
+        "";
+    const openId = raw.operator?.open_id ??
+        "";
+    return {
+        text,
+        chatId,
+        openId,
+        commandId: buildUpdateCommandId("card", extractFeishuEventId(data)),
+    };
+}
+// ---------------------------------------------------------------------------
+// WebSocket relay broadcast
+// ---------------------------------------------------------------------------
+let broadcastToRelay = () => { };
+const wechatSignal = { stopped: false };
+async function processFeishuMessageEvent(data) {
+    const traceId = makeTraceId();
+    try {
+        broadcastToRelay(data);
+        const event = getInnerEvent(data);
+        const message = event.message;
+        if (!message)
+            return;
+        const messageId = message.message_id;
+        const chatId = message.chat_id ?? "";
+        const chatType = message.chat_type ?? "group";
+        const msgTimestamp = parseInt(message.create_time ?? "0", 10) || Date.now();
+        const disposition = await feishuMessageLedger.accept({
+            messageId,
+            chatId,
+            createTime: msgTimestamp,
+        });
+        if (disposition === "duplicate") {
+            console.log(`[MSG] Duplicate message ignored: ${messageId ?? "(missing id)"}`);
+            return;
+        }
+        if (disposition === "stale") {
+            logTrace(traceId, "DONE", {
+                outcome: "skip_stale_feishu_message",
+                messageId,
+                chatId,
+                msgTimestamp,
+            });
+            console.log(`[${ts()}] [SKIP] Stale Feishu message ignored: messageId=${messageId ?? "(missing id)"} chatId=${chatId} createTime=${msgTimestamp}`);
+            return;
+        }
+        const text = await formatMessageContent(message);
+        const openId = event.sender?.sender_id?.open_id ?? "";
+        console.log(`[MSG] id=${messageId ?? "(missing)"} sender=${openId} chat=${chatId} type=${chatType} text="${text}"`);
+        appendChatLog(chatId, openId, text);
+        if (messageId) {
+            getTenantAccessToken().then((freshToken) => addReaction(freshToken, messageId).catch((err) => console.error(`[${ts()}] Reaction failed: ${err.message}`))).catch((err) => console.error(`[${ts()}] Reaction token failed: ${err.message}`));
+        }
+        if (!text)
+            return;
+        logTrace(traceId, "RECV", {
+            messageId,
+            chatId,
+            chatType,
+            text: text.slice(0, 100),
+        });
+        const delayNotice = formatDelayNotice(msgTimestamp, text);
+        if (delayNotice) {
+            const delayToken = await getTenantAccessToken();
+            await sendCardReply(delayToken, chatId, "延迟送达", delayNotice, "yellow").catch(() => { });
+            // 延迟送达的旧消息只发提醒、不转发给 agent 执行：
+            // 断线重连或补推时，早已过期的消息不应未经确认就触发新任务。
+            // 用户如需执行可自行重发。
+            logTrace(traceId, "DONE", {
+                outcome: "skip_delayed_feishu_message",
+                chatId,
+                msgTimestamp,
+                delayMinutes: Math.floor((Date.now() - msgTimestamp) / 60000),
+            });
+            console.log(`[${ts()}] [SKIP] Delayed Feishu message not forwarded to agent: messageId=${messageId ?? "(missing id)"} chatId=${chatId} createTime=${msgTimestamp}`);
+            return;
+        }
+        await handleCommand(feishuPlatform, text, chatId, openId, msgTimestamp, chatType, traceId, buildUpdateCommandId("message", messageId));
+    }
+    catch (err) {
+        logTrace(traceId, "ERROR", { message: err.message });
+        console.error(`[${ts()}] [FATAL] im.message.receive_v1 worker crashed: ${err.message}`);
+    }
+}
+const handleFeishuMessageEventAckFirst = createAckFirstEventHandler(processFeishuMessageEvent, (err) => console.error(`[${ts()}] [FATAL] Detached Feishu event worker failed: ${err.message}`));
+// ---------------------------------------------------------------------------
+// Simulate mode: inject message via HTTP
+// ---------------------------------------------------------------------------
+async function handleSimInjectMessage(req, res) {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    if (url.pathname !== "/api/sim/inject-message")
+        return false;
+    if (req.method !== "POST") {
+        res.writeHead(405, { "Content-Type": "application/json; charset=utf-8" });
+        res.end(JSON.stringify({ ok: false, error: "Method not allowed, use POST" }));
+        return true;
+    }
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.from(chunk));
+    }
+    const body = Buffer.concat(chunks).toString("utf-8");
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+        res.end(JSON.stringify({ ok: false, error: "Invalid JSON body" }));
+        return true;
+    }
+    const text = parsed.text;
+    if (!text) {
+        res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+        res.end(JSON.stringify({ ok: false, error: "Missing 'text' field" }));
+        return true;
+    }
+    const chatId = parsed.chat_id || SIM_DEFAULT_CHAT_ID;
+    const openId = parsed.open_id || "sim_user_001";
+    const chatType = parsed.chat_type || "group";
+    console.log(`[${ts()}] [SIM:INJECT] chat=${chatId} text="${text.slice(0, 80)}"`);
+    appendChatLog(chatId, openId, text);
+    // Fire and forget: process command, respond 202 immediately
+    handleCommand(feishuPlatform, text, chatId, openId, Date.now(), chatType).catch((err) => console.error(`[${ts()}] [SIM:INJECT] handleCommand error: ${err.message}`));
+    res.writeHead(202, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ ok: true, chat_id: chatId }));
+    return true;
+}
+async function startBotService(opts) {
+    const { httpServer, port } = opts;
+    console.log(`\n[启动 3/7] 在 http://127.0.0.1:${port} 上挂载本地 WebSocket 中继 …`);
+    appendStartupTrace("startBotService: before attachRelayWebSocket", { port });
+    const wsAttachment = attachRelayWebSocket(httpServer);
+    broadcastToRelay = wsAttachment.broadcast;
+    // UI router 在 setup 模式下已经挂在 httpServer 上；main 直入模式由 main() 负责挂
+    // —— 这里不再额外 attach，避免重复触发 createUiRouter。
+    console.log("  完成。\n");
+    // setup-activate 模式下，token / permissions / wsClient 任一阶段失败都需要
+    // 回滚已挂的 WSServer，否则用户重试 onActivate 时会重复挂载导致句柄泄漏。
+    // 用 try / catch 统一 wrap 后续启动逻辑。
+    try {
+        await startBotServiceCore();
+    }
+    catch (err) {
+        wsAttachment.close();
+        broadcastToRelay = () => { };
+        throw err;
+    }
+}
+async function startBotServiceCore() {
+    const modeTag = USE_LOCAL ? " (local relay mode)" : "";
+    console.log(`${"=".repeat(60)}`);
+    console.log(`  ChatCCC — Feishu Bot Bridge for Claude Code${modeTag}`);
+    console.log(`${"=".repeat(60)}`);
+    console.log(`  Send "/new" to the bot to create a new group + ${toolDisplayName(resolveDefaultAgentTool())} session.`);
+    console.log(`  In a session group, send any message to resume & prompt.`);
+    console.log(`${"=".repeat(60)}`);
+    console.log(`\n[启动 4/7] 向飞书开放平台申请 tenant_access_token …`);
+    let token;
+    try {
+        token = await getTenantAccessToken();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error("  失败：无法获取 tenant_access_token。");
+        console.error(`  接口: POST ${BASE_URL}/auth/v3/tenant_access_token/internal`);
+        const apiHost = BASE_URL.replace("https://", "").replace("/open-apis", "");
+        console.error("  常见原因:");
+        console.error(`    - 本机网络无法访问 ${apiHost}（可尝试：关闭系统/终端代理、检查防火墙；Windows 可管理员运行 netsh winsock reset 后重启）`);
+        console.error("    - App ID / App Secret 与开放平台「凭证与基础信息」不一致");
+        console.error("    - 自建应用尚未创建/发布可用版本");
+        console.error(`  详情: ${msg}`);
+        throw new Error(`无法从飞书开放平台获取 tenant_access_token: ${msg}`);
+    }
+    console.log(`  完成。当前 App ID 摘要: ${maskAppId(APP_ID)}\n`);
+    console.log(`\n[启动 5/7] 验证飞书应用权限（非破坏性探针）…`);
+    const permResults = await verifyAllPermissions(token);
+    const hasFailed = reportPermissionResults(permResults, (msg) => {
+        console.log(msg);
+    });
+    if (hasFailed) {
+        const failedScopes = permResults.filter((r) => !r.ok).map((r) => r.scope).join(", ");
+        appendStartupTrace("startBotService: permissions check failed", { failed: failedScopes });
+        throw new Error(`飞书权限不足: ${failedScopes}`);
+    }
+    appendStartupTrace("startBotService: permissions check ok");
+    console.log(`  完成。所有必需权限已验证通过。\n`);
+    console.log(`[${ts()}] [AUTH] Token obtained`);
+    const eventDispatcher = new EventDispatcher({});
+    eventDispatcher.register({
+        "im.message.receive_v1": handleFeishuMessageEventAckFirst,
+        "card.action.trigger": async (data) => {
+            try {
+                // 拦截关闭按钮：先置空内容，再尝试撤回（撤回结果不影响后续流程）
+                const raw2 = data.event ?? data;
+                const action2 = raw2?.action;
+                const actionVal2 = action2?.value;
+                if (actionVal2?.action === "close") {
+                    console.log(`[${ts()}] [CLOSE] close button clicked, raw keys: ${Object.keys(raw2).join(", ")}`);
+                    const messageId = raw2?.open_message_id
+                        ?? raw2?.context?.open_message_id;
+                    console.log(`[${ts()}] [CLOSE] open_message_id=${messageId ?? "MISSING"}`);
+                    if (messageId) {
+                        const closeToken = await getTenantAccessToken();
+                        updateCardMessage(closeToken, messageId, JSON.stringify({
+                            config: { wide_screen_mode: true },
+                            elements: [{ tag: "markdown", content: " " }],
+                        })).catch((err) => {
+                            console.error(`[${ts()}] [CLOSE] updateCardMessage failed: ${err.message}`);
+                        });
+                        recallMessage(closeToken, messageId).then((recalled) => {
+                            console.log(`[${ts()}] [CLOSE] recall result: ${recalled ? "OK" : "FAILED"}`);
+                        }).catch((err) => {
+                            console.error(`[${ts()}] [CLOSE] recall failed: ${err.message}`);
+                        });
+                    }
+                    else {
+                        console.error(`[${ts()}] [CLOSE] no open_message_id in event, cannot close`);
+                    }
+                    return;
+                }
+                const handledCodexReset = await handleCodexResetCardAction(data, {
+                    getTenantAccessToken,
+                    sendRawCard,
+                    sendTextReply,
+                    sendCardReply,
+                    updateCardMessage,
+                    recallMessage,
+                    consumeCodexRateLimitResetCredit,
+                });
+                if (handledCodexReset)
+                    return;
+                const result = parseCardAction(data);
+                if (!result)
+                    return;
+                const registry = await loadSessionRegistryForBinding();
+                const chatType = resolveFeishuCardActionChatType(result.chatId, registry);
+                console.log(`[BTN] chat=${result.chatId} chatType=${chatType} text="${result.text}"`);
+                handleCommand(feishuPlatform, result.text, result.chatId, result.openId, Date.now(), chatType, undefined, result.commandId).catch((err) => console.error(`[${ts()}] [BTN] handleCommand failed: ${err.message}`));
+            }
+            catch (err) {
+                console.error(`[${ts()}] [FATAL] card.action.trigger handler crashed: ${err.message}`);
+            }
+        },
+    });
+    if (USE_LOCAL) {
+        console.log(`\n[启动 6/7] 本地区 relay 模式：正在连接 ${LOCAL_RELAY_URL} …`);
+        console.log("  若失败：请先在 SDK 模式下启动主进程，或确认本机中继已在该地址监听。");
+        let localRelayOpened = false;
+        const ws = new WebSocket(LOCAL_RELAY_URL);
+        ws.on("open", () => {
+            localRelayOpened = true;
+            console.log("[WS] Connected to local relay");
+            console.log("[启动 7/7] 已连接本地中继，可接收转发事件。\n");
+            printServiceRunningHint("local", `http://127.0.0.1:${CHATCCC_PORT}`);
+        });
+        ws.on("message", async (raw) => {
+            try {
+                const data = JSON.parse(raw.toString());
+                const action = parseCardAction(data);
+                if (action) {
+                    const registry = await loadSessionRegistryForBinding();
+                    const chatType = resolveFeishuCardActionChatType(action.chatId, registry);
+                    handleCommand(feishuPlatform, action.text, action.chatId, action.openId, Date.now(), chatType, undefined, action.commandId).catch((err) => console.error(`[${ts()}] [BTN] handleCommand failed: ${err.message}`));
+                    return;
+                }
+                const event = getInnerEvent(data);
+                const message = event.message;
+                if (!message)
+                    return;
+                const text = await formatMessageContent(message);
+                const openId = event.sender?.sender_id?.open_id ?? "";
+                const chatId = message.chat_id ?? "";
+                appendChatLog(chatId, openId, text);
+                if (text.toLowerCase() === "/new" && openId) {
+                    console.log(`[MSG] /new from ${openId}, but local relay does not handle /new yet. Use SDK mode.`);
+                }
+            }
+            catch { /* ignore */ }
+        });
+        ws.on("close", () => { console.log("[WS] Local relay disconnected"); process.exit(0); });
+        ws.on("error", (err) => {
+            if (!localRelayOpened) {
+                console.error(`[启动 6/7] 失败：无法连接本地中继。`);
+                console.error(`  ${err.message}`);
+                console.error(`  目标: ${LOCAL_RELAY_URL}`);
+                // 注意：local relay 模式下连接是异步的；此处 throw 出 startBotService
+                // 已经返回的事件循环外，调用方拿不到。约定：local 模式连接失败一律
+                // 直接退出进程（与 setup-activate 模式无关 —— setup 模式不会用 local relay）。
+                printServiceDidNotStart(`无法连接本地中继 ${LOCAL_RELAY_URL}`);
+                process.exit(1);
+            }
+            console.error(`[WS] Local relay error: ${err.message}`);
+        });
+    }
+    else {
+        // 进程首次启动:此时所有 Map 都是空的,resetState 主要是打个 LOG 标识"开始
+        // 干净状态"。修正残留的 running stream-state 并重建 session→chat 映射。
+        resetState();
+        await feishuMessageLedger.load();
+        startUnifiedDisplayLoop();
+        fixStaleStreamStates().then(async () => {
+            const registry = await loadSessionRegistryForBinding();
+            rebuildSessionChatsFromRegistry(registry);
+        }).catch((err) => console.error(`[${ts()}] Init bindings failed: ${err.message}`));
+        // ⚠️ 关键设计:onReady / onReconnected 只重建只读映射,**绝不**清空运行时
+        // 状态(activePrompts、sessionInfoMap、processedMessages)。
+        // SDK 重连只是底层 WebSocket 抖动,业务层不受影响:
+        //   - 后台 generator 仍在跑、stream-state 仍在被写
+        //   - display loop 仍在向群推送
+        //   - 已处理消息的去重 set 必须保留,避免 SDK 重推老消息时 prompt 跑两遍
+        // 历史 bug:此处曾误调 resetState() 导致重连即让所有后台任务变孤儿,
+        // 同一 session 还可能双开 prompt(详见 session.ts::resetState 注释)。
+        const wsClient = new WSClient({
+            appId: APP_ID,
+            appSecret: APP_SECRET,
+            domain: FEISHU_PLATFORM_TYPE === "lark" ? Domain.Lark : Domain.Feishu,
+            onReady: async () => {
+                await rebuildBindingsFromRegistry().catch((err) => console.error(`[${ts()}] [SDK READY] rebuild bindings failed: ${err.message}`));
+            },
+            onReconnected: async () => {
+                await rebuildBindingsFromRegistry().catch((err) => console.error(`[${ts()}] [SDK RECONNECT] rebuild bindings failed: ${err.message}`));
+            },
+        });
+        console.log(`\n[启动 6/7] 飞书长连接：正在通过 SDK 建立 WebSocket …`);
+        try {
+            await wsClient.start({ eventDispatcher });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error("  失败：飞书 WebSocket 未能启动。");
+            console.error("  常见原因: 应用权限未开通、事件订阅未配置、网络问题、或 SDK 内部错误。");
+            console.error(`  详情: ${msg}`);
+            throw new Error(`飞书 SDK WebSocket 未能建立: ${msg}`);
+        }
+        console.log("[WS] Feishu WebSocket connected (SDK)");
+        console.log("[启动 7/7] 服务已就绪，等待飞书消息（群聊 / 卡片回调）。\n");
+        printServiceRunningHint("sdk", `http://127.0.0.1:${CHATCCC_PORT}`);
+        sendRestartCard(token).catch((err) => console.error(`[${ts()}] [RESTART] sendRestartCard failed: ${err.message}`));
+    }
+}
+// ---------------------------------------------------------------------------
+// WeChat iLink supervisor — 自动重连
+// ---------------------------------------------------------------------------
+async function startWechatSupervisor() {
+    if (!ILINK_ENABLED) {
+        console.log("[WX] 微信 iLink 未启用（platforms.ilink.enabled 不为 true），跳过。");
+        return;
+    }
+    console.log("\n[WX] 启动微信 iLink 平台...");
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    const MAX_QR_RETRIES = 3;
+    let qrTimeoutCount = 0;
+    while (!wechatSignal.stopped) {
+        let isQrTimeout = false;
+        try {
+            await startWechatPlatform((text, chatId, openId, msgTimestamp, chatType, traceId) => handleCommand(wechatPlatform, text, chatId, openId, msgTimestamp, chatType, traceId), wechatSignal, ILINK_REUSE_TOKEN_ON_START);
+            // 登录成功后重置计数
+            qrTimeoutCount = 0;
+        }
+        catch (err) {
+            const msg = err.message ?? "";
+            isQrTimeout = msg.includes("QR 登录超时");
+            if (isQrTimeout) {
+                qrTimeoutCount++;
+                console.error(`[WX] QR 登录超时 (${qrTimeoutCount}/${MAX_QR_RETRIES}): ${msg}`);
+                if (qrTimeoutCount >= MAX_QR_RETRIES) {
+                    console.error(`[WX] 已连续 ${MAX_QR_RETRIES} 次 QR 登录超时，放弃重试。如需重新尝试请重启 ChatCCC。`);
+                    break;
+                }
+            }
+            else {
+                console.error(`[WX] 微信 iLink 崩溃: ${msg}`);
+            }
+        }
+        if (wechatSignal.stopped)
+            break;
+        const delaySeconds = isQrTimeout ? 300 : 30;
+        const delayDesc = isQrTimeout ? "5 分钟" : "30 秒";
+        console.log(`[WX] ${delayDesc}后重试...`);
+        await sleep(delaySeconds * 1000);
+    }
+    console.log("[WX] 微信 iLink 平台已停止。");
+}
+async function startConfiguredPlatforms(httpServer, options) {
+    const plan = buildPlatformStartupPlan({
+        feishuEnabled: FEISHU_ENABLED,
+        ilinkEnabled: ILINK_ENABLED,
+    });
+    if (plan.startFeishu) {
+        try {
+            await startBotService({ httpServer, port: CHATCCC_PORT });
+        }
+        catch (err) {
+            if (options.failOnFeishuError)
+                throw err;
+            console.error(`\n[飞书] 启动失败: ${err.message}`);
+            console.error("[飞书] 微信等其他平台不受影响，将继续启动。\n");
+        }
+    }
+    else {
+        console.log("[飞书] 平台未启用，跳过飞书启动。");
+    }
+    if (plan.startIlink) {
+        startWechatSupervisor().catch((err) => console.error(`[WX] 微信 supervisor 异常退出: ${err.message}`));
+    }
+    else {
+        console.log("[WX] 微信 iLink 未启用，跳过微信启动。");
+    }
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+    // 用户直接运行 chatccc 时打开系统默认浏览器；由 `/restart`、`/update`
+    // 或 Web UI 拉起的替代进程会携带内部标记，不重复打扰用户。
+    const autoOpenWebUi = shouldAutoOpenWebUi({
+        openOnStart: config.webUi.openOnStart,
+    });
+    appendStartupTrace("main: entered", {
+        argv: process.argv.join(" ").slice(0, 400),
+        CHATCCC_PORT,
+        PROJECT_ROOT,
+        autoOpenWebUi,
+    });
+    // ChatCCC 是常驻服务，不能把“当前刚好有没有 Agent session”当作进程生命周期。
+    // referenced timer 明确锚定服务进程；HTTP Server 接入后还会定期 ref/健康检查。
+    // `/restart`、`/update` 都使用 process.exit()，不会被 timer 阻止。
+    const serviceLifecycle = createServiceLifecycleGuard({ tracer: appendStartupTrace });
+    serviceLifecycle.start();
+    // 黑匣子：所有未捕获异常 / 信号 / beforeExit 都同步写入 startup-trace.log（appendFileSync）。
+    // 越早装越好——后续任何一行抛错都有兜底；它独立于 SIGINT 清理（见末尾的
+    // server.close）——只负责诊断与默认致命退出，不替代清理逻辑。
+    installCrashLogging({
+        flush: () => fileLog.flush(),
+        onBeforeExit: (code) => serviceLifecycle.handleBeforeExit(code),
+    });
+    // stdout/stderr 管道读端消失（如 /restart 旧进程退出后）时，第三方 SDK 写
+    // stderr 会 EPIPE；无监听会抛 uncaughtException 杀死整个服务。挂守卫把这类
+    // IO 错误降级为一条非致命 trace。
+    installEpipeGuard();
+    // 模拟模式：独立端口 18079，不与 SDK 实例冲突，不走飞书凭证/权限/WSClient
+    if (USE_SIMULATE) {
+        const SIM_PORT = 18079;
+        console.log("\n[Simulate] 模拟飞书环境模式");
+        setPlatform(SimulatedPlatform);
+        console.log("  已切换到 SimulatedPlatform（零飞书依赖）");
+        appendStartupTrace("main: simulate mode", { port: SIM_PORT });
+        // 注册消息处理器，让 SimAgent.sendMessage() 能进程内触发 handleCommand
+        setMessageHandler((text, chatId, openId, _ts, chatType, traceId) => handleCommand(feishuPlatform, text, chatId, openId, Date.now(), chatType, traceId));
+        setExtraApiHandler(async (req, res) => {
+            const injected = await handleSimInjectMessage(req, res);
+            if (injected)
+                return true;
+            return (await handleAgentReloadConfigRequest(req, res))
+                || (await handleAgentImageRequest(req, res))
+                || (await handleAgentFileRequest(req, res))
+                || (await handleAgentDelegateTaskRequest(req, res, feishuPlatform))
+                || (await handleAgentStopStuckRequest(req, res))
+                || (await handleChatGptSubscriptionRequest(req, res));
+        });
+        const simServer = createServer(createUiRouter());
+        await new Promise((resolveListen, rejectListen) => {
+            const onError = (err) => {
+                simServer.removeListener("listening", onListening);
+                rejectListen(err);
+            };
+            const onListening = () => {
+                simServer.removeListener("error", onError);
+                resolveListen();
+            };
+            simServer.once("error", onError);
+            simServer.once("listening", onListening);
+            simServer.listen(SIM_PORT, "127.0.0.1");
+        }).catch((err) => {
+            console.error(`\n[启动] 监听失败：端口 ${SIM_PORT}（${err.code ?? "?"} — ${err.message}）`);
+            process.exit(1);
+        });
+        serviceLifecycle.attachServer(simServer, () => recoverHttpServer(simServer, SIM_PORT));
+        console.log(`\n${"=".repeat(60)}`);
+        console.log(`  ChatCCC — 模拟飞书环境模式`);
+        console.log(`${"=".repeat(60)}`);
+        console.log(`  发送消息: POST http://127.0.0.1:${SIM_PORT}/api/sim/inject-message`);
+        console.log(`  消息日志: ~/.chatccc/sim/messages.jsonl`);
+        console.log(`${"=".repeat(60)}\n`);
+        if (autoOpenWebUi) {
+            const url = buildWebUiUrl(SIM_PORT);
+            const opened = openWebUiInDefaultBrowser(SIM_PORT);
+            appendStartupTrace(opened ? "web-ui: opening simulate browser" : "web-ui: simulate browser unavailable", { url });
+        }
+        installShutdownHandlers(simServer, serviceLifecycle);
+        return;
+    }
+    if (Number.isNaN(CHATCCC_PORT) || CHATCCC_PORT < 1 || CHATCCC_PORT > 65535) {
+        console.error("\n[启动] 预检失败: config.json 的 port 字段不是有效端口号（1–65535）。");
+        console.error(`  当前配置: ${CHATCCC_PORT}`);
+        reportEnvironmentVariableReadout();
+        printServiceDidNotStart("config.json 的 port 字段配置无效（须为 1–65535 的整数）");
+        process.exit(1);
+    }
+    console.log(`\n[启动 1/7] 单实例：按 PID 文件清理旧 ChatCCC 进程`);
+    console.log(`  PID 文件: ${PID_FILE}`);
+    appendStartupTrace("main: before ensureSingleInstance", { PID_FILE, CHATCCC_PORT });
+    ensureSingleInstance(PID_FILE);
+    appendStartupTrace("main: after ensureSingleInstance");
+    console.log("  完成。\n");
+    // 注册 reload hook：dashboard 模式（或 setup 激活后再点向导）下用户点
+    // "保存并启动" 时，web-ui 会调用本回调，把磁盘上刚保存的 config.json
+    // 刷进进程内的 export let 常量（live binding 让 CLAUDE_MODEL 等下次创建
+    // 会话时自动看到新值）。setup 首次激活走 onActivate 路径，不依赖此 hook。
+    setReloadConfigHook(() => {
+        reloadRuntimeConfig("reload-from-ui");
+    });
+    setExtraApiHandler(async (req, res) => {
+        return (await handleAgentReloadConfigRequest(req, res))
+            || (await handleAgentImageRequest(req, res))
+            || (await handleAgentFileRequest(req, res))
+            || (await handleAgentDelegateTaskRequest(req, res, feishuPlatform))
+            || (await handleAgentStopStuckRequest(req, res))
+            || (await handleChatGptSubscriptionRequest(req, res));
+    });
+    console.log(`[启动 2/7] 环境与凭证检查`);
+    reportEnvironmentVariableReadout();
+    console.log(`  工作目录: ${process.cwd()}`);
+    console.log(`  包根目录: ${PROJECT_ROOT}`);
+    if (FEISHU_ENABLED) {
+        appendStartupTrace("main: before feishu credential check", {
+            hasAppId: Boolean(APP_ID.trim()),
+            hasAppSecret: Boolean(APP_SECRET.trim()),
+        });
+        if (!APP_ID.trim() || !APP_SECRET.trim()) {
+            // 凭证不全：进 setup 向导。注入 onActivate 回调让用户点"保存并启动"
+            // 时，原地（同进程）调用 startBotService，复用 setup HTTP server。
+            const setupServer = startSetupMode(CHATCCC_PORT, {
+                openBrowser: autoOpenWebUi,
+                onActivate: async (httpServer) => {
+                    reloadRuntimeConfig("setup-activate");
+                    appendStartupTrace("setup-activate: reloaded config from disk", {
+                        appIdMaskAfterReload: maskAppId(APP_ID),
+                    });
+                    try {
+                        await startConfiguredPlatforms(httpServer, { failOnFeishuError: true });
+                        return { ok: true };
+                    }
+                    catch (err) {
+                        appendStartupTrace("setup-activate: startConfiguredPlatforms failed", {
+                            message: err.message,
+                        });
+                        return { ok: false, error: err.message };
+                    }
+                },
+            });
+            setupServer.once("listening", () => {
+                serviceLifecycle.attachServer(setupServer, () => recoverHttpServer(setupServer, CHATCCC_PORT));
+            });
+            installShutdownHandlers(setupServer, serviceLifecycle);
+            return;
+        }
+        console.log(`  必填项校验通过（App ID 摘要: ${maskAppId(APP_ID)}）。\n`);
+        appendStartupTrace("main: feishu credentials ok", { appIdMask: maskAppId(APP_ID) });
+    }
+    else {
+        console.log("  飞书平台未启用（platforms.feishu.enabled = false），跳过飞书凭证检查。\n");
+        appendStartupTrace("main: feishu disabled", {});
+    }
+    startChromeDevtoolsGuard();
+    // 启动 HTTP server（同时挂 UI router，供 dashboard / setup / agent image/file 使用）
+    appendStartupTrace("main: before freeRelayListenPort", { CHATCCC_PORT });
+    const killed = freeRelayListenPort(CHATCCC_PORT);
+    const isInternalRestart = process.env[INTERNAL_RESTART_ENV_VAR] === "1";
+    appendStartupTrace("main: after freeRelayListenPort", { CHATCCC_PORT, killed, isInternalRestart });
+    // 内部自重启（/restart、/update）时父进程还占着端口（祖先链 PID 不会被杀）：
+    // 无条件等待端口释放再 listen，避免子进程一上来就 EADDRINUSE 秒退
+    // （Windows 端口释放有额外延迟，重试窗口容易不够）。
+    if (killed > 0 || isInternalRestart) {
+        await waitForPortFree(CHATCCC_PORT, isInternalRestart ? 5000 : undefined);
+        appendStartupTrace("main: port free confirmed", { CHATCCC_PORT, isInternalRestart });
+    }
+    const httpServer = createServer(createUiRouter());
+    await listenWithRetry(httpServer, CHATCCC_PORT, "127.0.0.1").catch((err) => {
+        console.error(`\n[启动] 本地中继 WebSocket 监听失败：端口 ${CHATCCC_PORT}（${err.code ?? "?"} — ${err.message}）`);
+        console.error("  处理建议: 关闭占用该端口的其它程序，或在 config.json 的 port 字段里改成其它未占用端口（如 18081）。");
+        printServiceDidNotStart(`本地中继端口 ${CHATCCC_PORT} 无法监听（${err.code ?? "?"} — ${err.message}）`);
+        process.exit(1);
+    });
+    serviceLifecycle.attachServer(httpServer, () => recoverHttpServer(httpServer, CHATCCC_PORT));
+    // 平台鉴权/长连接启动可能耗时；此时也必须允许 Ctrl+C / SIGTERM 正常退出，
+    // 不能只留下更早安装的信号日志 listener 把默认退出行为吞掉。
+    installShutdownHandlers(httpServer, serviceLifecycle);
+    // 必须等 HTTP server 真正监听后再发起打开请求，避免浏览器先到一步看到
+    // ERR_CONNECTION_REFUSED。Chrome CDP 守护仍保持自己原有的独立行为。
+    if (autoOpenWebUi) {
+        const url = buildWebUiUrl(CHATCCC_PORT);
+        const opened = openWebUiInDefaultBrowser(CHATCCC_PORT);
+        if (opened) {
+            console.log(`[WEB-UI] 已请求系统默认浏览器打开: ${url}`);
+            appendStartupTrace("web-ui: opening default browser", { url });
+        }
+        else {
+            appendStartupTrace("web-ui: default browser unavailable", { url });
+        }
+    }
+    else {
+        appendStartupTrace("web-ui: default browser skipped by lifecycle or preference", {
+            url: buildWebUiUrl(CHATCCC_PORT),
+            openOnStart: config.webUi.openOnStart,
+        });
+    }
+    await startConfiguredPlatforms(httpServer, { failOnFeishuError: false });
+}
+/**
+ * 生命周期健康检查发现 HTTP Server 已停止监听时，优先原地恢复同一个 Server。
+ * router、WebSocket upgrade listener 都挂在这个对象上，复用它能保留现有服务绑定；
+ * 恢复失败会被 lifecycle guard 记录，并在下一轮检查重试。
+ */
+async function recoverHttpServer(httpServer, port) {
+    if (httpServer.listening) {
+        httpServer.ref();
+        return;
+    }
+    appendStartupTrace("service-lifecycle: HTTP recovery begin", { port });
+    await listenWithRetry(httpServer, port, "127.0.0.1");
+    httpServer.ref();
+    appendStartupTrace("service-lifecycle: HTTP recovery listen succeeded", { port });
+}
+/**
+ * 带重试的 server.listen，Windows 端口释放有延迟时自动重试。
+ */
+async function listenWithRetry(server, port, host, maxRetries = 3) {
+    for (let i = 0; i < maxRetries; i++) {
+        try {
+            await new Promise((resolve, reject) => {
+                server.once("error", reject);
+                server.once("listening", resolve);
+                server.listen(port, host);
+            });
+            return;
+        }
+        catch (err) {
+            const e = err;
+            server.removeAllListeners("listening");
+            server.removeAllListeners("error");
+            if (e.code === "EADDRINUSE" && i < maxRetries - 1) {
+                await new Promise((r) => setTimeout(r, 500 * (i + 1)));
+                continue;
+            }
+            throw err;
+        }
+    }
+}
+/**
+ * 注册 SIGINT / SIGTERM 清理：把 relay/setup 共用的 httpServer 关掉再退出。
+ *
+ * Node EventEmitter 按注册顺序触发，installCrashLogging 装得更早 → 同步 trace
+ * 先写盘，再走这里。
+ */
+function installShutdownHandlers(httpServer, serviceLifecycle) {
+    process.on("SIGINT", () => {
+        console.log("\nShutting down...");
+        serviceLifecycle.beginShutdown("SIGINT");
+        wechatSignal.stopped = true;
+        stopChromeDevtoolsGuard();
+        httpServer.close();
+        process.exit(0);
+    });
+    process.on("SIGTERM", () => {
+        serviceLifecycle.beginShutdown("SIGTERM");
+        wechatSignal.stopped = true;
+        stopChromeDevtoolsGuard();
+        httpServer.close();
+        process.exit(0);
+    });
+}
+main().catch((err) => {
+    appendStartupTrace("main: catch fatal", { message: err.message, stack: err.stack?.slice(0, 800) });
+    console.error("\n[启动] 未捕获的致命错误（main 异步链）");
+    console.error(`  ${err.message}`);
+    if (err.stack)
+        console.error(err.stack);
+    printServiceDidNotStart(`main() 异常: ${err.message}`);
+    process.exit(1);
+});