lightclawbot 1.2.6 → 1.2.8

package/dist/src/group/orchestrator/routes/route-helpers.js

@@ -0,0 +1,186 @@
+/**
+ * @fileoverview 路由层公共辅助工具集
+ *
+ * @description
+ * 提取自各路由（Leader / Mention）的通用辅助方法，
+ * 供 Planning / SelfAnswer / Dispatch / MentionConcurrent 各路径复用。
+ *
+ * 包含以下能力：
+ * - 日志标签构建（buildTag）
+ * - 群成员能力卡解析（resolveMemberCards）
+ * - Leader 系统提示词构造（buildLeaderPrompt）
+ * - 统一流式输出上下文工厂封装（createSinkForAgent）
+ * - 安全账本写入（safeAppendAssistant / safeAppendSystem）
+ *
+ * @module route-helpers
+ */
+// ─── 工具函数 ──────────────────────────────────────────────────────────────────────
+import { createStreamReplyConfig } from '../../../streaming/stream-reply-sink.js';
+import { getModuleLogger } from '../../../utils/logger.js';
+import { generateMsgId } from '../../../dedup.js';
+import { CHANNEL_KEY } from '../../../config.js';
+/** 模块级日志记录器 */
+const log = getModuleLogger('group.leader-route');
+/**
+ * 禁用的内置工具列表（所有阶段通用）
+ *
+ * @remarks
+ * 这些工具在 Leader 编排场景下不允许被 Agent 调用，
+ * 因为会话管理和子 Agent 调度由编排层统一控制。
+ */
+export const DENY_TOOLS = [
+    'sessions_spawn',
+    'sessions_send',
+    'sessions_list',
+    'sessions_history',
+    'sessions_yield',
+    'session_status',
+    'sessions.spawn',
+    'subagents',
+    'agents_list',
+];
+/**
+ * 构建日志标签
+ *
+ * @param ctx - 调度上下文
+ * @returns 格式为 `[channel conv=xxx group=xxx]` 的标签字符串
+ */
+export function buildTag(ctx) {
+    return `[${CHANNEL_KEY} conv=${ctx.conversationId} group=${ctx.groupId}]`;
+}
+/**
+ * 安全解析群成员能力卡
+ *
+ * @remarks
+ * 通过 SoulResolver 将群成员元信息解析为结构化的能力卡。
+ * 解析失败时不抛出异常，降级返回空数组（Planning 阶段将视为无可派活成员）。
+ *
+ * @param deps - 路由依赖（使用 soulResolver）
+ * @param ctx - 调度上下文（使用 meta.members）
+ * @param tag - 日志标签
+ * @returns 解析后的能力卡数组，失败时为空数组
+ */
+export function resolveMemberCards(deps, ctx, tag) {
+    try {
+        return deps.soulResolver.resolveMany(ctx.meta.members);
+    }
+    catch (err) {
+        log.warn(`${tag} 解析群成员能力卡失败: ${err}，降级为空数组`);
+        return [];
+    }
+}
+/**
+ * 构造 Leader 系统提示词（不含 Planning 指令）
+ *
+ * @remarks
+ * 用于自答路径，构建 Leader 的角色定义和群成员信息提示词。
+ * 与 Planning 阶段的 `buildPlanner` 不同，此处不包含 JSON 输出格式约束。
+ * 构建失败时返回空字符串，Agent 将以默认行为运行。
+ *
+ * @param deps - 路由依赖（使用 promptBuilder）
+ * @param agentId - Leader Agent ID
+ * @param memberCards - 群成员能力卡
+ * @param tag - 日志标签
+ * @returns 系统提示词字符串，失败时为空
+ */
+export function buildLeaderPrompt(deps, agentId, memberCards, tag) {
+    try {
+        return deps.promptBuilder.buildLeader({ leaderAgentId: agentId, memberCards });
+    }
+    catch (err) {
+        log.warn(`${tag} 构建 Leader 提示词失败: ${err}`);
+        return '';
+    }
+}
+/**
+ * 构造统一流式输出上下文（公共逻辑提取）
+ *
+ * @remarks
+ * 封装 `createStreamReplyConfig` 的参数组装逻辑，
+ * 自动从 ctx 和 deps 中提取所需字段，调用方只需关注业务参数。
+ * 返回值包含完整的 StreamReplySinkContext，可直接传给 AgentRunner。
+ *
+ * @param deps - 路由依赖（使用 emitter）
+ * @param ctx - 调度上下文（使用 userId、groupId、conversationId）
+ * @param agentId - 当前发言 Agent ID
+ * @param runId - 预分配的 runId
+ * @param originalMsgId - 触发本回合的客户端原始 msgId
+ * @param options - 可选配置（parentRunId）
+ * @returns StreamReplySinkContext 实例
+ */
+export function createSinkForAgent(deps, ctx, agentId, runId, originalMsgId, options) {
+    const replyMsgId = generateMsgId();
+    // 构造 SignalContext（与私聊一致的信号上下文）
+    const signalCtx = {
+        emitter: deps.emitter,
+        targetId: ctx.userId,
+        replyMsgId,
+        originalMsgId,
+        agentId,
+    };
+    return createStreamReplyConfig({
+        emitter: deps.emitter,
+        targetId: ctx.userId,
+        replyMsgId,
+        originalMsgId,
+        effectiveApiKey: ctx.effectiveApiKey ?? '', // 群聊场景：从 DispatchContext 获取 apiKey，用于 COS 上传
+        agentId,
+        // 群聊扩展字段
+        groupId: ctx.groupId,
+        runId,
+        parentRunId: options?.parentRunId ?? null,
+        conversationId: ctx.conversationId,
+    }, {
+        // 群聊不让 SDK 自动 deliver 给 channel
+        suppressTyping: true,
+        // 预指定 runId
+        runId,
+        // abort 信号由 AgentRunner 层注入，此处不传
+    }, signalCtx);
+}
+/**
+ * 安全写 assistant 账本
+ *
+ * @remarks
+ * 将 Agent 的回复内容持久化到群账本。
+ * 写入失败时仅记录 warn 日志，不影响主流程执行。
+ *
+ * @param deps - 路由依赖（使用 ledger）
+ * @param groupId - 群 ID
+ * @param agentId - 发言 Agent ID
+ * @param content - 回复内容
+ * @param runId - 关联的 runId
+ * @param tag - 日志标签
+ */
+export async function safeAppendAssistant(deps, groupId, agentId, content, runId, tag) {
+    try {
+        await deps.ledger.appendAssistant({ groupId, agentId, content, runId, parentRunId: null });
+    }
+    catch (err) {
+        log.warn(`${tag} 写入 assistant 账本失败: ${err}`);
+    }
+}
+/**
+ * 安全写 system 账本
+ *
+ * @remarks
+ * 将系统事件（如 user_aborted、run_failed）持久化到群账本。
+ * 写入失败时仅记录 warn 日志，不影响主流程执行。
+ *
+ * @param deps - 路由依赖（使用 ledger）
+ * @param groupId - 群 ID
+ * @param event - 系统事件类型
+ * @param agentId - 关联 Agent ID
+ * @param userId - 触发用户 ID
+ * @param runId - 关联的 runId
+ * @param tag - 日志标签
+ * @param content - 可选的事件附加内容（如错误信息）
+ */
+export async function safeAppendSystem(deps, groupId, event, agentId, userId, runId, tag, content) {
+    try {
+        await deps.ledger.appendSystem({ groupId, event, agentId, userId, runId, content });
+    }
+    catch (err) {
+        log.warn(`${tag} 写入 system 账本失败: ${err}`);
+    }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * routes 子模块共享类型
+ *
+ * 两种路径（Mention / LeaderOrchestration）共享的接口契约：
+ *   - RouteDeps   路径执行依赖（由 Orchestrator 门面注入，避免重复构造）
+ *   - RouteResult 路径执行结果（用于 Orchestrator 决定回合是否落地为 DONE / FAILED）
+ */
+export {};

package/dist/src/group/services/group-cleanup-service.js

@@ -0,0 +1,183 @@
+/**
+ * 群组清理服务
+ * 专门负责群组数据的异步清理操作，包括物理文件删除和Agent session清理
+ *
+ * 主要功能：
+ * - 群组目录清理：递归删除群组物理存储数据
+ * - Agent session清理：删除相关Agent的session文件
+ * - 错误处理：完善的异常捕获和日志记录
+ *
+ * 设计特点：
+ * - 异步操作避免阻塞主线程
+ * - 安全的文件删除操作
+ * - 详细的日志记录
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { GroupStorageCore } from '../storage/index.js';
+import { CHANNEL_KEY } from '../../config.js';
+export class GroupCleanupService {
+    /**
+     * 群组存储服务实例
+     */
+    storage;
+    /**
+     * 构造函数
+     * 初始化清理服务的依赖组件
+     */
+    constructor() {
+        this.storage = new GroupStorageCore();
+    }
+    /**
+     * 异步清理群数据
+     * 在后台删除群组的物理存储数据
+     *
+     * @param groupId - 要清理的群组ID
+     *
+     * 清理内容：
+     * - 删除群组目录（递归删除所有文件）
+     * - 清理各Agent的session文件
+     * - 错误处理和日志记录
+     */
+    async cleanupGroup(groupId) {
+        try {
+            const groupDir = path.join(this.storage.getBasePath(), groupId);
+            await fs.rm(groupDir, { recursive: true, force: true });
+            // 清理各Agent的session文件
+            await this.cleanupAgentSessions(groupId);
+            console.log(`群组 ${groupId} 清理完成`);
+        }
+        catch (error) {
+            console.error(`清理群组 ${groupId} 失败:`, error);
+        }
+    }
+    /**
+     * 异步清空群组聊天账本
+     * 仅清理消息账本相关文件，保留 meta.json 等群组元数据，
+     * 同时清理各 Agent 与该群组关联的 session，保证下一轮对话从干净状态开始。
+     *
+     * @param groupId - 要清空账本的群组ID
+     *
+     * 清理内容：
+     * - 删除分片索引文件 index.json
+     * - 删除所有 chat-*.jsonl 账本分片文件
+     * - 清理各 Agent 的群组 session 文件
+     * - 保留 meta.json 等群组元数据，不影响群成员、置顶等配置
+     */
+    async clearGroupTranscript(groupId) {
+        try {
+            const groupDir = path.join(this.storage.getBasePath(), groupId);
+            // 群组目录不存在时无需清理
+            try {
+                await fs.access(groupDir);
+            }
+            catch {
+                console.warn(`群组 ${groupId} 目录不存在，跳过账本清理`);
+                // 仍然尝试清理 Agent session，避免有残留
+                await this.cleanupAgentSessions(groupId);
+                return;
+            }
+            // 仅删除账本相关文件（保留 meta.json）
+            const entries = await fs.readdir(groupDir);
+            await Promise.all(entries
+                .filter((name) => name === 'index.json' || /^chat-.*\.jsonl$/.test(name))
+                .map((name) => fs.rm(path.join(groupDir, name), { force: true })));
+            // 清理各 Agent 的 session 文件，保证对话上下文同步重置
+            await this.cleanupAgentSessions(groupId);
+            console.log(`群组 ${groupId} 账本清理完成（已保留元数据）`);
+        }
+        catch (error) {
+            console.error(`清空群组 ${groupId} 账本失败:`, error);
+        }
+    }
+    /**
+     * 清理群组相关Agent的session文件
+     * 删除群组中所有Agent的session数据，避免残留
+     *
+     * @param groupId - 要清理的群组ID
+     */
+    async cleanupAgentSessions(groupId) {
+        try {
+            // 读取群组元数据获取成员信息
+            const groupMeta = await this.storage.readGroupMeta(groupId);
+            if (!groupMeta) {
+                console.warn(`群组 ${groupId} 元数据不存在，跳过Agent session清理`);
+                return;
+            }
+            // 获取所有需要清理的Agent ID（包括默认代理）
+            const memberIds = groupMeta.members.map((m) => m.agentId);
+            const agentIds = [...new Set([...memberIds, groupMeta.defaultAgentId])];
+            for (const agentId of agentIds) {
+                await this.cleanupAgentSessionFiles(agentId, groupId);
+            }
+            console.log(`群组 ${groupId} 相关Agent session文件清理完成`);
+        }
+        catch (error) {
+            console.error(`清理群组 ${groupId} 的Agent session文件失败:`, error);
+        }
+    }
+    /**
+     * 清理单个Agent的群组相关session文件
+     * 删除Agent session目录中与该群组相关的文件，并更新sessions.json配置
+     *
+     * @param agentId - Agent ID
+     * @param groupId - 群组ID
+     */
+    async cleanupAgentSessionFiles(agentId, groupId) {
+        try {
+            const sessionsDir = path.join(os.homedir(), '.openclaw', 'agents', agentId, 'sessions');
+            // 检查session目录是否存在
+            try {
+                await fs.access(sessionsDir);
+            }
+            catch {
+                // 目录不存在，无需清理
+                return;
+            }
+            // 读取sessions.json文件
+            const sessionsJsonPath = path.join(sessionsDir, 'sessions.json');
+            let sessionsData = {};
+            try {
+                const sessionsContent = await fs.readFile(sessionsJsonPath, 'utf-8');
+                sessionsData = JSON.parse(sessionsContent);
+            }
+            catch (error) {
+                // sessions.json文件不存在或解析失败，无需清理
+                console.warn(`无法读取Agent ${agentId} 的sessions.json文件:`, error);
+                return;
+            }
+            // 构建sessionKey格式：agent:<agentId>:<channel>:group:<groupId>
+            const sessionKey = `agent:${agentId}:${CHANNEL_KEY}:group:${groupId}`;
+            // 在sessions.json中查找对应的session配置
+            const sessionEntry = sessionsData[sessionKey];
+            if (!sessionEntry || !sessionEntry.sessionId) {
+                // 没有找到对应的session配置，无需清理
+                console.log(`Agent ${agentId} 的session.json中未找到群组 ${groupId} 的session配置`);
+                return;
+            }
+            const sessionId = sessionEntry.sessionId;
+            const jsonlFileName = `${sessionId}.jsonl`;
+            const jsonlFilePath = path.join(sessionsDir, jsonlFileName);
+            // 删除对应的jsonl文件
+            try {
+                await fs.access(jsonlFilePath);
+                await fs.rm(jsonlFilePath, { force: true });
+                console.log(`删除Agent ${agentId} 的群组session文件: ${jsonlFileName}`);
+            }
+            catch (error) {
+                console.warn(`无法删除Agent ${agentId} 的session文件 ${jsonlFileName}:`, error);
+            }
+            // 从sessions.json中删除对应的session配置（重要：避免文件膨胀）
+            if (sessionsData[sessionKey]) {
+                delete sessionsData[sessionKey];
+                // 保存更新后的sessions.json文件
+                await fs.writeFile(sessionsJsonPath, JSON.stringify(sessionsData, null, 2), 'utf-8');
+                console.log(`从Agent ${agentId} 的sessions.json中删除群组 ${groupId} 的session配置`);
+            }
+        }
+        catch (error) {
+            console.error(`清理Agent ${agentId} 的session文件失败:`, error);
+        }
+    }
+}

package/dist/src/group/services/group-creation-service.js

@@ -0,0 +1,122 @@
+/**
+ * 群组创建服务
+ * 专门负责群组的创建操作，包括参数校验、UUID生成和并发控制
+ *
+ * 主要功能：
+ * - 参数校验：验证群组名称、成员列表、默认代理等参数
+ * - UUID生成：为新建群组生成唯一标识符
+ * - 并发控制：确保创建操作的原子性
+ * - 元数据构建：创建完整的群组元数据
+ *
+ * 设计特点：
+ * - 完整的参数验证链
+ * - 线程安全的创建操作
+ * - 与存储服务解耦
+ */
+import { randomUUID } from 'node:crypto';
+import { GroupStorageCore } from '../storage/index.js';
+import { ConcurrencyManager } from '../storage/concurrency-manager.js';
+export class GroupCreationService {
+    /**
+     * 群组存储服务实例
+     */
+    storage;
+    /**
+     * 并发控制管理器实例
+     */
+    concurrency;
+    /**
+     * 构造函数
+     * 初始化创建服务的依赖组件
+     */
+    constructor() {
+        this.storage = new GroupStorageCore();
+        this.concurrency = new ConcurrencyManager();
+    }
+    /**
+     * 创建新群组
+     * 执行完整的群组创建流程
+     *
+     * @param creatorId - 创建者用户ID
+     * @param name - 群组名称
+     * @param desc - 群组描述
+     * @param members - 成员列表（每个元素包含 agentId / agentName / agentDesc）
+     * @param defaultAgentId - 默认代理ID
+     * @returns 新建群组的元数据
+     *
+     * 创建流程：
+     * 1. 参数校验
+     * 2. 生成群组ID
+     * 3. 构建元数据
+     * 4. 使用锁确保原子性
+     * 5. 写入元数据和创建事件
+     */
+    async createGroup(creatorId, name, desc = '', members, defaultAgentId) {
+        // 参数校验
+        this.validateCreateParams(name, members, defaultAgentId);
+        const groupId = randomUUID();
+        const now = Date.now();
+        const groupMeta = {
+            groupId,
+            ownerIds: [creatorId],
+            name,
+            desc,
+            members,
+            defaultAgentId,
+            pinned: false,
+            createdAt: now,
+            updatedAt: now,
+        };
+        // 使用锁确保原子性
+        await this.concurrency.withLock(`group_create_${groupId}`, async () => {
+            await this.storage.writeGroupMeta(groupId, groupMeta);
+            // 写入群创建事件（账本 extra.members 仅记录 agentId 列表，
+            // 因为账本 system 事件用于追踪「事件涉及的参与者 ID」，不承载完整业务对象）
+            await this.storage.appendTranscriptEntry(groupId, {
+                role: 'system',
+                event: 'group_created',
+                msgId: `sys:group_created:${groupId}`,
+                extra: {
+                    members: members,
+                },
+            });
+        }, 30000); // 30秒超时
+        return groupMeta;
+    }
+    /**
+     * 验证创建参数
+     * 检查群组创建参数的有效性
+     *
+     * @param name - 群组名称
+     * @param members - 成员列表
+     * @param defaultAgentId - 默认代理ID
+     * @throws 如果参数无效则抛出错误
+     */
+    validateCreateParams(name, members, defaultAgentId) {
+        if (!name || name.length > 50) {
+            throw new Error('无效的群组名称：不能为空且长度不超过50个字符');
+        }
+        if (!members || members.length === 0 || members.length > 10) {
+            throw new Error('无效的成员列表：必须有1-10个成员');
+        }
+        // 单成员对象字段必填校验：避免 agentId 缺失导致后续逻辑越界
+        for (let i = 0; i < members.length; i++) {
+            const m = members[i];
+            if (!m || typeof m !== 'object') {
+                throw new Error(`无效的成员条目[${i}]：必须是对象`);
+            }
+            if (!m.agentId || typeof m.agentId !== 'string') {
+                throw new Error(`无效的成员条目[${i}]：缺少有效的 agentId`);
+            }
+        }
+        const memberIds = members.map((m) => m.agentId);
+        if (!defaultAgentId || !memberIds.includes(defaultAgentId)) {
+            throw new Error('无效的主 Agent：必须在成员列表中');
+        }
+        // 去重校验
+        const uniqueMembers = [...new Set(memberIds)];
+        if (uniqueMembers.length !== memberIds.length) {
+            throw new Error('成员列表中存在重复的代理ID');
+        }
+    }
+}

package/dist/src/group/services/group-deletion-service.js

@@ -0,0 +1,111 @@
+/**
+ * 群组删除服务
+ * 专门负责群组的解散操作，包括权限验证和软删除标记
+ *
+ * 主要功能：
+ * - 权限验证：检查用户是否有权限解散群组
+ * - 软删除标记：标记群组为解散状态
+ * - 并发控制：确保删除操作的原子性
+ * - 异步清理触发：启动后台清理任务
+ *
+ * 设计特点：
+ * - 安全的软删除机制
+ * - 异步清理避免阻塞
+ * - 与清理服务解耦
+ */
+import { GroupStorageCore } from '../storage/index.js';
+import { ConcurrencyManager } from '../storage/concurrency-manager.js';
+import { GroupCleanupService } from './group-cleanup-service.js';
+export class GroupDeletionService {
+    /**
+     * 群组存储服务实例
+     */
+    storage;
+    /**
+     * 并发控制管理器实例
+     */
+    concurrency;
+    /**
+     * 群组清理服务实例
+     */
+    cleanupService;
+    /**
+     * 构造函数
+     * 初始化删除服务的依赖组件
+     */
+    constructor() {
+        this.storage = new GroupStorageCore();
+        this.concurrency = new ConcurrencyManager();
+        this.cleanupService = new GroupCleanupService();
+    }
+    /**
+     * 解散群组
+     * 执行群组的解散操作
+     *
+     * @param groupId - 群组ID
+     * @param deleterId - 解散者用户ID
+     * @returns 解散后的群组元数据
+     *
+     * 解散流程：
+     * 1. 权限验证（群组存在且用户是拥有者）
+     * 2. 标记群组为解散状态
+     * 3. 异步启动清理任务
+     */
+    async deleteGroup(groupId, deleterId) {
+        return await this.concurrency.withLock(`group_delete_${groupId}`, async () => {
+            const existingMeta = await this.storage.readGroupMeta(groupId);
+            if (!existingMeta) {
+                throw new Error('群组不存在');
+            }
+            if (!existingMeta.ownerIds.includes(deleterId)) {
+                throw new Error('权限不足');
+            }
+            // 标记解散
+            const dismissedMeta = {
+                ...existingMeta,
+                dismissed: true,
+                updatedAt: Date.now(),
+            };
+            await this.storage.writeGroupMeta(groupId, dismissedMeta);
+            // 异步清理（不阻塞响应）
+            setTimeout(() => this.cleanupService.cleanupGroup(groupId), 0);
+            return dismissedMeta;
+        }, 30000); // 30秒超时
+    }
+    /**
+     * 清空群组聊天账本
+     * 仅清理消息记录与相关 Agent session，保留群组元数据（成员、名称、置顶等不变）
+     *
+     * @param groupId - 群组ID
+     * @param operatorId - 操作者用户ID（要求是群拥有者）
+     * @returns 操作完成后的群组元数据（仅刷新 updatedAt）
+     *
+     * 清空流程：
+     * 1. 权限验证（群组存在、未解散、用户是拥有者）
+     * 2. 异步触发账本清理任务（保留 meta.json）
+     * 3. 刷新 updatedAt 并返回最新元数据
+     */
+    async clearGroup(groupId, operatorId) {
+        return await this.concurrency.withLock(`group_clear_${groupId}`, async () => {
+            const existingMeta = await this.storage.readGroupMeta(groupId);
+            if (!existingMeta) {
+                throw new Error('群组不存在');
+            }
+            if (existingMeta.dismissed) {
+                throw new Error('群组已解散');
+            }
+            if (!existingMeta.ownerIds.includes(operatorId)) {
+                throw new Error('权限不足');
+            }
+            // 仅刷新更新时间，元数据其它字段保持不变
+            const updatedMeta = {
+                ...existingMeta,
+                updatedAt: Date.now(),
+            };
+            await this.storage.writeGroupMeta(groupId, updatedMeta);
+            // 异步清空账本（不阻塞响应）
+            setTimeout(() => this.cleanupService.clearGroupTranscript(groupId), 0);
+            return updatedMeta;
+        }, 30000); // 30秒超时
+    }
+}

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

@@ -0,0 +1,73 @@
+/**
+ * @file group-history-service.ts
+ * @description
+ * 群历史消息查询服务（业务层）。
+ *
+ * 职责：
+ *   1. 校验目标群是否存在 + 当前用户是否为 ownerIds 成员（越权拦截）；
+ *   2. 调用 GroupStorageCore.readTranscriptEntries 进行底层游标分页读取；
+ *   3. 统一返回 { messages, hasMore, nextCursor } 给 socket 层，
+ *      失败兜底由 socket 层捕获异常处理（与现有 list/create/update/delete
+ *      同款 try/catch 模式）。
+ *
+ * 与 storage 层的分工：
+ *   - storage 层只关心"目录里有什么 jsonl"，不感知群的权限语义；
+ *   - service 层负责"这个群能不能给这个用户看"，不直接接触文件系统。
+ *
+ * 设计参考：群聊方案 §6.5 群历史消息模块
+ */
+import { GroupStorageCore } from '../storage/index.js';
+/**
+ * 群历史消息服务。
+ *
+ * 单例（在 socket 层 lazy new），无内部状态，复用同一个 GroupStorageCore
+ * 实例以共享 MessageReader 内的文件缓存。
+ */
+export class GroupHistoryService {
+    /** 群存储核心：负责读 meta.json 鉴权 + 读 chat.jsonl 取历史 */
+    storage;
+    constructor(storage = new GroupStorageCore()) {
+        this.storage = storage;
+    }
+    /**
+     * 清除内部消息读取器的文件缓存。
+     * 在成员变更等写入操作后调用，确保下次 getHistory 读取到最新数据。
+     */
+    clearReaderCache() {
+        this.storage.clearReaderCache();
+    }
+    /**
+     * 查询群历史消息。
+     *
+     * 流程：
+     *   1. 读 meta.json：群不存在 → 抛 'Group not found'；
+     *   2. 校验 ownerIds.includes(userId)：不通过 → 抛 'Permission denied'；
+     *   3. 调 storage.readTranscriptEntries 走分片读取 + 时间游标分页；
+     *   4. storage 返回 { entries, hasMore, nextCursor }，按协议字段名映射。
+     *
+     * @throws 'Group not found' | 'Permission denied'
+     *         | 文件读取异常（由 storage 层抛出，socket 层兜底回 error）
+     */
+    async getHistory(query) {
+        const { groupId, userId, limit, before, chatOnly } = query;
+        // ① 群存在性 + 越权校验
+        const meta = await this.storage.readGroupMeta(groupId);
+        if (!meta) {
+            throw new Error('Group not found');
+        }
+        if (!meta.ownerIds.includes(userId)) {
+            throw new Error('Permission denied');
+        }
+        // ② 读取群账本（storage 内部已做 ENOENT 兜底 → 空结果）
+        const result = await this.storage.readTranscriptEntries(groupId, {
+            limit,
+            before,
+            chatOnly,
+        });
+        return {
+            messages: result.entries,
+            hasMore: result.hasMore,
+            nextCursor: result.nextCursor,
+        };
+    }
+}