lightclawbot 1.2.6-beta.0 → 1.2.7

package/dist/src/group/orchestrator/planning/summarizer-runner.js

@@ -0,0 +1,224 @@
+/**
+ * SummarizerRunner —— 场景 C 拆活路径的"汇总阶段"
+ *
+ * 职责：
+ *  1. 在所有 child 完成（含 done / failed / aborted）后，
+ *     用 Leader Agent 自身再跑一次 run（role=summarizer），不挂派活工具；
+ *  2. 通过 PromptBuilder.buildSummarizer 产出汇总指令；
+ *  3. 流式输出到独立的 SocketStreamSink（runId 与 leaderRunId 不同，
+ *     parentRunId=leaderRunId，前端按此聚合为汇总气泡）；
+ *  4. 写 assistant 账本（parentRunId=leaderRunId），便于后续历史回放。
+ *
+ * 失败 / 中止：
+ *  - aborted → 部分内容仍持久化，由上层路由统一写 user_aborted 事件；
+ *  - error/timeout → 写 system run_failed；
+ *  - 路由层据此决定 finalStatus = ABORTED / FAILED。
+ *
+ * 设计要点：
+ *  - 不转移状态机：SUMMARIZING / DONE 由调用方负责；
+ *  - 子任务全部失败时仍然跑汇总，由 prompt 决定如何"诚实告知失败"。
+ */
+import { createStreamReplyConfig } from '../../../streaming/stream-reply-sink.js';
+import { generatePreRunId } from '../../utils/id-generator.js';
+import { errorToString, normalizeRunStatus } from '../../utils/run-helpers.js';
+import { getModuleLogger } from '../../../utils/logger.js';
+import { generateMsgId } from '../../../dedup.js';
+/**
+ * 汇总阶段禁用的工具列表
+ *
+ * 防止 LLM 在汇总时再次尝试派活或调用 session 相关工具
+ */
+const SUMMARIZER_DENY_TOOLS = [
+    'sessions_spawn', 'sessions_send', 'sessions_list',
+    'sessions_history', 'sessions_yield', 'session_status',
+    'sessions.spawn', 'subagents', 'agents_list',
+];
+/**
+ * SummarizerRunner —— 汇总阶段执行器（无状态）
+ *
+ * 负责拉起 Leader Agent 的汇总 run，将子任务结果综合为最终回答。
+ */
+export class SummarizerRunner {
+    deps;
+    log = getModuleLogger('group.summarizer');
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** 执行一次汇总 run */
+    async run(input) {
+        const { ctx, leaderAgentId, leaderRunId, originalMsgId, subtaskResults } = input;
+        const { runRegistry } = this.deps;
+        const tag = `[Summarizer conv=${ctx.conversationId} agent=${leaderAgentId}]`;
+        // 注册 run（获取 abort 信号）
+        const summarizerRunId = generatePreRunId(ctx.conversationId, 'summarizer');
+        const abortSignal = runRegistry.registerRun(ctx.conversationId, summarizerRunId, leaderAgentId);
+        try {
+            // 准备流式输出 sink
+            const sinkContext = this.createSinkContext(input, summarizerRunId);
+            sinkContext.emitStart();
+            // 执行 runner
+            const runOutput = await this.executeRun(input, summarizerRunId, abortSignal, sinkContext);
+            // 处理结果并落账本
+            return await this.handleRunOutput(runOutput, input, summarizerRunId, tag);
+        }
+        catch (err) {
+            // runner 抛异常：记录错误并返回 failed
+            return await this.handleRunException(err, input, summarizerRunId, tag);
+        }
+        finally {
+            runRegistry.unregisterRun(ctx.conversationId, summarizerRunId);
+        }
+    }
+    /**
+     * 创建流式输出的 SinkContext
+     *
+     * 汇总气泡独立于 leader 气泡，通过 parentRunId 关联
+     */
+    createSinkContext(input, summarizerRunId) {
+        const { ctx, leaderAgentId, leaderRunId, originalMsgId } = input;
+        const { emitter } = this.deps;
+        const replyMsgId = generateMsgId();
+        const signalCtx = {
+            emitter,
+            targetId: ctx.userId,
+            replyMsgId,
+            originalMsgId,
+            agentId: leaderAgentId,
+        };
+        return createStreamReplyConfig({
+            emitter,
+            targetId: ctx.userId,
+            replyMsgId,
+            originalMsgId,
+            effectiveApiKey: ctx.effectiveApiKey ?? '',
+            agentId: leaderAgentId,
+            groupId: ctx.groupId,
+            runId: summarizerRunId,
+            parentRunId: leaderRunId,
+            conversationId: ctx.conversationId,
+        }, { suppressTyping: true, runId: summarizerRunId }, signalCtx);
+    }
+    /**
+     * 执行 summarizer run
+     *
+     * 构造汇总 prompt 并调用 runner，禁用派活相关工具
+     */
+    async executeRun(input, summarizerRunId, abortSignal, sinkContext) {
+        const { ctx, leaderAgentId, leaderRunId, subtaskResults } = input;
+        const { runner, promptBuilder } = this.deps;
+        const systemPrompt = promptBuilder.buildSummarizer({
+            leaderAgentId,
+            userMessage: ctx.userMessage,
+            subtaskResults,
+        });
+        // 明确告知 LLM 当前是汇总阶段，避免受历史 Planning JSON 影响
+        const summarizerMessage = [
+            '[汇总阶段] 子任务已全部完成，请用自然语言综合回答用户。不要输出JSON。',
+            `用户原始问题：${ctx.userMessage}`,
+        ].join('\n');
+        return runner.run({
+            groupId: ctx.groupId,
+            agentId: leaderAgentId,
+            userId: ctx.userId,
+            role: 'summarizer',
+            parentRunId: leaderRunId,
+            message: summarizerMessage,
+            systemPrompt,
+            abortSignal,
+            sinkContext,
+            preassignedRunId: summarizerRunId,
+            denyTools: [...SUMMARIZER_DENY_TOOLS],
+        });
+    }
+    /**
+     * 处理 runner 正常返回的结果，根据状态落账本
+     */
+    async handleRunOutput(runOutput, input, summarizerRunId, tag) {
+        const { ctx, leaderAgentId, leaderRunId } = input;
+        const realRunId = runOutput.runId || summarizerRunId;
+        const normalized = normalizeRunStatus(runOutput.status);
+        // normalizeRunStatus 实际只返回 done/aborted/failed，但类型签名为 RunStatus，
+        // 此处做 fallback 保证类型安全
+        const status = normalized === 'done' || normalized === 'aborted' || normalized === 'failed'
+            ? normalized
+            : 'failed';
+        const out = {
+            runId: realRunId,
+            agentId: leaderAgentId,
+            status,
+            finalText: runOutput.finalText,
+        };
+        const assistantParams = {
+            groupId: ctx.groupId,
+            agentId: leaderAgentId,
+            content: runOutput.finalText,
+            runId: realRunId,
+            parentRunId: leaderRunId,
+        };
+        switch (status) {
+            case 'done':
+                await this.persistAssistant(assistantParams, tag);
+                this.log.info(`${tag} done bytes=${runOutput.finalText.length}`);
+                break;
+            case 'aborted':
+                out.errorMessage = 'aborted';
+                // 被中止但有部分内容时仍持久化，刷新页面后用户可见中断前内容
+                if (runOutput.finalText) {
+                    await this.persistAssistant(assistantParams, tag, 'aborted partial');
+                    this.log.info(`${tag} aborted，已持久化部分内容 bytes=${runOutput.finalText.length}`);
+                }
+                break;
+            case 'failed':
+                out.errorMessage = errorToString(runOutput.error);
+                await this.persistSystemError(ctx.groupId, leaderAgentId, realRunId, out.errorMessage, tag);
+                this.log.warn(`${tag} failed reason=${out.errorMessage}`);
+                break;
+        }
+        return out;
+    }
+    /**
+     * 处理 runner 抛出异常的情况
+     */
+    async handleRunException(err, input, summarizerRunId, tag) {
+        const { ctx, leaderAgentId } = input;
+        const e = err instanceof Error ? err : new Error(String(err));
+        this.log.error(`${tag} runner 异常: ${e.message}`);
+        await this.persistSystemError(ctx.groupId, leaderAgentId, summarizerRunId, e.message, tag);
+        return {
+            runId: summarizerRunId,
+            agentId: leaderAgentId,
+            status: 'failed',
+            finalText: '',
+            errorMessage: errorToString(e),
+        };
+    }
+    /**
+     * 持久化 assistant 账本条目（带容错）
+     */
+    async persistAssistant(params, tag, label) {
+        try {
+            await this.deps.ledger.appendAssistant(params);
+        }
+        catch (err) {
+            const suffix = label ? `(${label})` : '';
+            this.log.warn(`${tag} appendAssistant${suffix} failed: ${err}`);
+        }
+    }
+    /**
+     * 持久化 run_failed 系统事件（带容错）
+     */
+    async persistSystemError(groupId, agentId, runId, content, tag) {
+        try {
+            await this.deps.ledger.appendSystem({
+                groupId,
+                event: 'run_failed',
+                agentId,
+                runId,
+                content,
+            });
+        }
+        catch (err) {
+            this.log.warn(`${tag} appendSystem failed: ${err}`);
+        }
+    }
+}

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

@@ -0,0 +1,9 @@
+/**
+ * @file routes 子模块出口
+ * @description 统一导出路径层的路由实现和共享类型
+ */
+export { LeaderOrchestrationRoute } from './leader-orchestration-route.js';
+export { MentionConcurrentRoute } from './mention-concurrent-route.js';
+// 工具函数（从统一工具层转发）
+export { generatePreRunId } from '../../utils/id-generator.js';
+export { normalizeRunStatus, errorToString } from '../../utils/run-helpers.js';

package/dist/src/group/orchestrator/routes/leader-dispatch.js

@@ -0,0 +1,229 @@
+/**
+ * @fileoverview Leader 派活路径执行器
+ *
+ * @description
+ * 当 Planning 阶段决策为 dispatch（需要将任务分配给群成员执行）时走此路径。
+ *
+ * 执行流程：
+ *   1. 校验 Plan 合法性（成员存在性、任务数上限等）
+ *   2. 推送过渡话给前端（如「正在为您处理...」）
+ *   3. 子任务 DAG 并行/串行执行
+ *   4. 汇总器收集所有子任务结果，生成最终回复
+ *   5. 根据各阶段结果确定终态
+ *
+ * 与自答路径的区别：
+ * - 派活路径涉及多个 Agent 协作，产生多个 run
+ * - 派活路径有明确的 Plan 结构（tasks DAG）
+ * - 派活路径包含汇总阶段（Summarizer）
+ *
+ * @module leader-dispatch
+ */
+// ─── 工具函数 ────────────────────────────────────────────────────────────────
+import { generatePreRunId } from '../../utils/id-generator.js';
+import { getModuleLogger } from '../../../utils/logger.js';
+import { generateMsgId } from '../../../dedup.js';
+// ─── Planning 模块 ───────────────────────────────────────────────────────────
+import { extractPlanFromDecision, validatePlan } from '../planning/index.js';
+// ─── 路由层公共工具 ──────────────────────────────────────────────────────────
+import { createSinkForAgent, safeAppendAssistant } from './route-helpers.js';
+/** 模块级日志记录器 */
+const log = getModuleLogger('group.leader-route');
+/**
+ * 执行派活路径：校验 Plan → 推送过渡话 → 子任务 DAG → 汇总
+ *
+ * @remarks
+ * 整个流程中状态机转移顺序：
+ *   RUNNING → PLANNING → RUNNING_CHILDREN → SUMMARIZING → DONE/FAILED/ABORTED
+ *
+ * 任何阶段失败都会通过 forceTerminal 直接终结状态机，
+ * 确保不会卡在中间态。
+ *
+ * @param deps - 路由依赖
+ * @param input - 路由运行输入（ctx + state）
+ * @param agentId - Leader Agent ID
+ * @param decision - Planning 阶段产出的派活决策
+ * @param memberCards - 群成员能力卡（当前用于日志，未来可用于动态路由）
+ * @param tag - 日志标签
+ * @param routeName - 路由名称（透传到返回结果中）
+ * @param options - 执行器与降级回调配置
+ */
+export async function executeDispatch(deps, input, agentId, decision, memberCards, tag, routeName, options) {
+    const { ctx, state } = input;
+    const { subtaskExecutor, summarizerRunner, fallbackSelfAnswer } = options;
+    // ── 1. 校验 Plan 合法性 ──
+    // 从决策中提取原始 Plan 结构，并校验成员存在性、任务数上限等约束
+    const rawPlan = extractPlanFromDecision(decision);
+    const validationResult = validatePlan(rawPlan, {
+        leaderAgentId: agentId,
+        members: ctx.meta.members.map((m) => m.agentId),
+        maxTasks: 5, // 单次派活最多 5 个子任务，防止资源耗尽
+    });
+    if (!validationResult.ok) {
+        // Plan 不合法时降级为自答，不中断用户体验
+        log.warn(`${tag} Plan 校验失败: ${validationResult.errors.join('; ')}，降级为自答`);
+        return fallbackSelfAnswer();
+    }
+    const plan = validationResult.plan;
+    const originalMsgId = ctx.msgId ?? generateMsgId();
+    // ── 2. 推送过渡话给前端 ──
+    // 过渡话是 Leader 在子任务执行前给用户的即时反馈（如「正在为您处理...」）
+    const transitionRunId = generatePreRunId(ctx.conversationId, 'transition');
+    if (decision.transition?.trim()) {
+        await emitTransition(deps, ctx, agentId, decision.transition, transitionRunId, originalMsgId, tag);
+    }
+    // Leader 自身的 run 摘要（过渡话视为 Leader 的一次 run）
+    const leaderSummary = {
+        runId: transitionRunId,
+        agentId,
+        status: 'done',
+        finalText: decision.transition || '',
+    };
+    // ── 3. 子任务 DAG 执行 ──
+    log.info(`${tag} 进入子任务流程，共 ${plan.tasks.length} 个任务`);
+    state.transitionTo('PLANNING');
+    state.transitionTo('RUNNING_CHILDREN');
+    let subtaskResults;
+    try {
+        subtaskResults = await subtaskExecutor.run({
+            ctx,
+            plan,
+            leaderAgentId: agentId,
+            leaderRunId: transitionRunId,
+            originalMsgId,
+        });
+    }
+    catch (err) {
+        // 子任务执行器整体崩溃（非单个子任务失败），直接终结
+        const e = err instanceof Error ? err : new Error(String(err));
+        log.error(`${tag} 子任务执行器崩溃: ${e.message}`);
+        state.forceTerminal('FAILED');
+        return { route: routeName, finalStatus: 'FAILED', runs: [leaderSummary], error: e };
+    }
+    // 将子任务结果映射为统一的 RouteRunSummary 格式
+    const childSummaries = mapSubtaskResults(subtaskResults);
+    // ── 4. 汇总阶段 ──
+    state.transitionTo('SUMMARIZING');
+    let summarizerSummary;
+    try {
+        const summarizerOut = await summarizerRunner.run({
+            ctx,
+            leaderAgentId: agentId,
+            leaderRunId: transitionRunId,
+            originalMsgId,
+            subtaskResults,
+        });
+        summarizerSummary = {
+            runId: summarizerOut.runId,
+            agentId: summarizerOut.agentId,
+            status: summarizerOut.status,
+            finalText: summarizerOut.finalText,
+            errorMessage: summarizerOut.errorMessage,
+        };
+    }
+    catch (err) {
+        // 汇总器崩溃兜底：子任务已完成但无法汇总，标记为失败
+        const e = err instanceof Error ? err : new Error(String(err));
+        log.error(`${tag} 汇总器执行异常: ${e.message}`);
+        state.forceTerminal('FAILED');
+        return {
+            route: routeName,
+            finalStatus: 'FAILED',
+            runs: [leaderSummary, ...childSummaries],
+            error: e,
+        };
+    }
+    // ── 5. 终态决策 ──
+    const allRuns = [leaderSummary, ...childSummaries, summarizerSummary];
+    const finalStatus = determineFinalStatus(allRuns, summarizerSummary.status, state);
+    // ── 6. ABORTED 时写入 user_aborted 系统事件 ──
+    // 在所有 run 结束（部分内容已 appendAssistant）之后再写，
+    // 保证前端按 ts 排序后终止提示在 agent 部分回复内容之后。
+    if (finalStatus === 'ABORTED') {
+        try {
+            await deps.ledger.appendSystem({
+                groupId: ctx.groupId,
+                event: 'user_aborted',
+                userId: ctx.userId,
+            });
+        }
+        catch (err) {
+            log.warn(`${tag} appendSystem(user_aborted) 失败: ${err}`);
+        }
+    }
+    log.info(`${tag} 派活流程完成 状态=${finalStatus} ` +
+        `子任务数=${childSummaries.length} ` +
+        `成功数=${childSummaries.filter((r) => r.status === 'done').length} ` +
+        `汇总器=${summarizerSummary.status}`);
+    return {
+        route: routeName,
+        finalStatus,
+        runs: allRuns,
+        error: finalStatus === 'FAILED' ? new Error(summarizerSummary.errorMessage ?? 'summarizer failed') : undefined,
+    };
+}
+// ─── 私有辅助函数 ────────────────────────────────────────────────────────────
+/**
+ * 将子任务结果数组映射为统一的 RouteRunSummary 格式
+ *
+ * @remarks
+ * SubtaskResult 使用 `output` 字段存储文本，而 RouteRunSummary 使用 `finalText`，
+ * 此函数负责字段名适配。
+ */
+function mapSubtaskResults(results) {
+    return results.map((r) => ({
+        runId: r.runId,
+        agentId: r.agentId,
+        status: r.status,
+        finalText: r.output,
+        errorMessage: r.errorMessage,
+    }));
+}
+/**
+ * 推送过渡话并写入账本
+ *
+ * @remarks
+ * 过渡话是 Leader 在子任务执行前给用户的即时反馈，
+ * 通过 SocketStreamSink 的 onFinal 直接推送完整文本（非流式），
+ * 同时持久化到群账本供历史消息回放。
+ */
+async function emitTransition(deps, ctx, agentId, text, runId, originalMsgId, tag) {
+    const sinkContext = createSinkForAgent(deps, ctx, agentId, runId, originalMsgId);
+    sinkContext.emitStart();
+    try {
+        // 过渡话不走流式，直接通过 dispatcher 推送完整文本并触发终态帧
+        sinkContext.dispatcher.sendFinalReply({ text });
+        sinkContext.dispatcher.markComplete();
+    }
+    catch (err) {
+        log.warn(`${tag} 过渡话推送异常: ${err}`);
+    }
+    await safeAppendAssistant(deps, ctx.groupId, agentId, text, runId, tag);
+}
+/**
+ * 根据所有 run 结果确定最终终态
+ *
+ * @remarks
+ * 终态决策优先级：
+ *   1. 任何 run 被 abort → 整体 ABORTED
+ *   2. 汇总器成功 → 整体 DONE（即使部分子任务失败，汇总器仍可能产出有效回复）
+ *   3. 其他情况 → FAILED
+ *
+ * @param allRuns - 所有 run 的摘要（Leader + 子任务 + 汇总器）
+ * @param summarizerStatus - 汇总器的终态
+ * @param state - 会话状态机
+ */
+function determineFinalStatus(allRuns, summarizerStatus, state) {
+    // 优先检查是否有 abort（用户主动取消）
+    if (allRuns.some((r) => r.status === 'aborted')) {
+        state.forceTerminal('ABORTED');
+        return 'ABORTED';
+    }
+    // 汇总器成功即视为整体成功
+    if (summarizerStatus === 'done') {
+        state.transitionTo('DONE');
+        return 'DONE';
+    }
+    // 兜底：汇总器未成功则整体失败
+    state.forceTerminal('FAILED');
+    return 'FAILED';
+}

package/dist/src/group/orchestrator/routes/leader-orchestration-route.js

@@ -0,0 +1,179 @@
+/**
+ * @fileoverview 路径 C —— Leader 决策编排路由（主入口）
+ *
+ * @description
+ * 实现两阶段决策流程：
+ *  1. Planning 阶段：Leader Agent 以 JSON 模式输出决策（self_answer / dispatch）
+ *  2. Execution 阶段：根据决策走自答或派活（子任务 DAG + 汇总）
+ *
+ * 核心设计：
+ * - Planning 支持重试（JSON 解析失败时自动重试）
+ * - 所有阶段失败均可优雅降级为自答
+ * - 子任务执行后由 Summarizer 汇总最终回复
+ *
+ * @module leader-orchestration-route
+ */
+// ─── 工具函数 ────────────────────────────────────────────────────────────────
+import { generatePreRunId } from '../../utils/id-generator.js';
+import { getModuleLogger } from '../../../utils/logger.js';
+// ─── Planning 模块 ───────────────────────────────────────────────────────────
+import { SubtaskExecutor, SummarizerRunner } from '../planning/index.js';
+// ─── 拆分后的子模块 ──────────────────────────────────────────────────────────
+import { buildTag, resolveMemberCards } from './route-helpers.js';
+import { executePlanning } from './leader-planning.js';
+import { executeSelfAnswer } from './leader-self-answer.js';
+import { executeDispatch } from './leader-dispatch.js';
+/**
+ * 路径 C —— Leader 决策层（提示词驱动方案）
+ *
+ * @remarks
+ * 两阶段决策：Planning（JSON 决策）→ Execution（自答 / 派活+汇总）
+ */
+export class LeaderOrchestrationRoute {
+    deps;
+    /** 路由名称标识，用于日志和结果追踪 */
+    name = 'leader_orchestration';
+    /** 子任务 DAG 执行器，负责并行/串行调度多个子 Agent */
+    subtaskExecutor;
+    /** 汇总阶段执行器，负责将子任务结果合并为最终回复 */
+    summarizerRunner;
+    /** Planning 阶段 JSON 解析失败时的最大重试次数 */
+    planningMaxRetries;
+    /** 日志记录器，命名空间 'group.leader-route' */
+    log = getModuleLogger('group.leader-route');
+    /**
+     * 构造 LeaderOrchestrationRoute 实例
+     *
+     * @param deps - 路由公共依赖（runner、emitter、ledger 等）
+     * @param options - 可选配置项，支持注入自定义执行器和重试策略
+     */
+    constructor(deps, options = {}) {
+        this.deps = deps;
+        this.subtaskExecutor = options.subtaskExecutor ?? new SubtaskExecutor(deps);
+        this.summarizerRunner = options.summarizerRunner ?? new SummarizerRunner(deps);
+        this.planningMaxRetries = options.planningMaxRetries ?? 1;
+    }
+    /**
+     * 执行路径 C —— 两阶段决策主流程
+     *
+     * @remarks
+     * 执行流程：
+     *  1. 状态机转移至 RUNNING_LEADER
+     *  2. 解析群成员能力卡（用于 Planning 提示词）
+     *  3. 调用 Planning 阶段获取 JSON 决策
+     *  4. 根据决策分支：self_answer → 自答 / dispatch → 派活+汇总
+     *  5. Planning 失败时优雅降级为自答
+     *
+     * @param input - 路由运行输入，包含上下文（ctx）和状态机（state）
+     * @returns 路由执行结果，包含终态、所有 run 摘要及可能的错误
+     */
+    async run(input) {
+        const { ctx, state } = input;
+        const tag = buildTag(ctx);
+        const agentId = ctx.meta.defaultAgentId;
+        // ── 1. 状态转移 ──
+        if (state.getStatus() === 'PENDING') {
+            state.transitionTo('ROUTING');
+        }
+        state.transitionTo('RUNNING_LEADER');
+        // ── 2. 解析群成员能力卡 ──
+        const memberCards = resolveMemberCards(this.deps, ctx, tag);
+        // ── 2.5 欢迎消息模式：跳过 Planning，直接走自答路径 ──
+        if (ctx.welcomeMode) {
+            this.log.info(`${tag} 欢迎消息模式，跳过 Planning 直接自答`);
+            return await this.doWelcomeAnswer(input, agentId, memberCards, tag);
+        }
+        // ── 3. Planning 阶段 ──
+        const planningResult = await executePlanning(this.deps, ctx, agentId, memberCards, tag, this.planningMaxRetries);
+        // ── 4. 处理 Planning 结果 ──
+        if (planningResult.aborted) {
+            const planningRunId = generatePreRunId(ctx.conversationId, 'planning');
+            state.forceTerminal('ABORTED');
+            // Planning 阶段被中止：写入 user_aborted 系统事件
+            try {
+                await this.deps.ledger.appendSystem({
+                    groupId: ctx.groupId,
+                    event: 'user_aborted',
+                    userId: ctx.userId,
+                });
+            }
+            catch (err) {
+                this.log.warn(`${tag} appendSystem(user_aborted) 失败: ${err}`);
+            }
+            return {
+                route: this.name,
+                finalStatus: 'ABORTED',
+                runs: [{ runId: planningRunId, agentId, status: 'aborted' }],
+            };
+        }
+        if (!planningResult.decision) {
+            this.log.warn(`${tag} Planning 失败，降级为自答: ${planningResult.lastError}`);
+            // 短暂等待 SDK 内部 session 写锁释放，避免 "Previous run is still shutting down" 冲突
+            await new Promise((r) => setTimeout(r, 200));
+            return await this.doSelfAnswer(input, agentId, memberCards, tag);
+        }
+        const decision = planningResult.decision;
+        // ── 5. 分支执行 ──
+        if (decision.action === 'self_answer') {
+            this.log.info(`${tag} 决策=自答`);
+            // 短暂等待 SDK 内部 session 写锁释放
+            await new Promise((r) => setTimeout(r, 200));
+            return await this.doSelfAnswer(input, agentId, memberCards, tag);
+        }
+        const dispatchDecision = decision;
+        return await this.doDispatch(input, agentId, dispatchDecision, memberCards, tag);
+    }
+    /**
+     * 委托自答路径
+     *
+     * @remarks
+     * 将执行委托给 {@link executeSelfAnswer}，Leader 直接流式回答用户。
+     * 用于 Planning 决策为 self_answer 或 Planning 失败降级的场景。
+     *
+     * @param input - 路由运行输入
+     * @param agentId - Leader Agent ID
+     * @param memberCards - 群成员能力卡（用于构建系统提示词）
+     * @param tag - 日志标签（含 conversationId、groupId）
+     */
+    doSelfAnswer(input, agentId, memberCards, tag) {
+        return executeSelfAnswer(this.deps, input, agentId, memberCards, tag, this.name);
+    }
+    /**
+     * 委托派活路径
+     *
+     * @remarks
+     * 将执行委托给 {@link executeDispatch}，流程为：
+     * 校验 Plan → 推送过渡话 → 子任务 DAG 执行 → Summarizer 汇总。
+     * 若 Plan 校验失败，内部会通过 fallbackSelfAnswer 降级为自答。
+     *
+     * @param input - 路由运行输入
+     * @param agentId - Leader Agent ID
+     * @param decision - Planning 阶段输出的派活决策（含 tasks 列表）
+     * @param memberCards - 群成员能力卡
+     * @param tag - 日志标签
+     */
+    doDispatch(input, agentId, decision, memberCards, tag) {
+        return executeDispatch(this.deps, input, agentId, decision, memberCards, tag, this.name, {
+            subtaskExecutor: this.subtaskExecutor,
+            summarizerRunner: this.summarizerRunner,
+            fallbackSelfAnswer: () => this.doSelfAnswer(input, agentId, memberCards, tag),
+        });
+    }
+    /**
+     * 欢迎消息自答路径
+     *
+     * @remarks
+     * 创建群后触发，使用 buildWelcome prompt 让主Agent生成欢迎消息。
+     * 与普通自答路径的区别：使用专门的欢迎消息 prompt 而非通用 Leader prompt。
+     *
+     * @param input - 路由运行输入
+     * @param agentId - Leader Agent ID
+     * @param memberCards - 群成员能力卡
+     * @param tag - 日志标签
+     */
+    doWelcomeAnswer(input, agentId, memberCards, tag) {
+        return executeSelfAnswer(this.deps, input, agentId, memberCards, tag, this.name, {
+            welcomeMode: true,
+        });
+    }
+}