@huyooo/ai-chat-core 0.2.45 → 0.3.2

package/src/orchestrator/orchestrator.ts

@@ -0,0 +1,1002 @@
+/**
+ * Chat Orchestrator
+ * 
+ * 直接消费 Protocol 层的 RawEvent，统一处理：
+ * 1. Thinking 状态机（首段去换行、done 配对、text 前自动闭合）
+ * 2. 工具调用循环 (while iterations < MAX)
+ * 3. 消息历史维护 (assistant + tool 消息)
+ * 4. ChatEvent 发射
+ * 
+ * 只有两套类型：RawEvent（输入）和 ChatEvent（输出）
+ */
+
+import type { ChatEvent } from '../events';
+import type { Tool, ToolErrorCategory, ToolGovernanceSnapshot } from '../types';
+import {
+  isToolError,
+  normalizeToolResult,
+  resolveToolGovernanceSnapshot,
+  resolveToolResultUi,
+  serializeToolResult,
+} from '../types';
+import type { RawEvent, RawToolCall, ProtocolMessage } from '../protocols';
+import type { ProviderAdapter } from '../adapter/types';
+import type {
+  OrchestratorConfig,
+  OrchestratorContext,
+  OrchestratorOptions,
+  AutoRunConfig,
+} from './types';
+import { getModelContextConfigFromLLM } from '../adapter';
+import {
+  createTextStart,
+  createTextDelta,
+  createTextEnd,
+  createThinkingStart,
+  createThinkingDelta,
+  createThinkingEnd,
+  createToolCallStart,
+  createToolCallOutput,
+  createToolCallResult,
+  createToolCallRequest,
+  createDone,
+  createAbort,
+  createApiError,
+  createStepStart,
+  createStepEnd,
+  createAssistantSegmentStart,
+  createAgentStatus,
+} from '../events';
+import type { FinishReason, ToolFailureReason } from '../events';
+import type { ToolApprovalRequestEvent } from '../events';
+import { createModuleLogger } from '../logger';
+import { validateJsonSchemaArgs } from '../tool-manager/define-tool';
+import { type CompactConfig } from './context-compressor';
+import { compactIfNeeded, compressSingleMessageIfNeeded } from './compression-handler';
+import type { LLMConfig } from '../llm-config';
+// 创建模块专用 logger
+const logger = createModuleLogger('Orchestrator');
+
+function shouldLogCompiledPrompt() {
+  return process.env.NODE_ENV === 'development';
+}
+
+function normalizePositiveLimit(value: number | undefined): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!Number.isFinite(value)) return undefined;
+  if (value <= 0) return undefined;
+  return Math.floor(value);
+}
+
+interface ParsedToolArgs {
+  ok: boolean;
+  args: Record<string, unknown>;
+  argumentsJson: string;
+  result?: string;
+  error?: {
+    message: string;
+    code: string;
+    category: ToolErrorCategory;
+    retryable: boolean;
+    suggestion: string;
+  };
+}
+
+/** 解析工具调用参数（JSON 对象格式）。解析失败不能执行工具，也不能把非法 arguments 写回模型历史。 */
+function parseToolArgs(args: string): ParsedToolArgs {
+  const raw = args ?? '';
+  const source = raw.trim() ? raw : '{}';
+  try {
+    const parsed: unknown = JSON.parse(source);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('function.arguments must be a JSON object');
+    }
+    return {
+      ok: true,
+      args: parsed as Record<string, unknown>,
+      argumentsJson: JSON.stringify(parsed),
+    };
+  } catch (e) {
+    logger.warn({ args: args?.slice(0, 200), error: String(e) }, '工具调用参数 JSON 解析失败');
+    const failureReason: ToolFailureReason = 'parse_error';
+    const message = '工具调用参数不是合法 JSON 对象，已拒绝执行工具';
+    const error = {
+      message,
+      code: 'INVALID_TOOL_ARGUMENTS_JSON',
+      category: 'validation' as const,
+      retryable: true,
+      suggestion: '请根据工具 inputSchema 重新生成 JSON 对象形式的 function.arguments。',
+    };
+    return {
+      ok: false,
+      args: {},
+      argumentsJson: '{}',
+      error,
+      result: JSON.stringify(buildToolFailurePayload({
+        message,
+        failureReason,
+        code: error.code,
+        category: error.category,
+        retryable: error.retryable,
+        suggestion: error.suggestion,
+        details: raw ? { rawArgumentsPreview: raw.slice(0, 500) } : undefined,
+        cause: String(e),
+      })),
+    };
+  }
+}
+
+function resolveApprovalRequirement(input: {
+  autoRunConfig?: AutoRunConfig;
+  tool?: Tool;
+  governance?: ToolGovernanceSnapshot;
+}): {
+  needsApproval: boolean;
+  reason?: 'manual-mode' | 'tool-policy' | 'destructive-only';
+} {
+  const { autoRunConfig, tool, governance } = input;
+
+  if (autoRunConfig?.mode === 'manual') {
+    return { needsApproval: true, reason: 'manual-mode' };
+  }
+  if (!tool) {
+    return { needsApproval: false };
+  }
+  if (tool.requiresApproval === true || governance?.approvalPolicy === 'manual') {
+    return { needsApproval: true, reason: 'tool-policy' };
+  }
+  if (governance?.approvalPolicy === 'destructive-only' && governance.sideEffectLevel === 'destructive') {
+    return { needsApproval: true, reason: 'destructive-only' };
+  }
+
+  return { needsApproval: false };
+}
+
+function buildToolFailurePayload(input: {
+  message: string;
+  failureReason: ToolFailureReason;
+  code?: string;
+  category?: ToolErrorCategory;
+  retryable?: boolean;
+  suggestion?: string;
+  details?: Record<string, unknown>;
+  cause?: string;
+  stack?: string;
+}) {
+  const { message, failureReason, code, category, retryable, suggestion, details, cause, stack } = input;
+  const errorDetails = {
+    ...(details ?? {}),
+    ...(cause ? { cause } : {}),
+    ...(stack ? { stack } : {}),
+  };
+
+  return {
+    status: 'error' as const,
+    failureReason,
+    error: {
+      message,
+      ...(code ? { code } : {}),
+      ...(category ? { category } : {}),
+      ...(retryable !== undefined ? { retryable } : {}),
+      ...(suggestion ? { suggestion } : {}),
+      ...(Object.keys(errorDetails).length > 0 ? { details: errorDetails } : {}),
+    },
+  };
+}
+
+function inferToolErrorCategory(code: string | undefined, fallback: ToolErrorCategory): ToolErrorCategory {
+  if (code === 'INVALID_PARAMS') return 'validation';
+  if (code === 'PERMISSION_DENIED' || code === 'TOOL_NOT_ENABLED') return 'permission';
+  if (code === 'NETWORK_ERROR') return 'network';
+  if (code === 'NOT_FOUND') return 'not_found';
+  if (code === 'TIMEOUT') return 'runtime';
+  return fallback;
+}
+
+const MODEL_TOOL_FAILURE_NOTICE = 'This tool call failed. In the final answer, explicitly mention the failure or the verified retry outcome; do not report this step as passed unless a later successful retry clearly verified it.';
+
+function buildModelToolContent(result: string, success: boolean): string {
+  if (success) return result;
+
+  try {
+    const parsed = JSON.parse(result) as unknown;
+    const envelope: Record<string, unknown> = parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? { ...(parsed as Record<string, unknown>) }
+      : { value: parsed };
+    envelope._modelNotice = MODEL_TOOL_FAILURE_NOTICE;
+    return JSON.stringify(envelope);
+  } catch {
+    return `${MODEL_TOOL_FAILURE_NOTICE}\n${result}`;
+  }
+}
+
+/** 单个工具执行上下文 */
+interface ToolExecContext {
+  toolCall: RawToolCall;
+  args: Record<string, unknown>;
+  messages: ProtocolMessage[];
+  context: OrchestratorContext;
+  options: OrchestratorOptions;
+  message: string;
+}
+
+/**
+ * Chat Orchestrator
+ * 
+ * 核心职责：统一处理工具调用循环，所有 Provider 共享相同的逻辑
+ */
+export class ChatOrchestrator {
+  private config: OrchestratorConfig;
+
+  constructor(config: OrchestratorConfig) {
+    this.config = { ...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 = normalizePositiveLimit(options.maxIterations ?? this.config.maxIterations);
+    const maxDurationMs = normalizePositiveLimit(options.maxDurationMs ?? this.config.maxDurationMs);
+    const maxToolCalls = normalizePositiveLimit(options.maxToolCalls ?? this.config.maxToolCalls);
+    const maxTotalTokens = normalizePositiveLimit(options.maxTotalTokens ?? this.config.maxTotalTokens);
+
+    logger.info({ model: options.model, messagePreview: message.slice(0, 50) + (message.length > 50 ? '...' : '') }, '开始对话');
+    if (shouldLogCompiledPrompt()) {
+      logger.info({
+        model: options.model,
+        compiledPrompt: message,
+      }, '完整编译 Prompt');
+    }
+
+    // 构建标准化消息列表
+    let messages = this.buildMessages(context, message);
+
+    const ctxConfig = this.config.llmConfig
+      ? getModelContextConfigFromLLM(options.model, this.config.llmConfig)
+      : undefined;
+    const compactConfig: CompactConfig = ctxConfig
+      ? { contextWindowTokens: ctxConfig.contextWindowTokens, maxOutputTokens: ctxConfig.maxOutputTokens }
+      : { contextWindowTokens: 128_000, maxOutputTokens: 8192 };
+
+    // 单条超长消息压缩：最后一条 user 消息如果占满 context 预算，用长上下文模型压缩
+    messages = yield* compressSingleMessageIfNeeded(messages, compactConfig, this.config.summarize, this.config.compressionConfig);
+
+    // 初始压缩：前端传入的历史可能就已经超长，直接复用当前对话模型
+    messages = yield* compactIfNeeded(messages, compactConfig, this.config.summarize, options.model);
+
+    // 全局状态
+    let iterations = 0;
+    let toolCallsExecuted = 0;
+    let finalText = '';
+    let finalFinishReason: FinishReason = 'stop';
+    let budgetHitReason: FinishReason | undefined;
+    // 内容块 ID 生成器
+    let blockSeq = 0;
+    const nextBlockId = (prefix: string) => `${prefix}-${++blockSeq}`;
+
+    // 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 (true) {
+      if (context.signal.aborted) {
+        yield createAbort('请求已取消');
+        return;
+      }
+
+      if (maxDurationMs !== undefined && Date.now() - startedAt >= maxDurationMs) {
+        budgetHitReason = 'max_duration';
+        finalFinishReason = 'max_duration';
+        break;
+      }
+
+      if (maxIterations !== undefined && iterations >= maxIterations) {
+        budgetHitReason = 'max_iterations';
+        finalFinishReason = 'max_iterations';
+        break;
+      }
+
+      iterations++;
+
+      // 每轮迭代前检查是否需要压缩
+      if (iterations > 1) {
+        messages = yield* compactIfNeeded(messages, compactConfig, this.config.summarize, options.model);
+      }
+      if (context.refreshTools) {
+        context.tools = await context.refreshTools();
+      }
+
+      const stepStartedAt = Date.now();
+      logger.info({ model: options.model, iterations }, `第 ${iterations} 轮开始`);
+
+      // 发射步骤开始事件（前端可用于展示 Agent 执行进度）
+      yield createStepStart(iterations);
+      // 告知前端当前阶段：模型正在思考（首次请求 / 工具执行完后新一轮）
+      yield createAgentStatus('thinking');
+
+      // 每轮状态
+      let thinkingStartedAt = 0;
+      let thinkingStarted = false;
+      let thinkingDone = false;
+      let textStarted = false;
+      let thinkingContent = '';
+      let thinkingSignature = '';
+      let thinkingBlockId = '';
+      let textBlockId = '';
+
+      // enableThinking 仅传给 ModelAdapter/协议层（是否向厂商请求推理）；界面是否展示思考由流里是否出现 thinking_delta 决定，二者解耦
+
+      try {
+        const pendingToolCalls: RawToolCall[] = [];
+        let hasToolCalls = false;
+
+        const stream = adapter.streamOnce(messages, context.tools, {
+          model: options.model,
+          enableThinking: options.enableThinking,
+          signal: context.signal,
+        });
+
+        for await (const event of stream) {
+          switch (event.type) {
+            // ========== Thinking 状态机（从 ModelAdapter.transformEvents 移入） ==========
+            case 'thinking_delta':
+              if (!event.delta || thinkingDone) break;
+              thinkingContent += event.delta;
+              {
+                let delta = event.delta;
+                if (!thinkingStarted) {
+                  delta = delta.replace(/^\n+/, '');
+                  if (!delta) break;
+                  thinkingStarted = true;
+                  thinkingStartedAt = Date.now();
+                  thinkingBlockId = nextBlockId('thinking');
+                  yield createAgentStatus(null);
+                  yield createThinkingStart(thinkingBlockId);
+                }
+                yield createThinkingDelta(thinkingBlockId, delta);
+              }
+              break;
+
+            case 'thinking_done':
+              if (event.thinkingSignature) thinkingSignature = event.thinkingSignature;
+              if (thinkingDone) break;
+              thinkingDone = true;
+              if (thinkingStarted) {
+                yield createThinkingEnd(thinkingBlockId, thinkingStartedAt);
+              }
+              break;
+
+            // ========== 文本 ==========
+            case 'text_delta':
+              if (event.delta) {
+                if (thinkingStarted && !thinkingDone) {
+                  thinkingDone = true;
+                  yield createThinkingEnd(thinkingBlockId, thinkingStartedAt);
+                }
+                if (!textStarted) {
+                  textStarted = true;
+                  textBlockId = nextBlockId('text');
+                  yield createAssistantSegmentStart('step', iterations);
+                  yield createAgentStatus(null);
+                  yield createTextStart(textBlockId);
+                }
+                finalText += event.delta;
+                yield createTextDelta(textBlockId, event.delta);
+              }
+              break;
+
+            // ========== 工具调用（完整事件） ==========
+            case 'tool_call_done':
+              if (event.toolCall) {
+                pendingToolCalls.push({
+                  id: event.toolCall.id || '',
+                  name: event.toolCall.name || '',
+                  arguments: event.toolCall.arguments || '{}',
+                  thoughtSignature: event.toolCall.thoughtSignature,
+                });
+                hasToolCalls = true;
+              }
+              break;
+
+            // ========== 完成 ==========
+            case 'done':
+              if (thinkingStarted && !thinkingDone) {
+                thinkingDone = true;
+                yield createThinkingEnd(thinkingBlockId, thinkingStartedAt);
+              }
+              if (textStarted) {
+                yield createTextEnd(textBlockId);
+                textStarted = false;
+              }
+              logger.info({ finishReason: event.finishReason, usage: event.usage, iterations }, `第 ${iterations} 轮完成`);
+              if (event.finishReason) {
+                finalFinishReason = event.finishReason as FinishReason;
+              }
+              if (event.finishReason === 'tool_calls') {
+                hasToolCalls = true;
+              }
+              if (event.usage) {
+                hasUsage = true;
+                totalUsage.promptTokens += event.usage.promptTokens || 0;
+                totalUsage.completionTokens += event.usage.completionTokens || 0;
+                totalUsage.totalTokens += event.usage.totalTokens || 0;
+                totalUsage.reasoningTokens += event.usage.reasoningTokens || 0;
+                totalUsage.cachedTokens += event.usage.cachedTokens || 0;
+              }
+              break;
+
+            // ========== 错误 ==========
+            case 'error':
+              logger.error({ error: event.error }, '收到 error');
+              yield createApiError(event.error ?? '未知错误');
+              return;
+
+            // 忽略中间事件（tool_call_start, tool_call_delta）
+            default:
+              break;
+          }
+        }
+
+        // 处理工具调用
+        if (hasToolCalls && pendingToolCalls.length > 0) {
+          if (maxIterations !== undefined && iterations >= maxIterations) {
+            finalFinishReason = 'max_iterations';
+            budgetHitReason = 'max_iterations';
+            yield createStepEnd(iterations, stepStartedAt);
+            break;
+          }
+          if (maxDurationMs !== undefined && Date.now() - startedAt >= maxDurationMs) {
+            finalFinishReason = 'max_duration';
+            budgetHitReason = 'max_duration';
+            yield createStepEnd(iterations, stepStartedAt);
+            break;
+          }
+          if (maxTotalTokens !== undefined && totalUsage.totalTokens >= maxTotalTokens) {
+            finalFinishReason = 'max_tokens';
+            budgetHitReason = 'max_tokens';
+            yield createStepEnd(iterations, stepStartedAt);
+            break;
+          }
+          if (maxToolCalls !== undefined && toolCallsExecuted + pendingToolCalls.length > maxToolCalls) {
+            finalFinishReason = 'max_tool_calls';
+            budgetHitReason = 'max_tool_calls';
+            yield createStepEnd(iterations, stepStartedAt);
+            break;
+          }
+
+          const clientToolNames = context.clientToolNames;
+          const clientToolCalls = clientToolNames
+            ? pendingToolCalls.filter(tc => clientToolNames.has(tc.name))
+            : [];
+
+          // 如果有客户端工具调用，透传给客户端，结束本轮
+          if (clientToolCalls.length > 0) {
+            logger.info({ toolNames: clientToolCalls.map(tc => tc.name) }, '检测到客户端工具调用，透传给客户端');
+            yield createAgentStatus(null);
+
+            // 发送所有客户端工具调用请求
+            for (const toolCall of clientToolCalls) {
+              yield createAssistantSegmentStart('tool_call', iterations);
+              const parsedArgs = parseToolArgs(toolCall.arguments);
+              if (!parsedArgs.ok) {
+                yield createToolCallResult(
+                  toolCall.id,
+                  toolCall.name,
+                  parsedArgs.result ?? '',
+                  false,
+                  Date.now(),
+                  parsedArgs.error,
+                  undefined,
+                  'parse_error',
+                  {},
+                );
+                continue;
+              }
+              const currentTool = this.config.tools?.get(toolCall.name);
+              const effectiveGovernance = await resolveToolGovernanceSnapshot(currentTool, parsedArgs.args);
+              yield createToolCallRequest(
+                toolCall.id,
+                toolCall.name,
+                parsedArgs.args,
+                currentTool?.ui,
+                effectiveGovernance,
+              );
+            }
+
+            const duration = Date.now() - startedAt;
+            yield createDone(finalText, 'tool_calls', undefined, duration);
+            return;
+          }
+
+          // 工具执行阶段
+          yield createAgentStatus(null);
+
+          // 添加 assistant 消息（包含 tool_calls + thinkingContent）到消息历史
+          // thinkingContent 对 Kimi/DeepSeek 等 API 是必需的：开启 thinking 时工具调用循环必须回传
+          const parsedToolCalls = pendingToolCalls.map(toolCall => ({
+            toolCall,
+            parsedArgs: parseToolArgs(toolCall.arguments),
+          }));
+          messages.push({
+            role: 'assistant',
+            content: finalText,
+            toolCalls: parsedToolCalls.map(({ toolCall, parsedArgs }) => ({
+              ...toolCall,
+              arguments: parsedArgs.argumentsJson,
+            })),
+            ...(thinkingContent ? { thinkingContent } : {}),
+            ...(thinkingSignature ? { thinkingSignature } : {}),
+          } satisfies ProtocolMessage);
+
+          // 逐个执行云端工具（委托到 executeSingleTool）
+          for (const { toolCall, parsedArgs } of parsedToolCalls) {
+            if (maxDurationMs !== undefined && Date.now() - startedAt >= maxDurationMs) {
+              finalFinishReason = 'max_duration';
+              budgetHitReason = 'max_duration';
+              break;
+            }
+            if (maxToolCalls !== undefined && toolCallsExecuted >= maxToolCalls) {
+              finalFinishReason = 'max_tool_calls';
+              budgetHitReason = 'max_tool_calls';
+              break;
+            }
+
+            yield createAssistantSegmentStart('tool_call', iterations);
+            if (!parsedArgs.ok) {
+              const toolStartedAt = Date.now();
+              yield createToolCallResult(
+                toolCall.id,
+                toolCall.name,
+                parsedArgs.result ?? '',
+                false,
+                toolStartedAt,
+                parsedArgs.error,
+                undefined,
+                'parse_error',
+                {},
+              );
+              messages.push({
+                role: 'tool',
+                content: buildModelToolContent(parsedArgs.result ?? '', false),
+                toolCallId: toolCall.id,
+                toolName: toolCall.name,
+              });
+              toolCallsExecuted++;
+              continue;
+            }
+
+            yield* this.executeSingleTool({
+              toolCall, args: parsedArgs.args, messages, context, options, message,
+            });
+            toolCallsExecuted++;
+
+            if (context.signal.aborted) {
+              yield createAbort('请求已取消');
+              return;
+            }
+          }
+
+          if (budgetHitReason) {
+            yield createStepEnd(iterations, stepStartedAt);
+            break;
+          }
+
+          // 发射步骤结束事件
+          yield createStepEnd(iterations, stepStartedAt);
+
+          // 清空累积文本，进入下一轮
+          finalText = '';
+          continue;
+        }
+
+        // 没有工具调用，响应完成
+        // 空响应检测：模型正常返回但没有产出任何正文
+        if (!finalText && !textStarted) {
+          logger.warn(
+            {
+              model: options.model,
+              thinkingOnly: thinkingStarted,
+              finishReason: finalFinishReason,
+              toolsCount: context.tools?.length ?? 0,
+            },
+            '模型返回空响应',
+          );
+          const hint = '模型未生成正文，请重试或更换模型。';
+          const hintBlockId = nextBlockId('text');
+          yield createAssistantSegmentStart('step', iterations);
+          yield createTextStart(hintBlockId);
+          yield createTextDelta(hintBlockId, hint);
+          yield createTextEnd(hintBlockId);
+          finalText = hint;
+        }
+        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 (budgetHitReason) {
+      logger.warn(
+        {
+          finishReason: budgetHitReason,
+          maxIterations,
+          maxDurationMs,
+          maxToolCalls,
+          maxTotalTokens,
+          iterations,
+          toolCallsExecuted,
+          totalTokens: totalUsage.totalTokens,
+          durationMs: Date.now() - startedAt,
+        },
+        `命中执行预算限制：${budgetHitReason}`,
+      );
+    }
+
+
+    // 发射完成事件（包含累积的 Token 使用统计 + finishReason）
+    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;
+    logger.info({ model: options.model, duration: `${duration}ms`, iterations, tokens: usage?.totalTokens, finishReason: finalFinishReason }, '对话完成');
+    yield createDone(finalText, finalFinishReason, usage, duration);
+  }
+
+  /**
+   * 构建标准化消息列表
+   */
+  private buildMessages(context: OrchestratorContext, message: string): ProtocolMessage[] {
+    const messages: ProtocolMessage[] = [];
+
+    // 系统提示
+    if (context.systemPrompt) {
+      messages.push({
+        role: 'system',
+        content: context.systemPrompt,
+      });
+    }
+
+    // 历史消息
+    for (const msg of context.history) {
+      const standardMsg: ProtocolMessage = {
+        role: msg.role as 'user' | 'assistant' | 'tool' | 'system',
+        content: msg.content,
+      };
+
+      if (msg.tool_calls) {
+        standardMsg.toolCalls = msg.tool_calls.map(tc => ({
+          id: tc.id,
+          name: tc.function.name,
+          arguments: tc.function.arguments,
+          thoughtSignature: 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;
+  }
+
+  /**
+   * 执行单个工具：批准检查 → 执行 → 结果处理 → 推送消息到历史
+   * 从 chat() 主循环提取，降低嵌套深度
+   */
+  private async *executeSingleTool(tc: ToolExecContext): AsyncGenerator<ChatEvent> {
+    const { toolCall, args, messages, context, message } = tc;
+    const toolStartedAt = Date.now();
+    const allowedToolNames = new Set(context.tools.map((tool) => tool.name));
+    if (!allowedToolNames.has(toolCall.name)) {
+      const descriptor = this.config.getToolDescriptor?.(toolCall.name);
+      const knownTool = !!descriptor || !!this.config.tools?.has(toolCall.name);
+      const enableRef = descriptor?.alias ?? toolCall.name;
+      const retryable = knownTool;
+      const message = knownTool
+        ? `工具 "${toolCall.name}" 存在，但未在当前聊天工具定义中启用`
+        : `工具 "${toolCall.name}" 未在当前聊天工具定义中声明`;
+      const suggestion = knownTool
+        ? `请先调用 tool_enable，参数 {"items":[{"ref":"${enableRef}","enabled":true}]}；工具定义刷新后再调用 "${enableRef}"。`
+        : '请先使用 tool_search 查找可用工具，并只调用当前已声明的工具。';
+      const failureReason: ToolFailureReason = 'denied';
+      const result = JSON.stringify(buildToolFailurePayload({
+        message,
+        failureReason,
+        code: 'TOOL_NOT_ENABLED',
+        category: 'permission',
+        retryable,
+        suggestion,
+      }));
+      const toolErrorShape = {
+        message,
+        code: 'TOOL_NOT_ENABLED',
+        category: 'permission',
+        retryable,
+      };
+      yield createToolCallResult(
+        toolCall.id,
+        toolCall.name,
+        result,
+        false,
+        toolStartedAt,
+        toolErrorShape,
+        undefined,
+        failureReason,
+        {},
+      );
+      messages.push({ role: 'tool', content: buildModelToolContent(result, false), toolCallId: toolCall.id, toolName: toolCall.name });
+      return;
+    }
+
+    // 获取最新的自动运行配置
+    const autoRunConfig = this.config.getAutoRunConfig
+      ? await this.config.getAutoRunConfig()
+      : (tc.options.autoRunConfig || this.config.autoRunConfig);
+
+    // 批准检查
+    const currentTool = this.config.tools?.get(toolCall.name);
+    let effectiveGovernance: ToolGovernanceSnapshot;
+    let argsPassSchemaValidation = true;
+    if (currentTool?.parameters) {
+      try {
+        validateJsonSchemaArgs(currentTool.parameters, args);
+      } catch (error) {
+        argsPassSchemaValidation = false;
+        logger.warn({ toolName: toolCall.name, error: String(error) }, '工具参数校验失败，跳过审批并交由执行层返回错误');
+      }
+    }
+    if (argsPassSchemaValidation) {
+      try {
+        effectiveGovernance = await resolveToolGovernanceSnapshot(currentTool, args);
+      } catch (error) {
+        logger.warn({ toolName: toolCall.name, error: String(error) }, '工具输入治理预判失败，已提升为 manual');
+        effectiveGovernance = { approvalPolicy: 'manual' };
+      }
+    } else {
+      effectiveGovernance = currentTool
+        ? {
+          approvalPolicy: currentTool.approvalPolicy,
+          sideEffectLevel: currentTool.sideEffectLevel,
+          hostDependency: currentTool.hostDependency,
+        }
+        : {};
+    }
+    const approval = resolveApprovalRequirement({ autoRunConfig, tool: currentTool, governance: effectiveGovernance });
+    const needsApproval = argsPassSchemaValidation && approval.needsApproval;
+    if (needsApproval && this.config.onToolApprovalRequest) {
+      const toolDescriptor = this.config.getToolDescriptor?.(toolCall.name);
+      const approvalToolMeta = {
+        toolName: toolDescriptor?.name,
+        extensionId: toolDescriptor?.assetId,
+        alias: toolDescriptor?.alias,
+        displayName: toolDescriptor?.displayName,
+      };
+      logger.info({ toolName: toolCall.name }, '发送工具批准请求');
+      const approvalRequest: ToolApprovalRequestEvent = {
+        type: 'tool_approval_request',
+        data: {
+          id: toolCall.id,
+          name: toolCall.name,
+          ...approvalToolMeta,
+          args,
+          reason: approval.reason ?? 'tool-policy',
+          approvalPolicy: effectiveGovernance.approvalPolicy,
+          sideEffectLevel: effectiveGovernance.sideEffectLevel,
+          hostDependency: effectiveGovernance.hostDependency,
+          ...(effectiveGovernance.riskSummary ? { riskSummary: effectiveGovernance.riskSummary } : {}),
+          ...(effectiveGovernance.riskTags?.length ? { riskTags: effectiveGovernance.riskTags } : {}),
+          ...(effectiveGovernance.riskSignals?.length ? { riskSignals: effectiveGovernance.riskSignals } : {}),
+          requestedAt: Date.now(),
+        },
+      };
+      yield approvalRequest;
+
+      const approved = await this.config.onToolApprovalRequest({
+        id: toolCall.id,
+        name: toolCall.name,
+        ...approvalToolMeta,
+        args,
+      });
+
+      if (!approved) {
+        const failureReason: ToolFailureReason = 'denied';
+        const result = JSON.stringify(buildToolFailurePayload({
+          message: '用户跳过了此工具',
+          failureReason,
+          code: 'TOOL_CALL_SKIPPED',
+          category: 'permission',
+          retryable: true,
+          suggestion: '如果需要执行该工具，请重新发起请求并批准工具调用。',
+        }));
+        const toolErrorShape = {
+          message: '用户跳过了此工具',
+          code: 'TOOL_CALL_SKIPPED',
+          category: 'permission' as const,
+          retryable: true,
+          suggestion: '如果需要执行该工具，请重新发起请求并批准工具调用。',
+        };
+        yield createToolCallResult(
+          toolCall.id,
+          toolCall.name,
+          result,
+          false,
+          toolStartedAt,
+          toolErrorShape,
+          undefined,
+          failureReason,
+          effectiveGovernance,
+        );
+        messages.push({ role: 'tool', content: buildModelToolContent(result, false), toolCallId: toolCall.id, toolName: toolCall.name });
+        return;
+      }
+    }
+
+    // 发射工具开始事件（携带 ui 声明，前端据此决定渲染方式）
+    yield createToolCallStart(
+      toolCall.id,
+      toolCall.name,
+      args,
+      currentTool?.ui,
+      effectiveGovernance,
+    );
+
+    // 超时信号包装
+    const toolDefForTimeout = this.config.tools?.get(toolCall.name);
+    let effectiveSignal = context.signal;
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    if (toolDefForTimeout?.timeout) {
+      const ac = new AbortController();
+      timeoutId = setTimeout(() => ac.abort(), toolDefForTimeout.timeout);
+      context.signal.addEventListener('abort', () => ac.abort(), { once: true });
+      effectiveSignal = ac.signal;
+    }
+
+    // 执行工具
+    let result: string;
+    let toolErrorShape: import('../events').ToolError | undefined;
+    let success = true;
+    let resultUi = currentTool?.ui;
+    let failureReason: ToolFailureReason | undefined;
+    try {
+      const eventQueue: ChatEvent[] = [];
+      let wake: (() => void) | null = null;
+      const notify = () => wake?.();
+      const pushEvent = (ev: ChatEvent) => { eventQueue.push(ev); notify(); };
+
+      let toolDone = false;
+      let toolValue: import('../types').ToolExecuteResult | undefined;
+      let toolError: unknown;
+
+      const hooks = {
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        allowedToolNames: Array.from(allowedToolNames),
+        governance: effectiveGovernance,
+        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, effectiveSignal, hooks)
+        .then((v) => { toolValue = v; toolDone = true; notify(); })
+        .catch((e) => { toolError = e; toolDone = true; notify(); });
+
+      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 normalizedResult = normalizeToolResult(toolValue);
+      resultUi = resolveToolResultUi(normalizedResult, currentTool?.ui);
+      result = JSON.stringify(serializeToolResult(normalizedResult));
+    } catch (error) {
+      success = false;
+      if (isToolError(error)) {
+        toolErrorShape = error.toolError;
+        failureReason = error.toolError.code === 'TIMEOUT' ? 'timeout' : 'execution_error';
+        result = JSON.stringify(buildToolFailurePayload({
+          message: error.toolError.message,
+          failureReason,
+          code: error.toolError.code,
+          category: error.toolError.category ?? inferToolErrorCategory(error.toolError.code, 'runtime'),
+          retryable: error.toolError.retryable,
+          suggestion: error.toolError.suggestion,
+          details: error.toolError.details,
+          cause: error.cause ? String(error.cause) : undefined,
+        }));
+      } else {
+        const msg = error instanceof Error ? error.message : String(error);
+        toolErrorShape = { message: msg };
+        failureReason = 'execution_error';
+        result = JSON.stringify(buildToolFailurePayload({
+          message: msg,
+          failureReason,
+          category: 'runtime',
+          cause: error instanceof Error && error.cause ? String(error.cause) : undefined,
+          stack: error instanceof Error ? error.stack : undefined,
+        }));
+      }
+    }
+
+    if (timeoutId !== undefined) clearTimeout(timeoutId);
+
+    // 发射工具结果事件
+    yield createToolCallResult(
+      toolCall.id,
+      toolCall.name,
+      result,
+      success,
+      toolStartedAt,
+      toolErrorShape,
+      resultUi,
+      failureReason,
+      effectiveGovernance,
+    );
+
+    // 添加 tool 消息到历史
+    messages.push({
+      role: 'tool',
+      content: buildModelToolContent(result, success),
+      toolCallId: toolCall.id,
+      toolName: toolCall.name,
+    });
+  }
+}
+
+/**
+ * 创建 Orchestrator 实例
+ */
+export function createOrchestrator(config: OrchestratorConfig): ChatOrchestrator {
+  return new ChatOrchestrator(config);
+}