lightclawbot 1.2.6-beta.0 → 1.2.7

package/dist/src/tools/group-history-tool.js

@@ -0,0 +1,172 @@
+/**
+ * @file group-history-tool.ts
+ * @description 群聊历史消息查询工具
+ * 提供群聊场景下的历史消息检索能力，支持按时间分页和关键词过滤。
+ * 注册为 OpenClaw 插件工具，仅在 lightclawbot 频道的群聊会话中生效。
+ */
+import path from 'path';
+import { resolveOpenClawHome } from '../history/session-store.js';
+import { MessageReader } from '../group/storage/message-reader.js';
+import { CHANNEL_KEY } from '../config.js';
+/** 工具注册名称 */
+export const GROUP_HISTORY_TOOL_NAME = 'group_chat_history';
+/** 单条消息内容的最大展示长度，超出部分将被截断 */
+const MAX_CONTENT_LENGTH = 500;
+/** 默认返回的消息条数 */
+const DEFAULT_LIMIT = 20;
+/** 允许返回的最大消息条数 */
+const MAX_LIMIT = 50;
+/** 关键词过滤时的读取倍率，多读取数据以保证过滤后仍有足够结果 */
+const KEYWORD_READ_MULTIPLIER = 3;
+/** 从 sessionKey 中提取 groupId 的正则表达式 */
+const GROUP_ID_REGEX = /:group:(.+)$/;
+/**
+ * 群聊历史工具的参数 JSON Schema 定义
+ * 用于 Agent 调用时的参数校验和提示
+ */
+export const groupHistoryToolSchema = {
+    type: 'object',
+    properties: {
+        limit: {
+            type: 'number',
+            description: '返回的历史消息条数，默认 20，最大 50',
+        },
+        before: {
+            type: 'number',
+            description: '时间戳上限（毫秒），只返回此时间之前的消息。不传则返回最新消息',
+        },
+        keyword: {
+            type: 'string',
+            description: '关键词过滤，只返回包含该关键词的消息（大小写不敏感）',
+        },
+    },
+    required: [],
+};
+/**
+ * 从 sessionKey 中解析出 groupId
+ * @param sessionKey - 会话标识，格式如 `xxx:group:groupId`
+ * @returns 解析出的 groupId，无法解析时返回 undefined
+ */
+function parseGroupIdFromSessionKey(sessionKey) {
+    if (!sessionKey)
+        return undefined;
+    return sessionKey.match(GROUP_ID_REGEX)?.[1];
+}
+/**
+ * 根据 groupId 解析群聊数据存储目录的绝对路径
+ * @param groupId - 群组唯一标识
+ * @returns 群聊数据目录路径
+ */
+function resolveGroupDir(groupId) {
+    return path.join(resolveOpenClawHome(), 'groups', groupId);
+}
+/**
+ * 规范化 limit 参数，确保在 [1, MAX_LIMIT] 范围内
+ * @param raw - 原始 limit 值
+ * @returns 规范化后的 limit 值
+ */
+function normalizeLimit(raw) {
+    return Math.min(Math.max(raw ?? DEFAULT_LIMIT, 1), MAX_LIMIT);
+}
+/**
+ * 将单条消息记录格式化为可读字符串
+ * 格式：[时间] 角色(名称): 内容
+ * @param entry - 消息记录条目
+ * @returns 格式化后的字符串
+ */
+function formatEntry(entry) {
+    const time = new Date(entry.ts).toLocaleString('zh-CN', {
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+    });
+    const role = entry.role === 'user' ? `用户(${entry.userId ?? '未知'})` : `Agent(${entry.agentId ?? '未知'})`;
+    let content = (entry.content ?? '').trim();
+    if (content.length > MAX_CONTENT_LENGTH) {
+        content = content.slice(0, MAX_CONTENT_LENGTH) + '…(已截断)';
+    }
+    return `[${time}] ${role}: ${content}`;
+}
+/**
+ * 批量格式化消息记录列表
+ * @param entries - 消息记录数组
+ * @returns 以换行符连接的格式化字符串
+ */
+function formatEntries(entries) {
+    return entries.map(formatEntry).join('\n');
+}
+/**
+ * 构建查询成功时的返回结果
+ * @param entries - 匹配到的消息记录
+ * @param hasMore - 是否还有更早的记录可供翻页
+ * @returns 标准工具返回结果
+ */
+function buildSuccessResult(entries, hasMore) {
+    const formatted = formatEntries(entries);
+    const hasMoreHint = hasMore ? '（还有更早的记录，可通过 before 参数翻页）' : '';
+    const summary = `共找到 ${entries.length} 条消息${hasMoreHint}：\n\n${formatted}`;
+    return { content: [{ type: 'text', text: summary }] };
+}
+/**
+ * 构建纯文本的工具返回结果
+ * @param text - 要返回的文本内容
+ * @returns 标准工具返回结果
+ */
+function buildTextResult(text) {
+    return { content: [{ type: 'text', text }] };
+}
+/**
+ * 注册群聊历史消息查询工具到 OpenClaw 插件系统
+ * 该工具仅在 lightclawbot 频道的群聊会话中可用，
+ * 支持按时间分页查询和关键词过滤。
+ * @param api - OpenClaw 插件 API 实例
+ */
+export function registerGroupHistoryTool(api) {
+    const log = api.logger;
+    const reader = new MessageReader();
+    api.registerTool((ctx) => {
+        // 仅在 lightclawbot 频道生效
+        if (ctx.messageChannel !== 'lightclawbot')
+            return null;
+        // 从 sessionKey 中提取 groupId，非群聊会话则不注册此工具
+        const groupId = parseGroupIdFromSessionKey(ctx.sessionKey);
+        if (!groupId)
+            return null;
+        return {
+            name: GROUP_HISTORY_TOOL_NAME,
+            description: `查询当前群聊的历史消息记录。当你需要了解之前的对话内容、其他 Agent 的回复、用户的历史诉求时，调用此工具。返回按时间排序的对话记录，包含发言者角色、名称和内容。`,
+            parameters: groupHistoryToolSchema,
+            async execute(_toolCallId, params) {
+                const limit = normalizeLimit(params.limit);
+                const before = params.before ?? Date.now();
+                const keyword = params.keyword?.trim().toLowerCase();
+                log?.info?.(`[$${CHANNEL_KEY}:${GROUP_HISTORY_TOOL_NAME}] 开始查询群${groupId}的历史记录`);
+                try {
+                    const groupDir = resolveGroupDir(groupId);
+                    // 关键词过滤时多读取数据，确保过滤后仍有足够结果
+                    const readLimit = keyword ? limit * KEYWORD_READ_MULTIPLIER : limit;
+                    const result = await reader.readTranscriptEntries(groupDir, {
+                        limit: readLimit,
+                        before,
+                        chatOnly: true,
+                    });
+                    let entries = result.entries;
+                    // 按关键词过滤并截取指定条数
+                    if (keyword) {
+                        entries = entries.filter((e) => e.content?.toLowerCase().includes(keyword)).slice(0, limit);
+                    }
+                    if (entries.length === 0) {
+                        return buildTextResult('未找到匹配的历史消息。');
+                    }
+                    return buildSuccessResult(entries, result.hasMore);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    log?.error?.(`[$${CHANNEL_KEY}: ${GROUP_HISTORY_TOOL_NAME}] 查询失败: ${msg}`);
+                    return buildTextResult(`查询群聊历史失败: ${msg}`);
+                }
+            },
+        };
+    }, { name: GROUP_HISTORY_TOOL_NAME });
+}

package/dist/src/{upload-tool.js → tools/upload-tool.js}

@@ -13,8 +13,8 @@
  */
 import * as fsp from "node:fs/promises";
 import * as path from "node:path";
-import { formatFileSize } from "./media.js";
-import { LOCALFILE_SCHEME } from "./config.js";
+import { formatFileSize } from "../media.js";
+import { LOCALFILE_SCHEME } from "../config.js";
 // ============================================================
 // 工具参数 schema（JSON Schema 格式）
 // ============================================================

package/dist/src/tools.js

@@ -4,10 +4,11 @@
  * 在 defineChannelPluginEntry 的 registerFull 回调中注册所有 Agent Tools。
  * 此模块仅在插件完全激活后加载，避免 setup-only 模式拉起不必要的依赖。
  */
-import { registerUploadTool } from './upload-tool.js';
-// import { registerDownloadTool } from "./download-tool.js";
+import { registerUploadTool } from './tools/upload-tool.js';
+import { registerGroupHistoryTool } from './tools/group-history-tool.js';
 export function registerLightclawTools(api) {
     // 注册文件存储工具（飞书工厂函数模式：execute 时动态从 api.config 解析 apiKey）
     registerUploadTool(api);
-    // registerDownloadTool(api);
+    // 注册群聊历史查询工具（群聊场景下 Agent 可主动查询历史记录）
+    registerGroupHistoryTool(api);
 }

package/dist/src/utils/index.js

@@ -1,2 +1,3 @@
 export * from './common.js';
 export * from './account.js';
+export * from './logger.js';

package/dist/src/utils/logger.js

@@ -0,0 +1,38 @@
+import { getLightclawRuntime } from '../runtime.js';
+/**
+ * 获取模块专属日志器（惰性代理）。
+ *
+ * 返回一个 Proxy 对象，仅在实际调用日志方法（info/warn/error/debug 等）时
+ * 才通过 getLightclawRuntime() 获取真实 logger 实例并转发调用。
+ * 这样即使在模块顶层 `const log = getModuleLogger('xxx')` 也不会触发
+ * runtime 未初始化的异常。
+ *
+ * @param module 模块名称（如 'group.inbound'、'outbound'）
+ * @returns 带模块标签的惰性日志器代理
+ *
+ * @example
+ * ```ts
+ * // 可安全地在模块顶层调用
+ * const log = getModuleLogger('group.orchestrator');
+ * // 实际使用时才会初始化 runtime
+ * log.info('调度开始');
+ * ```
+ */
+export function getModuleLogger(module) {
+    let cached = null;
+    /** 获取或缓存真实 logger 实例 */
+    const resolve = () => {
+        if (!cached) {
+            cached = getLightclawRuntime().logging.getChildLogger({ module });
+        }
+        return cached;
+    };
+    return new Proxy({}, {
+        get(_target, prop, receiver) {
+            const real = resolve();
+            const value = Reflect.get(real, prop, receiver);
+            // 如果是函数则绑定到真实 logger 上下文
+            return typeof value === 'function' ? value.bind(real) : value;
+        },
+    });
+}

package/openclaw.plugin.json

@@ -78,7 +78,8 @@
   },
   "contracts": {
     "tools": [
-      "lightclaw_upload_file"
+      "lightclaw_upload_file",
+      "group_chat_history"
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightclawbot",
-  "version": "1.2.6-beta.0",
+  "version": "1.2.7",
   "description": "LightClawBot channel plugin with message support, cron jobs, and proactive messaging",
   "type": "module",
   "files": [

package/dist/src/socket/chat.js

@@ -1,257 +0,0 @@
-/**
- * LightClaw — Chat（会话元信息）处理器
- *
- * 收敛 EVENT_CHAT_REQUEST 各子类型的处理逻辑，与 handlers.ts 中的
- * 消息 / 历史 / Agents 等事件处理保持平级解耦，避免 handlers.ts 膨胀。
- *
- * 涉及的持久化文件：
- *   `~/.openclaw/agents/<agentId>/chats/<userId>/chats.json`
- *    └─ 以 ChatMeta[] 形式存储该用户在该 Agent 下的会话元信息列表
- *        （不包含消息正文，正文以 jsonl 形式另外存储）
- *
- * 四个处理器（对应 data.type）：
- *   - list：   读取 chats.json 返回 { chats }；文件不存在 / 解析失败
- *             时返回空数组，不抛错，避免阻塞前端。
- *   - create： 新建一条会话元数据，chatId = randomUUID()，插入列表最前。
- *             文件或目录不存在时由 writeChatsFile 递归创建。
- *   - update： 根据 chatId 修改 title（并置 titleLocked=true + 刷新 updatedAt）；
- *             文件或条目不存在时回 error，不隐式创建。
- *   - delete： 根据 chatId 从列表剔除，原子写回；文件或条目不存在时回 error。
- *
- * 全部响应均通过 EVENT_CHAT_RESPONSE + ReliableEmitter 发出（带 ACK + 重试）。
- * 错误处理统一走 createChatErrorSender 生成的回调，保证日志 / 响应结构一致。
- */
-import { randomUUID } from 'node:crypto';
-import * as fs from 'node:fs';
-import { CHANNEL_KEY, EVENT_CHAT_RESPONSE } from '../config.js';
-import { generateMsgId } from '../dedup.js';
-import { readChatsFile, readChatsFileOrInitDefault, resolveChatsFilePath, writeChatsFile } from '../utils/common.js';
-/**
- * 生成统一的错误响应发送器。
- *
- * 背景：list / create / update / delete 四个 handler 的错误处理结构完全一致：
- *   1. 打同一格式日志：`[CHANNEL_KEY] Chat <type> error: <msg>`
- *   2. 通过 EVENT_CHAT_RESPONSE 回同一组基础字段（msgId/from/to/type/agentId/error）
- * 仅差异项：
- *   - `type` 不同
- *   - `chatId` 是否需要回显（update/delete 需要）
- *   - list 出错时前端期望一个兜底的空列表 `chats: []`，避免 UI 处理 undefined
- *
- * 因此将其封装为模块级工厂，handler 开头调用一次即可，避免重复闭包。
- *
- * @param ctx   共享上下文（见 ChatErrorSenderContext）
- * @param extra 额外字段（如 `chatId`、兜底 `chats: []`），会与 error 一并合并到响应体
- * @returns     ChatErrorSender — 调用时传入错误信息即可
- */
-function createChatErrorSender(ctx, extra = {}) {
-    const { responseMsgId, botClientId, userId, agentId, type, reliableEmitter, log } = ctx;
-    return (error) => {
-        log?.error(`[${CHANNEL_KEY}] Chat ${type} error: ${error}`);
-        reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
-            msgId: responseMsgId,
-            from: botClientId,
-            to: userId,
-            type,
-            agentId,
-            timestamp: Date.now(),
-            ...extra,
-            error,
-        }, responseMsgId);
-    };
-}
-/**
- * 处理 EVENT_CHAT_REQUEST(type=list)：返回该用户在指定 Agent 下的会话列表。
- *
- * 行为：
- *   1. 解析当前用户 + Agent 的 chats.json 绝对路径
- *   2. 调用 readChatsFileOrInitDefault 读取：文件不存在时**主动落盘一条 chatId=''
- *      的默认会话兜底条目**，保证前端拉列表永远拿到至少一项；格式异常时返回 []
- *   3. 通过 EVENT_CHAT_RESPONSE 回 { chats }；若意外抛异常则回 { chats: [], error }
- *
- * 为什么 list 路径要主动兜底？
- *   - 用户首次连接拉列表 → 拿到默认对话 → UI 展示一致，不会出现
- *     “先空态、首条消息后又凭空多出一项”的诡异闪烁；
- *   - 兜底是幂等的：若 chats.json 已存在则等价于纯读取，无副作用；
- *   - 与 ensureSessionInHistory 的被动兜底形成双保险，覆盖“前端跳过 list
- *     直接发消息”的极端场景。
- *
- * 为什么 create/update/delete/history:request 仍走纯只读 readChatsFile？
- *   - 它们要么是用户主动操作（隐式创建语义已在 create 中处理），
- *     要么是只读查询（不应有写盘副作用），由 list 路径统一负责兜底即可。
- */
-export function handleChatList(params) {
-    const { userId, agentId, botClientId, reliableEmitter, log } = params;
-    // 当前用户在当前 Agent 下的会话记录保存路径，即 chats.json 的绝对路径
-    const chatsPath = resolveChatsFilePath(agentId, userId);
-    // 响应 msgId：同时做 ReliableEmitter 的 ack key，成功 / 失败分支共用同一枚
-    const responseMsgId = generateMsgId();
-    // list 出错时，用一个空数组兑底，避免 UI 处理 undefined
-    const sendError = createChatErrorSender({ responseMsgId, botClientId, userId, agentId, type: 'list', reliableEmitter, log }, { chats: [] });
-    try {
-        // 主动兜底读取：文件不存在则落盘一条 chatId='' 的默认会话；存在则等价于纯只读
-        const chats = readChatsFileOrInitDefault(chatsPath);
-        log?.info(`[${CHANNEL_KEY}] Chat list: userId=${userId} agentId=${agentId} count=${chats.length}`);
-        // 正常分支：统一经 ReliableEmitter 发送，依赖其 ACK + 重试保障送达
-        reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
-            msgId: responseMsgId,
-            from: botClientId,
-            to: userId,
-            type: 'list',
-            agentId,
-            chats,
-            timestamp: Date.now(),
-        }, responseMsgId);
-    }
-    catch (err) {
-        // 兼容 Error / 非 Error 投掷（如字符串 throw），统一拼接为可读消息
-        sendError(err instanceof Error ? err.message : String(err));
-    }
-}
-/**
- * 处理 EVENT_CHAT_REQUEST(type=create)：新建一条会话元数据。
- *
- * 行为：
- *   1. 解析 `~/.openclaw/agents/<agentId>/chats/<userId>/chats.json`
- *   2. 文件不存在 → 以空列表起步（writeChatsFile 会递归建目录 + 原子落盘）
- *   3. 文件存在   → 读取并在头部插入新会话（新建的默认置顶于列表最前）
- *   4. 新会话默认 `title = '新会话'`，`chatId = randomUUID()`，createdAt = updatedAt = now
- *   5. 通过 EVENT_CHAT_RESPONSE 返回 { chat: 新建项 }
- */
-export function handleChatCreate(params) {
-    const { userId, agentId, botClientId, reliableEmitter, log } = params;
-    const chatsPath = resolveChatsFilePath(agentId, userId);
-    // 响应 msgId：成功 / 失败分支共用，侜助前端根据 msgId 反查原请求
-    const responseMsgId = generateMsgId();
-    const sendError = createChatErrorSender({
-        responseMsgId,
-        botClientId,
-        userId,
-        agentId,
-        type: 'create',
-        reliableEmitter,
-        log,
-    });
-    try {
-        // 读取已有列表：文件不存在则返回 [] —— create 是隐式创建语义
-        const existing = readChatsFile(chatsPath);
-        const now = Date.now();
-        const newChat = {
-            chatId: randomUUID(),
-            title: '新会话',
-            // 新建时 titleLocked=false：首条消息后可被自动标题生成策略改写
-            titleLocked: false,
-            createdAt: now,
-            updatedAt: now,
-            pinned: false,
-            // sessionIdHistory：同一 chat 历史上使用过的 sessionId（支持会话分支 / 重置）
-            sessionIdHistory: [],
-        };
-        // 新会话插入到最前，writeChatsFile 会在目录不存在时逐级创建（tmp → rename 原子落盘）
-        const nextChats = [newChat, ...existing];
-        writeChatsFile(chatsPath, nextChats);
-        log?.info(`[${CHANNEL_KEY}] Chat create: userId=${userId} agentId=${agentId} chatId=${newChat.chatId}`);
-        reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
-            msgId: responseMsgId,
-            from: botClientId,
-            to: userId,
-            type: 'create',
-            agentId,
-            chats: [newChat],
-            timestamp: Date.now(),
-        }, responseMsgId);
-    }
-    catch (err) {
-        sendError(err instanceof Error ? err.message : String(err));
-    }
-}
-export function handleChatUpdate(params) {
-    const { userId, agentId, chatId, title, botClientId, reliableEmitter, log } = params;
-    const chatsPath = resolveChatsFilePath(agentId, userId);
-    const responseMsgId = generateMsgId();
-    // update 错误响应需要回显 chatId，便于前端关联请求
-    const sendError = createChatErrorSender({ responseMsgId, botClientId, userId, agentId, type: 'update', reliableEmitter, log }, { chatId });
-    // title 可能为纯空白字符，trim 后再判断，避免“空标题”落盘
-    const nextTitle = title?.trim();
-    if (!nextTitle) {
-        sendError('Missing title');
-        return;
-    }
-    // 文件必须存在，update 不负责创建（语义上：无源数据则无从更新）
-    if (!fs.existsSync(chatsPath)) {
-        sendError(`Chats file not found: ${chatsPath}`);
-        return;
-    }
-    try {
-        const chats = readChatsFile(chatsPath);
-        // O(n) 线性查找；chats.json 一般单用户单 Agent 规模有限，无需 Map 索引
-        const idx = chats.findIndex((c) => c.chatId === chatId);
-        if (idx < 0) {
-            sendError(`Chat not found: chatId=${chatId}`);
-            return;
-        }
-        // 更新：title + updatedAt + titleLocked
-        // titleLocked=true：用户主动改名后锁定，防止被自动标题生成策略覆盖
-        const updated = {
-            ...chats[idx],
-            title: nextTitle,
-            titleLocked: true,
-            updatedAt: Date.now(),
-        };
-        // 浅拷贝后原位替换，保留其他项的顺序（列表排序给前端决定，后端不托管）
-        const nextChats = [...chats];
-        nextChats[idx] = updated;
-        // 原子落盘：writeChatsFile 内部使用 tmp + rename 保证不损坏原文件
-        writeChatsFile(chatsPath, nextChats);
-        log?.info(`[${CHANNEL_KEY}] Chat update: userId=${userId} agentId=${agentId} chatId=${chatId} title="${nextTitle}"`);
-        reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
-            msgId: responseMsgId,
-            from: botClientId,
-            to: userId,
-            type: 'update',
-            agentId,
-            chats: [updated],
-            timestamp: Date.now(),
-        }, responseMsgId);
-    }
-    catch (err) {
-        sendError(err instanceof Error ? err.message : String(err));
-    }
-}
-export function handleChatDelete(params) {
-    const { userId, agentId, chatId, botClientId, reliableEmitter, log } = params;
-    const chatsPath = resolveChatsFilePath(agentId, userId);
-    const responseMsgId = generateMsgId();
-    // delete 错误响应需要回显 chatId，便于前端关联请求
-    const sendError = createChatErrorSender({ responseMsgId, botClientId, userId, agentId, type: 'delete', reliableEmitter, log }, { chatId });
-    // 文件必须存在，delete 不负责创建（无文件 == 无可删的项，返回明确错误）
-    if (!fs.existsSync(chatsPath)) {
-        sendError(`Chats file not found: ${chatsPath}`);
-        return;
-    }
-    try {
-        const chats = readChatsFile(chatsPath);
-        // 先确认条目存在再写盘，避免“无效删除”仍触发一次磁盘 IO
-        const idx = chats.findIndex((c) => c.chatId === chatId);
-        if (idx < 0) {
-            sendError(`Chat not found: chatId=${chatId}`);
-            return;
-        }
-        // 剔除目标项，保留其余顺序（不重排，不影响前端缓存的列表索引）
-        const nextChats = chats.filter((c) => c.chatId !== chatId);
-        // 原子落盘：writeChatsFile 内部使用 tmp + rename 保证不损坏原文件
-        writeChatsFile(chatsPath, nextChats);
-        log?.info(`[${CHANNEL_KEY}] Chat delete: userId=${userId} agentId=${agentId} chatId=${chatId} remaining=${nextChats.length}`);
-        reliableEmitter.emitWithAck(EVENT_CHAT_RESPONSE, {
-            msgId: responseMsgId,
-            from: botClientId,
-            to: userId,
-            type: 'delete',
-            agentId,
-            chats: chats.filter((c) => c.chatId === chatId),
-            timestamp: Date.now(),
-        }, responseMsgId);
-    }
-    catch (err) {
-        sendError(err instanceof Error ? err.message : String(err));
-    }
-}