lightclawbot 1.2.6 → 1.2.7

package/dist/src/socket/handlers.js

@@ -1,71 +1,21 @@
 /**
- * LightClaw — Socket.IO 事件处理器
+ * LightClaw — Socket.IO 事件处理器（主入口）
  *
- * 将 socket 事件监听（message:private、history:request、sessions:request）
- * 从 gateway 主逻辑中解耦，使 gateway.ts 只负责连接管理，本模块专注事件处理。
+ * 将 socket 事件监听从 gateway 主逻辑中解耦，本模块只负责事件注册与分发。
+ * 各事件的具体处理逻辑已拆分到 events/ 子目录下的独立模块中。
  *
  * 事件处理流程：
  *   1. message:private  — 接收用户私信，过滤无效消息后入队等待 AI 处理
  *   2. history:request  — 接收历史消息拉取请求，查询本地存储后返回
- *   3. sessions:request — 接收会话列表请求，返回所有已存在的会话
- *
- * 所有出站 socket.emit 通过 ReliableEmitter 实现 ACK 确认 + 自动重试，
- * 保证消息在网络抖动时不丢失。
+ *   3. agents:request   — 接收 Agent 列表请求，返回配置中的 agents
+ *   4. chat:request     — 接收会话管理请求（list/create/update/delete）
+ *   5. group:request    — 接收群组管理请求（list/create/update/delete/clear）
+ *   6. group:member:request  — 接收群成员管理请求（add/remove）
+ *   7. group:history:request — 接收群历史消息请求
+ *   8. group:abort:request   — 接收群消息中止请求
  */
-import { CHANNEL_KEY, EVENT_MESSAGE_PRIVATE, EVENT_HISTORY_REQUEST, EVENT_HISTORY_RESPONSE, DEFAULT_HISTORY_LIMIT, DEFAULT_AGENT_ID, EVENT_AGENTS_REQUEST, EVENT_AGENTS_RESPONSE, KIND_FILE_DOWNLOAD, FILE_DOWNLOAD_STATUS, EVENT_CHAT_REQUEST, } from '../config.js';
-import { isDuplicate, debounceHistoryRequest, generateMsgId } from '../dedup.js';
-import { getLightclawRuntime } from '../runtime.js';
-import { readSessionHistoryWithCron, readSessionHistoriesByIds, loadSessionStore } from '../history/index.js';
-import { handleChatList, handleChatCreate, handleChatUpdate, handleChatDelete } from './chat.js';
-import { uploadFileToServer } from '../file-storage.js';
-import { guessMimeByExt } from '../media.js';
-import { ensureSessionInHistory, readChatsFile, resolveChatsFilePath } from '../utils/common.js';
-import { attachSoulIdsToAgents, readSoulIdMap, LIGHTSOUL_CONFIG_PATH } from './agent-soul.js';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-const getNonEmptyString = (value) => {
-    if (typeof value !== 'string')
-        return undefined;
-    const trimmed = value.trim();
-    return trimmed || undefined;
-};
-const isMainAgent = (agent) => {
-    const id = getNonEmptyString(agent.id);
-    const name = getNonEmptyString(agent.name);
-    return id === DEFAULT_AGENT_ID || name === DEFAULT_AGENT_ID;
-};
-const withDefaultWorkspace = (agent, defaultWorkspace) => {
-    if (!defaultWorkspace || getNonEmptyString(agent.workspace))
-        return agent;
-    return { ...agent, workspace: defaultWorkspace };
-};
-/**
- * 组装 agents:request 响应列表，确保单 agent 场景也返回默认 main agent。
- */
-export const normalizeAgentsWithMainAgent = (currentCfg) => {
-    const agentsConfig = currentCfg.agents;
-    const agentsList = Array.isArray(agentsConfig?.list) ? agentsConfig.list : [];
-    const defaultWorkspace = getNonEmptyString(agentsConfig?.defaults?.workspace);
-    let hasMainAgent = false;
-    const normalizedAgents = agentsList.map((agent) => {
-        if (!isMainAgent(agent))
-            return agent;
-        hasMainAgent = true;
-        return withDefaultWorkspace(agent, defaultWorkspace);
-    });
-    if (hasMainAgent)
-        return normalizedAgents;
-    const mainAgent = {
-        id: DEFAULT_AGENT_ID,
-        name: DEFAULT_AGENT_ID,
-        displayName: DEFAULT_AGENT_ID,
-        isDefault: true,
-    };
-    if (defaultWorkspace) {
-        mainAgent.workspace = defaultWorkspace;
-    }
-    return [mainAgent, ...normalizedAgents];
-};
+// 从子模块导入各事件处理器绑定函数
+import { bindMessagePrivateHandler, bindHistoryRequestHandler, bindAgentsRequestHandler, bindChatRequestHandler, bindGroupRequestHandler, bindGroupHistoryHandler, bindGroupMemberHandler, bindGroupAbortHandler, } from './events/index.js';
 /**
  * 绑定所有 Socket.IO 事件监听器到指定 socket 实例。
  *
@@ -76,519 +26,54 @@ export const normalizeAgentsWithMainAgent = (currentCfg) => {
  * @param deps   - 处理事件所需的外部依赖（账户信息、队列、日志等）
  */
 export function bindSocketHandlers(socket, deps) {
-    const { account, botClientId, log, handleMessage, onEvent, reliableEmitter } = deps;
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    const { botClientId, onEvent, reliableEmitter, orchestrator, groupStorage } = deps;
     // 事件：接收用户私信（message:private）
-    // 职责：对消息做多层过滤，将合法消息放入处理队列
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    socket.on(EVENT_MESSAGE_PRIVATE, (data, ack) => {
-        // 立即回复 ACK，告知服务端消息已收到，避免服务端重发
-        ack?.();
-        // {"msgId":"91647ae9-c123-48e4-9d80-26f2e9a91ac9","from":"100013456706","to":"lhins-jem9a0br","content":"今天天气怎么样","files":[],"timestamp":1776077511044}
-        log?.info(`[${CHANNEL_KEY}] Received private message: ${JSON.stringify(data)}，botClientId:${botClientId}`);
-        // ① 回环防御：过滤 bot 自身发出的消息，防止自问自答死循环
-        if (data.from === botClientId)
-            return;
-        // ② 分发文件下载信令（kind=file:download, status=download_req）：独立链路，不入 AI 处理队列
-        if (data.kind === KIND_FILE_DOWNLOAD) {
-            const reqTransferData = data.extra?.transferData;
-            if (reqTransferData?.status === FILE_DOWNLOAD_STATUS.REQ) {
-                // 去重：同一 transferId 的重复请求直接跳过
-                if (isDuplicate(data.msgId))
-                    return;
-                onEvent?.();
-                void handleFileDownloadReq(data, botClientId, reliableEmitter, account, log);
-            }
-            // 其他 status（ready/url/error）是本端自己发出的下行消息，理论上不会从前端回流；
-            // 即便误触发，此处直接 return 不做处理，避免进入 AI 处理队列
-            return;
-        }
-        // ③ 跳过其他控制消息（如 typing 状态、stream 信号等），只处理 kind=text 的真实用户消息
-        if (data.kind && data.kind !== 'text')
-            return;
-        // ③ 内容校验：消息既无文字内容也无附件文件时，直接丢弃
-        const hasContent = data.content?.trim();
-        const hasFiles = data.files && data.files.length > 0;
-        if (!hasContent && !hasFiles)
-            return;
-        // 去重
-        if (isDuplicate(data.msgId))
-            return;
-        // 通知框架收到入站事件，更新 lastEventAt 时间戳，防止 stale-socket 检测误判断线
-        onEvent?.();
-        log?.info(`[${CHANNEL_KEY}] Message from Agent: ${data.agentId}, ${data.from}: "${(data.content || '').slice(0, 60)}" files=${data.files?.length ?? 0}`);
-        // /stop 及自然语言 abort 不做旁路，统一交给 openclaw fast-abort。
-        const chatId = extractChatId(data);
-        handleMessage({
-            senderId: data.from,
-            text: data.content || '',
-            messageId: data.msgId,
-            files: data.files ?? [],
-            timestamp: data.timestamp,
-            agentId: data.agentId, // 透传前端指定的 agentId
-            chatId, // 透传前端指定的 chatId（多会话分桶用）
-        });
-        // ④ 异步登记当前生效的 sessionId 到 chats.json[chatId].sessionIdHistory。
-        //
-        // 为什么用 setImmediate？
-        //   - 首条消息到达时，框架还未创建 session，sessions.json 查不到该 sessionKey；
-        //   - /reset 等场景下，框架会在派发消息前 rotate sessionId，本回合的当前 sessionId
-        //     是 rotate 之后的新 ID；
-        //   - 把登记放到下一个事件循环 tick，给框架留出时序窗口（创建/rotate session）；
-        //   - 与主消息流解耦，登记失败不影响 handleMessage 主流程。
-        //
-        // 即使本次未登记成功（首条消息时 sessions.json 还没条目），下一条消息进来时
-        // 仍会再次触发本逻辑，幂等的 ensureSessionInHistory 会补登记，最终一致。
-        setImmediate(() => {
-            try {
-                recordSessionInHistory({
-                    userId: data.from,
-                    agentId: data.agentId,
-                    chatId,
-                    accountId: account.accountId,
-                    log,
-                });
-            }
-            catch (err) {
-                log?.warn(`[${CHANNEL_KEY}] recordSessionInHistory(message:private) error: ${err instanceof Error ? err.message : String(err)}`);
-            }
-        });
-    });
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    bindMessagePrivateHandler(socket, deps);
     // 事件：历史消息请求（history:request）
-    // 职责：根据用户 ID 解析 sessionKey，从本地存储读取历史消息后返回给客户端
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    socket.on(EVENT_HISTORY_REQUEST, (data, ack) => {
-        // 立即回复 ACK，告知服务端请求已收到
-        ack?.();
-        if (!data?.from) {
-            log?.warn(`[${CHANNEL_KEY}] History request missing userId, ignoring`);
-            return;
-        }
-        // 回环防御：忽略 bot 自身发出的请求
-        if (data.from === botClientId)
-            return;
-        // 去重：如果有 msgId，走消息级去重
-        if (data.msgId && isDuplicate(data.msgId)) {
-            log?.warn(`[${CHANNEL_KEY}] Duplicate history request (msgId), ignoring`);
-            return;
-        }
-        // 防抖：同一用户高频请求只处理最后一条
-        debounceHistoryRequest(data.from, () => {
-            // 通知框架收到入站事件（更新 lastEventAt，防止 stale-socket 误判）
-            onEvent?.();
-            try {
-                // 获取插件运行时，读取最新配置（支持热更新，不缓存旧配置）
-                const pluginRuntime = getLightclawRuntime();
-                const currentCfg = pluginRuntime.config.loadConfig();
-                // 通过路由解析器获取该用户对应的 Agent 路由信息
-                // resolveAgentRoute 会综合账户配置、用户 ID、渠道等信息计算出 sessionKey
-                const baseRoute = pluginRuntime.channel.routing.resolveAgentRoute({
-                    cfg: currentCfg,
-                    channel: CHANNEL_KEY,
-                    accountId: account.accountId,
-                    peer: { kind: 'direct', id: data.from },
-                });
-                // agentId 合法性校验：防止前端传入任意 agentId 访问其他 Agent 的数据
-                const currentCfgTyped = currentCfg;
-                const validAgentIds = currentCfgTyped.agents?.list?.map((a) => a.id) ?? [DEFAULT_AGENT_ID];
-                log?.info(`[${CHANNEL_KEY}], 当前合法的agentId为：${validAgentIds}`);
-                const resolvedAgentId = data.agentId && validAgentIds.includes(data.agentId) ? data.agentId : DEFAULT_AGENT_ID;
-                log?.info(`[${CHANNEL_KEY}], 当前agentId为：${resolvedAgentId}`);
-                // 始终用 effectiveAgentId 调用 buildAgentSessionKey 生成 sessionKey：
-                // - 前端传了合法 agentId → 用它；否则降级到 baseRoute.agentId（框架路由解析出的默认值）
-                //
-                // 框架生成的基础 sessionKey 形如：
-                //   agent:<agentId>:<channel>:direct:<userId>
-                // 当前端带上 chatId（多会话场景）时，需要在基础 sessionKey 末尾追加 `:<chatId>`，
-                // 形成：agent:<agentId>:<channel>:direct:<userId>:<chatId>，
-                // 以区分同一用户下的不同会话历史文件。框架本身不感知 chatId，
-                // 故在此处显式拼接，保持与写入端（chat 维度的 sessionId）一致。
-                const baseSessionKey = pluginRuntime.channel.routing.buildAgentSessionKey({
-                    agentId: resolvedAgentId,
-                    channel: CHANNEL_KEY,
-                    accountId: baseRoute.accountId,
-                    peer: { kind: 'direct', id: data.from },
-                    dmScope: 'per-channel-peer',
-                });
-                const chatIdSuffix = extractChatId(data);
-                const sessionKey = chatIdSuffix ? `${baseSessionKey}:${chatIdSuffix}` : baseSessionKey;
-                log?.info(`[${CHANNEL_KEY}] userId=${data.from}，chatId=${chatIdSuffix || '-'}，当前的sessionKey=${sessionKey}`);
-                // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-                // ① 兜底登记当前 sessionId 到 sessionIdHistory
-                //
-                // 为什么在拉历史时也做登记？—— 兜底覆盖一个边界场景：用户 reset 后没再
-                // 发过消息，只是重新打开聊天界面拉历史。此时 message:private 的登记
-                // 路径不会被触发，仅靠这里能补登记，确保历史不丢。
-                //
-                // 必须先于读历史，因为读历史依赖 sessionIdHistory 来合并多份 jsonl，
-                // 当前 sessionId 也要一起读到。
-                // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-                try {
-                    const store = loadSessionStore(resolvedAgentId);
-                    const currentSessionId = store[sessionKey]?.sessionId;
-                    if (currentSessionId) {
-                        ensureSessionInHistory(resolvedAgentId, data.from, chatIdSuffix, currentSessionId);
-                    }
-                }
-                catch (err) {
-                    log?.warn(`[${CHANNEL_KEY}] ensureSessionInHistory(history:request) error: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-                // ② 读取历史消息：优先按 sessionIdHistory 合并多份 jsonl（跨 reset 历史回看）
-                //
-                // - chats.json 命中（含 chatId === '' 的默认对话兜底条目）：
-                //     把该 chat 用过的所有 sessionId（含归档的旧 sessionId）的 jsonl
-                //     全部读出来按 timestamp 合并；
-                // - 否则：退化到原来的"按 sessionKey 读当前 jsonl + cron 合并"路径，
-                //   保持向后兼容（chats.json 不存在 / 解析异常等极端场景）。
-                // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-                const limit = data.limit ?? DEFAULT_HISTORY_LIMIT;
-                const chatOnly = data.chatOnly ?? true;
-                let messages = [];
-                let readMode = 'single-session-with-cron';
-                try {
-                    // 查询侧使用与登记侧同一个 chatId（已在 extractChatId 统一归一）。
-                    const targetChatId = chatIdSuffix;
-                    const chatsPath = resolveChatsFilePath(resolvedAgentId, data.from);
-                    // 这里使用**纯只读**的 readChatsFile：
-                    //   - 拉历史是只读接口，不应该在用户还没发任何消息前就把
-                    //     chats.json 写到磁盘（避免凭空出现一个默认对话）；
-                    //   - 如果是默认对话首次消息后拉历史，前面的 ensureSessionInHistory
-                    //     已经走 readChatsFileOrInitDefault 打点过 chats.json，这里能读到。
-                    const matched = readChatsFile(chatsPath).find((c) => c.chatId === targetChatId);
-                    const historyIds = matched?.sessionIdHistory ?? [];
-                    if (historyIds.length > 0) {
-                        messages = readSessionHistoriesByIds(historyIds, {
-                            limit,
-                            chatOnly,
-                            agentId: resolvedAgentId,
-                        });
-                        readMode = 'multi-session';
-                    }
-                }
-                catch (err) {
-                    log?.warn(`[${CHANNEL_KEY}] readSessionHistoriesByIds fallback to single-session: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                if (messages.length === 0 && readMode !== 'multi-session') {
-                    // 退路 / 兜底：仅当未走多 sessionId 合并路径时，退化到按当前 sessionKey 读（含 cron 合并）。
-                    // 已走 multi-session 但消息为空，意味着 chats.json 里 sessionIdHistory 全部 jsonl 都没内容，
-                    // 这是合理的"空历史"状态，不应再退回 single-session 路径，避免重复 cron 拼接的副作用。
-                    messages = readSessionHistoryWithCron(sessionKey, {
-                        limit,
-                        chatOnly,
-                        includeCron: true,
-                        agentId: resolvedAgentId,
-                    });
-                }
-                log?.info(`[${CHANNEL_KEY}] History request: userId=${data.from} sessionKey=${sessionKey} mode=${readMode} found=${messages.length}`);
-                // 过滤掉内容为空的消息（既无文字也无附件），避免客户端渲染空气泡
-                const historyMsgId = generateMsgId();
-                reliableEmitter.emitWithAck(EVENT_HISTORY_RESPONSE, {
-                    msgId: historyMsgId,
-                    from: botClientId,
-                    to: data.from,
-                    sessionKey,
-                    messages: messages.filter((msg) => !!msg.content.trim() || (msg.files && msg.files.length > 0)),
-                    agentId: resolvedAgentId,
-                }, historyMsgId);
-            }
-            catch (err) {
-                // 查询失败时返回空列表 + 错误信息，客户端可据此展示错误提示
-                log?.error(`[${CHANNEL_KEY}] History request error: ${err}`);
-                const errorMsgId = generateMsgId();
-                reliableEmitter.emitWithAck(EVENT_HISTORY_RESPONSE, {
-                    msgId: errorMsgId,
-                    from: botClientId,
-                    to: data.from,
-                    sessionKey: '',
-                    messages: [],
-                    error: err instanceof Error ? err.message : String(err),
-                    agentId: data.agentId || DEFAULT_AGENT_ID,
-                }, errorMsgId);
-            }
-        });
+    bindHistoryRequestHandler(socket, {
+        account: deps.account,
+        botClientId,
+        reliableEmitter,
+        onEvent,
     });
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     // 事件：Agents 列表请求（agents:request）
-    // 职责：读取 openclaw.json 中 agents.list，并在单 agent 场景补齐默认 main（支持热更新，不缓存）
-    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-    socket.on(EVENT_AGENTS_REQUEST, (data, ack) => {
-        // 立即回复 ACK，告知服务端请求已收到
-        ack?.();
-        if (data.from === botClientId)
-            return;
-        // 通知框架收到入站事件（更新 lastEventAt，防止 stale-socket 误判）
-        onEvent?.();
-        try {
-            // 获取插件运行时，读取最新配置
-            const pluginRuntime = getLightclawRuntime();
-            const currentCfg = pluginRuntime.config.loadConfig();
-            const agentsList = normalizeAgentsWithMainAgent(currentCfg);
-            let agentsWithSoulIds = agentsList;
-            try {
-                agentsWithSoulIds = attachSoulIdsToAgents(agentsList, readSoulIdMap());
-            }
-            catch (soulErr) {
-                log?.warn(`[${CHANNEL_KEY}] Failed to read soul config ${LIGHTSOUL_CONFIG_PATH}: ${soulErr instanceof Error ? soulErr.message : String(soulErr)}`);
-            }
-            log?.info(`[${CHANNEL_KEY}] Agents request: count=${agentsWithSoulIds.length}`);
-            const agentsMsgId = generateMsgId();
-            reliableEmitter.emitWithAck(EVENT_AGENTS_RESPONSE, {
-                msgId: agentsMsgId,
-                to: data.from,
-                from: botClientId,
-                agents: agentsWithSoulIds,
-                timestamp: Date.now(),
-            }, agentsMsgId);
-        }
-        catch (err) {
-            log?.error(`[${CHANNEL_KEY}] Agents request error: ${err}`);
-            const agentsErrMsgId = generateMsgId();
-            reliableEmitter.emitWithAck(EVENT_AGENTS_RESPONSE, {
-                msgId: agentsErrMsgId,
-                from: botClientId,
-                to: data.from,
-                agents: [],
-                error: err instanceof Error ? err.message : String(err),
-                timestamp: Date.now(),
-            }, agentsErrMsgId);
-        }
+    bindAgentsRequestHandler(socket, {
+        botClientId,
+        reliableEmitter,
+        onEvent,
     });
-    socket.on(EVENT_CHAT_REQUEST, (data, ack) => {
-        ack?.();
-        log?.info(`[${CHANNEL_KEY}] Received chat request from ${data.from}: ${data.type}`);
-        if (!data?.from) {
-            log?.warn(`[${CHANNEL_KEY}] Chat request missing userId, ignoring`);
-            return;
-        }
-        // 回环防御
-        if (data.from === botClientId)
-            return;
-        onEvent?.();
-        switch (data.type) {
-            case 'list':
-                handleChatList({
-                    userId: data.from,
-                    agentId: data.agentId,
-                    botClientId,
-                    reliableEmitter,
-                    log,
-                });
-                break;
-            case 'create':
-                handleChatCreate({
-                    userId: data.from,
-                    agentId: data.agentId,
-                    botClientId,
-                    reliableEmitter,
-                    log,
-                });
-                break;
-            case 'update':
-                handleChatUpdate({
-                    userId: data.from,
-                    agentId: data.agentId,
-                    chatId: data.chatId,
-                    title: data.title,
-                    botClientId,
-                    reliableEmitter,
-                    log,
-                });
-                break;
-            case 'delete':
-                handleChatDelete({
-                    userId: data.from,
-                    agentId: data.agentId,
-                    chatId: data.chatId,
-                    botClientId,
-                    reliableEmitter,
-                    log,
-                });
-                break;
-        }
+    // 事件：会话管理请求（chat:request）
+    bindChatRequestHandler(socket, {
+        botClientId,
+        reliableEmitter,
+        onEvent,
     });
-}
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// 内部工具：从 PrivateMessageData / HistoryRequestData 中统一提取 chatId
-//
-// 抽离原因：原代码同一字段在 message:private（||）、setImmediate（??）、
-// history:request（?.trim()）三处使用了三种不同写法，虽然在协议正常时结果一致，
-// 但语义有偏差且日后极易踩坑。统一为 extractChatId 后：
-//   - 入参可能是 undefined / null / 非字符串 / 含空白字符串 / 合法字符串；
-//   - 一律 trim 后归一为字符串；undefined / null / 非字符串 → ''；
-//   - 返回值要么是 ''（默认对话标识），要么是非空合法 chatId。
-// 这样写入侧（chats.json[chatId].sessionIdHistory）与读取侧（按 chatId 查询）
-// 始终拿到同一个值，杜绝因写法差异引起的"找不到 chat 条目"问题。
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-function extractChatId(data) {
-    const raw = data?.extra?.chatId;
-    if (typeof raw !== 'string')
-        return '';
-    return raw.trim();
-}
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// 内部工具：把当前 chat 在用的 sessionId 登记到 chats.json[chatId].sessionIdHistory
-//
-// 设计要点：
-//   1. 解析 sessionKey —— 与 history:request 分支保持一致：
-//        agent:<agentId>:<channel>:direct:<userId>[:<chatId>]
-//      若无 chatId 直接早返（无 chatId 的会话不在 chats.json 中登记）。
-//   2. 通过 agentId 合法性校验，避免前端伪造 agentId 污染他人 chats.json。
-//   3. 从 sessions.json 索引读出当前 sessionKey 对应的 sessionId
-//      —— 框架在派发消息前完成 mint/rotate，本时刻读到的就是"当前生效"的 sessionId。
-//   4. 调用幂等的 ensureSessionInHistory：已存在则跳过；新出现则末尾追加并落盘。
-//
-// 调用时机：
-//   - EVENT_MESSAGE_PRIVATE：在 setImmediate 中异步调用，确保框架已建好/rotate 好 session；
-//   - EVENT_HISTORY_REQUEST：在 sessionKey 解析后同步调用，作为兜底登记入口。
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-function recordSessionInHistory(params) {
-    const { userId, agentId, chatId, accountId, log } = params;
-    // 取最新配置，复用 history 分支同款 agentId 校验逻辑（防止伪造 agentId）
-    const pluginRuntime = getLightclawRuntime();
-    const currentCfg = pluginRuntime.config.loadConfig();
-    const currentCfgTyped = currentCfg;
-    const validAgentIds = currentCfgTyped.agents?.list?.map((a) => a.id) ?? [DEFAULT_AGENT_ID];
-    const resolvedAgentId = agentId && validAgentIds.includes(agentId) ? agentId : DEFAULT_AGENT_ID;
-    // 计算 sessionKey（必须与 history:request 一致，否则查不到 sessions.json 条目）
-    const baseRoute = pluginRuntime.channel.routing.resolveAgentRoute({
-        cfg: currentCfg,
-        channel: CHANNEL_KEY,
-        accountId,
-        peer: { kind: 'direct', id: userId },
+    // 事件：群组管理请求（group:request）
+    // 传入 orchestrator 用于创建群后唤醒主Agent生成欢迎消息
+    bindGroupRequestHandler(socket, {
+        botClientId,
+        reliableEmitter,
+        onEvent,
+        orchestrator,
     });
-    const baseSessionKey = pluginRuntime.channel.routing.buildAgentSessionKey({
-        agentId: resolvedAgentId,
-        channel: CHANNEL_KEY,
-        accountId: baseRoute.accountId,
-        peer: { kind: 'direct', id: userId },
-        dmScope: 'per-channel-peer',
+    // 事件：群历史消息请求（group:history:request）
+    bindGroupHistoryHandler(socket, {
+        botClientId,
+        reliableEmitter,
+        onEvent,
+    });
+    // 事件：群成员管理请求（group:member:request）
+    bindGroupMemberHandler(socket, {
+        botClientId,
+        reliableEmitter,
+        onEvent,
+    });
+    // 事件：群消息中止请求（group:abort:request）
+    bindGroupAbortHandler(socket, {
+        botClientId,
+        reliableEmitter,
+        onEvent,
+        orchestrator,
+        groupStorage,
     });
-    // 与 history:request 保持完全一致的 sessionKey 拼接规则：
-    //   - 空 chatId  → 不追加后缀，直接用 baseSessionKey（默认对话场景）
-    //   - 非空 chatId → 追加 `:<chatId>` 后缀（多会话场景）
-    // 这是写入侧已建立的约定，框架对无 chatId 会话写到 baseSessionKey 上。
-    const sessionKey = chatId ? `${baseSessionKey}:${chatId}` : baseSessionKey;
-    // 查 sessions.json 拿当前生效 sessionId；首条消息时可能查不到 → 跳过，下一条消息会补登记
-    const store = loadSessionStore(resolvedAgentId);
-    const currentSessionId = store[sessionKey]?.sessionId;
-    if (!currentSessionId) {
-        log?.info(`[${CHANNEL_KEY}] recordSessionInHistory: sessionId not found yet, skip. sessionKey=${sessionKey}`);
-        return;
-    }
-    // 登记 sessionId 到 chats.json，确保历史记录能被查到；已存在则跳过，新增则末尾追加并落盘
-    ensureSessionInHistory(resolvedAgentId, userId, chatId, currentSessionId);
-}
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// 文件下载处理器（kind=file:download, status=download_req）
-//
-// 流程：
-//   1. 从 data.extra.transferData 解析 transferId / localPath
-//   2. 基础校验：必须是绝对路径，文件必须存在
-//   3. 先回告 download_ready 帧（transferId + 文件元数据），前端据此更新下载按钮状态
-//   4. 通过 uploadFileToServer 将本机文件上传到 ai-server，拿到下载 URL
-//   5. 回告 download_url 帧（transferId + url），前端触发浏览器原生下载
-//   6. 任一阶段失败 → 回告 download_error 帧（transferId + error message）
-//
-// 备注：不走目录白名单校验，因为 localPath 来自 AI 工具返回的 localfile:// 链接，
-// AI 只会返回自己刚写盘的文件；上传到 ai-server 后会经过一轮内容审核兜底。
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-async function handleFileDownloadReq(data, botClientId, reliableEmitter, account, log) {
-    const transferData = data.extra?.transferData;
-    const transferId = transferData?.transferId;
-    const localPath = transferData?.localPath;
-    log?.info(`[${CHANNEL_KEY}] file:download(req) received: transferId=${transferId}, localPath=${localPath}, from=${data.from}`);
-    const sendError = (error) => {
-        const msgId = generateMsgId();
-        reliableEmitter.emitWithAck(EVENT_MESSAGE_PRIVATE, {
-            msgId,
-            from: botClientId,
-            to: data.from,
-            content: '',
-            timestamp: Date.now(),
-            kind: KIND_FILE_DOWNLOAD,
-            extra: {
-                chatId: extractChatId(data),
-                transferData: { transferId, status: FILE_DOWNLOAD_STATUS.ERROR, error },
-            },
-        }, msgId);
-        log?.error(`[${CHANNEL_KEY}] file:download(error) sent: transferId=${transferId}, error=${error}`);
-    };
-    if (!transferId || !localPath) {
-        sendError('Missing transferId or localPath in extra.transferData');
-        return;
-    }
-    // 基础校验：必须是绝对路径
-    if (!path.isAbsolute(localPath)) {
-        sendError(`localPath must be an absolute path: ${localPath}`);
-        return;
-    }
-    const resolvedPath = path.resolve(localPath);
-    if (!fs.existsSync(resolvedPath)) {
-        sendError(`File not found: ${resolvedPath}`);
-        return;
-    }
-    const stat = fs.statSync(resolvedPath);
-    if (!stat.isFile()) {
-        sendError(`Not a regular file: ${resolvedPath}`);
-        return;
-    }
-    const fileName = path.basename(resolvedPath);
-    const mimeType = guessMimeByExt(path.extname(fileName).toLowerCase()) || 'application/octet-stream';
-    // 回告 download_ready（文件确认存在 + 元数据）
-    const readyMsgId = generateMsgId();
-    reliableEmitter.emitWithAck(EVENT_MESSAGE_PRIVATE, {
-        msgId: readyMsgId,
-        from: botClientId,
-        to: data.from,
-        content: '',
-        timestamp: Date.now(),
-        kind: KIND_FILE_DOWNLOAD,
-        extra: {
-            chatId: extractChatId(data),
-            transferData: {
-                transferId,
-                status: FILE_DOWNLOAD_STATUS.READY,
-                name: fileName,
-                size: stat.size,
-                contentType: mimeType,
-            },
-        },
-    }, readyMsgId);
-    log?.info(`[${CHANNEL_KEY}] file:download(ready) sent: transferId=${transferId}, name=${fileName}, size=${stat.size}`);
-    // 上传本机文件到 ai-server（含审核），成功后把 URL 回告前端
-    try {
-        // 通过 senderId 解析真实 apiKey，用于 /drive/save 鉴权
-        const apiKey = account.apiKey;
-        const uploadResult = await uploadFileToServer(resolvedPath, { apiKey });
-        if (!uploadResult.isUploaded || !uploadResult.url) {
-            sendError('Upload to ai-server failed');
-            return;
-        }
-        const urlMsgId = generateMsgId();
-        reliableEmitter.emitWithAck(EVENT_MESSAGE_PRIVATE, {
-            msgId: urlMsgId,
-            from: botClientId,
-            to: data.from,
-            content: '',
-            timestamp: Date.now(),
-            kind: KIND_FILE_DOWNLOAD,
-            extra: {
-                chatId: extractChatId(data),
-                transferData: {
-                    transferId,
-                    status: FILE_DOWNLOAD_STATUS.URL,
-                    url: uploadResult.url,
-                    name: fileName,
-                    size: stat.size,
-                    contentType: mimeType,
-                },
-            },
-        }, urlMsgId);
-        log?.info(`[${CHANNEL_KEY}] file:download(url) sent: transferId=${transferId}, url=${uploadResult.url}`);
-    }
-    catch (err) {
-        sendError(err instanceof Error ? err.message : String(err));
-    }
 }