a2ui-migration

A2UI 迁移

此技能是一个路由器。它会识别正在迁移的内容，然后将你引导至相应情况的指南。根据以下三项事实来确定迁移情况：

1. 语言／平台：Dart（Flutter）、TypeScript（Lit、Angular、React、web core）、Python（Agent SDK、ADK、A2A）、Swift、Kotlin。
2. 来源：代码当前使用的 SDK 或软件包及其版本，以及它在线路上使用的协议版本。
3. 目标：代码之后应使用的 SDK，以及应使用的协议版本。

在写明这三项之前，请勿开始编辑。如果迁移同时更改 SDK 和线路版本，则这属于两次迁移；当 Agent 和渲染器不是同时发布时，请将其拆分。

第 1 步：确定语言和源 SDK

请查看仓库中的清单，而不只是文件扩展名：

清单	要查找的依赖项名称
pubspec.yaml、包含 dart_* 的 Bazel BUILD	genui、a2ui_core、a2ui_flutter、a2ui_agent、a2ui_cli、genai_primitives
package.json	@a2ui/web_core、@a2ui/lit、@a2ui/angular、@a2ui/react、@a2ui/markdown-it、@a2ui/agent、@a2ui/catalog-*
pyproject.toml、requirements*.txt、uv.lock	a2ui-core、a2ui-agent-sdk、a2ui-a2a、a2ui-adk、a2ui-catalog-*
Package.swift	A2UISwiftCore、A2UISwiftUI、BasicCatalog、BasicCatalogSwiftUI（本仓库 Package.swift 的产品）
build.gradle*	kotlin/agent_sdk_legacy/ 下的旧版 Kotlin Agent SDK

记录准确的版本约束，并在本仓库中阅读该软件包对应发布线的 CHANGELOG.md。

第 2 步：确定线路协议版本

SDK 版本并不总能说明协议版本；请阅读代码发送或预期接收的载荷（测试夹具、基准文件、提示词、传输代码）：

载荷中的证据	协议
beginRendering、surfaceUpdate、dataModelUpdate 消息	v0.8
"version": "v0.9"，包含 createSurface、updateComponents、updateDataModel、deleteSurface；绑定形式为 {"path": ...}，调用形式为 {"call": ...}	v0.9
"version": "v0.9.1"	v0.9.1
"version": "1.0"；绑定形式为 {"@path": ...}，调用形式为 {"@call": ...}；每个组件都有 catalogId；使用 callRendererFunction／callAgentFunction	v1.0

其他线索：catalog ID（.../specification/v0_9/catalogs/basic/catalog.json 对应 v0.9，.../specification/v1_0/catalogs/basic/catalog.json 对应 v1.0；v1.0 catalog 文件位于 catalogs/<name>/v1/ 下，但其 ID 仍保留 specification/v1_0 路径）、能力的元数据键（a2uiClientCapabilities 对应 v0.9，a2uiRendererCapabilities 对应 v1.0），以及项目用于验证的架构目录名称（specification/v0_9/json 与 specification/v1_0/json）。

步骤 3：确定目标

根据任务询问或推断目标是同一协议版本上的新版 SDK、同一 SDK 上的新协议版本，还是两者兼有。如果任务未说明，优先选择最小步幅：当前 SDK 的最新版本，并采用 Agent 已支持的协议版本。以与源版本相同的方式记录目标。

步骤 4：根据情况查阅指南

语言	从	到	指南
Dart	genui 0.9.x / 0.10.x（A2UI v0.9）	a2ui_core + a2ui_flutter（+ a2ui_agent），v0.9 或 v1.0	references/dart_genui_to_1_0.md
任意语言	协议 v0.8	协议 v0.9	specification/v0_9/docs/evolution_guide.md；Python 负载转换器 samples/agent/adk/migrate_v08_to_v09.py；Lit 渲染器示例见 typescript/renderers/lit/README.md
任意语言	协议 v0.9	协议 v0.9.1	specification/v0_9_1/docs/evolution_guide.md
任意语言	协议 v0.9 / v0.9.1	协议 v1.0	specification/v1_0/docs/evolution_guide.md，然后查阅 SDK 的 CHANGELOG.md
任意语言	某个 A2UI SDK 版本	同一 SDK 的较新版本	先查看该软件包的 CHANGELOG.md（优先查看 Breaking: 条目），然后执行下方的通用流程

如果符合某一行，请完整阅读并遵循相应指南。如果没有符合的行，请执行通用流程，然后添加一个案例（见本文末尾）。

通用流程

如果没有适用的案例指南，请按以下流程操作；使用案例指南时，也将此流程作为外层循环：

1. 盘点。 列出所有导入或依赖源 SDK 的文件、包含载荷的所有 fixture 或 golden，以及所有向模型说明线上格式的提示词。按涉及的层分组：传输、渲染器接线、目录和组件、函数、测试。
2. 先处理依赖。 修改清单，然后让项目解析依赖项。在新软件包安装完成之前，不要编辑源代码。
3. 一次迁移一层。 依次迁移传输、渲染器接线、目录和组件、函数，最后迁移测试。每完成一层就编译一次；未通过编译的层会掩盖下一层的错误。
4. 载荷和提示词。 更新 fixture、golden 和提示词文本，使其符合目标线上版本。不要一概替换键；演进指南会列出需要更改的位置。
5. 行为差异。 阅读目标版本的行为说明（案例指南中有相应章节），并逐项对照应用检查：错误处理、验证严格程度、未知 ID、排序、Markdown、主题。
6. 验证。 运行分析器或类型检查器、单元测试和组件测试，并使用包含输入和操作的界面，针对真实 Agent 手动完成一次往返。
7. 记录。 在变更说明中注明所应用的案例、需要修改应用以适应的行为差异，以及指南未涵盖的内容。

迁移不属于自己的包

如果要将迁移作为拉取请求提交到他人的仓库，例如依赖 genui 的 pub.dev 上的包：

1. 首先阅读仓库的 CI 工作流、任务运行器和本地检查脚本、Agent 指令（AGENTS.md、CLAUDE.md、.cursor/rules/ 等）、CONTRIBUTING.md（有些仓库要求在合并 PR 前签署 CLA），以及提交和 PR 标题规范（有些仓库会根据 Conventional Commits 检查 PR 标题；也要遵循历史记录使用的语言）。在修改前后都在本地运行 CI 步骤，包括示例和仓库中依赖待迁移包的每个包，即使 CI 会跳过这些步骤也要运行。使用 CI 所用的工具链版本。如果仓库固定的工具链版本无法安装，只在运行检查时放宽固定版本，然后在所有记录该版本的位置恢复原样。
2. 保留包名和公开类名。在新 SDK 允许的范围内保留其 API 形态，并在 CHANGELOG.md 的 Unreleased 标题下列出每项破坏性变更；版本号留给维护者决定。
3. 更新 README、示例和 Agent 指令中展示旧 SDK API 的内容，避免它们继续教人编写无法编译的代码。
4. 只提交迁移相关内容：
   • 包含清单、受版本控制的锁文件，以及因添加或移除依赖而发生变化的生成文件，例如插件注册文件。
   • 不要包含工具自行进行的修改（配置重写、在较新工具链上进行任何编辑前执行普通安装所导致的锁文件变更；在变更说明中提及这些情况）、无关的生成文件变更，以及包含本地路径的生成文件。如果仓库没有完整的忽略文件，请按文件名暂存文件。
   • 如果变更仅移除了依赖，锁文件中应恰好移除不再被其他内容需要的包；检查全新解析是否会产生更多变更。
   • 使用较新工具链解析的锁文件可能会选中项目自身工具链（CI、版本文件）无法使用的版本。逐一检查每个新包是否兼容，并暂缓引入不兼容的包。
5. 即使新依赖需要更高的语言或 SDK 版本，也要保留包的最低版本要求。包管理器会拒绝使用低于依赖要求的工具链；而提高版本上限可能会改变整个包的语言语义或格式。
6. 阅读已发布 SDK 版本的 API（位于包管理器缓存中），不要依据本仓库的源码，因为源码可能领先于已发布版本。
7. 保持迁移无需改变的行为不变，包括你注意到的 Bug；改在变更说明中提及这些问题。
8. 在应用仓库中，更新仍在使用的文档（架构说明、README、其他语言中的注释），但保留当时的决策记录、规范和计划原样；如果项目工具有此要求，也不要改动工作区和 CI 之外的带日期实验。当仓库要求为依赖变更提供决策记录时，请添加一份标注为提案的记录，并将决定留给所有者。如果 Agent 端使用另一种语言，且客户端会将其记录转换为线上版本，请保留该转换，以免 Agent 及其存储数据发生变化。

案例指南列出了这些规则在各个平台上的具体含义；对于 Dart 和 Flutter，请参阅 不属于自己的包。

添加迁移指南

迁移某项内容时，如果本技能还没有相关指南，请添加一份，以便后续迁移可以据此开始：

1. 在此文件旁边创建 references/<language>_<from>_to_<to>.md，命名格式如 references/dart_genui_to_1_0.md。
2. 添加与现有指南相同的章节：范围和版本假设、依赖项、按层级逐步说明并提供迁移前后的代码、检查清单、API 映射、实用方案和行为变更。
3. 在第 4 步的表格中添加一行。
4. 文本和拉取请求请遵循 natural-writing 和 pr-hygiene。