lightclawbot 1.2.6 → 1.2.8

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

@@ -0,0 +1,233 @@
+/**
+ * @file Socket 网关侧的群组（Group）请求处理器集合。
+ * @description
+ * 提供对群组的「列表查询 / 创建 / 更新 / 解散 / 清空」五类 socket 请求的统一处理：
+ * - 参数校验
+ * - 调用对应的领域服务（GroupQueryService / GroupCreationService / GroupUpdateService / GroupDeletionService）
+ * - 通过 ReliableEmitter 以可靠投递的方式回包给前端
+ * - 失败时统一通过 `createGroupErrorSender` 输出错误响应与日志
+ */
+import { CHANNEL_KEY } from '../../config.js';
+import { EVENT_GROUP_RESPONSE } from '../../group/constants/index.js';
+import { getModuleLogger } from '../../utils/logger.js';
+import { generateMsgId } from '../../dedup.js';
+import { resolveEffectiveApiKey } from '../../config.js';
+import { GroupQueryService, GroupCreationService, GroupUpdateService, GroupDeletionService, } from '../../group/services/index.js';
+/** 模块级共享的群组查询服务实例，便于命中其内部缓存。 */
+const queryService = new GroupQueryService();
+/** 模块级日志器，通过公共方法获取，无需参数传递。 */
+const logger = getModuleLogger('socket.group');
+/** 将未知错误统一转换为字符串消息。 */
+function toErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * 构造统一的群组错误响应发射器。
+ * 调用返回的函数会输出 error 日志并通过 ReliableEmitter 发送错误响应。
+ * @param ctx - 错误响应的上下文（包含请求类型与回包必要字段）
+ * @param extra - 额外要合并到响应体的字段（例如 `groupId`）
+ */
+function createGroupErrorSender(ctx, extra = {}) {
+    const { requestMsgId, botClientId, userId, type, reliableEmitter } = ctx;
+    return (error) => {
+        logger.error(`[${CHANNEL_KEY}] 群组 ${type} 错误: ${error}`);
+        reliableEmitter.emitWithAck(EVENT_GROUP_RESPONSE, {
+            msgId: requestMsgId,
+            from: botClientId,
+            to: userId,
+            type,
+            timestamp: Date.now(),
+            groups: [],
+            ...extra,
+            extra: { error },
+        }, requestMsgId);
+    };
+}
+/**
+ * 发送群组成功响应。
+ * @param ctx - 通用回包上下文
+ * @param type - 群组请求类型
+ * @param groups - 返回给前端的群组列表
+ */
+function emitGroupResponse(ctx, type, groups) {
+    const { requestMsgId, botClientId, userId, reliableEmitter } = ctx;
+    reliableEmitter.emitWithAck(EVENT_GROUP_RESPONSE, {
+        msgId: requestMsgId,
+        from: botClientId,
+        to: userId,
+        type,
+        groups,
+        timestamp: Date.now(),
+    }, requestMsgId);
+}
+/** 处理「群组列表」请求：查询当前用户加入的所有群组并回包。 */
+export async function handleGroupList(params) {
+    const { userId } = params;
+    const sendError = createGroupErrorSender({ ...params, type: 'list' });
+    try {
+        const groups = await queryService.getUserGroups(userId);
+        logger.info(`[${CHANNEL_KEY}] 群组列表: userId=${userId} count=${groups.length}`);
+        emitGroupResponse(params, 'list', groups);
+    }
+    catch (err) {
+        sendError(toErrorMessage(err));
+    }
+}
+/**
+ * 处理「创建群组」请求。
+ * 校验 name / members / defaultAgentId 后调用 GroupCreationService 创建群组，
+ * 成功后清理查询缓存并回包新建群组的 meta 信息。
+ */
+export async function handleGroupCreate(params) {
+    const { userId, name, desc, members, defaultAgentId, orchestrator } = params;
+    const sendError = createGroupErrorSender({ ...params, type: 'create' });
+    if (!name || !name.trim()) {
+        sendError('缺少群名称');
+        return;
+    }
+    if (!Array.isArray(members) || members.length === 0) {
+        sendError('缺少群成员');
+        return;
+    }
+    if (!defaultAgentId) {
+        sendError('缺少默认 Agent ID');
+        return;
+    }
+    try {
+        const creationService = new GroupCreationService();
+        const groupMeta = await creationService.createGroup(userId, name.trim(), (desc ?? '').trim(), members, defaultAgentId);
+        queryService.clearCache();
+        logger.info(`[${CHANNEL_KEY}] 创建群组: userId=${userId} groupId=${groupMeta.groupId} name="${groupMeta.name}" members=${members.length}`);
+        emitGroupResponse(params, 'create', [groupMeta]);
+        // 创建群成功后，唤醒主Agent生成欢迎消息
+        if (orchestrator) {
+            triggerWelcomeMessage(orchestrator, groupMeta, userId).catch((err) => {
+                logger.warn(`[${CHANNEL_KEY}] 唤醒主Agent生成欢迎消息失败: ${toErrorMessage(err)}`);
+            });
+        }
+    }
+    catch (err) {
+        sendError(toErrorMessage(err));
+    }
+}
+/**
+ * 创建群成功后触发主Agent生成欢迎消息
+ *
+ * @remarks
+ * 构造一个特殊的 DispatchContext，让主Agent根据群目标生成欢迎消息。
+ * 采用「即发即忘」模式，不阻塞创建群的响应流程。
+ *
+ * @param orchestrator - 调度器实例
+ * @param groupMeta - 新创建的群元数据
+ * @param userId - 创建者用户 ID
+ */
+async function triggerWelcomeMessage(orchestrator, groupMeta, userId) {
+    const triggerMsgId = generateMsgId();
+    const conversationId = `conv:${groupMeta.groupId}:welcome:${triggerMsgId}`;
+    const abortSignal = orchestrator.runRegistry.ensureConversation(conversationId);
+    const effectiveApiKey = resolveEffectiveApiKey({ senderId: userId });
+    // 构造引导主Agent生成欢迎消息的用户消息
+    const welcomeUserMessage = [
+        `群「${groupMeta.name}」已创建成功。`,
+        groupMeta.desc ? `群目标：${groupMeta.desc}` : '',
+        `请作为领航员发送一条欢迎消息，向我介绍这个群的目标和建议的开始方向。`,
+    ].filter(Boolean).join('\n');
+    const ctx = {
+        conversationId,
+        groupId: groupMeta.groupId,
+        userId,
+        meta: {
+            groupId: groupMeta.groupId,
+            members: groupMeta.members,
+            defaultAgentId: groupMeta.defaultAgentId,
+            ownerIds: groupMeta.ownerIds,
+            name: groupMeta.name,
+            desc: groupMeta.desc,
+        },
+        userMessage: welcomeUserMessage,
+        mentions: [],
+        abortSignal,
+        msgId: triggerMsgId,
+        effectiveApiKey,
+        welcomeMode: true,
+    };
+    const result = await orchestrator.dispatch(ctx);
+    logger.info(`[${CHANNEL_KEY}] 欢迎消息生成完成: groupId=${groupMeta.groupId} status=${result.finalStatus}`);
+}
+/**
+ * 处理「更新群组」请求。
+ * 仅把传入的有效字段合并进 updates，无可更新字段时返回错误。
+ */
+export async function handleGroupUpdate(params) {
+    const { userId, groupId, name, desc, pinned } = params;
+    const sendError = createGroupErrorSender({ ...params, type: 'update' }, { groupId });
+    if (!groupId) {
+        sendError('缺少群组 ID');
+        return;
+    }
+    const updates = {};
+    if (typeof name === 'string')
+        updates.name = name.trim();
+    if (typeof desc === 'string')
+        updates.desc = desc.trim();
+    if (typeof pinned === 'boolean')
+        updates.pinned = pinned;
+    if (Object.keys(updates).length === 0) {
+        sendError('没有可更新的字段');
+        return;
+    }
+    try {
+        const updateService = new GroupUpdateService();
+        const updated = await updateService.updateGroup(groupId, userId, updates);
+        queryService.clearCache();
+        logger.info(`[${CHANNEL_KEY}] 更新群组: userId=${userId} groupId=${groupId} fields=${Object.keys(updates).join(',')}`);
+        emitGroupResponse(params, 'update', [updated]);
+    }
+    catch (err) {
+        sendError(toErrorMessage(err));
+    }
+}
+/**
+ * 处理「解散群组」请求。
+ * 鉴权与删除逻辑由 GroupDeletionService 内部完成，
+ * 成功后清理查询缓存并回包被解散群组的 meta 信息。
+ */
+export async function handleGroupDelete(params) {
+    const { userId, groupId } = params;
+    const sendError = createGroupErrorSender({ ...params, type: 'delete' }, { groupId });
+    if (!groupId) {
+        sendError('缺少群组 ID');
+        return;
+    }
+    try {
+        const deletionService = new GroupDeletionService();
+        const dismissed = await deletionService.deleteGroup(groupId, userId);
+        queryService.clearCache();
+        logger.info(`[${CHANNEL_KEY}] 解散群组: userId=${userId} groupId=${groupId}`);
+        emitGroupResponse(params, 'delete', [dismissed]);
+    }
+    catch (err) {
+        sendError(toErrorMessage(err));
+    }
+}
+/**
+ * 处理「清空群组聊天账本」请求。
+ * 仅清理消息账本与相关 Agent session，保留群组元数据（成员、置顶、名称等不变）。
+ */
+export async function handleGroupClear(params) {
+    const { userId, groupId } = params;
+    const sendError = createGroupErrorSender({ ...params, type: 'clear' }, { groupId });
+    if (!groupId) {
+        sendError('缺少群组 ID');
+        return;
+    }
+    try {
+        const deletionService = new GroupDeletionService();
+        const cleared = await deletionService.clearGroup(groupId, userId);
+        logger.info(`[${CHANNEL_KEY}] 清空群组: userId=${userId} groupId=${groupId}`);
+        emitGroupResponse(params, 'clear', [cleared]);
+    }
+    catch (err) {
+        sendError(toErrorMessage(err));
+    }
+}

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

@@ -0,0 +1,102 @@
+/**
+ * 历史消息查询 Service
+ *
+ * 职责：封装私聊历史消息的查询逻辑，包括：
+ *   - sessionKey 解析
+ *   - agentId 合法性校验
+ *   - 多模式读取（multi-session / single-session-with-cron）
+ *   - sessionId 兜底登记
+ *
+ * 由 handlers/history-request.ts 调用，保持 handler 层薄而清晰。
+ */
+import { CHANNEL_KEY, DEFAULT_HISTORY_LIMIT, DEFAULT_AGENT_ID } from '../../config.js';
+import { getLightclawRuntime } from '../../runtime.js';
+import { readSessionHistoryWithCron, readSessionHistoriesByIds, loadSessionStore, } from '../../history/index.js';
+import { ensureSessionInHistory, readChatsFile, resolveChatsFilePath } from '../../utils/common.js';
+import { extractChatId } from '../utils/message.js';
+import { getModuleLogger } from '../../utils/logger.js';
+/** 模块级日志器 */
+const log = getModuleLogger('socket.history-service');
+/**
+ * 查询私聊历史消息
+ *
+ * @param data    前端请求数据
+ * @param account 当前账户配置
+ * @returns 查询结果（消息列表 + sessionKey + agentId）
+ */
+export function queryPrivateHistory(data, account) {
+    const pluginRuntime = getLightclawRuntime();
+    const currentCfg = pluginRuntime.config.loadConfig();
+    const baseRoute = pluginRuntime.channel.routing.resolveAgentRoute({
+        cfg: currentCfg,
+        channel: CHANNEL_KEY,
+        accountId: account.accountId,
+        peer: { kind: 'direct', id: data.from },
+    });
+    // agentId 合法性校验
+    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}`);
+    // 构建 sessionKey
+    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
+    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)}`);
+    }
+    // ② 读取历史消息
+    const limit = data.limit ?? DEFAULT_HISTORY_LIMIT;
+    const chatOnly = data.chatOnly ?? true;
+    let messages = [];
+    let readMode = 'single-session-with-cron';
+    try {
+        const targetChatId = chatIdSuffix;
+        const chatsPath = resolveChatsFilePath(resolvedAgentId, data.from);
+        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') {
+        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 filteredMessages = messages.filter((msg) => !!msg.content.trim() || (msg.files && msg.files.length > 0));
+    return {
+        messages: filteredMessages,
+        sessionKey,
+        agentId: resolvedAgentId,
+    };
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Socket 业务逻辑层统一导出
+ *
+ * 包含：会话管理、历史消息查询、群组管理、群成员管理、群历史、群中止等业务逻辑。
+ */
+export { handleChatList } from './chat-list.js';
+export { handleChatCreate } from './chat-create.js';
+export { handleChatUpdate } from './chat-update.js';
+export { handleChatDelete } from './chat-delete.js';
+export { queryPrivateHistory } from './history.js';
+export { handleGroupList, handleGroupCreate, handleGroupUpdate, handleGroupDelete, handleGroupClear, } from './group.js';
+export { handleGroupMemberAdd, handleGroupMemberRemove } from './group-member.js';
+export { handleGroupHistory } from './group-history.js';
+export { handleGroupAbort } from './group-abort.js';

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

@@ -0,0 +1,7 @@
+/**
+ * Socket 事件处理器核心类型定义
+ *
+ * 本文件仅包含 handler 层的依赖注入接口（SocketHandlerDeps），
+ * 各事件 payload 类型定义拆分至 request.ts 中。
+ */
+export {};

package/dist/src/socket/types/request.js

@@ -0,0 +1,8 @@
+/**
+ * @file request.ts
+ * @description Socket 事件 payload 类型定义
+ *
+ * 各事件（history:request、chat:request、group:request 等）的请求数据结构。
+ * 群组相关接口共享 BaseGroupRequestData 基础字段，减少重复声明。
+ */
+export {};

package/dist/src/socket/types/service.js

@@ -0,0 +1,8 @@
+/**
+ * @file service.ts
+ * @description Socket Service 层类型定义
+ *
+ * 包含 chat / group / history 等 service 模块的入参接口与辅助类型。
+ * 群组相关 handler 入参统一继承 GroupHandlerParams，减少重复字段声明。
+ */
+export {};

package/dist/src/socket/utils/agent-soul.js

@@ -0,0 +1,95 @@
+/**
+ * @file agent-soul.ts
+ * @description Agent SoulId 映射工具
+ *
+ * 负责从 lightsoul 配置文件中读取 agent 与 soulId 的映射关系，
+ * 并将 soulId 附加到 agent 配置列表中。
+ *
+ * 配置文件支持两种格式：
+ * - 扁平格式：`{ "agentId": "soulId" }`
+ * - 对象格式：`{ "agentId": { "soulId": "xxx" } }`
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getModuleLogger } from '../../utils/logger.js';
+/** 模块级日志器 */
+const log = getModuleLogger('socket.agent-soul');
+/** lightsoul 配置文件默认路径 */
+export const LIGHTSOUL_CONFIG_PATH = path.join(process.env.HOME || '', '.config/lightsoul/config.json');
+/**
+ * 获取非空 trim 字符串，空白视为无效
+ * @param value - 待检测值
+ * @returns trim 后的字符串，若无效则返回空字符串
+ */
+const getTrimmedString = (value) => (typeof value === 'string' ? value.trim() : '');
+/**
+ * 判断值是否为非数组的普通对象
+ * @param value - 待检测值
+ */
+const isPlainObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+/**
+ * 解析原始 JSON 字符串为 SoulIdMap
+ *
+ * 支持两种配置格式：
+ * - 字符串值：`{ "agentId": "soulId" }` → 直接映射
+ * - 对象值：`{ "agentId": { "soulId": "xxx" } }` → 提取 soulId 字段
+ *
+ * @param raw - lightsoul 配置文件的原始 JSON 字符串
+ * @returns 解析后的 agentId → soulId 映射表
+ */
+export function parseSoulIdMap(raw) {
+    const map = {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        log.error(`解析 lightsoul 配置失败: ${error instanceof Error ? error.message : String(error)}`);
+        return map;
+    }
+    if (!isPlainObject(parsed))
+        return map;
+    for (const [agentId, value] of Object.entries(parsed)) {
+        // 扁平格式：值直接为 soulId 字符串
+        const directValue = getTrimmedString(value);
+        if (directValue) {
+            map[agentId] = directValue;
+            continue;
+        }
+        // 对象格式：从 value.soulId 中提取
+        if (isPlainObject(value)) {
+            const soulId = getTrimmedString(value.soulId);
+            if (soulId) {
+                map[agentId] = soulId;
+            }
+        }
+    }
+    return map;
+}
+/**
+ * 从配置文件中读取 SoulIdMap
+ * @param configPath - 配置文件路径，默认为 LIGHTSOUL_CONFIG_PATH
+ * @returns 解析后的 agentId → soulId 映射表
+ * @throws 文件不存在或读取失败时抛出异常
+ */
+export function readSoulIdMap(configPath = LIGHTSOUL_CONFIG_PATH) {
+    return parseSoulIdMap(fs.readFileSync(configPath, 'utf8'));
+}
+/**
+ * 为 agents 列表附加 soulId
+ *
+ * 匹配规则：优先按 agent.id 查找，其次按 agent.name 查找。
+ * 若匹配到 soulId，则返回附加了 soulId 字段的新对象；否则原样返回。
+ *
+ * @param agents - agent 配置列表
+ * @param soulMap - agentId → soulId 映射表
+ * @returns 附加 soulId 后的 agents 列表（不修改原数组）
+ */
+export function attachSoulIdsToAgents(agents, soulMap) {
+    return agents.map((agent) => {
+        const id = getTrimmedString(agent.id);
+        const name = getTrimmedString(agent.name);
+        const soulId = (id && soulMap[id]) || (name && soulMap[name]) || undefined;
+        return soulId ? { ...agent, soulId } : agent;
+    });
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Socket 工具函数层统一导出
+ *
+ * 包含：消息判断/提取工具、Agent Soul ID 解析工具。
+ */
+export { isGroupMessage, extractChatId, recordSessionInHistory } from './message.js';
+export { parseSoulIdMap, readSoulIdMap, attachSoulIdsToAgents, LIGHTSOUL_CONFIG_PATH, } from './agent-soul.js';
+export { hasRequiredFields, getMissingFields } from './validate.js';

package/dist/src/socket/utils/message.js

@@ -0,0 +1,83 @@
+/**
+ * Socket 事件处理器内部工具函数
+ *
+ * 包含：isGroupMessage、extractChatId、recordSessionInHistory
+ * 从 handlers.ts 中抽离，统一管理公共逻辑。
+ */
+import { CHANNEL_KEY, DEFAULT_AGENT_ID } from '../../config.js';
+import { getLightclawRuntime } from '../../runtime.js';
+import { loadSessionStore } from '../../history/index.js';
+import { ensureSessionInHistory } from '../../utils/common.js';
+import { getModuleLogger } from '../../utils/logger.js';
+/** 模块级日志器 */
+const log = getModuleLogger('socket.utils');
+/**
+ * 判断一条 PrivateMessageData 是否为群聊消息
+ *
+ * 协议约定（docs/design.md §6.6.1）：群聊复用 EVENT_MESSAGE_PRIVATE 事件，
+ * 通过顶层 chatKind === 'group' 区分，且 extra.groupId 必填为非空字符串。
+ * 容错：缺 chatKind / groupId / 字段类型不对 → 一律视为非群聊，回退 DM 路径。
+ */
+export function isGroupMessage(data) {
+    if (data.chatKind !== 'group')
+        return false;
+    const groupId = data.extra?.groupId;
+    return typeof groupId === 'string' && groupId.trim().length > 0;
+}
+/**
+ * 从 PrivateMessageData / HistoryRequestData 中统一提取 chatId
+ *
+ * 统一为 extractChatId 后：
+ *   - 入参可能是 undefined / null / 非字符串 / 含空白字符串 / 合法字符串；
+ *   - 一律 trim 后归一为字符串；undefined / null / 非字符串 → ''；
+ *   - 返回值要么是 ''（默认对话标识），要么是非空合法 chatId。
+ */
+export function extractChatId(data) {
+    const raw = data?.extra?.chatId;
+    if (typeof raw !== 'string')
+        return '';
+    return raw.trim();
+}
+/**
+ * 把当前 chat 在用的 sessionId 登记到 chats.json[chatId].sessionIdHistory
+ *
+ * 调用时机：
+ *   - EVENT_MESSAGE_PRIVATE：在 setImmediate 中异步调用，确保框架已建好/rotate 好 session；
+ *   - EVENT_HISTORY_REQUEST：在 sessionKey 解析后同步调用，作为兜底登记入口。
+ */
+export function recordSessionInHistory(params) {
+    const { userId, agentId, chatId, accountId } = 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 },
+    });
+    const baseSessionKey = pluginRuntime.channel.routing.buildAgentSessionKey({
+        agentId: resolvedAgentId,
+        channel: CHANNEL_KEY,
+        accountId: baseRoute.accountId,
+        peer: { kind: 'direct', id: userId },
+        dmScope: 'per-channel-peer',
+    });
+    // 与 history:request 保持完全一致的 sessionKey 拼接规则：
+    //   - 空 chatId  → 不追加后缀，直接用 baseSessionKey（默认对话场景）
+    //   - 非空 chatId → 追加 `:<chatId>` 后缀（多会话场景）
+    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);
+}

package/dist/src/socket/utils/validate.js

@@ -0,0 +1,42 @@
+/**
+ * @file validate.ts
+ * @description Socket 事件请求数据的通用字段校验工具
+ *
+ * 提供泛型的必填字段校验函数，避免各 handler 重复实现相同逻辑。
+ */
+/**
+ * 校验请求数据是否包含所有必填字段（非空判断）
+ *
+ * @typeParam T - 请求数据类型
+ * @param data - 请求数据（可能为 undefined）
+ * @param requiredFields - 必填字段名称数组
+ * @returns 当所有必填字段均存在且非空时返回 true（同时作为类型守卫）
+ *
+ * @example
+ * ```ts
+ * const REQUIRED = ['from', 'msgId', 'type'] as const;
+ * if (!hasRequiredFields<GroupRequestData>(data, REQUIRED)) { ... }
+ * ```
+ */
+export function hasRequiredFields(data, requiredFields) {
+    if (!data)
+        return false;
+    return requiredFields.every((key) => !!data[key]);
+}
+/**
+ * 获取请求数据中缺失的必填字段名称列表
+ *
+ * @typeParam T - 请求数据类型
+ * @param data - 请求数据（可能为 undefined 或部分填充）
+ * @param requiredFields - 必填字段名称数组
+ * @returns 缺失字段名称数组，用于日志输出
+ *
+ * @example
+ * ```ts
+ * const missing = getMissingFields(data, REQUIRED);
+ * log.warn(`缺少字段: [${missing.join(', ')}]`);
+ * ```
+ */
+export function getMissingFields(data, requiredFields) {
+    return requiredFields.filter((key) => !data?.[key]);
+}

package/dist/src/streaming/index.js

@@ -6,6 +6,7 @@
  * 使用方式：
  *   import { createStreamReplyConfig } from "./streaming/index.js";
  */
+export { DEFAULT_PARTIAL_COALESCE } from "./types.js";
 // 增量计算器
 export { createDeltaTrackerState, toStreamDeltaText } from "./delta-tracker.js";
 // 真流式回复配置（dispatcher + replyOptions，用于 dispatchReplyFromConfig）