本文由 Huifer 撰写,TanStack Ship(一个生产级的 TanStack Start + Cloudflare Workers SaaS 起步模板)的独立开发者与维护者。我在基于 TanStack Start 构建的生产级 SaaS 应用中运行流式聊天与工具调用型 agent,并亲身经历过无类型流式 SDK 的那些失败模式——静默吞掉错误、客户端断开后残留的模型请求,以及事后才补上去的重试逻辑。本指南拆解
@tanstack/ai-effect,它是 TanStack AI 的一个官方(first-party)Effect 4 绑定:AI.chat返回类型化的Stream,每个活动都以 Effect 或 Stream 形式运行。本文内容仅基于官方文档与已发布的包元数据。已核实来源:TanStack AI Effect 文档 · @tanstack/ai-effect on npm · TanStack AI 文档 · Effect 4 文档 · TanStack AI 仓库 · TanStack Ship features
最后更新:2026-11-07 · 更新日志
TanStack AI + Effect 4:官方适配器详解
TanStack AI 现已为你的 AI 应用提供官方的(first-party)Effect 适配器。如果你在 Effect 4 服务端上构建流式聊天,这篇指南就是为你准备的——你再也不必在 effect 运行时和 AI SDK 之间二选一。@tanstack/ai-effect(发布于 2026-11-06,当前为 0.1.0)就是一个官方 Effect 适配器。官方 README 的一句话定位是:为 TanStack AI 提供 Effect 4 绑定——每个活动都是 Effect 或 Stream,外加 Effect 服务端工具。 如果你的服务端代码是用 Effect 4 编写的,你就不必再在 effect 运行时和 TanStack 的 AI SDK 之间做取舍。
TL;DR(面向在服务端运行 Effect 4 的 TypeScript 团队):
@tanstack/ai-effect是 TanStack AI 的官方 Effect 4 绑定。核心的chat()返回 async iterable 并抛出普通错误,无法在 Effect 程序中组合。@tanstack/ai-effect中的AI.chat改而返回Stream<StreamChunk, AIError>——带类型错误、Stream组合子,且中断能真正中止模型请求。安装@tanstack/ai @tanstack/ai-effect @tanstack/ai-openai @tanstack/ai-react effect,用Stream.toAsyncIterable包裹你的服务端路由,客户端保持useChat不变。
它是什么: @tanstack/ai-effect 是 TanStack AI SDK 的官方 Effect 4 绑定,于 2026-11-06 以 0.1.0 发布。本指南面向服务端层已经在运行 Effect 4、并希望把流式聊天、工具调用和结构化输出类型化接入其 Effect 错误通道的 TypeScript 团队。一句话如何决策: 如果你的服务端现在引入了 effect,就采用适配器;如果没有,核心 chat() 更简单。本指南涵盖安装、服务端路由、客户端接线,以及采用决策;供应商侧定价与提示工程不在范围内。
为什么需要单独的适配器包
先交代一点背景:TanStack AI 于 2026 年进入 RC 阶段,以 "Still Your AI, Still Your Way" 发布达到 1.0,自 2026 年以来快速迭代——1.1.0 于 2026-11-05 发布,1.2.0 紧随其后几天内推出。Effect 适配器是最新的接口面:npm 记录到它的前三次发布(0.0.0-stage、0.0.0、0.1.0)全部集中在 2026-11-06 的一个 19 分钟窗口内,文档站点也在同一天新增了 Effect 章节。
@tanstack/ai 中的核心 chat() 函数从设计上就是运行时无关的:它返回分块的 async iterable 并抛出普通的 Error。对于纯 TypeScript 服务端,这是正确的默认值,但它破坏了 Effect 程序在意的两条契约:
- 错误无类型。 在 Effect 中,错误存在于通道类型中(
Stream<Chunk, Error>)。抛出的错误会逃出你类型化的错误流程,落到包裹该 fiber 的某处通用 catch-all 中。 - 缺少结构化中断。 Effect 通过 fiber 管理中断。async iterable 在 fiber 被中断时并不知道如何取消一个正在进行的模型请求——与供应商的连接就此泄漏。
@tanstack/ai-effect 修复了这两点。AI.chat 返回 Stream<StreamChunk, AIError>,并且据官方文档:"如果浏览器关闭请求,流会停止。随后 AI.chat 会中止对模型的请求。" 最后这部分是真正关键的生产细节——除非适配器把链路接好,否则中止下游 SSE 不会让上游任何东西被中止,而本适配器确实接好了。
安装
该包需要 Effect 4(effect 4.1 或更高版本)以及 @tanstack/ai 1.2.0+ 作为 peer 依赖:
npm i @tanstack/ai @tanstack/ai-effect @tanstack/ai-openai @tanstack/ai-react effect
注意,@tanstack/ai-effect 声明了零运行时依赖——effect 和 @tanstack/ai 是 peer 依赖,所以由你的 lockfile 控制版本。
安装体积,依据 npm registry 实测(解压后大小,当前最新版本):
| 包 | 解压后大小 | 文件数 |
|---|---|---|
@tanstack/ai-effect 0.1.0 | 61.4 kB | 18 |
@tanstack/ai 1.2.0 | 5737.3 kB | 644 |
@tanstack/ai-openai 1.1.1 | 989.9 kB | 182 |
@tanstack/ai-react 1.0.2 | 491.0 kB | 99 |
effect 4.1.2 | 55264.1 kB | 3013 |
适配器本身是该集合中最小的包,61.4 kB、18 个文件。effect 是沉重的 peer 依赖,解压后 55264.1 kB,但 tree-shaking 与仅服务端的打包让它在客户端 bundle 中完全消失——官方客户端示例交付的是搭配 useChat 的纯 React。
从你的 Effect 服务端路由流式输出聊天
官方集成分三步:第一步,安装相关包;第二步,从你的服务端路由流式输出聊天;第三步,在客户端展示聊天。官方文档的服务端示例足够小,可以完整复现:
import { chatParamsFromRequest, toServerSentEventsResponse } from '@tanstack/ai'
import * as AI from '@tanstack/ai-effect'
import { openaiText } from '@tanstack/ai-openai'
import { Stream } from 'effect'
export async function POST(request: Request) {
const params = await chatParamsFromRequest(request)
const stream = AI.chat({
adapter: openaiText('gpt-6.1-sol'),
messages: params.messages,
threadId: params.threadId,
runId: params.runId,
})
return toServerSentEventsResponse(Stream.toAsyncIterable(stream))
}
三部分,各司其职:
AI.chat接受的选项与核心chat()相同——相同的适配器、相同的消息、相同的 thread/run ID。它返回Stream<StreamChunk, AIError>。Stream.toAsyncIterable把 EffectStream转回toServerSentEventsResponse所读取的 async iterable,从而 SSE 传输层保持不变。- 中断已接好:浏览器关闭请求 → 流停止 → 模型请求被中止。
在客户端展示聊天——无需 Effect
客户端保持纯 React。@tanstack/ai-react 中的 useChat 读取 Server-Sent Events:
import { useState } from 'react'
import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
export function Chat() {
const [input, setInput] = useState('')
const { messages, sendMessage, isLoading } = useChat({
connection: fetchServerSentEvents('/api/chat'),
threadId: 'effect-chat',
})
return (
<div>
{messages.map((message) => (
<p key={message.id}>
{message.role}: {message.parts.map((part) =>
part.type === 'text' ? part.content : null)}
</p>
))}
<form onSubmit={(event) => { event.preventDefault(); sendMessage(input); setInput('') }}>
<input value={input} onChange={(event) => setInput(event.target.value)} />
<button type="submit" disabled={isLoading}>Send</button>
</form>
</div>
)
}
这个边界是刻意的:Effect 存在于服务端,客户端消费纯 SSE。你不会为了一个聊天界面而把 effect 发往浏览器。部署方面,该路由使用 Web 标准的 Request/Response,因此可以在 Cloudflare Workers 上原样运行;在 TanStack Start 中,如果你更喜欢那种形态,也可以把同一处理器表达为 Server Function。
把整条回复作为 Effect 获取
如果你不需要逐 token 流式输出,传入 stream: false。AI.chat 随后返回一个 { text, chunks } 的 Effect,可与 Effect.gen 组合:
import * as AI from '@tanstack/ai-effect'
import { openaiText } from '@tanstack/ai-openai'
import { Effect } from 'effect'
const program = Effect.gen(function* () {
const { text } = yield* AI.chat({
adapter: openaiText('gpt-6.1-sol'),
messages: [{ role: 'user', content: 'Write a haiku about rivers.' }],
threadId: 'haiku',
stream: false,
})
return text
})
const haiku = await Effect.runPromise(program)
配合 outputSchema,同一个调用返回解析后结构化对象的 Effect——与核心 SDK 的结构化输出相同的 schema 选项。
适配器中还包含什么
除了 AI.chat,官方文档还列出了另外三个接口面,全部遵循同样的"每个活动都是 Effect 或 Stream"规则:
- Effect 工具——让你的 AI 工具获得 Effect 服务,从而使工具执行继承你的依赖注入与错误通道。
- Effect 活动——把图像、嵌入和语音作为 Effect 运行。
- Effect Chat 教程——官方文档中一份完整的、循序渐进的应用构建教程。
决策框架:采用前的三个问题
- 你的服务端现在是否引入了
effect? 如果是,适配器是严格增量式的:与核心chat()相同的选项,类型化地接入你既有的错误通道。如果不是,单纯为了 AI 调用而引入 Effect 是一个你并不需要的运行时依赖;核心chat()已覆盖相同的功能。 - 你是否需要中断的正确性? 带有付费模型调用的长 agent 循环,在客户端断开导致供应商请求仍在运行时,会白白泄漏金钱。适配器在下游断开时中止上游;而手写的 async iterable 需要你自己接好这条链路。
- 你的客户端是 React 吗? 官方的客户端契约是
useChat加上来自@tanstack/ai-react的 SSE。非 React 客户端消费的是同一个 SSE 流,但你需要自己重写那个 hook。
采用前后:你的代码发生了哪些变化
以官方示例为基准,标准 TanStack Start 服务端路由上的 diff:
| 维度 | 核心 chat()(前) | AI.chat(后) |
|---|---|---|
| 返回类型 | AsyncIterable<StreamChunk> | Stream<StreamChunk, AIError> |
| 错误 | 抛出普通 Error,被通用捕获 | 通道中的类型化 AIError |
| 客户端断开 | 除非你接好,否则请求继续 | 中止模型请求 |
| 可组合性 | 手工 async-iterable 组合子 | Stream 模块组合子 |
| 路由形态 | 经 toServerSentEventsResponse 的 SSE 路由 | 完全一致 |
路由形态不会改变,而这正是关键:改变的是流经其中的值的类型。
方法与局限
本文一切内容均来自官方的 Effect 文档页、0.1.0 已发布的 npm 元数据,以及 GitHub 仓库,每一项都已在上文链接。我尚未在生产环境中运行过这个适配器;采用前后的对照表比较的是文档化的契约,而非实测延迟。需要权衡的局限:该包为 0.1.0,诞生仅数日,尚处 1.0 之前,API 可能变化;文档覆盖的是客户端 React,因此非 React 客户端属于未文档化的领域;而采用 Effect 4 本身是一项团队层面的承诺,本文不做评估。对于重度依赖工具的 agent,主要的注意点是:文档把 Effect 工具和 Effect 活动列为受支持的接口面,但在 0.1.0 阶段,在把生产发布押注于其上之前,你应该对照官方 Effect Chat 教程,逐一核实你所依赖的每个工具模式。
版本与兼容性事实
| 包 | 版本 | 说明 |
|---|---|---|
@tanstack/ai-effect | 0.1.0 | 发布于 2026-11-06;零运行时依赖 |
effect | ≥ 4.1.0(peer) | 需要 Effect 4 |
@tanstack/ai | ≥ 1.2.0(peer) | 当前稳定版为 1.2.0 |
@tanstack/ai-openai | — | 文档中使用的供应商适配器 |
@tanstack/ai-react | — | 客户端 useChat / SSE 传输 |
当前状态:0.1.0,诞生仅数日,1.0 之前 API 可能变化。文档已经把它作为一等公民般的接口面来覆盖,这正是它不是实验性功能的信号——文档站点在该包发布的同一天,新增了一整个 Effect 章节、一份 Effect Chat 教程,以及 Effect 示例。
你应当(以及不应当)采用它的时机
应当在以下情况采用它: 你的服务端已经是 Effect 4——适配器消除了阻抗失配,而不需要你手工包裹 chat();你需要在错误通道中获得类型化的 AIError,而非抛出的错误;中断的正确性很重要(长时间运行的 agent 循环中,泄漏的供应商请求会实打实地烧钱)。
应当在以下情况跳过它: 你的服务端是不带 Effect 的纯 TypeScript——核心 chat() 已经用更少的移动部件给了你 async iterable 和 SSE 传输;或者你的客户端是非 React,而你只需要 SSE 契约,适配器对此并无改变。
对于构建在 TanStack Start 上的 SaaS,有趣的中间地带是服务端 agent:在 Effect 中以类型化重试进入通道的工具调用循环,通过与其他 TanStack AI 应用相同的 useChat 契约暴露给 React 客户端。
常见问题
客户端也需要 Effect 吗?
不需要。官方示例客户端是搭配 useChat 读取 Server-Sent Events 的纯 React。Effect 运行时留在服务端。
需要哪个 Effect 版本?
Effect 4——具体是 effect 4.1.0 或更高版本,作为 peer 依赖与 @tanstack/ai 1.2.0+ 一并声明。
中断真的会取消模型请求吗?
会,据官方文档:当浏览器关闭请求时流会停止,随后 AI.chat 会中止对模型的请求。
我能拿到单个解析后的对象而非流吗?
能。传入 stream: false 以获取 { text, chunks } 的 Effect,或使用 outputSchema 以获取解析后结构化输出的 Effect。
0.1.0 是否可用于生产?
它诞生仅数日且处于 1.0 之前,但它被文档作为一等公民的接口面(独立的文档章节、教程、示例)而非实验性附加项来覆盖。在升级前请锁定版本并阅读更新日志。
延伸阅读
- TanStack AI 1.2.0 发布指南——本适配器所绑定的 SDK。
- 最佳 SaaS 起步模板 2026——如果你在评估是否基于 TanStack Ship 构建,而非手工接好 AI 集成。
- TanStack Ship 模板——已接好计费、认证与 i18n 的生产级起步项目。