TanStack AI 仓库深度分析

王小酱
8 阅读5分钟

这是一个非常新、非常有活力的项目（2025年10月才创建，已有 2.6k Stars / 183 Forks，且仍在高速迭代），下面我从整体到细节逐层拆解，帮你建立清晰的心智模型。

github.com/TanStack/ai

一、项目定位

TanStack AI 是一个类型安全、提供商无关的 AI SDK，核心目标是让开发者能以统一、声明式的方式调用各种 AI 模型（OpenAI、Anthropic、Gemini、Ollama、Grok、Groq 等），并无缝集成到 React / Vue / Solid / Svelte / Preact 前端框架中。它和 Vercel AI SDK 是直接竞品，但更强调TanStack 生态整合和AG-UI 协议合规。

二、整体架构

项目是一个 pnpm + Nx 管理的 Monorepo，分三大语言生态：

packages/
├── typescript/   ← 主战场（29 个包）
├── python/       ← FastAPI 后端支持
└── php/          ← Slim Framework 后端支持

TypeScript 包按职责分为以下几个层次（从底层到上层）：

第一层 — 核心层 @tanstack/ai 所有逻辑的入口。包含：

  • types.ts：完整的类型体系（ModelMessage、UIMessage、Tool、StreamChunk 等）
  • activities/：各种 AI 活动的实现
    • chat/：最核心，支持流式、非流式、Agent 循环、结构化输出
    • generateImage/、generateSpeech/、generateVideo/、generateTranscription/、summarize/
  • tool-registry.ts：工具注册系统
  • middlewares/：中间件管道系统

第二层 — 提供商适配器层 每个 AI 服务商都是独立的包，按功能进行 Tree-Shaking：

  • @tanstack/ai-openai → openaiText、openaiEmbed、openaiImage 等
  • @tanstack/ai-anthropic → anthropicText 等
  • @tanstack/ai-gemini、@tanstack/ai-grok、@tanstack/ai-groq、@tanstack/ai-ollama、@tanstack/ai-openrouter、@tanstack/ai-fal、@tanstack/ai-elevenlabs

第三层 — 客户端无头状态层 @tanstack/ai-client 框架无关的聊天状态管理引擎（ChatClient），通过 SSE / HTTP Stream 连接后端。

第四层 — 框架集成层

  • @tanstack/ai-react → useChat、useGenerateImage、useSummarize 等 Hooks
  • @tanstack/ai-vue、@tanstack/ai-solid、@tanstack/ai-svelte、@tanstack/ai-preact

第五层 — UI 组件层

  • @tanstack/ai-react-ui、@tanstack/ai-vue-ui、@tanstack/ai-solid-ui — 开箱即用的聊天界面组件

第六层 — DevTools 层

  • @tanstack/ai-devtools + react-ai-devtools、solid-ai-devtools — 调试面板

隔离执行层（安全沙箱）

  • ai-isolate-node、ai-isolate-cloudflare、ai-isolate-quickjs — 用于在沙箱中安全执行 AI 生成的代码

三、最关键的核心概念拆解

1. Adapter（适配器）系统

这是整个 SDK 的基石。每个提供商的每个功能都是一个独立 Adapter，解决了 Tree-Shaking 问题：

import { openaiText } from '@tanstack/ai-openai/adapters'
// 只打包 chat 功能，不会把 image generation 代码带进去
const adapter = openaiText()  // 或 openaiText('gpt-4o')

Adapter 对象携带完整的类型信息（支持哪些模态、Provider-specific 配置选项），使得 TypeScript 能在编译期就检查你传的消息内容是否符合该模型能力。

2. chat() 函数与 TextEngine

chat() 是最核心的函数，它背后是一个 TextEngine 类，实现了完整的 Agent 循环：

用户消息 → 模型流式响应 → 检测 tool_calls → 执行工具 → 追加结果 → 再次调用模型 → ...直到 stop

该循环支持：

  • agentLoopStrategy：自定义循环继续/停止逻辑（默认最多 5 次迭代）
  • middleware：在每个阶段钩入观察/修改逻辑
  • outputSchema：循环结束后用 Zod/ArkType 解析结构化输出
  • stream: false：非流式模式，等待全部完成返回字符串
  • 工具审批（needsApproval）、客户端工具（浏览器端执行）、懒加载工具

3. AG-UI 协议

这是项目近期（2026年4月）引入的重大特性。SDK 的流式输出格式完全对齐 @ag-ui/core 定义的事件规范，每个 StreamChunk 都是标准的 AG-UI 事件（RUN_STARTED、TEXT_MESSAGE_CONTENT、TOOL_CALL_START 等），使得 TanStack AI 可以和其他遵循 AG-UI 协议的工具（如 CopilotKit）互通。

4. 工具系统（Isomorphic Tools）

const todoTool = toolDefinition({
  name: 'getTodos',
  inputSchema: z.object({ userId: z.string() }),
  outputSchema: z.array(z.object({ id: z.string(), title: z.string() })),
})

// 服务端实现（在 Node.js API Route 中执行）
const serverTodo = todoTool.server(async ({ userId }) => db.todos.find({ userId }))

// 客户端实现（在浏览器中执行）
const clientTodo = todoTool.client(async ({ userId }) => fetch(`/api/todos/${userId}`))

同一个工具定义，可以有服务端和客户端两种实现，SDK 自动处理路由逻辑。

5. useChat Hook（React 端）

useChat 是 React 开发者最直接接触的接口，它包装了 ChatClient，暴露：

  • messages：当前会话消息（UIMessage[]）
  • sendMessage、append、reload、stop、clear
  • isLoading、error、status、connectionStatus
  • addToolResult：客户端工具执行完成后提交结果
  • addToolApprovalResponse：用户审批工具调用

四、数据流全景图

[React useChat]
     ↓ sendMessage()
[ChatClient @tanstack/ai-client]  ← 通过 SSE/HTTP 连接
     ↓ POST /api/chat
[Server Route (TanStack Start)]
     ↓ chat({ adapter, messages, tools })
[TextEngine in @tanstack/ai]
     ↓
[Provider Adapter (e.g. openaiText)]
     ↓ OpenAI SDK streaming
[AI Provider (OpenAI/Anthropic/etc.)]
     ↑ stream chunks (AG-UI events)
[Middleware Pipeline] → 流式返回 SSE
     ↑
[ChatClient] → 解析 StreamChunk → 更新 UIMessage
     ↑
[useChat] → React 重渲染 → 界面更新

五、你的学习路线建议

第一阶段 — 跑通 Demo（1-2天） 从 examples/ts-react-chat 开始，按 README 装好环境（Node 24+、pnpm、OpenAI Key），把项目跑起来，感受流式对话的全流程。

第二阶段 — 理解核心类型（2-3天） 精读 packages/typescript/ai/src/types.ts，这个文件定义了整个体系的语言（ModelMessage vs UIMessage、ContentPart、StreamChunk、Tool、AG-UI 事件等），理解透了其他代码就顺了。

第三阶段 — 跟踪一次 chat 调用（3-4天） 在本地 debug 模式下，从 useChat.sendMessage() 出发，一路追踪到 TextEngine.run() 的每次迭代，理解 Agent 循环的状态机（cyclePhase、toolPhase、loopStrategy）。

第四阶段 — 自己写一个 Tool（2-3天） 用 toolDefinition() + .server() 写一个真实工具（比如查天气或搜索数据库），接入 chat() 感受 tool_calls 的完整生命周期。

第五阶段 — 研究 Adapter 实现（3-4天） 读 packages/typescript/ai-openai/src/adapters/ 和 ai-anthropic/src/，理解如何将 provider 原始 stream 转换为 AG-UI 事件格式，然后尝试仿写一个最简单的自定义 Adapter。

第六阶段 — 中间件与 DevTools（2天） 学习 middlewares/ 的 compose 机制，用 DevTools 面板可视化观察每次 AI 调用的事件流。

六、需要注意的特别点

环境要求严格：项目要求 Node.js v24+，因为 ai-isolate-node 用了 isolated-vm，如果版本低会有兼容性问题。

项目仍在快速迭代：从提交历史看，AG-UI 协议整合是最近（2026年4月）才完成的，部分 API 还标着 @deprecated 过渡标记（比如 StreamChunkType 已废弃，应用 EventType enum），学习时注意看 deprecated 注释。

多语言生态是亮点：Python 和 PHP 的包允许你用非 Node.js 后端，只要按 SSE 格式输出 StreamChunk，前端的 @tanstack/ai-client 就能无缝对接，这是和 Vercel AI SDK 的重要差异点。

这个项目架构设计非常清晰、注释极为详细，是学习现代 TypeScript Monorepo + 流式 AI 应用架构的极好素材，相信深入后你会收获很大！

avatar
文章
阅读
粉丝