a2ui-migration

A2UI の移行

このスキルはルーターです。移行対象を特定し、そのケースに対応するガイドへ案内します。ケースは、次の3つの情報で特定します。

1. 言語／プラットフォーム：Dart（Flutter）、TypeScript（Lit、Angular、React、Web コア）、Python（エージェント SDK、ADK、A2A）、Swift、Kotlin。
2. 移行元：現在コードが使用している SDK またはパッケージとそのバージョン、および通信で使用するプロトコルのバージョン。
3. 移行先：移行後にコードで使用する SDK と、使用するプロトコルのバージョン。

3つすべてを書き出す前に、編集を始めないでください。SDK と通信プロトコルのバージョンを同時に変更する移行は、2つの移行に相当します。エージェントとレンダラーが同時にリリースされない場合は、分けて進めてください。

手順 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 エージェント SDK

正確なバージョン制約を記録し、このリポジトリ内にある該当パッケージの CHANGELOG.md を読んで、コードがどのリリース系列を使用しているか確認してください。

手順 2：通信プロトコルのバージョンを特定する

SDK のバージョンからプロトコルのバージョンが分かるとは限りません。コードが送信または想定するペイロード（フィクスチャ、ゴールデン、プロンプト、トランスポートコード）を確認してください。

ペイロード内の証拠	プロトコル
beginRendering、surfaceUpdate、dataModelUpdate メッセージ	v0.8
createSurface、updateComponents、updateDataModel、deleteSurface を含む "version": "v0.9"。バインディングは {"path": ...}、呼び出しは {"call": ...}	v0.9
"version": "v0.9.1"	v0.9.1
"version": "1.0"。バインディングは {"@path": ...}、呼び出しは {"@call": ...}。コンポーネントごとの catalogId。callRendererFunction／callAgentFunction	v1.0

その他の手がかり：カタログ ID（.../specification/v0_9/catalogs/basic/catalog.json は v0.9、.../specification/v1_0/catalogs/basic/catalog.json は v1.0 です。v1.0 のカタログファイルは 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 の最新リリースを移行先とします。移行元と同じ方法で移行先を記録します。

ステップ 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
任意	protocol v0.8	protocol v0.9	specification/v0_9/docs/evolution_guide.md、Python ペイロードコンバーター samples/agent/adk/migrate_v08_to_v09.py、Lit レンダラーの例 typescript/renderers/lit/README.md
任意	protocol v0.9	protocol v0.9.1	specification/v0_9_1/docs/evolution_guide.md
任意	protocol v0.9 / v0.9.1	protocol v1.0	specification/v1_0/docs/evolution_guide.md、続いて SDK の CHANGELOG.md
任意	A2UI SDK のリリース	同じ SDK の後続リリース	該当パッケージの CHANGELOG.md（まず Breaking: の項目）、続いて以下の一般的な手順

該当する行がある場合は、ガイドを最後まで読み、その指示に従います。該当する行がない場合は、一般的な手順に従ってから、このファイルの末尾にある手順に従ってケースを追加します。

一般的な手順

該当するケースガイドがない場合や、ケースガイドの外側のループとして、次の手順を使用します。

1. 棚卸し。 ソース SDK をインポートまたは依存しているすべてのファイル、ペイロードを保持するすべてのフィクスチャまたはゴールデン、モデルにワイヤ形式を説明するすべてのプロンプトを一覧にします。それらを対象レイヤーごとに分類します：トランスポート、レンダラーの配線、カタログとコンポーネント、関数、テスト。
2. まず依存関係から。 マニフェストを変更してから、プロジェクトで依存関係を解決できるようにします。新しいパッケージをインストールするまでは、ソースを編集しないでください。
3. 一度に一つのレイヤーずつ。 トランスポート、レンダラーの配線、カタログとコンポーネント、関数、テストの順に移行します。各レイヤーの後にコンパイルします。コンパイルできないレイヤーがあると、次のレイヤーのエラーが隠れてしまいます。
4. ペイロードとプロンプト。 フィクスチャ、ゴールデン、プロンプトのテキストを移行先のワイヤバージョンに合わせて更新します。キーを一括置換しないでください。変更される位置は、各バージョンの変更ガイドに記載されています。
5. 動作の違い。 移行先の動作に関する注意事項（ケースガイドにはそのためのセクションがあります）を読み、アプリで一つずつ確認します。エラー処理、検証の厳格さ、不明な ID、順序、Markdown、テーマ設定を確認します。
6. 検証。 アナライザーまたは型チェッカー、ユニットテストとウィジェットテストを実行し、入力とアクションのあるサーフェスを使って、実際のエージェントとの手動での往復テストを一度行います。
7. 記録。 変更の説明に、適用したケース、アプリの変更が必要だった動作の違い、ガイドで扱われていなかった事項を記載します。

所有していないパッケージの移行

移行が他者のリポジトリへのプルリクエストとなる場合、たとえば genui に依存する pub.dev 上のパッケージの場合は、次の手順に従ってください。

1. まず、リポジトリの CI ワークフロー、タスクランナーとローカルゲートスクリプト、エージェント向けの指示（AGENTS.md、CLAUDE.md、.cursor/rules/ など）、CONTRIBUTING.md（PR のマージ前に署名済み CLA を求めるものもあります）、コミットと PR タイトルの規約を確認してください（Conventional Commits に照らして PR タイトルを確認するリポジトリもあります。過去の履歴で使われている言語にも従ってください）。CI の手順は、変更の前後にローカルで実行してください。CI でスキップされる場合でも、サンプルと、移行対象に依存するリポジトリ内のすべてのパッケージで実行してください。CI で使われているツールチェーンのリリースを使用してください。リポジトリで固定されているツールチェーンのリリースをインストールできない場合は、チェックを実行する間だけ固定を緩め、記録されているすべての箇所で元に戻してください。
2. パッケージ名と公開クラス名は維持してください。新しい SDK で可能な限り、API の構造を維持し、破壊的変更をそれぞれ CHANGELOG.md の Unreleased 見出しの下に記載してください。バージョン番号はメンテナーに任せてください。
3. 古い SDK の API を示している README、サンプル、エージェント向けの指示を更新し、コンパイルできなくなったコードを学習させないようにしてください。
4. 移行に関係する変更だけをコミットしてください。
   • マニフェスト、追跡対象のロックファイル、依存関係の追加や削除によって変更される生成ファイル（プラグイン登録など）を含めてください。
   • ツールが独自に変更する編集内容（設定の書き換え、編集前に新しいツールチェーンで通常のインストールを実行すると発生するロックファイルの変更。これらは変更内容の説明に記載してください）、無関係な生成ファイルの変更、ローカルパスを保持する生成ファイルは含めないでください。完全な ignore ファイルがないリポジトリでは、ファイル名を指定してステージしてください。
   • 変更内容が依存関係の削除だけの場合、ロックファイルから削除されるのは、ほかで必要とされていないパッケージだけです。新たに解決を行っても、それ以外に変更が生じないことを確認してください。
   • 新しいツールチェーンで解決されたロックファイルには、プロジェクト自体のツールチェーン（CI、バージョンファイル）で使用できないリリースが選ばれる場合があります。追加される各パッケージがそのツールチェーンで使用できるか確認し、使用できないものはバージョンを固定してください。
5. 新しい依存関係により、より新しいバージョンが必要になる場合でも、パッケージの最低言語バージョンまたは SDK バージョンを維持してください。パッケージマネージャーは、依存関係の要件より古いツールチェーンを自動的に拒否します。一方、上限を引き上げると、パッケージ全体の言語のセマンティクスやフォーマットが変わることがあります。
6. このリポジトリのソースではなく、公開された SDK リリースの API をパッケージマネージャーのキャッシュで確認してください。リポジトリのソースは、リリース版より先行している可能性があります。
7. 移行のために変更する必要がなかった動作は、気づいた不具合も含め、そのままにしてください。代わりに、変更内容の説明でその不具合に触れてください。
8. アプリのリポジトリでは、随時更新されるドキュメント（アーキテクチャに関するメモ、README、ほかの言語のコメント）を更新してください。ただし、決定記録、仕様、当時の計画はそのままにし、プロジェクトのツールが指示する場合は、日付付きの実験をワークスペースと CI の対象外にしてください。変更した依存関係について決定記録の作成が必要なリポジトリでは、提案として記録を追加し、決定はオーナーに委ねてください。エージェント側が別の言語を使い、クライアントが記録をワイヤー形式のバージョンに変換する場合は、その変換を維持し、エージェントとその保存データを変更しないでください。

事例ガイドでは、これらのルールが各プラットフォームで何を意味するかを説明しています。Dart と Flutter については、 In a package you do not ownを参照してください。

ケースの追加

このスキルにガイドがないものを移行した場合は、次の移行がそこから始められるよう、ガイドを追加してください。

1. このファイルと同じ階層に references/<language>_<from>_to_<to>.md を作成します。ファイル名は references/dart_genui_to_1_0.md のようにします。
2. 既存のガイドと同じセクションを設けます。対象範囲とバージョンの前提条件、依存関係、各レイヤーの移行手順（変更前と変更後のコード）、チェックリスト、API マッピング、レシピ、動作の変更点を含めてください。
3. Step 4 の表に行を追加します。
4. テキストとプルリクエストについては、natural-writing と pr-hygiene に従ってください。