lightclawbot 1.2.6 → 1.2.7

package/dist/src/group/storage/group-storage-core.js

@@ -0,0 +1,227 @@
+/**
+ * 群组存储核心服务
+ * 作为主要的接口类，整合分片管理器、消息读取器和消息写入器
+ * 提供统一的API接口，保持向后兼容性
+ */
+import path from 'path';
+import { resolveOpenClawHome } from '../../history/session-store.js';
+import { SliceManager } from './slice-manager.js';
+import { MessageReader } from './message-reader.js';
+import { MessageWriter } from './message-writer.js';
+export class GroupStorageCore {
+    /**
+     * 存储配置对象
+     */
+    config;
+    /**
+     * 分片管理器
+     */
+    sliceManager;
+    /**
+     * 消息读取器
+     */
+    messageReader;
+    /**
+     * 消息写入器
+     */
+    messageWriter;
+    /**
+     * 构造函数
+     * 初始化群组存储服务的配置参数和各个组件
+     *
+     * @param config - 部分配置参数，会与默认配置合并
+     */
+    constructor(config = {}) {
+        this.config = {
+            basePath: path.join(resolveOpenClawHome(), 'groups'),
+            maxGroupSize: 10,
+            maxHistorySize: 5000,
+            sliceConfig: {
+                maxSliceSize: 1000,
+                minSliceSize: 100,
+                strategy: 'hybrid'
+            },
+            ...config
+        };
+        this.sliceManager = new SliceManager();
+        this.messageReader = new MessageReader();
+        this.messageWriter = new MessageWriter();
+    }
+    /**
+     * 获取基础存储路径
+     * 返回配置的基础存储路径，用于外部模块了解存储位置
+     *
+     * @returns 基础存储路径字符串
+     */
+    getBasePath() {
+        return this.config.basePath;
+    }
+    /**
+     * 确保群组目录存在
+     * 内部方法，用于创建或确认群组目录的存在
+     *
+     * @param groupId - 群组ID
+     * @returns 群组目录的完整路径
+     * @throws 当目录创建失败时抛出错误
+     */
+    async ensureGroupDir(groupId) {
+        const { promises: fs } = await import('fs');
+        const groupDir = path.join(this.config.basePath, groupId);
+        await fs.mkdir(groupDir, { recursive: true });
+        return groupDir;
+    }
+    /**
+     * 读取群组元数据
+     * 从文件系统读取指定群组的元数据信息
+     *
+     * @param groupId - 要读取的群组ID
+     * @returns 群组元数据对象，如果群组不存在则返回null
+     */
+    async readGroupMeta(groupId) {
+        try {
+            const { promises: fs } = await import('fs');
+            const groupDir = path.join(this.config.basePath, groupId);
+            const metaPath = path.join(groupDir, 'meta.json');
+            const content = await fs.readFile(metaPath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch (error) {
+            // 处理文件不存在的特殊情况，返回null而不是抛出错误
+            if (error.code === 'ENOENT') {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * 写入群组元数据（原子操作）
+     * 使用原子操作方式写入群组元数据，避免数据损坏
+     *
+     * @param groupId - 要写入的群组ID
+     * @param meta - 群组元数据对象
+     * @returns Promise<void>
+     */
+    async writeGroupMeta(groupId, meta) {
+        const groupDir = await this.ensureGroupDir(groupId);
+        await this.messageWriter.writeGroupMeta(groupDir, meta);
+    }
+    /**
+     * 追加群账本条目
+     * 向群组的聊天记录文件中追加新的条目，支持分片存储
+     *
+     * @param groupId - 群组ID
+     * @param entry - 账本条目（不包含时间戳）
+     * @returns Promise<void>
+     */
+    async appendTranscriptEntry(groupId, entry) {
+        const groupDir = await this.ensureGroupDir(groupId);
+        const maxSliceSize = this.config.sliceConfig?.maxSliceSize || 1000;
+        await this.messageWriter.appendTranscriptEntry(groupDir, entry, maxSliceSize);
+    }
+    /**
+     * 批量追加消息
+     * 一次性追加多条消息，优化写入性能
+     *
+     * @param groupId - 群组ID
+     * @param entries - 消息条目数组
+     * @returns Promise<void>
+     */
+    async appendBatchTranscriptEntries(groupId, entries) {
+        const groupDir = await this.ensureGroupDir(groupId);
+        const maxSliceSize = this.config.sliceConfig?.maxSliceSize || 1000;
+        await this.messageWriter.appendBatchTranscriptEntries(groupDir, entries, maxSliceSize);
+    }
+    /**
+     * 读取群历史消息（游标分页）
+     * 读取指定群组的聊天历史记录，支持分页和过滤，支持多分片合并查询
+     *
+     * @param groupId - 群组ID
+     * @param options - 查询选项
+     * @returns 包含历史条目和分页信息的结果对象
+     */
+    async readTranscriptEntries(groupId, options = {}) {
+        const groupDir = path.join(this.config.basePath, groupId);
+        try {
+            const { promises: fs } = await import('fs');
+            await fs.access(groupDir);
+            return await this.messageReader.readTranscriptEntries(groupDir, options);
+        }
+        catch (error) {
+            // 处理目录不存在的特殊情况，返回空结果
+            if (error.code === 'ENOENT') {
+                return { entries: [], hasMore: false };
+            }
+            throw error;
+        }
+    }
+    /**
+     * 批量读取消息
+     * 读取指定时间范围内的所有消息，不分页
+     *
+     * @param groupId - 群组ID
+     * @param startTime - 开始时间戳
+     * @param endTime - 结束时间戳
+     * @param chatOnly - 是否只返回聊天内容
+     * @returns 时间范围内的所有消息
+     */
+    async readMessagesByTimeRange(groupId, startTime, endTime, chatOnly = false) {
+        const groupDir = path.join(this.config.basePath, groupId);
+        try {
+            const { promises: fs } = await import('fs');
+            await fs.access(groupDir);
+            return await this.messageReader.readMessagesByTimeRange(groupDir, startTime, endTime, chatOnly);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * 获取消息统计信息
+     * 返回群组的消息统计信息
+     *
+     * @param groupId - 群组ID
+     * @returns 消息统计信息
+     */
+    async getMessageStats(groupId) {
+        const groupDir = path.join(this.config.basePath, groupId);
+        try {
+            const { promises: fs } = await import('fs');
+            await fs.access(groupDir);
+            return await this.messageReader.getMessageStats(groupDir);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return { totalMessages: 0, sliceCount: 0 };
+            }
+            throw error;
+        }
+    }
+    /**
+     * 清除消息读取器的文件缓存。
+     * 在写入操作后调用，确保后续读取能获取到最新数据。
+     */
+    clearReaderCache() {
+        this.messageReader.clearCache();
+    }
+    /**
+     * 获取存储配置
+     * 返回当前的存储配置信息
+     *
+     * @returns 存储配置对象
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * 更新存储配置
+     * 动态更新存储配置参数
+     *
+     * @param newConfig - 新的配置参数
+     */
+    updateConfig(newConfig) {
+        this.config = { ...this.config, ...newConfig };
+    }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * @file 群组存储模块索引文件
+ * @description 统一导出所有存储相关的类和接口
+ */
+// 导出核心接口类
+export { GroupStorageCore } from './group-storage-core.js';
+// 导出专门的服务类
+export { SliceManager } from './slice-manager.js';
+export { MessageReader } from './message-reader.js';
+export { MessageWriter } from './message-writer.js';
+// 导出并发管理器
+export { ConcurrencyManager } from './concurrency-manager.js';

package/dist/src/group/storage/message-reader.js

@@ -0,0 +1,213 @@
+/**
+ * 消息读取器
+ * 专门负责群组历史消息的读取和查询功能
+ * 包括多分片合并查询、分页处理、消息过滤等高级功能
+ *
+ * 性能优化特性：
+ * - 文件内容缓存：减少重复文件读取操作
+ * - 批量读取优化：优化多分片查询性能
+ * - 智能分片处理：根据查询条件智能选择分片
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import { SliceManager } from './slice-manager.js';
+export class MessageReader {
+    sliceManager;
+    /**
+     * 文件内容缓存
+     * key: 文件路径
+     * value: { content: 文件内容, timestamp: 缓存时间 }
+     */
+    fileCache = new Map();
+    /**
+     * 缓存有效期（毫秒）
+     */
+    CACHE_TTL = 30000; // 30秒
+    constructor() {
+        this.sliceManager = new SliceManager();
+    }
+    /**
+     * 清空缓存
+     * 可用于内存管理或测试
+     */
+    clearCache() {
+        this.fileCache.clear();
+    }
+    /**
+     * 读取分片文件内容（带缓存）
+     * 读取指定分片文件中的消息记录，支持缓存优化
+     *
+     * @param groupDir - 群组目录路径
+     * @param filename - 分片文件名
+     * @param options - 查询选项
+     * @returns 分片中的消息条目数组
+     */
+    async readSliceFile(groupDir, filename, options) {
+        const filePath = path.join(groupDir, filename);
+        const now = Date.now();
+        // 检查缓存
+        const cached = this.fileCache.get(filePath);
+        if (cached && now - cached.timestamp < this.CACHE_TTL) {
+            return this.processCachedContent(cached.content, options);
+        }
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            // 更新缓存
+            this.fileCache.set(filePath, { content, timestamp: now });
+            return this.processContent(content, options);
+        }
+        catch (error) {
+            // 处理文件不存在的特殊情况，返回空数组
+            if (error.code === 'ENOENT') {
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * 处理缓存内容
+     */
+    processCachedContent(content, options) {
+        const lines = content.trim().split('\n').filter(line => line);
+        let entries = lines.map(line => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+        }).filter(Boolean);
+        // 应用过滤条件
+        if (options.chatOnly) {
+            entries = entries.filter(entry => entry.role !== 'system');
+        }
+        // 时间过滤和排序处理
+        return entries
+            .filter(entry => entry.ts < options.before)
+            .sort((a, b) => b.ts - a.ts)
+            .slice(0, options.limit);
+    }
+    /**
+     * 处理新读取的内容
+     */
+    processContent(content, options) {
+        return this.processCachedContent(content, options);
+    }
+    /**
+     * 批量读取分片文件（性能优化）
+     * 一次性读取多个分片，减少IO操作
+     */
+    async readMultipleSlices(groupDir, filenames, options) {
+        const results = await Promise.all(filenames.map(filename => this.readSliceFile(groupDir, filename, options)));
+        return results.flat();
+    }
+    /**
+     * 读取群历史消息（游标分页）
+     * 读取指定群组的聊天历史记录，支持分页和过滤，支持多分片合并查询
+     *
+     * @param groupDir - 群组目录路径
+     * @param options - 查询选项
+     * @param options.limit - 返回条数限制，默认50
+     * @param options.before - 时间戳上限，默认当前时间
+     * @param options.chatOnly - 是否只返回聊天内容，默认false
+     * @returns 包含历史条目和分页信息的结果对象
+     * @throws 当文件读取或解析失败时抛出错误（ENOENT错误除外）
+     */
+    async readTranscriptEntries(groupDir, options = {}) {
+        const { limit = 50, before = Date.now(), chatOnly = false } = options;
+        try {
+            // 获取相关分片列表
+            const relevantSlices = await this.sliceManager.getRelevantSlices(groupDir, before);
+            // 如果没有分片，返回空结果
+            if (relevantSlices.length === 0) {
+                return { entries: [], hasMore: false };
+            }
+            // 批量读取所有相关分片（性能优化）
+            const allEntries = await this.readMultipleSlices(groupDir, relevantSlices.map(slice => slice.filename), { before, limit: Number.MAX_SAFE_INTEGER, chatOnly });
+            // 排序和分页处理
+            const sortedEntries = allEntries
+                .sort((a, b) => b.ts - a.ts)
+                .slice(0, limit);
+            // 判断是否还有更多数据
+            const hasMore = await this.sliceManager.calculateHasMore(groupDir, before, sortedEntries);
+            const nextCursor = sortedEntries.length > 0 ? sortedEntries[0].ts : undefined;
+            return {
+                entries: sortedEntries.reverse(), // 按时间升序返回
+                hasMore,
+                nextCursor
+            };
+        }
+        catch (error) {
+            // 处理文件不存在的特殊情况，返回空结果
+            if (error.code === 'ENOENT') {
+                return { entries: [], hasMore: false };
+            }
+            throw error;
+        }
+    }
+    /**
+     * 批量读取消息
+     * 读取指定时间范围内的所有消息，不分页
+     *
+     * @param groupDir - 群组目录路径
+     * @param startTime - 开始时间戳
+     * @param endTime - 结束时间戳
+     * @param chatOnly - 是否只返回聊天内容
+     * @returns 时间范围内的所有消息
+     */
+    async readMessagesByTimeRange(groupDir, startTime, endTime, chatOnly = false) {
+        try {
+            const relevantSlices = await this.sliceManager.getRelevantSlices(groupDir, endTime);
+            let allEntries = [];
+            for (const slice of relevantSlices) {
+                // 如果分片的开始时间晚于结束时间，跳过
+                if (slice.startTime > endTime)
+                    continue;
+                const sliceEntries = await this.readSliceFile(groupDir, slice.filename, {
+                    before: endTime,
+                    limit: Number.MAX_SAFE_INTEGER,
+                    chatOnly
+                });
+                // 过滤开始时间之后的消息
+                const filteredEntries = sliceEntries.filter(entry => entry.ts >= startTime);
+                allEntries = [...filteredEntries, ...allEntries];
+            }
+            return allEntries.sort((a, b) => a.ts - b.ts);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * 获取消息统计信息
+     * 返回群组的消息统计信息
+     *
+     * @param groupDir - 群组目录路径
+     * @returns 消息统计信息
+     */
+    async getMessageStats(groupDir) {
+        try {
+            const fs = await import('fs');
+            const indexPath = path.join(groupDir, 'index.json');
+            if (!fs.existsSync(indexPath)) {
+                return { totalMessages: 0, sliceCount: 0 };
+            }
+            const content = await fs.promises.readFile(indexPath, 'utf-8');
+            const index = JSON.parse(content);
+            const firstSlice = index.slices[0];
+            const lastSlice = index.slices[index.slices.length - 1];
+            return {
+                totalMessages: index.totalMessages || 0,
+                sliceCount: index.slices.length,
+                firstMessageTime: firstSlice?.startTime,
+                lastMessageTime: lastSlice?.endTime
+            };
+        }
+        catch (error) {
+            return { totalMessages: 0, sliceCount: 0 };
+        }
+    }
+}

package/dist/src/group/storage/message-writer.js

@@ -0,0 +1,229 @@
+/**
+ * 消息写入器
+ * 专门负责群组消息的写入和存储管理
+ * 包括原子操作、分片切换、消息ID分配等核心功能
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import { SliceManager } from './slice-manager.js';
+import { ConcurrencyManager } from './concurrency-manager.js';
+export class MessageWriter {
+    sliceManager;
+    concurrencyManager;
+    constructor() {
+        this.sliceManager = new SliceManager();
+        this.concurrencyManager = new ConcurrencyManager();
+    }
+    /**
+     * 追加群账本条目
+     * 向群组的聊天记录文件中追加新的条目，支持分片存储
+     *
+     * @param groupDir - 群组目录路径
+     * @param entry - 账本条目（不包含时间戳）
+     * @param maxSliceSize - 单个分片最大消息数
+     * @returns Promise<void>
+     * @throws 当文件追加写入失败时抛出错误
+     */
+    async appendTranscriptEntry(groupDir, entry, maxSliceSize) {
+        // 使用锁确保消息ID分配的原子性
+        await this.concurrencyManager.withLock(`message-write-${path.basename(groupDir)}`, async () => {
+            // 获取当前活跃分片
+            const activeSlice = await this.sliceManager.getActiveSlice(groupDir, maxSliceSize);
+            const slicePath = path.join(groupDir, activeSlice.filename);
+            // 读取索引获取下一个消息ID
+            const index = await this.sliceManager.readSliceIndex(groupDir);
+            const messageId = index.nextMessageId || 1;
+            // 构建完整的账本条目，添加时间戳和消息ID
+            const fullEntry = {
+                ts: Date.now(),
+                id: messageId,
+                ...entry
+            };
+            // 格式化为JSON Lines格式
+            const line = JSON.stringify(fullEntry) + '\n';
+            const lineSize = Buffer.byteLength(line, 'utf-8');
+            // 使用追加模式写入
+            await fs.appendFile(slicePath, line, 'utf-8');
+            // 更新分片统计信息
+            await this.sliceManager.updateSliceStats(groupDir, activeSlice.filename, messageId, fullEntry.ts, lineSize);
+        }, 30000); // 30秒超时
+    }
+    /**
+     * 批量追加消息
+     * 一次性追加多条消息，优化写入性能
+     *
+     * @param groupDir - 群组目录路径
+     * @param entries - 消息条目数组
+     * @param maxSliceSize - 单个分片最大消息数
+     * @returns Promise<void>
+     */
+    async appendBatchTranscriptEntries(groupDir, entries, maxSliceSize) {
+        if (entries.length === 0)
+            return;
+        // 使用锁确保批量消息ID分配的原子性
+        await this.concurrencyManager.withLock(`batch-message-write-${path.basename(groupDir)}`, async () => {
+            // 获取当前活跃分片
+            const activeSlice = await this.sliceManager.getActiveSlice(groupDir, maxSliceSize);
+            const slicePath = path.join(groupDir, activeSlice.filename);
+            // 读取索引获取起始消息ID
+            const index = await this.sliceManager.readSliceIndex(groupDir);
+            let messageId = index.nextMessageId || 1;
+            // 构建批量写入内容
+            let batchContent = '';
+            let totalSize = 0;
+            const timestamp = Date.now();
+            for (const entry of entries) {
+                const fullEntry = {
+                    ts: timestamp,
+                    id: messageId,
+                    ...entry
+                };
+                const line = JSON.stringify(fullEntry) + '\n';
+                batchContent += line;
+                totalSize += Buffer.byteLength(line, 'utf-8');
+                messageId++;
+            }
+            // 批量写入
+            await fs.appendFile(slicePath, batchContent, 'utf-8');
+            // 更新分片统计信息
+            await this.sliceManager.updateSliceStats(groupDir, activeSlice.filename, messageId - 1, // 最后一条消息的ID
+            timestamp, totalSize);
+        }, 30000); // 30秒超时
+    }
+    /**
+     * 写入群组元数据（原子操作）
+     * 使用原子操作方式写入群组元数据，避免数据损坏
+     *
+     * @param groupDir - 群组目录路径
+     * @param meta - 群组元数据对象
+     * @returns Promise<void>
+     */
+    async writeGroupMeta(groupDir, meta) {
+        const metaPath = path.join(groupDir, 'meta.json');
+        const tempPath = `${metaPath}.tmp`;
+        // 先写入临时文件
+        await fs.writeFile(tempPath, JSON.stringify(meta, null, 2));
+        // 原子重命名
+        await fs.rename(tempPath, metaPath);
+    }
+    /**
+     * 清理过期分片
+     * 根据配置清理过期的分片文件，释放存储空间
+     *
+     * @param groupDir - 群组目录路径
+     * @param maxHistorySize - 最大历史消息数量
+     * @returns 被清理的分片数量
+     */
+    async cleanupExpiredSlices(groupDir, maxHistorySize) {
+        const index = await this.sliceManager.readSliceIndex(groupDir);
+        if (index.totalMessages <= maxHistorySize) {
+            return 0;
+        }
+        // 计算需要保留的消息数量
+        const messagesToKeep = Math.min(maxHistorySize, index.totalMessages);
+        let messagesKept = 0;
+        let slicesToRemove = [];
+        // 从最新的分片开始计算
+        const sortedSlices = [...index.slices].sort((a, b) => b.startTime - a.startTime);
+        for (const slice of sortedSlices) {
+            if (messagesKept + slice.messageCount <= messagesToKeep) {
+                messagesKept += slice.messageCount;
+            }
+            else {
+                slicesToRemove.push(slice);
+            }
+        }
+        // 移除过期的分片
+        for (const slice of slicesToRemove) {
+            const slicePath = path.join(groupDir, slice.filename);
+            try {
+                await fs.unlink(slicePath);
+            }
+            catch (error) {
+                // 忽略文件不存在的错误
+                if (error.code !== 'ENOENT') {
+                    throw error;
+                }
+            }
+        }
+        // 更新索引
+        if (slicesToRemove.length > 0) {
+            index.slices = index.slices.filter(slice => !slicesToRemove.includes(slice));
+            index.totalMessages = messagesKept;
+            await this.sliceManager.writeSliceIndex(groupDir, index);
+        }
+        return slicesToRemove.length;
+    }
+    /**
+     * 压缩分片文件
+     * 将多个小分片合并为一个大分片，优化存储效率
+     *
+     * @param groupDir - 群组目录路径
+     * @param minSliceSize - 触发压缩的最小消息数
+     * @returns 是否执行了压缩操作
+     */
+    async compactSlices(groupDir, minSliceSize) {
+        const index = await this.sliceManager.readSliceIndex(groupDir);
+        // 找出需要压缩的小分片
+        const smallSlices = index.slices.filter(slice => slice.messageCount < minSliceSize);
+        if (smallSlices.length <= 1) {
+            return false; // 只有一个或没有小分片，不需要压缩
+        }
+        // 按时间顺序排序
+        smallSlices.sort((a, b) => a.startTime - b.startTime);
+        // 读取所有小分片的消息
+        let allMessages = [];
+        for (const slice of smallSlices) {
+            const slicePath = path.join(groupDir, slice.filename);
+            try {
+                const content = await fs.readFile(slicePath, 'utf-8');
+                const lines = content.trim().split('\n').filter(line => line);
+                const messages = lines.map(line => JSON.parse(line));
+                allMessages = [...allMessages, ...messages];
+            }
+            catch (error) {
+                // 忽略读取错误
+                continue;
+            }
+        }
+        // 按时间排序
+        allMessages.sort((a, b) => a.ts - b.ts);
+        // 创建新的合并分片
+        const timestamp = Date.now();
+        const dateStr = new Date(timestamp).toISOString().split('T')[0].replace(/-/g, '');
+        const sequence = index.nextSliceSequence || 1;
+        const newFilename = `chat-${dateStr}-compacted-${String(sequence).padStart(3, '0')}.jsonl`;
+        // 写入合并后的分片
+        const newSlicePath = path.join(groupDir, newFilename);
+        let fileContent = '';
+        for (const message of allMessages) {
+            fileContent += JSON.stringify(message) + '\n';
+        }
+        await fs.writeFile(newSlicePath, fileContent, 'utf-8');
+        // 删除旧的小分片
+        for (const slice of smallSlices) {
+            const slicePath = path.join(groupDir, slice.filename);
+            try {
+                await fs.unlink(slicePath);
+            }
+            catch (error) {
+                // 忽略删除错误
+            }
+        }
+        // 更新索引
+        index.slices = index.slices.filter(slice => !smallSlices.includes(slice));
+        const newSliceInfo = {
+            filename: newFilename,
+            startTime: allMessages[0]?.ts || timestamp,
+            endTime: allMessages[allMessages.length - 1]?.ts || timestamp,
+            messageCount: allMessages.length,
+            fileSize: Buffer.byteLength(fileContent, 'utf-8'),
+            minId: allMessages[0]?.id,
+            maxId: allMessages[allMessages.length - 1]?.id
+        };
+        index.slices.push(newSliceInfo);
+        index.nextSliceSequence = sequence + 1;
+        await this.sliceManager.writeSliceIndex(groupDir, index);
+        return true;
+    }
+}