🔍 引言：AI SDK 的痛点与新选择

随着大模型（LLM）能力的爆发，越来越多前端/全栈开发者希望将 AI 能力嵌入产品。然而，主流 SDK（如 OpenAI 官方库、Vercel AI SDK）普遍存在以下问题：

• 厂商锁定：API 设计紧耦合特定模型（如 gpt-4o），切换成本高；
• 类型缺失：providerOptions 参数缺乏强类型校验，错误往往运行时才暴露；
• 生态割裂：React / Solid / Svelte 各自为政，难以复用核心逻辑；
• 工具调用（Function Calling）复杂：需手动处理工具注册、校验、执行与回传流程。

2025 年，TanStack 团队（TanStack Query、Router 的缔造者）推出了开源项目 —— TanStack AI，试图以“类型驱动 + 适配器架构 + 框架无关”的理念，重塑 AI 应用开发体验。

---

🚀 核心设计理念

TanStack AI 的设计哲学延续了 TanStack 系列一贯的简洁与克制：

特性	说明
Provider-Agnostic	通过 adapter 插件机制统一 OpenAI / Anthropic / Gemini / Llama 等后端，逻辑一次编写，自由切换模型。
End-to-End Type Safety	深度集成 TypeScript：模型名、providerOptions、工具入参均享编译时校验 + IDE 智能补全。
Framework-Agnostic	提供 @tanstack/ai-react、@tanstack/ai-solid、@tanstack/ai（vanilla）等包，核心逻辑零框架依赖。
Isomorphic Tooling	工具定义（Zod Schema）可同时用于服务端执行与客户端类型推导，安全又高效。

💡 官方愿景远不止 JS：未来将支持 Python / PHP 服务端运行时，构建跨语言 AI 标准。

---

⚙️ 快速上手：一个流式聊天应用

1️⃣ 服务端：定义流式聊天接口（Next.js API Route）

// pages/api/chat.ts
import { chat, toStreamResponse } from '@tanstack/ai';
import { openai } from '@tanstack/ai-openai';

export async function POST(request: Request) {
  const { messages, conversationId } = await request.json();

  const stream = chat({
    adapter: openai(),       // ← 适配器：可随时换为 `anthropic()` 或 `gemini()`
    messages,                // [{ role: 'user', content: '你好' }]
    model: 'gpt-4o',         // ← 类型安全：仅允许 OpenAI 支持的模型
    conversationId,          // ← 用于多轮会话追踪
    // providerOptions: { reasoning: { effort: 'medium' } } // ← OpenAI 特有参数，TS 自动提示
  });

  return toStreamResponse(stream); // 自动设置 `Content-Type: text/event-stream`
}

✅ chat() 返回 AsyncIterable 流，天然支持 SSE（Server-Sent Events）；
✅ toStreamResponse() 封装了流式响应头与序列化逻辑，无需手动拼接 data:。

---

2️⃣ 客户端：React 中使用 useChat

// components/Chat.tsx
import { useChat, fetchServerSentEvents } from '@tanstack/ai-react';
import { useState } from 'react';

export function Chat() {
  const [input, setInput] = useState('');
  
  const { messages, sendMessage, isLoading } = useChat({
    connection: fetchServerSentEvents('/api/chat'), // ← 自动处理 SSE 协议
  });

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    if (input.trim() && !isLoading) {
      sendMessage(input); // 乐观更新：先本地加消息，再发请求
      setInput('');
    }
  };

  return (
    <div>
      {/* 渲染消息流（支持流式更新） */}
      {messages.map(msg => (
        <div key={msg.id}>
          <strong>{msg.role === 'assistant' ? '🤖 AI:' : '👤 You:'}</strong>
          <p>{msg.content}</p>
        </div>
      ))}

      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={e => setInput(e.target.value)}
          placeholder="Ask anything..."
          disabled={isLoading}
        />
        <button type="submit" disabled={isLoading}>
          {isLoading ? ' Thinking...' : 'Send'}
        </button>
      </form>
    </div>
  );
}

✨ 亮点：

• messages 自动更新（含流式 partial content）；
• isLoading 状态管理；
• 乐观 UI（Optimistic UI）提升交互流畅度。

---

🔧 高级能力：工具调用（Function Calling）

LLM 的知识是静态的——如何让它“联网”？TanStack AI 提供了一套声明式 + 类型安全的工具调用方案。

步骤 1：用 Zod 定义工具 Schema（同构）

// lib/tools.ts
import { toolDefinition } from '@tanstack/ai';
import { z } from 'zod';

export const searchInternetDef = toolDefinition({
  name: 'search_internet',
  description: 'Search the internet for current information using Tavily.',
  inputSchema: z.object({
    query: z.string().describe('The search query.'),
    maxResults: z.number().optional().default(5),
  }),
});

✅ .describe() 为参数添加自然语言说明，极大提升模型调用准确率；
✅ Zod Schema 同时用于：
‣ 服务端入参校验
‣ 客户端类型推导
‣ 模型 prompt 中的工具描述生成

---

步骤 2：服务端实现工具逻辑（安全）

// lib/tools.ts (续)
export const searchInternet = searchInternetDef.server(
  async ({ query, maxResults }) => {
    // ← 类型已由 Zod 校验并推导！
    const res = await fetch('https://api.tavily.com/search', {
      method: 'POST',
      headers: { 
        'Authorization': `Bearer ${process.env.TAVILY_API_KEY}`,
        'Content-Type': 'application/json' 
      },
      body: JSON.stringify({ query, max_results: maxResults }),
    });
    return res.json();
  }
);

---

步骤 3：集成进 Chat 流程

服务端注册工具：

// pages/api/chat.ts (修改)
const stream = chat({
  adapter: openai(),
  messages,
  model: 'gpt-4o',
  tools: [searchInternet], // ← 注册服务端可执行工具
});

客户端声明工具（仅定义，不暴露逻辑）：

// components/Chat.tsx (修改)
const { messages, sendMessage } = useChat({
  connection: fetchServerSentEvents('/api/chat'),
  tools: [searchInternetDef], // ← 仅传递定义，类型安全 + 无密钥泄露风险
});

---

🔄 工具调用流程图解

🎯 全程自动编排，开发者只需专注 工具定义 + 实现。

---

📈 优势 vs 竞品（如 Vercel AI SDK）

维度	TanStack AI	Vercel AI SDK
类型安全	⭐⭐⭐⭐⭐ 深度 TS 集成，编译时拦截错误	⭐⭐ 有限类型提示
多厂商支持	⭐⭐⭐⭐ adapter 插件化，切换零成本	⭐⭐ 以 OpenAI 为中心，其他需额外封装
框架支持	⭐⭐⭐⭐ React/Solid/Vanilla + 规划 Svelte	⭐⭐⭐ 主打 React/Next.js
工具调用	⭐⭐⭐⭐ 声明式 Zod Schema + 同构	⭐⭐⭐ 需手动处理 useTools + 类型断言
开源协议	MIT（完全开放）	Apache 2.0（部分闭源高级功能？）

---

🔮 未来展望

• ✅ Alpha → Beta → Stable：核心 API 稳定中，文档持续完善；
• 🚧 Python / PHP 服务端运行时：跨语言统一开发体验；
• 🧩 Agent 框架：支持 Planning、Memory、Multi-Agent 协作；
• 🛡️ Tool Approval Flow：人工审核敏感工具调用（Human-in-the-Loop）；
• 🌐 Svelte / Vue 插件：扩大框架覆盖。

---

✅ 总结

TanStack AI 不是又一个 API 封装，而是一套面向未来的 AI 应用架构范式。

• 如果你追求 类型安全 与 开发体验，它可能是当前 TS 生态中最严谨的选择；
• 如果你担心 厂商锁定，它的适配器设计让你“随时可走”；
• 如果你正在构建 带工具调用的智能应用，它的 Zod + 同构方案大幅降低心智负担。

---