Back to Details

major-version-mode

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Context

上下文

This task is part of the next AI SDK major release. Breaking changes are acceptable.
本任务属于AI SDK下一个主版本开发的一部分，允许引入破坏性变更。

Breaking Change Guidelines

破坏性变更指南

While breaking changes are acceptable, it is still encouraged to minimize unnecessary disruption for 3P consumers of the AI SDK. Providing deprecated aliases and automated migration logic can help ease the transition.
虽然允许破坏性变更，但仍建议尽量减少对AI SDK第三方使用者的不必要干扰。提供弃用别名和自动迁移逻辑有助于平滑过渡。

Renamed/changed exports

重命名/修改的导出项

If renaming or modifying an exported function or type, provide a deprecated alias as a package-level export where feasible:
typescript
/** @deprecated Use `newFunctionName` instead. */
export { newFunctionName as oldFunctionName } from './new-module';
Only do this if it doesn't introduce meaningful technical debt. If it does, skip the alias — but check with the user first before making a clean break.
如果重命名或修改已导出的函数或类型，在可行的情况下提供作为包级导出的弃用别名：
typescript
/** @deprecated Use `newFunctionName` instead. */
export { newFunctionName as oldFunctionName } from './new-module';
仅在不会引入明显技术债务的情况下才这么做。如果会产生技术债务，则跳过别名——但在彻底移除前请先与用户确认。

Modified message types (e.g. in 
@ai-sdk/provider-utils
)

修改后的消息类型（例如 
@ai-sdk/provider-utils
中的类型）

If modifying model message shapes (e.g. content part types in 
packages/provider-utils/src/types/content-part.ts
):
  1. Deprecate in 
    @ai-sdk/provider-utils
     rather than removing immediately, if feasible. Mark deprecated types/members with a 
    @deprecated
    JSDoc comment and a 
    TODO
    note to remove in the following major version.
  2. Keep deprecated equivalents in 
    packages/ai/src/prompt/content-part.ts
     — this file is the consumer-facing layer and should retain the old shapes in the Zod schemas so existing consumer code continues to compile with a deprecation warning. Include a similar note about deprecation and removal in the following major version.
  3. If clean deprecation isn't feasible without meaningful technical debt, a hard removal may be preferred — but check with the user first.
如果修改模型消息结构（例如 
packages/provider-utils/src/types/content-part.ts
中的内容部分类型）：
  1. 在 
    @ai-sdk/provider-utils
    中弃用    而非立即移除（如可行）。为弃用的类型/成员添加 
    @deprecated
    JSDoc 注释，并标注TODO说明将在下一个主版本中移除。
  2. 在 
    packages/ai/src/prompt/content-part.ts
    中保留弃用的等效项    ——该文件是面向使用者的层，应在Zod schema中保留旧结构，这样现有使用者代码可继续编译，同时显示弃用警告。添加类似的说明，注明弃用情况及下一个主版本的移除计划。
  3. 如果无法在不产生明显技术债务的情况下实现平滑弃用，可选择直接移除——但请先与用户确认。

Provider spec changes (
@ai-sdk/provider
)

提供商规范变更（
@ai-sdk/provider
）

The 
provider
package defines the spec that provider implementers code against. It should generally not be modified outside of major versions, so keeping the spec clean and consistent is critical.
Breaking changes without maintaining temporary backward compatibility measures are more acceptable here than elsewhere, because the audience is smaller — far fewer developers implement their own providers than build features on top of the AI SDK.
Rules:
  • Only modify the latest spec version. Older versioned spec interfaces must remain completely untouched.
  • Deprecated aliases are not required — a clean break is preferred to preserve spec clarity.
  • The current spec version is not the same as the current AI SDK major version number. If it's unclear which spec version to operate on, ask the user before proceeding.
provider
包定义了提供商实现者编写代码所遵循的规范。通常不应在主版本之外修改该规范，因此保持规范的清晰性和一致性至关重要。
与其他地方相比，这里更允许不保留临时向后兼容措施的破坏性变更，因为受众更少——实现自定义提供商的开发者远少于基于AI SDK构建功能的开发者。
规则：
  • 仅修改最新的规范版本。 旧版本的规范接口必须完全保持不变。
  • 不需要提供弃用别名——为了保持规范清晰，优先选择彻底变更。
  • 当前规范版本与当前AI SDK主版本号并不一致。如果不确定要操作哪个规范版本，请先询问用户再继续。

Documentation

文档

After implementing changes, update relevant documentation in 
content/docs/
.
If the change requires consumers to update their code or migrate stored data, add a section to the latest migration guide:
  • Find the migration guide with the highest version number in 
    content/docs/08-migration-guides/
  • Add a concise section explaining what changed and how to migrate
实现变更后，更新 
content/docs/
中的相关文档。
如果变更要求使用者更新代码或迁移存储的数据，请在最新的迁移指南中添加一个章节：
  • 在 
    content/docs/08-migration-guides/
    中找到版本号最高的迁移指南
  • 添加一个简洁的章节，说明变更内容以及迁移方法