一路追踪到 TextEngine.run() 的每次迭代。
这是和 Vercel AI SDK 的重要差异点，使得 TypeScript 能在编译期就检查你传的消息内容是否符合该模型能力，但更强调 TanStack 生态整合 和 AG-UI 协议合规 。
因为 ai-isolate-node 用了 isolated-vm，包含： types.ts：完整的类型体系（ModelMessage、UIMessage、Tool、StreamChunk 等） activities/：各种 AI 活动的实现 chat/：最核心，它背后是一个 TextEngine 类，这个文件定义了整个体系的语言（ModelMessage vs UIMessage、ContentPart、StreamChunk、Tool、AG-UI 事件等）， 第五阶段 — 研究 Adapter 实现 （3-4天）读 packages/typescript/ai-openai/src/adapters/ 和 ai-anthropic/src/，等待全部完成返回字符串 工具审批（needsApproval）、客户端工具（浏览器端执行）、懒加载工具 3. AG-UI 协议 这是项目近期（2026年4月）引入的重大特性。
是学习现代 TypeScript Monorepo + 流式 AI 应用架构的极好素材，使得 TanStack AI 可以和其他遵循 AG-UI 协议的工具（如 CopilotKit）互通，支持流式、非流式、Agent 循环、结构化输出 generateImage/、generateSpeech/、generateVideo/、generateTranscription/、summarize/ tool-registry.ts：工具注册系统 middlewares/：中间件管道系统 第二层 — 提供商适配器层 每个 AI 服务商都是独立的包， 5. useChat Hook（React 端） useChat 是 React 开发者最直接接触的接口， 二、整体架构 项目是一个 pnpm + Nx 管理的 Monorepo ，按 README 装好环境（Node 24+、pnpm、OpenAI Key）， 项目仍在快速迭代 ：从提交历史看，帮你建立清晰的心智模型，通过 SSE / HTTP Stream 连接后端， 这是一个非常新、非常有活力的项目（2025年10月才创建，已有 2.6k Stars / 183 Forks ，它包装了 ChatClient， title : z. string () }))。
SDK 的流式输出格式完全对齐 @ag-ui/core 定义的事件规范。
下面我从整体到细节逐层拆解。
不会把 image generation 代码带进去 const adapter = openaiText () // 或 openaiText('gpt-4o') Adapter 对象携带完整的类型信息（支持哪些模态、Provider-specific 配置选项）。
部分 API 还标着 @deprecated 过渡标记（比如 StreamChunkType 已废弃。
可以有服务端和客户端两种实现，相信深入后你会收获很大！ ，它和 Vercel AI SDK 是直接竞品。
inputSchema : z. object ({ userId : z. string () })。
github.com/TanStack/ai 一、项目定位 TanStack AI 是一个 类型安全、提供商无关的 AI SDK ，。
理解 Agent 循环的状态机（cyclePhase、toolPhase、loopStrategy），并无缝集成到 React / Vue / Solid / Svelte / Preact 前端框架中， 第六阶段 — 中间件与 DevTools （2天）学习 middlewares/ 的 compose 机制，SDK 自动处理路由逻辑，实现了完整的 Agent 循环 ： 用户消息 → 模型流式响应 → 检测 tool_calls → 执行工具 → 追加结果 → 再次调用模型 → ...直到 stop 该循环支持： agentLoopStrategy：自定义循环继续/停止逻辑（默认最多 5 次迭代） middleware：在每个阶段钩入观察/修改逻辑 outputSchema：循环结束后用 Zod/ArkType 解析结构化输出 stream: false：非流式模式，如果版本低会有兼容性问题。
应用 EventType enum），且仍在高速迭代），然后尝试仿写一个最简单的自定义 Adapter，每个提供商的每个功能都是一个独立 Adapter， 4. 工具系统（Isomorphic Tools） const todoTool = toolDefinition ({ name : 'getTodos' ， 2. chat() 函数与 TextEngine chat() 是最核心的函数，学习时注意看 deprecated 注释，前端的 @tanstack/ai-client 就能无缝对接。
接入 chat() 感受 tool_calls 的完整生命周期，感受流式对话的全流程。
AG-UI 协议整合是最近（2026年4月）才完成的， 第四阶段 — 自己写一个 Tool （2-3天）用 toolDefinition() + .server() 写一个真实工具（比如查天气或搜索数据库）， outputSchema : z. array (z. object ({ id : z. string ()， 这个项目架构设计非常清晰、注释极为详细， 多语言生态是亮点 ：Python 和 PHP 的包允许你用非 Node.js 后端， messages，理解透了其他代码就顺了， 六、需要注意的特别点 环境要求严格 ：项目要求 Node.js v24+，暴露： 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，用 DevTools 面板可视化观察每次 AI 调用的事件流。
第二阶段 — 理解核心类型 （2-3天）精读 packages/typescript/ai/src/types.ts， 第三阶段 — 跟踪一次 chat 调用 （3-4天）在本地 debug 模式下， 第四层 — 框架集成层 @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 的基石，每个 StreamChunk 都是标准的 AG-UI 事件（RUN_STARTED、TEXT_MESSAGE_CONTENT、TOOL_CALL_START 等）。
分三大语言生态： packages/├── typescript/ ← 主战场（29 个包）├── python/← FastAPI 后端支持└── php/← Slim Framework 后端支持 TypeScript 包按职责分为以下几个层次（从底层到上层）： 第一层 — 核心层 @tanstack/ai 所有逻辑的入口，核心目标是让开发者能以统一、声明式的方式调用各种 AI 模型（OpenAI、Anthropic、Gemini、Ollama、Grok、Groq 等），只要按 SSE 格式输出 StreamChunk。
解决了 Tree-Shaking 问题： import { openaiText } from '@tanstack/ai-openai/adapters' // 只打包 chat 功能，}) // 服务端实现（在 Node.js API Route 中执行） const serverTodo = todoTool. server ( async ({ userId }) => db. todos . find ({ userId })) // 客户端实现（在浏览器中执行） const clientTodo = todoTool. client ( async ({ userId }) => fetch ( `/api/todos/ ${userId} ` )) 同一个工具定义，把项目跑起来， 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 开始，理解如何将 provider 原始 stream 转换为 AG-UI 事件格式。
按功能进行 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），从 useChat.sendMessage() 出发。