@ai-sdk/workflow 2.0.73 发布：工具输入校验对齐 streamText

Vercel 的 AI SDK 生态持续高频迭代，工作流扩展包 @ai-sdk/workflow 推出了 2.0.73 版本。这是一个以修复为主的补丁版本，但其中关于工具输入校验（tool input validation）的改动，对构建持久化 AI 工作流的开发者来说意义不小。

本次更新改了什么

2.0.73 属于 patch 级别的版本，发布说明中列出两项功能性修复，以及一批依赖更新。它没有引入新 API，也没有破坏性变更，核心目标是把工作流运行时的行为与普通流式调用拉齐。

对于正在使用 WorkflowAgent 做可恢复、可持久化智能体编排的团队来说，这类"行为一致性"修复往往比新功能更关键——它直接决定了同一段工具定义在不同执行路径下是否会产生不同的输入解析结果。

什么是 patch 版本？ 在语义化版本（SemVer）规范中，版本号形如 MAJOR.MINOR.PATCH。patch 位（此处为 73）的递增表示向后兼容的问题修复，不引入新功能、不做破坏性变更；minor 位递增表示向后兼容的新增功能；major 位递增则意味着可能破坏现有代码的变更。因此 @ai-sdk/workflow 从 2.0.x 升到 2.0.73 属于低风险跟进，通常无需改动应用代码即可升级，但仍建议对受影响的边界行为做回归验证。

核心修复一：工具输入校验与 streamText 对齐

本次最值得关注的提交是 6ac1ee1，它让 WorkflowAgent 使用原始工具 schema 来校验和规范化工具输入，从而与 streamText 的表现保持一致。

发布说明中明确列举了被对齐的行为清单：默认值（defaults）、转换（transforms）、类型强制（coercion）、精化校验（refinements）、未知键处理（unknown-key handling）、自定义校验器（custom validators）、repairToolCall，以及各类生命周期回调（lifecycle callbacks）。这些在持久化运行（durable runs）中现在与流式调用行为相同。

这项改动解决了一个容易踩坑的问题：过去，持久化工作流可能会因为 schema 处理逻辑与 streamText 不同，导致工具入参在边界情况下出现偏差，比如默认值没被填充、未知字段被放行或误删、transform 执行时机不一致等。对齐之后，开发者可以更放心地在两种执行模式间切换。

streamText 与 WorkflowAgent 的区别。 streamText 是 AI SDK 中最常用的流式文本生成 API，工具调用在其同步的请求—响应生命周期内完成校验与执行。而 WorkflowAgent 面向持久化、可恢复的编排场景：一次工具调用可能跨越进程重启、人工中断或长时间等待，执行状态需要被序列化并存储。正因为两条路径的输入处理时机不同，历史上容易在 schema 解析上产生分歧。所谓「使用原始工具 schema」，是指不再套用工作流侧额外的一层转换，而是直接拿开发者定义的那份 schema（如基于 Zod/JSON Schema 的定义）做解析，从而保证校验、默认值填充与规范化结果与 streamText 完全一致。

核心修复二：审批请求保留转换前输入

同一提交还处理了一个关于人机审批（approval requests）的细节：审批请求现在会保留转换前（pre-transform）的输入。

这意味着工具输入在被 transform 处理之前就会被记录到审批请求里，从而避免在恢复（resume）执行时 transform 被重复执行两次。对于涉及人工审核、需要中断再续跑的持久化工作流来说，这是个实实在在的 bug 修复——重复执行 transform 可能导致状态漂移、副作用叠加，或者审批人看到的输入与实际执行的输入不一致。

tool call 的 transform 是什么？ transform 是一段挂在工具定义上的函数，在模型给出的原始参数被最终使用前对其进行加工，例如补全字段、改写格式或注入上下文。它是纯函数式的「输入到输入」映射。问题在于：当工作流因人工审批而中断、之后从检查点恢复时，如果保存的是 transform 之后的输入，恢复流程会再次对其执行 transform，造成「二次转换」——若 transform 非幂等（即重复执行结果不同），就会引发状态漂移或副作用叠加。保留 transform 前的原始输入，等于把转换点记录在可重放的边界之前，恢复时只执行一次，语义与一次性流式调用保持一致。

其他改动：运行时上下文与依赖更新

另一项修复来自提交 88ea0d7，内容是让工作流正确传递由 telemetry.includeRuntimeContext 允许的运行时上下文。对于关注可观测性的团队，这让链路追踪中的运行时信息更完整。

依赖方面，本次更新升级了 @ai-sdk/provider-utils 至 5.0.60，以及 ai 至 7.0.141。这类同步更新通常意味着上游在 provider 工具层与核心包上也有相应调整，建议一并检查版本兼容性。

telemetry.includeRuntimeContext 与可观测性。 现代 AI 应用的链路追踪通常遵循 OpenTelemetry 语义，span 与 trace 用于串联一次请求内部的各步骤。includeRuntimeContext 是一个开关，开启后会把运行时信息（如环境、请求元数据、工作流实例上下文）附加到遥测数据上。持久化工作流由于跨越多个进程甚至多天执行，其 trace 上下文容易被截断或丢失；此修复确保这些上下文能正确随工作流传递，让分布式追踪能完整还原一次可恢复执行的链路，便于定位延迟与失败环节。

哪些人应该升级

如果你正在使用 @ai-sdk/workflow 构建持久化智能体，尤其是满足以下任一条件，建议尽快升级：团队在工具 schema 上使用了 transform、默认值或自定义校验器；工作流涉及人工审批与恢复执行；依赖 telemetry 追踪运行时上下文。

如果你的工作流只做简单的工具调用、且未使用 transform 或审批流程，升级风险很低，属于常规的补丁跟进。无论哪种情况，由于这是 patch 版本且变更集中在行为对齐，升级后建议针对工具入参的边界用例做一轮回归测试。