lightclawbot 1.2.6 → 1.2.8

package/dist/src/socket/service/chat-update.js

@@ -0,0 +1,83 @@
+/**
+ * @file chat-update.ts
+ * @description Chat handler — update（修改会话标题）
+ *
+ * 根据 chatId 修改 title（并置 titleLocked=true + 刷新 updatedAt）；
+ * 文件或条目不存在时返回 error 响应，不隐式创建。
+ */
+import * as fs from 'node:fs';
+import { CHANNEL_KEY, EVENT_CHAT_RESPONSE } from '../../config.js';
+import { readChatsFile, resolveChatsFilePath, writeChatsFile } from '../../utils/common.js';
+import { log, generateMsgId, createChatErrorSender } from './chat-common.js';
+/**
+ * 对目标会话应用标题更新
+ * @param chat - 原始会话元数据
+ * @param newTitle - 新标题（已 trim）
+ * @returns 更新后的会话元数据副本
+ */
+function applyTitleUpdate(chat, newTitle) {
+    return {
+        ...chat,
+        title: newTitle,
+        titleLocked: true,
+        updatedAt: Date.now(),
+    };
+}
+/**
+ * 发送更新成功响应
+ * @param params - handler 基础参数
+ * @param responseMsgId - 响应消息 ID
+ * @param updatedChat - 更新后的会话元数据
+ */
+function emitUpdateResponse(params, responseMsgId, updatedChat) {
+    const { botClientId, userId, agentId, reliableEmitter } = params;
+    reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
+        msgId: responseMsgId,
+        from: botClientId,
+        to: userId,
+        type: 'update',
+        agentId,
+        chats: [updatedChat],
+        timestamp: Date.now(),
+    }, responseMsgId);
+}
+/**
+ * 处理 EVENT_CHAT_REQUEST(type=update)
+ *
+ * 流程：校验 title → 校验文件存在 → 读取列表 → 查找目标 → 更新写回 → 回包
+ *
+ * @param params - Chat update 操作入参（含 chatId、title）
+ */
+export function handleChatUpdate(params) {
+    const { userId, agentId, chatId, title, botClientId, reliableEmitter } = params;
+    const chatsPath = resolveChatsFilePath(agentId, userId);
+    const responseMsgId = generateMsgId();
+    const sendError = createChatErrorSender({ responseMsgId, botClientId, userId, agentId, type: 'update', reliableEmitter }, { chatId });
+    // 前置校验：标题不能为空
+    const nextTitle = title?.trim();
+    if (!nextTitle) {
+        sendError('标题不能为空');
+        return;
+    }
+    // 前置校验：会话文件必须存在
+    if (!fs.existsSync(chatsPath)) {
+        sendError(`会话文件不存在: ${chatsPath}`);
+        return;
+    }
+    try {
+        const chats = readChatsFile(chatsPath);
+        const targetChat = chats.find((c) => c.chatId === chatId);
+        if (!targetChat) {
+            sendError(`会话不存在: chatId=${chatId}`);
+            return;
+        }
+        const updatedChat = applyTitleUpdate(targetChat, nextTitle);
+        const updatedChats = chats.map((c) => (c.chatId === chatId ? updatedChat : c));
+        writeChatsFile(chatsPath, updatedChats);
+        log.info(`[${CHANNEL_KEY}] 会话标题更新成功: userId=${userId}, agentId=${agentId}, chatId=${chatId}, title="${nextTitle}"`);
+        emitUpdateResponse(params, responseMsgId, updatedChat);
+    }
+    catch (err) {
+        sendError(err instanceof Error ? err.message : String(err));
+    }
+}

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

@@ -0,0 +1,104 @@
+/**
+ * @file Socket 网关侧的群消息中止（Group Abort）请求处理器。
+ *
+ * @description
+ * 当群主需要中止某个正在进行的群聊会话时，前端通过 Socket 发送 abort 请求，
+ * 本模块负责接收并处理该请求。
+ *
+ * 职责：
+ * - 校验前端传入的 groupId / conversationId 是否合法；
+ * - 鉴权：验证请求用户是否为群 ownerIds 成员（仅群主可中止）；
+ * - 调用 Orchestrator.abort() 级联中止整棵 run 树（包括所有子任务）；
+ * - 通过 ReliableEmitter 以可靠投递方式回包（带 ACK 确认机制）；
+ * - 幂等：重复 abort 同一 conversationId 不报错，返回 abortedRunIds: []。
+ *
+ * @module socket/group-abort
+ */
+import { CHANNEL_KEY } from '../../config.js';
+import { EVENT_GROUP_ABORT_RESPONSE } from '../../group/constants/index.js';
+import { getModuleLogger } from '../../utils/logger.js';
+/** 群消息中止模块日志器，模块标识为 'group.abort' */
+const log = getModuleLogger('group.abort');
+/**
+ * 统一发送群中止响应（成功/失败共用）。
+ *
+ * @description 构造标准的 abort 响应消息体，通过可靠发射器发送给请求方。
+ * 无论中止成功或失败，都通过此函数统一回包，保证响应格式一致。
+ *
+ * @param params - 回包所需的上下文参数（从请求参数中提取）
+ * @param abortedRunIds - 成功中止的 run ID 列表，失败时为空数组
+ * @param error - 可选的错误描述信息，存在时会附加到响应的 extra.error 字段
+ */
+function emitAbortResponse(params, abortedRunIds, error) {
+    const { requestMsgId, botClientId, userId, groupId, conversationId, reliableEmitter } = params;
+    reliableEmitter.emitWithAck(EVENT_GROUP_ABORT_RESPONSE, {
+        msgId: requestMsgId,
+        from: botClientId,
+        to: userId,
+        groupId,
+        conversationId,
+        timestamp: Date.now(),
+        abortedRunIds,
+        ...(error ? { extra: { error } } : {}),
+    }, requestMsgId);
+}
+/**
+ * 处理「群消息中止」请求的核心函数。
+ *
+ * @description
+ * 完整处理流程如下：
+ * 1. **参数校验** — 确保 groupId 和 conversationId 均已提供；
+ * 2. **鉴权** — 从存储层读取群元数据，校验请求用户是否在 ownerIds 中；
+ * 3. **级联中止** — 调用 orchestrator.abort() 中止目标 conversationId 下的所有 run；
+ * 4. **回包** — 将中止结果通过可靠发射器返回给前端。
+ *
+ * @param params - 群消息中止请求的完整参数
+ * @returns Promise<void> 无返回值，结果通过 reliableEmitter 回包
+ */
+export async function handleGroupAbort(params) {
+    const { userId, groupId, conversationId, orchestrator, storage } = params;
+    const logContext = `userId=${userId} groupId=${groupId} conversationId=${conversationId}`;
+    log.info(`[${CHANNEL_KEY}] 收到群消息中止请求: ${logContext}`);
+    /**
+     * 错误快捷回包辅助函数。
+     * 记录错误日志并向前端发送包含错误信息的空 abortedRunIds 响应。
+     *
+     * @param error - 错误描述文本
+     */
+    const sendError = (error) => {
+        log.error(`[${CHANNEL_KEY}] 群消息中止失败: ${logContext} 错误=${error}`);
+        emitAbortResponse(params, [], error);
+    };
+    // ① 参数校验
+    if (!groupId) {
+        sendError('缺少 groupId');
+        return;
+    }
+    if (!conversationId) {
+        sendError('缺少 conversationId');
+        return;
+    }
+    // ② 鉴权：读取群元数据，校验用户是否为群拥有者
+    // 只有 ownerIds 中的用户才有权限中止群会话，防止非授权用户恶意中止
+    try {
+        const meta = await storage.readGroupMeta(groupId);
+        if (!meta) {
+            sendError('群组不存在');
+            return;
+        }
+        if (!meta.ownerIds.includes(userId)) {
+            sendError('无操作权限');
+            return;
+        }
+    }
+    catch (err) {
+        // 存储层异常时记录完整错误信息，便于排查
+        sendError(`读取群元数据失败: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    // ③ 级联中止：中止该 conversationId 下所有正在运行的 run（包括子任务）
+    const abortedRunIds = orchestrator.abort(conversationId);
+    log.info(`[${CHANNEL_KEY}] 群消息中止成功: ${logContext} 已中止runIds=[${abortedRunIds.join(',')}]`);
+    // ④ 回包
+    emitAbortResponse(params, abortedRunIds);
+}

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

@@ -0,0 +1,140 @@
+/**
+ * @file Socket 网关侧的群组历史消息（Group History）请求处理器。
+ *
+ * @description
+ * 当前端需要拉取群聊历史消息时，通过 Socket 发送 history 请求，
+ * 本模块负责接收并处理该请求，支持分页游标翻页。
+ *
+ * 职责：
+ * - 校验前端传入的分页参数（limit / before / chatOnly）；
+ * - 调用 GroupHistoryService 拉取指定群组的历史消息；
+ * - 通过 ReliableEmitter 以可靠投递方式回包（带 ACK 确认机制）；
+ * - 失败统一通过 sendError 输出错误响应与日志。
+ *
+ * @module socket/group-history
+ */
+import { CHANNEL_KEY, DEFAULT_HISTORY_LIMIT } from '../../config.js';
+import { EVENT_GROUP_HISTORY_RESPONSE } from '../../group/constants/index.js';
+import { GroupHistoryService } from '../../group/services/index.js';
+import { getModuleLogger } from '../../utils/logger.js';
+/** 群组历史消息模块日志器，模块标识为 'group.history' */
+const log = getModuleLogger('group.history');
+/**
+ * 模块级共享的群组历史服务实例。
+ *
+ * @remarks
+ * - 采用单例模式，避免重复创建服务实例；
+ * - 同时导出供 group-member 模块引用，用于在成员变更时清除历史缓存。
+ */
+export const historyService = new GroupHistoryService();
+/**
+ * 统一发送群组历史响应（成功/失败共用）。
+ *
+ * @description 构造标准的 history 响应消息体，通过可靠发射器发送给请求方。
+ * 无论拉取成功或失败，都通过此函数统一回包，保证响应格式一致。
+ *
+ * @param params - 回包所需的上下文参数（从请求参数中 Pick）
+ * @param messages - 历史消息列表，失败时传空数组
+ * @param hasMore - 是否还有更早的消息可继续翻页
+ * @param options - 可选扩展参数
+ * @param options.nextCursor - 下一页游标（本批次最早消息的时间戳）
+ * @param options.error - 错误描述信息，存在时附加到 extra.error
+ */
+function emitHistoryResponse(params, messages, hasMore, options) {
+    const { requestMsgId, botClientId, userId, groupId, reliableEmitter } = params;
+    // 构造响应 payload，使用展开运算符按需附加可选字段
+    reliableEmitter.emitWithAck(EVENT_GROUP_HISTORY_RESPONSE, {
+        msgId: requestMsgId,
+        from: botClientId,
+        to: userId,
+        groupId,
+        timestamp: Date.now(),
+        messages,
+        hasMore,
+        // 仅在有下一页游标时附加 nextCursor 字段
+        ...(options?.nextCursor != null ? { nextCursor: options.nextCursor } : {}),
+        // 仅在有错误时附加 extra.error 字段
+        ...(options?.error ? { extra: { error: options.error } } : {}),
+    }, 
+    // 使用 requestMsgId 作为 ACK 标识，实现幂等去重
+    requestMsgId);
+}
+/**
+ * 规范化 limit 参数。
+ *
+ * @description 校验规则：
+ * - 必须为 number 类型（排除 undefined）
+ * - 必须为有限数（排除 Infinity / NaN）
+ * - 必须为正数（排除 0 和负数）
+ * - 取整（排除小数，如 3.7 → 3）
+ * 不满足以上任一条件时，回退到 DEFAULT_HISTORY_LIMIT。
+ *
+ * @param raw - 前端传入的原始 limit 值
+ * @returns 合法的 limit 正整数
+ */
+function normalizeLimit(raw) {
+    return typeof raw === 'number' && Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : DEFAULT_HISTORY_LIMIT;
+}
+/**
+ * 规范化 before 游标。
+ *
+ * @description 校验规则与 normalizeLimit 类似：
+ * - 必须为有限正数
+ * - 不满足时返回 undefined，表示不指定游标（从最新消息开始拉取）
+ *
+ * @param raw - 前端传入的原始 before 时间戳
+ * @returns 合法的游标时间戳，或 undefined 表示取最新一页
+ */
+function normalizeBefore(raw) {
+    return typeof raw === 'number' && Number.isFinite(raw) && raw > 0 ? raw : undefined;
+}
+/**
+ * 处理「群组历史消息」请求的核心函数。
+ *
+ * @description
+ * 完整处理流程如下：
+ * 1. **参数校验** — 确保 groupId 已提供；
+ * 2. **参数规范化** — 兜底 limit / before / chatOnly；
+ * 3. **拉取消息** — 调用 GroupHistoryService.getHistory；
+ * 4. **回包** — 将结果通过可靠发射器返回给前端。
+ *
+ * @param params - 群组历史消息请求的完整参数
+ * @returns Promise<void> 无返回值，结果通过 reliableEmitter 回包
+ */
+export async function handleGroupHistory(params) {
+    const { userId, groupId } = params;
+    /**
+     * 错误快捷回包辅助闭包。
+     * 记录 error 级日志并向前端发送包含错误信息的空消息列表响应。
+     *
+     * @param error - 错误描述文本
+     */
+    const sendError = (error) => {
+        log.error(`[${CHANNEL_KEY}] 群组历史消息错误: groupId=${groupId} 错误=${error}`);
+        emitHistoryResponse(params, [], false, { error });
+    };
+    // ① 参数校验：groupId 为必填项，缺失时直接报错回包
+    if (!groupId) {
+        sendError('缺少 groupId');
+        return;
+    }
+    // ② 参数规范化：对前端传入的分页参数进行兜底处理
+    // 条数上限
+    const limit = normalizeLimit(params.limit);
+    // 翻页游标
+    const before = normalizeBefore(params.before);
+    // 是否仅聊天消息，默认 false
+    const chatOnly = params.chatOnly ?? false;
+    // ③ 拉取历史消息：调用 GroupHistoryService 获取分页数据
+    try {
+        const result = await historyService.getHistory({ groupId, userId, limit, before, chatOnly });
+        // 记录本次拉取的关键参数和结果摘要，便于线上排查
+        log.info(`[${CHANNEL_KEY}] 群组历史消息: groupId=${groupId} count=${result.messages.length}`);
+        // ④ 成功回包：携带消息列表、翻页状态和下一页游标
+        emitHistoryResponse(params, result.messages, result.hasMore, { nextCursor: result.nextCursor });
+    }
+    catch (err) {
+        // 服务层异常时提取错误信息并通过 sendError 统一回包
+        sendError(err instanceof Error ? err.message : String(err));
+    }
+}

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

@@ -0,0 +1,209 @@
+/**
+ * @file group-member.ts
+ * @description 群成员加入/退出请求的 Socket 网关处理器。
+ * 负责接收客户端的群成员变更请求，执行业务逻辑后通过可靠发射器回包。
+ */
+import { CHANNEL_KEY } from '../../config.js';
+import { EVENT_GROUP_MEMBER_RESPONSE } from '../../group/constants/index.js';
+import { GroupMemberService, GroupUpdateService, GroupQueryService } from '../../group/services/index.js';
+import { getLightclawRuntime } from '../../runtime.js';
+import { historyService } from './group-history.js';
+import { getModuleLogger } from '../../utils/logger.js';
+const log = getModuleLogger('group.member');
+/** 群成员服务实例，用于执行成员增删操作 */
+const memberService = new GroupMemberService();
+/** 群查询服务实例，用于管理查询缓存 */
+const queryService = new GroupQueryService();
+/**
+ * 构建群成员响应的基础载荷
+ * @description 统一构造响应数据结构，供成功和错误场景复用
+ * @param ctx - 请求上下文参数
+ * @param type - 操作类型（add/remove）
+ * @param members - 当前群成员列表
+ * @param extra - 附加信息（如错误详情）
+ * @returns 符合 EVENT_GROUP_MEMBER_RESPONSE 事件格式的载荷对象
+ */
+function buildResponsePayload(ctx, type, members, extra) {
+    const { requestMsgId, botClientId, userId, groupId, agentId } = ctx;
+    return {
+        msgId: requestMsgId,
+        from: botClientId,
+        to: userId,
+        type,
+        timestamp: Date.now(),
+        groupId,
+        agentId,
+        members,
+        ...(extra && { extra }),
+    };
+}
+/**
+ * 创建错误回包发送函数（柯里化）
+ * @description 返回一个闭包函数，调用时自动记录错误日志并向客户端发送错误响应
+ * @param ctx - 包含操作类型的请求上下文
+ * @returns 接收错误信息字符串的发送函数
+ */
+function createGroupMemberErrorSender(ctx) {
+    const { type, reliableEmitter, requestMsgId } = ctx;
+    return (error) => {
+        log.error(`[${CHANNEL_KEY}] 群成员${type}错误: ${error}`);
+        const payload = buildResponsePayload(ctx, type, [], { error });
+        reliableEmitter.emitWithAck(EVENT_GROUP_MEMBER_RESPONSE, payload, requestMsgId);
+    };
+}
+/**
+ * 发送成功响应
+ * @description 将操作成功后的群成员列表通过可靠发射器回包给客户端
+ * @param ctx - 请求上下文参数
+ * @param type - 操作类型（add/remove）
+ * @param members - 操作后的最新群成员列表
+ */
+function emitGroupMemberResponse(ctx, type, members) {
+    const { reliableEmitter, requestMsgId } = ctx;
+    const payload = buildResponsePayload(ctx, type, members);
+    reliableEmitter.emitWithAck(EVENT_GROUP_MEMBER_RESPONSE, payload, requestMsgId);
+}
+/**
+ * 构建 agentId 校验器与元信息解析器
+ * @description 从运行时配置中加载 Agent 列表，生成校验和元信息查询工具。
+ * 优先使用 extra 中传入的 agentName/agentDesc，否则从配置列表中按优先级解析。
+ * @param extra - 外部传入的 Agent 名称和描述（优先级高于配置）
+ * @returns 包含 isValidAgentId 校验函数和 resolveAgentMeta 元信息解析函数的对象
+ */
+function buildAgentRuntimeHelpers(extra) {
+    const pluginRuntime = getLightclawRuntime();
+    const currentCfg = pluginRuntime.config.loadConfig();
+    const list = currentCfg.agents?.list ?? [];
+    // 若配置列表为空，则使用默认 Agent ID 作为唯一合法值
+    const validIds = list.length > 0 ? list.map((a) => a.id) : [];
+    const validSet = new Set(validIds);
+    // 构建 agentId -> 元信息 的映射表，按优先级解析名称和描述
+    const metaMap = new Map();
+    for (const a of list) {
+        metaMap.set(a.id, {
+            agentName: a.displayName ?? a.identity?.name ?? a.name ?? a.id,
+            agentDesc: a.description ?? a.identity?.description ?? a.desc ?? a.routing ?? '',
+        });
+    }
+    return {
+        isValidAgentId: (agentId) => validSet.has(agentId),
+        resolveAgentMeta: (agentId) => {
+            // 若 extra 中提供了有效的 agentName 且不等于 agentId 本身，优先使用 extra
+            if (extra?.agentName && extra.agentName !== agentId) {
+                return { agentName: extra.agentName, agentDesc: extra.agentDesc ?? '' };
+            }
+            return metaMap.get(agentId);
+        },
+    };
+}
+/**
+ * 校验必填参数
+ * @description 类型守卫函数，校验 groupId 和 agentId 是否存在，不存在则发送错误响应
+ * @param groupId - 待校验的群组 ID
+ * @param agentId - 待校验的 Agent ID
+ * @param sendError - 错误发送函数
+ * @returns 校验通过返回 true（同时收窄 groupId 类型为 string）
+ */
+function validateRequiredParams(groupId, agentId, sendError) {
+    if (!groupId) {
+        sendError('缺少 groupId');
+        return false;
+    }
+    if (!agentId) {
+        sendError('缺少 agentId');
+        return false;
+    }
+    return true;
+}
+/**
+ * 成员变更后的缓存清理
+ * @description 清除群查询缓存和历史消息阅读者缓存，确保后续查询获取最新数据
+ */
+function invalidateCaches() {
+    queryService.clearCache();
+    historyService.clearReaderCache();
+}
+/**
+ * 处理「加入群」请求
+ * @description 校验参数后调用 memberService 添加成员，成功后清除缓存并回包
+ * @param params - 群成员操作入参
+ */
+export async function handleGroupMemberAdd(params) {
+    const { userId, groupId, agentId } = params;
+    const sendError = createGroupMemberErrorSender({ ...params, type: 'add' });
+    if (!validateRequiredParams(groupId, agentId, sendError))
+        return;
+    try {
+        const { isValidAgentId, resolveAgentMeta } = buildAgentRuntimeHelpers(params.extra);
+        const result = await memberService.addMember(groupId, userId, agentId, {
+            isValidAgentId,
+            resolveAgentMeta,
+        });
+        invalidateCaches();
+        log.info(`[${CHANNEL_KEY}] 群成员添加: userId=${userId} groupId=${groupId} agentId=${agentId} members=${result.members.length}`);
+        emitGroupMemberResponse(params, 'add', result.members);
+    }
+    catch (err) {
+        sendError(err instanceof Error ? err.message : String(err));
+    }
+}
+/**
+ * 处理「退出群」请求
+ * @description 校验参数后调用 memberService 移除成员，成功后清除缓存并回包
+ * @param params - 群成员操作入参
+ */
+export async function handleGroupMemberRemove(params) {
+    const { userId, groupId, agentId } = params;
+    const sendError = createGroupMemberErrorSender({ ...params, type: 'remove' });
+    if (!validateRequiredParams(groupId, agentId, sendError))
+        return;
+    try {
+        const result = await memberService.removeMember(groupId, userId, agentId);
+        invalidateCaches();
+        log.info(`[${CHANNEL_KEY}] 群成员移除: userId=${userId} groupId=${groupId} agentId=${agentId} members=${result.members.length}`);
+        emitGroupMemberResponse(params, 'remove', result.members);
+    }
+    catch (err) {
+        sendError(err instanceof Error ? err.message : String(err));
+    }
+}
+/**
+ * 处理「全量刷新成员元信息」请求
+ * @description 从客户端传入的 extra.agentMetaMap 中获取所有 Agent 的最新 agentName / agentDesc，
+ * 调用 GroupUpdateService.syncMembersMeta 全量刷新所有群组中的成员信息。
+ * 注意：此操作不需要 groupId 和 agentId，因为是全量刷新所有群组。
+ * @param params - 群成员操作入参
+ */
+export async function handleGroupMemberUpdate(params) {
+    const { userId, reliableEmitter, requestMsgId, botClientId } = params;
+    const sendError = createGroupMemberErrorSender({ ...params, type: 'update' });
+    try {
+        // 从客户端传入的 extra 中获取 agentMetaMap
+        const agentMetaMap = params.extra?.agentMetaMap;
+        if (!agentMetaMap || Object.keys(agentMetaMap).length === 0) {
+            sendError('缺少 extra.agentMetaMap 或映射表为空');
+            return;
+        }
+        // 调用 syncMembersMeta 全量刷新
+        const updateService = new GroupUpdateService();
+        const result = await updateService.syncMembersMeta(agentMetaMap);
+        invalidateCaches();
+        log.info(`[${CHANNEL_KEY}] 群成员元信息同步: userId=${userId} scanned=${result.scannedCount} updated=${result.updatedGroupIds.length}`);
+        // 回包：返回被更新的群组 ID 列表
+        reliableEmitter.emitWithAck(EVENT_GROUP_MEMBER_RESPONSE, {
+            msgId: requestMsgId,
+            from: botClientId,
+            to: userId,
+            type: 'update',
+            timestamp: Date.now(),
+            members: [],
+            extra: {
+                updatedGroupIds: result.updatedGroupIds,
+                scannedCount: result.scannedCount,
+            },
+        }, requestMsgId);
+    }
+    catch (err) {
+        sendError(err instanceof Error ? err.message : String(err));
+    }
+}