lightclawbot 1.2.6 → 1.2.8

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

@@ -0,0 +1,169 @@
+/**
+ * 群成员管理服务
+ *
+ * 负责群组成员的「加入」与「移除」两类原子操作，是群聊方案 §6.4
+ * (`group:member:request`) 在领域层的具体实现。
+ *
+ * 关键约束（来自群聊方案 §2.3 A4 / §6.4.3）：
+ *   - 加成员：当前 members.length < 10，且 agentId 必须合法（在 agents.list 中）
+ *     且不在 members 中；
+ *   - 踢成员：agentId !== meta.defaultAgentId（不能踢主 Agent），且 agentId
+ *     必须 ∈ members；
+ *   - 操作必须由 ownerIds 中的用户发起（与 update/delete 一致，避免越权）；
+ *   - 成员变更后写入 system 事件到群账本：member_added / member_removed，
+ *     便于前端回放历史时还原"加群/踢出"动作（§3.4 群账本设计）。
+ *
+ * 设计选择：
+ *   - 与 GroupUpdateService 一样使用 ConcurrencyManager 加 `group_member_<groupId>`
+ *     锁，避免并发 add/remove 造成 members 列表错乱；
+ *   - agentId 是否合法（在 agents.list 中）由 socket 层注入校验函数，
+ *     service 层只关心"群内成员一致性"。这样保留域服务的纯粹性，
+ *     不直接依赖 lightclaw runtime / config，便于单元测试。
+ */
+import { GroupStorageCore } from '../storage/index.js';
+import { ConcurrencyManager } from '../storage/concurrency-manager.js';
+import { generateMsgId } from '../../dedup.js';
+export class GroupMemberService {
+    /** 群组存储服务实例（meta 读写 + 群账本追加） */
+    storage;
+    /** 并发控制管理器实例（按 groupId 加锁） */
+    concurrency;
+    /**
+     * 群成员上限（来自 §2.3 A1：Agent 数量 ≤ 10，本期 §6.4.3 校验文案 max 10）
+     */
+    static MAX_MEMBERS = 10;
+    constructor() {
+        this.storage = new GroupStorageCore();
+        this.concurrency = new ConcurrencyManager();
+    }
+    /**
+     * 添加 Agent 到群组
+     *
+     * 流程：
+     *   1. 锁内读取 meta：群必须存在 + 未解散 + 当前用户在 ownerIds 内；
+     *   2. agentId 合法性校验（可选）+ 不在 members + members 未达上限；
+     *   3. 末尾追加 agentId → 写回 meta.json（updatedAt 自动刷新）；
+     *   4. 群账本追加 system: member_added 事件（agentId 落在 entry.agentId）。
+     *
+     * @param groupId   目标群 ID
+     * @param updaterId 发起操作的用户 ID（必须 ∈ ownerIds）
+     * @param agentId   要加入的 Agent ID
+     * @param options   可选：注入 agentId 合法性校验
+     * @returns         操作完成后的 meta 与 members
+     *
+     * @throws Error 群不存在 / 已解散 / 越权 / agentId 非法 / 已在群内 / 群已满
+     */
+    async addMember(groupId, updaterId, agentId, options = {}) {
+        if (!agentId || !agentId.trim()) {
+            throw new Error('无效的 agentId：不能为空');
+        }
+        const trimmedAgentId = agentId.trim();
+        return await this.concurrency.withLock(`group_member_${groupId}`, async () => {
+            const meta = await this.requireWritableMeta(groupId, updaterId);
+            if (options.isValidAgentId && !options.isValidAgentId(trimmedAgentId)) {
+                throw new Error(`无效的 agentId：${trimmedAgentId} 不在 agents.list 中`);
+            }
+            // 基于 agentId 做去重判断，避免对象比较带来的歧义
+            if (meta.members.some((m) => m.agentId === trimmedAgentId)) {
+                throw new Error('Agent already in group');
+            }
+            if (meta.members.length >= GroupMemberService.MAX_MEMBERS) {
+                throw new Error(`Group is full (max ${GroupMemberService.MAX_MEMBERS})`);
+            }
+            // 通过注入的解析器拿到 agentName / agentDesc，缺省时以 agentId 兜底，
+            // 保证 GroupMember 三个字段始终被填写
+            const resolved = options.resolveAgentMeta?.(trimmedAgentId);
+            const newMember = {
+                agentId: trimmedAgentId,
+                agentName: resolved?.agentName ?? trimmedAgentId,
+                agentDesc: resolved?.agentDesc ?? '',
+            };
+            const updatedMeta = {
+                ...meta,
+                members: [...meta.members, newMember],
+                updatedAt: Date.now(),
+            };
+            await this.storage.writeGroupMeta(groupId, updatedMeta);
+            await this.storage.appendTranscriptEntry(groupId, {
+                role: 'system',
+                event: 'member_added',
+                agentId: trimmedAgentId,
+                msgId: generateMsgId(),
+            });
+            return {
+                meta: updatedMeta,
+                members: [...updatedMeta.members],
+            };
+        }, 30000);
+    }
+    /**
+     * 从群组踢出 Agent
+     *
+     * 流程：
+     *   1. 锁内读取 meta：群必须存在 + 未解散 + 当前用户在 ownerIds 内；
+     *   2. 不能踢主 Agent（defaultAgentId） + agentId 必须 ∈ members；
+     *   3. 从 members 中移除 → 写回 meta.json（updatedAt 自动刷新）；
+     *   4. 群账本追加 system: member_removed 事件。
+     *
+     * 注意：被踢 Agent 在该群内的历史发言保留（不删 sessions/.jsonl 与账本旧条目），
+     * 仅"不再被调度"——这是群聊方案 §6.4.3 B 的硬性约束。
+     *
+     * @param groupId   目标群 ID
+     * @param updaterId 发起操作的用户 ID（必须 ∈ ownerIds）
+     * @param agentId   要踢出的 Agent ID
+     * @returns         操作完成后的 meta 与 members
+     *
+     * @throws Error 群不存在 / 已解散 / 越权 / 试图踢主 Agent / agentId 不在群内
+     */
+    async removeMember(groupId, updaterId, agentId) {
+        if (!agentId || !agentId.trim()) {
+            throw new Error('无效的 agentId：不能为空');
+        }
+        const trimmedAgentId = agentId.trim();
+        return await this.concurrency.withLock(`group_member_${groupId}`, async () => {
+            const meta = await this.requireWritableMeta(groupId, updaterId);
+            if (trimmedAgentId === meta.defaultAgentId) {
+                throw new Error('Cannot remove default agent');
+            }
+            if (!meta.members.some((m) => m.agentId === trimmedAgentId)) {
+                throw new Error('Agent not in group');
+            }
+            const updatedMeta = {
+                ...meta,
+                members: meta.members.filter((m) => m.agentId !== trimmedAgentId),
+                updatedAt: Date.now(),
+            };
+            await this.storage.writeGroupMeta(groupId, updatedMeta);
+            await this.storage.appendTranscriptEntry(groupId, {
+                role: 'system',
+                event: 'member_removed',
+                agentId: trimmedAgentId,
+                msgId: generateMsgId(),
+            });
+            return {
+                meta: updatedMeta,
+                members: [...updatedMeta.members],
+            };
+        }, 30000);
+    }
+    /**
+     * 读取并校验"可写"状态的群元数据。
+     *
+     * 把 add / remove 共用的前置校验抽到这里，保证两条链路对"群存在性 +
+     * 解散态 + 越权"的处理完全一致：任一不通过即抛错；通过则返回原 meta，
+     * 由调用方做后续业务字段变更。
+     */
+    async requireWritableMeta(groupId, updaterId) {
+        const meta = await this.storage.readGroupMeta(groupId);
+        if (!meta) {
+            throw new Error('Group not found');
+        }
+        if (meta.dismissed === true) {
+            throw new Error('Group has been dismissed');
+        }
+        if (!meta.ownerIds.includes(updaterId)) {
+            throw new Error('Permission denied');
+        }
+        return meta;
+    }
+}

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

@@ -0,0 +1,133 @@
+/**
+ * 群组查询服务
+ * 专门负责群组数据的查询操作，包括列表查询、过滤和排序
+ *
+ * 性能优化特性：
+ * - 用户群组列表缓存：减少重复的文件系统操作
+ * - 批量元数据读取：优化多群组查询性能
+ * - 智能缓存失效：基于文件修改时间的缓存管理
+ *
+ * 主要功能：
+ * - 群组列表查询：按拥有者过滤和排序
+ * - 群组元数据读取：获取指定群组的详细信息
+ * - 权限验证：检查用户对群组的访问权限
+ *
+ * 设计特点：
+ * - 单一职责：专注于查询操作
+ * - 可复用性：可被其他服务调用
+ * - 错误处理：完善的异常捕获和空结果处理
+ */
+import { promises as fs } from 'fs';
+import { GroupStorageCore } from '../storage/index.js';
+export class GroupQueryService {
+    /**
+     * 群组存储服务实例
+     */
+    storage;
+    /**
+     * 用户群组列表缓存
+     * key: userId
+     * value: { groups: GroupMeta[], timestamp: number }
+     */
+    userGroupsCache = new Map();
+    /**
+     * 缓存有效期（毫秒）
+     */
+    CACHE_TTL = 60000; // 60秒
+    /**
+     * 构造函数
+     * 初始化查询服务的依赖组件
+     */
+    constructor() {
+        this.storage = new GroupStorageCore();
+    }
+    /**
+     * 清空缓存
+     * 可用于内存管理或测试
+     */
+    clearCache() {
+        this.userGroupsCache.clear();
+    }
+    /**
+     * 查询用户拥有的群组列表
+     * 获取用户拥有的所有活跃群组，支持排序和过滤
+     *
+     * @param userId - 用户ID
+     * @returns 群组元数据列表，按置顶优先和更新时间倒序排序
+     *
+     * 查询逻辑：
+     * 1. 检查缓存是否存在且有效
+     * 2. 读取群组存储目录
+     * 3. 批量读取所有群组元数据（性能优化）
+     * 4. 过滤：只返回当前用户拥有且未解散的群组
+     * 5. 排序：置顶群组优先，按更新时间倒序
+     */
+    async getUserGroups(userId) {
+        const now = Date.now();
+        // 检查缓存
+        const cached = this.userGroupsCache.get(userId);
+        if (cached && now - cached.timestamp < this.CACHE_TTL) {
+            return cached.groups;
+        }
+        const groupsDir = this.storage.getBasePath();
+        try {
+            const groupDirs = await fs.readdir(groupsDir);
+            const groups = [];
+            // 批量读取所有群组元数据（性能优化）
+            const metaPromises = groupDirs.map(async (groupId) => {
+                try {
+                    const meta = await this.storage.readGroupMeta(groupId);
+                    if (meta && meta.ownerIds.includes(userId) && !meta.dismissed) {
+                        return meta;
+                    }
+                }
+                catch (error) {
+                    // 忽略单个群组读取失败的情况
+                    console.warn(`读取群组 ${groupId} 元数据失败:`, error);
+                }
+                return null;
+            });
+            const metaResults = await Promise.all(metaPromises);
+            const validGroups = metaResults.filter(Boolean);
+            // 排序：置顶优先，按更新时间倒序
+            validGroups.sort((a, b) => {
+                if (a.pinned !== b.pinned) {
+                    return a.pinned ? -1 : 1;
+                }
+                return b.updatedAt - a.updatedAt;
+            });
+            // 更新缓存
+            this.userGroupsCache.set(userId, { groups: validGroups, timestamp: now });
+            return validGroups;
+        }
+        catch (error) {
+            // 如果存储目录不存在（ENOENT），返回空列表
+            if (error.code === 'ENOENT') {
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * 获取群组详细信息
+     * 读取指定群组的元数据信息
+     *
+     * @param groupId - 群组ID
+     * @returns 群组元数据，如果不存在则返回null
+     */
+    async getGroupDetail(groupId) {
+        return await this.storage.readGroupMeta(groupId);
+    }
+    /**
+     * 验证用户对群组的权限
+     * 检查用户是否有权限访问指定群组
+     *
+     * @param groupId - 群组ID
+     * @param userId - 用户ID
+     * @returns 用户是否有权限访问该群组
+     */
+    async validateUserPermission(groupId, userId) {
+        const groupMeta = await this.getGroupDetail(groupId);
+        return !!(groupMeta && groupMeta.ownerIds.includes(userId));
+    }
+}

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

@@ -0,0 +1,144 @@
+/**
+ * 群组更新服务
+ * 专门负责群组信息的更新操作，包括权限验证和字段更新
+ *
+ * 主要功能：
+ * - 权限验证：检查用户是否有权限更新群组
+ * - 字段更新：合并更新字段并维护时间戳
+ * - 并发控制：确保更新操作的原子性
+ *
+ * 设计特点：
+ * - 严格的权限验证
+ * - 安全的字段更新机制
+ * - 与存储服务解耦
+ */
+import { promises as fs } from 'fs';
+import { GroupStorageCore } from '../storage/index.js';
+import { ConcurrencyManager } from '../storage/concurrency-manager.js';
+export class GroupUpdateService {
+    /**
+     * 群组存储服务实例
+     */
+    storage;
+    /**
+     * 并发控制管理器实例
+     */
+    concurrency;
+    /**
+     * 构造函数
+     * 初始化更新服务的依赖组件
+     */
+    constructor() {
+        this.storage = new GroupStorageCore();
+        this.concurrency = new ConcurrencyManager();
+    }
+    /**
+     * 更新群组信息
+     * 执行群组信息的更新操作
+     *
+     * @param groupId - 群组ID
+     * @param updaterId - 更新者用户ID
+     * @param updates - 更新字段对象
+     * @returns 更新后的群组元数据
+     *
+     * 更新流程：
+     * 1. 权限验证（群组存在且用户是拥有者）
+     * 2. 验证更新字段有效性
+     * 3. 合并更新字段
+     * 4. 更新更新时间戳
+     * 5. 写入更新后的元数据
+     */
+    async updateGroup(groupId, updaterId, updates) {
+        return await this.concurrency.withLock(`group_update_${groupId}`, async () => {
+            const existingMeta = await this.storage.readGroupMeta(groupId);
+            if (!existingMeta) {
+                throw new Error('群组不存在');
+            }
+            if (!existingMeta.ownerIds.includes(updaterId)) {
+                throw new Error('权限不足');
+            }
+            // 验证更新字段有效性（排除members和defaultAgentId的特殊处理）
+            const hasUpdates = Object.keys(updates).some((key) => key !== 'members' && key !== 'defaultAgentId');
+            if (!hasUpdates) {
+                throw new Error('没有有效的更新字段');
+            }
+            const updatedMeta = {
+                ...existingMeta,
+                ...updates,
+                updatedAt: Date.now(),
+            };
+            // 写入群组元数据
+            await this.storage.writeGroupMeta(groupId, updatedMeta);
+            return updatedMeta;
+        }, 30000); // 30秒超时
+    }
+    /**
+     * 全量同步成员元信息
+     *
+     * 当 Agent 配置变更（agentName / agentDesc 修改）后，遍历所有群组，
+     * 将 members 中匹配的成员属性刷新为最新值。
+     *
+     * 设计要点：
+     * - 不限制 userId，无论谁改了 agent 都跟着同步
+     * - 只更新 agentName / agentDesc，不增删成员，保证成员列表一致性
+     * - 每个群组独立加锁，避免与其他更新操作冲突
+     * - 仅当群组中确实存在需要更新的成员且属性有变化时才写入，减少无效 IO
+     *
+     * @param agentMetaMap - Agent 元信息映射表，key 为 agentId
+     * @returns 同步结果，包含被更新的群组 ID 列表和扫描总数
+     */
+    async syncMembersMeta(agentMetaMap) {
+        const agentIds = Object.keys(agentMetaMap);
+        if (agentIds.length === 0) {
+            return { updatedGroupIds: [], scannedCount: 0 };
+        }
+        // 扫描所有群组目录
+        const groupsDir = this.storage.getBasePath();
+        let groupDirs = [];
+        try {
+            groupDirs = await fs.readdir(groupsDir);
+        }
+        catch {
+            // 群组目录不存在时直接返回
+            return { updatedGroupIds: [], scannedCount: 0 };
+        }
+        const updatedGroupIds = [];
+        // 并行处理所有群组（每个群组独立加锁）
+        const tasks = groupDirs.map(async (groupId) => {
+            try {
+                await this.concurrency.withLock(`group_update_${groupId}`, async () => {
+                    const meta = await this.storage.readGroupMeta(groupId);
+                    if (!meta || meta.dismissed) {
+                        return;
+                    }
+                    // 检查是否有成员需要更新
+                    let hasChange = false;
+                    const updatedMembers = meta.members.map((member) => {
+                        const newMeta = agentMetaMap[member.agentId];
+                        if (newMeta &&
+                            (member.agentName !== newMeta.agentName || member.agentDesc !== newMeta.agentDesc)) {
+                            hasChange = true;
+                            return { ...member, agentName: newMeta.agentName, agentDesc: newMeta.agentDesc };
+                        }
+                        return member;
+                    });
+                    if (!hasChange) {
+                        return;
+                    }
+                    const updatedMeta = {
+                        ...meta,
+                        members: updatedMembers,
+                        updatedAt: Date.now(),
+                    };
+                    await this.storage.writeGroupMeta(groupId, updatedMeta);
+                    updatedGroupIds.push(groupId);
+                }, 30000);
+            }
+            catch {
+                // 单个群组同步失败不影响其他群组
+            }
+        });
+        await Promise.all(tasks);
+        return { updatedGroupIds, scannedCount: groupDirs.length };
+    }
+}

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

@@ -0,0 +1,20 @@
+/**
+ * 群组服务模块索引文件
+ * 统一导出所有群组相关的服务类，便于外部模块引用
+ *
+ * 包含服务：
+ * - GroupQueryService: 群组查询服务
+ * - GroupCreationService: 群组创建服务
+ * - GroupUpdateService: 群组更新服务（含 syncMembersMeta 全量同步成员元信息）
+ * - GroupDeletionService: 群组删除服务
+ * - GroupCleanupService: 群组清理服务
+ * - GroupMemberService: 群组成员管理服务（add / remove）
+ * - GroupHistoryService: 群历史消息查询服务（chat.jsonl 游标分页 + 权限校验）
+ */
+export { GroupQueryService } from './group-query-service.js';
+export { GroupCreationService } from './group-creation-service.js';
+export { GroupUpdateService } from './group-update-service.js';
+export { GroupDeletionService } from './group-deletion-service.js';
+export { GroupCleanupService } from './group-cleanup-service.js';
+export { GroupMemberService } from './group-member-service.js';
+export { GroupHistoryService } from './group-history-service.js';

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

@@ -0,0 +1,119 @@
+/**
+ * 并发控制管理器
+ * 用于确保群聊操作的原子性和线程安全，防止数据竞争和并发冲突
+ *
+ * 设计原理：
+ * - 基于Promise的锁机制实现，确保同一时刻对同一资源的操作串行化
+ * - 使用Map数据结构存储锁状态，键为资源标识符，值为锁的Promise对象
+ * - 支持异步操作的等待和释放，保证操作的完整性和一致性
+ * - 添加超时机制防止死锁，锁状态监控便于调试
+ *
+ * 适用场景：
+ * - 群组创建、更新、删除等写操作
+ * - 群组成员管理操作
+ * - 任何需要保证操作原子性的并发场景
+ */
+export class ConcurrencyManager {
+    /**
+     * 锁状态映射表
+     * - key: 资源标识符（如groupId）
+     * - value: 表示锁状态的Promise对象，resolve时表示锁已释放
+     */
+    locks = new Map();
+    /**
+     * 锁创建时间映射表，用于监控锁状态和超时检测
+     */
+    lockTimestamps = new Map();
+    /**
+     * 默认锁超时时间（毫秒）
+     */
+    DEFAULT_TIMEOUT = 30000; // 30秒
+    /**
+     * 使用锁执行异步操作
+     * 确保同一时刻对同一资源的操作按顺序执行，避免并发冲突
+     *
+     * @param key - 锁的键，通常为资源标识符（如群组ID）
+     * @param operation - 要执行的异步操作函数，返回Promise<T>
+     * @param timeout - 锁超时时间（毫秒），默认30秒
+     * @returns 操作结果的Promise，保持原操作的返回类型
+     *
+     * @example
+     * ```typescript
+     * const manager = new ConcurrencyManager();
+     * const result = await manager.withLock('group-123', async () => {
+     *   // 执行需要并发控制的群组操作
+     *   return await updateGroup(groupId, updates);
+     * }, 60000); // 60秒超时
+     * ```
+     *
+     * 执行流程：
+     * 1. 检查是否已有相同key的锁存在
+     * 2. 如果存在，等待该锁释放，但设置超时限制
+     * 3. 创建新的锁并添加到锁映射表，记录创建时间
+     * 4. 执行操作函数，设置超时保护
+     * 5. 无论操作成功或失败，最终释放锁并清理状态
+     */
+    async withLock(key, operation, timeout = this.DEFAULT_TIMEOUT) {
+        const startTime = Date.now();
+        // 等待现有锁释放，但设置超时限制
+        while (this.locks.has(key)) {
+            const lockPromise = this.locks.get(key);
+            if (lockPromise) {
+                // 检查锁是否超时
+                const lockTimestamp = this.lockTimestamps.get(key);
+                if (lockTimestamp && Date.now() - lockTimestamp > timeout) {
+                    // 强制释放超时的锁
+                    console.warn(`锁 ${key} 已超时，强制释放`);
+                    this.locks.delete(key);
+                    this.lockTimestamps.delete(key);
+                    break;
+                }
+                // 等待锁释放，但设置超时
+                try {
+                    await Promise.race([
+                        lockPromise,
+                        new Promise((_, reject) => setTimeout(() => reject(new Error(`等待锁 ${key} 超时`)), timeout))
+                    ]);
+                }
+                catch (error) {
+                    // 等待超时，强制释放锁
+                    console.warn(`等待锁 ${key} 超时，强制释放`);
+                    this.locks.delete(key);
+                    this.lockTimestamps.delete(key);
+                    break;
+                }
+            }
+        }
+        // 创建新的锁：使用Promise控制锁的状态
+        let resolveLock;
+        const lock = new Promise(resolve => {
+            resolveLock = resolve;
+        });
+        // 设置锁状态：将新锁添加到映射表中
+        this.locks.set(key, lock);
+        this.lockTimestamps.set(key, Date.now());
+        try {
+            // 执行受保护的操作：在锁的保护下执行实际业务逻辑，设置超时保护
+            const result = await Promise.race([
+                operation(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`操作 ${key} 执行超时`)), timeout))
+            ]);
+            return result;
+        }
+        catch (error) {
+            // 记录操作失败信息
+            console.error(`锁保护的操作失败: ${key}`, error);
+            throw error;
+        }
+        finally {
+            // 清理锁状态：无论操作成功或失败，都要释放锁
+            this.locks.delete(key);
+            this.lockTimestamps.delete(key);
+            resolveLock(); // 通知等待的请求锁已释放
+            const duration = Date.now() - startTime;
+            if (duration > timeout / 2) {
+                console.warn(`锁 ${key} 持有时间较长: ${duration}ms`);
+            }
+        }
+    }
+}