1. 重构背景

旧 coordinator.agent.ts 的问题（来自架构评审 P3 — 协调器只做编排）：

硬编码 Tool 定义：prepare_equipment_form 的 Zod Schema 直接写在 coordinator 中（约 120 行）
硬编码路由逻辑：关键词列表（EQUIPMENT_CREATE_KEYWORDS、FAULT_INTENT_KEYWORDS）静态判断走哪条管线
职责不清：同时包含 SSE 输出、System Prompt 构建、图片预处理、LLM 调用、意图学习——全部耦合在一起
多角色冲突：coordinator 同时是"路由器""翻译器""执行器""学习器"

重构目标：Coordinator 只负责"按顺序调动各模块"，不做具体的决策和执行。

2. 重构后的四阶段架构

```typescript // orchestrator.ts — 主入口，~233 行 export async function streamOrchestrator(opts: OrchestratorOptions) { const { ctx, messages, userMessage, imageBase64, res, ... } = opts;

// ── Phase 1: Context Build ────────────────────── const systemPrompt = buildSystemPrompt(ctx, { entities: entityResults, intentContext: intentResult?.contextBlock, recentPatterns: await getRecentPatterns(tenantId, 5), });

// ── Phase 2: Image Preprocess ─────────────────── let llmUserText = userMessage; if (imageBase64) { const imgDesc = await describeImageForCoordinator(imageBase64, mimeType); llmUserText = ${llmUserText}\n\n[图片内容摘要]\n${imgDesc}; }

// ── Phase 3: LLM Reasoning ─────────────────────── const authorizedTools = toolRegistry.getAuthorized(ctx.ability); const tools = createAuthorizedTools(authorizedTools, ctx);

const result = streamText({ model: provider.chat(AI_FAST_MODEL), system: systemPrompt, messages: [...chatHistory, { role: "user", content: llmUserText }], tools, stopWhen: stepCountIs(3), // 最多 3 次 Tool Call maxOutputTokens: 8192, });

// Phase 3 流式输出 → SSE const gen = handleSSEStream(result.fullStream, { res, logPrefix, intentResult, tenantId, userMessage, onToolCall: (toolName, action) => { // ── Phase 4: Learning (fire-and-forget) ────── recordIntentPattern({ tenantId, rawExpression, resolvedIntent, confidence }) .catch(() => {}); }, }); } ```

每个 Phase 的职责单一、边界清楚：

| Phase | 职责 | 复杂度 | |---|---|---| | Phase 1: Context Build | 构造 System Prompt（注入权限、实体、意图上下文） | 委托给 system-prompt-builder.ts | | Phase 2: Image Preprocess | 视觉模型将图片转为文字摘要 | 委托给 describeImageForCoordinator() | | Phase 3: LLM Reasoning | streamText + Tool Calling + SSE | 本文核心 | | Phase 4: Learning | fire-and-forget 记录意图模式 | 异步，不影响主流程 |

3. Phase 3 核心：Tool Calling + SSE

3.1 Tool Registry 按权限过滤

``typescript // orchestrator.ts — 只暴露用户有权使用的 Tool const authorizedTools = toolRegistry.getAuthorized(ctx.ability); const tools = createAuthorizedTools(authorizedTools, ctx); ``

toolRegistry.getAuthorized() 内部调用 ability.can(casl.action, casl.subject) 过滤，确保 LLM 的 Tool Choice 列表中不会出现用户无权调用的操作。

3.2 Tool Factory：注入权限、超时、错误处理

```typescript // tool-factory.ts — 每个 McpTool 被包装为 Vercel AI SDK Tool export function mcpToolToAiSdkTool(mcpTool, ctx) { return tool({ description: mcpTool.description, inputSchema: mcpTool.inputSchema, execute: async (input) => { // ① CASL 权限检查 if (casl && !ctx.ability.can(casl.action, casl.subject)) return { success: false, error: { code: "PERMISSION_DENIED" } };

// ② 超时控制 return Promise.race([ mcpTool.handler(input, ctx), timeout(15000), ]); }, }); } ```

三个注入点：权限检查、超时控制、错误格式化——全部由 Tool Factory 统一处理，Tool 本身不需要关心这些横切关注点。

3.3 SSE 流式输出

``typescript // sse-handler.ts — Generator 函数处理 streamText 事件流 export async function* handleSSEStream(fullStream, opts) { for await (const event of fullStream) { switch (event.type) { case "text-delta": // LLM 逐字输出 → 实时推送给前端 opts.res.write(data: ${JSON.stringify({ type: "chunk", content: event.text })}\n\n`); break;

case "tool-result": // Tool 执行完毕 → 推送 UI Card uiCard = event.output; opts.res.write(data: ${JSON.stringify({ type: "ui_card", card: uiCard })}\n\n); break; } } } ```

前端接收两种 SSE 事件：chunk（流式文字，打字机效果）和 ui_card（结构化卡片——DynamicForm、故障单、设备列表等）。

4. 两阶段管线集成（铭牌 OCR 特殊路径）

当用户明确说"建档/录入设备"并上传图片时，管线不走 LLM Tool Calling，而是直接走两阶段快速通道：

``typescript // coordinator.agent.ts（保留在旧文件中，待迁移到 orchestrator） if (hasEquipmentCreateIntent && imageBase64) { const rawFields = await extractFromNameplate(imageBase64, mimeType, "铭牌"); const classified = classifyFields(rawFields); const formResult = await executeEquipmentAction("prepare_equipment_form", formParams, ctx); // → 直接返回 DynamicForm，绕过 LLM Tool Calling } ``

这是性能优化：铭牌建档是确定性流程（拍铭牌 → 填表单），不需要 LLM 做路由决策。

5. 防止 Tool Calling 死循环

``typescript streamText({ // ... stopWhen: stepCountIs(3), // 最多 3 步 Tool Call }); ``

stepCountIs(3) 是 Vercel AI SDK 提供的控制机制——当 LLM 连续调用 Tool 超过 3 次时，强制停止并返回已有结果。这在设备关联备件 + 创建保养计划 + 检查库存的连续调用场景中重要：防止 LLM 在一个对话轮次中无休止地调用 Tool。

6. 核心文件索引

| 文件 | 行数 | 职责 | |---|---|---| | ai/orchestrator.ts | 233 | Pipeline 入口，四阶段调度 | | ai/tool-registry.ts | 86 | Tool 注册 + 按权限过滤 | | ai/tool-factory.ts | 93 | McpTool → AI SDK Tool + 权限/超时/错误注入 | | ai/sse-handler.ts | 118 | Generator 函数，streamText → SSE 事件转换 | | ai/system-prompt-builder.ts | — | System Prompt 动态构建 | | agents/coordinator.agent.ts | 880 | 旧 Coordinator（两阶段管道逻辑仍在此处） |

下一篇：基于 Qwen-VL 的铭牌 OCR 两阶段管线——详细拆解已发布的同名文章，包含 130s→3-8s 的性能修复过程。