a2ui-migration 是 A2UI 项目中的一个迁移路由技能(skill),用途是把使用 A2UI 或前身 SDK(例如 Flutter 的 genui)的应用、渲染器、catalog 或智能体,迁移到更新的 SDK 或协议版本。它本身不直接给出代码改写规则,而是先识别迁移情形,再指向对应的迁移指南。
用途与定位 该技能面向需要升级 A2UI 相关依赖或线上协议版本的任务。它明确要求:必须先确定三件事再动手——语言/平台、源(当前使用的 SDK/包及其版本,以及线上通信的协议版本)、目标(迁移后应使用的 SDK 与协议版本)。如果迁移同时改变 SDK 和线上协议版本,应拆成两个迁移;当智能体与渲染器不是同时发布时尤其要拆分。
第一步识别语言与源 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;build.gradle 中位于 kotlin/agent_sdk_legacy/ 的旧版 Kotlin agent SDK。还需记录精确版本约束,并阅读该包的 CHANGELOG.md。
第二步识别线上协议版本 SDK 版本不总等于协议版本,技能要求读取代码发送或期望的负载(fixtures、goldens、prompts、传输代码)来判断:出现 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 路径、能力元数据键(a2uiClientCapabilities 为 v0.9,a2uiRendererCapabilities 为 v1.0)以及校验所用 schema 目录。
第三步确定目标 技能建议在任务未说明时选择最小步骤:当前 SDK 的最新发行版、保持智能体已使用的协议版本。目标也要按源相同的方式记录。
第四步路由到案例指南 技能给出路由表: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 渲染器示例;v0.9 到 v0.9.1 参阅 specification/v0_9_1/docs/evolution_guide.md;v0.9/0.9.1 到 v1.0 参阅 specification/v1_0/docs/evolution_guide.md 再读 SDK 的 CHANGELOG.md;同一 SDK 的后续版本则先读该包 CHANGELOG.md 的 Breaking 条目,再走通用流程。
通用迁移流程 无匹配案例指南时使用,也作为案例指南的外层循环:清点所有导入或依赖源 SDK 的文件、保存负载的 fixtures/goldens、向模型描述线上格式的提示词,按传输、渲染器接线、目录与组件、函数、测试分层;先改依赖清单并让项目成功解析依赖,再改源码;逐层迁移,每层之后编译;更新 fixtures、goldens 和提示词到目标线上版本,不要全局替换键名;阅读目标版本的行为说明并逐项核对错误处理、校验严格度、未知 id、排序、markdown、主题等差异;最后运行分析器或类型检查、单元与组件测试,并用带输入和动作的 surface 对真实智能体做一次手工往返验证,并在变更描述中记录所用案例、需应用改动的行为差异以及指南未覆盖之处。
迁移非自有包时的规则 当迁移是向他人仓库(例如 pub.dev 上依赖 genui 的包)提交 PR 时,技能要求先读该仓库的 CI 工作流、任务运行器与本地门禁脚本、agent 指令文件(AGENTS.md、CLAUDE.md、.cursor/rules/ 等)、CONTRIBUTING.md(有些要求签署 CLA)以及提交与 PR 标题规范;在改动前后本地运行 CI 步骤,包括 examples 和所有依赖被迁移包的其它包;使用 CI 所用的工具链发行版;无法安装固定工具链时只临时放宽以运行检查、随后恢复。保留包名与公开类名,尽量保持 API 形状,把每项破坏性变更列在 CHANGELOG.md 的 Unreleased 下,版本号留给维护者;更新 README、示例与 agent 指令,避免展示无法编译的旧 API。提交只包含迁移相关内容:清单、被跟踪的 lock 文件、因依赖增删而变化的生成文件;排除工具自动修改、无关生成与含本地路径的生成文件;在不完整 ignore 的仓库按名称暂存文件。只删依赖时须确认全新解析不再变化;用较新工具链解析出的 lock 可能选了项目工具链无法使用的版本,要逐个核对并压回。保持包的最低语言或 SDK 版本,即使新依赖要求更高版本。阅读已发布 SDK 发行版的 API(包管理器缓存),而不是仓库中可能超前的源码。未必须改变的行为(包括发现的 bug)保持原样并在变更描述中说明。应用仓库中更新仍在使用的文档,但保留决策记录、规格与计划原样;需要为变更依赖补决策记录时,以 proposed 状态添加、决定权留给所有者;智能体位于其它语言且客户端负责转换到线上版本时,保留该转换。
适用场景与限制 适用于 A2UI 生态的 SDK/协议升级、向第三方仓库提交迁移 PR、以及为新迁移情形补充指南(在 references/ 下按 language_from_to_to.md 命名并加入路由表)。资料未提供安装命令、收费、价格或具体平台限制;该技能不替代案例指南中的代码细节,未覆盖的情形需按通用流程处理并自行补充案例。