@zooique/memora 0.3.0 → 2.0.0

package/dist/agent/loop.js

@@ -1,5 +1,6 @@
 import { 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 { safeSetTimeout } from '../utils/safeTimer.js';
@@ -80,7 +81,13 @@ export class AgentLoop {
         });
     }
     /**
-     * 处理一轮用户输入
+     * 处理一轮用户输入（编排方法）
+     *
+     * 拆分为 4 个子方法：
+     *   - handleRecallAndInputGuard：召回注入 + 输入护栏
+     *   - handleIteration：单次迭代编排（abort 检查 + LLM 调用 + 分支路由）
+     *   - handleToolCalls：工具调用分支 + Reflection
+     *   - handleTextResponse：纯文本结束 + 输出护栏
      *
      * @param userInput - 用户原始输入
      * @param recalledMemories - 记忆召回结果（Agent.memory.search() 产出），
@@ -94,158 +101,20 @@ 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 = this.runInputGuardrails(userInput);
-            if (inputGuardResult.blocked) {
-                // P3: try/finally 确保 done 一定送达，即使 text yield 异常
-                try {
-                    yield { type: 'text', content: inputGuardResult.message ?? 'Input blocked by guardrail' };
-                }
-                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>` });
+            // 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 };
+                const result = yield* this.handleIteration(iteration, signal);
+                if (result === 'aborted' || result === 'done')
                     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 = this.runOutputGuardrails(llmResult.fullContent);
-                if (outputGuardResult.blocked) {
-                    // P3: try/finally 确保 done 一定送达，即使 text yield 异常
-                    try {
-                        yield { type: 'text', content: outputGuardResult.message ?? 'Output blocked by guardrail' };
-                    }
-                    finally {
-                        yield { type: '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' };
@@ -254,6 +123,232 @@ 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) {
+        // 注入记忆召回结果（agent上下文组装协议 §1：Agent 记忆召回结果层）
+        const recallSpan = this.tracer.startSpan(TRACE_SPANS.RECALL, {
+            recallCount: recalledMemories?.length ?? 0,
+        });
+        // 将召回记忆以 system 消息注入（优先级高、不污染 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 inputGuardSpan = this.tracer.startSpan(TRACE_SPANS.GUARDRAIL_INPUT, {
+            ruleCount: this.guardrailRules.length,
+        });
+        const inputGuardResult = runGuardrails(this.guardrailRules, userInput, this.ui);
+        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) {
+            // 反思次数限制：通过前缀匹配统计已推送的 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
+        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) {
+        // 纯文本结束
+        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 };
+        }
+        // 输出护栏检查：在响应返回给用户之前，检查是否命中护栏规则
+        const outputGuardSpan = this.tracer.startSpan(TRACE_SPANS.GUARDRAIL_OUTPUT, {
+            ruleCount: this.guardrailRules.length,
+        });
+        const outputGuardResult = runGuardrails(this.guardrailRules, llmResult.fullContent, this.ui);
+        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 通过结构化字段判断护栏触发
+            try {
+                yield {
+                    type: 'text',
+                    content: outputGuardResult.message ?? 'Output blocked by guardrail',
+                    guardrailBlocked: true,
+                };
+            }
+            finally {
+                yield { type: 'done' };
+            }
+            return 'done';
+        }
+        if (outputGuardResult.warning) {
+            yield {
+                type: 'text',
+                content: `${this.ui.guardrailWarningPrefix} ${outputGuardResult.warning}`,
+            };
+        }
+        yield { type: 'done' };
+        return 'done';
+    }
     /**
      * 调用 LLM（带指数退避重试）
      *
@@ -407,43 +502,33 @@ 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++;
             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();
+            // 并发发起工具执行（不 await，收集 Promise 由 Promise.all 统一等待）
+            toolPromises.push(this.executeOneTool(tc, signal));
+        }
+        // 2. 等待全部工具完成（真并发，总耗时 ≈ 最慢的工具而非所有工具之和）
+        const results = await Promise.all(toolPromises);
+        // 3. 按原始顺序 push messages + yield tool_result
+        //    顺序确定保证：Reflection 的 slice(-toolCalls.length) 能取到本轮完整结果
+        for (let i = 0; i < toolCalls.length; i++) {
+            const tc = toolCalls[i];
+            const result = results[i];
             this.messages.push({
                 role: 'tool',
                 content: result,
@@ -514,6 +599,58 @@ export class AgentLoop {
             abortPromise,
         ]);
     }
+    /**
+     * 执行单个工具（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（注入人格 + 规则 + 领域 + 工具描述）
      */
@@ -765,58 +902,7 @@ export class AgentLoop {
             logger.debug({ removedCount, remainingMessages: this.messages.length }, '临时 system 消息已清理');
         }
     }
-    // ─── 护栏与 Reflection 辅助方法 ──────────────────────────
-    /**
-     * 输入护栏检查
-     *
-     * 在用户输入注入上下文之前运行，遍历所有 guardrail 规则，
-     * 用正则匹配用户输入。命中 block action 时返回 blocked=true。
-     *
-     * 护栏自身异常（正则编译失败等）降级为"放行 + 记日志"，
-     * 永远不阻断用户对话（降级优先原则）。
-     */
-    runInputGuardrails(input) {
-        if (this.guardrailRules.length === 0)
-            return { blocked: false };
-        for (const rule of this.guardrailRules) {
-            try {
-                // 从记忆内容中提取 pattern（格式：pattern: /regex/ action: block|warn）
-                const patternMatch = rule.content.match(/pattern:\s*(.+)/);
-                const actionMatch = rule.content.match(/action:\s*(block|warn)/);
-                if (!patternMatch || !actionMatch)
-                    continue;
-                const pattern = patternMatch[1]?.trim();
-                const action = actionMatch[1]?.trim();
-                if (!pattern || !action)
-                    continue;
-                // 去掉正则定界符 //
-                const regexStr = pattern.startsWith('/') && pattern.endsWith('/') ? pattern.slice(1, -1) : pattern;
-                const regex = new RegExp(regexStr, 'i');
-                if (regex.test(input)) {
-                    if (action === 'block') {
-                        logger.warn({ rule: rule.name, pattern: regexStr }, '输入护栏阻断');
-                        return { blocked: true, message: this.ui.inputBlockedByGuard(rule.name) };
-                    }
-                    logger.warn({ rule: rule.name, pattern: regexStr }, '输入护栏警告');
-                    return { blocked: false, warning: this.ui.inputBlockedByGuard(rule.name) };
-                }
-            }
-            catch (err) {
-                // 护栏自身异常降级：放行 + 记日志
-                logger.error({ rule: rule.name, err }, '护栏规则执行异常，已降级放行');
-            }
-        }
-        return { blocked: false };
-    }
-    /**
-     * 输出护栏检查
-     *
-     * 在 LLM 响应返回给用户之前运行，防止敏感信息泄露。
-     * 输入/输出共享同一护栏规则集。
-     */
-    runOutputGuardrails(output) {
-        return this.runInputGuardrails(output);
-    }
+    // ─── Reflection 辅助方法 ────────────────────────────────
     /**
      * 判断工具错误结果是否可重试（Reflection 用）
      *