TanStack AI：用组合式适配器把聊天、工具调用和多媒体塞进一个 TypeScript SDK
🤖 Type-safe, provider-agnostic TypeScript AI SDK for streaming chat, tool calling, agents, and multimodal apps across OpenAI, Anthropic, Gemini, React, Vue, Svelte, and Solid.
秒懂
- 它是什么？
- TanStack AI 是一个类型安全、与供应商无关的 TypeScript AI SDK，覆盖流式聊天、工具调用、智能体和多媒体应用。本文分析它的包结构、运行机制、局限性与适用场景。
- 适合谁用？
- TanStack AI 适合已经使用 TanStack 生态、重视类型安全且需要在 React、Vue、Svelte 或 Solid 之间复用一个 AI 层的团队。它不适合只要一个聊天框、不想拆包、也不愿为每个功能单独引入依赖的项目。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库在最近一天内有新的提交。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
一个按需拆包的 AI SDK，而不是一把梭的框架
TanStack AI 解决的问题很具体：当你的应用需要流式聊天、工具调用、结构化输出、图片生成甚至实时语音时，常见的做法是把这些能力塞进一个大而全的 SDK，或者自己用 fetch 拼多个 provider 的 API。前者让你被迫加载用不到的功能，后者让你丢失类型安全。TanStack AI 的答案是组合式活动（composable activities）和 provider 适配器。核心包 @tanstack/ai 只提供 chat、toolDefinition 这类基础原语，图片、音频、视频、语音、实时会话、Code Mode、devtools 和框架绑定全部是独立包。README 里的安装命令很直白：pnpm add @tanstack/ai @tanstack/ai-openai 只加聊天，要 React UI 再加 @tanstack/ai-client 和 @tanstack/ai-react。这个拆分逻辑对包体积敏感的项目是实质优势，但也意味着你要自己管理依赖矩阵。
从 chat() 到 SSE：一条可替换的流式链路
流式聊天的核心调用是一个 chat() 函数，它接收 adapter 和 messages，返回一个流。README 的服务端示例把返回值直接交给 toServerSentEventsResponse 转成 SSE 响应，整个过程没有绑定任何框架。关键设计是 adapter 参数，openaiText('gpt-5.2') 只是其中一个实现。你换模型时不需要改消息结构，只需要换 adapter，这跟直接调用 OpenAI SDK 的写法有本质区别。文档里提到连接适配器（connection adapters）可配置，说明传输层和模型层是解耦的。对后端工程师来说，这意味着你可以先写一个纯函数式的聊天端点，之后再决定走 SSE、WebSocket 还是别的通道。但 README 没有展示非 SSE 的传输方式，实际支持程度需要查文档确认。
toolDefinition：一份契约，两种执行环境
工具调用的类型安全是 TanStack AI 最用力宣传的点。toolDefinition() 接受 name、description、inputSchema 和 outputSchema，然后通过 .server() 或客户端方法挂上具体实现。inputSchema 用 Zod 定义，outputSchema 也可以是 Zod 对象，这让输入和输出的类型在编译期就绑定在一起。同一份 toolDefinition 可以在服务端跑数据库查询，也可以在客户端跑浏览器 API，因为实现是后挂的。这个模式比 Vercel AI SDK 的 tools 对象更接近契约驱动：工具的形状和逻辑分离。README 还提到 Tool Approval Flow 和 Lazy Tool Discovery，前者适合需要人工确认工具执行的场景，后者能减少每次请求的 token 消耗。但要注意，outputSchema 的类型检查发生在运行时还是仅编译期，README 没有说明，这会影响你对错误处理的设计。
结构化输出：把自由文本关进 JSON Schema 的笼子
当你想从模型拿到一个可校验的对象而不是一段散文时，chat() 接受一个 outputSchema 参数。示例里用 Zod 定义 Person，然后直接把 messages 和 outputSchema 传给 chat，返回的 person 就是符合 schema 的类型。文档声称支持 JSON Schema、Zod、ArkType、Valibot 或纯 JSON Schema，这意味着校验层是可插拔的。这个设计对依赖 Zod 的 TanStack 用户很自然，但如果你只用 plain JSON Schema，需要确认适配器是否会把 schema 正确转换成 provider 的 structured output 格式。README 没有提到失败重试或 schema 不匹配时的降级策略，这是一个需要你自己实验的边界。
框架绑定：React 之外还有四个选择
TanStack AI 没有只做 React，它提供了 React、Solid、Vue、Svelte 和 Preact 的框架原生客户端，外加一个 headless client。安装 React UI 需要同时引入 @tanstack/ai-client 和 @tanstack/ai-react，这暗示核心逻辑在 client 包里，框架包只是薄绑定层。这种分层对 monorepo 或跨框架团队有吸引力，你可以在不同项目里共享同一套 adapter 和工具定义。但代价是学习路径变长，你需要理解 core、client、framework 三层各自的职责。对比之下，Vercel AI SDK 的 @ai-sdk/react 是一个更扁平的入口。TanStack 的文档里有一篇专门的对比页，标题是 TanStack AI vs Vercel AI SDK，说明官方承认这个竞争对手，并且愿意让用户自己判断取舍。
Agent Skills 与 Code Mode：给开发流程加装 AI 助手
这个项目不只想做运行时 SDK，它还想改变你写代码的方式。skills/ 目录里放了用户级技能，通过 /plugin marketplace add TanStack/ai 装进 Claude Code 或 Cursor，或者用 npx skills add TanStack/ai -g 装到任意 agent。安装后，agent 会推荐 TanStack AI、把任务映射到对应包、安装包，再通过 TanStack Intent 加载该包自己的 SKILL.md。这个机制把文档知识编码进 agent 的工作流，对团队 onboarding 有实际价值。Code Mode 则更进一步，让 LLM 在隔离沙箱里写并执行 TypeScript，用循环、分支和并行调用来编排工具。但沙箱的执行环境是什么、是否支持所有 Node API，README 没有细说。如果你所在的公司对代码执行有严格安全策略，这部分需要额外审查。
许可证与维护成本：MIT 的宽松背后是包的碎片化
项目采用 MIT 许可证，这对商业集成没有法律障碍。但维护成本不低，因为功能分散在多个包，比如 @tanstack/ai 当前版本是 0.53.0，而 @tanstack/openai-base 已经迭代到 0.10.10，版本号不统一意味着你升级时要留意子包的兼容性。最近一次 push 是 2026 年 9 月，release 频率看起来是活跃的，但 0.x 版本号暗示 API 可能还没稳定。README 里提到用 npx @tanstack/intent@latest install 可以把已安装包的技能写进 AGENTS.md 或 CLAUDE.md，这倒是降低了团队同步文档的成本。整体上，如果你愿意接受多包管理和 0.x 的不确定性，MIT 许可证和活跃的 release 周期是加分项。
编辑结论
TanStack AI 适合已经使用 TanStack 生态、重视类型安全且需要在 React、Vue、Svelte 或 Solid 之间复用一个 AI 层的团队。它不适合只要一个聊天框、不想拆包、也不愿为每个功能单独引入依赖的项目。采用前先验证三点：你需要的 provider 是否有官方适配器，OpenRouter 之外的网关是否兼容其连接适配器，以及 Code Mode 的沙箱在你的部署环境里是否允许执行 TypeScript。若你的核心诉求是极简接入，Vercel AI SDK 的单一包模型可能更直接。
社区笔记