TanStack AI + Effect 4:官方适配器详解(0.1.0)

TanStack AI 发布官方 Effect 4 适配器 @tanstack/ai-effect 0.1.0:AI.chat 返回类型化 Effect Stream,错误经类型化,客户端断开时中断会中止模型请求。涵盖安装、服务端路由与客户端接线,专为服务端已用 Effect 4 的 TypeScript 团队设计。

Huifer
Huifer
November 7, 20268 min read
其他语言:Deutsch · English

本文由 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 依赖:

bash
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.061.4 kB18
@tanstack/ai 1.2.05737.3 kB644
@tanstack/ai-openai 1.1.1989.9 kB182
@tanstack/ai-react 1.0.2491.0 kB99
effect 4.1.255264.1 kB3013

适配器本身是该集合中最小的包,61.4 kB、18 个文件。effect 是沉重的 peer 依赖,解压后 55264.1 kB,但 tree-shaking 与仅服务端的打包让它在客户端 bundle 中完全消失——官方客户端示例交付的是搭配 useChat 的纯 React。

从你的 Effect 服务端路由流式输出聊天

官方集成分三步:第一步,安装相关包;第二步,从你的服务端路由流式输出聊天;第三步,在客户端展示聊天。官方文档的服务端示例足够小,可以完整复现:

ts
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 把 Effect Stream 转回 toServerSentEventsResponse 所读取的 async iterable,从而 SSE 传输层保持不变。
  • 中断已接好:浏览器关闭请求 → 流停止 → 模型请求被中止。

在客户端展示聊天——无需 Effect

客户端保持纯 React。@tanstack/ai-react 中的 useChat 读取 Server-Sent Events:

tsx
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 组合:

ts
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 教程——官方文档中一份完整的、循序渐进的应用构建教程。

决策框架:采用前的三个问题

  1. 你的服务端现在是否引入了 effect? 如果是,适配器是严格增量式的:与核心 chat() 相同的选项,类型化地接入你既有的错误通道。如果不是,单纯为了 AI 调用而引入 Effect 是一个你并不需要的运行时依赖;核心 chat() 已覆盖相同的功能。
  2. 你是否需要中断的正确性? 带有付费模型调用的长 agent 循环,在客户端断开导致供应商请求仍在运行时,会白白泄漏金钱。适配器在下游断开时中止上游;而手写的 async iterable 需要你自己接好这条链路。
  3. 你的客户端是 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-effect0.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 之前,但它被文档作为一等公民的接口面(独立的文档章节、教程、示例)而非实验性附加项来覆盖。在升级前请锁定版本并阅读更新日志。

延伸阅读