本文由 Huifer 撰写,他是 TanStack Ship 的独立开发者兼维护者。当 npm 在 2026-11-05 把
@tanstack/ai的latestdist-tag 切换过去时,我做了自己在模板里处理每一次依赖升级时都会做的事:把 1.0.1 和 1.1.0 两个已发布的 tarball 都拉下来,直接 diff 随包发布的类型声明,而不是相信一段 changelog 摘要。这份 diff 是本指南的骨架,也改变了我对这次发布的预期。已验证来源:TanStack · TanStack AI 文档 · npm 上的
@tanstack/ai1.1.0 · GitHub 上的 TanStack AI · web.dev · Cloudflare Workers 文档最后更新:2026-11-05 · 更新日志
@tanstack/ai 1.1.0 是 TanStack 那款类型安全的 TypeScript AI SDK 当前的 latest 版本。 npm 在 2026-11-04T14:01:38Z 发布了它,latest dist-tag 于 2026-11-05 完成切换。它是从 1.0.1(2026-10-29)升级而来的次版本号(minor),因此 semver 要求它保持向后兼容。发布的 README 与 1.0.1 完全一致,只有两处赞助商 logo 的 URL 不同,所以真正有价值的 diff 在代码里——而且它喊出了一件很明确的事:取消(cancellation)现在会端到端地传递下去,从调用方一路传到 MCP 工具发现、生成活动、realtime token 铸造、文件上传和视频任务。
TL;DR
- 实测:
@tanstack/ai1.1.0 于2026-11-04T14:01:38Z发布到 npm;latestdist-tag 于 2026-11-05 切换(来源:npm registry 记录)。- 实测:
13:58:44Z到14:02:01Z之间共发布了 12 个@tanstack/ai*包——一个 3 分 17 秒的发布窗口。- 推算: 已发布 tarball 中的 644 个文件里有 65 个发生变化——大约占整个包的 10%。
- 实测: README 除两处赞助商图片 URL 外逐字节相同。文档没变,代码变了。
- 实测: API 新增的部分全部围绕取消展开——生成活动上的
abortSignal与timeout,MCP 工具发现上的signal,realtime token 与 connect 调用上的abortSignal。- 我的判断: 升级风险低,但请在同一个 commit 里升级整个
@tanstack/ai*家族,因为适配器与核心是分开发布的。
简短回答:
@tanstack/ai1.1.0 是 TanStack 的类型安全 AI SDK,于 2026-11-04 以latest标签发布到 npm,接替 1.0.1。它可度量的变化是取消机制的打通:abortSignal和timeout现在会从 chat 中间件流向 MCP 发现、embeddings、realtime token、文件上传和视频任务。
TanStack AI 1.1.0:变更了什么与如何升级(2026)
本指南写给两类人:一是已经把 AI 功能交付到生产环境、如今在依赖审计里看到 @tanstack/ai@1.1.0 的开发者;二是正在决定 AI 层应该放在哪里的创始人。如果你还在挑选起点,直接跳到这次发布支撑的是 AI SaaS 模板的哪一项能力。
下面所有内容都是对照那两个已发布的 npm tarball 和注册表元数据逐项核验出来的,因为这里大多数发布摘要写自一份在注册表数据里根本不存在的 changelog。
@tanstack/ai 1.1.0 实际发布了什么:经核验的记录
npm 记录能证明什么
1.1.0 的注册表条目就是权威产物。以下是它发布时的内容:
| 注册表字段 | @tanstack/ai@1.1.0 中的值 |
|---|---|
| 版本 | 1.1.0(前一版:1.0.1,发布于 2026-10-29) |
| 发布时间戳 | 2026-11-04T14:01:38.341Z |
| 描述 | "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation." |
| 许可证 | MIT |
| 引擎要求 | Node >=18 |
| 仓库 | git+https://github.com/TanStack/ai.git(目录 packages/ai) |
| 运行时依赖 | @ag-ui/core@1.0.0、@tanstack/ai-utils@^1.0.1、@tanstack/ai-event-client@^1.0.1、@cfworker/json-schema@^4.1.1、@standard-schema/spec@^1.1.0、fast-json-patch@^3.1.1、partial-json@^0.1.7 |
| peer 依赖 | @opentelemetry/api >= 1.9.0(可选) |
| 导出子路径 | .、./byok、./locks、./client、./testing、./adapters、./byok/server、./middlewares、./middlewares/otel、./adapter-internals |
| 包体积 | 644 个已发布文件;sideEffects: false |
其中两行对升级决策最关键。唯一发生变化的依赖范围是两个内部 TanStack 包——@tanstack/ai-utils 和 @tanstack/ai-event-client,都从 ^1.0.0 提升到 ^1.0.1;所有外部依赖都没变。而导出映射完全没有变化,所以你应用里的任何 import 路径都不需要改写。
npm 记录不能证明什么
注册表数据里没有 changelog 正文,1.1.0 tarball 内的 README 也与 1.0.1 的 README 一致,只有两处赞助商 logo URL 不同。因此「新增了什么」无法只靠注册表元数据回答——必须去对比已发布的构建产物,这正是我做的事。
真正的改动:取消与超时的信号传递
对比两个已发布的 tarball,644 个文件中有 65 个发生变化,分布在 chat、MCP、middleware、embeddings、files、realtime 和 video 几个方向。主题只有一个:中止信号现在能触达真正的工作本身,而不只是停掉包在外面的那层 wrapper。
chat 中间件现在拿到一个关联(linked)的 abort signal
在 1.0.1 中,chat runner 保留了两套彼此独立的「已取消」概念:调用方的 abortController.signal,以及中间件自己的 abort() controller。在 1.1.0 中,runner 会计算出一个单一的 linkedSignal——调用方信号加上 ctx.abort()——并把这个信号交给中间件和适配器请求。随包发布的注释说得很直白:/** The caller signal plus ctx.abort(), only when there is a caller signal. */
对于一个从 UI 侧取消对话的应用来说,这是「请求停了」和「请求、工具循环以及 provider 调用都停了」之间的区别。中间件的类型声明也同步更新了:signal 现在会在调用方中止 chat 请求或某个中间件调用 abort() 时中止。
MCP 工具发现会收到本次运行的信号
MCP 往往是一个 AI 应用最容易卡住的地方。在 1.0.1 中,MCPToolManager.discover() 不接受任何参数,各个 MCP 数据源的 tools() 调用也无法被取消。在 1.1.0 中类型变成了:
export interface MCPToolSource {
tools: (options?: {
lazy?: boolean
signal?: AbortSignal
}) => Promise<Array<AnyServerTool>>
close: () => Promise<void>
}
同时 MCPToolManager.discover(signal?: AbortSignal) 会把 chat 运行的信号转发给每个数据源的 tools() 调用。文档中的契约明确说明:忽略 signal 的数据源依然可以工作——这是可选的协作,不是硬性要求。
生成活动接受 abortSignal 与 timeout
embed() 活动新增了两个在 1.0.1 中并不存在的选项,声明注释把语义定义得很精确:
export declare function embed<TAdapter extends EmbeddingAdapter<string, any, any, any>>(
options: EmbedOptions<TAdapter>,
): Promise<EmbeddingResult>
// 1.1.0 中 EmbedOptions 内部
timeout?: number // 本次活动调用的最长时长(毫秒)。
// SDK 全局没有默认值——请根据 provider 和具体任务选择合适的值。
// 与 abortSignal 组合生效;谁先中止算谁。
abortSignal?: AbortSignal // 调用方的取消信号(请求断开、任务/运行时取消)。
// 与 timeout 组合成一个有效信号并转发给适配器。
// 属于单次请求级别——不会存储在全局 provider 客户端配置上。
SDK 层面没有任何默认超时值。这是类型接口层面一个有意做出的设计选择,意味着上限要你按活动自行设定——对于一个不能比请求活得久的 embedding 任务来说,这正是你想要的。
realtime、files 与 video 适配器同样接受 abort signal
同样的形态在适配器层一路传递下去:
- Realtime:
RealtimeTokenAdapter.generateToken(options?: { abortSignal?: AbortSignal })、RealtimeTokenOptions.abortSignal,以及connect(token, clientTools?, options?: { abortSignal?: AbortSignal })。客户端侧的连接建立现在也能被取消,而不只是 token 请求。 - Files:
FilesAdapter上的upload、get和delete各自接受可选的{ abortSignal },并附带说明:在支持的情况下,适配器应把它转发给 provider 请求。 - Video:
getVideoStatus与getVideo接受{ abortSignal },新增的可选方法cancelVideoJob(jobId, options?)让适配器可以请求 provider 停掉仍在运行的任务。随包发布的契约说明这是尽力而为:拒绝会被记录,而不会抛出。
2026-11-04 这趟发布列车:让整个 AI 家族版本对齐
@tanstack/ai 是 monorepo 发布,各包并不共享同一个版本号。以下是我在 npm 上针对 2026-11-04 核验到的内容:
| 包 | 发布的版本 | 时间戳(UTC) |
|---|---|---|
@tanstack/ai-anthropic | 1.1.0 | 13:58:44 |
@tanstack/ai-client | 1.1.0 | 13:58:45 |
@tanstack/ai-event-client | 1.0.1 | 13:58:50 |
@tanstack/ai-openrouter | 1.1.0 | 13:59:02 |
@tanstack/ai-openai | 1.1.0 | 13:59:23 |
@tanstack/ai-mcp | 1.1.0 | 13:59:50 |
@tanstack/ai-react | 1.0.2 | 13:59:53 |
@tanstack/ai-gemini | 1.1.0 | 14:00:14 |
@tanstack/ai-solid | 1.0.1 | 14:00:30 |
@tanstack/ai-cloudflare | 1.1.0 | 14:01:37 |
@tanstack/ai | 1.1.0 | 14:01:38 |
@tanstack/ai-utils | 1.0.1 | 14:02:01 |
@tanstack/ai-vue(1.0.1)、@tanstack/ai-svelte(1.0.0)和 @tanstack/ai-preact(1.0.1)不在这一趟列车里;它们的 latest 版本仍带着更早的发布时间戳。
为什么版本对齐比核心升级更重要
由于框架包和适配器包各自带自己的版本号(ai-react 是 1.0.2,ai-utils 是 1.0.1),部分升级完全可能发生——而这正是这次发布最可能咬到你的方式。核心声明了 @tanstack/ai-utils: ^1.0.1 和 @tanstack/ai-event-client: ^1.0.1 这样的 caret 范围,所以只要 lockfile 把它钉在旧版本,npm 就会很乐意在你的依赖树里解析出一个过期的 1.0.0;然后你就会用 1.1.0 的核心跑 1.0.0 的内部实现,而且没有任何错误会告诉你这件事。
把这个家族当成一个整体:在同一个 commit 里 bump 所有 @tanstack/ai* 条目,然后重新安装,让 npm 从同一个发布窗口里解析出完整的一组。
用四条命令自己验证
这就是完整的验证闭环,大约花一分钟。
# 1. registry 对 1.1.0 的描述
npm view @tanstack/ai@1.1.0 version description license engines peerDependencies
# 2. latest 标签归谁,以及各版本分别是什么时候落地的
npm view @tanstack/ai dist-tags
npm view @tanstack/ai time --json | grep -E '"1\.(0|1)\.'
# 3. 真正发生变化的依赖范围
npm view @tanstack/ai@1.0.1 dependencies
npm view @tanstack/ai@1.1.0 dependencies
# 4. 直接对比两个已发布的构建产物,而不是相信 changelog 摘要
mkdir -p /tmp/ai-diff && cd /tmp/ai-diff
npm pack @tanstack/ai@1.0.1 --silent
npm pack @tanstack/ai@1.1.0 --silent
mkdir -p old new
tar -xzf tanstack-ai-1.0.1.tgz -C old
tar -xzf tanstack-ai-1.1.0.tgz -C new
diff -rq old/package/dist new/package/dist | wc -l
diff -u old/package/dist/esm/activities/chat/mcp/types.d.ts \
new/package/dist/esm/activities/chat/mcp/types.d.ts
第 4 步最物有所值:MCP 的 signal 新增和 embed() 上的 timeout/abortSignal 选项,都是我靠它发现的,而这两项在随包发布的 README 里根本看不到。
这次发布支撑的是 AI SaaS 模板的哪一项能力
这是一次技术性发布,所以下面直接给出它真正影响的采购决策,而不是一段泛泛的销售话术。
取消机制的打通,是「AI 功能成本符合预期」和「它悄悄为没人收到的结果付费」之间的分水岭。当用户在回答进行到一半时关掉标签页,除非有东西去取消,provider 请求、MCP 工具发现和 embedding 任务都会继续跑下去。有了 1.1.0,一个 TanStack Start 路由可以把它的 request.signal 传进活动里;配合协作式的 MCP 服务器,就能在运行被取消时停下发现过程。
这是模板级的能力,不是应用层的小细节。 一份宣称提供流式对话、工具调用、结构化输出和额度计费的样板工程,同时也应该提供取消能力,否则每个客户都得自己重新实现一遍——这正是我对比过的 AI SaaS 样板工程要暴露出来的东西。
具体来说,任何 AI SaaS 起点都值得检查三个层面:
- 流式对话 ——
chat()加上官方文档中的toServerSentEventsResponse(),并在 Worker 运行时下 flush SSE 响应,这部分Cloudflare Streams API 指南有覆盖。 - 工具调用与 MCP —— 一个你可以在服务端实现的
toolDefinition()契约,以及一个不再在已取消的运行上阻塞的 MCP 层。 - 结构化输出 —— 使用 Zod、ArkType、Valibot 或原生 JSON Schema 的
outputSchema,让解析结果是带类型的对象,而不是你要用正则去抠的字符串。
如果你想看的是能跑的示例而不是 API 参考,AI Image Studio 模板提供了图像流水线(生成、编辑、放大、画廊、额度),AI Workspace 模板提供了多模型对话、RAG、联网搜索、MCP 工具调用、额度计费和 Stripe 计费——全部跑在 TanStack Start 上。
局限、披露,以及如何理解本文的论断
这里用到的论断类型。 实测(Measured)表示直接读自 npm 注册表元数据或已发布的 tarball。推算(Calculated)表示我在这些文件上做的算术(644 里的 65、发布窗口时长)。估计(Estimated)表示我的判断。用户提供(User-provided)表示没有——这里没有任何指标来自用户或客户。
我没有做的事。 我没有把这个版本跑在生产应用里。我对比了两个已发布的 tarball 并阅读了随包发布的类型声明;我没有对流式延迟、token 成本或取消延迟做基准测试,也不声称这些方面有任何改进。1.1.0 的上游 changelog 我没能拿到,所以如果维护者在类型接口之外还发布了行为变更——比如默认值变更、没有类型变化的运行时修复——本指南不会显示出来。发布之前请查看 TanStack AI 的 GitHub 仓库 里的源码 diff。
披露。 我维护 TanStack Ship,上面链接的模板都是我自己的产品。我与文中提到的任何模型供应商都不存在实质关联,也不对任何供应商的定价、可用性或模型阵容作出任何断言。
结论与下一步
@tanstack/ai 1.1.0 是一个行为良好的次版本发布:导出映射没变,外部依赖没变,README 基本没变,整个 API 增量就是一组可选的 abortSignal 和 timeout 参数,它们让取消能触达工作本身,而不是停在 wrapper 外面。风险不在 API——风险在于只升级核心,却把适配器包落在一个版本之后。
下一步:并排对比 AI SaaS 样板工程,看看哪些真正把流式对话、工具调用、额度计费和取消打通到端到端——然后浏览这些模板,在你写下第一个 prompt handler 之前,先预览那个与你的产品匹配的那个。
相关阅读: Tanstack React Query 5 106 0 Release Guide · Tanstack Redact Webpack Rspack Setup Guide · Tanstack Ecosystem Complete Guide 20260620
FAQ:@tanstack/ai 1.1.0 升级
@tanstack/ai 1.1.0 是破坏性变更吗?
不是。它是从 1.0.1 升级而来的次版本号,semver 要求保持向后兼容。我在产物层面验证过:1.0.1 与 1.1.0 的导出映射完全相同,README 只在两处赞助商 logo URL 上有差异,每个外部依赖范围都没有变化。新增的选项都是可选的,因此现有调用无需修改即可编译和运行。
我需要同时升级所有 @tanstack/ai 包吗?
应该要。这个家族并不共享同一个版本号——ai-react 升到了 1.0.2,ai-utils 升到了 1.0.1——而核心通过 caret 范围依赖 @tanstack/ai-utils 和 @tanstack/ai-event-client。部分升级可能让 1.1.0 的核心跑在 1.0.0 的内部实现之上,而且没有任何错误会暴露这一点。
@tanstack/ai 1.1.0 会改变我编写流式对话端点的方式吗?
不会。1.1.0 发布的 README 记录的 chat() 调用和 toServerSentEventsResponse() 传输方式与 1.0.1 相同,diff 也显示 chat 入口的类型接口没有任何变化。如果你的端点现在能用,它会继续能用。改变的是当一次运行被取消时,底层会发生什么。