背景：智能体框架的竞争点从「能不能跑」转到「跑多久」
2025 年这一波智能体框架首先要解决的问题是连通性：怎么把一个模型、一批工具和一段上下文拼起来，跑出一个能用的循环。到 2026 年，连通性已经不是瓶颈，真正拉开差距的是会话能持续多久、能不能在崩溃与发布之后接着跑、以及换模型换沙箱时有多少代码要重写。
TanStack AI 从立项起就把第三个问题当成卖点，官方原话是「永不锁定」。这句话在 1.0 里被拆成了四个可分别选择的东西：模型供应商、UI 框架、沙箱，以及它们之间的线协议。值得注意的是，1.0 并没有把这个承诺升级成「我们替你选好」，而是把它固化成了接口契约——你仍然要自己选，但选完之后不必重写。
理解这一点很重要，因为它解释了本文后面会反复出现的那个结构：TanStack AI 在功能上扩张得很凶，但在 API 上收缩得很谨慎。1.0 公告里有一句容易被忽略的话——1.0 没有引入新概念，团队只是把 0.x 里所有被标记为弃用的 API 全部移除，而每一个替代方案在 0.x 时代就已经交付了。
官方公告与文档都写明了这一分层：核心 API 稳定且可用于生产；@tanstack/ai-harness 与 @tanstack/ai-harness-cli 以 0.x 发布，其他包中的 Harness 入口点（例如 ai-skills 与 ai-acp 下的对应入口）同样是实验性的，可能在次版本内发生变更。任何把 Harness 直接放进关键生产链路的计划都需要自己承担这个变更风险。目前官方及行业暂未披露更多细节，后续将持续跟进迭代动态。
两层版本策略：稳定的是契约，不是功能集合
多数框架发 1.0 时的潜台词是「功能齐了」。TanStack 这次给出的定义不一样：1.0 是对你所依赖的那批 API 的正式承诺。这个措辞把稳定的对象从功能集合挪到了接口契约上，带来的直接后果是功能可以继续快速加，只要不破坏契约。
这条界线画在哪里，是本文认为这次发布里信息量最大的一个决策。Harness 被单独留在 0.x，理由在文档里写得很直白：它是整套工具箱里最新的一块，团队希望在锁定 API 之前先把它交到用户手里，然后「告诉我们哪里会坏」。
从采用角度看，这条界线给出了一个相当清晰的操作路径：核心层可以进生产，Harness 层适合进试点。它同时也意味着，至少在 Harness 转稳定之前，任何基于它的长期架构都需要预留一层自己的封装。
从 alpha 到 1.0：一组可核对的增长读数
官方给出了一张 alpha 与 1.0 的对照，这是本文认为少数几个值得原样引用的表格之一，因为它把「扩张了多少」变成了可核对的数字，而不是形容词。
| 维度 | Alpha（2025 年 12 月） | 1.0（2026 年 10 月） |
|---|---|---|
| 模型适配器 | 4 个 | 23 个，外加 openaiCompatible 覆盖任意 OpenAI 风格接口 |
| UI 框架 | React、Solid、原生 JS | React、Vue、Solid、Svelte、Preact、Angular、Octane、Remix、原生 JS |
| 编码智能体 | 无 | Claude Code、Codex、OpenCode、Grok Build 及任意 ACP 智能体 |
| 沙箱供应商 | 无 | 11 个 |
时间线同样公开：2025 年 12 月 alpha 发布，两周后的 Alpha 2 补齐了全模态；随后是一段被团队自己称作「重写之冬」的时期，ai 函数在投入八天工作后被砍掉，适配器被拆成可树摇的小块；2026 年春加入中间件、实时语音、Code Mode、流式结构化输出与完整的 AG-UI 合规；6 月加入 MCP、发布 Beta、在 Open Source Awards 获评年度 AI 项目，并支持在沙箱中运行编码智能体；8 月发布 RC 并锁定架构；10 月发布 1.0。
团队规模是这张表里没有但应当被一起读的数字：维护者仍是三人，贡献者 143 人。这个比例既是社区健康度的证据，也是集中风险的来源——三名维护者要覆盖 23 个适配器与 11 个沙箱的兼容性，是这套架构最现实的脆弱点。
稳定核心覆盖哪几块面
1.0 声明进入稳定状态的面有七块：chat、tools、media、MCP、persistence、sandboxes、agents。把它们放在一起看，能看出一条清晰的分层——chat 是请求响应循环，tools 是能力边界，media 是模态，MCP 是对外协议，persistence 是状态，sandboxes 是执行环境，agents 是编排层。
其中 persistence 进入稳定这件事，是 Harness 能做持久会话的前提。如果状态层本身还在变，会话层就没有可依赖的地基。这也部分解释了为什么 Harness 必须单独留在实验状态：它站在最上面那层，下面任何一层的语义变化都会传导到它。
官方还提到一个容易被忽略的工程细节：端到端测试在每个拉取请求上运行，针对的是确定性模型夹具，不发起真实 API 调用。这句话的实际含义是，23 个适配器乘以若干工具执行流所构成的组合矩阵，是通过把模型输出固定住来测的。测的是适配与执行的机械正确性，不是模型的实际表现。这个取舍很务实，但也意味着测试通过不代表某家供应商的实际响应格式一定没问题——尤其是那些改动频繁的供应商。
Harness 的执行模型：定义一次，按会话打开
chat 函数解决的是一次请求一次响应，这在聊天框里够用，但对编码智能体、客服机器人或媒体工作室不够：它们需要一个保持打开的会话，能在工作过程中接收新消息、能派生别的智能体、能在一次发布之后活下来。
Harness 的模型因此分成两步：先以 defineHarness 用与 chat 函数相同的参数定义一次，得到一个具名的 Harness；再由 createHarnessHost 起一个宿主，按 threadId 为每路会话 open 出一个 session。会话用 send 发送消息，用 onEvent 订阅标准 AG-UI 事件。
这个模型里有一个设计值得单独拎出来：send 支持 steer 模式。它意味着用户可以在智能体正在工作的过程中插话，这条消息会在下一次模型调用之前加入正在运行的那一轮；如果当前轮已经结束，它就成为下一轮的输入。与之相对的是 follow-up，它会等到当前工作完成才被处理。把「插话」和「排队」做成两个显式模式，而不是统一塞进消息队列，是这套执行模型里少见的一处对用户意图的细分。
持久会话的三条机制与它们的边界
官方把 session 提供的能力列了六项，其中前三项构成了持久化的核心，本文把它们拆成三条机制来看。
| 机制 | 解决什么 | 官方写明的边界 |
|---|---|---|
| 会话日志 | 每个 thread 拥有一份日志；只要给宿主一个能扛住重启的存储，被崩溃或发布切断的那一轮可以在下一个宿主上继续 | 同一时刻只有一个宿主拥有某个 thread |
| 可恢复等待 | 审批、提问、登录会把运行停下来等，等待状态落在日志里；任何服务器都能在重启之后接走这个回答 | 内存态的子智能体等待无法跨宿主恢复 |
| 凭据与多用户 | 访问规则、团队共享的 thread、按用户各自的供应商密钥 | 文档示例默认用内存持久化，生产需要自备持久存储 |
第三条机制里的那句边界声明值得放大：官方明确写了「仍然存在恢复限制，包括内存态的子智能体等待无法跨宿主恢复」。这句话的含金量在于它把「持久」这个词拆成了两层——会话日志是持久的，但运行时状态不是全部持久。一个正在等待子智能体返回的父会话，如果宿主换了，这段等待不会自动继续。
对工程来说这直接决定了存储选型不是可选项而是必选项。文档给的例子用的是内存持久化，官方紧接着补了一句：要在重启后恢复，你需要一个能扛住重启的存储。换句话说，开箱配置不具备恢复能力。
插件、子智能体与预算
Harness 的扩展方式是插件：把工具、提示词、中间件、命令与状态打包，然后加载进任意 Harness。官方自带的插件覆盖文件工具、权限、undo 命令、待办列表、compact 命令与用量统计，这一套组合起来已经足够在终端里搭出一个编码智能体。
子智能体在两条路径上都可用：可以从代码里按并行或串行方式调用，带预算与超时；也可以让模型把它们当工具调用。RC 之后新增的能力允许在 chat 与 useChat 中直接把某一轮交给一个具名子智能体，例如 researcher 或 writer，并带上类型化输入与限制。
预算与超时被显式做成参数而不是约定，这一点在多智能体场景下比看上去重要。近期多项评测都指向同一个现象：多智能体系统的开销与收益并不总是成正比。把预算做成一等参数，至少让「花多少」这件事变成可以在代码里写死的选择。
Harness 还能把编码工作交接给 Claude Code、Codex、Grok Build 或任意 ACP 智能体，每个都跑在自己的沙箱里。这条路径把 TanStack AI 定位在了编排层而不是执行层——它不自己做编码，它决定交给谁做、在什么环境里做。
一处定义多处运行：五条入口形态
Harness 被设计成同一份定义可以在多个入口运行，官方给出的命令行形态有五种，这个设计是「不锁定」承诺在运行时侧的延伸。
| 入口 | 形态 | 适用场景 |
|---|---|---|
| 默认 | 终端里的对话 | 本地开发与调试 |
| -p 参数 | 单条提示词 | 脚本与持续集成 |
| --serve | 基于 HTTP 的会话协议 | 自建后端服务 |
| --acp | ACP 智能体 | 编辑器集成，如 Zed |
| --mcp | MCP 服务器 | 接入 Claude Code 与 Cursor 等 MCP 宿主 |
其中 acp 与 mcp 两个入口是按需加载的，只有真正用到时才会引入对应包。这个细节在处理依赖体积的前端工程里不是小事。
在 Web 应用中，createHarnessHandler 通过 HTTP 提供会话，handleHarnessSocket 通过 WebSocket 提供。运行路由讲的是标准 AG-UI 事件，因此 useChat 可以直接对接一个 Harness，并且支持审批与页面刷新后重新加入正在运行的那一轮。
RC 之后落地的新能力
架构在 8 月的 RC 中锁定，此后两个月是纯功能开发。按官方分类，落地的内容可以归到四组。
智能体相关：chat 与 useChat 中的子智能体；decide 函数用于类型化的选择、打分与布尔决策；Portable Agent Skills 让任何支持工具调用的模型在需要时加载 SKILL.md 技能文件；Compaction 用于把长会话压在上下文上限之内，并在供应商提供原生压缩时优先使用；computer use 让模型通过截图操作网页，且同一份代码在 OpenAI 与 Anthropic 上都能跑。
模型相关：reasoning 作为一个统一选项在所有供应商上一致工作并按模型分别定型；自动提示缓存，且工具或系统提示词在会话中途变更不会丢失缓存；retry 用于应对限流；历史可以跨模型重放，让一段会话迁移到另一个模型；各家的 Files API 收敛到同一个接口。
MCP 相关：createMCPServer 把 TanStack 工具以 MCP 服务器的形式暴露给 Claude Desktop、Cursor 与任意 MCP 宿主；工具过滤器、审批与基于任务的工具；WebMCP 双向可用，浏览器智能体可以调用你的客户端工具，你的聊天也可以使用页面提供的工具。
供应商、框架与沙箱：新增 Cloudflare Workers AI 与 AI Gateway、Lovable AI Gateway、Azure OpenAI、World Labs Marble、TypeSafe、Ollaya 等适配器；Remix 3 支持与 Svelte 开发者工具；新增 Blaxel、Upstash Box、E2B、boxd、Railway 五个沙箱供应商。
构建与测试：类型化的无头聊天 UI 工厂，可为任意框架写自定义适配器；fakeText 可在无网络无密钥的情况下测试 chat、工具与中间件；以及给你的编码助手用的 Agent Skills，让 Claude Code 或 Cursor 按你安装的版本写出正确的 TanStack AI 代码。
升级路径与真实代价
官方给出的升级步骤是四步：跑 codemod、把稳定包一起升到 1.0 同时移除三个没有 1.0 版本的 UI 包、跑类型检查逐个修、按指南处理 0.x 遗留的存储数据。本文认为真正需要提前评估的是后面三项。
其一是 threadId。它从可选变成了浏览器端与服务端都必填，且两侧都不再自动生成。浏览器端需要为每个会话传入一个稳定标识，例如路由 ID 或数据库 ID；服务端需要传入客户端发来的那个值。codemod 无法自动添加 threadId，因为它不知道你的 ID 从哪来。这一改动的实际含义是：会话标识的所有权从框架转移到了应用。它既是持久化能够工作的前提，也是这次升级里无法由 codemod 自动处理的部分。
其二是三个 UI 包的移除：ai-react-ui、ai-solid-ui 与 ai-vue-ui 没有 1.0 版本，官方要求改用对应的 createChatHook 自行构建 UI。如果你的界面依赖的是这几个包的现成组件，这次升级等于一次界面重写。
其三是存储数据迁移。官方明确警告，通过类型检查并不等于迁移了已存储的会话、运行记录与文件，部署前必须按指南执行存储数据的处理步骤。对已经有线上会话的系统来说，这一步的风险高于前两项的总和。
另外还有两处需要改代码：addToolApprovalResponse 被移除，改为解析工具审批中断；自建服务端如果向客户端流数据，停止发送 DONE 标记，改用 RUN_FINISHED 事件结束运行。
本文推算：五条增量判断
以下五条是本文基于公开材料做的推算与判断，原文并未直接给出，仅供参考。
其一，稳定的对象是契约而不是功能，这决定了 1.0 之后的功能扩张速度不会下降，反而可能加快，因为新增功能不必再承担破坏性变更的代价。对使用者来说，这意味着「升到 1.0 就安心了」这个直觉需要修正为「核心可以安心，边界仍会移动」。
其二，threadId 变必填且双侧不自动生成，是一次明确的所有权转移。它换来的是持久化能力，代价是应用必须自己承担会话标识的生成、稳定与去重。这个交换在架构上是对的，但很多团队会在迁移阶段低估它的工作量，因为它牵涉到路由、数据库与客户端三处。
其三，恢复能力是分层的，不是二值的。会话日志可以恢复，内存态的子智能体等待不能。因此在设计多智能体流程时，凡是跨宿主必须活下来的等待，都应该被显式建模为会话日志中的事件，而不是依赖运行时内存。
其四，端到端测试用确定性模型夹具，是对适配器与沙箱组合爆炸的务实应对。它保证了机械正确性，但不保证供应商的实际兼容性。工程上应当在这个测试层之外，另建一层低频的真实调用冒烟测试，专门盯那些改动频繁的供应商。
其五，三名维护者覆盖 23 个适配器与 11 个沙箱，是这套架构最现实的集中风险。选择供应商时，除了看是否在列表里，还应看该适配器最近一次实质性提交的时点，以及是否有活跃的独立贡献者在维护。
冷静判断：它改变了什么，没改变什么
它改变的是选择权的成本模型。在 1.0 之前，换模型或换沙箱往往意味着重写编排层；现在这件事被压缩成了换一个适配器包。对那些必须同时支持多家供应商、或者需要在公有云与私有部署之间来回迁的团队，这个变化是实打实的。
它没有改变的是智能体本身的能力上限。TanStack AI 不提供模型，也不提供智能体的规划与记忆能力，它提供的是把这些东西接起来并跑久一点的管道。会话能持续多久、能不能恢复，是它能负责的部分；会话里的决策质量如何，仍然取决于你选的模型与你写的提示词。
最需要留意的是版本策略带来的采用节奏。核心与 Harness 分处在稳定与实验两侧，这个分层是诚实的，但也意味着一个完整的产品级智能体应用，至少在当下仍需要自己维护一层对 Harness 的封装。官方在公告结尾写的是「接下来先打磨，然后是支持，最后把 Harness 推到稳定」，这条路线是否按期兑现，目前官方及行业暂未披露更多细节，后续将持续跟进迭代动态。