lightclawbot 1.2.6 → 1.2.8

package/dist/src/group/orchestrator/lifecycle/conversation-state.js

@@ -0,0 +1,162 @@
+/**
+ * 回合状态机（ConversationStateMachine）
+ *
+ * 单次回合（一次"用户发问 → 系统回完所有内容"）对应一个状态机实例。
+ * 由 Orchestrator 在 dispatch() 入口创建，贯穿三种路径（A/B/C）和 abort/失败兜底。
+ *
+ * 状态转移表（与 types.ts ConversationStatus 注释一致）：
+ *
+ *   PENDING           → ROUTING
+ *   ROUTING           → RUNNING_LEADER | RUNNING_CHILDREN
+ *   RUNNING_LEADER    → DONE | PLANNING | ABORTED | FAILED
+ *   PLANNING          → RUNNING_CHILDREN | FAILED
+ *   RUNNING_CHILDREN  → DONE | SUMMARIZING | ABORTED | FAILED
+ *   SUMMARIZING       → DONE | ABORTED | FAILED
+ *   DONE / ABORTED / FAILED  终态，不可再转移
+ *
+ * 设计要点：
+ *  1. 非法转移立刻抛错，避免静默错乱；
+ *  2. 状态变更可订阅（onChange），方便接日志 / metrics；
+ *  3. 提供 isTerminal() / isRunning() 等便捷判断。
+ */
+/**
+ * 合法状态转移表（key → 允许进入的状态集合）
+ */
+const TRANSITIONS = {
+    PENDING: ['ROUTING', 'ABORTED', 'FAILED'],
+    ROUTING: ['RUNNING_LEADER', 'RUNNING_CHILDREN', 'ABORTED', 'FAILED'],
+    RUNNING_LEADER: ['DONE', 'PLANNING', 'ABORTED', 'FAILED'],
+    PLANNING: ['RUNNING_CHILDREN', 'ABORTED', 'FAILED'],
+    RUNNING_CHILDREN: ['DONE', 'SUMMARIZING', 'ABORTED', 'FAILED'],
+    SUMMARIZING: ['DONE', 'ABORTED', 'FAILED'],
+    DONE: [],
+    ABORTED: [],
+    FAILED: [],
+};
+/**
+ * 终态集合
+ */
+const TERMINAL_STATES = new Set([
+    'DONE',
+    'ABORTED',
+    'FAILED',
+]);
+/**
+ * 运行中状态集合（未进入终态、且已离开 PENDING/ROUTING）
+ */
+const RUNNING_STATES = new Set([
+    'RUNNING_LEADER',
+    'PLANNING',
+    'RUNNING_CHILDREN',
+    'SUMMARIZING',
+]);
+/**
+ * 回合状态机
+ */
+export class ConversationStateMachine {
+    /** 关联的 conversationId */
+    conversationId;
+    /** 当前状态 */
+    current;
+    /** 状态变更监听器列表 */
+    listeners = [];
+    /**
+     * 构造一个新的状态机
+     *
+     * @param conversationId - 回合唯一 ID
+     * @param initial - 初始状态，默认为 PENDING
+     */
+    constructor(conversationId, initial = 'PENDING') {
+        this.conversationId = conversationId;
+        this.current = initial;
+    }
+    /**
+     * 获取当前状态
+     */
+    getStatus() {
+        return this.current;
+    }
+    /**
+     * 是否处于终态
+     */
+    isTerminal() {
+        return TERMINAL_STATES.has(this.current);
+    }
+    /**
+     * 是否处于运行中状态
+     */
+    isRunning() {
+        return RUNNING_STATES.has(this.current);
+    }
+    /**
+     * 判断从当前状态能否转移到目标状态
+     *
+     * @param next - 目标状态
+     */
+    canTransitionTo(next) {
+        return TRANSITIONS[this.current].includes(next);
+    }
+    /**
+     * 执行状态转移
+     *
+     * @param next - 目标状态
+     * @throws 当目标状态不在合法转移表中时抛错
+     */
+    transitionTo(next) {
+        if (this.current === next) {
+            // 同状态自循环视为 no-op，避免上层重复调用时报错
+            return;
+        }
+        if (!this.canTransitionTo(next)) {
+            throw new Error(`[Orchestrator] 非法状态转移: ${this.current} → ${next} (conversationId=${this.conversationId})`);
+        }
+        const prev = this.current;
+        this.current = next;
+        this.notify(next, prev);
+    }
+    /**
+     * 强制转移到终态（ABORTED / FAILED）
+     * 用于级联 abort 或全局兜底，绕过普通转移表
+     *
+     * @param next - 必须是终态
+     * @throws 当 next 不是终态时抛错
+     */
+    forceTerminal(next) {
+        if (this.current === next)
+            return;
+        if (this.isTerminal()) {
+            // 已在终态，幂等返回
+            return;
+        }
+        const prev = this.current;
+        this.current = next;
+        this.notify(next, prev);
+    }
+    /**
+     * 注册状态变更监听器
+     *
+     * @param listener - 回调
+     * @returns 取消订阅函数
+     */
+    onChange(listener) {
+        this.listeners.push(listener);
+        return () => {
+            this.listeners = this.listeners.filter((l) => l !== listener);
+        };
+    }
+    /**
+     * 内部：通知所有监听器
+     */
+    notify(next, prev) {
+        for (const listener of this.listeners) {
+            try {
+                listener(next, prev);
+            }
+            catch (err) {
+                // 监听器异常不影响状态机本身
+                // 后续接入统一日志后改为 logger.warn
+                console.warn('[ConversationStateMachine] listener error:', err);
+            }
+        }
+    }
+}

package/dist/src/group/orchestrator/lifecycle/index.js

@@ -0,0 +1,7 @@
+/**
+ * lifecycle 子模块出口
+ * 统一导出回合状态机、Run 注册表、群账本写入器
+ */
+export { ConversationStateMachine } from './conversation-state.js';
+export { RunRegistry } from './run-registry.js';
+export { LedgerWriter } from './ledger-writer.js';

package/dist/src/group/orchestrator/lifecycle/ledger-writer.js

@@ -0,0 +1,96 @@
+/**
+ * LedgerWriter —— 群账本写入器
+ *
+ * 调度器内 **唯一** 写群账本的入口。
+ * 内部复用 `GroupStorageCore.appendTranscriptEntry`（已带分片 + 锁），
+ * 对外暴露三类语义化 API：
+ *
+ *  - appendUser(...)        写一条 role=user 条目
+ *  - appendAssistant(...)   写一条 role=assistant 条目
+ *  - appendSystem(...)      写一条 role=system 条目
+ *
+ * 设计要点：
+ *  1. 不直接调用 fs，所有 IO 通过 GroupStorageCore；
+ *  2. 屏蔽底层 TranscriptEntry 字段拼装细节，调用方传业务参数即可；
+ *  3. 写入失败抛错，由上层（Orchestrator）决定降级策略。
+ */
+import { generateMsgId } from '../../../dedup.js';
+/**
+ * 群账本写入器
+ */
+export class LedgerWriter {
+    storage;
+    /**
+     * @param storage - 群存储核心实例（建议外部单例传入）
+     */
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * 追加用户消息条目
+     *
+     * @param input - 用户消息入参
+     */
+    async appendUser(input) {
+        const { groupId, userId, content, mentions, files, msgId } = input;
+        await this.storage.appendTranscriptEntry(groupId, {
+            role: 'user',
+            userId,
+            content,
+            // 仅在显式提供时写入，避免给历史数据兜出 undefined 字段
+            ...(msgId ? { msgId } : {}),
+            // 文件附件放在顶层（与前端 TranscriptEntry 对齐）
+            ...(files && files.length > 0 ? { files } : {}),
+            extra: this.buildExtra({ mentions }),
+        });
+    }
+    /**
+     * 追加 Agent 回复条目
+     *
+     * @param input - Agent 回复入参
+     */
+    async appendAssistant(input) {
+        const { groupId, agentId, content, runId, parentRunId = null } = input;
+        await this.storage.appendTranscriptEntry(groupId, {
+            role: 'assistant',
+            agentId,
+            content,
+            runId,
+            parentRunId,
+            // 统一去重锰点：assistant 条目以 runId 作为 msgId，
+            // 使前端在「流式收尾本地追加 vs 后端历史回放」之间可用同一 key 去重。
+            msgId: runId,
+        });
+    }
+    /**
+     * 追加系统事件条目
+     *
+     * @param input - 系统事件入参
+     */
+    async appendSystem(input) {
+        const { groupId, event, agentId, userId, runId, content, members } = input;
+        await this.storage.appendTranscriptEntry(groupId, {
+            role: 'system',
+            event,
+            agentId,
+            userId,
+            runId,
+            content,
+            // 统一去重锚点：加 'sys:' 前缀避免与 assistant 条目（msgId=runId）冲突，
+            // 否则前端 mergeEntries 按 msgId 去重时会误将 system 条目当作 assistant 的重复而跳过。
+            // 缺省时本地生成一个唯一 ID，保证账本中的所有条目都带 msgId。
+            msgId: runId ? `sys:${runId}` : generateMsgId(),
+            extra: members && members.length > 0 ? { members } : undefined,
+        });
+    }
+    /**
+     * 内部：构造 extra 字段，过滤空值
+     */
+    buildExtra(input) {
+        const extra = {};
+        if (input.mentions && input.mentions.length > 0) {
+            extra.mentions = input.mentions;
+        }
+        return Object.keys(extra).length > 0 ? extra : undefined;
+    }
+}

package/dist/src/group/orchestrator/lifecycle/run-registry.js

@@ -0,0 +1,174 @@
+/**
+ * RunRegistry —— Run 注册表 / 级联 Abort 控制器
+ *
+ * 调度器维护的核心数据结构之一：
+ *   Map<conversationId, Map<runId, AbortController>>
+ *
+ * 用途：
+ *  1. 注册某次回合下启动的所有 run（leader / mention / child / summarizer）；
+ *  2. 用户点停止时，按 conversationId 一次性级联 abort 整棵 run 树；
+ *  3. 单 run 异常时，定向 abort 单条 run；
+ *  4. 提供 conversation 级 AbortSignal，供调度器直接传给 dispatch 流程。
+ *
+ * 设计要点：
+ *  - 完全内存态，不做持久化；
+ *  - 所有写操作做幂等处理，重复 register / abort 不抛错；
+ *  - abortConversation 返回实际被中止的 runId 列表，方便接 group:abort:response。
+ */
+/**
+ * Run 注册表（单例由 Orchestrator 持有）
+ */
+export class RunRegistry {
+    /** conversationId → 桶 */
+    conversations = new Map();
+    /**
+     * 创建（或复用）一个回合桶，返回其级联 abort 信号
+     *
+     * @param conversationId - 回合 ID
+     */
+    ensureConversation(conversationId) {
+        let bucket = this.conversations.get(conversationId);
+        if (!bucket) {
+            bucket = {
+                rootController: new AbortController(),
+                runs: new Map(),
+            };
+            this.conversations.set(conversationId, bucket);
+        }
+        return bucket.rootController.signal;
+    }
+    /**
+     * 注册一次具体的 Agent 执行
+     * 自动监听回合级 abort，触发后立即 abort 本 run
+     *
+     * @param conversationId - 所属回合
+     * @param runId - run 唯一 ID
+     * @param agentId - 执行 Agent
+     * @returns 该 run 的 AbortSignal（传给 subagent.run）
+     */
+    registerRun(conversationId, runId, agentId) {
+        const bucket = this.getOrCreateBucket(conversationId);
+        // 幂等：重复注册同 runId 直接返回原 signal
+        const existed = bucket.runs.get(runId);
+        if (existed) {
+            return existed.controller.signal;
+        }
+        const controller = new AbortController();
+        const registered = {
+            runId,
+            agentId,
+            controller,
+            aborted: false,
+        };
+        bucket.runs.set(runId, registered);
+        // 回合级 abort 触发时，级联 abort 本 run
+        const onRootAbort = () => {
+            if (!registered.aborted) {
+                registered.aborted = true;
+                controller.abort();
+            }
+        };
+        if (bucket.rootController.signal.aborted) {
+            onRootAbort();
+        }
+        else {
+            bucket.rootController.signal.addEventListener('abort', onRootAbort, { once: true });
+        }
+        return controller.signal;
+    }
+    /**
+     * 解除注册（run 正常结束 / 失败时调用，避免泄漏）
+     *
+     * @param conversationId - 回合 ID
+     * @param runId - run ID
+     */
+    unregisterRun(conversationId, runId) {
+        const bucket = this.conversations.get(conversationId);
+        if (!bucket)
+            return;
+        bucket.runs.delete(runId);
+    }
+    /**
+     * 中止单条 run（不影响同回合其他 run）
+     *
+     * @param conversationId - 回合 ID
+     * @param runId - run ID
+     * @returns 是否真的执行了 abort（false 表示不存在或已 abort）
+     */
+    abortRun(conversationId, runId) {
+        const bucket = this.conversations.get(conversationId);
+        if (!bucket)
+            return false;
+        const run = bucket.runs.get(runId);
+        if (!run || run.aborted)
+            return false;
+        run.aborted = true;
+        run.controller.abort();
+        return true;
+    }
+    /**
+     * 级联中止整个回合
+     * 触发 rootController.abort()，所有已注册 run 自动级联 abort
+     *
+     * @param conversationId - 回合 ID
+     * @returns 实际被中止的 runId 列表（已 abort 的不计入）
+     */
+    abortConversation(conversationId) {
+        const bucket = this.conversations.get(conversationId);
+        if (!bucket)
+            return [];
+        const aborted = [];
+        // 先触发回合级 abort，让 onRootAbort 监听器统一处理
+        if (!bucket.rootController.signal.aborted) {
+            bucket.rootController.abort();
+        }
+        // 兜底遍历：确保所有 run 都被标记并收集 ID
+        for (const run of bucket.runs.values()) {
+            if (!run.aborted) {
+                run.aborted = true;
+                run.controller.abort();
+            }
+            aborted.push(run.runId);
+        }
+        return aborted;
+    }
+    /**
+     * 清理已完成的回合（应在终态后调用，避免内存泄漏）
+     *
+     * @param conversationId - 回合 ID
+     */
+    disposeConversation(conversationId) {
+        this.conversations.delete(conversationId);
+    }
+    /**
+     * 获取某回合下所有 runId（调试 / metrics 用）
+     *
+     * @param conversationId - 回合 ID
+     */
+    listRunIds(conversationId) {
+        const bucket = this.conversations.get(conversationId);
+        if (!bucket)
+            return [];
+        return Array.from(bucket.runs.keys());
+    }
+    /**
+     * 当前在跑的回合数（监控用）
+     */
+    size() {
+        return this.conversations.size;
+    }
+    /**
+     * 内部：取桶；不存在时创建
+     */
+    getOrCreateBucket(conversationId) {
+        let bucket = this.conversations.get(conversationId);
+        if (!bucket) {
+            bucket = {
+                rootController: new AbortController(),
+                runs: new Map(),
+            };
+            this.conversations.set(conversationId, bucket);
+        }
+        return bucket;
+    }
+}