lightclawbot 1.2.6-beta.0 → 1.2.7

package/dist/src/gateway.js

@@ -19,6 +19,7 @@ import { createInboundHandler } from './inbound.js';
 import { bindSocketHandlers, registerSocket, unregisterSocket, flushPendingMessages } from './socket/index.js';
 import { ReliableEmitter } from './socket/reliable-emitter.js';
 import { buildAuthHeaders } from './utils/index.js';
+import { GroupStorageCore, Orchestrator, createGroupInboundHandler, } from './group/index.js';
 // ============================================================
 // Gateway 实例追踪（防止同一 accountId 创建多个连接）
 // ============================================================
@@ -125,7 +126,7 @@ export async function startGateway(ctx) {
     let healthHeartbeatTimer = null;
     // ---- 可靠发送器（所有出站 emit 都通过此实例） ----
     // ReliableEmitter 负责：断线时缓冲消息、重连后 flush、ACK 超时重试
-    const reliableEmitter = new ReliableEmitter(() => currentSocket, log);
+    const reliableEmitter = new ReliableEmitter(() => currentSocket);
     // ---- WebSocket 发送抽象 ----
     /**
      * 底层 emit：将 PrivateMessageData 通过 ReliableEmitter 发送给客户端。
@@ -196,10 +197,24 @@ export async function startGateway(ctx) {
     };
     /** SocketEmitter 抽象：将 emit / sendReply / sendFiles 和 botClientId 打包传给 inbound 处理器 */
     const emitter = { emit, sendReply, sendFiles, botClientId };
+    // ---- 群聊调度器装配（路径 A 全链路服务于 chatKind === 'group' 的消息） ----
+    // 多 Gateway 进程共享同一份 ~/.openclaw/groups 目录，但每 account 一份 Orchestrator
+    // （RunRegistry 是进程内存态，跨 account 互不干扰）。
+    const groupStorage = new GroupStorageCore();
+    const orchestrator = new Orchestrator({
+        accountId: account.accountId,
+        storage: groupStorage,
+        emitter,
+    });
+    const groupInboundHandler = createGroupInboundHandler({
+        emitter,
+        storage: groupStorage,
+        orchestrator,
+    });
     // ---- 入站消息处理器 ----
     // createInboundHandler 返回一个异步函数，负责处理单条用户消息（文件处理、路由、AI 分发、回复）
     const handleInboundMessage = createInboundHandler(account, emitter, log);
-    // ---- 消息处理（fire-and-forget） ----
+    // ---- 私聊消息处理（fire-and-forget） ----
     // 不做串行队列：并发/abort 由 openclaw 的 session 写锁 + followup queue 负责。
     // 这里仅兜底 inbound 自身未捕获的异常。
     const handleMessage = (msg) => {
@@ -231,6 +246,35 @@ export async function startGateway(ctx) {
             }
         })();
     };
+    // ---- 群聊消息处理 ----
+    const handleGroupMessage = (data) => {
+        if (isAborted)
+            return;
+        void (async () => {
+            try {
+                await groupInboundHandler(data);
+            }
+            catch (err) {
+                log?.error(`[${CHANNEL_KEY}] Group handler error: ${err}`);
+                try {
+                    const groupId = data.extra?.groupId;
+                    emitter.emit({
+                        msgId: generateMsgId(),
+                        from: emitter.botClientId,
+                        to: data.from,
+                        content: '群消息处理异常，请稍后重试。',
+                        timestamp: Date.now(),
+                        replyToMsgId: data.msgId,
+                        chatKind: 'group',
+                        extra: { groupId: typeof groupId === 'string' ? groupId : undefined },
+                    });
+                }
+                catch (notifyErr) {
+                    log?.error(`[${CHANNEL_KEY}] Failed to notify user about group handler error: ${notifyErr}`);
+                }
+            }
+        })();
+    };
     // ---- 生命周期 ----
     /**
      * 销毁当前 Gateway 实例，释放所有资源：
@@ -268,8 +312,6 @@ export async function startGateway(ctx) {
     const socket = new NativeSocketClient(WS_URL, {
         // 认证：ticket 作为 URL query 参数，替代 Authorization header
         path: `${SOCKET_PATH}${ticketQuery}&enableMultiLogin=false`,
-        // 注入日志对象，便于 NativeSocketClient 内部打印连接/重连/错误等诊断信息
-        log,
         logPrefix: `[${CHANNEL_KEY}:${account.accountId}:NativeSocket]`,
     });
     currentSocket = socket;
@@ -291,7 +333,7 @@ export async function startGateway(ctx) {
         // 恢复可靠发送器（断线时已 pause，重连后需要 resume 才能继续发送）
         reliableEmitter.resume();
         // 重连后 flush 断线期间缓冲的 outbound 消息（主动发送场景）
-        const { sent, failed } = flushPendingMessages(account.accountId, log);
+        const { sent, failed } = flushPendingMessages(account.accountId);
         if (sent > 0 || failed > 0) {
             log?.info(`[${CHANNEL_KEY}] Flushed buffered outbound messages: sent=${sent}, failed=${failed}`);
         }
@@ -311,10 +353,12 @@ export async function startGateway(ctx) {
     bindSocketHandlers(socket, {
         account,
         botClientId,
-        log,
         handleMessage,
         onEvent,
         reliableEmitter,
+        handleGroupMessage,
+        orchestrator,
+        groupStorage,
     });
     /**
      * 连接错误事件处理。

package/dist/src/group/constants/index.js

@@ -0,0 +1,20 @@
+/**
+ * @file 群聊事件常量定义
+ * @description 定义群聊模块中所有的事件类型和对应的消息通道名称
+ */
+/** 群组基础操作请求事件 */
+export const EVENT_GROUP_REQUEST = 'group:request';
+/** 群组基础操作响应事件 */
+export const EVENT_GROUP_RESPONSE = 'group:response';
+/** 群组成员管理请求事件 */
+export const EVENT_GROUP_MEMBER_REQUEST = 'group:member:request';
+/** 群组成员管理响应事件 */
+export const EVENT_GROUP_MEMBER_RESPONSE = 'group:member:response';
+/** 群组历史消息请求事件 */
+export const EVENT_GROUP_HISTORY_REQUEST = 'group:history:request';
+/** 群组历史消息响应事件 */
+export const EVENT_GROUP_HISTORY_RESPONSE = 'group:history:response';
+/** 群组操作中止请求事件 */
+export const EVENT_GROUP_ABORT_REQUEST = 'group:abort:request';
+/** 群组操作中止响应事件 */
+export const EVENT_GROUP_ABORT_RESPONSE = 'group:abort:response';

package/dist/src/group/inbound/index.js

@@ -0,0 +1,254 @@
+/**
+ * @file 群聊消息入站处理器
+ * @description
+ * 接收 Socket 私信消息，基于 extra.groupId 路由为群聊消息，
+ * 完成权限校验后写入账本并交由 Orchestrator 调度。
+ * 所有依赖通过 {@link GroupInboundDeps} 注入，错误通过 {@link sendError} 回发。
+ */
+import { generateMsgId } from '../../dedup.js';
+import { CHANNEL_KEY, MEDIA_MAX_BYTES, LOCALFILE_SCHEME, resolveEffectiveApiKey } from '../../config.js';
+import { normalizeMentions, guessMimeType } from '../utils/index.js';
+import { getModuleLogger } from '../../utils/logger.js';
+import { parseDataUrl, formatFileSize } from '../../media.js';
+import { downloadFileFromServer, uploadFileToServer, getFileDownloadUrl } from '../../file-storage.js';
+import { getLightclawRuntime } from '../../runtime.js';
+/**
+ * 工厂函数：基于注入的依赖创建一个群聊入站处理器。
+ *
+ * @param deps 依赖注入对象，参见 {@link GroupInboundDeps}
+ * @returns 一个可直接挂载到 Socket 私信事件上的异步处理函数
+ */
+export function createGroupInboundHandler(deps) {
+    const { emitter, storage, orchestrator } = deps;
+    const logger = getModuleLogger('group.inbound');
+    /**
+     * 以群聊系统消息的形式向指定用户回发错误提示。
+     * 内部捕获 emit 异常，确保错误回发本身不会再抛出影响主流程。
+     *
+     * @param userId        目标用户 ID
+     * @param message       错误文案
+     * @param extra         附加 extra 字段（通常包含 groupId）
+     * @param replyToMsgId  关联的原始消息 ID（用于在 UI 上展示回复关系）
+     */
+    const sendError = (userId, message, extra, replyToMsgId) => {
+        // 错误回发统一带上 streamStatus: 'failed'，便于前端流式状态机识别终态
+        const finalExtra = { ...extra, streamStatus: 'failed' };
+        try {
+            const ok = emitter.emit({
+                msgId: generateMsgId(),
+                from: emitter.botClientId,
+                to: userId,
+                content: message,
+                timestamp: Date.now(),
+                replyToMsgId,
+                chatKind: 'group',
+                extra: finalExtra,
+            });
+            if (!ok) {
+                logger.warn(`[${CHANNEL_KEY}] sendError 发送失败（socket 可能已断开）。to=${userId}`);
+            }
+        }
+        catch (err) {
+            logger.warn(`[${CHANNEL_KEY}] sendError 执行异常: ${err}`);
+        }
+    };
+    /**
+     * 实际的消息处理函数。整体流程：
+     *   1. 从 extra 解析 groupId，校验合法性；
+     *   2. 读取群元数据 meta，校验群存在且用户为拥有者；
+     *   3. 规范化 mentions；
+     *   4. 将用户消息写入 Ledger；
+     *   5. 构造 DispatchContext 并交由 Orchestrator 异步调度。
+     */
+    return async function handle(data) {
+        const userId = data.from;
+        // 统一原始触发消息 ID：缺失时本地生成一个，使 conversationId / replyToMsgId / ctx.msgId 保持一致
+        const triggerMsgId = data.msgId ?? generateMsgId();
+        // 注意：data.extra 来源于客户端，字段类型不可信，统一以 unknown 承载，由下游做严格的运行时校验。
+        const extraIn = (data.extra ?? {});
+        const groupId = extraIn.groupId;
+        // 统一日志前缀
+        const tag = `[${CHANNEL_KEY}][group=${groupId}][user=${userId}]`;
+        // —— 1. 入参校验：必须携带合法的 groupId ——
+        if (typeof groupId !== 'string' || !groupId.trim()) {
+            logger.warn(`[${tag}] 群消息缺少 groupId，无法处理。msgId=${triggerMsgId} from=${userId}`);
+            sendError(userId, '群消息缺少 groupId，无法处理', {}, triggerMsgId);
+            return;
+        }
+        // —— 2. 读取群元数据 ——
+        let meta;
+        try {
+            meta = await storage.readGroupMeta(groupId);
+        }
+        catch (err) {
+            logger.error(`${tag} 读取群元数据失败: ${err}`);
+            sendError(userId, '读取群信息失败，请稍后重试', { groupId }, triggerMsgId);
+            return;
+        }
+        // 群不存在/已解散
+        if (!meta) {
+            logger.warn(`${tag} 群不存在或已解散`);
+            sendError(userId, '群不存在或已解散', { groupId }, triggerMsgId);
+            return;
+        }
+        // —— 3. 权限校验：仅群拥有者可在群内发言 ——
+        if (!meta.ownerIds.includes(userId)) {
+            logger.warn(`${tag} 你不是该群的拥有者，无法在此群发言`);
+            sendError(userId, '你不是该群的拥有者，无法在此群发言', { groupId }, triggerMsgId);
+            return;
+        }
+        // —— 4. 规范化业务数据 ——
+        const content = (data.content ?? '').trim();
+        const memberIds = meta.members.map((m) => m.agentId);
+        const mentions = normalizeMentions(extraIn.mentions, memberIds);
+        // —— 4.5 处理文件附件（参考私聊 inbound.ts 的文件处理模式） ——
+        const rawFiles = data.files ?? [];
+        const pluginRuntime = getLightclawRuntime();
+        // 获取当前用户的 apiKey，用于从云端下载文件（需要认证）
+        const effectiveApiKey = resolveEffectiveApiKey({ senderId: userId });
+        /** 群聊文件附件（与私聊 FileAttachment 对齐：name + mimeType + size + uri） */
+        const groupFiles = [];
+        /** 传递给 AI 上下文的 Attachments（name + mimeType + url + localPath） */
+        const ctxAttachments = [];
+        /** 本地媒体路径列表（供 SDK vision 模型直接读取文件内容） */
+        const localMediaPaths = [];
+        /** 本地文件 MIME 类型列表，与 localMediaPaths 一一对应 */
+        const localMediaTypes = [];
+        /** 附加到用户消息末尾的文件描述文本（告知 AI 用户发送了哪些文件） */
+        let attachmentDescription = '';
+        for (const file of rawFiles) {
+            // 前端发送 FileAttachment 格式：{ name, mimeType, size, uri, bytes }
+            const fileName = file.name || 'unknown';
+            const fileMimeType = file.mimeType || guessMimeType(fileName);
+            const fileUri = file.uri || '';
+            const fileSize = file.size ?? 0;
+            groupFiles.push({ name: fileName, mimeType: fileMimeType, size: fileSize, uri: fileUri || undefined });
+            try {
+                let buffer;
+                let mimeType;
+                let uploadPublicUrl;
+                // 来源 1：data URL（base64 编码的文件内容）
+                const parsed = file.bytes ? parseDataUrl(file.bytes) : null;
+                if (parsed) {
+                    buffer = parsed.buffer;
+                    mimeType = parsed.mimeType;
+                }
+                else if (fileUri) {
+                    // 来源 2：云端 URI（CDN 地址或文件路径）
+                    logger.info(`${tag} 文件有 URI，从云端下载: ${fileUri}`);
+                    const downloaded = await downloadFileFromServer(fileUri, { apiKey: effectiveApiKey });
+                    buffer = downloaded.buffer;
+                    mimeType = fileMimeType;
+                    uploadPublicUrl = fileUri.startsWith('http') ? fileUri : getFileDownloadUrl(fileUri);
+                }
+                else {
+                    // 来源 3：既无 bytes 也无 uri，无法处理，跳过此文件
+                    logger.warn(`${tag} 文件无 bytes 或 uri: ${fileName}，跳过`);
+                    attachmentDescription += `\n用户发送了文件: ${fileName} (${formatFileSize(fileSize)})`;
+                    continue;
+                }
+                // 保存到本地媒体存储（框架统一管理）
+                const saved = await pluginRuntime.channel.media.saveMediaBuffer(buffer, mimeType, 'inbound', MEDIA_MAX_BYTES, fileName);
+                localMediaPaths.push(saved.path);
+                localMediaTypes.push(mimeType);
+                const localPath = `${LOCALFILE_SCHEME}${saved.path}`;
+                if (uploadPublicUrl) {
+                    // URI 来源：已有公网 URL，直接使用
+                    ctxAttachments.push({ name: fileName, mimeType, url: localPath, localPath: saved.path });
+                }
+                else {
+                    // data URL 来源：上传到 COS 获取公网 URL
+                    try {
+                        const uploadResult = await uploadFileToServer(saved.path, { apiKey: effectiveApiKey });
+                        ctxAttachments.push({ name: fileName, mimeType, url: localPath, localPath: saved.path });
+                        logger.info(`${tag} 文件已上传到 COS: ${saved.path} → ${uploadResult.url}`);
+                    }
+                    catch (uploadErr) {
+                        logger.warn(`${tag} COS 上传失败，降级使用本地路径: ${uploadErr}`);
+                        ctxAttachments.push({ name: fileName, mimeType, url: localPath, localPath: saved.path });
+                    }
+                }
+                logger.info(`${tag} 文件已保存: ${saved.path} (${mimeType}, ${formatFileSize(saved.size)})`);
+            }
+            catch (err) {
+                // 单个文件处理失败不影响整条消息的处理，记录错误后继续
+                logger.error(`${tag} 文件处理失败 ${fileName}: ${err}`);
+                if (fileUri) {
+                    // 降级：仅传 CDN URL
+                    ctxAttachments.push({ name: fileName, mimeType: fileMimeType, url: fileUri });
+                }
+            }
+            attachmentDescription += `\n用户发送了文件: ${fileName} (${formatFileSize(fileSize)})`;
+            logger.info(`${tag} 文件附件: ${fileName} (${fileMimeType}, ${formatFileSize(fileSize)}) uri=${fileUri ? '有' : '无'}`);
+        }
+        // 将文件描述追加到用户消息中（与私聊一致，让 AI 知道用户发送了哪些文件）
+        const userMessage = content + attachmentDescription;
+        // —— 5. 用户消息入账（Ledger）——
+        try {
+            await orchestrator.ledger.appendUser({
+                groupId,
+                userId,
+                content,
+                mentions,
+                files: groupFiles.length > 0 ? groupFiles : undefined,
+                msgId: triggerMsgId,
+            });
+        }
+        catch (err) {
+            logger.error(`${tag} 用户消息入账失败: ${err}`);
+            sendError(userId, '消息入账失败，请稍后重试', { groupId }, triggerMsgId);
+            return;
+        }
+        // —— 6. 构造调度上下文并触发 dispatch ——
+        const conversationId = `conv:${groupId}:${triggerMsgId}`;
+        // 提前 ensure 以获取 abortSignal（dispatch 内部会幂等处理）
+        const abortSignal = orchestrator.runRegistry.ensureConversation(conversationId);
+        // 从 openclaw.json 配置中读取 agents.list，过滤掉不在配置中的成员
+        const currentCfg = pluginRuntime.config.loadConfig();
+        const configAgentIds = new Set((currentCfg.agents?.list ?? []).map((a) => a.id));
+        // 仅保留在 openclaw.json agents 列表中存在的成员
+        const validMembers = configAgentIds.size > 0 ? meta.members.filter((m) => configAgentIds.has(m.agentId)) : meta.members;
+        const ctx = {
+            conversationId,
+            groupId,
+            userId,
+            meta: {
+                groupId: meta.groupId,
+                members: validMembers,
+                defaultAgentId: meta.defaultAgentId,
+                ownerIds: meta.ownerIds,
+            },
+            userMessage,
+            mentions,
+            abortSignal,
+            msgId: triggerMsgId,
+            files: ctxAttachments.length > 0
+                ? ctxAttachments.map((a) => ({
+                    name: a.name,
+                    mimeType: a.mimeType,
+                    size: groupFiles.find((f) => f.name === a.name)?.size ?? 0,
+                    uri: a.url,
+                    localPath: a.localPath,
+                }))
+                : undefined,
+            mediaPaths: localMediaPaths.length > 0 ? localMediaPaths : undefined,
+            mediaTypes: localMediaTypes.length > 0 ? localMediaTypes : undefined,
+            effectiveApiKey,
+        };
+        logger.info(`${tag} 开始调度 conv=${conversationId} mentions=[${mentions.join(',')}]`);
+        // dispatch 采用「即发即忘」模式，结果通过 .then 处理
+        orchestrator.dispatch(ctx).then((result) => {
+            logger.info(`${tag} 调度完成 status=${result.finalStatus} route=${result.route}`);
+        }, (err) => {
+            logger.error(`${tag} 调度异常: ${err instanceof Error ? err.message : String(err)}`);
+            // 主动 dispose 防止注册表泄漏
+            try {
+                orchestrator.runRegistry.disposeConversation(conversationId);
+            }
+            catch (cleanupErr) {
+                logger.warn(`${tag} 调度异常后清理会话失败: ${cleanupErr}`);
+            }
+            sendError(userId, '群消息处理异常，请稍后重试', { groupId }, triggerMsgId);
+        });
+    };
+}

package/dist/src/group/index.js

@@ -0,0 +1,15 @@
+/**
+ * @file 群聊功能入口文件
+ * @description 群聊模块的公共 API 出口，外部模块应从此文件导入所需功能
+ */
+// ── 统一常量 ──
+export { EVENT_GROUP_REQUEST, EVENT_GROUP_RESPONSE, EVENT_GROUP_MEMBER_REQUEST, EVENT_GROUP_MEMBER_RESPONSE, EVENT_GROUP_HISTORY_REQUEST, EVENT_GROUP_HISTORY_RESPONSE, EVENT_GROUP_ABORT_REQUEST, EVENT_GROUP_ABORT_RESPONSE, } from './constants/index.js';
+// ── 统一工具函数 ──
+export { generatePreRunId, normalizeRunStatus, errorToString, } from './utils/index.js';
+// ── 存储层 ──
+export { GroupStorageCore } from './storage/index.js';
+export { ConcurrencyManager } from './storage/concurrency-manager.js';
+// ── 调度器 ──
+export { Orchestrator } from './orchestrator/orchestrator.js';
+// ── 群入站处理器 ──
+export { createGroupInboundHandler } from './inbound/index.js';