lightclawbot 1.2.6 → 1.2.8

package/dist/src/group/storage/slice-manager.js

@@ -0,0 +1,165 @@
+/**
+ * 分片管理器
+ * 专门负责群组聊天记录的分片存储管理
+ * 包括分片索引的读写、活跃分片管理、分片创建等核心功能
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+export class SliceManager {
+    /**
+     * 读取分片索引
+     * 从文件系统读取群组的分片索引信息
+     *
+     * @param groupDir - 群组目录路径
+     * @returns 分片索引对象，如果索引不存在则创建默认索引
+     */
+    async readSliceIndex(groupDir) {
+        const indexPath = path.join(groupDir, 'index.json');
+        try {
+            const content = await fs.readFile(indexPath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch (error) {
+            // 如果索引文件不存在，创建默认索引
+            if (error.code === 'ENOENT') {
+                return {
+                    version: '1.0',
+                    groupId: path.basename(groupDir),
+                    totalMessages: 0,
+                    lastUpdated: Date.now(),
+                    slices: [],
+                    nextMessageId: 1,
+                    nextSliceSequence: 1
+                };
+            }
+            throw error;
+        }
+    }
+    /**
+     * 写入分片索引（原子操作）
+     * 使用原子操作方式写入分片索引，避免数据损坏
+     *
+     * @param groupDir - 群组目录路径
+     * @param index - 分片索引对象
+     */
+    async writeSliceIndex(groupDir, index) {
+        const indexPath = path.join(groupDir, 'index.json');
+        const tempPath = `${indexPath}.tmp`;
+        // 更新最后更新时间
+        index.lastUpdated = Date.now();
+        // 先写入临时文件
+        await fs.writeFile(tempPath, JSON.stringify(index, null, 2));
+        // 原子重命名
+        await fs.rename(tempPath, indexPath);
+    }
+    /**
+     * 获取当前活跃分片
+     * 返回当前正在写入的分片信息，如果不存在则创建新分片
+     *
+     * @param groupDir - 群组目录路径
+     * @param maxSliceSize - 单个分片最大消息数
+     * @returns 活跃分片信息
+     */
+    async getActiveSlice(groupDir, maxSliceSize) {
+        const index = await this.readSliceIndex(groupDir);
+        // 如果没有分片，创建第一个分片
+        if (index.slices.length === 0) {
+            return await this.createNewSlice(groupDir, index);
+        }
+        // 获取最后一个分片
+        const lastSlice = index.slices[index.slices.length - 1];
+        // 如果最后一个分片未满，返回该分片
+        if (lastSlice.messageCount < maxSliceSize) {
+            return lastSlice;
+        }
+        // 创建新分片
+        return await this.createNewSlice(groupDir, index);
+    }
+    /**
+     * 创建新分片
+     * 创建新的分片文件并更新索引
+     *
+     * @param groupDir - 群组目录路径
+     * @param index - 当前索引
+     * @returns 新创建的分片信息
+     */
+    async createNewSlice(groupDir, index) {
+        const timestamp = Date.now();
+        const dateStr = new Date(timestamp).toISOString().split('T')[0].replace(/-/g, '');
+        const sequence = index.nextSliceSequence || 1;
+        const filename = `chat-${dateStr}-${String(sequence).padStart(3, '0')}.jsonl`;
+        const sliceInfo = {
+            filename,
+            startTime: timestamp,
+            endTime: timestamp,
+            messageCount: 0,
+            fileSize: 0,
+            minId: index.nextMessageId || 1,
+            maxId: 0
+        };
+        // 添加到索引
+        index.slices.push(sliceInfo);
+        index.activeSlice = filename;
+        index.nextSliceSequence = sequence + 1;
+        // 写入索引
+        await this.writeSliceIndex(groupDir, index);
+        return sliceInfo;
+    }
+    /**
+     * 更新分片统计信息
+     * 在写入消息后更新分片的统计信息
+     *
+     * @param groupDir - 群组目录路径
+     * @param sliceFilename - 分片文件名
+     * @param messageId - 消息ID
+     * @param timestamp - 消息时间戳
+     * @param lineSize - 写入行的字节大小
+     */
+    async updateSliceStats(groupDir, sliceFilename, messageId, timestamp, lineSize) {
+        const index = await this.readSliceIndex(groupDir);
+        const sliceIndex = index.slices.findIndex((slice) => slice.filename === sliceFilename);
+        if (sliceIndex !== -1) {
+            index.slices[sliceIndex].messageCount += 1;
+            index.slices[sliceIndex].endTime = timestamp;
+            index.slices[sliceIndex].maxId = messageId;
+            index.slices[sliceIndex].fileSize += lineSize;
+            index.totalMessages += 1;
+            index.nextMessageId = messageId + 1;
+            await this.writeSliceIndex(groupDir, index);
+        }
+    }
+    /**
+     * 获取相关分片列表
+     * 根据时间范围获取需要查询的分片列表
+     *
+     * @param groupDir - 群组目录路径
+     * @param before - 时间戳上限
+     * @returns 按时间倒序排列的相关分片列表
+     */
+    async getRelevantSlices(groupDir, before) {
+        const index = await this.readSliceIndex(groupDir);
+        return index.slices
+            .filter((slice) => slice.startTime < before)
+            .sort((a, b) => b.startTime - a.startTime);
+    }
+    /**
+     * 计算是否还有更多数据
+     * 根据索引和当前查询结果判断是否还有更早的历史记录
+     *
+     * @param groupDir - 群组目录路径
+     * @param before - 查询时间上限
+     * @param currentEntries - 当前查询结果
+     * @returns 是否还有更多数据
+     */
+    async calculateHasMore(groupDir, before, currentEntries) {
+        if (currentEntries.length === 0) {
+            return false;
+        }
+        const index = await this.readSliceIndex(groupDir);
+        // 找到最早的分片
+        const earliestSlice = index.slices.reduce((earliest, slice) => slice.startTime < earliest.startTime ? slice : earliest);
+        // 如果最早的分片开始时间早于当前查询的最早时间戳，说明还有更早的数据
+        const earliestEntryTs = currentEntries[0]?.ts || before;
+        return earliestSlice.startTime < earliestEntryTs;
+    }
+}

package/dist/src/group/types/common.js

@@ -0,0 +1,5 @@
+/**
+ * @file 群聊公共类型定义
+ * @description 群聊模块中跨子模块共享的基础类型（请求类型枚举等）
+ */
+export {};

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

@@ -0,0 +1,5 @@
+/**
+ * @file 群聊类型统一出口
+ * @description 统一导出所有跨模块共享的 TS 类型定义
+ */
+export {};

package/dist/src/group/types/message.js

@@ -0,0 +1,5 @@
+/**
+ * @file 群聊 IM 协议消息接口定义
+ * @description 定义群聊消息的基础接口，用于类型安全和消息格式标准化
+ */
+export {};

package/dist/src/group/types/orchestrator.js

@@ -0,0 +1,5 @@
+/**
+ * @file 调度器核心类型定义
+ * @description 统一收敛群聊调度器的所有内部类型
+ */
+export {};

package/dist/src/group/types/storage.js

@@ -0,0 +1,5 @@
+/**
+ * @file 群聊存储相关类型定义
+ * @description 定义群组模块的数据结构、配置选项和查询接口
+ */
+export {};

package/dist/src/group/utils/id-generator.js

@@ -0,0 +1,15 @@
+/**
+ * @file ID 生成工具
+ * @description 提供群聊模块中各类 ID 的生成方法
+ */
+/**
+ * 生成临时 runId（在 SDK 拉起 run 之前给 RunRegistry 占位用）
+ * 形如：`pre_<conversationId>_<role>_<random>`
+ *
+ * @param conversationId - 回合 ID
+ * @param role - run 角色
+ */
+export function generatePreRunId(conversationId, role) {
+    const rand = Math.random().toString(36).slice(2, 10);
+    return `pre_${conversationId}_${role}_${rand}`;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * @file 群聊公共工具函数统一出口
+ * @description 统一导出所有跨子模块共享的纯函数，供 orchestrator、inbound 等模块按需引入
+ */
+/** ID 生成：预生成 runId，用于在 run 启动前即可关联上下文 */
+export { generatePreRunId } from './id-generator.js';
+/** Run 状态处理：状态规范化、错误序列化 */
+export { normalizeRunStatus, errorToString } from './run-helpers.js';
+/** 数据规范化：mention 列表清洗与校验 */
+export { normalizeMentions } from './normalize.js';
+/** MIME 类型推断：根据文件扩展名猜测 MIME 类型 */
+export { guessMimeType } from './mime.js';

package/dist/src/group/utils/mime.js

@@ -0,0 +1,36 @@
+/**
+ * @file MIME 类型推断工具
+ * @description 根据文件扩展名猜测对应的 MIME 类型，供群聊文件处理等模块复用
+ */
+/** 扩展名到 MIME 类型的映射表 */
+const EXTENSION_MIME_MAP = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+    pdf: 'application/pdf',
+    doc: 'application/msword',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    xls: 'application/vnd.ms-excel',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    ppt: 'application/vnd.ms-powerpoint',
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    txt: 'text/plain',
+    csv: 'text/csv',
+    json: 'application/json',
+    zip: 'application/zip',
+    mp3: 'audio/mpeg',
+    mp4: 'video/mp4',
+};
+/**
+ * 根据文件扩展名猜测 MIME 类型
+ *
+ * @param fileName 文件名（含扩展名）
+ * @returns 对应的 MIME 类型字符串，未匹配时返回 'application/octet-stream'
+ */
+export function guessMimeType(fileName) {
+    const ext = fileName.split('.').pop()?.toLowerCase() ?? '';
+    return EXTENSION_MIME_MAP[ext] || 'application/octet-stream';
+}

package/dist/src/group/utils/normalize.js

@@ -0,0 +1,32 @@
+/**
+ * @file 群聊数据规范化工具
+ * @description 提供群聊场景下的数据清洗与规范化函数
+ */
+/**
+ * 规范化 mention 列表
+ *
+ * - 仅保留字符串类型且非空的 ID
+ * - 去重（保持原始顺序）
+ * - 仅保留属于当前群成员的 ID
+ *
+ * @param raw - 原始 mention 数据（来自客户端 extra，类型不可信）
+ * @param members - 当前群的合法成员 ID 列表
+ * @returns 规范化后的 mention 列表
+ */
+export function normalizeMentions(raw, members) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return [];
+    const memberSet = new Set(members);
+    const seen = new Set();
+    const result = [];
+    for (const item of raw) {
+        if (typeof item !== 'string')
+            continue;
+        const id = item.trim();
+        if (!id || seen.has(id) || !memberSet.has(id))
+            continue;
+        seen.add(id);
+        result.push(id);
+    }
+    return result;
+}

package/dist/src/group/utils/run-helpers.js

@@ -0,0 +1,36 @@
+/**
+ * @file Run 状态/错误处理工具
+ * @description 提供 Run 状态转换和错误字符串化的纯函数
+ */
+/**
+ * 把 AgentRunOutput.status 转成 RunStatus
+ */
+export function normalizeRunStatus(status) {
+    switch (status) {
+        case 'ok':
+            return 'done';
+        case 'aborted':
+            return 'aborted';
+        case 'timeout':
+        case 'error':
+        default:
+            return 'failed';
+    }
+}
+/**
+ * 把任意错误转成可见字符串（去掉栈信息）
+ */
+export function errorToString(err, fallback = '未知错误') {
+    if (!err)
+        return fallback;
+    if (err instanceof Error)
+        return err.message || fallback;
+    if (typeof err === 'string')
+        return err;
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return fallback;
+    }
+}

package/dist/src/history/session-reader.js

@@ -338,8 +338,14 @@ function parseLines(lines, opts) {
             if (!msg || typeof msg !== "object")
                 continue;
             // 过滤 openclaw delivery-mirror 消息（镜像投递，非真实消息）
-            if (msg.model === "delivery-mirror")
-                continue;
+            // 但对 cron 直接投递的消息放行（用户需要看到定时提醒内容）
+            if (msg.model === "delivery-mirror") {
+                const idempotencyKey = msg.idempotencyKey
+                    ?? parsed.idempotencyKey;
+                if (!idempotencyKey || !idempotencyKey.startsWith("cron-direct-delivery:")) {
+                    continue;
+                }
+            }
             // 过滤传输层伪装为 user 的系统注入消息
             if (isSystemInjectedUserMessage(msg))
                 continue;

package/dist/src/outbound.js

@@ -11,16 +11,11 @@
  *   2. WS 不可用时 fallback 到 REST API（需配置 apiBaseUrl）
  */
 import { CHANNEL_KEY, DEFAULT_ACCOUNT_ID, EVENT_MESSAGE_PRIVATE } from './config.js';
-import { getLightclawRuntime } from './runtime.js';
 import { getSocket, bufferMessage, hasEntry, getBotClientId, getReliableEmitter } from './socket/index.js';
 import { resolveAccount } from './utils/index.js';
-/**
- * 获取出站模块专属日志器。
- * 通过 getChildLogger 注入 module 标签，方便在日志系统中过滤出站相关日志。
- */
-function getLogger() {
-    return getLightclawRuntime().logging.getChildLogger({ module: 'outbound' });
-}
+import { getModuleLogger } from './utils/logger.js';
+/** 出站模块专属日志器（惰性代理，模块顶层安全调用） */
+const logger = getModuleLogger('outbound');
 /**
  * 出站消息 ID 计数器，用于生成全局唯一的消息序号。
  * 模块级变量，进程生命周期内单调递增，不会重置。
@@ -107,21 +102,21 @@ function sendViaSocket(accountId, target, text, replyToId) {
             emitter.emitWithAck(EVENT_MESSAGE_PRIVATE, message, msgId).then((ok) => {
                 // ok=false 表示重试耗尽仍未收到 ACK，记录错误供告警系统捕获
                 if (!ok) {
-                    getLogger().error(`[${CHANNEL_KEY}] outbound delivery failed after retries: msgId=${msgId}`);
+                    logger.error(`[${CHANNEL_KEY}] outbound delivery failed after retries: msgId=${msgId}`);
                 }
             });
-            getLogger().info(`[${CHANNEL_KEY}] outbound sent via reliable WS: to=${target} msgId=${msgId}`);
+            logger.info(`[${CHANNEL_KEY}] outbound sent via reliable WS: to=${target} msgId=${msgId}`);
             return msgId;
         }
         // 策略 2：可靠发送器不可用，直接 emit（兜底，正常情况不应走到此分支）
         try {
             entry.socket.emit(EVENT_MESSAGE_PRIVATE, message);
-            getLogger().info(`[${CHANNEL_KEY}] outbound sent via WS (fallback): to=${target} msgId=${msgId}`);
+            logger.info(`[${CHANNEL_KEY}] outbound sent via WS (fallback): to=${target} msgId=${msgId}`);
             return msgId;
         }
         catch (err) {
             // emit 本身抛异常（如 socket 已关闭），降级到 REST API
-            getLogger().warn(`[${CHANNEL_KEY}] outbound WS emit failed: ${err}`);
+            logger.warn(`[${CHANNEL_KEY}] outbound WS emit failed: ${err}`);
             return null;
         }
     }
@@ -130,7 +125,7 @@ function sendViaSocket(accountId, target, text, replyToId) {
     if (hasEntry(resolvedAccountId)) {
         const buffered = bufferMessage(resolvedAccountId, message);
         if (buffered) {
-            getLogger().info(`[${CHANNEL_KEY}] outbound buffered (WS reconnecting): to=${target} msgId=${msgId}`);
+            logger.info(`[${CHANNEL_KEY}] outbound buffered (WS reconnecting): to=${target} msgId=${msgId}`);
             return msgId;
         }
     }
@@ -153,7 +148,6 @@ function sendViaSocket(accountId, target, text, replyToId) {
  * @throws 当 WS 和 REST API 均不可用时抛出 Error
  */
 export async function sendText(ctx) {
-    const log = getLogger();
     try {
         // 解析账户配置（含 apiKey、apiBaseUrl、accountId 等）
         const account = resolveAccount(ctx.cfg, ctx.accountId);
@@ -169,7 +163,7 @@ export async function sendText(ctx) {
         if (!account.apiBaseUrl) {
             throw new Error('WS not connected and apiBaseUrl not configured, cannot send outbound message');
         }
-        log.info(`[${CHANNEL_KEY}] outbound fallback to REST API: to=${target}`);
+        logger.info(`[${CHANNEL_KEY}] outbound fallback to REST API: to=${target}`);
         const resp = await fetch(`${account.apiBaseUrl}/send`, {
             method: 'POST',
             headers: {
@@ -193,7 +187,7 @@ export async function sendText(ctx) {
         return { channel: CHANNEL_KEY, messageId: data.messageId ?? `msg_${Date.now()}` };
     }
     catch (err) {
-        log.error(`[${CHANNEL_KEY}] outbound.sendText error: ${err}`);
+        logger.error(`[${CHANNEL_KEY}] outbound.sendText error: ${err}`);
         throw err;
     }
 }
@@ -216,7 +210,6 @@ export async function sendText(ctx) {
  * @throws 当 WS 和 REST API 均不可用时抛出 Error
  */
 export async function sendMedia(ctx) {
-    const log = getLogger();
     try {
         // 解析账户配置
         const account = resolveAccount(ctx.cfg, ctx.accountId);
@@ -240,7 +233,7 @@ export async function sendMedia(ctx) {
             throw new Error('WS not connected and apiBaseUrl not configured, cannot send outbound media');
         }
         // 通过 REST API 发送完整媒体消息（含 mediaUrl）
-        log.info(`[${CHANNEL_KEY}] outbound media via REST API: to=${target}`);
+        logger.info(`[${CHANNEL_KEY}] outbound media via REST API: to=${target}`);
         const resp = await fetch(`${account.apiBaseUrl}/send-media`, {
             method: 'POST',
             headers: {
@@ -264,7 +257,7 @@ export async function sendMedia(ctx) {
         return { channel: CHANNEL_KEY, messageId: data.messageId ?? `msg_${Date.now()}` };
     }
     catch (err) {
-        log.error(`[${CHANNEL_KEY}] outbound.sendMedia error: ${err}`);
+        logger.error(`[${CHANNEL_KEY}] outbound.sendMedia error: ${err}`);
         throw err;
     }
 }

package/dist/src/shared.js

@@ -124,9 +124,10 @@ export function createLightclawPluginBase(params) {
             // true = deliver 回调会收到 kind="block" 的中间块，实现流式推送
             blockStreaming: true,
         },
-        streaming: {
-            blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
-        },
+        // 注意：原 streaming.blockStreamingCoalesceDefaults 已移除——
+        // 当前请求侧固定走 disableBlockStreaming=true（partial 通道），框架不会调用
+        // BlockReplyCoalescer，配置不生效；二次聚合改在 sink 内部由
+        // partialCoalesce 完成（详见 ADR-017 / streaming/stream-reply-sink.ts）。
         reload: { configPrefixes: [`channels.${CHANNEL_KEY}`] },
         configSchema: {
             schema: {

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

@@ -0,0 +1,147 @@
+import { CHANNEL_KEY, DEFAULT_AGENT_ID, EVENT_AGENTS_REQUEST, EVENT_AGENTS_RESPONSE } from '../../config.js';
+import { generateMsgId } from '../../dedup.js';
+import { getLightclawRuntime } from '../../runtime.js';
+import { attachSoulIdsToAgents, readSoulIdMap, LIGHTSOUL_CONFIG_PATH } from '../utils/agent-soul.js';
+import { getModuleLogger } from '../../utils/logger.js';
+/** 模块级日志器 */
+const log = getModuleLogger('socket.agents-request');
+/**
+ * 提取非空字符串，空白字符串视为无效值
+ * @param value - 待检测的未知类型值
+ * @returns 去除首尾空白后的字符串；若非字符串或为空白则返回 undefined
+ */
+const getNonEmptyString = (value) => {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+};
+/**
+ * 判断给定 agent 是否为默认的 main agent
+ * @param agent - agent 配置对象
+ * @returns 当 agent 的 id 或 name 等于 DEFAULT_AGENT_ID 时返回 true
+ */
+const isMainAgent = (agent) => {
+    const id = getNonEmptyString(agent.id);
+    const name = getNonEmptyString(agent.name);
+    return id === DEFAULT_AGENT_ID || name === DEFAULT_AGENT_ID;
+};
+/**
+ * 为缺少 workspace 的 agent 补齐默认 workspace
+ * @param agent - agent 配置对象
+ * @param defaultWorkspace - 全局默认 workspace 路径
+ * @returns 补齐 workspace 后的 agent 对象（若已有则原样返回）
+ */
+const withDefaultWorkspace = (agent, defaultWorkspace) => {
+    if (!defaultWorkspace || getNonEmptyString(agent.workspace))
+        return agent;
+    return { ...agent, workspace: defaultWorkspace };
+};
+/**
+ * 统一发送 agents 响应消息
+ * @param reliableEmitter - 可靠消息发射器
+ * @param payload - 响应载荷，包含目标、来源、agents 列表及可选错误信息
+ */
+const emitAgentsResponse = (reliableEmitter, payload) => {
+    const msgId = generateMsgId();
+    reliableEmitter.emitWithAck(EVENT_AGENTS_RESPONSE, { msgId, ...payload, timestamp: Date.now() }, msgId);
+};
+/**
+ * 标准化 agents 列表，确保始终包含一个 main agent
+ *
+ * 处理逻辑：
+ * 1. 从配置中读取 agents.list
+ * 2. 遍历列表，为已存在的 main agent 补齐默认 workspace
+ * 3. 若列表中不存在 main agent，则自动创建一个并置于列表首位
+ *
+ * @param currentCfg - 当前 openclaw.json 完整配置对象
+ * @returns 标准化后的 agents 列表（保证包含 main agent）
+ */
+const normalizeAgentsWithMainAgent = (currentCfg) => {
+    const agentsConfig = currentCfg.agents;
+    const agentsList = Array.isArray(agentsConfig?.list) ? agentsConfig.list : [];
+    // 从 defaults 中提取全局默认 workspace（如果存在且有效）
+    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);
+    });
+    // 列表中已包含 main agent，直接返回
+    if (hasMainAgent)
+        return normalizedAgents;
+    // 自动构造默认 main agent 并插入列表首位
+    const mainAgent = {
+        id: DEFAULT_AGENT_ID,
+        name: DEFAULT_AGENT_ID,
+        displayName: DEFAULT_AGENT_ID,
+        isDefault: true,
+        ...(defaultWorkspace && { workspace: defaultWorkspace }),
+    };
+    return [mainAgent, ...normalizedAgents];
+};
+/**
+ * 处理 agents:request 事件的核心逻辑
+ *
+ * 流程：加载配置 → 标准化 agents → 附加 soulId → 发送响应
+ *
+ * @param from - 请求来源客户端 ID
+ * @param botClientId - 当前 bot 客户端 ID
+ * @param reliableEmitter - 可靠消息发射器
+ */
+const handleAgentsRequest = (from, botClientId, reliableEmitter) => {
+    const pluginRuntime = getLightclawRuntime();
+    const currentCfg = pluginRuntime.config.loadConfig();
+    const agentsList = normalizeAgentsWithMainAgent(currentCfg);
+    // 尝试为 agents 附加 soulId，失败时降级使用无 soulId 的列表
+    let agentsWithSoulIds = agentsList;
+    try {
+        agentsWithSoulIds = attachSoulIdsToAgents(agentsList, readSoulIdMap());
+    }
+    catch (soulErr) {
+        const errMsg = soulErr instanceof Error ? soulErr.message : String(soulErr);
+        log.error(`[${CHANNEL_KEY}] 读取 soul 配置 ${LIGHTSOUL_CONFIG_PATH} 失败: ${errMsg}`);
+    }
+    log.info(`[${CHANNEL_KEY}] 收到 agents 请求，返回数量: ${agentsWithSoulIds.length}`);
+    emitAgentsResponse(reliableEmitter, {
+        to: from,
+        from: botClientId,
+        agents: agentsWithSoulIds,
+    });
+};
+/**
+ * 注册 agents:request 事件监听器
+ *
+ * 当收到其他客户端发来的 agents 请求时，读取最新配置并返回 agents 列表。
+ * 忽略自身发出的请求，避免消息回环。
+ *
+ * @param socket - 原生 Socket 实例
+ * @param deps - 依赖项（botClientId、reliableEmitter、onEvent 回调）
+ */
+export function bindAgentsRequestHandler(socket, deps) {
+    const { botClientId, reliableEmitter, onEvent } = deps;
+    socket.on(EVENT_AGENTS_REQUEST, (data, ack) => {
+        // 立即确认收到消息
+        ack?.();
+        // 忽略自身发出的请求，防止回环
+        if (data.from === botClientId)
+            return;
+        // 触发外部事件回调（如心跳续期）
+        onEvent?.();
+        try {
+            handleAgentsRequest(data.from, botClientId, reliableEmitter);
+        }
+        catch (err) {
+            log.error(`[${CHANNEL_KEY}] 处理 agents 请求异常: ${err}`);
+            // 发生异常时返回空列表及错误信息
+            emitAgentsResponse(reliableEmitter, {
+                to: data.from,
+                from: botClientId,
+                agents: [],
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    });
+}