lightclawbot 1.2.6 → 1.2.7

package/dist/src/socket/events/file-download.js

@@ -0,0 +1,121 @@
+/**
+ * 文件下载处理器（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）
+ */
+import { CHANNEL_KEY, EVENT_MESSAGE_PRIVATE, KIND_FILE_DOWNLOAD, FILE_DOWNLOAD_STATUS, } from '../../config.js';
+import { generateMsgId } from '../../dedup.js';
+import { uploadFileToServer } from '../../file-storage.js';
+import { guessMimeByExt } from '../../media.js';
+import { extractChatId } from '../utils/message.js';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getModuleLogger } from '../../utils/logger.js';
+/** 模块级日志器 */
+const log = getModuleLogger('socket.file-download');
+/**
+ * 处理文件下载请求
+ */
+export async function handleFileDownloadReq(data, botClientId, reliableEmitter, account) {
+    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 {
+        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));
+    }
+}

package/dist/src/socket/events/group-abort.js

@@ -0,0 +1,59 @@
+/**
+ * @file group-abort.ts
+ * @description 群消息中止请求处理器
+ *
+ * 监听 group:abort:request 事件，对请求进行必填字段校验、
+ * 自身消息过滤、去重判断后，委托给 handleGroupAbort 执行中止逻辑。
+ */
+import { CHANNEL_KEY } from '../../config.js';
+import { isDuplicate } from '../../dedup.js';
+import { handleGroupAbort } from '../service/group-abort.js';
+import { EVENT_GROUP_ABORT_REQUEST } from '../../group/constants/index.js';
+import { getModuleLogger } from '../../utils/logger.js';
+import { hasRequiredFields, getMissingFields } from '../utils/validate.js';
+/** 模块级日志器 */
+const log = getModuleLogger('socket.group-abort-handler');
+/** 中止请求的必填字段列表 */
+const REQUIRED_FIELDS = ['from', 'msgId', 'groupId', 'conversationId'];
+/**
+ * 注册 group:abort:request 事件监听器
+ *
+ * 处理流程：确认消息 → 校验必填字段 → 过滤自身消息 → 去重 → 委托 service 处理
+ *
+ * @param socket - 原生 Socket 实例
+ * @param deps - 依赖项（botClientId、reliableEmitter、orchestrator 等）
+ */
+export function bindGroupAbortHandler(socket, deps) {
+    const { botClientId, reliableEmitter, onEvent, orchestrator, groupStorage } = deps;
+    socket.on(EVENT_GROUP_ABORT_REQUEST, (data, ack) => {
+        // 立即确认收到消息
+        ack?.();
+        // 校验必填字段，明确记录缺失项
+        if (!hasRequiredFields(data, REQUIRED_FIELDS)) {
+            const missing = getMissingFields(data, REQUIRED_FIELDS);
+            log.warn(`[${CHANNEL_KEY}] 中止群消息请求缺少必填字段: [${missing.join(', ')}]，已忽略`);
+            return;
+        }
+        // 忽略自身发出的请求，防止回环
+        if (data.from === botClientId)
+            return;
+        // 去重：同一 msgId 的请求只处理一次
+        if (isDuplicate(`group:abort:${data.msgId}`)) {
+            log.warn(`[${CHANNEL_KEY}] 重复的群中止请求 (msgId=${data.msgId})，已忽略`);
+            return;
+        }
+        log.info(`[${CHANNEL_KEY}] 收到中止群消息请求: from=${data.from}, groupId=${data.groupId}, conversationId=${data.conversationId}`);
+        // 触发外部事件回调（如心跳续期）
+        onEvent?.();
+        void handleGroupAbort({
+            userId: data.from,
+            botClientId,
+            reliableEmitter,
+            requestMsgId: data.msgId,
+            groupId: data.groupId,
+            conversationId: data.conversationId,
+            orchestrator,
+            storage: groupStorage,
+        });
+    });
+}

package/dist/src/socket/events/group-history.js

@@ -0,0 +1,59 @@
+/**
+ * @file group-history.ts
+ * @description 群历史消息请求处理器
+ *
+ * 监听 group:history:request 事件，对请求进行必填字段校验（并报告缺失字段）、
+ * 自身消息过滤、去重判断后，委托给 handleGroupHistory 查询并返回历史消息。
+ */
+import { CHANNEL_KEY } from '../../config.js';
+import { isDuplicate } from '../../dedup.js';
+import { handleGroupHistory } from '../service/group-history.js';
+import { EVENT_GROUP_HISTORY_REQUEST } from '../../group/constants/index.js';
+import { getModuleLogger } from '../../utils/logger.js';
+import { hasRequiredFields, getMissingFields } from '../utils/validate.js';
+/** 模块级日志器 */
+const log = getModuleLogger('socket.group-history-handler');
+/** 群历史消息请求的必填字段列表 */
+const REQUIRED_FIELDS = ['from', 'msgId', 'groupId'];
+/**
+ * 注册 group:history:request 事件监听器
+ *
+ * 处理流程：确认消息 → 校验必填字段（报告缺失详情） → 过滤自身消息 → 去重 → 委托 service 查询历史
+ *
+ * @param socket - 原生 Socket 实例
+ * @param deps - 依赖项（botClientId、reliableEmitter、onEvent 回调）
+ */
+export function bindGroupHistoryHandler(socket, deps) {
+    const { botClientId, reliableEmitter, onEvent } = deps;
+    socket.on(EVENT_GROUP_HISTORY_REQUEST, (data, ack) => {
+        // 立即确认收到消息
+        ack?.();
+        // 校验必填字段，缺失时输出具体字段名称便于排查
+        if (!hasRequiredFields(data, REQUIRED_FIELDS)) {
+            const missing = getMissingFields(data, REQUIRED_FIELDS);
+            log.warn(`[${CHANNEL_KEY}] 群历史消息请求缺少必填字段: [${missing.join(', ')}]，已忽略`);
+            return;
+        }
+        // 忽略自身发出的请求，防止回环
+        if (data.from === botClientId)
+            return;
+        // 去重：同一 msgId 的请求只处理一次
+        if (isDuplicate(`group:history:${data.msgId}`)) {
+            log.warn(`[${CHANNEL_KEY}] 重复的群历史消息请求 (msgId=${data.msgId})，已忽略`);
+            return;
+        }
+        log.info(`[${CHANNEL_KEY}] 收到群历史消息请求: from=${data.from}, groupId=${data.groupId}, limit=${data.limit ?? '-'}, before=${data.before ?? '-'}, chatOnly=${data.chatOnly ?? '-'}`);
+        // 触发外部事件回调（如心跳续期）
+        onEvent?.();
+        void handleGroupHistory({
+            userId: data.from,
+            botClientId,
+            reliableEmitter,
+            requestMsgId: data.msgId,
+            groupId: data.groupId,
+            limit: data.limit,
+            before: data.before,
+            chatOnly: data.chatOnly,
+        });
+    });
+}

package/dist/src/socket/events/group-member.js

@@ -0,0 +1,83 @@
+/**
+ * @file group-member.ts
+ * @description 群成员管理请求处理器（group:member:request）
+ *
+ * 监听 group:member:request 事件，对请求进行必填字段校验（并报告缺失字段）、
+ * 自身消息过滤、去重判断后，根据 type 分发到 add/remove handler。
+ */
+import { CHANNEL_KEY } from '../../config.js';
+import { isDuplicate } from '../../dedup.js';
+import { handleGroupMemberAdd, handleGroupMemberRemove, handleGroupMemberUpdate } from '../service/group-member.js';
+import { EVENT_GROUP_MEMBER_REQUEST } from '../../group/constants/index.js';
+import { getModuleLogger } from '../../utils/logger.js';
+import { hasRequiredFields, getMissingFields } from '../utils/validate.js';
+/** 模块级日志器 */
+const log = getModuleLogger('socket.group-member-handler');
+/** 基础必填字段列表（所有操作类型共用） */
+const BASE_REQUIRED_FIELDS = ['from', 'msgId', 'type'];
+/** add/remove 操作额外必填字段 */
+const MEMBER_OP_REQUIRED_FIELDS = ['from', 'msgId', 'type', 'groupId', 'agentId'];
+/**
+ * 根据成员操作类型分发到对应的 service handler
+ * @param data - 请求数据
+ * @param botClientId - Bot 客户端 ID
+ * @param reliableEmitter - 可靠消息发射器
+ */
+function dispatchMemberHandler(data, botClientId, reliableEmitter) {
+    const baseCtx = {
+        userId: data.from,
+        botClientId,
+        reliableEmitter,
+        requestMsgId: data.msgId,
+        groupId: data.groupId,
+        agentId: data.agentId,
+        extra: data.extra,
+    };
+    switch (data.type) {
+        case 'add':
+            void handleGroupMemberAdd(baseCtx);
+            break;
+        case 'remove':
+            void handleGroupMemberRemove(baseCtx);
+            break;
+        case 'update':
+            void handleGroupMemberUpdate(baseCtx);
+            break;
+        default:
+            log.warn(`[${CHANNEL_KEY}] 未知的群成员操作类型: ${data.type}`);
+    }
+}
+/**
+ * 注册 group:member:request 事件监听器
+ *
+ * 处理流程：确认消息 → 校验必填字段（报告缺失详情） → 过滤自身消息 → 去重 → 分发到对应 handler
+ *
+ * @param socket - 原生 Socket 实例
+ * @param deps - 依赖项（botClientId、reliableEmitter、onEvent 回调）
+ */
+export function bindGroupMemberHandler(socket, deps) {
+    const { botClientId, reliableEmitter, onEvent } = deps;
+    socket.on(EVENT_GROUP_MEMBER_REQUEST, (data, ack) => {
+        // 立即确认收到消息
+        ack?.();
+        // 校验必填字段，update 类型不需要 groupId 和 agentId
+        const requiredFields = data.type === 'update' ? BASE_REQUIRED_FIELDS : MEMBER_OP_REQUIRED_FIELDS;
+        if (!hasRequiredFields(data, requiredFields)) {
+            const missing = getMissingFields(data, requiredFields);
+            log.warn(`[${CHANNEL_KEY}] 群成员请求缺少必填字段: [${missing.join(', ')}]，已忽略`);
+            return;
+        }
+        // 忽略自身发出的请求，防止回环
+        if (data.from === botClientId)
+            return;
+        // 去重：同一 msgId 的请求只处理一次
+        if (isDuplicate(`group:member:${data.msgId}`)) {
+            log.warn(`[${CHANNEL_KEY}] 重复的群成员请求 (msgId=${data.msgId})，已忽略`);
+            return;
+        }
+        log.info(`[${CHANNEL_KEY}] 收到群成员请求: from=${data.from}, type=${data.type}, groupId=${data.groupId}, agentId=${data.agentId}`);
+        // 触发外部事件回调（如心跳续期）
+        onEvent?.();
+        dispatchMemberHandler(data, botClientId, reliableEmitter);
+    });
+}

package/dist/src/socket/events/group-request.js

@@ -0,0 +1,91 @@
+/**
+ * @file group-request.ts
+ * @description 群组管理请求处理器（group:request）
+ *
+ * 监听 group:request 事件，对请求进行必填字段校验（并报告缺失字段）、
+ * 自身消息过滤、去重判断后，根据 type 分发到 list/create/update/delete/clear handler。
+ */
+import { CHANNEL_KEY } from '../../config.js';
+import { isDuplicate } from '../../dedup.js';
+import { handleGroupList, handleGroupCreate, handleGroupUpdate, handleGroupDelete, handleGroupClear, } from '../service/group.js';
+import { EVENT_GROUP_REQUEST } from '../../group/constants/index.js';
+import { getModuleLogger } from '../../utils/logger.js';
+import { hasRequiredFields, getMissingFields } from '../utils/validate.js';
+/** 模块级日志器 */
+const log = getModuleLogger('socket.group-request');
+/** 必填字段列表 */
+const REQUIRED_FIELDS = ['from', 'msgId', 'type'];
+/**
+ * 根据群组操作类型分发到对应的 service handler
+ * @param data - 请求数据
+ * @param botClientId - Bot 客户端 ID
+ * @param reliableEmitter - 可靠消息发射器
+ */
+function dispatchGroupHandler(data, botClientId, reliableEmitter, orchestrator) {
+    const baseCtx = { userId: data.from, botClientId, reliableEmitter, requestMsgId: data.msgId };
+    switch (data.type) {
+        case 'list':
+            void handleGroupList(baseCtx);
+            break;
+        case 'create':
+            void handleGroupCreate({
+                ...baseCtx,
+                name: data.extra?.name,
+                desc: data.extra?.desc,
+                members: data.extra?.members,
+                defaultAgentId: data.extra?.defaultAgentId,
+                orchestrator,
+            });
+            break;
+        case 'update':
+            void handleGroupUpdate({
+                ...baseCtx,
+                groupId: data.groupId,
+                name: data.extra?.name,
+                desc: data.extra?.desc,
+                pinned: data.extra?.pinned,
+            });
+            break;
+        case 'delete':
+            void handleGroupDelete({ ...baseCtx, groupId: data.groupId });
+            break;
+        case 'clear':
+            void handleGroupClear({ ...baseCtx, groupId: data.groupId });
+            break;
+        default:
+            log.warn(`[${CHANNEL_KEY}] 未知的群组操作类型: ${data.type}`);
+    }
+}
+/**
+ * 注册 group:request 事件监听器
+ *
+ * 处理流程：确认消息 → 校验必填字段（报告缺失详情） → 过滤自身消息 → 去重 → 分发到对应 handler
+ *
+ * @param socket - 原生 Socket 实例
+ * @param deps - 依赖项（botClientId、reliableEmitter、onEvent 回调）
+ */
+export function bindGroupRequestHandler(socket, deps) {
+    const { botClientId, reliableEmitter, onEvent, orchestrator } = deps;
+    socket.on(EVENT_GROUP_REQUEST, (data, ack) => {
+        // 立即确认收到消息
+        ack?.();
+        // 校验必填字段，缺失时输出具体字段名称便于排查
+        if (!hasRequiredFields(data, REQUIRED_FIELDS)) {
+            const missing = getMissingFields(data, REQUIRED_FIELDS);
+            log.warn(`[${CHANNEL_KEY}] 群组请求缺少必填字段: [${missing.join(', ')}]，已忽略`);
+            return;
+        }
+        // 忽略自身发出的请求，防止回环
+        if (data.from === botClientId)
+            return;
+        // 去重：同一 msgId 的请求只处理一次
+        if (isDuplicate(`group:${data.msgId}`)) {
+            log.warn(`[${CHANNEL_KEY}] 重复的群组请求 (msgId=${data.msgId})，已忽略`);
+            return;
+        }
+        log.info(`[${CHANNEL_KEY}] 收到群组请求: from=${data.from}, type=${data.type}, groupId=${data.groupId ?? '-'}`);
+        // 触发外部事件回调（如心跳续期）
+        onEvent?.();
+        dispatchGroupHandler(data, botClientId, reliableEmitter, orchestrator);
+    });
+}

package/dist/src/socket/events/history-request.js

@@ -0,0 +1,95 @@
+/**
+ * @file history-request.ts
+ * @description 私聊历史消息请求处理器（history:request）
+ *
+ * 监听 history:request 事件，对请求进行必填字段校验、
+ * 自身消息过滤、去重与防抖后，委托给 queryPrivateHistory 执行查询，
+ * 并通过 reliableEmitter 回包（成功/失败统一格式）。
+ */
+import { CHANNEL_KEY, EVENT_HISTORY_REQUEST, EVENT_HISTORY_RESPONSE, DEFAULT_AGENT_ID } from '../../config.js';
+import { isDuplicate, debounceHistoryRequest, generateMsgId } from '../../dedup.js';
+import { queryPrivateHistory } from '../service/history.js';
+import { getModuleLogger } from '../../utils/logger.js';
+/** 模块级日志器 */
+const log = getModuleLogger('socket.history-request');
+/**
+ * 发送历史消息查询成功响应
+ * @param reliableEmitter - 可靠消息发射器
+ * @param botClientId - Bot 客户端 ID
+ * @param userId - 请求方用户 ID
+ * @param result - 查询结果
+ */
+function emitSuccessResponse(reliableEmitter, botClientId, userId, result) {
+    const msgId = generateMsgId();
+    const payload = {
+        msgId,
+        from: botClientId,
+        to: userId,
+        sessionKey: result.sessionKey,
+        messages: result.messages,
+        agentId: result.agentId,
+    };
+    reliableEmitter.emitWithAck(EVENT_HISTORY_RESPONSE, payload, msgId);
+}
+/**
+ * 发送历史消息查询失败响应
+ * @param reliableEmitter - 可靠消息发射器
+ * @param botClientId - Bot 客户端 ID
+ * @param userId - 请求方用户 ID
+ * @param agentId - 请求中的 agentId（兜底为默认值）
+ * @param err - 错误对象
+ */
+function emitErrorResponse(reliableEmitter, botClientId, userId, agentId, err) {
+    const msgId = generateMsgId();
+    const payload = {
+        msgId,
+        from: botClientId,
+        to: userId,
+        sessionKey: '',
+        messages: [],
+        agentId,
+        error: err instanceof Error ? err.message : String(err),
+    };
+    reliableEmitter.emitWithAck(EVENT_HISTORY_RESPONSE, payload, msgId);
+}
+/**
+ * 注册 history:request 事件监听器
+ *
+ * 处理流程：确认消息 → 校验 from 字段 → 过滤自身消息 → 去重 → 防抖 → 查询 → 回包
+ *
+ * @param socket - 原生 Socket 实例
+ * @param deps - 依赖项
+ */
+export function bindHistoryRequestHandler(socket, deps) {
+    const { account, botClientId, reliableEmitter, onEvent } = deps;
+    socket.on(EVENT_HISTORY_REQUEST, (data, ack) => {
+        // 立即确认收到消息
+        ack?.();
+        // 校验必填字段
+        if (!data?.from) {
+            log.warn(`[${CHANNEL_KEY}] 历史消息请求缺少 from 字段，已忽略`);
+            return;
+        }
+        // 忽略自身发出的请求，防止回环
+        if (data.from === botClientId)
+            return;
+        // 去重：同一 msgId 的请求只处理一次
+        if (data.msgId && isDuplicate(`history:${data.msgId}`)) {
+            log.warn(`[${CHANNEL_KEY}] 重复的历史消息请求 (msgId=${data.msgId})，已忽略`);
+            return;
+        }
+        // 防抖：同一用户高频请求只处理最后一条
+        debounceHistoryRequest(data.from, () => {
+            // 触发外部事件回调（如心跳续期）
+            onEvent?.();
+            try {
+                const result = queryPrivateHistory(data, account);
+                emitSuccessResponse(reliableEmitter, botClientId, data.from, result);
+            }
+            catch (err) {
+                log.error(`[${CHANNEL_KEY}] 历史消息查询失败: ${err instanceof Error ? err.message : String(err)}`);
+                emitErrorResponse(reliableEmitter, botClientId, data.from, data.agentId || DEFAULT_AGENT_ID, err);
+            }
+        });
+    });
+}

package/dist/src/socket/events/index.js

@@ -0,0 +1,39 @@
+/**
+ * @file index.ts
+ * @description Socket 事件处理器子模块统一导出入口
+ *
+ * 本模块作为 socket/events 目录的桶文件（barrel），集中导出：
+ * - 类型定义：各事件处理器所需的依赖接口和请求数据类型
+ * - 工具函数：消息判断、会话 ID 提取、历史记录等通用工具
+ * - 事件绑定器：各类 Socket 事件的监听注册函数
+ */
+/**
+ * 工具函数导出 —— 消息处理相关的通用工具
+ *
+ * - isGroupMessage: 判断消息是否为群消息
+ * - extractChatId: 从消息中提取会话 ID
+ * - recordSessionInHistory: 将当前会话记录到历史存储
+ */
+export { isGroupMessage, extractChatId, recordSessionInHistory } from '../utils/message.js';
+/**
+ * 事件绑定器导出 —— 各 Socket 事件的监听注册函数
+ *
+ * - bindAgentsRequestHandler: 注册 agents 列表请求事件监听
+ * - handleFileDownloadReq: 处理文件下载请求
+ * - bindMessagePrivateHandler: 注册私聊消息事件监听
+ * - bindHistoryRequestHandler: 注册私聊历史消息请求事件监听
+ * - bindChatRequestHandler: 注册聊天请求事件监听
+ * - bindGroupRequestHandler: 注册群聊请求事件监听
+ * - bindGroupHistoryHandler: 注册群历史消息请求事件监听
+ * - bindGroupMemberHandler: 注册群成员变更事件监听
+ * - bindGroupAbortHandler: 注册群中止请求事件监听
+ */
+export { bindAgentsRequestHandler } from './agents-request.js';
+export { handleFileDownloadReq } from './file-download.js';
+export { bindMessagePrivateHandler } from './message-private.js';
+export { bindHistoryRequestHandler } from './history-request.js';
+export { bindChatRequestHandler } from './chat-request.js';
+export { bindGroupRequestHandler } from './group-request.js';
+export { bindGroupHistoryHandler } from './group-history.js';
+export { bindGroupMemberHandler } from './group-member.js';
+export { bindGroupAbortHandler } from './group-abort.js';

package/dist/src/socket/events/message-private.js

@@ -0,0 +1,82 @@
+/**
+ * 私信消息处理器（message:private）
+ *
+ * 职责：对消息做多层过滤，将合法消息放入处理队列
+ */
+import { CHANNEL_KEY, EVENT_MESSAGE_PRIVATE, KIND_FILE_DOWNLOAD, FILE_DOWNLOAD_STATUS } from '../../config.js';
+import { isDuplicate } from '../../dedup.js';
+import { isGroupMessage, extractChatId, recordSessionInHistory } from '../utils/message.js';
+import { handleFileDownloadReq } from './file-download.js';
+import { getModuleLogger } from '../../utils/logger.js';
+const log = getModuleLogger('socket.message-private');
+/** 生成私聊消息去重 key */
+const dedupKey = (msgId) => `private:${msgId}`;
+/** 判断消息是否包含有效内容（文字或附件） */
+function hasValidPayload(data) {
+    return !!(data.content?.trim() || (data.files && data.files.length > 0));
+}
+/** 处理私聊文本消息（非群聊分支） */
+function handlePrivateTextMessage(data, deps) {
+    const { account, handleMessage } = deps;
+    const chatId = extractChatId(data);
+    handleMessage({
+        senderId: data.from,
+        text: data.content || '',
+        messageId: data.msgId,
+        files: data.files ?? [],
+        timestamp: data.timestamp,
+        agentId: data.agentId,
+        chatId,
+    });
+    // 异步登记 sessionId 到历史记录
+    setImmediate(() => {
+        try {
+            recordSessionInHistory({
+                userId: data.from,
+                agentId: data.agentId,
+                chatId,
+                accountId: account.accountId,
+            });
+        }
+        catch (err) {
+            log.warn(`[${CHANNEL_KEY}] recordSessionInHistory 失败: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}
+/** 注册 message:private 事件监听 */
+export function bindMessagePrivateHandler(socket, deps) {
+    const { botClientId, onEvent, reliableEmitter, account, handleGroupMessage } = deps;
+    socket.on(EVENT_MESSAGE_PRIVATE, (data, ack) => {
+        ack?.();
+        // ① 回环防御：过滤 bot 自身发出的消息
+        if (data.from === botClientId)
+            return;
+        // ② 文件下载信令分发（独立链路，不入 AI 处理队列）
+        if (data.kind === KIND_FILE_DOWNLOAD) {
+            const status = data.extra?.transferData?.status;
+            if (status === FILE_DOWNLOAD_STATUS.REQ && !isDuplicate(dedupKey(data.msgId))) {
+                onEvent?.();
+                void handleFileDownloadReq(data, botClientId, reliableEmitter, account);
+            }
+            return;
+        }
+        // ③ 跳过非文本控制消息
+        if (data.kind && data.kind !== 'text')
+            return;
+        // ④ 内容校验 + 去重
+        if (!hasValidPayload(data))
+            return;
+        if (isDuplicate(dedupKey(data.msgId)))
+            return;
+        onEvent?.();
+        // ⑤ 群聊/私聊分流
+        if (isGroupMessage(data)) {
+            handleGroupMessage(data);
+            log.info(`[${CHANNEL_KEY}] 处理群聊消息: groupId=${data?.extra?.groupId}, from=${data.from}, content="${(data.content || '').slice(0, 60)}", files=${data.files?.length ?? 0}`);
+        }
+        else {
+            log.info(`[${CHANNEL_KEY}] 处理私聊消息: agent=${data.agentId}, from=${data.from}, content="${(data.content || '').slice(0, 60)}", files=${data.files?.length ?? 0}`);
+            handlePrivateTextMessage(data, deps);
+        }
+    });
+}