@zooique/memora 1.0.1 → 2.0.3

package/dist/agent/loop.js

@@ -1,10 +1,24 @@
-import { LOOP_CONSTANTS } from '../agent/constants.js';
+import { AGENT_CONSTANTS, LOOP_CONSTANTS } from '../agent/constants.js';
 import { ContextManager } from '../agent/contextManager.js';
 import { runGuardrails } from '../agent/guardrail.js';
 import { NOOP_TRACER, TRACE_SPANS } from '../agent/tracer.js';
-import { MemoraError, isRetryableErrorCode, toError } from '../utils/errors.js';
+import { MemoraError, isAbortError, isRetryableErrorCode, toError } from '../utils/errors.js';
 import { safeSetTimeout } from '../utils/safeTimer.js';
+import { roundTo } from '../utils/math.js';
 import { logger } from '../logging/logger.js';
+/** AgentLoop 运行时指标纯状态容器（progressive-refactor §2.1 模式 A） */
+class LoopMetrics {
+    llmCallCount = 0;
+    totalInputTokens = 0;
+    totalOutputTokens = 0;
+    recallTotalCount = 0;
+    recallHitCount = 0;
+    toolCallCount = 0;
+    toolFailureCount = 0;
+    get hitRate() {
+        return this.recallTotalCount > 0 ? this.recallHitCount / this.recallTotalCount : 0;
+    }
+}
 export class AgentLoop {
     opts;
     messages = [];
@@ -17,34 +31,29 @@ export class AgentLoop {
     guardrailRules;
     /** Reflection 最大重试次数（默认 2） */
     maxReflectionRetries;
+    /**
+     * 当前轮次已推送的 REFLECTION_HINT 次数（显式计数器）
+     *
+     * 替代旧实现通过 messages.filter(startsWith('[REFLECTION_HINT]')).length 推断的方式——
+     * 当 ContextManager 裁剪中间段消息时，REFLECTION_HINT 可能被裁掉导致计数失真。
+     * 显式字段不受 messages 数组变动影响，状态机更健壮。
+     */
+    reflectionCountThisTurn = 0;
     /** 宿主可覆盖的 UI 消息文本（已填充默认值） */
     ui;
+    /** 护栏规则正则编译失败回调（从 opts.onGuardrailError 提取，用于 GuardrailUI） */
+    guardrailUI;
     /** 上下文超限时是否自动生成摘要 */
     enableContextSummary;
     /** 上下文管理器（从 loop 提取的 token 估算 + 截断 + 摘要职责） */
     contextManager;
-    // ─── 运行时指标统计字段 ──────────────────────────
-    // 累计值，从 AgentLoop 构造起累加，供 getMetrics() 返回快照。
-    // 设计为私有字段而非外部注入，保持 AgentLoop 自洽。
-    /** LLM 调用总次数（含重试，每次 provider.chat 调用 +1） */
-    metricLlmCallCount = 0;
-    /** 累计输入 token 数（基于 estimateTokens 粗略估算） */
-    metricTotalInputTokens = 0;
-    /** 累计输出 token 数（基于 estimateTokens 粗略估算） */
-    metricTotalOutputTokens = 0;
-    /** 记忆召回总次数（每轮 processUserInput +1） */
-    metricRecallTotalCount = 0;
-    /** 记忆召回命中次数（召回结果非空 +1） */
-    metricRecallHitCount = 0;
-    /** 工具调用总次数 */
-    metricToolCallCount = 0;
-    /** 工具调用失败次数（结果以 [ERR 开头） */
-    metricToolFailureCount = 0;
+    // ─── 运行时指标统计 ──────────────────────────────
+    metrics = new LoopMetrics();
     // metricTruncationCount 已移至 ContextManager.truncationCount
     constructor(opts) {
         this.opts = opts;
         this.maxIterations = opts.maxIterations ?? 20;
-        this.maxContextTokens = opts.maxContextTokens ?? 32000;
+        this.maxContextTokens = opts.maxContextTokens ?? AGENT_CONSTANTS.DEFAULT_MAX_CONTEXT_TOKENS;
         this.tracer = opts.tracer ?? NOOP_TRACER;
         this.guardrailRules = opts.guardrailRules ?? [];
         this.maxReflectionRetries = opts.maxReflectionRetries ?? 2;
@@ -63,8 +72,15 @@ export class AgentLoop {
             guardrailWarningPrefix: opts.messages?.guardrailWarningPrefix ?? '[Guardrail Warning]',
             outputBlockedByGuard: opts.messages?.outputBlockedByGuard ??
                 ((rule) => `Output blocked by guardrail rule "${rule}"`),
+            reflectionHint: opts.messages?.reflectionHint ??
+                ((remaining) => `[REFLECTION_HINT] 上次工具调用失败，错误可重试。请分析错误原因，修正参数后重新调用工具。剩余反思次数：${remaining}`),
         };
         this.enableContextSummary = opts.enableContextSummary ?? true;
+        // 护栏规则正则编译失败回调（从 opts 提取，供 GuardrailUI 使用）
+        this.guardrailUI = {
+            inputBlockedByGuard: this.ui.inputBlockedByGuard,
+            onRegexError: opts.onGuardrailError,
+        };
         // 上下文管理器（token 估算 + 截断 + 摘要）
         // 注入 tracer，让 generateContextSummary 有 span 埋点
         this.contextManager = new ContextManager({
@@ -72,6 +88,7 @@ export class AgentLoop {
             provider: opts.provider,
             contextTruncatedFn: this.ui.contextTruncated,
             tracer: this.tracer,
+            onContextTruncated: opts.onContextTruncated,
         });
         // 初始化 system prompt（基于永驻记忆，加前缀）
         const prefix = opts.systemPromptPrefix ?? '';
@@ -81,7 +98,13 @@ export class AgentLoop {
         });
     }
     /**
-     * 处理一轮用户输入
+     * 处理一轮用户输入（编排方法）
+     *
+     * 拆分为 4 个子方法：
+     *   - handleRecallAndInputGuard：召回注入 + 输入护栏
+     *   - handleIteration：单次迭代编排（abort 检查 + LLM 调用 + 分支路由）
+     *   - handleToolCalls：工具调用分支 + Reflection
+     *   - handleTextResponse：纯文本结束 + 输出护栏
      *
      * @param userInput - 用户原始输入
      * @param recalledMemories - 记忆召回结果（Agent.memory.search() 产出），
@@ -95,168 +118,22 @@ export class AgentLoop {
             inputLength: userInput.length,
         });
         try {
-            // 注入记忆召回结果（agent上下文组装协议 §1：Agent 记忆召回结果层）
-            const recallSpan = this.tracer.startSpan(TRACE_SPANS.RECALL, {
-                recallCount: recalledMemories?.length ?? 0,
-            });
-            // 将召回记忆以 system 消息注入（优先级高、不污染 user 输入）
-            // 替代旧方案：嵌入 user 消息+反指令→模型易混淆
-            if (recalledMemories?.length) {
-                this.injectRecallAsSystem(recalledMemories);
-            }
-            // 补充 span 属性：让宿主监控面板能按命中/未命中过滤
-            recallSpan.setAttribute('hit', recalledMemories !== undefined && recalledMemories.length > 0);
-            recallSpan.end();
-            // 召回命中率统计：每轮对话算一次召回，结果非空算命中
-            this.metricRecallTotalCount++;
-            if (recalledMemories && recalledMemories.length > 0) {
-                this.metricRecallHitCount++;
-            }
-            // 有记忆召回时，通知上层（用于 UI 展示"召回透明度"——记忆名称 + 相似度）
-            // 暴露 id/name/score/source 摘要，不泄露完整 content
-            if (recalledMemories?.length) {
-                yield {
-                    type: 'recall',
-                    memories: recalledMemories.map((m) => ({
-                        id: m.id,
-                        name: m.name,
-                        score: m.score,
-                        source: m.source,
-                    })),
-                };
-            }
-            // 输入护栏检查：在用户输入注入上下文之前，检查是否命中护栏规则
-            // 护栏自身异常时降级为"放行 + 记日志"，不阻断用户对话
-            const inputGuardResult = runGuardrails(this.guardrailRules, userInput, this.ui);
-            if (inputGuardResult.blocked) {
-                // P3: try/finally 确保 done 一定送达，即使 text yield 异常
-                // guardrailBlocked: true 让 eval 框架和宿主 UI 通过结构化字段判断护栏触发
-                try {
-                    yield {
-                        type: 'text',
-                        content: inputGuardResult.message ?? 'Input blocked by guardrail',
-                        guardrailBlocked: true,
-                    };
-                }
-                finally {
-                    yield { type: 'done' };
-                }
+            // 1. 召回注入 + 输入护栏（返回 true 表示已 block 并 yield done，应 return）
+            if (yield* this.handleRecallAndInputGuard(userInput, recalledMemories))
                 return;
-            }
-            if (inputGuardResult.warning) {
-                // warn 级别只通知，不阻断
-                yield {
-                    type: 'text',
-                    content: `${this.ui.guardrailWarningPrefix} ${inputGuardResult.warning}`,
-                };
-            }
-            // 安全规范 §6：用户输入用 <user_input> 标签包裹，增强 LLM 对注入攻击的免疫力
+            // 2. 用户消息 push（安全规范 §6：用 <user_input> 标签包裹，增强 LLM 对注入攻击的免疫力）
             this.messages.push({ role: 'user', content: `<user_input>${userInput}</user_input>` });
+            // 重置当前轮次的反思计数器（每轮用户输入独立计算反思次数）
+            this.reflectionCountThisTurn = 0;
+            // 3. 迭代循环
             let iteration = 0;
             while (iteration < this.maxIterations) {
                 iteration++;
-                logger.debug({ iteration, messageCount: this.messages.length }, 'Agent Loop 迭代');
-                // 每次迭代前检查是否已被取消
-                if (signal?.aborted) {
-                    yield { type: 'aborted', reason: this.ui.abortedByUser };
-                    return;
-                }
-                // 调用 LLM（带重试 + 截断保护）
-                const chatOpts = this.buildChatOptions();
-                // 上下文摘要：如果启用且首次截断，生成摘要
-                let contextSummary;
-                if (this.enableContextSummary &&
-                    this.contextManager.shouldTruncate(this.messages)) {
-                    // 摘要缓存管理已移至 ContextManager.getOrCreateSummary
-                    // 传入 signal，让摘要生成可被用户取消中断（避免 generator 挂起）
-                    contextSummary = await this.contextManager.getOrCreateSummary(this.messages, signal);
-                }
-                const safeMessages = this.contextManager.truncateMessages(this.messages, contextSummary);
-                // 截断后同步替换工作记忆，防止 messages 数组无限增长
-                // 持久化由 MessageHistory 负责，工作记忆只需保留当前上下文窗口内的消息
-                if (safeMessages !== this.messages) {
-                    this.messages = [...safeMessages];
-                }
-                const llmResult = yield* this.callLlmWithRetry(safeMessages, chatOpts, signal, iteration);
-                if (llmResult.aborted) {
-                    // LLM 调用中断时仍保留已生成的部分文本到上下文消息列表
-                    // 让下一轮 LLM 能看到中断响应（追加 interrupted 标记让 LLM 识别非完整回复）
-                    // 注意：工具调用中断（execResult.aborted）不在此处理，因 executeToolCalls
-                    // 已 push assistant（含 toolCalls），追加文本标记会破坏工具调用结构
-                    if (llmResult.fullContent.trim()) {
-                        this.messages.push({
-                            role: 'assistant',
-                            content: llmResult.fullContent + this.ui.interrupted,
-                        });
-                    }
-                    yield { type: 'aborted', reason: this.ui.abortedByUser };
-                    return;
-                }
-                // 工具调用分支
-                if (llmResult.toolCalls && llmResult.toolCalls.length > 0) {
-                    const execResult = yield* this.executeToolCalls(llmResult.toolCalls, llmResult.fullContent, signal);
-                    if (execResult.aborted) {
-                        yield { type: 'aborted', reason: this.ui.abortedByUser };
-                        return;
-                    }
-                    // Reflection（反思/自修正）：检查是否有可重试的错误
-                    // 如果工具结果中有 retryable 错误，在 LLM 上下文中追加反思提示
-                    // 帮助 LLM 聚焦于修正而非放弃
-                    const hasRetryableError = this.messages
-                        .slice(-llmResult.toolCalls.length) // 只看本轮工具结果
-                        .some((m) => m.role === 'tool' && this.isRetryableToolError(m.content));
-                    if (hasRetryableError) {
-                        // 反思次数限制：通过前缀匹配统计已推送的 REFLECTION_HINT 消息
-                        // （实际推送的 content 带有后缀说明，需用 startsWith 而非严格相等）
-                        const reflectionHint = this.messages.filter((m) => m.role === 'system' && m.content.startsWith('[REFLECTION_HINT]')).length;
-                        if (reflectionHint < this.maxReflectionRetries) {
-                            this.messages.push({
-                                role: 'system',
-                                content: `[REFLECTION_HINT] 上次工具调用失败，错误可重试。请分析错误原因，修正参数后重新调用工具。剩余反思次数：${this.maxReflectionRetries - reflectionHint}`,
-                            });
-                        }
-                    }
-                    // 继续循环：把工具结果回填给 LLM
-                    continue;
-                }
-                // 纯文本结束
-                if (llmResult.fullContent) {
-                    this.messages.push({ role: 'assistant', content: llmResult.fullContent });
-                }
-                else {
-                    // LLM 返回空响应（既无文本也无工具调用）的兜底处理
-                    // 正常 LLM 不会返回空响应，但某些 provider 异常/边界情况下可能发生
-                    logger.warn({ iteration }, 'LLM 返回空响应（无文本、无工具调用），使用兜底提示');
-                    const fallbackText = '（模型未返回有效内容，请重试或换一种方式提问）';
-                    this.messages.push({ role: 'assistant', content: fallbackText });
-                    yield { type: 'text', content: fallbackText };
-                }
-                // 输出护栏检查：在响应返回给用户之前，检查是否命中护栏规则
-                const outputGuardResult = runGuardrails(this.guardrailRules, llmResult.fullContent, this.ui);
-                if (outputGuardResult.blocked) {
-                    // P3: try/finally 确保 done 一定送达，即使 text yield 异常
-                    // guardrailBlocked: true 让 eval 框架和宿主 UI 通过结构化字段判断护栏触发
-                    try {
-                        yield {
-                            type: 'text',
-                            content: outputGuardResult.message ?? 'Output blocked by guardrail',
-                            guardrailBlocked: true,
-                        };
-                    }
-                    finally {
-                        yield { type: 'done' };
-                    }
+                const result = yield* this.handleIteration(iteration, signal);
+                if (result === 'aborted' || result === 'done')
                     return;
-                }
-                if (outputGuardResult.warning) {
-                    yield {
-                        type: 'text',
-                        content: `${this.ui.guardrailWarningPrefix} ${outputGuardResult.warning}`,
-                    };
-                }
-                yield { type: 'done' };
-                return;
             }
+            // 4. 最大迭代兜底
             logger.warn({ iterations: iteration }, '达到最大迭代次数');
             yield { type: 'text', content: this.ui.maxIterationsReached };
             yield { type: 'done' };
@@ -265,6 +142,206 @@ export class AgentLoop {
             responseSpan.end();
         }
     }
+    /**
+     * 召回注入 + 输入护栏（processUserInput 子方法 1/4）
+     *
+     * 职责：
+     *   - 注入记忆召回结果（system 消息，优先级高、不污染 user 输入）
+     *   - 召回命中率统计（metricRecallTotalCount / metricRecallHitCount）
+     *   - 通知上层 UI 召回透明度（yield recall chunk）
+     *   - 输入护栏检查（block 时 yield text + done，warn 时 yield text）
+     *
+     * @yields recall / text（guardrail block/warn）/ done（block 时）
+     * @returns true 表示输入被 block 已 yield done，调用方应 return；false 表示继续
+     */
+    async *handleRecallAndInputGuard(userInput, recalledMemories) {
+        // 注入记忆召回结果 + 统计 + 透明度通知（提取到 _injectRecall，编码约定 §6）
+        yield* this._injectRecall(recalledMemories);
+        // 输入护栏检查：在用户输入注入上下文之前，检查是否命中护栏规则
+        // 护栏自身异常时降级为"放行 + 记日志"，不阻断用户对话
+        const inputGuardSpan = this.tracer.startSpan(TRACE_SPANS.GUARDRAIL_INPUT, {
+            ruleCount: this.guardrailRules.length,
+        });
+        const inputGuardResult = runGuardrails(this.guardrailRules, userInput, this.guardrailUI);
+        inputGuardSpan.setAttribute('blocked', inputGuardResult.blocked);
+        inputGuardSpan.setAttribute('warned', !!inputGuardResult.warning);
+        inputGuardSpan.end();
+        if (inputGuardResult.blocked) {
+            // P3: try/finally 确保 done 一定送达，即使 text yield 异常
+            // guardrailBlocked: true 让 eval 框架和宿主 UI 通过结构化字段判断护栏触发
+            try {
+                yield {
+                    type: 'text',
+                    content: inputGuardResult.message ?? 'Input blocked by guardrail',
+                    guardrailBlocked: true,
+                };
+            }
+            finally {
+                yield { type: 'done' };
+            }
+            return true;
+        }
+        if (inputGuardResult.warning) {
+            // warn 级别只通知，不阻断
+            yield {
+                type: 'text',
+                content: `${this.ui.guardrailWarningPrefix} ${inputGuardResult.warning}`,
+            };
+        }
+        return false;
+    }
+    /**
+     * 单次迭代编排（processUserInput 子方法 2/4）
+     *
+     * 职责：
+     *   - abort 检查
+     *   - 上下文摘要 + 截断
+     *   - LLM 调用（callLlmWithRetry）
+     *   - LLM 中断处理
+     *   - 分支路由：工具调用 → handleToolCalls；纯文本 → handleTextResponse
+     *
+     * @yields text / aborted / done（由子方法委托）
+     * @returns 'aborted' | 'done' | 'continue'（continue 表示继续下一轮迭代）
+     */
+    async *handleIteration(iteration, signal) {
+        logger.debug({ iteration, messageCount: this.messages.length }, 'Agent Loop 迭代');
+        // 每次迭代前检查是否已被取消
+        if (signal?.aborted) {
+            yield { type: 'aborted', reason: this.ui.abortedByUser };
+            return 'aborted';
+        }
+        // 调用 LLM（带重试 + 截断保护）
+        const chatOpts = this.buildChatOptions();
+        // 上下文摘要：如果启用且首次截断，生成摘要
+        let contextSummary;
+        if (this.enableContextSummary &&
+            this.contextManager.shouldTruncate(this.messages)) {
+            // 摘要缓存管理已移至 ContextManager.getOrCreateSummary
+            // 传入 signal，让摘要生成可被用户取消中断（避免 generator 挂起）
+            contextSummary = await this.contextManager.getOrCreateSummary(this.messages, signal);
+        }
+        const safeMessages = this.contextManager.truncateMessages(this.messages, contextSummary);
+        // 截断后同步替换工作记忆，防止 messages 数组无限增长
+        // 持久化由 MessageHistory 负责，工作记忆只需保留当前上下文窗口内的消息
+        if (safeMessages !== this.messages) {
+            this.messages = [...safeMessages];
+        }
+        const llmResult = yield* this.callLlmWithRetry(safeMessages, chatOpts, signal, iteration);
+        if (llmResult.aborted) {
+            // LLM 调用中断时仍保留已生成的部分文本到上下文消息列表
+            // 让下一轮 LLM 能看到中断响应（追加 interrupted 标记让 LLM 识别非完整回复）
+            // 注意：工具调用中断（execResult.aborted）不在此处理，因 executeToolCalls
+            // 已 push assistant（含 toolCalls），追加文本标记会破坏工具调用结构
+            if (llmResult.fullContent.trim()) {
+                this.messages.push({
+                    role: 'assistant',
+                    content: llmResult.fullContent + this.ui.interrupted,
+                });
+            }
+            yield { type: 'aborted', reason: this.ui.abortedByUser };
+            return 'aborted';
+        }
+        // 工具调用分支
+        if (llmResult.toolCalls && llmResult.toolCalls.length > 0) {
+            return yield* this.handleToolCalls(llmResult, signal);
+        }
+        // 纯文本结束分支
+        return yield* this.handleTextResponse(llmResult);
+    }
+    /**
+     * 工具调用分支 + Reflection（processUserInput 子方法 3/4）
+     *
+     * 职责：
+     *   - executeToolCalls 执行工具调用
+     *   - abort 检查（工具执行中断）
+     *   - Reflection：检查可重试错误，追加反思提示
+     *
+     * @yields aborted（工具执行中断时）
+     * @returns 'aborted' | 'continue'（continue 表示工具结果已回填，继续下一轮 LLM 调用）
+     */
+    async *handleToolCalls(llmResult, signal) {
+        const execResult = yield* this.executeToolCalls(llmResult.toolCalls, llmResult.fullContent, signal);
+        if (execResult.aborted) {
+            yield { type: 'aborted', reason: this.ui.abortedByUser };
+            return 'aborted';
+        }
+        // Reflection（反思/自修正）：检查是否有可重试的错误
+        // 如果工具结果中有 retryable 错误，在 LLM 上下文中追加反思提示
+        // 帮助 LLM 聚焦于修正而非放弃
+        const hasRetryableError = this.messages
+            .slice(-llmResult.toolCalls.length) // 只看本轮工具结果
+            .some((m) => m.role === 'tool' && this.isRetryableToolError(m.content));
+        if (hasRetryableError) {
+            // 反思次数限制：使用显式计数器，避免 messages 裁剪导致计数失真
+            if (this.reflectionCountThisTurn < this.maxReflectionRetries) {
+                this.reflectionCountThisTurn++;
+                this.messages.push({
+                    role: 'system',
+                    content: this.ui.reflectionHint(this.maxReflectionRetries - this.reflectionCountThisTurn),
+                });
+            }
+        }
+        // 继续循环：把工具结果回填给 LLM
+        return 'continue';
+    }
+    /**
+     * 纯文本结束 + 输出护栏（processUserInput 子方法 4/4）
+     *
+     * 职责：
+     *   - push assistant 消息（含空响应兜底）
+     *   - 输出护栏检查（block 时 yield text + done，warn 时 yield text）
+     *   - yield done 结束本轮对话
+     *
+     * @yields text（空响应兜底 / guardrail block/warn）/ done
+     * @returns 'done'（调用方收到后 return）
+     */
+    async *handleTextResponse(llmResult) {
+        // 输出护栏检查：在响应返回给用户之前，检查是否命中护栏规则
+        // 注意：护栏检查必须在 messages.push 之前执行，否则被 block 的内容仍会进入下一轮 LLM 上下文
+        const outputGuardSpan = this.tracer.startSpan(TRACE_SPANS.GUARDRAIL_OUTPUT, {
+            ruleCount: this.guardrailRules.length,
+        });
+        const outputGuardResult = runGuardrails(this.guardrailRules, llmResult.fullContent, this.guardrailUI);
+        outputGuardSpan.setAttribute('blocked', outputGuardResult.blocked);
+        outputGuardSpan.setAttribute('warned', !!outputGuardResult.warning);
+        outputGuardSpan.end();
+        if (outputGuardResult.blocked) {
+            // P3: try/finally 确保 done 一定送达，即使 text yield 异常
+            // guardrailBlocked: true 让 eval 框架和宿主 UI 通过结构化字段判断护栏触发
+            // block 时不 push 到 messages——被 block 的内容不应进入下一轮 LLM 上下文
+            try {
+                yield {
+                    type: 'text',
+                    content: outputGuardResult.message ?? 'Output blocked by guardrail',
+                    guardrailBlocked: true,
+                };
+            }
+            finally {
+                yield { type: 'done' };
+            }
+            return 'done';
+        }
+        // 护栏通过后再 push 到对话历史——确保被 block/warn 的内容不污染 LLM 上下文
+        if (llmResult.fullContent) {
+            this.messages.push({ role: 'assistant', content: llmResult.fullContent });
+        }
+        else {
+            // LLM 返回空响应（既无文本也无工具调用）的兜底处理
+            // 正常 LLM 不会返回空响应，但某些 provider 异常/边界情况下可能发生
+            logger.warn('LLM 返回空响应（无文本、无工具调用），使用兜底提示');
+            const fallbackText = '（模型未返回有效内容，请重试或换一种方式提问）';
+            this.messages.push({ role: 'assistant', content: fallbackText });
+            yield { type: 'text', content: fallbackText };
+        }
+        if (outputGuardResult.warning) {
+            yield {
+                type: 'text',
+                content: `${this.ui.guardrailWarningPrefix} ${outputGuardResult.warning}`,
+            };
+        }
+        yield { type: 'done' };
+        return 'done';
+    }
     /**
      * 调用 LLM（带指数退避重试）
      *
@@ -306,36 +383,10 @@ export class AgentLoop {
                 break;
             }
             if (attempt > 0) {
-                // 仅在流式输出前失败时重试（streamStarted = false）
-                const delay = LOOP_CONSTANTS.RETRY_BASE_DELAY_MS * Math.pow(2, attempt - 1);
-                logger.warn({ attempt, delay, error: lastError?.message }, 'LLM 调用失败，重试中');
-                // 发射 retry chunk：让宿主 UI 显示"网络波动，重试中 N/M..."，消除 3 秒静默
-                yield {
-                    type: 'retry',
-                    attempt,
-                    maxRetries: LOOP_CONSTANTS.MAX_LLM_RETRIES,
-                    delayMs: delay,
-                    error: lastError?.message ?? 'unknown error',
-                };
-                // 重试延迟期间支持 abort：用 Promise.race 替代单纯的 setTimeout
-                await new Promise((resolve) => {
-                    if (signal?.aborted) {
-                        resolve();
-                        return;
-                    }
-                    const timeoutId = safeSetTimeout(() => {
-                        signal?.removeEventListener('abort', onAbort);
-                        resolve();
-                    }, delay);
-                    const onAbort = () => {
-                        clearTimeout(timeoutId);
-                        resolve();
-                    };
-                    signal?.addEventListener('abort', onAbort, { once: true });
-                });
+                yield* this._waitForRetryWithAbort(attempt, lastError, signal);
+                // Reset streaming state after retry delay
                 fullContent = '';
                 toolCalls = undefined;
-                // 延迟后再次检查 abort
                 if (signal?.aborted) {
                     aborted = true;
                     break;
@@ -343,8 +394,8 @@ export class AgentLoop {
             }
             try {
                 // LLM 指标统计：每次 provider.chat 调用 +1，输入 token 累计
-                this.metricLlmCallCount++;
-                this.metricTotalInputTokens += this.contextManager.estimateTokens(safeMessages);
+                this.metrics.llmCallCount++;
+                this.metrics.totalInputTokens += this.contextManager.estimateTokens(safeMessages);
                 // safeMessages 为 readonly Message[]，provider.chat 期望 Message[]；
                 // 通过浅拷贝转换为可变数组，避免类型断言。
                 for await (const chunk of this.opts.provider.chat([...safeMessages], effectiveOpts)) {
@@ -362,7 +413,7 @@ export class AgentLoop {
                     }
                 }
                 // 输出 token 统计：成功时累计输出 token
-                this.metricTotalOutputTokens += this.contextManager.estimateTokens([
+                this.metrics.totalOutputTokens += this.contextManager.estimateTokens([
                     { role: 'assistant', content: fullContent },
                 ]);
                 break; // 成功，退出重试循环
@@ -372,7 +423,7 @@ export class AgentLoop {
                 lastError = e;
                 // AbortError 表示用户主动取消或超时中断，不重试，直接标记 aborted 退出
                 // 避免用户点击停止后仍继续发起 LLM 请求，防止 UI 卡在"停止生成"状态
-                if (e.name === 'AbortError' || (err instanceof DOMException && err.name === 'AbortError')) {
+                if (isAbortError(err)) {
                     aborted = true;
                     break;
                 }
@@ -380,13 +431,13 @@ export class AgentLoop {
                     // 流式已开始输出，不能重试（用户已看到部分结果），向上抛出
                     llmSpan.recordException(e);
                     llmSpan.end();
-                    throw err;
+                    throw lastError;
                 }
                 if (attempt >= LOOP_CONSTANTS.MAX_LLM_RETRIES) {
                     // 重试次数耗尽
                     llmSpan.recordException(e);
                     llmSpan.end();
-                    throw err;
+                    throw lastError;
                 }
                 // 继续重试（超时/网络错误等在流式开始前均可重试）
             }
@@ -418,52 +469,34 @@ export class AgentLoop {
             content: fullContent,
             toolCalls,
         });
-        // 执行工具
+        // 执行工具（E-803 并行优化：独立 tool_call 并发执行，事件按原始顺序 yield）
+        // 设计：方案 B（保持顺序的并发）
+        //   - 并发发起所有工具执行（Promise.all，真并发，总耗时 ≈ 最慢的工具）
+        //   - 批量 yield tool_start（UI 按 toolCallId 创建所有工具卡片）
+        //   - 按原始顺序 push messages + yield tool_result（保证 Reflection slice(-N) 正确）
+        //   - messages 顺序确定 → Reflection 的 slice(-toolCalls.length) 仍取到本轮完整结果
+        //   - 宿主 UI 按 toolCallId 配对 tool_start/tool_result，不依赖严格交替顺序
+        // 执行前检查取消（批量，避免 abort 后还发起工具）
+        if (signal?.aborted) {
+            return { aborted: true };
+        }
+        // 1. 批量 yield tool_start + 并发发起所有工具执行
+        const toolPromises = [];
         for (const tc of toolCalls) {
-            // 工具执行前检查取消
-            if (signal?.aborted) {
-                return { aborted: true };
-            }
             // 工具调用统计：每次工具执行 +1
-            this.metricToolCallCount++;
+            this.metrics.toolCallCount++;
             yield { type: 'tool_start', toolCallId: tc.id, name: tc.function.name, args: tc.function.arguments };
-            // 工具执行 Span
-            const toolSpan = this.tracer.startSpan(TRACE_SPANS.TOOL_EXEC, {
-                toolName: tc.function.name,
-            });
-            // 工具执行可能因文件不存在、路径越界等原因失败
-            // 捕获异常并转为结构化错误结果字符串，回传给 LLM 让其自行调整策略
-            // 避免错误直接传播到 agent.chat() 导致整个对话中断
-            // 错误结果包含 [ERR:TOOL:code] 前缀，供 Reflection 逻辑解析
-            let result;
-            try {
-                // 工具执行包裹 signal 中断，避免 abort 无法中断卡住的 generator
-                // 原 await toolExecutor 不响应 signal，工具卡住时 generator 挂起、_chatBusy 泄漏
-                result = await this.raceToolWithSignal(tc.function.name, tc.function.arguments, signal);
-            }
-            catch (err) {
-                const e = toError(err);
-                toolSpan.recordException(e);
-                if (err instanceof MemoraError) {
-                    const code = err.errorCode ?? 'UNKNOWN';
-                    result = `[ERR:TOOL:${code}] 错误：${err.title}${err.detail ? ` — ${err.detail}` : ''}`;
-                    logger.warn({ tool: tc.function.name, errorCode: code, title: err.title }, '工具执行失败，错误已回传给 LLM');
-                }
-                else {
-                    result = `[ERR:TOOL:UNKNOWN] 错误：工具执行异常 — ${e.message}`;
-                    logger.error({ tool: tc.function.name, err }, '工具执行异常');
-                }
-            }
-            toolSpan.end();
-            this.messages.push({
-                role: 'tool',
-                content: result,
-                toolCallId: tc.id,
-            });
-            // 工具失败统计：结果以 [ERR 开头算失败
-            if (result.startsWith('[ERR')) {
-                this.metricToolFailureCount++;
-            }
+            // 并发发起工具执行（不 await，收集 Promise 由 Promise.all 统一等待）
+            toolPromises.push(this.executeOneTool(tc, signal));
+        }
+        // 2. 等待全部工具完成（真并发，总耗时 ≈ 最慢的工具而非所有工具之和）
+        const results = await Promise.all(toolPromises);
+        // 3. 处理工具消息与失败统计
+        this._processToolResults(toolCalls, results);
+        // 4. 按原始顺序 yield tool_result
+        for (let i = 0; i < toolCalls.length; i++) {
+            const tc = toolCalls[i];
+            const result = results[i];
             yield {
                 type: 'tool_result',
                 toolCallId: tc.id,
@@ -513,17 +546,74 @@ export class AgentLoop {
             return '[ERR:TOOL:ABORTED] 错误：工具执行被中断';
         }
         // 创建 abort 监听 Promise（signal abort 时 resolve 错误字符串）
-        // 注意：工具先完成时，abort 监听器会残留在 signal 上直到 signal 触发或被 GC，
-        //   但 { once: true } 保证只触发一次，且无副作用，可接受。
+        // onAbort 提到外层，便于 race 结束后清理监听器
+        let onAbort = null;
         const abortPromise = new Promise((resolve) => {
-            const onAbort = () => resolve('[ERR:TOOL:ABORTED] 错误：工具执行被中断');
+            onAbort = () => resolve('[ERR:TOOL:ABORTED] 错误：工具执行被中断');
             signal.addEventListener('abort', onAbort, { once: true });
         });
         // Promise.race 竞争：工具先完成返回结果，signal 先 abort 返回错误字符串
+        // race 结束后清理监听器，避免 N 次并发工具调用累积 N 个残留监听器
+        // （{ once: true } 只保证触发一次，不保证未触发时被移除）
         return Promise.race([
             this.opts.toolExecutor(name, args),
             abortPromise,
-        ]);
+        ]).finally(() => {
+            if (onAbort)
+                signal.removeEventListener('abort', onAbort);
+        });
+    }
+    /**
+     * 执行单个工具（E-803 抽取：为并行化提供独立执行单元）
+     *
+     * 职责：
+     *   - startSpan / endSpan（工具执行 Span，并发时 span 时间重叠，可观测性改进）
+     *   - raceToolWithSignal 竞争包裹（兼容 signal 中断，每个工具独立 race）
+     *   - 异常捕获并转为结构化错误字符串（[ERR:TOOL:code] 前缀，供 Reflection 解析）
+     *
+     * 不含职责（由 executeToolCalls 主循环控制，保证顺序确定）：
+     *   - yield tool_start / tool_result（事件顺序由主循环批量 yield 保证）
+     *   - messages.push（消息顺序由主循环按原始顺序 push，确保 Reflection slice 正确）
+     *   - metricToolCallCount / metricToolFailureCount（统计由主循环控制）
+     *
+     * 并发安全：本方法无共享状态，多个 executeOneTool 可同时执行。
+     * toolExecutor 内部无状态（纯分发 + 参数校验），天然支持并发调用。
+     *
+     * @param tc 单个工具调用描述（id + function.name + function.arguments）
+     * @param signal 可选的 AbortSignal
+     * @returns 工具结果字符串（成功）或 [ERR:TOOL:code] 错误字符串（失败）
+     */
+    async executeOneTool(tc, signal) {
+        // 工具执行 Span（并发时多个 span 时间重叠，tracer 可观测并发度）
+        const toolSpan = this.tracer.startSpan(TRACE_SPANS.TOOL_EXEC, {
+            toolName: tc.function.name,
+        });
+        try {
+            // 工具执行包裹 signal 中断，避免 abort 无法中断卡住的 generator
+            // raceToolWithSignal 天然兼容并发：每个调用独立 race，{ once: true } 监听器无副作用
+            return await this.raceToolWithSignal(tc.function.name, tc.function.arguments, signal);
+        }
+        catch (err) {
+            // 工具执行可能因文件不存在、路径越界等原因失败
+            // 捕获异常并转为结构化错误结果字符串，回传给 LLM 让其自行调整策略
+            // 避免错误直接传播到 agent.chat() 导致整个对话中断
+            const e = toError(err);
+            toolSpan.recordException(e);
+            if (err instanceof MemoraError) {
+                const code = err.errorCode ?? 'UNKNOWN';
+                const result = `[ERR:TOOL:${code}] 错误：${err.title}${err.detail ? ` — ${err.detail}` : ''}`;
+                logger.warn({ tool: tc.function.name, errorCode: code, title: err.title }, '工具执行失败，错误已回传给 LLM');
+                return result;
+            }
+            else {
+                const result = `[ERR:TOOL:UNKNOWN] 错误：工具执行异常 — ${e.message}`;
+                logger.error({ tool: tc.function.name, err }, '工具执行异常');
+                return result;
+            }
+        }
+        finally {
+            toolSpan.end();
+        }
     }
     /**
      * 构建 system prompt（注入人格 + 规则 + 领域 + 工具描述）
@@ -544,6 +634,12 @@ export class AgentLoop {
             })
                 .join('\n');
             prompt += `\n\n## 可用工具\n\n你可以通过 tool_call 调用以下工具：\n${toolDescs}`;
+            // 工具选择规则：肯定式引导，放在工具描述之后作为 LLM 选工具时的决策依据
+            prompt += `\n\n## 工具选择规则（必须遵守）\n\n`
+                + `- 创建/修改角色（Persona）→ 必须使用 create_persona，禁止使用 write_file\n`
+                + `- 创建/修改技能（Skill）→ 必须使用 create_skill，禁止使用 write_file\n`
+                + `- 创建/修改规则（Rule）→ 必须使用 create_rule，禁止使用 write_file\n`
+                + `- 以上三种配置文件的任何操作，永远不要使用 write_file 工具`;
         }
         return prompt;
     }
@@ -643,6 +739,27 @@ export class AgentLoop {
         this.opts.systemPromptPrefix = newPrefix;
         this.rebuildSystemMessage();
     }
+    /**
+     * 刷新 bootstrap 记忆段（设定面板 CRUD 专用）
+     *
+     * 设定面板对 rule/skill 执行增删改后，调用此方法用最新的记忆数组
+     * 重建 system prompt 中的 bootstrap 段，使变更立即对当前会话生效。
+     *
+     * 与 refreshPersonaPrefix 的区别：
+     *   - refreshPersonaPrefix 替换 systemPromptPrefix（角色 + 画像）
+     *   - refreshBootstrapMemories 替换 bootstrapMemories（rule + skill）
+     *
+     * 调用链：ConfigManager.deleteRule/updateRule/deleteSkill
+     *   → refreshBootstrapMemories 回调（assembler 注入）
+     *   → loop.refreshBootstrapMemories(memories)
+     *   → rebuildSystemMessage()
+     *
+     * @param memories 最新的 rule + skill 活跃记忆数组（由 ConfigManager.getBootstrapMemories 提供）
+     */
+    refreshBootstrapMemories(memories) {
+        this.opts.bootstrapMemories = memories;
+        this.rebuildSystemMessage();
+    }
     /**
      * 注入情感基调到 system prompt（Phase 2.1：AffectController）
      *
@@ -688,24 +805,20 @@ export class AgentLoop {
      * @returns AgentMetrics 快照（decay 字段为 null，由 Agent 层填充）
      */
     getMetrics() {
-        // 计算召回命中率：totalCount 为 0 时返回 0，避免除零
-        const hitRate = this.metricRecallTotalCount > 0
-            ? this.metricRecallHitCount / this.metricRecallTotalCount
-            : 0;
         return {
             llm: {
-                callCount: this.metricLlmCallCount,
-                totalInputTokens: this.metricTotalInputTokens,
-                totalOutputTokens: this.metricTotalOutputTokens,
+                callCount: this.metrics.llmCallCount,
+                totalInputTokens: this.metrics.totalInputTokens,
+                totalOutputTokens: this.metrics.totalOutputTokens,
             },
             recall: {
-                totalCount: this.metricRecallTotalCount,
-                hitCount: this.metricRecallHitCount,
-                hitRate: Math.round(hitRate * 1000) / 1000, // 保留 3 位小数
+                totalCount: this.metrics.recallTotalCount,
+                hitCount: this.metrics.recallHitCount,
+                hitRate: roundTo(this.metrics.hitRate, 3), // 保留 3 位小数
             },
             tools: {
-                callCount: this.metricToolCallCount,
-                failureCount: this.metricToolFailureCount,
+                callCount: this.metrics.toolCallCount,
+                failureCount: this.metrics.toolFailureCount,
             },
             context: {
                 truncationCount: this.contextManager.truncationCount,
@@ -787,12 +900,78 @@ export class AgentLoop {
         const match = result.match(/^\[ERR:TOOL:(\w+)\]/);
         if (!match)
             return false;
-        // regex 捕获组保证 match[1] 非空，但使用空值兜底避免非空断言
         const codeStr = match[1] ?? '';
         if (!codeStr)
             return false;
         const code = codeStr;
         return isRetryableErrorCode(code);
     }
+    /**
+     * 重试延迟 + abort 支持（从 callLlmWithRetry 提取，编码约定 §6 ≤60 行约束）
+     *
+     * 发射 retry chunk、等待指数退避延迟（支持中途 abort），返回 void。
+     * 调用方在延迟后自行检查 signal.aborted 决定是否退出重试循环。
+     */
+    async *_waitForRetryWithAbort(attempt, lastError, signal) {
+        const delay = LOOP_CONSTANTS.RETRY_BASE_DELAY_MS * Math.pow(2, attempt - 1);
+        logger.warn({ attempt, delay, error: lastError?.message }, 'LLM 调用失败，重试中');
+        yield {
+            type: 'retry',
+            attempt,
+            maxRetries: LOOP_CONSTANTS.MAX_LLM_RETRIES,
+            delayMs: delay,
+            error: lastError?.message ?? 'unknown error',
+        };
+        await new Promise((resolve) => {
+            if (signal?.aborted) {
+                resolve();
+                return;
+            }
+            const timeoutId = safeSetTimeout(() => {
+                signal?.removeEventListener('abort', onAbort);
+                resolve();
+            }, delay);
+            const onAbort = () => { clearTimeout(timeoutId); resolve(); };
+            signal?.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    /**
+     * 处理工具执行结果：push messages + yield tool_result（从 executeToolCalls 提取）
+     */
+    _processToolResults(toolCalls, results) {
+        for (let i = 0; i < toolCalls.length; i++) {
+            const tc = toolCalls[i];
+            const result = results[i];
+            this.messages.push({ role: 'tool', content: result, toolCallId: tc.id });
+            if (result.startsWith('[ERR')) {
+                this.metrics.toolFailureCount++;
+            }
+        }
+    }
+    /**
+     * 注入记忆召回结果 + 统计 + 透明度通知（从 handleRecallAndInputGuard 提取）
+     */
+    async *_injectRecall(recalledMemories) {
+        const recallSpan = this.tracer.startSpan(TRACE_SPANS.RECALL, {
+            recallCount: recalledMemories?.length ?? 0,
+        });
+        if (recalledMemories?.length) {
+            this.injectRecallAsSystem(recalledMemories);
+        }
+        recallSpan.setAttribute('hit', recalledMemories !== undefined && recalledMemories.length > 0);
+        recallSpan.end();
+        this.metrics.recallTotalCount++;
+        if (recalledMemories && recalledMemories.length > 0) {
+            this.metrics.recallHitCount++;
+        }
+        if (recalledMemories?.length) {
+            yield {
+                type: 'recall',
+                memories: recalledMemories.map((m) => ({
+                    id: m.id, name: m.name, score: m.score, source: m.source,
+                })),
+            };
+        }
+    }
 }
 //# sourceMappingURL=loop.js.map