Vercel AI SDK 3.0 学习入门指南

前言：范式革命——当UI成为AI思维的涌现

在使用本指南前，请接受一个颠覆性的观念：我们不再是为AI生成的数据寻找匹配的UI容器。相反，我们正在构建一个环境，让合适的UI成为AI解决问题过程中自然“涌现”的产物。UI不再是预设的终点，而是AI思维过程的可视化、可交互的中间步骤。

本指南将带您掌握这种思想，并将其转化为稳定、可扩展、安全的生产级应用。

第一部分：核心哲学与四大基石

在深入案例前，必须理解支撑 Vercel AI SDK 3.0 生成式UI的四大核心理念。它们是您后续所有架构决策的理论依据。

1. 基石一：UI是AI状态的纯函数 (UI = f(AIState))

   • 理念: 整个用户界面，在任何时刻，都应是当前AI完整状态（包括对话历史、上下文、内部数据）的确定性渲染结果。
   • 实践: 我们使用createAI来管理这个核心的、持久化的AIState。这意味着UI的变更不是通过命令式地“添加”或“移除”组件，而是通过更新AIState，然后让React根据新状态重新渲染出正确的UI。

2. 基石二：工具是LLM的声明式API (Tools as a Declarative API for LLMs)

   • 理念: 您的React组件不再仅仅是UI片段，它们是提供给LLM的一套功能强大的、类型安全的“API”。您通过Zod Schema和描述（description）来定义这个API的“文档”。
   • 实践: LLM的职责是根据用户意图，选择调用哪个“API”（工具），并提供符合“文档”（Schema）的参数。SDK负责执行这个调用并将结果渲染出来。您的工作从“命令AI做什么”转变为“教会AI能用什么”。

3. 基石三：服务器是安全可靠的业务编排器 (The Secure Orchestrator)

   • 理念: 所有核心业务逻辑、数据获取、外部API调用和状态变更，都必须在服务器端的render函数或独立的Server Action中执行。
   • 实践: 客户端只接收渲染好的UI和无害的数据。API密钥、数据库连接、复杂的业务规则永远不会暴露。这天然地形成了一个安全的后端边界。

4. 基石四：流式传输是默认的用户体验 (Streaming as the Default UX)

   • 理念: 用户等待是糟糕的体验。系统必须在思考和处理的同时，持续地提供反馈。
   • 实践: 优先使用streamUI和异步生成器 (async function*)。这允许您流式传输加载状态、中间思考过程的文本、甚至是部分渲染的UI，从而创造一种“实时协作”而非“请求-响应”的体验。

第二部分：分级案例深潜——从基础构件到复杂工作流

我们将通过三个不同业务领域的案例，逐步展示四大基石如何在实践中组合，以解决日益复杂的问题。

Level 1: 基础构件——让AI掌握“说话”和“展示”

目标：掌握让AI返回单个、有状态的UI组件的核心模式。

案例1.1：智能金融仪表盘小部件 (领域：金融科技)

场景: 用户是金融分析师，他需要快速获取某支股票的关键指标。

实现:

1. 工具定义 (/components/ai/stock-quote.tsx