lightclawbot 1.2.6-beta.0 → 1.2.7

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

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Leader Planning 阶段执行器
+ *
+ * @description
+ * 负责 Planning 阶段：以 JSON 模式调用 Leader Agent 输出决策，
+ * 支持重试（JSON 解析失败时自动重试）。
+ *
+ * @module leader-planning
+ */
+import { generatePreRunId } from '../../utils/id-generator.js';
+import { getModuleLogger } from '../../../utils/logger.js';
+import { parsePlanningDecision } from '../planning/index.js';
+import { DENY_TOOLS } from './route-helpers.js';
+const log = getModuleLogger('group.leader-route');
+/**
+ * 执行 Planning 阶段：强制 JSON 输出决策，支持重试
+ *
+ * @param deps - 路由依赖
+ * @param ctx - 路由上下文
+ * @param agentId - Leader Agent ID
+ * @param memberCards - 群成员能力卡
+ * @param tag - 日志标签
+ * @param maxRetries - 最大重试次数
+ */
+export async function executePlanning(deps, ctx, agentId, memberCards, tag, maxRetries) {
+    const { runner, promptBuilder, runRegistry } = deps;
+    const planningPrompt = promptBuilder.buildPlanner({
+        leaderAgentId: agentId,
+        memberCards,
+        userMessage: ctx.userMessage,
+    });
+    const planningRunId = generatePreRunId(ctx.conversationId, 'planning');
+    const planningAbort = runRegistry.registerRun(ctx.conversationId, planningRunId, agentId);
+    // Planning 不推送给前端，不传 sinkContext，AgentRunner 内部会使用静默 sink
+    // Planning 阶段不传 attachments/媒体文件：
+    // Planning 只需要知道"用户发了文件"这个事实（已在 userMessage 的 attachmentDescription 中体现），
+    // 如果传入图片等媒体文件，AI 会被图片内容"分心"，直接描述图片而忽略 JSON 格式要求。
+    // 真正需要"看到"文件内容的是自答阶段（leader-self-answer）和子任务阶段。
+    let planningOutput;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        if (planningAbort.aborted)
+            break;
+        try {
+            planningOutput = await runner.run({
+                // 使用独立的 sessionKey（加 :planning 后缀），避免 Planning 阶段的 JSON 决策
+                // 输出被写入主 session transcript，污染后续自答/派活阶段的 LLM 上下文
+                groupId: `${ctx.groupId}:planning`,
+                agentId,
+                userId: ctx.userId,
+                role: 'leader',
+                message: ctx.userMessage,
+                systemPrompt: planningPrompt,
+                abortSignal: planningAbort,
+                preassignedRunId: attempt === 0 ? planningRunId : `${planningRunId}:retry${attempt}`,
+                denyTools: DENY_TOOLS,
+                enableAgentToAgent: true,
+                jsonMode: true,
+            });
+            if (planningOutput.status !== 'ok')
+                break;
+            // 尝试解析 JSON 决策
+            const parseResult = parsePlanningDecision(planningOutput.finalText);
+            if (parseResult.ok) {
+                log.info(`${tag} Planning 决策完成: action=${parseResult.decision.action} ` +
+                    `尝试次数=${attempt} 字节数=${planningOutput.finalText.length}`);
+                runRegistry.unregisterRun(ctx.conversationId, planningRunId);
+                return { aborted: false, decision: parseResult.decision };
+            }
+            // JSON 解析失败，记录并决定是否重试
+            lastError = parseResult.error;
+            log.warn(`${tag} Planning JSON 解析失败 (第 ${attempt} 次): ${parseResult.error}`);
+            if (attempt < maxRetries) {
+                planningOutput = undefined;
+            }
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            log.error(`${tag} Planning 执行异常 (第 ${attempt} 次): ${e.message}`);
+            lastError = e.message;
+            if (attempt >= maxRetries) {
+                planningOutput = undefined;
+            }
+        }
+    }
+    runRegistry.unregisterRun(ctx.conversationId, planningRunId);
+    // 判断是否为 abort
+    if (planningOutput?.status === 'aborted' || planningAbort.aborted) {
+        return { aborted: true };
+    }
+    return { aborted: false, lastError };
+}

package/dist/src/group/orchestrator/routes/leader-self-answer.js

@@ -0,0 +1,223 @@
+/**
+ * @fileoverview Leader 自答路径执行器
+ *
+ * @description
+ * 当 Planning 阶段决策为 self_answer（Leader 自身有能力回答）或
+ * Planning 失败需要降级时，走此路径。
+ *
+ * 核心行为：
+ * - 构造流式 SocketStreamSink，实时推送 token 到前端
+ * - 调用 runner.run 让 Leader Agent 直接生成回复
+ * - 根据 run 终态（ok / aborted / failed）写入账本并转移状态机
+ *
+ * 与 dispatch 路径的区别：
+ * - 自答路径不涉及子任务拆分和 DAG 执行
+ * - 自答路径只产生一个 run（Leader 自身）
+ *
+ * @module leader-self-answer
+ */
+// ─── 工具函数 ────────────────────────────────────────────────────────────────
+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';
+// ─── 路由层公共工具 ──────────────────────────────────────────────────────────
+import { DENY_TOOLS, buildLeaderPrompt, createSinkForAgent, safeAppendAssistant, safeAppendSystem, } from './route-helpers.js';
+/** 模块级日志记录器，统一使用 leader-route 命名空间 */
+const log = getModuleLogger('group.leader-route');
+/**
+ * 执行自答路径：正常流式 run，Leader 直接回答用户
+ *
+ * @remarks
+ * 执行流程：
+ *   1. 预分配 runId + 注册 AbortSignal
+ *   2. 构造 SocketStreamSink 并推送首帧
+ *   3. 调用 runner.run 执行 Agent
+ *   4. 根据 run 结果写入账本并转移状态机
+ *
+ * @param deps - 路由依赖
+ * @param input - 路由运行输入（ctx + state）
+ * @param agentId - Leader Agent ID
+ * @param memberCards - 群成员能力卡（用于构造 system prompt）
+ * @param tag - 日志标签
+ * @param routeName - 路由名称（透传到返回结果中）
+ * @param options - 可选配置（如 welcomeMode）
+ */
+export async function executeSelfAnswer(deps, input, agentId, memberCards, tag, routeName, options) {
+    const { ctx, state } = input;
+    const { runner, runRegistry } = deps;
+    // ── 1. 预分配 runId 并注册 AbortSignal ──
+    // preRunId 在 run 开始前生成，确保首帧推送时前端就能拿到稳定的 runId
+    const preRunId = generatePreRunId(ctx.conversationId, 'leader-answer');
+    // 注册到 RunRegistry，支持用户中途 abort 时级联取消
+    const abortSignal = runRegistry.registerRun(ctx.conversationId, preRunId, agentId);
+    // 兜底生成 msgId，确保前端气泡能正确关联到触发消息
+    const originalMsgId = ctx.msgId ?? generateMsgId();
+    // ── 2. 构造流式 sink 并发送首帧 ──
+    // sinkContext 负责将 runner 产出的 token 实时推送到前端 WebSocket
+    // emitStart() 发送首帧，前端据此创建气泡占位
+    const sinkContext = createSinkForAgent(deps, ctx, agentId, preRunId, originalMsgId);
+    sinkContext.emitStart();
+    // ── 3. 执行 Agent run ──
+    // 根据是否为欢迎消息模式，选择不同的 system prompt
+    let extraSystemPrompt;
+    if (options?.welcomeMode) {
+        // 欢迎消息模式：使用专门的 buildWelcome prompt
+        try {
+            extraSystemPrompt = deps.promptBuilder.buildWelcome({
+                leaderAgentId: agentId,
+                groupName: ctx.meta.name || ctx.meta.groupId,
+                groupDesc: ctx.meta.desc || '',
+                memberCards,
+            });
+        }
+        catch (err) {
+            log.warn(`${tag} 构建 Welcome 提示词失败: ${err}，降级为 Leader prompt`);
+            extraSystemPrompt = buildLeaderPrompt(deps, agentId, memberCards, tag);
+        }
+    }
+    else {
+        // 普通自答模式：使用 Leader prompt
+        extraSystemPrompt = buildLeaderPrompt(deps, agentId, memberCards, tag);
+    }
+    try {
+        const runOutput = await runner.run({
+            groupId: ctx.groupId,
+            agentId,
+            userId: ctx.userId,
+            role: 'leader', // 标识为 leader 角色，影响模型选择和 token 限制
+            message: ctx.userMessage,
+            systemPrompt: extraSystemPrompt,
+            abortSignal, // 用户 abort 时自动取消请求
+            sinkContext, // 统一流式输出上下文
+            preassignedRunId: preRunId, // 确保 runId 全程一致
+            denyTools: DENY_TOOLS, // 禁止 Agent 调用会话管理类工具
+            enableAgentToAgent: true, // 允许 Agent 间通信（如引用其他 Agent 的输出）
+            // 传递文件附件，使 AI 能感知用户上传的文件
+            attachments: ctx.files?.filter((f) => f.uri).map((f) => ({
+                name: f.name,
+                mimeType: f.mimeType || 'application/octet-stream',
+                url: f.uri,
+                localPath: f.localPath,
+            })),
+        });
+        // ── 4. 处理 run 结果并写入账本 ──
+        // runner 可能在内部重新分配 runId（如重试场景），优先使用实际 runId
+        const realRunId = runOutput.runId || preRunId;
+        const summary = {
+            runId: realRunId,
+            agentId,
+            status: normalizeRunStatus(runOutput.status),
+        };
+        // 根据 run 终态填充 summary 的可选字段，供上层日志/metrics 使用
+        if (runOutput.status === 'ok') {
+            summary.finalText = runOutput.finalText; // 完整回复文本
+        }
+        else if (runOutput.status === 'aborted') {
+            // 被中止时也保留已输出的部分内容，供 flushLedger 持久化
+            summary.finalText = runOutput.finalText || undefined;
+            summary.errorMessage = 'aborted';
+        }
+        else {
+            summary.errorMessage = errorToString(runOutput.error); // 错误描述
+        }
+        // 确定终态并转移状态机（DONE / ABORTED / FAILED）
+        const finalStatus = resolveTerminalState(runOutput.status, summary, { state, tag });
+        // 将结果持久化到群账本（assistant 消息或 system 事件）
+        await flushLedger(finalStatus, deps, ctx, agentId, realRunId, tag, summary);
+        // 释放 RunRegistry 中的注册，允许同一 conversation 发起新 run
+        runRegistry.unregisterRun(ctx.conversationId, preRunId);
+        return { route: routeName, finalStatus, runs: [summary], error: runOutput.error };
+    }
+    catch (err) {
+        // runner.run 抛出未预期异常（如网络超时、SDK 内部错误）的兜底处理
+        // 此分支确保即使 runner 崩溃，状态机也能正确终结，不会卡在 RUNNING 态
+        const e = err instanceof Error ? err : new Error(String(err));
+        log.error(`${tag} 自答执行异常: ${e.message}`);
+        state.forceTerminal('FAILED');
+        runRegistry.unregisterRun(ctx.conversationId, preRunId);
+        return {
+            route: routeName,
+            finalStatus: 'FAILED',
+            runs: [{ runId: preRunId, agentId, status: 'failed', errorMessage: e.message }],
+            error: e,
+        };
+    }
+}
+// ─── 私有辅助函数 ────────────────────────────────────────────────────────────
+/**
+ * 根据 run 输出状态确定终态并转移状态机
+ *
+ * @remarks
+ * 状态转移规则：
+ * - ok      → transitionTo('DONE')    正常完成
+ * - aborted → forceTerminal('ABORTED') 用户主动取消
+ * - 其他    → forceTerminal('FAILED')  执行失败
+ *
+ * 注意：forceTerminal 与 transitionTo 的区别在于前者跳过中间态校验，
+ * 适用于异常终结场景。
+ *
+ * @param outputStatus - runner 返回的原始状态字符串
+ * @param summary - 当前 run 的摘要对象（可能被修改 errorMessage）
+ * @param opts.state - 会话状态机实例
+ * @param opts.tag - 日志标签
+ * @returns 终态值（DONE / ABORTED / FAILED）
+ */
+function resolveTerminalState(outputStatus, summary, opts) {
+    const { state, tag } = opts;
+    if (outputStatus === 'ok') {
+        state.transitionTo('DONE');
+        log.info(`${tag} 自答完成，字节数=${summary.finalText?.length ?? 0}`);
+        return 'DONE';
+    }
+    if (outputStatus === 'aborted') {
+        // aborted 时 runner 不一定填充 error，手动标记
+        summary.errorMessage = 'aborted';
+        state.forceTerminal('ABORTED');
+        return 'ABORTED';
+    }
+    // 其他状态（如 'error'、'timeout' 等）统一视为失败
+    state.forceTerminal('FAILED');
+    return 'FAILED';
+}
+/**
+ * 根据终态将结果写入对应账本
+ *
+ * @remarks
+ * 账本写入策略：
+ * - DONE    → appendAssistant：记录 Agent 的完整回复内容
+ * - ABORTED → appendSystem('user_aborted')：记录用户取消事件
+ * - FAILED  → appendSystem('run_failed')：记录失败事件及错误信息
+ *
+ * 所有写入操作通过 safe* 包装，失败时仅 warn 不抛异常，
+ * 确保账本写入失败不影响主流程返回。
+ *
+ * @param finalStatus - 已确定的终态
+ * @param deps - 路由依赖（使用 ledger）
+ * @param ctx - 调度上下文
+ * @param agentId - 发言 Agent ID
+ * @param runId - 关联的 runId
+ * @param tag - 日志标签
+ * @param summary - run 摘要（提供 finalText / errorMessage）
+ */
+async function flushLedger(finalStatus, deps, ctx, agentId, runId, tag, summary) {
+    switch (finalStatus) {
+        case 'DONE':
+            // 将 Agent 完整回复持久化，供历史消息回放使用
+            await safeAppendAssistant(deps, ctx.groupId, agentId, summary.finalText ?? '', runId, tag);
+            break;
+        case 'ABORTED':
+            // 被中止时：如果已有部分输出内容，将其作为 assistant 条目持久化，
+            // 刷新页面后用户仍能看到中断前的内容。
+            if (summary.finalText) {
+                await safeAppendAssistant(deps, ctx.groupId, agentId, summary.finalText, runId, tag);
+            }
+            // 在 assistant 条目之后写 user_aborted，保证前端按 ts 排序后终止提示在部分内容之后
+            await safeAppendSystem(deps, ctx.groupId, 'user_aborted', agentId, ctx.userId, runId, tag);
+            break;
+        case 'FAILED':
+            // 记录失败事件及错误详情，便于排查问题
+            await safeAppendSystem(deps, ctx.groupId, 'run_failed', agentId, ctx.userId, runId, tag, summary.errorMessage);
+            break;
+    }
+}

package/dist/src/group/orchestrator/routes/mention-concurrent-route.js

@@ -0,0 +1,226 @@
+/**
+ * @file MentionConcurrentRoute —— 路径 B：@ 命中成员串行回复
+ * @description
+ * 适用场景：用户消息 @ 了群内成员，被 @ 的成员按顺序串行回复，无需 Leader 参与决策。
+ *
+ * 执行流程：
+ *   1. 状态转移：PENDING → ROUTING → RUNNING_CHILDREN
+ *   2. 为每个被 @ 的成员创建独立的 run（预分配 runId + AbortSignal）
+ *   3. 按顺序串行执行所有被 @ 成员的 Agent run
+ *   4. 每个成员独立流式输出回复（通过 SocketStreamSink 推流）
+ *   5. 所有成员完成后，根据结果汇总终态 → DONE / FAILED / ABORTED
+ *
+ * 设计要点：
+ *   - 不涉及 Leader 决策，直接由被 @ 的成员回答
+ *   - 每个被 @ 的成员按顺序串行执行，前一个完成后再执行下一个
+ *   - 不进行结果汇总，每个成员直接回复用户
+ */
+// ─── 工具函数 / 常量导入 ───────────────────────────────────────────────────────
+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';
+// ─── 路由层公共工具 ─────────────────────────────────────────────────────────
+import { buildTag, createSinkForAgent, safeAppendAssistant, safeAppendSystem } from './route-helpers.js';
+/**
+ * 路径 B —— Mention 串行层
+ *
+ * @remarks
+ * 实现 DispatchRoute 接口，由 Orchestrator 在 mentions 非空时选择调用。
+ * 内部为每个被 @ 的 agentId 创建独立的 run，按顺序串行执行后汇总终态。
+ */
+export class MentionConcurrentRoute {
+    deps;
+    /** 路径标识名，用于日志和 RouteResult 中标记来源 */
+    name = 'mention_concurrent';
+    /** 模块级日志实例 */
+    log = getModuleLogger('group.mention-route');
+    /**
+     * @param deps - 由 Orchestrator 注入的共享依赖（runner、ledger、emitter 等）
+     */
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * 执行路径 B（Mention 串行层）
+     *
+     * @param input - 路径入参，包含调度上下文和状态机
+     * @returns 路径执行结果，包含终态和各 run 摘要
+     */
+    async run(input) {
+        const { ctx, state } = input;
+        const tag = buildTag(ctx);
+        // ── 1. 状态转移：PENDING → ROUTING → RUNNING_CHILDREN ──
+        // 若当前仍为初始态 PENDING，先过渡到 ROUTING 表示正在选路
+        if (state.getStatus() === 'PENDING') {
+            state.transitionTo('ROUTING');
+        }
+        // 进入 RUNNING_CHILDREN 表示子 run 开始执行
+        state.transitionTo('RUNNING_CHILDREN');
+        // ── 2. 串行执行所有被 @ 成员的 run ──
+        // 按 mentions 数组顺序逐个执行，前一个完成后再启动下一个
+        const runResults = [];
+        for (const agentId of ctx.mentions) {
+            const result = await this.executeMentionRun(ctx, agentId, tag);
+            runResults.push(result);
+        }
+        // ── 3. 汇总终态 ──
+        // 根据所有 run 的结果决定整体状态（DONE / FAILED / ABORTED）
+        const finalStatus = this.determineFinalStatus(runResults, state);
+        // ── 4. ABORTED 时写入 user_aborted 系统事件 ──
+        // 在所有 run 结束（部分内容已 appendAssistant）之后再写，
+        // 保证前端按 ts 排序后终止提示在 agent 部分回复内容之后。
+        if (finalStatus === '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}`);
+            }
+        }
+        this.log.info(`${tag} finished status=${finalStatus} mentionCount=${ctx.mentions.length} ` +
+            `successCount=${runResults.filter((r) => r.status === 'done').length}`);
+        return {
+            route: this.name,
+            finalStatus,
+            runs: runResults,
+            error: finalStatus === 'FAILED' ? new Error('一个或多个 Mention run 执行失败') : undefined,
+        };
+    }
+    /**
+     * 为单个被 @ 的成员执行 Agent run
+     *
+     * @param ctx - 调度上下文
+     * @param agentId - 被 @ 的成员 Agent ID
+     * @param tag - 日志前缀
+     * @returns 该 run 的执行摘要（不会抛出异常）
+     */
+    async executeMentionRun(ctx, agentId, tag) {
+        const { runner, runRegistry } = this.deps;
+        const individualTag = `${tag} agent=${agentId}`;
+        // ── 1. 预分配 runId 并注册 AbortSignal ──
+        // 生成唯一 runId，同时在 RunRegistry 中注册以支持级联 abort
+        const preRunId = generatePreRunId(ctx.conversationId, 'mention');
+        const abortSignal = runRegistry.registerRun(ctx.conversationId, preRunId, agentId);
+        // ── 2. 构造独立的流式输出上下文（每个成员独立推流） ──
+        // 每个被 @ 成员拥有独立的 replyMsgId，前端据此区分不同成员的流式回复
+        const originalMsgId = ctx.msgId ?? generateMsgId();
+        const sinkContext = createSinkForAgent(this.deps, ctx, agentId, preRunId, originalMsgId);
+        // 在 runner.run 之前显式发 typing_start，通知前端该成员即将开始输出
+        sinkContext.emitStart();
+        // ── 3. 执行 Agent run ──
+        let runOutput;
+        try {
+            runOutput = await runner.run({
+                groupId: ctx.groupId,
+                agentId,
+                userId: ctx.userId,
+                role: 'mention', // 标记为 mention 角色
+                message: ctx.userMessage,
+                systemPrompt: '', // Mention 场景直接使用 Agent 默认配置，不注入额外 system prompt
+                abortSignal, // 传入 abort 信号以支持用户中止
+                sinkContext, // 统一流式输出上下文
+                preassignedRunId: preRunId, // 使用预分配的 runId 保证一致性
+                // 传递文件附件，使 AI 能感知用户上传的文件
+                attachments: ctx.files?.filter((f) => f.uri).map((f) => ({
+                    name: f.name,
+                    mimeType: f.mimeType || 'application/octet-stream',
+                    url: f.uri,
+                    localPath: f.localPath,
+                })),
+            });
+        }
+        catch (err) {
+            // runner.run 内部已兜底，此处为极端异常（如 OOM）的最终防线
+            const e = err instanceof Error ? err : new Error(String(err));
+            this.log.error(`${individualTag} runner 异常: ${e.message}`);
+            // 异常时也需注销 run，避免 RunRegistry 泄漏
+            runRegistry.unregisterRun(ctx.conversationId, preRunId);
+            return { runId: preRunId, agentId, status: 'failed', errorMessage: errorToString(e) };
+        }
+        // ── 4. 处理 run 结果 ──
+        // 优先使用 runner 返回的真实 runId（SDK 可能重新分配），兜底用预分配 ID
+        const realRunId = runOutput.runId || preRunId;
+        const status = normalizeRunStatus(runOutput.status);
+        const summary = { runId: realRunId, agentId, status };
+        if (runOutput.status === 'ok') {
+            // 成功：记录最终文本并写入 assistant 账本，供历史消息回放
+            summary.finalText = runOutput.finalText;
+            await safeAppendAssistant(this.deps, ctx.groupId, agentId, runOutput.finalText, realRunId, individualTag);
+            this.log.info(`${individualTag} 回复完成 bytes=${runOutput.finalText.length}`);
+        }
+        else if (runOutput.status === 'aborted') {
+            // 被中止：如果已有部分输出内容，将其作为 assistant 条目持久化，
+            // 刷新页面后用户仍能看到中断前的内容。
+            // user_aborted 系统事件由 run 方法在所有 run 结束后统一写入，保证 ts 顺序正确。
+            summary.errorMessage = 'aborted';
+            if (runOutput.finalText) {
+                summary.finalText = runOutput.finalText;
+                await safeAppendAssistant(this.deps, ctx.groupId, agentId, runOutput.finalText, realRunId, individualTag);
+                this.log.info(`${individualTag} 中止但已有部分内容，已持久化 bytes=${runOutput.finalText.length}`);
+            }
+        }
+        else {
+            // 失败：记录错误信息并写入 system 账本，便于排查问题
+            summary.errorMessage = errorToString(runOutput.error);
+            await this.safeAppendSystemEvent(ctx, agentId, runOutput, realRunId, individualTag);
+        }
+        // ── 5. 收尾：从注册表中注销 run，释放 abort 监听资源 ──
+        runRegistry.unregisterRun(ctx.conversationId, preRunId);
+        return summary;
+    }
+    /**
+     * 根据所有 run 的结果汇总终态并转移状态机
+     *
+     * @remarks
+     * 优先级：ABORTED > FAILED > DONE
+     * 只要有一个 run 被 abort，整体标记为 ABORTED；
+     * 只要有一个 run 失败（且无 abort），整体标记为 FAILED。
+     */
+    determineFinalStatus(results, state) {
+        // 检查是否存在被用户主动中止的 run
+        const hasAborted = results.some((r) => r.status === 'aborted');
+        // 检查是否存在执行失败的 run
+        const hasFailed = results.some((r) => r.status === 'failed');
+        // 优先级：ABORTED > FAILED > DONE
+        if (hasAborted) {
+            state.forceTerminal('ABORTED');
+            return 'ABORTED';
+        }
+        if (hasFailed) {
+            state.forceTerminal('FAILED');
+            return 'FAILED';
+        }
+        // 全部成功，正常转移到 DONE
+        state.transitionTo('DONE');
+        return 'DONE';
+    }
+    /**
+     * 安全写入 system 事件账本
+     *
+     * @remarks
+     * 将非成功状态的 run 信息记录到系统账本，便于运维排查和审计。
+     * 根据 run 状态写入不同事件类型：
+     *   - aborted → user_aborted 事件（用户主动中止）
+     *   - 其他失败 → run_failed 事件（Agent 执行异常）
+     *
+     * 异常仅 warn 级别记录，不影响主流程。
+     */
+    async safeAppendSystemEvent(ctx, agentId, runOutput, runId, tag) {
+        try {
+            // 注意：aborted 分支已在上层处理（保存部分内容为 assistant 条目），
+            // 此方法现在仅处理非 abort 的失败场景。
+            if (runOutput.status !== 'aborted') {
+                // Agent 执行失败：记录 run_failed 事件及错误详情
+                await safeAppendSystem(this.deps, ctx.groupId, 'run_failed', agentId, ctx.userId, runId, tag, errorToString(runOutput.error));
+            }
+        }
+        catch (err) {
+            this.log.warn(`${tag} appendSystem 失败: ${err}`);
+        }
+    }
+}