a2ui-migration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

A2UI migration

A2UI 迁移

This skill is a router. It identifies what is being migrated and then sends you to the guide for that case. A case is identified by three facts:
  1. Language / platform: Dart (Flutter), TypeScript (Lit, Angular, React, web core), Python (agent SDKs, ADK, A2A), Swift, Kotlin.
  2. Source: the SDK or package the code uses today and its version, and the protocol version it speaks on the wire.
  3. Target: the SDK the code should use afterwards, and the protocol version it should speak.
Do not start editing before all three are written down. A migration that changes the SDK and the wire version at the same time is two migrations; split it when the agent and the renderer are not released together.
此 skill 是一个路由器。它会识别正在迁移的内容,然后把你引导到对应场景的 guide。一个场景由以下三个事实确定:
  1. 语言 / 平台:Dart(Flutter)、TypeScript(Lit、Angular、React、web core)、Python(Agent SDK、ADK、A2A)、Swift、Kotlin。
  2. 源:当前代码使用的 SDK 或 package 及其版本,以及它在 wire 上使用的协议版本。
  3. 目标:代码迁移后应使用的 SDK,以及它应使用的协议版本。
在将这三项信息全部写下来之前,不要开始编辑。同时更改 SDK 和 wire version 的迁移属于两项迁移;当 Agent 和 renderer 不是同时发布时,应将其拆分。

Step 1: identify the language and the source SDK

第 1 步:识别语言和源 SDK

Read the manifests in the repository, not just the file extensions:
ManifestDependency names to look for
pubspec.yaml
, Bazel
BUILD
with
dart_*
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
(products of this repository's
Package.swift
)
build.gradle*
the legacy Kotlin agent SDK under
kotlin/agent_sdk_legacy/
Record the exact version constraint, and read that package's
CHANGELOG.md
in this repository for the release line the code is on.
读取仓库中的 manifest,而不只是查看文件扩展名:
Manifest要查找的 dependency 名称
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
中的 products)
build.gradle*
位于
kotlin/agent_sdk_legacy/
下的旧版 Kotlin Agent SDK
记录确切的 version constraint,并读取本仓库中该 package 的
CHANGELOG.md
,以确定代码所在的 release line。

Step 2: identify the wire protocol version

第 2 步:识别 wire 协议版本

The SDK version does not always tell the protocol version; read the payloads the code sends or expects (fixtures, goldens, prompts, transport code):
Evidence in payloadsProtocol
beginRendering
,
surfaceUpdate
,
dataModelUpdate
messages
v0.8
"version": "v0.9"
with
createSurface
,
updateComponents
,
updateDataModel
,
deleteSurface
; bindings as
{"path": ...}
and calls as
{"call": ...}
v0.9
"version": "v0.9.1"
v0.9.1
"version": "1.0"
; bindings as
{"@path": ...}
, calls as
{"@call": ...}
; per-component
catalogId
;
callRendererFunction
/
callAgentFunction
v1.0
Other signs: catalog ids (
.../specification/v0_9/catalogs/basic/catalog.json
is v0.9,
.../specification/v1_0/catalogs/basic/catalog.json
is v1.0; the v1.0 catalog files live under
catalogs/<name>/v1/
, but their ids keep the
specification/v1_0
path), the metadata keys for capabilities (
a2uiClientCapabilities
is v0.9,
a2uiRendererCapabilities
is v1.0), and the names of the schema directories a project validates against (
specification/v0_9/json
versus
specification/v1_0/json
).
SDK 版本并不总能反映协议版本;应读取代码发送或期望接收的 payload(fixture、golden、prompt、transport code):
Payload 中的证据协议
beginRendering
、
surfaceUpdate
、
dataModelUpdate
消息
v0.8
"version": "v0.9"
,并包含
createSurface
、
updateComponents
、
updateDataModel
、
deleteSurface
;binding 写作
{"path": ...}
,call 写作
{"call": ...}
v0.9
"version": "v0.9.1"
v0.9.1
"version": "1.0"
;binding 写作
{"@path": ...}
,call 写作
{"@call": ...}
;每个 component 都有
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
路径)、capabilities 的 metadata key(
a2uiClientCapabilities
属于 v0.9,
a2uiRendererCapabilities
属于 v1.0),以及项目用于校验的 schema 目录名称(
specification/v0_9/json
与
specification/v1_0/json
)。

Step 3: fix the target

第 3 步:确定目标

Ask, or infer from the task, whether the target is a new SDK on the same protocol version, a new protocol version on the same SDK, or both. When the task does not say, prefer the smallest step: the current SDK's latest release on the protocol version the agent already speaks. Record the target the same way as the source.
询问任务方,或根据任务推断目标是:在同一协议版本上使用新的 SDK、在同一 SDK 上使用新的协议版本,还是两者同时进行。当任务未说明时,优先采用幅度最小的迁移:在 Agent 当前使用的协议版本上采用当前 SDK 的最新 release。以与源相同的方式记录目标。

Step 4: route to a case guide

第 4 步:路由到场景 guide

LanguageFromToGuide
Dart
genui
0.9.x / 0.10.x (A2UI v0.9)
a2ui_core
+
a2ui_flutter
(+
a2ui_agent
), v0.9 or v1.0
references/dart_genui_to_1_0.md
anyprotocol v0.8protocol v0.9
specification/v0_9/docs/evolution_guide.md
; Python payload converter
samples/agent/adk/migrate_v08_to_v09.py
; Lit renderer example in
typescript/renderers/lit/README.md
anyprotocol v0.9protocol v0.9.1
specification/v0_9_1/docs/evolution_guide.md
anyprotocol v0.9 / v0.9.1protocol v1.0
specification/v1_0/docs/evolution_guide.md
, then the SDK's
CHANGELOG.md
anyan A2UI SDK releasea later release of the same SDKthat package's
CHANGELOG.md
(
Breaking:
entries first), then the generic procedure below
When a row matches, read the guide in full and follow it. When no row matches, follow the generic procedure and then add a case (see the end of this file).
语言来源目标Guide
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
任意protocol v0.8protocol v0.9
specification/v0_9/docs/evolution_guide.md
;Python payload converter
samples/agent/adk/migrate_v08_to_v09.py
;Lit renderer 示例
typescript/renderers/lit/README.md
任意protocol v0.9protocol v0.9.1
specification/v0_9_1/docs/evolution_guide.md
任意protocol v0.9 / v0.9.1protocol v1.0
specification/v1_0/docs/evolution_guide.md
,然后查看 SDK 的
CHANGELOG.md
任意A2UI SDK release同一 SDK 的后续 release该 package 的
CHANGELOG.md
(先查看
Breaking:
条目),然后执行下面的通用流程
当某一行匹配时,完整阅读对应的 guide 并遵循执行。若没有匹配行,则遵循通用流程,然后新增一个场景(见本文末尾)。

Generic procedure

通用流程

Use this when no case guide exists, and as the outer loop around a case guide:
  1. Inventory. List every file that imports or depends on the source SDK, every fixture or golden that holds payloads, and every prompt that describes the wire format to a model. Group them by the layer they touch: transport, renderer wiring, catalogs and components, functions, tests.
  2. Dependencies first. Change the manifest, then make the project resolve dependencies. Do not edit source until the new packages are installed.
  3. One layer at a time. Migrate transport, then renderer wiring, then catalogs and components, then functions, then tests. Compile after each layer; a layer that does not compile hides errors in the next one.
  4. Payloads and prompts. Update fixtures, goldens and prompt text to the target wire version. Do not blanket-replace keys; the evolution guides list which positions change.
  5. Behavioral differences. Read the target's behavior notes (a case guide has a section for them) and check each one against the app: error handling, validation strictness, unknown ids, ordering, markdown, theming.
  6. Verify. Run the analyzer or type checker, unit and widget tests, and one manual round trip against the real agent with a surface that has an input and an action.
  7. Record. Note in the change description which case was applied, which behavioral differences needed app changes, and anything the guide did not cover.
在没有场景 guide 时使用此流程;对于已有场景 guide,它也作为包围该 guide 的外层循环使用:
  1. 盘点。 列出每个 import 或 dependency 源 SDK 的文件,每个保存 payload 的 fixture 或 golden,以及每个向模型描述 wire format 的 prompt。按其影响的层进行分组:transport、renderer wiring、catalog 和 component、function、test。
  2. 先处理依赖。 先修改 manifest,然后让项目解析 dependency。在新 package 安装完成之前,不要编辑 source。
  3. 逐层迁移。 依次迁移 transport、renderer wiring、catalog 和 component、function、test。每完成一层都进行编译;无法编译的一层会掩盖下一层中的错误。
  4. Payload 与 prompt。 将 fixture、golden 和 prompt 文本更新到目标 wire version。不要整体替换 key;evolution guide 会列出发生变化的各个位置。
  5. 行为差异。 阅读目标版本的行为说明(场景 guide 中会有相应章节),并逐项对照应用检查:错误处理、校验严格程度、未知 id、顺序、markdown、主题。
  6. 验证。 运行 analyzer 或 type checker、unit 和 widget test,并针对真实 Agent 手动执行一次往返测试,使用包含 input 和 action 的 surface。
  7. 记录。 在变更说明中记录应用了哪个场景、哪些行为差异需要修改应用,以及 guide 未涵盖的任何内容。

Migrating a package you do not own

迁移自己不维护的 package

When the migration is a pull request to someone else's repository, such as a package on pub.dev that depends on
genui
:
  1. Read the repository's CI workflows, its task runner and local gate scripts, its agent instructions (
    AGENTS.md
    ,
    CLAUDE.md
    ,
    .cursor/rules/
    and the like), its
    CONTRIBUTING.md
    (some require a signed CLA before a PR is merged) and its commit and PR title conventions first (some repositories check PR titles against Conventional Commits; follow the history's language too). Run the CI steps locally before and after the change, including in examples and in every package of the repository that depends on the migrated one, even when CI skips them. Use the toolchain release CI uses. When the repository pins a toolchain release you cannot install, relax the pin only to run the checks, then restore it everywhere it is recorded.
  2. Keep the package's name and public class names. Keep its API shape where the new SDK allows, and list each breaking change in its
    CHANGELOG.md
    under an
    Unreleased
    heading; leave the version number to the maintainer.
  3. Update the README, examples and agent instructions that show the old SDK's API, so they do not teach code that no longer compiles.
  4. Commit only the migration:
    • Include the manifests, the tracked lock files, and generated files that change because a dependency was added or dropped, such as plugin registrations.
    • Leave out edits that tools make on their own (configuration rewrites, lock changes that a plain install on a newer toolchain makes before any edit; mention those in the change description), unrelated generated changes, and generated files that hold local paths. In a repository without a complete ignore file, stage files by name.
    • When the change only removes dependencies, the lock loses exactly the packages that nothing else needs; check that a fresh resolve changes nothing more.
    • A lock resolved with a newer toolchain can pick releases that the project's own toolchain (CI, version files) cannot use. Check each new package against it, and hold back the ones it cannot use.
  5. Keep the package's minimum language or SDK version even when the new dependencies need a newer one. The package manager already refuses a toolchain older than a dependency needs, while a higher bound can change language semantics or formatting across the whole package.
  6. Read the APIs of the published SDK releases (in the package manager's cache), not this repository's sources, which may be ahead of the release.
  7. Leave behavior the migration did not have to change as it is, including bugs you notice, and mention them in the change description instead.
  8. In an app repository, update living docs (architecture notes, READMEs, comments in other languages) but leave decision records, specs and plans of their time as they are, and dated experiments outside the workspace and CI when the project's tooling says to. When the repository requires a decision record for a changed dependency, add one as proposed and leave the decision to the owner. When the agent side is in another language and the client translates its records to the wire version, keep that translation, so the agent and its stored data do not change.
A case guide lists what these rules mean on its platform; for Dart and Flutter, see In a package you do not own.
当迁移对象是其他人仓库中的 pull request,例如 pub.dev 上某个 dependency
genui
的 package:
  1. 首先阅读仓库的 CI workflow、task runner、本地 gate script、agent 指令(
    AGENTS.md
    、
    CLAUDE.md
    、
    .cursor/rules/
    等)、
    CONTRIBUTING.md
    (有些仓库要求在合并 PR 前签署 CLA),以及提交和 PR 标题规范(有些仓库会根据 Conventional Commits 检查 PR 标题;还应遵循历史记录中的措辞风格)。在变更前后都要在本地运行 CI 步骤,包括示例中的步骤,以及仓库中每个 dependency 被迁移 package 的 package 中的步骤,即使 CI 会跳过这些步骤。使用 CI 所采用的 toolchain release。如果仓库固定了某个无法安装的 toolchain release,可以仅为运行检查而放宽固定版本,完成后应在所有记录位置恢复它。
  2. 保留 package 名称和 public class 名称。在新 SDK 允许的情况下保留其 API 形态,并在 package 的
    CHANGELOG.md
    中
    Unreleased
    标题下列出每一项 breaking change;版本号留给 maintainer 决定。
  3. 更新 README、示例以及展示旧 SDK API 的 agent 指令,避免它们继续教授无法再编译的代码。
  4. 提交中只应包含迁移相关内容:
    • 包含 manifest、已跟踪的 lock file,以及因新增或移除 dependency 而发生变化的自生成文件,例如 plugin registration。
    • 排除工具自行产生的编辑(configuration rewrite;在任何编辑之前使用较新 toolchain 执行普通 install 所产生的 lock 变化;应在变更说明中提及这些内容)、无关的自生成变更,以及包含本地路径的自生成文件。在 ignore file 不完整的仓库中,按文件名逐个 stage。
    • 当变更只移除 dependency 时,lock 中应恰好失去所有其他 package 都不再需要的 package;检查一次全新解析不会产生其他变化。
    • 使用较新 toolchain 解析出的 lock 可能会选中项目自身 toolchain(CI、version file)无法使用的 release。逐一检查新增 package,并在无法使用时将其暂缓纳入。
  5. 即使新 dependency 要求更高版本,也要保留 package 的最低 language 或 SDK version。package manager 本来就会拒绝比 dependency 要求更旧的 toolchain,而提高上限可能改变整个 package 的 language 语义或 formatting。
  6. 阅读已发布 SDK release 的 API(位于 package manager 的 cache 中),不要以本仓库的 source 为准,因为它们可能领先于已发布版本。
  7. 对于迁移无需改变的行为,保持原样,包括你注意到的 bug;在变更说明中提及,而不要顺手修改。
  8. 在 app 仓库中,应更新持续维护的文档(architecture note、README、其他语言的注释),但保持当时的 decision record、spec 和 plan 原样;对于工作区和 CI 之外带日期的实验,仅在项目工具链要求时更新。若仓库规定 dependency 变更需要 decision record,则以 proposed 状态新增一份,并将决定留给 owner。当 Agent 端使用另一种语言,而 client 会把记录转换为 wire version 时,应保留该转换,以免 Agent 及其存储数据发生变化。
场景 guide 会说明这些规则在其平台上的具体含义;对于 Dart 和 Flutter,请参阅在非自有 package 中迁移。

Adding a case

新增场景

When you migrate something this skill has no guide for, add one so the next migration starts from it:
  1. Create
    references/<language>_<from>_to_<to>.md
    next to this file, named like
    references/dart_genui_to_1_0.md
    .
  2. Give it the same sections as the existing guide: scope and version assumptions, dependencies, a step per layer with before/after code, checklist, API mapping, recipes, and behavior changes.
  3. Add a row to the table in Step 4.
  4. Follow
    natural-writing
    and
    pr-hygiene
    for the text and the pull request.
当你迁移的对象没有对应的 guide 时,请新增一个场景,以便下一次迁移可以直接从它开始:
  1. 在本文件旁创建
    references/<language>_<from>_to_<to>.md
    ,命名方式如
    references/dart_genui_to_1_0.md
    。
  2. 为它设置与现有 guide 相同的章节:适用范围与版本假设、依赖关系、按层划分的迁移步骤(包含迁移前后代码)、检查清单、API 映射、实践配方和行为变更。
  3. 在第 4 步的表格中添加一行。
  4. 文本和 pull request 应分别遵循
    natural-writing
    和
    pr-hygiene
    。