lightclawbot 1.2.6-beta.0 → 1.2.7

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

@@ -0,0 +1,265 @@
+/**
+ * @file 群聊调度器（Orchestrator）
+ * @description
+ * 群聊消息处理的总入口，负责：
+ *   1. 根据用户消息中的 mentions 信息选择执行路径（Leader 决策 / Mention 并发）
+ *   2. 装配并注入各子模块依赖（AgentRunner、SoulResolver、PromptBuilder 等）
+ *   3. 管理会话生命周期（注册、abort、清理）
+ *   4. 发布调度过程中的关键事件（用于 metrics / 日志追踪）
+ *
+ * 设计原则：
+ *   - 不写账本：账本写入由上游 inbound 层完成
+ *   - 不解析 mentions：mentions 规范化由 inbound 层完成
+ *   - 不直接调用 SDK：Agent 执行委托给 AgentRunner
+ *   - 单例模式：每个 gateway / account 维护一份 Orchestrator 实例
+ */
+import { ConversationStateMachine } from './lifecycle/conversation-state.js';
+import { RunRegistry } from './lifecycle/run-registry.js';
+import { LedgerWriter } from './lifecycle/ledger-writer.js';
+import { AgentRunner } from './execution/agent-runner.js';
+import { SoulResolver } from './execution/soul-resolver.js';
+import { PromptBuilder } from './execution/prompt-builder.js';
+import { LeaderOrchestrationRoute } from './routes/leader-orchestration-route.js';
+import { MentionConcurrentRoute } from './routes/mention-concurrent-route.js';
+import { CHANNEL_KEY } from '../../config.js';
+import { getModuleLogger } from '../../utils/logger.js';
+/**
+ * 群聊调度器主体
+ *
+ * @remarks
+ * 每个 gateway / account 维护一份实例。
+ * 职责边界：路径选择 + 子模块装配 + 生命周期管理 + 事件发布。
+ * 具体的 Agent 执行逻辑委托给 Route 实现。
+ *
+ * 路径策略：
+ *   - mentions 非空 → MentionConcurrentRoute（并发调用被 @ 的 Agent）
+ *   - mentions 为空 → LeaderOrchestrationRoute（默认 Agent 自决直答或拆活派发）
+ */
+export class Orchestrator {
+    /** Run 注册表：管理所有活跃会话的 AbortController，支持级联 abort */
+    runRegistry;
+    /** 群账本写入器：负责将 Agent 回复写入持久化账本 */
+    ledger;
+    /** 路径共享依赖集合：所有 Route 实例共享的基础设施引用 */
+    routeDeps;
+    /** Leader 决策路径：默认 Agent 自决直答或拆活派发给其他成员 */
+    leaderRoute;
+    /** Mention 并发路径：用户 @ 了特定成员时，并发调用被 @ 的 Agent */
+    mentionRoute;
+    /** 模块日志器 */
+    log;
+    /** 事件订阅回调（可选） */
+    onEvent;
+    /**
+     * 构造 Orchestrator 实例
+     *
+     * @param options - 构造参数，包含 accountId、storage、emitter 等依赖
+     *
+     * @remarks
+     * 构造过程中会初始化以下子模块：
+     *   - RunRegistry：会话级 abort 管理
+     *   - LedgerWriter：账本写入
+     *   - AgentRunner：Agent 执行器（内部通过 getLightclawRuntime() 获取 runtime）
+     *   - SoulResolver：成员身份/能力卡解析
+     *   - PromptBuilder：系统提示词构建
+     *   - LeaderOrchestrationRoute / MentionConcurrentRoute：两条执行路径
+     */
+    constructor(options) {
+        const { accountId, storage, emitter, onEvent } = options;
+        this.log = getModuleLogger('group.orchestrator');
+        this.onEvent = onEvent;
+        // ── 基础设施层 ──
+        this.runRegistry = new RunRegistry();
+        // 群账本写入器：负责将 Agent 回复写入持久化账本
+        this.ledger = new LedgerWriter(storage);
+        // ── 执行层 ──
+        // AgentRunner 内部通过 getLightclawRuntime() 获取 PluginRuntime，无需外部传入
+        const runner = new AgentRunner({ accountId });
+        // SoulResolver：根据 agentId 解析成员的能力描述（soul card）
+        const soulResolver = new SoulResolver();
+        // PromptBuilder：基于群元数据和成员能力卡构建系统提示词
+        const promptBuilder = new PromptBuilder();
+        // ── 路径共享 deps：所有 Route 实例共享的依赖集合 ──
+        this.routeDeps = {
+            runner,
+            soulResolver,
+            promptBuilder,
+            runRegistry: this.runRegistry,
+            ledger: this.ledger,
+            emitter,
+        };
+        // Leader 决策路径：默认 Agent 自决直答或拆活派发给其他成员
+        this.leaderRoute = new LeaderOrchestrationRoute(this.routeDeps);
+        // Mention 并发路径：用户 @ 了特定成员时，调用被 @ 的 Agent
+        this.mentionRoute = new MentionConcurrentRoute(this.routeDeps);
+    }
+    /**
+     * 调度入口：处理一次完整的群聊回合
+     *
+     * @param ctx - 调度上下文，包含 conversationId、groupId、用户消息、mentions 等
+     * @returns 路径执行结果，包含最终状态、各 run 信息和可能的错误
+     *
+     * @remarks
+     * 执行流程：
+     *   1. 创建会话状态机，在 RunRegistry 中注册会话
+     *   2. 发布 conversation_started 事件
+     *   3. 根据 mentions 选择路径（Leader / Mention）
+     *   4. 执行选中的路径，获取结果
+     *   5. 异常兜底：路径执行失败时标记 FAILED 状态
+     *   6. 收尾：从 RunRegistry 中清理会话，发布终态事件
+     */
+    async dispatch(ctx) {
+        const tag = `[${CHANNEL_KEY}][conv=${ctx.conversationId}][group=${ctx.groupId}]`;
+        // 创建会话状态机（跟踪 IDLE → RUNNING → DONE/FAILED/ABORTED 状态流转）
+        const state = new ConversationStateMachine(ctx.conversationId);
+        // 在注册表中确保会话存在（幂等操作，返回 AbortSignal）
+        this.runRegistry.ensureConversation(ctx.conversationId);
+        this.emitEvent({
+            type: 'conversation_started',
+            conversationId: ctx.conversationId,
+            ts: Date.now(),
+        });
+        // ── 路径选择：根据 mentions 决定走哪条路径 ──
+        const route = this.selectRoute(ctx);
+        this.emitEvent({
+            type: 'route_decided',
+            conversationId: ctx.conversationId,
+            ts: Date.now(),
+            payload: { route, mentions: ctx.mentions },
+        });
+        this.log.info(`${tag} route=${route} mentions=[${ctx.mentions.join(',')}]`);
+        // ── 推送 thinking_started 帧：通知前端 Agent 已进入思考阶段 ──
+        // 前端收到后可精确展示"哪个 Agent 在思考"，替代纯前端的猜测逻辑
+        this.emitThinkingStarted(ctx, route);
+        let result;
+        try {
+            switch (route) {
+                case 'leader_orchestration':
+                    // Leader 路径：默认 Agent 先规划，再决定直答或派活
+                    result = await this.leaderRoute.run({ ctx, state });
+                    break;
+                case 'mention_concurrent':
+                    // Mention 路径：并发调用所有被 @ 的 Agent
+                    result = await this.mentionRoute.run({ ctx, state });
+                    break;
+            }
+        }
+        catch (err) {
+            // 兜底：路径内部未捕获的异常统一标记为 FAILED
+            const e = err instanceof Error ? err : new Error(String(err));
+            this.log.error(`${tag} 路径执行失败: ${e.message}`);
+            state.forceTerminal('FAILED');
+            result = { route, finalStatus: 'FAILED', runs: [], error: e };
+        }
+        // 清理已完成的会话，释放资源
+        this.runRegistry.disposeConversation(ctx.conversationId);
+        // 发布 conversation_finished / conversation_aborted / conversation_failed 事件
+        this.emitFinishEvent(ctx, result);
+        return result;
+    }
+    /**
+     * 级联中止指定会话的所有 Agent run
+     *
+     * @param conversationId - 要中止的会话 ID
+     * @returns 实际被中止的 runId 列表
+     */
+    abort(conversationId) {
+        return this.runRegistry.abortConversation(conversationId);
+    }
+    /**
+     * 路径选择策略
+     *
+     * @param ctx - 调度上下文
+     * @returns 选中的路径标识
+     *
+     * @remarks
+     * 当前策略：
+     *   - mentions 非空 → mention_concurrent（用户明确指定了目标 Agent）
+     *   - mentions 为空 → leader_orchestration（由默认 Agent 自主决策）
+     */
+    selectRoute(ctx) {
+        return ctx.mentions.length > 0 ? 'mention_concurrent' : 'leader_orchestration';
+    }
+    /**
+     * 安全发布事件
+     *
+     * @param event - 要发布的调度事件
+     *
+     * @remarks
+     * 监听器异常会被捕获并记录警告日志，不会影响主调度流程。
+     */
+    emitEvent(event) {
+        if (!this.onEvent)
+            return;
+        try {
+            this.onEvent(event);
+        }
+        catch (err) {
+            this.log.warn?.(`[${CHANNEL_KEY}][Orchestrator] 事件监听器异常: ${err}`);
+        }
+    }
+    /**
+     * 向前端推送 thinking_started 帧
+     *
+     * @remarks
+     * 在路径选择完成后、实际 Agent 执行前推送，通知前端进入"思考中"阶段。
+     * 前端收到后可精确展示对应 Agent 的思考动画，替代纯前端的猜测逻辑。
+     *
+     * 帧格式遵循 message:private 协议，streamStatus='thinking'，
+     * 前端 useGroupChat 中识别此状态后更新 thinking 状态和 agentId。
+     *
+     * @param ctx - 调度上下文
+     * @param route - 选中的路径标识
+     */
+    emitThinkingStarted(ctx, route) {
+        try {
+            // 确定思考中的 agentId：
+            // - leader_orchestration 路径：使用 defaultAgentId
+            // - mention_concurrent 路径：使用第一个被 @ 的 agentId
+            const agentId = route === 'leader_orchestration' ? ctx.meta.defaultAgentId : ctx.mentions[0] || ctx.meta.defaultAgentId;
+            this.routeDeps.emitter.emit({
+                msgId: `thinking:${ctx.conversationId}`,
+                from: this.routeDeps.emitter.botClientId,
+                to: ctx.userId,
+                content: '',
+                timestamp: Date.now(),
+                chatKind: 'group',
+                extra: {
+                    groupId: ctx.groupId,
+                    agentId,
+                    conversationId: ctx.conversationId,
+                    streamStatus: 'thinking',
+                },
+            });
+        }
+        catch (err) {
+            // thinking 帧推送失败不影响主流程，仅记录警告
+            this.log.warn?.(`[${CHANNEL_KEY}][Orchestrator] thinking_started 推送失败: ${err}`);
+        }
+    }
+    /**
+     * 根据路径执行结果发布终态事件
+     *
+     * @param ctx - 调度上下文
+     * @param result - 路径执行结果
+     *
+     * @remarks
+     * 终态映射：
+     *   - DONE → conversation_finished
+     *   - ABORTED → conversation_aborted
+     *   - 其他 → conversation_failed
+     */
+    emitFinishEvent(ctx, result) {
+        const type = result.finalStatus === 'DONE'
+            ? 'conversation_finished'
+            : result.finalStatus === 'ABORTED'
+                ? 'conversation_aborted'
+                : 'conversation_failed';
+        this.emitEvent({
+            type,
+            conversationId: ctx.conversationId,
+            ts: Date.now(),
+            payload: { route: result.route, runCount: result.runs.length, error: result.error?.message },
+        });
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * planning 模块统一出口
+ *
+ * 主 Agent 拆活相关：
+ *  - PlanValidator（plan 合法性校验）
+ *  - SubtaskExecutor（子任务 DAG 执行）
+ *  - SummarizerRunner（汇总阶段执行）
+ *  - PlanningParser（Planning 决策解析）
+ */
+export { validatePlan, } from './plan-validator.js';
+export { SubtaskExecutor, } from './subtask-executor.js';
+export { SummarizerRunner, } from './summarizer-runner.js';
+export { parsePlanningDecision, extractPlanFromDecision, } from './planning-parser.js';

package/dist/src/group/orchestrator/planning/plan-validator.js

@@ -0,0 +1,233 @@
+/**
+ * LightClaw — Plan 校验器
+ *
+ * 对主 Agent 产出的拆分计划做硬约束校验：
+ *  1. 总数 1 ≤ N ≤ maxTasks；
+ *  2. 每个 task 的 id 非空且唯一；
+ *  3. to 必须 ∈ 群成员且不能是主 Agent 自己；
+ *  4. dependsOn 引用合法且无环；
+ *  5. task 描述非空。
+ *
+ * 校验通过返回标准化后的 plan，失败返回错误列表。
+ */
+/**
+ * 校验并标准化 Plan
+ *
+ * @param raw - 原始 plan 数据
+ * @param vctx - 校验上下文
+ */
+export function validatePlan(raw, vctx) {
+    const maxTasks = vctx.maxTasks ?? 5;
+    // ── 顶层结构校验 ──
+    const structErr = validateStructure(raw, maxTasks);
+    if (structErr) {
+        return { ok: false, errors: [structErr] };
+    }
+    const tasksRaw = raw.tasks;
+    const memberSet = new Set(vctx.members);
+    const idSet = new Set();
+    const errors = [];
+    const normalized = [];
+    // ── 逐项字段校验 + 标准化 ──
+    for (let i = 0; i < tasksRaw.length; i++) {
+        const result = validateTaskItem(tasksRaw[i], i, memberSet, idSet, vctx.leaderAgentId);
+        errors.push(...result.errors);
+        if (result.item) {
+            normalized.push(result.item);
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    // ── dependsOn 引用合法性 ──
+    for (const item of normalized) {
+        if (!item.dependsOn)
+            continue;
+        for (const dep of item.dependsOn) {
+            if (dep === item.id) {
+                errors.push(`任务 "${item.id}" 不能依赖自身`);
+            }
+            else if (!idSet.has(dep)) {
+                errors.push(`任务 "${item.id}" 依赖了不存在的 id "${dep}"`);
+            }
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    // ── 循环依赖检测 ──
+    const cycle = detectCycle(normalized);
+    if (cycle) {
+        return {
+            ok: false,
+            errors: [`计划中存在循环依赖: ${cycle.join(' -> ')}`],
+        };
+    }
+    return { ok: true, plan: { tasks: normalized } };
+}
+/**
+ * 顶层结构校验，返回错误信息或 null
+ */
+function validateStructure(raw, maxTasks) {
+    if (!raw || typeof raw !== 'object') {
+        return 'plan 必须是一个对象';
+    }
+    const tasksRaw = raw.tasks;
+    if (!Array.isArray(tasksRaw)) {
+        return 'plan.tasks 必须是一个数组';
+    }
+    if (tasksRaw.length === 0) {
+        return 'plan.tasks 不能为空';
+    }
+    if (tasksRaw.length > maxTasks) {
+        return `plan.tasks 长度 ${tasksRaw.length} 超过最大限制 ${maxTasks}`;
+    }
+    return null;
+}
+/**
+ * 校验并标准化单个 task 项
+ */
+function validateTaskItem(t, index, memberSet, idSet, leaderAgentId) {
+    const prefix = `tasks[${index}]`;
+    const errors = [];
+    if (!t || typeof t !== 'object') {
+        return { errors: [`${prefix} 不是一个对象`], item: null };
+    }
+    const item = t;
+    // id
+    const id = typeof item.id === 'string' ? item.id.trim() : '';
+    if (!id) {
+        errors.push(`${prefix}.id 必须是非空字符串`);
+    }
+    else if (idSet.has(id)) {
+        errors.push(`${prefix}.id 重复: "${id}"`);
+    }
+    else {
+        idSet.add(id);
+    }
+    // to
+    const to = typeof item.to === 'string' ? item.to.trim() : '';
+    if (!to) {
+        errors.push(`${prefix}.to 必须是非空字符串`);
+    }
+    else if (!memberSet.has(to)) {
+        errors.push(`${prefix}.to "${to}" 不是群成员`);
+    }
+    else if (to === leaderAgentId) {
+        errors.push(`${prefix}.to "${to}" 是主 Agent 自身（禁止派给自己）`);
+    }
+    // task
+    const task = typeof item.task === 'string' ? item.task.trim() : '';
+    if (!task) {
+        errors.push(`${prefix}.task 必须是非空字符串`);
+    }
+    // dependsOn
+    let dependsOn;
+    if (item.dependsOn != null) {
+        if (!Array.isArray(item.dependsOn)) {
+            errors.push(`${prefix}.dependsOn 必须是字符串数组`);
+        }
+        else {
+            dependsOn = [];
+            for (let j = 0; j < item.dependsOn.length; j++) {
+                const d = item.dependsOn[j];
+                if (typeof d !== 'string' || !d.trim()) {
+                    errors.push(`${prefix}.dependsOn[${j}] 必须是非空字符串`);
+                }
+                else {
+                    dependsOn.push(d.trim());
+                }
+            }
+        }
+    }
+    return { errors, item: { id, to, task, dependsOn } };
+}
+/**
+ * 循环依赖检测（Kahn 拓扑排序）
+ *
+ * @returns 若存在环则返回环路径，否则 undefined
+ */
+function detectCycle(tasks) {
+    const indeg = new Map();
+    const graph = new Map();
+    for (const t of tasks) {
+        indeg.set(t.id, 0);
+        graph.set(t.id, []);
+    }
+    for (const t of tasks) {
+        for (const dep of t.dependsOn ?? []) {
+            graph.get(dep).push(t.id);
+            indeg.set(t.id, (indeg.get(t.id) ?? 0) + 1);
+        }
+    }
+    // Kahn（使用索引模拟队列，避免 shift() 的 O(n) 开销）
+    const queue = [];
+    for (const [id, deg] of indeg) {
+        if (deg === 0)
+            queue.push(id);
+    }
+    let head = 0;
+    let visited = 0;
+    while (head < queue.length) {
+        const cur = queue[head++];
+        visited += 1;
+        for (const next of graph.get(cur)) {
+            const d = indeg.get(next) - 1;
+            indeg.set(next, d);
+            if (d === 0)
+                queue.push(next);
+        }
+    }
+    if (visited === tasks.length)
+        return undefined;
+    // 收集环中节点，DFS 还原路径
+    const inCycle = new Set();
+    for (const [id, d] of indeg) {
+        if (d > 0)
+            inCycle.add(id);
+    }
+    return reconstructCycle(graph, inCycle);
+}
+/**
+ * 在环子图上 DFS 还原一条可视化环路径
+ */
+function reconstructCycle(graph, inCycle) {
+    const start = inCycle.values().next().value;
+    const stack = [start];
+    const onStack = new Set([start]);
+    // 记录每个节点已探索到的邻居索引，避免重复访问导致死循环
+    const edgeIdx = new Map();
+    edgeIdx.set(start, 0);
+    while (stack.length > 0) {
+        const top = stack[stack.length - 1];
+        const neighbors = graph.get(top) ?? [];
+        let idx = edgeIdx.get(top) ?? 0;
+        let found = false;
+        // 从上次探索位置继续寻找环内邻居
+        while (idx < neighbors.length) {
+            const next = neighbors[idx];
+            idx++;
+            if (!inCycle.has(next))
+                continue;
+            edgeIdx.set(top, idx);
+            if (onStack.has(next)) {
+                // 找到环
+                const cycleStart = stack.indexOf(next);
+                return [...stack.slice(cycleStart), next];
+            }
+            stack.push(next);
+            onStack.add(next);
+            edgeIdx.set(next, 0);
+            found = true;
+            break;
+        }
+        if (!found) {
+            // 当前节点所有邻居已探索完毕，回溯
+            edgeIdx.set(top, idx);
+            stack.pop();
+            onStack.delete(top);
+        }
+    }
+    // 兜底：理论不可达
+    return [...inCycle];
+}