@huyooo/ai-chat-core 0.2.19 → 0.2.21

package/src/providers/orchestrator.ts

@@ -0,0 +1,761 @@
+/**
+ * Chat Orchestrator
+ * 
+ * 统一处理：
+ * 1. 工具调用循环 (while iterations < MAX)
+ * 2. 消息历史维护 (assistant + tool 消息)
+ * 3. 事件发射 (ChatEvent)
+ * 4. 错误处理
+ * 
+ * 所有 Provider 通过此类执行，确保行为一致
+ */
+
+import type { ChatEvent } from '../events';
+import type { ChatMessage, ToolDefinition, SideEffect, ToolResult } from '../types';
+import type {
+  ProviderAdapter,
+  StandardMessage,
+  StreamChunk,
+  ToolCallRequest,
+  OrchestratorConfig,
+  OrchestratorContext,
+  OrchestratorOptions,
+  SearchResultItem,
+  AutoRunConfig,
+} from './types';
+import {
+  createTextDelta,
+  createThinkingStart,
+  createThinkingDelta,
+  createThinkingEnd,
+  createSearchStart,
+  createSearchResult,
+  createSearchEnd,
+  createToolCallStart,
+  createToolCallOutput,
+  createToolCallResult,
+  createToolCallRequest,
+  createDone,
+  createAbort,
+  createApiError,
+  createStepStart,
+  createStepEnd,
+  createAgentStatus,
+} from '../events';
+import type { ToolApprovalRequestEvent } from '../events';
+import { DebugLogger } from '../utils';
+import { compactMessages } from './context-compressor';
+import { WEB_SEARCH_TOOL_NAME } from '../internal/web-search';
+
+// 创建模块专用 logger
+const logger = DebugLogger.module('Orchestrator');
+
+
+function normalizeSearchResults(items: SearchResultItem[]): SearchResultItem[] {
+  const byUrl = new Map<string, SearchResultItem>();
+  for (const it of items) {
+    const url = String(it?.url ?? '').trim();
+    if (!url) continue;
+
+    const snippet = String(it?.snippet ?? '').trim();
+    let title = String(it?.title ?? '').trim();
+    if (!title) {
+      try {
+        title = new URL(url).hostname;
+      } catch {
+        title = url;
+      }
+    }
+
+    const prev = byUrl.get(url);
+    if (!prev) {
+      byUrl.set(url, { title, url, snippet });
+      continue;
+    }
+    if (!prev.snippet && snippet) prev.snippet = snippet;
+    if (!prev.title && title) prev.title = title;
+  }
+  return Array.from(byUrl.values());
+}
+
+/** 
+ * 默认最大迭代次数（安全兜底）
+ * 
+ * 不是正常终止条件——模型不调工具时循环自然 break。
+ * 
+ * 正常终止由以下机制保证：
+ * 1. 模型不再调工具 → break
+ * 2. 用户取消 → abort signal
+ * 3. context window 超限 → API 报错 → error handler
+ * 4. 重复工具调用检测 → 注入提示终止循环
+ * 
+ * 设为 25，作为异常情况的安全兜底（正常任务极少超过 10 轮）。
+ * 调用方可通过 OrchestratorConfig.maxIterations 覆盖。
+ */
+const DEFAULT_MAX_ITERATIONS = 25;
+
+/**
+ * 重复工具调用检测阈值
+ * 
+ * 同名同参数的工具连续调用超过此次数时，注入提示让模型停止循环。
+ */
+const DUPLICATE_TOOL_CALL_THRESHOLD = 2;
+
+/**
+ * Chat Orchestrator
+ * 
+ * 核心职责：统一处理工具调用循环，所有 Provider 共享相同的逻辑
+ */
+export class ChatOrchestrator {
+  private config: OrchestratorConfig;
+
+  constructor(config: OrchestratorConfig) {
+    this.config = {
+      maxIterations: DEFAULT_MAX_ITERATIONS,
+      ...config,
+    };
+  }
+
+  /**
+   * 执行聊天
+   * 
+   * @param adapter Provider 适配器
+   * @param message 用户消息
+   * @param context Orchestrator 上下文
+   * @param options 选项
+   */
+  async *chat(
+    adapter: ProviderAdapter,
+    message: string,
+    context: OrchestratorContext,
+    options: OrchestratorOptions
+  ): AsyncGenerator<ChatEvent> {
+    const startedAt = Date.now();
+    const maxIterations = this.config.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+
+    // 构建标准化消息列表
+    const messages = this.buildMessages(context, message);
+
+    // 初始压缩：前端传入的历史可能就已经超长
+    if (compactMessages(messages)) {
+      logger.info('初始历史已压缩');
+    }
+
+    // 全局状态
+    let iterations = 0;
+    let finalText = '';
+    let searchResults: SearchResultItem[] = [];
+    let searchStartedAt = 0;
+    let searchStarted = false;
+    let searchEnded = false;
+
+    // 重复工具调用检测：记录上一轮的工具调用签名（name + args hash）
+    let lastToolCallSignature = '';
+    let duplicateToolCallCount = 0;
+
+    // Token 使用累积（多轮工具调用时累加）
+    let totalUsage: { promptTokens: number; completionTokens: number; totalTokens: number; reasoningTokens: number; cachedTokens: number } = {
+      promptTokens: 0, completionTokens: 0, totalTokens: 0, reasoningTokens: 0, cachedTokens: 0,
+    };
+    let hasUsage = false;
+
+    // 工具调用循环
+    while (iterations < maxIterations) {
+      if (context.signal.aborted) {
+        yield createAbort('请求已取消');
+        return;
+      }
+
+      iterations++;
+
+      // Context 压缩：如果消息历史过长，压缩中间部分
+      if (iterations > 1) {
+        compactMessages(messages);
+      }
+
+      const stepStartedAt = Date.now();
+      logger.info(`======= 第 ${iterations} 轮开始 =======`);
+
+      // 发射步骤开始事件（前端可用于展示 Agent 执行进度）
+      yield createStepStart(iterations);
+      // 告知前端当前阶段：模型正在思考（首次请求 / 工具执行完后新一轮）
+      yield createAgentStatus('thinking');
+
+      // ========== 每轮独立的状态 ==========
+      let thinkingText = '';
+      let thinkingStartedAt = 0;
+      let thinkingStarted = false;
+      let thinkingComplete = false;
+
+      // ========== 调试日志：chunk 计数 ==========
+      const chunkCounts: Record<string, number> = {};
+      let textStartedInOrchestrator = false;
+      const logChunk = (type: string) => {
+        chunkCounts[type] = (chunkCounts[type] || 0) + 1;
+      };
+      // ==========================================
+
+      try {
+        const pendingToolCalls: ToolCallRequest[] = [];
+        let hasToolCalls = false;
+
+        // 是否启用思考（每轮都可以启用）
+        // 强制转为 boolean，避免上层传入 'false' / 1 等导致逻辑误判
+        const enableThinkingThisRound = options.enableThinking === true;
+        // Web Search：允许在多轮中发生（模型可能在后续轮次再次检索）
+        const enableSearchThisRound = options.enableSearch === true;
+
+        logger.debug('调用 adapter.streamOnce', { enableThinking: enableThinkingThisRound, enableSearch: enableSearchThisRound });
+
+        const stream = adapter.streamOnce(messages, context.tools, {
+          model: options.model,
+          enableThinking: enableThinkingThisRound,
+          enableSearch: enableSearchThisRound,
+          signal: context.signal,
+        });
+
+        for await (const chunk of stream) {
+          logChunk(chunk.type);
+          switch (chunk.type) {
+            case 'text':
+              if (chunk.text) {
+                // 首次 text，记录状态并清除 thinking loading（文字流接管）
+                if (!textStartedInOrchestrator) {
+                  textStartedInOrchestrator = true;
+                  logger.debug('首次收到 text', { thinkingStarted, thinkingComplete });
+                  yield createAgentStatus(null);
+                }
+                // 如果还在思考中，先结束思考（仅在启用 thinking 时）
+                if (enableThinkingThisRound && thinkingStarted && !thinkingComplete) {
+                  logger.debug('text 触发 thinking_end');
+                  thinkingComplete = true;
+                  yield createThinkingEnd(thinkingStartedAt);
+                }
+                finalText += chunk.text;
+                yield createTextDelta(chunk.text);
+              }
+              break;
+
+            case 'thinking':
+              // Gate：未启用 thinking 时，忽略所有 thinking 输出（用于统一 ask/normal 体验）
+              if (!enableThinkingThisRound) break;
+              if (chunk.thinking) {
+                if (thinkingComplete) {
+                  // ⚠️ 异常：thinking_done 后还收到 thinking
+                  logger.warn('⚠️ thinkingComplete=true 但收到 thinking', chunk.thinking.slice(0, 30));
+                  logger.warn('当前状态', { textStarted: textStartedInOrchestrator, chunkCounts });
+                } else if (textStartedInOrchestrator) {
+                  // ⚠️ 异常：text 开始后还收到 thinking
+                  logger.warn('⚠️ text 开始后收到 thinking', chunk.thinking.slice(0, 30));
+                } else {
+                  // 兼容：部分 provider 的第一段 thinking 可能以换行开头（UI 使用 pre-wrap 会显示成“顶部空一行”）
+                  // 只在“第一段 thinking”做一次性处理，避免破坏中间格式
+                  let delta = chunk.thinking;
+                  if (!thinkingStarted) {
+                    delta = delta.replace(/^(?:\r?\n)+/, '');
+                    if (!delta) break; // 第一段只有换行：等待后续真正内容再开始
+                  }
+
+                  // 正常处理
+                  if (!thinkingStarted) {
+                    thinkingStarted = true;
+                    thinkingStartedAt = Date.now();
+                    logger.debug('发送 thinking_start');
+                    yield createAgentStatus(null); // thinking spinner 接管，清除 loading
+                    yield createThinkingStart();
+                  }
+                  thinkingText += delta;
+                  yield createThinkingDelta(delta);
+                }
+              }
+              break;
+
+            case 'thinking_done':
+              // Gate：未启用 thinking 时，忽略 thinking_done
+              if (!enableThinkingThisRound) break;
+              logger.info('收到 thinking_done', { thinkingStarted, thinkingComplete });
+              if (thinkingStarted && !thinkingComplete) {
+                thinkingComplete = true;
+                logger.debug('发送 thinking_end');
+                yield createThinkingEnd(thinkingStartedAt);
+              } else if (!thinkingStarted) {
+                logger.warn('⚠️ 收到 thinking_done 但 thinkingStarted=false');
+              }
+              break;
+
+            case 'tool_call':
+              if (chunk.toolCall) {
+                // Gate：如果当前没有任何可用工具定义，忽略模型产生的工具调用（避免 ask 模式误入工具循环）
+                if (!context.tools || context.tools.length === 0) {
+                  logger.warn('收到 tool_call 但当前未注入工具，已忽略', { toolName: chunk.toolCall.name });
+                  break;
+                }
+                pendingToolCalls.push(chunk.toolCall);
+                hasToolCalls = true;
+              }
+              break;
+
+            case 'search_result':
+              // Gate：未启用搜索时，忽略 search_result
+              if (!enableSearchThisRound) break;
+              if (chunk.searchResults) {
+                // 首次收到搜索结果时，发送 search_start 事件
+                if (!searchStarted) {
+                  searchStarted = true;
+                  searchStartedAt = Date.now();
+                  yield createAgentStatus(null); // 搜索 spinner 接管，清除 loading
+                  yield createSearchStart(message);
+                }
+                searchResults = normalizeSearchResults(chunk.searchResults);
+                yield createSearchResult(searchResults, searchStartedAt);
+              }
+              break;
+
+            case 'done':
+              logger.info('收到 done', { finishReason: chunk.finishReason, usage: chunk.usage });
+              logger.info(`第 ${iterations} 轮 chunk 统计`, chunkCounts);
+              if (chunk.finishReason === 'tool_calls') {
+                hasToolCalls = true;
+              }
+              // 累积 Token 使用统计（多轮工具调用时累加）
+              if (chunk.usage) {
+                hasUsage = true;
+                totalUsage.promptTokens += chunk.usage.promptTokens || 0;
+                totalUsage.completionTokens += chunk.usage.completionTokens || 0;
+                totalUsage.totalTokens += chunk.usage.totalTokens || 0;
+                totalUsage.reasoningTokens += chunk.usage.reasoningTokens || 0;
+                totalUsage.cachedTokens += chunk.usage.cachedTokens || 0;
+              }
+              break;
+
+            case 'error':
+              logger.error('收到 error', chunk.error);
+              yield createApiError(chunk.error ?? '未知错误');
+              return;
+          }
+        }
+
+        logger.info(`第 ${iterations} 轮 for-await 循环结束`);
+        logger.debug('状态', { thinkingStarted, thinkingComplete });
+
+        // 确保思考状态完成（仅在启用 thinking 时）
+        if (enableThinkingThisRound && thinkingStarted && !thinkingComplete) {
+          logger.debug('补发 thinking_end');
+          thinkingComplete = true;
+          yield createThinkingEnd(thinkingStartedAt);
+        }
+
+        // 处理工具调用
+        if (hasToolCalls && pendingToolCalls.length > 0) {
+          // ========== 重复工具调用检测 ==========
+          // 生成当前轮的工具调用签名（所有工具名 + 参数拼接后的字符串）
+          const currentSignature = pendingToolCalls
+            .map(tc => `${tc.name}:${tc.arguments}`)
+            .sort()
+            .join('|');
+
+          if (currentSignature === lastToolCallSignature) {
+            duplicateToolCallCount++;
+          } else {
+            duplicateToolCallCount = 0;
+            lastToolCallSignature = currentSignature;
+          }
+
+          if (duplicateToolCallCount >= DUPLICATE_TOOL_CALL_THRESHOLD) {
+            logger.warn('检测到重复工具调用，注入终止提示', {
+              signature: currentSignature.slice(0, 200),
+              count: duplicateToolCallCount + 1,
+            });
+
+            // 不再执行工具，而是注入一条提示消息让模型停止循环
+            const toolNames = pendingToolCalls.map(tc => tc.name).join(', ');
+            messages.push({
+              role: 'assistant',
+              content: finalText,
+              toolCalls: pendingToolCalls,
+            });
+            for (const toolCall of pendingToolCalls) {
+              messages.push({
+                role: 'tool',
+                content: `[系统提示] 你已经连续 ${duplicateToolCallCount + 1} 次使用相同参数调用 ${toolCall.name}，任务应已完成。请直接回复用户执行结果，不要再调用工具。`,
+                toolCallId: toolCall.id,
+                toolName: toolCall.name,
+              });
+            }
+
+            // 发射步骤结束事件，进入下一轮让模型生成总结
+            yield createStepEnd(iterations, stepStartedAt);
+            finalText = '';
+            continue;
+          }
+          // ========== 重复检测结束 ==========
+
+          // 检查是否有客户端工具调用（优先使用 context 中的配置，兼容 config）
+          const clientToolNames = context.clientToolNames || this.config.clientToolNames;
+          const clientToolCalls = clientToolNames
+            ? pendingToolCalls.filter(tc => clientToolNames.has(tc.name))
+            : [];
+
+          // 如果有客户端工具调用，透传给客户端，结束本轮
+          if (clientToolCalls.length > 0) {
+            logger.info('检测到客户端工具调用，透传给客户端', clientToolCalls.map(tc => tc.name));
+
+            // 发送所有客户端工具调用请求
+            for (const toolCall of clientToolCalls) {
+              let args: Record<string, unknown>;
+              try {
+                args = JSON.parse(toolCall.arguments || '{}');
+              } catch {
+                args = {};
+              }
+              yield createToolCallRequest(toolCall.id, toolCall.name, args);
+            }
+
+            // 结束本轮对话，让客户端执行后发新请求继续
+            const duration = Date.now() - startedAt;
+            yield createDone(finalText, undefined, duration);
+            return;
+          }
+
+          // 工具执行阶段：工具卡片/搜索卡片接管进度显示，清除 loading
+          yield createAgentStatus(null);
+
+          // 1. 添加 assistant 消息（包含 tool_calls）到消息历史
+          const assistantMessage: StandardMessage = {
+            role: 'assistant',
+            content: finalText,
+            toolCalls: pendingToolCalls,
+          };
+          messages.push(assistantMessage);
+
+          // 2. 执行云端工具并添加 tool 消息
+          for (const toolCall of pendingToolCalls) {
+            const toolStartedAt = Date.now();
+
+            // 解析参数
+            let args: Record<string, unknown>;
+            try {
+              args = JSON.parse(toolCall.arguments || '{}');
+            } catch {
+              // 参数解析失败，添加错误消息
+              messages.push({
+                role: 'tool',
+                content: '参数解析错误',
+                toolCallId: toolCall.id,
+              });
+              continue;
+            }
+
+            // web_search_ai 参数兜底：
+            // OpenRouter 等模型有时会发起空 arguments 的 function_call（arguments: ""），导致 query 缺失。
+            // 为保证链路可用：当 query 缺失时，默认使用本轮用户消息作为 query。
+            if (toolCall.name === WEB_SEARCH_TOOL_NAME) {
+              const q = typeof args.query === 'string' ? args.query : '';
+              if (!q.trim()) {
+                args.query = message;
+              }
+            }
+
+            // 获取最新的自动运行配置（优先使用动态回调）
+            const autoRunConfig = this.config.getAutoRunConfig
+              ? await this.config.getAutoRunConfig()
+              : (options.autoRunConfig || this.config.autoRunConfig);
+
+            // 手动批准模式：需要用户确认
+            logger.debug('检查工具批准', {
+              toolName: toolCall.name,
+              autoRunConfigMode: autoRunConfig?.mode,
+              hasCallback: !!this.config.onToolApprovalRequest,
+            });
+            if (autoRunConfig?.mode === 'manual' && this.config.onToolApprovalRequest) {
+              logger.info('发送工具批准请求', toolCall.name);
+              // 发送批准请求事件
+              const approvalRequest: ToolApprovalRequestEvent = {
+                type: 'tool_approval_request',
+                data: {
+                  id: toolCall.id,
+                  name: toolCall.name,
+                  args,
+                  requestedAt: Date.now(),
+                },
+              };
+              yield approvalRequest;
+
+              // 等待用户批准
+              const approved = await this.config.onToolApprovalRequest({
+                id: toolCall.id,
+                name: toolCall.name,
+                args,
+              });
+
+              if (!approved) {
+                // 用户跳过执行
+                const result = JSON.stringify({ skipped: true, message: '用户跳过了此工具' });
+                if (toolCall.name === WEB_SEARCH_TOOL_NAME && enableSearchThisRound) {
+                  // 用 search_end 表示“跳过搜索”
+                  if (!searchStarted) {
+                    searchStarted = true;
+                    searchStartedAt = Date.now();
+                    const q = typeof args.query === 'string' ? args.query : message;
+                    yield createSearchStart(q);
+                  }
+                  searchEnded = true;
+                  yield createSearchEnd(false, searchStartedAt, `用户跳过了 ${WEB_SEARCH_TOOL_NAME}`);
+                } else {
+                  yield createToolCallResult(toolCall.id, toolCall.name, result, false, toolStartedAt);
+                }
+                messages.push({
+                  role: 'tool',
+                  content: result,
+                  toolCallId: toolCall.id,
+                  toolName: toolCall.name,
+                });
+                continue;
+              }
+            }
+
+            const isWebSearchTool = toolCall.name === WEB_SEARCH_TOOL_NAME;
+            // web_search_ai 走专属事件；其他工具（含 update_plan）走通用 tool_call_start
+            if (!isWebSearchTool) {
+              yield createToolCallStart(toolCall.id, toolCall.name, args);
+            } else if (enableSearchThisRound) {
+              if (!searchStarted) {
+                searchStarted = true;
+                searchStartedAt = Date.now();
+                const q = typeof args.query === 'string' ? args.query : message;
+                yield createSearchStart(q);
+              }
+            }
+
+            // 执行工具
+            let result: string;
+            let dynamicSideEffects: SideEffect[] | undefined;
+            let success = true;
+            try {
+              // stdout/stderr 流式输出：通过 hooks 推送到事件队列，再在等待工具完成期间持续 yield
+              const eventQueue: ChatEvent[] = [];
+              let wake: (() => void) | null = null;
+              const notify = () => wake?.();
+              const pushEvent = (ev: ChatEvent) => {
+                eventQueue.push(ev);
+                notify();
+              };
+
+              let toolDone = false;
+              let toolValue: string | ToolResult | undefined;
+              let toolError: unknown;
+
+              const hooks = {
+                toolCallId: toolCall.id,
+                toolName: toolCall.name,
+                onStdout: (chunk: string) => {
+                  if (chunk) pushEvent(createToolCallOutput(toolCall.id, toolCall.name, 'stdout', chunk));
+                },
+                onStderr: (chunk: string) => {
+                  if (chunk) pushEvent(createToolCallOutput(toolCall.id, toolCall.name, 'stderr', chunk));
+                },
+              };
+
+              this.config.executeTool(toolCall.name, args, context.signal, hooks)
+                .then((v) => {
+                  toolValue = v;
+                  toolDone = true;
+                  notify();
+                })
+                .catch((e) => {
+                  toolError = e;
+                  toolDone = true;
+                  notify();
+                });
+
+              // 在工具执行期间，把 stdout/stderr 事件不断 yield 出去
+              while (!toolDone || eventQueue.length > 0) {
+                while (eventQueue.length > 0) {
+                  const ev = eventQueue.shift();
+                  if (ev) yield ev;
+                }
+                if (toolDone) break;
+                await new Promise<void>((r) => (wake = r));
+                wake = null;
+              }
+
+              if (toolError) throw toolError;
+              const executeResult = toolValue as string | ToolResult;
+              // 处理返回值：可能是字符串或 ToolResult
+              if (typeof executeResult === 'string') {
+                result = executeResult;
+              } else {
+                result = executeResult.result;
+                dynamicSideEffects = executeResult.sideEffects;
+              }
+            } catch (error) {
+              success = false;
+              const errorMessage = error instanceof Error ? error.message : String(error);
+              result = `错误: ${errorMessage}`;
+            }
+
+            // 获取工具定义：用于副作用和结果类型
+            const tool = this.config.tools?.get(toolCall.name);
+            const sideEffects = dynamicSideEffects ?? tool?.sideEffects;
+            // 成功时传递 resultType，用于前端生成对应类型的 Part
+            const resultType = success ? tool?.resultType : undefined;
+
+            // 发射工具结果事件（包含副作用信息和结果类型）
+            // update_plan 走通用 tool_call_result（前端通过 resultType:'plan' 渲染 PlanPart）
+            if (!isWebSearchTool) {
+              yield createToolCallResult(toolCall.id, toolCall.name, result, success, toolStartedAt, undefined, sideEffects, resultType);
+            } else if (enableSearchThisRound) {
+              // web_search_ai：解析工具结果并产出 search_result / search_end
+              let parsedResults: SearchResultItem[] = [];
+              let parseError: string | undefined;
+              try {
+                const obj = JSON.parse(result || '{}') as any;
+                const arr = Array.isArray(obj?.results) ? obj.results : [];
+                parsedResults = arr
+                  .map((r: any) => ({
+                    title: typeof r?.title === 'string' ? r.title : '',
+                    url: typeof r?.url === 'string' ? r.url : '',
+                    snippet: typeof r?.snippet === 'string' ? r.snippet : '',
+                  }))
+                  .filter((r: SearchResultItem) => !!r.url);
+                if (typeof obj?.error === 'string' && obj.error) {
+                  parseError = obj.error;
+                  success = false;
+                }
+              } catch {
+                parseError = `${WEB_SEARCH_TOOL_NAME} 返回结果解析失败`;
+                success = false;
+              }
+
+              if (parsedResults.length > 0) {
+                searchResults = normalizeSearchResults(parsedResults);
+                yield createSearchResult(searchResults, searchStartedAt);
+              }
+              searchEnded = true;
+              yield createSearchEnd(success, searchStartedAt, parseError);
+            }
+
+            // 添加 tool 消息到历史
+            messages.push({
+              role: 'tool',
+              content: result,
+              toolCallId: toolCall.id,
+              toolName: toolCall.name,  // Gemini 需要工具名称
+            });
+
+            // 工具执行后检查取消信号：如果用户在工具执行过程中取消，立即终止
+            if (context.signal.aborted) {
+              yield createAbort('请求已取消');
+              return;
+            }
+          }
+
+          // 发射步骤结束事件
+          yield createStepEnd(iterations, stepStartedAt);
+
+          // 清空累积文本，进入下一轮
+          finalText = '';
+          continue;
+        }
+
+        // 没有工具调用，响应完成
+        yield createStepEnd(iterations, stepStartedAt);
+        break;
+
+      } catch (error) {
+        // 异常路径也要关闭 step 事件，确保前端 step 计数正确
+        yield createStepEnd(iterations, stepStartedAt);
+
+        if (context.signal.aborted) {
+          yield createAbort('请求已取消');
+        } else {
+          yield createApiError(error instanceof Error ? error.message : String(error));
+        }
+        return;
+      }
+    }
+
+    // 安全兜底：如果达到最大迭代次数，记录警告
+    if (iterations >= maxIterations) {
+      logger.warn(`达到最大迭代次数 ${maxIterations}，强制结束工具调用循环`);
+    }
+
+    // 确保搜索状态完成
+    if (searchStarted && !searchEnded) {
+      yield createSearchEnd(true, searchStartedAt);
+    }
+
+    // 注意：不再更新 context.history
+    // 无状态架构：前端负责保存消息到数据库，下次请求时重新构建历史
+
+    // 发射完成事件（包含累积的 Token 使用统计）
+    const duration = Date.now() - startedAt;
+    const usage = hasUsage ? {
+      promptTokens: totalUsage.promptTokens,
+      completionTokens: totalUsage.completionTokens,
+      totalTokens: totalUsage.totalTokens,
+      ...(totalUsage.reasoningTokens > 0 ? { reasoningTokens: totalUsage.reasoningTokens } : {}),
+      ...(totalUsage.cachedTokens > 0 ? { cachedTokens: totalUsage.cachedTokens } : {}),
+    } : undefined;
+    yield createDone(finalText, usage, duration);
+  }
+
+  /**
+   * 构建标准化消息列表
+   */
+  private buildMessages(context: OrchestratorContext, message: string): StandardMessage[] {
+    const messages: StandardMessage[] = [];
+
+    // 系统提示
+    if (context.systemPrompt) {
+      messages.push({
+        role: 'system',
+        content: context.systemPrompt,
+      });
+    }
+
+    // 历史消息
+    for (const msg of context.history) {
+      const standardMsg: StandardMessage = {
+        role: msg.role as 'user' | 'assistant' | 'tool',
+        content: msg.content,
+      };
+
+      // 处理 assistant 消息的工具调用
+      if (msg.tool_calls) {
+        standardMsg.toolCalls = msg.tool_calls.map(tc => ({
+          id: tc.id,
+          name: tc.function.name,
+          arguments: tc.function.arguments,
+          // 保留 thought_signature（Gemini 模型需要）
+          thought_signature: tc.thought_signature,
+        }));
+      }
+
+      // 处理 tool 消息的 tool_call_id
+      if (msg.role === 'tool' && msg.tool_call_id) {
+        standardMsg.toolCallId = msg.tool_call_id;
+      }
+
+      messages.push(standardMsg);
+    }
+
+    // 当前用户消息（跳过空消息，用于工具调用后继续对话）
+    if (message) {
+      messages.push({
+        role: 'user',
+        content: message,
+        images: context.images,
+      });
+    }
+
+    return messages;
+  }
+}
+
+/**
+ * 创建 Orchestrator 实例
+ */
+export function createOrchestrator(config: OrchestratorConfig): ChatOrchestrator {
+  return new ChatOrchestrator(config);
+}