AI SDK TypeSafe AI 3.0.16更新：决策状态支持图像输入

AI SDK 旗下的 @ai-sdk/typesafe-ai 发布了 3.0.16 补丁版本，围绕实验性的决策状态（decision state）做了一批底层能力增强，重点在于对多模态输入和状态规范化的支持。这类更新看起来琐碎，却对使用类型安全方式构建 AI 应用的开发者有直接影响。

本次更新的核心变化

这是一个 Patch 版本（补丁更新），版本号从 3.0.x 系列递增至 3.0.16，由 GitHub Actions 自动发布，并经过 GitHub 的验证签名。更新内容集中在一个 changeset（9184a35）中，涉及决策状态处理的多项改动。

最值得关注的一点是图像输入支持。更新为 OpenAI Decisions 以及语言模型适配器（language model adapters）加入了对图像输入的处理能力，这意味着决策流程不再局限于纯文本，可以把图像作为上下文的一部分传入模型。

同时，更新也明确了边界：Gateway 保持原有的字符串和 JSON 请求格式，会拒绝文件类型的输入，TypeSafe AI 本身在这方面也采取相同策略。换句话说，图像支持是在特定适配路径上开放的，而非全局放开。

Changeset 是 Monorepo 项目中常用的版本管理方案（由 @changesets/cli 提供），开发者在提交代码时同步记录变更意图和版本影响级别（patch / minor / major），CI 流水线再据此自动生成 changelog 并发布包。AI SDK 作为多包 Monorepo，采用这一机制能确保各子包版本号的变动有据可查。本次发布关联的 changeset 编号 9184a35 即对应一次具体的变更记录，包含了上述所有决策状态相关改动的描述，开发者可在仓库的 .changeset 目录中找到原始说明文件，以获取比 release notes 更详尽的改动意图。

决策状态的结构化处理

这次更新引入了「有序的文本、文件和 JSON 部分（ordered text, file, and JSON parts）」进入实验性决策状态。这是一个结构化的变化——状态不再是单一的字符串或对象，而是被拆分成一系列有序的「parts」。

状态规范化

更新把所有公开的状态形式在调用决策提供方（decision providers）之前，统一规范化为一个 parts 数组。提供方最终收到的文本会以 text part 的形式呈现，JSON 对象则以 json part 的形式呈现。这种规范化带来的好处是接口一致性：无论上层传入什么形态，底层 provider 看到的都是统一结构。

这里有一个需要开发者注意的行为变化：直接作为 state 传入的数组现在会被当作决策状态的 parts。如果你本意是传一个 JSON 数组作为数据，而不是 parts 列表，就需要把它包裹在一个对象里，或者显式包装成一个 json part。否则框架会把数组元素误解为状态组成部分。

原生 JSON 状态的保留

当状态中恰好只包含一个 JSON part 时，TypeSafe AI 会保留原生的 JSON 状态形态，而不是强行拆解。这是对单一 JSON 场景的一个优化，避免了不必要的结构转换。此外，更新还在语言模型决策提示中对共享状态（shared state）进行了标注，让模型能够区分哪些是共享上下文。

决策状态（decision state） 是 TypeSafe AI 实验性决策系统中的核心概念，用于描述在调用 AI 模型做出某项"决策"时所携带的上下文信息。与普通的模型调用不同，决策系统试图在类型安全的约束下，将"输入上下文→模型判断→结构化输出"这一流程抽象为可审计、可追踪的状态机。早期版本中，决策状态通常以字符串或单一 JSON 对象的形式存在，这在处理纯文本场景时足够用，但面对需要混合多种数据类型（文本说明 + 图像截图 + 结构化参数）的复杂决策请求时便显得捉襟见肘。引入有序 parts 模型，正是为了让状态可以像消息列表一样携带异构内容，同时保持强类型约束。

可观测性：OpenTelemetry 集成改进

这次更新对追踪（tracing）也做了处理。决策文件的字节数据会以 base64 编码序列化到 OpenTelemetry 的状态属性中，这样文件内容就能在遥测数据里被记录下来。

在 span 的粒度上，更新做了分层设计：模型调用的 span（model-call spans）记录的是规范化后的状态 parts，而外层 span 则保留公开的状态输入（public state inputs）。这种区分让开发者在调试时既能看到用户层面原始的输入，又能看到实际传给模型的处理结果，对排查多模态和结构化状态的问题很有帮助。

OpenTelemetry（OTel） 是一套开放标准的可观测性框架，提供统一的追踪（tracing）、指标（metrics）和日志（logs）数据收集与导出规范，被 Jaeger、Datadog、Grafana Tempo 等主流观测平台广泛支持。在 AI 应用场景中，OTel 的 span（跨度）机制可以将一次模型调用拆解为多个有层级关系的追踪单元，从而让开发者看清每一步的耗时、输入输出和错误信息。将文件字节以 base64 编码写入 span 属性，是目前在不改变 OTel 协议的前提下携带二进制数据的通行做法——OTel 的属性值仅支持字符串、数值和布尔类型，因此二进制内容必须先序列化为字符串形式。这一设计使图像等文件内容可被追踪系统捕获，但也会增加遥测数据的体积，在高频调用场景下需留意存储和传输成本。

依赖同步更新

伴随本次发布，几个底层依赖也一同升级：

• @ai-sdk/provider@4.0.25
• @ai-sdk/provider-utils@5.0.57

这类依赖的联动更新意味着 provider 抽象层也在配合 parts 化和图像输入的新模型调整内部实现。使用整个 AI SDK 生态的项目在升级时应当留意这些包的版本对齐。

对开发者的实际意义

抛开版本号本身，这次更新反映出 TypeSafe AI 在决策能力上的两个走向：一是向多模态靠拢，把图像纳入决策输入；二是向结构化状态演进，用统一的 parts 模型管理文本、文件和 JSON，并配套了规范化和可观测性机制。

对于已经在用 @ai-sdk/typesafe-ai 构建类型安全 AI 流程的团队，升级到 3.0.16 前最该检查的是直接传数组作为 state 的代码路径——这里的行为变化可能导致现有逻辑被静默改变。确认无误后，图像输入和更清晰的遥测数据会是实打实的能力增益。