ae-generate-tracking-plan

ae-generate-tracking-plan

スキル間の連携

作業の残りがこのスキルの範囲外である場合、または必要な前提条件に別の機能が必要な場合は、連携プロトコルに従ってください。この実行で利用可能なスキルから、機能に基づいて選択し、検証済みのコンテキストを保持したうえで、残りのタスクを続行してください。このプロトコルがすでに読み込まれている場合は、再利用してください。

会話の言語：このスキルのドキュメントは英語ですが、ユーザーへの出力はすべて、必ずユーザーの入力言語で行ってください。 英語で入力された場合 → 英語で返信、中国語で入力された場合 → 中国語で返信、日本語で入力された場合 → 日本語で返信してください。 判断に迷う場合は、英語を既定としてください。 これは、セクションタイトル、フェーズ名、テンプレートのプロンプト、例文、選択肢一覧など、すべての出力に適用されます。 ⚠️ 重要：テンプレートのローカライズは CLI が行います。モデルでインポート済みのテンプレート内容を手動で翻訳しないでください。AE_LANG=<user_lang> を設定し、draft.meta.lang を記述したうえで、ae-cli tracking code import-template / ae-cli tracking plan draft を通じて再生成してください。正となる情報源には src/tracking/i18n モジュールを使用してください。 テンプレートが管理するローカライズ済みラベルを変更する前に、まず src/tracking/i18n で該当する翻訳を確認してください（例：resources/xlsx/sheets.ts、resources/xlsx/headers.ts、resources/xlsx/types.ts、resources/cli/*.json）。該当する翻訳が見つからない場合は、インポートされたテキストをそのまま保持し、ビジネス上の意味を書き換える前に確認してください。 識別子、CLI インポートに必要なテンプレート名、または追跡可能性のために引用する原文を除き、このドキュメント内の中国語のテキストを英語または日本語の返信にそのままコピーしないでください。

用語集

中国語	英語	備考
イベント計測設計	Tracking Plan	AE プロジェクトレベルのイベントとプロパティの定義
イベント計測テンプレート	Tracking Plan Template	業界／ジャンル別に事前作成された xlsx テンプレート
プラン名	Plan Name	ユーザー向けのプラン識別子
アプリケーションシナリオ	Application Scenario	アプリの機能を一文で説明したもの
素材の種類	Source Material Type	prd / chat / codebase / template / data
データサンプル／ファイルプロファイル	Data Sample / File Profile	ae-data-integration の inspect プロファイル（source_type: data）から取得した列→プロパティのマッピング元
ビジネス上の側面	Business Dimension	収益モデル、コアループ、機能エントリ、通貨体系
収益モデル	Revenue Model	IAA / IAP / mixed / subscription / commission
コアループ	Core Loop	ゲームプレイの中核となるループ（例：「ステージを周回 → コインを獲得 → ガチャでヒーローを入手」）
機能エントリ	Functional Entry	ステージ、ショップ、ギルド、ランキング、タスク、実績など
通貨体系	Currency System	有料通貨（ダイヤなど）、無料通貨（ゴールドなど）
イベント	Event	名前付きのユーザーアクションまたはシステム上の発生事象（event_name）
イベントプロパティ	Event Property	イベントに付随するデータ（prop_names）
共通／スーパーイベントプロパティ	Common/Super Property	すべてのイベントに自動で付与されるプロパティ。⚠️ AE で正しい中国語の用語は「公共事件属性」または「公共属性」です。「Super Property」を「超级属性」と訳してはいけません。これは AE で有効な用語ではありません。
ユーザープロパティ	User Property	ユーザープロファイル上のプロパティ（永続的な状態）
プリセットプロパティ	Preset Property	# が先頭に付くシステムプロパティ（#device_id、#time など）
自動トラッキングイベント	Auto-track Event	SDK によって自動収集されるイベント（ta_app_start、ta_page_show など）
システムイベント	System Event	SDK の自動トラッキングイベント（ta_*）用に予約された event_tag 値。モジュールに属さない 2 つのタグのうちの 1 つ（もう 1 つは基本イベント）。
基本イベント	Basic	アカウントレベルのライフサイクル／進行イベント（登録、ログイン、レベルアップ、ロール作成など）用の event_tag 値。機能モジュールには紐付きません。
機能モジュール	Functional Module	機能固有のビジネスイベント用の event_tag 値。イベントが属するモジュールを示します（例：バトル、ショップ、広告、決済、基本）。
SDK 統合モード	SDK Integration Mode	client_only / server_only / both / none
クライアントプラットフォーム	Client Platform	Android、iOS、Web、Unity、ミニプログラムなど
サーバー言語	Server Language	Java、Python、Go、Node.js、PHP など
ユーザー ID 体系	User Identity System	distinct_id の方針 + account_id の取得元
ゲスト ID	Visitor ID / Distinct ID	ログイン前の匿名 ID
アカウント ID	Account ID	ログイン後に識別されたユーザー
挿入	Insert	プロジェクトにコードを直接挿入すること
スニペット	Snippet	単独ファイルとして提供されるコード
オブジェクト配列	Object Array (array_row)	[{...}] — 関連するエンティティの可変長リスト
オブジェクト	Object (object)	{...} — 固定構造の単一エンティティ
検証	Validation	xlsx 生成前のドラフトルールチェック
アップロード	Upload	イベント計測設計の xlsx を AE にアップロードすること
追加	Append	既存のプランに新しいイベント／プロパティを追加すること
置換	Replace	既存のプランを削除して新しいプランをアップロードすること
競合検出	Conflict Detection	アップロード前に型の不一致やイベントの重複を検出すること
アーカイブ	Archive	最終版の draft.xlsx を plans/ ディレクトリにコピーすること
xlsx 形式仕様	xlsx Format Contract	AE 互換の Excel 生成に関する列のルール
draft.json	draft.json	イベント計測設計の内部中間表現（JSON）
display_name	Display Name	ユーザーの言語で表示する、人が読みやすい名前
event_tag	Event Tag	イベントが属する機能モジュール（例：バトル、ショップ、広告、決済）。自動トラッキングイベントには「システムイベント」を使用します。
snake_case	snake_case	標準的な命名形式：lowercase_with_underscores

トリガーするタイミング

ユーザーが「トラッキングプラン／トラッキングテンプレート／AE プラン／トラッキングの作成を手伝って」などと言及した場合にトリガーします。 対象アプリ種別：H5／Web／iOS／Android／ミニプログラム／Unity。手順を厳守してください。 Phase 0 → 1 → 2 → 3 → 4 の順に進め、手順を省略しないでください。

Phase 1／3／4 は ae-cli tracking CLI（ae-cli tracking plan draft ／ae-cli auth login／ae-cli tracking plan upload／ae-cli tracking plan delete）を使用して実行します。 すべての CLI コマンドの先頭に AE_LANG=<user_lang> を付けてください（例：AE_LANG=en ae-cli tracking plan draft ...）。 これにより、CLI の出力メッセージと生成される xlsx のヘッダーがユーザーの言語になります。 アップロードコマンドでは、サーバーがアップロードされた xlsx を同じシート／ヘッダー言語で解析できるよう、必ず --lang <user_lang> も指定してください。

言語ルール：新しく生成するコンテンツでは、draft.json のユーザー向けフィールド（display_name、event_desc、event_tag、 プロパティの display_name、プロパティの desc など）を、ユーザーの入力言語で作成してください。 すべてのイベント、イベントプロパティ、共通イベントプロパティ、ユーザープロパティには、空でない display_name が必要です。 正式な snake_case 識別子は、ユーザー向けの表示名の代わりにはなりません。 インポートしたテンプレートでは、これらのフィールドを手動で翻訳しないでください。テンプレートのシート名、ヘッダー、プロパティ型の表示値、CLI メッセージ、自動トラッキング／i18n 管理のラベルは、AE_LANG=<user_lang> と draft.meta.lang を介して src/tracking/i18n から取得する必要があります。 ローカライズされたラベルが必要な場合は、src/tracking/i18n を確認し、既存のリソースキー／値を使用してください。モデルで翻訳を独自に作成しないでください。 テンプレートの業務テキストをローカライズする必要があり、CLI／i18n リソースに該当するものがない場合は、インポートしたテキストをそのまま保持し、業務上の意味を書き換える前にユーザーに確認してください。 event_name、prop_name などの識別子フィールドのみ英語のままにします。プロパティ名は snake_case とし、イベント名はデフォルトで小文字にします。ユーザーから大文字表記を維持するよう求められた場合に限り、大文字を使用します。 このスキルではコマンドの動作のみを扱い、内部実装は扱いません。

---

Phase 0 — 起点（メッセージごとに質問は1つ）

手順 1：言語の初期化

ユーザーの入力言語から <user_lang> を判定します：中国語→zh、英語→en、日本語→ja、韓国語→ko。その他の言語は en とします。 CLI の出力と生成される xlsx のヘッダーをユーザーの言語にするため、以降のすべての CLI コマンドの先頭に AE_LANG=<user_lang> を付けてください。 xlsx をアップロードする際は、--lang <user_lang> も指定してください。draft.meta.lang／生成された xlsx の言語と一致させる必要があります。

以下の5項目を順番に収集してください。一度にすべて質問しないでください。

項目 1 — アプリケーションのシナリオ

次のように質問します：「アプリケーションのビジネスシナリオを教えてください。1文で要約してください。例：ユーザーが商品を閲覧して注文する EC サイト」

ユーザーの回答後、meta.scenario に記録し、meta.plan_name を生成します。

項目 2 — ソース資料＋ビジネスの観点（合わせて質問）

質問する前に、現在の実行環境がエージェントのサンドボックスかどうかを判断します。サンドボックスに用意された cli-token.json、制限付きのファイルシステムアクセス、ユーザーのローカルファイルが利用できないことなど、実行環境のコンテキストをもとに判断できます。サンドボックス内で何が見えるかを判断するためだけに、ユーザーに質問してはいけません。

サンドボックス環境で利用できる製品ドキュメントは、ユーザーが会話ワークスペースに添付／アップロードしたファイルを含め、サンドボックスのワークスペース内で読み取り可能なファイルに限られます。マウントまたは添付されていない限り、サンドボックス外の任意のローカルパスは読み取れません。コードベースはローカル資料の選択肢であり、コードベースが読み取り可能なワークスペース内にすでに存在する場合を除き、サンドボックス環境では非表示にする必要があります。選択肢を非表示にした場合は、表示するリストの番号を 1 から連番に振り直してください。番号を飛ばして表示してはいけません。

サンドボックス環境でない場合は、次のとおり正確に質問してください：

Choose your source material (up to 2):

1 - Product document (local path, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/xlsx/pptx/URL/images (png/jpg/jpeg/webp)
2 - Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
3 - Codebase (local project path; hidden in sandbox) — Analyze source code to extract events and properties
4 - Pre-built template (built-in industry and game genre templates) — Select a built-in template
5 - Modify existing tracking plan (local AE format xlsx file) — Import an existing tracking plan xlsx as baseline for modification; can be combined with Product doc / Description / Codebase, but NOT with Pre-built template
6 - Data sample / file profile (from ae-data-integration inspect) — Map data columns (CSV/Excel/JSONL) to events & properties from an inspect profile; single-source path, not combinable with other options

Reply with number(s), e.g. 1,5 or 4. Select up to 2 (option 6 is single-source).

サンドボックス環境の場合は、次のとおり正確に質問してください：

Choose your source material (up to 2):

1 - Product document (sandbox workspace path, uploaded attachment, URL, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/xlsx/pptx/URL/images (png/jpg/jpeg/webp). You can attach/upload relevant files here.
2 - Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
3 - Pre-built template (built-in industry and game genre templates) — Select a built-in template
4 - Modify existing tracking plan (sandbox workspace path) — Import an existing tracking plan xlsx as baseline for modification; can be combined with Product doc / Description, but NOT with Pre-built template
5 - Data sample / file profile (from ae-data-integration inspect) — Map data columns (CSV/Excel/JSONL) to events & properties from an inspect profile; single-source path, not combinable with other options

Reply with number(s), e.g. 1,4 or 3. Select up to 2 (option 5 is single-source).

このソース資料リストを、番号なしの箇条書き、カード、文章に書き換えないでください。ユーザーが表示されている番号で回答できるようにする必要があります。 このプロンプトを翻訳する際は、数字の接頭辞と改行を正確に維持してください。表示される各選択肢は必ずそれぞれ別の行に置き、必ず 1 -、2 -、3 - などで始めてください。番号付きの選択肢を同じ段落や表示行に複数置かないでください。Markdown レンダラーがソフト改行を詰めて表示する可能性がある場合は、空行ではなく、改行の前に半角スペースを 2 つ付ける Markdown のハード改行を使用してください。変更できるのは選択肢のテキストのみで、番号の接頭辞や「1 行につき 1 つの選択肢」という構造は変更しないでください。

ユーザーは複数選択できます（最大 2 件）。番号は、サンドボックスではない正規リストではなく、ユーザーに表示されたリストに基づいて解釈してください。

正規のソース資料オプション（サンドボックスではない場合の番号）：

1. 製品ドキュメント ****(****ローカルパス、サンドボックスのワークスペースパス、アップロードされた添付ファイル、URL、画像ファイル、またはフォルダー) — 製品ドキュメントからイベントとプロパティを抽出します。md/pdf/docx/xlsx/pptx/URL/画像（png/jpg/jpeg/webp）に対応しています
2. 詳細な説明（会話形式）— アプリのビジネスフロー、主要機能、ユーザー行動、収益化モデルなどを説明します
3. コードベース（ローカルプロジェクトパス。サンドボックスでは非表示）— ソースコードを分析してイベントとプロパティを抽出します
4. 事前構築済みテンプレート（組み込みの業界別・ゲームジャンル別テンプレート）— 組み込みテンプレートを選択します（利用可能なテンプレートを確認するには AE_LANG=<user_lang> ae-cli tracking plan list-templates --json を実行してください）

ユーザーの選択に基づいてソース資料の種類を特定し、meta.source_type に記録してください。

選択	source_type	処理方法
製品ドキュメントのみ	prd	製品ドキュメント（テキスト／画像）を読み取り、イベントとプロパティを抽出します
説明のみ	chat	説明に基づいてドラフト段階でイベントを作成します
コードベースのみ	codebase	ソースコードをスキャンし、ビジネスロジックからイベント／プロパティを抽出します
テンプレートのみ	template	組み込みテンプレートの選択肢を提示します
既存プランのみ	existing_plan	xlsx をベースラインとしてインポートします（「既存トラッキングプランの変更フロー」を参照）
データサンプルのみ	data	検査プロファイル（ae-local-data-profile/v1）を読み取り、列をイベント／プロパティに対応付けます（下記の「データパス（source_type = data）」を参照）
2 項目の組み合わせ	2 つのタイプを _ で結合します	1 つ目をベースライン、2 つ目を補足情報として扱います（優先順位：existing_plan → template → codebase → prd → chat）
既存プラン + 事前構築済みテンプレート	許可されません	どちらもイベントのベースラインを提供するため、意味上の競合が生じます
データサンプル + その他	許可されません	データサンプルは単一ソース専用の経路です

追加質問（下記の複数ソースの組み合わせルールで定義されている順序で質問してください）：

• 製品ドキュメント → サンドボックス環境ではない場合、次の文をそのまま質問してください：

  What is the product document path?
  
  You can provide one or more items, separated by commas or newlines:
  1. Local file path
  2. URL
  3. Image file path
  4. Folder path
  

• 製品ドキュメント → サンドボックス環境の場合、次の文をそのまま質問してください：

  What is the product document path?
  
  You can provide one or more items, separated by commas or newlines:
  1. Sandbox workspace path
  2. Uploaded attachment path
  3. URL
  4. Image file path
  5. Folder path
  
  You can also attach/upload relevant files here, and I will read them from the sandbox workspace if available.
  

• 詳細な説明 → 曖昧すぎる場合は、主要機能、ユーザー行動、ビジネスフロー、収益化について追加で質問してください
• コードベース → **「プロジェクトディレクトリのパスを教えてください」**と質問してから、ソースをスキャンしてビジネスロジックを抽出してください
• 事前構築済みテンプレート → 該当するテンプレートを表示し、ユーザーに確認してください
• 既存のトラッキングプランの変更 → **「既存のトラッキングプランの xlsx ファイルパスを指定してください」**と質問してから、以下のフローに従ってください
• データサンプル → **「検査プロファイル JSON のパス（または、それが含まれる実行ディレクトリ）を指定してください」**と質問してから、ae-local-data-profile/v1 製品を読み取り、以下の「データパス（source_type = data）」フローに従ってください

既存のトラッキングプランの変更フロー（ユーザーがこのオプションを選択した場合）：

1. インポート：ユーザーにファイルパスを尋ね、すぐにインポートします：

   AE_LANG=<user_lang> ae-cli tracking code import-template --template <path> --out .ae-cli/draft.json
   

2. 結果を確認：

   • CLI でエラーが発生した場合（ファイルが見つからない／解析に失敗）→ エラーを報告し、ファイルを修正して再試行するようユーザーに依頼します
   • draft.json の events 配列が空の場合 → 🛑 重大：AE 形式のシートが見つかりません（#事件数据 のような # 接頭辞のシートがありません）。このファイルは AE トラッキングプランの xlsx ではないようです。元のファイルを修正して再インポートする必要があることをユーザーに伝えます。

3. コンテンツの検証（events が空でない場合）：

   AE_LANG=<user_lang> ae-cli tracking plan validate --in .ae-cli/draft.json --fix
   

4. 重大度に応じた検証結果の処理：

   • 検証に合格し、問題がまったくない場合 → ステップ 5 に進みます。

   重大度	例	対応	ユーザーの操作
   🔧 軽微（自動修正可能）	display_name の重複、array_row サブプロパティの不整合、イベント名の重複	--fix で自動修正し、draft.json に書き込みます。修正内容をユーザーに知らせます。	なし（通知のみ）
   ⚠️ 中程度（確認が必要）	プロパティ名が snake_case に準拠していない、プロパティ名の重複、無効なプロパティ型、ネストされたプロパティの親が複合型ではない	各問題について現在の値と修正案を提示します。draft.json に書き込む前に、ユーザーが項目ごとに確認します。	修正を項目ごとに確認
   🛑 重大	ファイルを解析できない、またはインポート後の events 配列が空	拒否します。該当する問題をユーザーに伝えます。ユーザーは元のファイルを修正して再インポートします。	元のファイルを修正

   中程度の問題の確認形式：

   ⚠️ The following content needs to be fixed:
   
   | # | Issue | Location | Current | Suggested |
   |---|-------|----------|---------|------------|
   | 1 | snake_case | event_name | UserLogin | user_login (keep UserLogin only if the user asked to preserve case) |
   | 2 | snake_case | prop_name | vipLevel | vip_level |
   | 3 | invalid type | property "level" | integer | number |
   
   Apply all suggested fixes? ok / specify per item / skip
   

   • ok → 提案された修正をすべて draft.json に適用します
   • specify per item → 項目ごとに順番に確認します
   • skip → 現在の値を維持し、後の調整フェーズで対応します

   ⚠️ ユーザーの元の xlsx ファイルは絶対に変更しないでください。 変更はすべて draft.json に書き込みます。

5. 修正後に再検証します → 問題がなくなるまで繰り返し、その後、次の追加質問（別のソース資料と組み合わせる場合）または項目 3（existing_plan が唯一のソースの場合）に進みます。

コードベース分析のフロー（source_type に codebase が含まれる場合）：

1. ユーザーからプロジェクトディレクトリのパスを受け取ります
2. ディレクトリ構造をスキャンし、技術スタック（エンジン／フレームワーク／言語）を特定します
3. 中核となるビジネスモジュールを読み取ります（ゲームロジック、シーン管理、UI 操作、状態／データモデル、ネットワーク／決済など）
4. コードから以下を抽出します：
   • イベント：プレイヤーのインタラクション操作（クリック／スワイプ／トリガー）、シーン遷移、ゲーム状態の変更（開始／一時停止／終了）、ビジネスフローのノード（購入／アップグレード／アンロック）
   • イベントプロパティ：アクションのパラメーター（弾の種類／敵のレベル／アイテム ID）、状態値（スコア／HP／コイン）、コンテキスト（レベル ID／難易度／モード）
   • ユーザープロパティ：永続状態（レベル／経験値／VIP／累計課金額）
5. 抽出結果を AE の命名規則に合わせます（イベント名はデフォルトで小文字、依頼があった場合のみ大文字を使用します。プロパティ名は snake_case、さらにユーザーの言語で display_name を追加します）
6. 抽出結果をユーザーに確認し、不足している項目を補います

ビジネスディメンションの確認：

ソース資料の確認後、source_type に基づいてビジネスディメンション情報を必ず処理します。先に進む前に、ユーザーによる明示的な確認が必要です。

source_type	対応
template	テンプレートから継承したビジネスディメンションをそのまま表示し、詳細な推定は省略します
existing_plan	既存プランの内容からビジネスディメンションを推定します（イベントモジュール、決済イベント、通貨プロパティを分析します）。不足項目を追加で確認し、イベント注入のプレビューを表示します
prd / codebase / chat	ビジネスディメンションを推定 → 不足項目を追加で確認 → イベント注入のプレビュー
組み合わせ（例：template_prd）	詳細なルールは以下を参照してください。ベースとなるソースの方法を優先し、補足ソースから追加のコンテキストを得ます

source_type が template、または template_ で始まる場合（template、template_prd、template_codebase、template_chat が該当します）：

テンプレートにあらかじめ設定されたビジネスディメンションを表示します：

Business Dimension (inherited from template: <template name>)

Revenue Model: <revenue_model>
Core Loop: <core_loop>
Functional Entries: <functional_entries>
Currency System: <currency_system>

Confirm using these business dimensions? ok / modify

• ユーザーが ok と入力した場合 → 次のステップに進みます
• ユーザーが「modify」と言った場合 → ユーザーが補足できるよう、prd/chat フローに切り替えます
• 組み合わせの場合（例：template_prd）：テンプレートのディメンションを確認した後、Phase 1.2 のコンテキストとして、prd/chat から得られた補足的な知見も記載します。

source_type に existing_plan が含まれる場合：

インポートしたプランの内容からビジネスディメンションを推測します。

1. 既存イベントを分析：event_tag の値を調べ、機能モジュールを特定します（例：「Battle」というタグが付いたイベント → 戦闘モジュール）。イベント名から課金や広告関連のパターンを調べ、収益モデルを推測します。
2. 推測結果の表示：推測結果を次の形式で要約します。

   Business Dimension (inferred from existing plan: <filename>)
   
   Revenue Model: <inferred from payment/ad events>
   Core Loop: <inferred from event flow>
   Functional Entries: <inferred from event_tag values>
   Currency System: <inferred from currency-related properties>
   
   Confirm these business dimensions? ok / modify
   

3. 不足情報の確認：推測できなかった項目のみ質問します
4. イベント追加プレビュー：追加を提案するイベントモジュールを表示します（プランにまだ含まれていないイベントのみ追加）。ユーザーが ok と入力した場合は次に進みます

• 組み合わせの場合（例：existing_plan_prd）：プランからディメンションを確認した後、Phase 1.2 のコンテキストとして、prd/chat から得られた補足的な知見も記載します。

source_type が prd / codebase / chat の場合：

1. 推測結果の表示：マッピングの基準として business-dimension-mapping.md を使用し、推測結果を要約して表示します
2. 不足情報の確認：「simple」と推測された項目、または情報が不足している項目のみ確認します
3. イベント追加プレビュー：追加を提案するイベントモジュールを表示します。ユーザーが ok と入力した場合は次に進みます

プラットフォームの検証：business-dimension-mapping.md の第 5 章の判断ルールを使用し、追加するイベントのプラットフォーム割り当てが妥当か確認します。

テンプレートの照合（prd / codebase / chat のシナリオで任意。existing_plan または template のシナリオには適用されません）：

ビジネスディメンションの確認後、アプリの種類に基づいて一致するテンプレートを自動検出します。

AE_LANG=<user_lang> ae-cli tracking plan list-templates --json

一致したテンプレートをユーザーに提示して確認します。確認済みのテンプレートはベースラインとして使用し、Phase 1 のイベント統合に含めます。

複数ソースの組み合わせルール（ユーザーが2つのソース素材を選択した場合）

追加質問の順序（フェーズ0の質問順）：

ユーザーの選択順には従わないでください。代わりに、次の順序を使用してください。

existing_plan（blocking validation, always first）→ codebase/prd（user's selection order）→ chat → template

理由：

• existing_plan を最初に処理する必要があります。インポートと検証の際に、ユーザーがファイルを修正する必要が生じる可能性があるため、早い段階で処理すればコンテキストの無駄を避けられます。
• codebase ／ prd は実際のビジネス要件を直接反映するため、汎用的な説明やテンプレートより優先します。
• chat は会話形式の説明であり、ビジネスコンテキストを補足します。
• template は汎用的な業界テンプレートであり、ユーザーのビジネスに対する具体性が最も低いものです。

ソース素材の処理は、主にフェーズ1.2（ソース素材のマージ）で行います。例外は existing_plan のみです。ユーザーが提供したファイルは続行前に修正が必要な場合があるため、フェーズ0でインポートして検証します。それ以外のすべてのソースは、標準フローに従ってフェーズ1.2で処理します。

マージの優先順位（フェーズ1.2）：existing_plan → template → codebase → prd → chat → autotrack
先にあるソースが優先されます。同名のイベントは先にあるバージョンを維持し、後続のソースは新しいイベントの追加、または上書きせずに prop_names をマージする場合にのみ使用します。

ビジネス次元の推定（複数ソースの組み合わせシナリオ）：

ベースラインソースの推定方法を主軸として使用します。補足ソース（特に prd ／ chat）から追加情報を取り入れてもかまいません。統合した内容をユーザーに提示し、確認を受けてください。

有効な組み合わせ：

「ベースライン」列は、ユーザーの選択順とは異なる場合があるマージ優先順位の高いソースを示します（フェーズ1.2のマージ順を参照）。追加質問では、ユーザーの選択順ではなく、上記の「複数ソースの組み合わせルール」で定めた固定順序を使用してください。

ベースライン	補足	補足ソースについてフェーズ0で行うこと
existing_plan	codebase	パスを取得し、テクノロジースタックを簡易検出する
existing_plan	prd	パスを取得する
existing_plan	chat	説明を取得する。次元の推定にも参加する
template	codebase	パスを取得し、テクノロジースタックを簡易検出する。テンプレートの照合とインポートはフェーズ1.2まで保留する
template	prd	パスを取得する。テンプレートの照合とインポートはフェーズ1.2まで保留する
template	chat	説明を取得する
codebase	prd	パスを取得する
codebase	chat	説明を取得する
prd	chat	説明を取得する
codebase	template	上記の template+codebase の行と同じ（マージ優先順位では template がベースライン）
prd	template	上記の template+prd の行と同じ（マージ優先順位では template がベースライン）

禁止：existing_plan + template（どちらもイベントのベースラインを提供するため、意味上の競合が発生します）。

ビジネス次元の情報を meta.business_dimension に記録する：

"business_dimension": {
  "revenue_model": "<model>",
  "core_loop": "<description>",
  "functional_entries": ["<entry list>"],
  "currency_system": { ... },
  "ad_scenes": [],
  "iap_items": []
}

データパス（source_type = data）— 単一ゲートの簡略フロー

ユーザーが データサンプル／ファイルプロファイル オプション（source_type = data）を選択した場合、標準の5項目アンカーとは異なるフローになります。このパスでは、ビジネス理解からイベントを新たに作成するのではなく、テーブル列をイベント／プロパティに対応付け、5セグメントの Refine ループの代わりに単一の確認ゲートを使用します。

スキップする項目（項目1「アプリケーションシナリオ」と項目2「データサンプル」のみを収集します）：

• 項目3（SDK 統合設定） → スキップします。meta.sdk_integration_mode = "none"（データは RESTful ／ LogBus ／ DataX 経由で取り込まれ、SDK は使用しません）。SDK の自動追跡イベントは注入されません（フェーズ1.4ではすでに none をスキップしています）。
• 項目4（ユーザー ID システム） → ビジター ID 戦略に関する質問をスキップします。代わりに、inspect プロファイルの identity_candidates（たとえば distinct_id ／ account_id 列）から meta.user_identity を導出します。アカウント列がある場合は account_id_source: "user_account"、ない場合は "none" とします。
• ビジネス次元の確認 → スキップします。マッピングは収益モデルやコアループではなく、列に基づいて行われます。meta.business_dimension は空のままにします。

ドラフトの作成（データパスではフェーズ1.1／1.2／1.3を置き換えます）：

1. inspect プロファイルを読み込みます：ae-local-data-profile/v1 JSON プロダクト（列／型／サンプル／UE 対象可否／マッピングの信頼度）を確認します。存在しない場合、または古くなっている場合は、まずソースファイルに対して ae-cli data-integration inspect を再実行します。
2. イベントモデルを決定します（UE ルーティングを再利用）：単一テーブル・単一イベントの track／単一テーブル・複数イベント（イベント名列）／単一テーブルの user_set／混在。エージェントは、1つのテーブルを複数のイベントに分割することを提案できます（例：広告テーブルを campaign_type に基づいて ad_show／ad_click に分割）。そのような提案は、ゲートで必ず確認する必要があります。
3. 列からプロパティへのマッピング案：
   • まずシステム列を特定します：時刻フィールド、distinct_id／account_id、イベント名列、ユーザープロパティ名列。
   • 残りの列をイベントプロパティ／ユーザープロパティ／スーパー プロパティにマッピングします。
   • 命名規則：プロパティ名は snake_case、イベント名はデフォルトで小文字（依頼があった場合のみ大文字）とし、display_name + desc + event_tag を付与します（言語はユーザーの入力に合わせます）。
   • 型の推定：CSV 列はデフォルトで string とします。フィールド名、値の分布、業務ドキュメント／プロンプトの事前情報に基づいて、number／bool／datetime／enum を推定します。不確かな列や矛盾のある列には「to-confirm」のマークを付け、ゲートでのみ確認します（事前に列ごとに質問しないでください）。
4. 確認ゲートは1回のみ（以下の Phase 2 を置き換えます）。
5. 既存の計画とマージします（Phase 4.1／4.2 の競合検出を再利用します）。
6. 保存：.ae-cli/draft.json → xlsx → アップロード（sdk_integration_mode = none）。

確認ゲート（1回、サマリーテーブル1つ）：

以下の内容をすべて含む統合テーブルを1つのメッセージで提示し、ユーザーからの返信を1回だけ待ちます：

• イベント一覧：event_name／display_name／desc／event_tag／platform。
• プロパティ一覧：name／display_name／type／desc／source。不確かな型には「to-confirm」のマークを付けます。
• フィールド範囲：デフォルトでは計画内で使用するフィールドのみとし、ソース列をすべて取り込むための全件インポート切り替えを含めます。
• 未認識データ／不正データの処理：マッピングされていない列、null 値、解析できない行の扱い。
• 同名プロパティの型の競合：ゲート内でインライン表示します（Phase 4.2 の Type A を参照）。

ユーザーは1回だけ返信します：すべて承認する場合は ok、または対象を指定して編集します（個々の列やイベントの名前変更／型変更／追加／削除）。ゲートの確認後は Phase 3（プロジェクトトークン）、続いて Phase 4（マージ＋アップロード）に進み、5セグメントの Refine ループには入らないでください。

dry-run モード：

ユーザーが dry-run を依頼した場合（または呼び出し元が data-integration plan --dry-run を渡した場合）、ドラフトのプレビューと列からプロパティへのマッピングのサマリーのみを生成します。

• 確認ゲートのテーブル（イベント＋プロパティ＋フィールド範囲＋未認識データの処理）とマッピング結果を表示しますが、.ae-cli/draft.json は書き込みません。
• xlsx を生成せず、plans/ にアーカイブせず、AE にアップロードしません。
• 何も保存されていないことを明示します。ユーザーは後から通常の実行を承認できます。

項目 3 — SDK 統合設定（クライアント＋サーバー）

質問：「クライアントのプラットフォームは何ですか？（複数選択可。例：Android＋iOS）サーバー側 SDK を統合しますか？」

項目 3 のこの質問をした後は、停止してユーザーの回答を待ってください。同じ応答で項目 4 を表示しないでください。

言語フィルター：以下の SDK は中国語のみのドキュメントを提供しており、中国語ユーザーにのみ表示されます：Mini-program、Mini-game、OpenHarmony、LayaAir、Egret、Cocos2d-Lua。中国語以外のユーザーには表示しないでください。

クライアント統合（複数選択可）：

選択肢	クライアント SDK の種類
H5/Web アプリ	JavaScript SDK
モバイルゲーム - Android ネイティブ	Android SDK
モバイルゲーム - iOS ネイティブ	iOS SDK
モバイルゲーム - Unity	Unity SDK
モバイルゲーム - CocosCreator	CocosCreator SDK
モバイルゲーム - Cocos2d-x	Cocos2d-x SDK
モバイルゲーム - Cocos2d-Lua	Cocos2d-Lua SDK
モバイルゲーム - LayaAir	LayaAir SDK
モバイルゲーム - Egret	Egret SDK
モバイルゲーム - Unreal	Unreal SDK
モバイルアプリ - Android ネイティブ	Android SDK
モバイルアプリ - iOS ネイティブ	iOS SDK
モバイルアプリ - React Native	React Native SDK
モバイルアプリ - Flutter	Flutter SDK
モバイルアプリ - uni-app	uni-app SDK
モバイルアプリ - OpenHarmony	OpenHarmony SDK
ミニゲーム	ミニゲーム SDK（統合版。WeChat／QQ／TikTok／Baidu などに対応）
ミニプログラム	ミニプログラム SDK（統合版。WeChat／TikTok／Alipay／Baidu などに対応）
PC ゲーム - Unreal	Unreal SDK
PC ゲーム - Unity	Unity SDK
PC アプリ - C++	C++ SDK
PC アプリ - C#	C# SDK
PC アプリ - macOS ネイティブ	macOS SDK
PC アプリ - OpenHarmony	OpenHarmony SDK
クライアント SDK なし	なし（sdk_integration_mode: "server_only"）

プログラミング言語（Android／iOS SDK のみ）：

SDK の種類	対応言語
Android SDK	Java／Kotlin（複数選択可）
iOS SDK	Objective-C／Swift（複数選択可）
その他の SDK	言語は固定されており、選択不要

追加質問：Android SDK を選択した場合 → **「プログラミング言語はどれですか？ Java／Kotlin／両方」**と質問します。 追加質問：iOS SDK を選択した場合 → **「プログラミング言語はどれですか？ Objective-C／Swift／両方」**と質問します。

client_platform_languages に記録します：

"client_platform_languages": {
  "android": ["java", "kotlin"],
  "openharmony": ["typescript"]
}

⚠️ マルチプラットフォームのメタフィールドのルール：クライアントプラットフォームが 2 つ以上選択されている場合、Draft メタでは client_platforms（配列）と client_platform_languages（辞書）を必ず使用してください。プラットフォームを 1 つしか記録できない client_sdk_type（単一値）と client_language（単一値）のみを使用しないでください。単一プラットフォームの場合は client_sdk_type と client_language を使用します。

サーバー統合：

選択肢	サーバー SDK の種類	sdk_integration_mode
Java	Java SDK	both
Python	Python SDK	both
Go	Go SDK	both
Node.js	Node SDK	both
PHP	PHP SDK	both
C#／.NET	C# SDK	both
C++	C++ SDK	both
Erlang	Erlang SDK	both
Lua	Lua SDK	both
Ruby	Ruby SDK	both
その他	使用言語を追加で質問し、SDK の提供状況を wiki で確認	both
サーバー SDK なし	なし	client_only または none

SDK 統合モードの自動判定：

クライアント統合	サーバー統合	sdk_integration_mode
はい	はい	both
はい	いいえ	client_only
いいえ	はい	server_only
いいえ	いいえ	none（RESTful／LogBus／DataX のデータ取り込み）

none モード：過去データのインポート、一括データ同期、サードパーティシステムとの統合などに適しています。Refine フェーズでは SDK の自動トラッキングイベントは挿入されません。

項目 3 の確認ステップ：

ユーザーが項目 3 に回答したら、SDK 設定を正規化し、不足している追加質問（Android／iOS のプログラミング言語、またはサーバー言語が Other の場合の質問）のみを行います。

次に、正規化した SDK 設定を要約し、次のように質問します：「この SDK 統合設定でよろしいですか？続行して項目 4 に進む場合は ok と返信するか、変更内容を説明してください。」

ユーザーがこの SDK 統合設定を明示的に確認するまで、項目 4 を表示したり、識別情報に関する質問をしたりしないでください。

項目 4 — ユーザー ID システム（ビジター ID とアカウント ID の組み合わせ）

質問：「ビジター ID の生成方法は何ですか？」

選択肢：

• auto — SDK が自動生成します（デフォルト。ほとんどのシナリオに適しています）
• device_id — デバイス ID を使用します（iOS IDFV／Android AndroidID）
• custom — カスタムのビジター ID（SDK の初期化直後に identify() を呼び出す必要があります）

追加質問：custom を選択した場合 → 「ビジター ID にはどの値を使用しますか？ 例：デバイス ID／UUID／ゲスト一時 ID」

---

質問：「アカウント ID の取得元は何ですか？」

選択肢：

• user_account — ユーザーアカウント ID（ログイン後の一意な識別子）
• role_id — ロール ID（ゲーム固有。1 つのアカウントで複数のロールを持てます）
• none — アカウントシステムなし（完全なゲストモード）

追加質問：

• user_account を選択した場合 → 「アカウント ID に使用する具体的な値は何ですか？ 例：user_id（ユーザー ID）、phone（電話番号）、email（メールアドレス）」
• role_id を選択した場合 → 「ロール ID はゲームに適しています。1 つのアカウントで複数のロールを作成できるため、ロールごとの行動をより詳細に分析できます」

meta.user_identity に記録します：

---

フェーズ 1 — ドラフト

1.1 標準ドラフトの構築

概念構造を作成します（内部 JSON。ユーザーには直接表示されません）：

Draft
├── meta:
│   ├── app_type:                   App type
│   ├── sdk_integration_mode:       SDK integration mode: client_only / server_only / both
│   ├── client_platforms?:          Client SDK type list (required when multi-platform, e.g. ["android","ios"])
│   ├── client_sdk_type?:           Primary client SDK type (single platform, backward compatible)
│   ├── client_platform_languages?: Per-platform languages (required when multi-platform, e.g. {"android":["kotlin"],"ios":["swift"]})
│   ├── client_language?:           Client dev language (single platform, backward compatible)
│   ├── server_language?:           Server dev language (only when server_only or both)
│   ├── project_id?:                AE project ID (filled in Phase 3)
│   ├── host?:                      AE web address (filled in Phase 3)
│   ├── plan_name:                  Plan name
│   ├── lang:                       xlsx output language (zh/en/ja/ko), based on user's current language; controls generated xlsx headers/sheet names
│   ├── scenario:                   Business scenario description
│   ├── source_type:                Source material type
│   ├── user_identity:              User identity config
│   │   ├── account_id_source:      Account ID source: user_account / role_id / none
│   │   ├── account_id_field?:      Account ID field name (only when user_account, e.g. user_id / phone / email)
│   │   ├── distinct_id_strategy:   Visitor ID strategy: auto / device_id / custom
│   │   └── distinct_id_custom_value?: Custom visitor ID value
│   └── business_dimension:         Business dimension config (injected in Phase 1.3)
│       ├── revenue_model:          Revenue model: IAA / IAP / mixed / subscription / commission
│       ├── core_loop:              Core gameplay loop description
│       ├── functional_entries:     Functional entry list
│       ├── currency_system:        Currency system
│       ├── ad_scenes:              Ad scenes (IAA / mixed only)
│       └── iap_items:              IAP items (IAP / mixed only)
├── events:                         Event array, each with platform field
├── event_properties:               Global event property pool (deduplicated)
├── common_event_properties:        Common/super properties (attached to every event)
└── user_properties:                User properties

SDK 統合モードのフィールド：

// Multi-platform example (Android + iOS)
{
  "sdk_integration_mode": "both",       // client_only / server_only / both
  "client_platforms": ["android", "ios"],   // Required for multi-platform
  "client_platform_languages": {            // Required for multi-platform; per-platform languages
    "android": ["kotlin"],
    "ios": ["swift"]
  },
  "server_language": "java"                // Only when server_only or both
}

// Single platform example (backward compatible)
{
  "sdk_integration_mode": "client_only",
  "client_sdk_type": "android",            // Single platform
  "client_language": "kotlin"              // Single platform
}

イベントのプラットフォームタグ（events[].platform）：

{
  "event_name": "order_create",
  "display_name": "Order Create",
  "platform": "server",    // client / server / both
  "prop_names": ["order_id", "order_amount", "payment_method"],
  "source": "prd"
}

• platform: "client" — クライアント側からアップロードします（ユーザー行動イベント）
• platform: "server" — サーバー側からアップロードします（ビジネスデータイベント）
• platform: "both" — 両側からアップロードします（タイムスタンプを同期する必要があります）

プロパティオブジェクトの形式（event_properties／common_event_properties のプールエントリー）：

{
  "name": "order_amount",
  "display_name": "Order Amount",
  "type": "number",
  "desc": "Order total in cents",
  "source": "prd"
}

⚠️ フィールド名には name（prop_name ではありません）、display_name、type、desc、source を使用します。イベントでは prop_names: ["order_amount", ...] を使ってプロパティを参照します。これはプロパティの name を参照する配列（文字列配列）であり、プロパティオブジェクトではありません。

ユーザープロパティの形式（user_properties のプールエントリー）：

{
  "name": "vip_level",
  "display_name": "VIP Level",
  "type": "number",
  "desc": "Current VIP level of the user",
  "source": "chat",
  "update_type": "user_set"
}

update_type には、user_set（上書き）、user_setOnce（初回設定のみ）、user_add（数値の加算）、user_append（配列への追加）のいずれかを指定します。

ユーザー ID フィールド（meta.user_identity）：

{
  "account_id_source": "user_account", // Account ID source: user_account / role_id / none
  "account_id_field": "user_id",       // Account ID field name (only when user_account)
  "distinct_id_strategy": "auto",      // Visitor ID strategy: auto / device_id / custom
  "distinct_id_custom_value": null     // Custom visitor ID value description (only when strategy=custom)
}

プロパティの型（列挙型）：string／number／bool／datetime／ object（サブプロパティを持つ単一オブジェクト）／array_row（parent.child のネストに対応するオブジェクト配列）／array_string（文字列配列）

命名規則：プロパティ名には snake_case を使用します。イベント名はデフォルトで小文字にし、ユーザーから大文字の維持を求められた場合にのみ大文字を保持します。人が読める名前には display_name を使用します。

1.2 ソース資料の統合

統合順序：existing_plan → template → codebase → prd → chat → autotrack

先行するソースを優先します。同名のイベントは先行するバージョンを維持し、後続のソースは新しいイベントの追加、または既存イベントを上書きしない prop_names の統合にのみ使用します。

• existing_plan：Phase 0 ですでにインポートおよび検証済みです（「既存のトラッキングプランの変更フロー」を参照）。イベントはベースラインとして draft.json にあり、各項目には source: "existing_plan" が設定されています。優先度の高いソースからは新しいイベントのみを追加し、同名のイベントは existing_plan のバージョンを維持します。
• template：ユーザーが選択した業界テンプレート（以下の「テンプレート検索規約」を参照）をベースラインとして使用します。各項目には source: "template" が設定されています。
  • テンプレートは ae-cli によって、ae-cli パッケージのルートとユーザーのテンプレートディレクトリから解決されます。
  • インポートコマンド：AE_LANG=<user_lang> ae-cli tracking code import-template --template-name "<template name>" --out .ae-cli/draft.json
  • ⚠️ テンプレートのインポート直後に必ず検証してください（Phase 1.6 を参照）。テンプレートの内容が完全に正しいとは限りません。
  • ⚠️ インポート後にテンプレートの内容を手動で翻訳しないでください：draft.json を読み込んで display_name、event_desc、event_tag、またはプロパティの display_name／desc をモデルで翻訳しないでください。ユーザーが意味の書き換えを明示的に求めない限り、CLI／テンプレートリーダーが生成したインポート済みの業務上の内容をそのまま維持してください。
  • ⚠️ CLI が管理するローカライズには src/tracking/i18n を使用してください：AE_LANG=<user_lang> と draft.meta.lang によって、CLI メッセージ、xlsx のシート名、xlsx のヘッダー、プロパティ型の表示値、autotrack／i18n が管理するラベルが制御されます。これらが誤っている場合は、src/tracking/i18n にある既存の翻訳を確認し、ラベルを手作業で編集するのではなく、意図したロケールを指定して再生成してください。
  • ⚠️ テンプレートのラベルに、モデルが独自に翻訳を作成しないでください：ローカライズされたテンプレート管理のラベルを置き換えたり説明したりする際は、src/tracking/i18n のリソースにある正確な値を使用してください。対応するリソースがない場合は、テンプレートのテキストを維持し、意味を変更する前にユーザーに確認してください。
  • ⚠️ event_tag は自由形式でモデル翻訳する項目ではありません：业务事件／系统事件 を別の言語に手動で置き換えないでください。テンプレートのタグを維持するか、CLI が管理するシステムラベルについては src/tracking/i18n と autotrack の生成に任せてください。
• codebase：プロジェクトのソースディレクトリをスキャンし、ビジネスロジックからイベント／プロパティを抽出します。同名イベントは、既存フィールドを上書きせずに prop_names をマージします。新しい項目には source: "codebase" を設定します。
• prd：ユーザーから提供されたすべての製品ドキュメント（md／pdf／docx／xlsx／pptx／URL／画像）を読み込み、各ファイルからイベントとプロパティを抽出します。同名イベントは、既存フィールドを上書きせずに prop_names をマージします。画像ファイルは、UI 要素とインタラクションフローをマルチモーダルに解釈して分析します。新しい項目には source: "prd" を設定します。
  • **形式ごとに、以下の表に従って読み込んでください。**優先ツールを最初に使い、利用できない場合は読み込みを中断せず、代替手段を使用してください。

    形式	読み込み方法
    md	直接読み込む
    docx	pandoc -t markdown <file> を使用します。利用できない場合は markitdown <file> を使用します（未インストールの場合は pip install markitdown）。最後の手段として unzip -p <file> word/document.xml を実行し、テキストを読み取ります。
    pdf（テキスト）	テキストを抽出します（ネイティブ Read または PDF テキスト抽出ツール）。
    pdf（スキャン）	ページを画像に変換してから、ビジョン機能で読み取ります。
    xlsx	構造を保持するリーダー（openpyxl／pandas。未インストールの場合は pip install）で行／列を読み取ります。トラッキングテーブルでは行／列のレイアウトに意味があるため、フラット化された Markdown ダンプに頼らないでください。
    pptx	markitdown <file> を使用します（未インストールの場合は pip install markitdown）。
    png/jpg/jpeg/webp	マルチモーダルに解釈し、UI 要素とインタラクションフローを分析します。

  • **xlsx は、既存の 2 つの xlsx フローとは別の、3 つ目のソース資料の経路です。**人が読めるトラッキングテーブル（イベント／プロパティ／型の行）は、ここでは行ごとに読み取ります。AE 形式のトラッキングプラン xlsx は import-template を通し、CSV／Excel のデータサンプル はデータ経路（ae-cli data-integration inspect）を通します。一方の経路の入力を、もう一方の経路に流さないでください。
  • prd のパスがフォルダーの場合：ディレクトリ内のすべてのファイルを再帰的にスキャンします。
    • md/pdf/docx/xlsx/pptx → 上の表に従って読み込み、イベント／プロパティを抽出します。
    • png/jpg/jpeg/webp → マルチモーダルに解釈し、UI 要素とインタラクションフローを分析します。
    • サブディレクトリ → 再帰的に処理します。
    • その他のファイル → スキップします。
  • prd のパスが URL の場合：URL の内容を直接取得し、上記と同じルールで処理します。
• chat：ビジネスシナリオを固定するフェーズと、編集指示を洗練するフェーズで使用し、source: "chat" を設定します。
• autotrack：meta.client_sdk_type に基づいて SDK の自動トラッキングイベントを自動挿入します（client_only または both モードの場合のみ）。source: "autotrack" を設定します。

1.3 ビジネスディメンションイベントの注入

フェーズ 0 で収集した meta.business_dimension に基づいて、以下のルールに従い対応するイベントを注入します。

収益モデル → 必須イベント：

収益モデル	注入するイベント	説明
IAA	ad_show, ad_click, ad_reward_get	広告表示／クリック／報酬受け取り
IAP	payment, payment_fail	決済成功／失敗
mixed	IAA + IAP のすべてのイベント
subscription	subscription_start, subscription_renew, subscription_cancel	サブスクリプション開始／更新／キャンセル
commission	order_create, order_paid, commission_settled	注文作成／決済／コミッション精算

コアループ → イベントシーケンス：

ユーザーの core_loop の説明からノードのアクションを解析し、イベントにマッピングします。

例：「プレイヤーがステージを繰り返しクリアしてコインを獲得し、コインを使ってガチャでヒーローを獲得する」 → ステージモジュール：stage_start（ステージ開始）、stage_complete（ステージクリア）、stage_fail（ステージ失敗） → リソース獲得：token_get（コイン獲得、プロパティ：token_type=diamond、token_amount） → ガチャモジュール：gacha_draw（ガチャを引く）、pool_type（プールタイプ）、draw_count（抽選回数） → ヒーロー獲得：hero_get（ヒーロー獲得）、hero_id

機能エントリー → モジュールイベントグループ：

機能エントリー	イベント例	説明
ステージ	stage_start, stage_complete, stage_fail, stage_id	ステージ開始／クリア／失敗
ガチャ	gacha_draw, pool_type, draw_count, hero_get	ガチャを引く／プール／回数／獲得
ショップ	shop_open, shop_buy, token_balance	ショップを開く／購入／残高
ギルド	guild_join, guild_donate, guild_boss_start	ギルド加入／寄付／ボス戦
ランキング	rank_view, rank_refresh, rank_click	ランキング表示／更新／クリック
タスク	task_accept, task_complete, task_reward_claim	タスク受諾／完了／報酬受け取り
実績	achieve_unlock, achieve_reward_claim	実績解除／報酬受け取り
デイリーチェックイン	daily_sign, sign_reward_claim	デイリーサインイン／報酬受け取り

通貨システム → プロパティ設計：

通貨タイプ	イベント	プロパティ
ハード通貨（ダイヤ）の獲得	token_get	token_type=diamond、token_amount、token_balance、source
ソフト通貨（ゴールド）の獲得	token_get	token_type=gold、token_amount、token_balance、source
ハード通貨の消費	token_consume	token_type、token_amount、token_balance、consume_type
ソフト通貨の消費	token_consume	token_type、token_amount、token_balance、consume_type

注入ルール：

1. ビジネスディメンションイベントには source: "business_dimension" のマークを付けます
2. ソース素材のイベントと統合する際、同名のイベントはソース素材のバージョンを維持し、上書きしません
3. 収益モデルが none（収益化なし）の場合、収益関連イベントの注入をスキップします

1.4 SDK の自動トラッキングイベントを自動注入する

フェーズ 0 で収集した SDK 統合モードに基づいて、自動トラッキングイベントを注入するかどうかを決定します。

注入条件：

• sdk_integration_mode === "client_only" → 自動トラッキングイベントを注入します
• sdk_integration_mode === "both" → 自動トラッキングイベントを注入します（クライアント側のみ）
• sdk_integration_mode === "server_only" → 注入しません（サーバー SDK には自動トラッキング機能がありません）
• sdk_integration_mode === "none" → 注入しません（SDK がなく、他の方法でデータを取り込みます）

注入ルール：

1. 推奨イベントのみを注入します。オプションイベントは自動注入されません（オプションを有効にするかどうかは、Refine フェーズで確認します）
2. 自動トラッキングイベントは events 配列の末尾に配置し、source: "autotrack" としてマークします
3. 自動トラッキングイベントの event_tag は "System Event" に設定します
4. 自動トラッキングイベントにはプリセットプロパティのみを含めます（prop_names は空、またはプリセットプロパティ名のみを含みます）
5. # が先頭に付いたプリセットプロパティは、SDK によって自動収集されるため、event_properties プールには追加しません
6. クリーンアップと重複排除：CLI は次の処理を行います。
   • ユーザーが選択した SDK と一致しない、テンプレートまたは既存のプランから継承された自動トラッキングイベントを削除します。たとえば、Android／iOS 向けに作成されたテンプレートに ta_app_install、ta_app_start、ta_app_end が含まれていても、ユーザーが JavaScript SDK を選択した場合、JavaScript SDK はこれらをサポートしていないため、ta_app_* イベントは自動的に削除されます。
   • ユーザーが選択した SDK に対応する正しい自動トラッキングイベントを注入します。
   • イベント名をグローバルに照合して重複を排除します。下書きにすでに存在するイベントは注入しません（テンプレートから継承した正しい自動トラッキングイベントは保持されます）。

SDK の種類 → 推奨イベント（詳細は references/autotrack-events.md を参照してください）：

SDK の種類	推奨（自動注入）	オプション（Refine プロンプト）
Android／iOS	ta_app_install、ta_app_start、ta_app_end	ta_app_view、ta_app_click、ta_app_crash
JavaScript	ta_page_show、ta_page_hide	ta_pageview
WeChat ミニプログラム	ta_mp_launch、ta_mp_show、ta_mp_hide、ta_mp_view、ta_mp_share	ta_page_leave、ta_add_favorite、ta_mp_click
WeChat ミニゲーム	ta_mp_launch、ta_mp_show、ta_mp_hide	—
Unity	ta_app_install、ta_app_start、ta_app_end	ta_scene_loaded、ta_scene_unloaded
Unity WeChat ミニゲーム	ta_mg_launch、ta_mg_show、ta_mg_hide	ta_scene_loaded、ta_scene_unloaded
その他のゲームエンジン	ta_app_install、ta_app_start、ta_app_end	—

自動トラッキングイベントの用途に関する注意事項：

• 自動トラッキングイベントは、SDK に組み込まれた自動レポート機能です。同じ名前のイベントを手動で定義する必要はありません
• 例：JavaScript SDK の ta_page_show はページビューを自動収集するため、home_page_show、about_page_show などを定義する必要はありません
• テンプレートに自動トラッキングイベント（業界テンプレートの ta_app_install など）がすでに含まれている場合、CLI は重複して注入しません
• これらのイベントを使用するには、ae-generate-tracking-code フェーズで SDK の初期化時に対応するスイッチを有効にする必要があります

下書き JSON の例：

{
  "event_name": "ta_app_install",
  "display_name": "App Install",
  "event_desc": "Triggered on first app install; upgrades do not trigger; reinstall after deletion triggers",
  "event_tag": "System Event",
  "platform": "client",
  "prop_names": [],
  "source": "autotrack"
}

注：自動トラッキングイベントの platform は常に "client" です。自動トラッキング機能があるのはクライアント SDK のみだからです。

1.5 保存して xlsx を生成する

必ず先に draft.json を書き込み、その後に draft コマンドを実行してください。この手順を省略して、ae-cli tracking plan draft を直接実行しないでください。

• 下書きを .ae-cli/draft.json に保存します
• ⚠️ meta.lang を書き込みます：ユーザーの現在の言語（zh／en／ja／ko）に基づいて draft.meta.lang を設定し、生成される xlsx のヘッダー、シート名、型の値が AE プラットフォームの言語と一致するようにします
• 書き込み後にファイルが更新されたことを必ず確認してください（ファイルの更新日時または内容を確認します）。新しい内容を確認してから、xlsx を生成してください
• アップロード可能な xlsx を生成します。

AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx

1.6 ルール検証（必ず実行）

xlsx の生成時に自動検証を行い、AE トラッキングプランのルールへの準拠を確認します。

AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx --fix

検証ルール：

ルール	説明	自動修正
表示名の一意性	同じプロパティプール内で、display_name が重複してはいけません	✅ 区別できる接頭辞を追加
オブジェクト配列の一貫性	異なるイベント間で同じ array_row を使用する場合、サブプロパティが一致している必要があります	✅ 不足しているサブプロパティを補完
プロパティ名の snake_case	プロパティ名は ^[a-z][a-z0-9_]*$ に一致する必要があります	❌ 手動修正が必要
イベント名の形式	イベント名は ^[A-Za-z][A-Za-z0-9_]*$ に一致します。デフォルトでは小文字にし、リクエストがあれば大文字を維持します	❌ 手動修正が必要
プロパティ名の一意性	プロパティ名が重複してはいけません	❌ 手動修正が必要
イベント名の一意性	イベント名が重複してはいけません	✅ 後から出現した重複を削除

検証フロー：

1. CLI が draft.json を自動検証します
2. 修正可能な問題が見つかった場合 → 自動修正 → draft.json を更新 → xlsx を生成します
3. 修正不可能な問題が見つかった場合 → エラーとなり、draft.json の手動修正が必要です
4. 問題がない場合 → フェーズ 1.7 に進みます

注：異なるプロパティプール間では、表示名が同じでもかまいません（例：vip_level はイベントプロパティとユーザープロパティの両方にできます）。

フェーズ 0 の既存プラン検証との関係：基盤となるルールエンジンは同じですが、フェーズ 0 では、ユーザーが各修正を確認できるため、対話型の 3 段階（軽微／中程度／重大）を使用します。フェーズ 1.6 では、自動ドラフト生成の一部として実行されるため、バッチ処理の 2 段階（自動修正可能／手動修正が必要）を使用します。フェーズ 0 で「中程度（確認が必要）」となるルールは、ここでは「❌ 手動修正が必要」として表示されます。ルール自体は同じですが、対話型の確認がありません。

1.7 サマリーの表示

イベント数／イベントプロパティプールのサイズ／スーパー・プロパティ数／ユーザープロパティ数を Markdown テーブルでユーザーに表示し、成果物のパスも表示します。

表示後、ユーザーに次のように伝えます。

Phase 1 complete.
Next: Phase 2 — Refine to confirm the plan.

📁 テンプレート検索の規則

次のコマンドを実行して、利用可能なテンプレートを動的に検出します。

AE_LANG=<user_lang> ae-cli tracking plan list-templates --json

言語ルール：テンプレート名とテンプレートのビジネスコンテンツをモデルで翻訳してはいけません。CLI から返される名前、または src/tracking/i18n リソース内に見つかった名前のみをローカライズ名として使用してください。list-templates --json が元のテンプレートの name のみを返す場合、その名前はそのまま表示し、インポート時も変更せずに使用してください。ローカライズされたテンプレート固有のラベルを提示または変更する前に、src/tracking/i18n を参照してください。翻訳を独自に作成してはいけません。

組み込みテンプレートは、ae-cli によって ae-cli パッケージのルートから解決されます。ユーザーテンプレートは、ae-cli のユーザーテンプレートディレクトリから解決されます。ユーザーの現在のワークスペースから ./tracking-plan-template/... のパスを手動で組み立ててはいけません。

次の順序でディレクトリを検索します。

1. <ae-cli package root>/tracking-plan-template/ — バンドルされたテンプレート
2. ~/.ae-cli/templates/ — ユーザー提供のテンプレートディレクトリ

各テンプレートでは .md の抽出済みファイルが優先されます（同じ名前の .md が存在する場合は md パスを返し、存在しない場合は xlsx パスを返します）。 CLI から返されたテンプレート名を表示し、インポートには JSON 結果の name を正確にそのまま使用してください。インポート時に形式を自動検出します。

AE_LANG=<user_lang> ae-cli tracking code import-template --template-name "<template name>" --out .ae-cli/draft.json

---

フェーズ 2 — 調整（5セグメントのループ）

データパス（source_type = data）：この5セグメントのループはすべてスキップし、代わりに「データパス（source_type = data）」で定義されている単一の確認ゲートを使用してください。

以下の順序で、セグメントごとに1回ずつ会話します。

1. sdk_config（SDK 設定＋ユーザー ID、統合） — SDK の統合モード、プラットフォーム／言語、ビジター ID の戦略、アカウント ID の取得元、対応する SDK 呼び出しを表示します
2. business（ビジネスディメンション＋ビジネスイベント、統合） — 収益モデル、コアループ、機能エントリー、注入されたイベントモジュール（プラットフォーム別にグループ化）を表示します
3. autotrack（自動トラッキングイベント） — SDK の自動トラッキングイベントを別の表に表示し、有効化方法を説明します
4. common_props（スーパー プロパティ） — すべてのスーパー プロパティを表示し、使用シナリオと注意事項を説明します
5. props（イベントプロパティ＋ユーザープロパティ） — イベントごとにグループ化したイベントプロパティプールと、ユーザープロパティの表を表示します

セグメントごとの流れ：

1. 現在のドラフトの該当セクションを表示します
2. セグメント固有の確認質問をします。現在のセグメント番号、現在のセグメントキー、次のセグメントキーを必ず含めてください。

   Segment <n>/5 <segment_key> confirmed? Reply ok to continue to Segment <n+1>/5 <next_segment_key>, or describe changes.
   

   セグメント 5 の場合：

   Segment 5/5 props confirmed? Reply ok to archive the plan and continue to Phase 3, or describe changes.
   

3. ユーザーが自然言語で指示を出したら、.ae-cli/draft.json を更新して、次を再実行します。

   AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx
   

4. ユーザーが ok と返答したら、次のセグメントに進みます

ok は調整ステートマシンへの入力であり、メッセージの重複エラーではありません。ユーザーが ok を連続して複数回返答した場合は、ok ごとに順番に1セグメントだけ進めてください。確認を促す前に、新しいセグメントの見出しを表示してください。そうすることで、連続する確認が同じ質問の繰り返しに見えなくなります。

ユーザーはいつでも 「Go back to segment N」 と言って、任意のセグメント（N = 1-5）に戻ることができます。

---

sdk_config（フェーズ 2 セグメント 1）

SDK の統合設定とユーザー ID システムを表示します。

SDK Integration Config:
- Integration mode: <client_only / server_only / both / none>
- Client: <platform> (<language>)
- Server: <language>

User Identity Config:
- Account ID source: <user_account / role_id / none>
- Account ID field: <specific field>
- Visitor ID strategy: <auto / device_id / custom>

ユーザーが「ok」と返答するか、変更します。

---

business（フェーズ 2 セグメント 2）

ビジネスディメンションとビジネスイベントを表示します。

Business Dimensions:
- Revenue model: <IAA / IAP / mixed / subscription / commission>
- Core loop: <description>
- Functional entries: <list>
- Currency system: <hard currency / soft currency>

Injected Event Modules (grouped by platform):

Client events (platform=client):
- <event>: <display_name> — <event_desc>
- ...

Server events (platform=server):
- <event>: <display_name> — <event_desc>
- ...

Both-platform events (platform=both):
- <event>: <display_name> — <event_desc>

矛盾の検出：ビジネスディメンションがソース資料と矛盾する場合は、ユーザーに確認を求めるため、目立つようにフラグを立てます。

ユーザーが「ok」と返答するか、変更します。

---

autotrack（フェーズ 2 セグメント 3）

client_only または both モードの場合にのみ表示します。

SDK の自動トラッキングイベント一覧を、次の注記とともに表示します。

• これらのイベントは SDK によって自動収集されます。コード生成時に手動で track() を呼び出す必要はありません。SDK の初期化時に対応するスイッチを有効にしてください
• display_name または event_desc は変更できますが、イベント名は変更できません

ユーザーが「ok」と返答するか、変更します。

---

common_props（フェーズ 2 セグメント 4）

すべてのスーパー プロパティ（name ／ display_name ／ type ／ desc）を表示します。

注記：

• スーパー プロパティはすべてのイベントに付与されるため、ビジネス全体で共通するグローバルディメンションに最適です
• アプリの種類別の一般的なスーパー プロパティ：
  • H5／Web：channel（流入チャネル）、referrer_domain（参照元ドメイン）
  • モバイルアプリ：channel、app_version、platform
  • ゲーム：channel、vip_level、server_id
  • ミニプログラム：channel、scene
• 禁止事項：SDK のプリセットプロパティ（# プレフィックス）をスーパー プロパティとして設定しないでください

ユーザーが「ok」と返答するか、変更します。

---

props（フェーズ 2 セグメント 5）

イベントプロパティプール（イベントごとにグループ化）と、ユーザープロパティの表を表示します。

• イベントプロパティ：name ／ display_name ／ type ／ desc。event_tag ごとにグループ化します
• ユーザープロパティ：name ／ display_name ／ type ／ update_type ／ desc

ユーザープロパティの更新方法：

更新方法	説明	使用例
user_setOnce	初回のみ設定し、その後の更新は無視します	初回登録時刻、初回支払い時刻、初回チャネル
user_set	上書き更新し、常に最新の値を使用します	現在のレベル、現在の残高、ニックネーム、VIP ステータス
user_add	数値を加算します。累積値に適しています	合計チャージ額、合計ログイン日数、広告の合計視聴回数

ユーザーが「ok」と返答したら、すぐにアーカイブコマンドを実行してから、フェーズ 3 に進みます。

---

Refine Phase ヒューリスティックによる提案

• スーパー プロパティとイベント プロパティ：プロパティが3つ以上のイベントに表示される場合は、スーパー プロパティに昇格します。スーパー プロパティは、ビジネス全体で使用するグローバルなディメンション（channel、vip_level、ab_test_group）に適しています。
• 禁止事項：SDK のプリセット プロパティ（# プレフィックス）をスーパー プロパティとして設定しないでください。
• イベントにはプロパティが必要です：すべてのイベントに、意味があり説明可能なプロパティを少なくとも1つ設定してください。
• ネストされたプロパティ：array_row の親プロパティには、オブジェクトのグループを表す parent.child サブプロパティを設定します。

---

Phase 2 後 — 納品前のセルフチェック

⚠️ AE にアップロードする前に、以下のセルフチェックを完了する必要があります。問題があれば、アップロード前に修正してください。

命名規則のチェック

• イベント名とプロパティ名は、文字で始まっていますか？
• イベント名とプロパティ名には、文字、数字、アンダースコアのみが含まれていますか（中国語や空白は含まれていませんか）？
• 重複したイベント名や、同義のイベントが併存していませんか（例：order_create と create_order）？
• 同じプロパティ名に、複数の表示名や型が割り当てられていませんか？
• すべてのイベント、イベント プロパティ、共通イベント プロパティ、ユーザー プロパティに、ユーザーの言語による空でない display_name が設定されていますか？

収益モデルで必須となるイベントのチェック

収益モデル	必須イベント	チェック
IAA	ad_show、ad_click、ad_reward_get	[ ]
IAP	payment、payment_fail	[ ]
mixed	IAA + IAP のすべてのイベント	[ ]
subscription	subscription_start、subscription_renew、subscription_cancel	[ ]
commission	order_create、order_paid、commission_settled	[ ]

対になるイベントの整合性チェック

開始／終了で対になるイベント（例：battle_start／battle_end）では、同じ名前で同じ構造のオブジェクト配列を使用する必要があります。

• 開始イベントで報告されるオブジェクト配列のサブプロパティは、終了イベントでも同じ名前、同じ型である必要があります。
• チェック対象：ステージのペア（stage_start／stage_complete）、バトルのペア（battle_start／battle_end）、ガチャのペア（gacha_draw／hero_get）など

単位の説明チェック

• 金額フィールドに単位（セント／USD）が記載されていますか？
• 所要時間フィールドに単位（秒／ミリ秒）が記載されていますか？
• 残高フィールドが、チャージ後の残高または操作前の残高として明記されていますか？

列挙値のチェック

• 列挙値がイベントの説明に記載されていますか（10個以下）？
• 値が10個を超える場合、ディメンションテーブルを使用する旨の注記がありますか？
• null 値のフォールバック戦略が文書化されていますか（例：「不明なチャネル → unknown を使用」）？

オブジェクト配列の使用チェック

次の3つの条件をすべて満たす場合に限り、オブジェクト配列（array_row）を使用します。満たさない場合は、オブジェクトまたは通常のプロパティを使用してください。

1. イベント プロパティに、同じ型の複数のエンティティを記録する
2. 各エンティティについて、2つ以上のプロパティを記録する必要がある
3. エンティティ数が可変である

オブジェクトの使用チェック

次の条件に該当する場合は、オブジェクト（object）を使用します。オブジェクト配列とは区別してください。

• 1対1の関係 → object を使用します。例：ユーザーの現在の「装備」の詳細、プレイヤーが現在配置している「ヒーロー」（1体のみ）
• 1対多の関係 → array_row を使用します。例：「バックパックのアイテム」一覧、「編成中のヒーロー」一覧（複数）

簡単なルール：{...} の形のデータ → object を使用し、[{...}] の形のデータ → array_row を使用します。

---

フェーズ 2 後 — アーカイブ

5 つすべての「調整」セグメントが確定したら（セグメント 5 でユーザーが ok と回答したら）、直ちにアーカイブしてください。省略したり、遅らせたりしないでください。

AE_LANG=<user_lang> ae-cli tracking plan archive --draft .ae-cli/draft.json --xlsx .ae-cli/draft.xlsx --name "<plan_name>"

パラメーター	説明	例
--draft	draft.json のパス（必須）	.ae-cli/draft.json
--xlsx	draft.xlsx のパス（必須）	.ae-cli/draft.xlsx
--name	出力ファイル名のプレフィックスとして使用するプラン名（必須）	"AI SaaS Website Tracking Plan"

出力先は plans/<date>-<plan_name>.xlsx です。draft.json は meta.archived_at が設定されるよう更新されます。

アーカイブ後、ユーザーに次のように伝えてください。

✅ Archive complete
File path: plans/<date>-<plan_name>.xlsx

Next: Phase 3 — Upload to AE:
1. Login to AE to get token
2. Get AE project ID
3. Upload plan to AE

⚠️ 厳守事項：フェーズ 3 に進む前に、アーカイブを完了してください。フェーズ 3.1 の最初の質問をする前に、meta.archived_at が存在することを確認してください。

---

フェーズ 3 — トークンと projectId

フェーズ 3 の開始時に、ユーザーに次のように伝えてください。

## Phase 3 — Upload Preparation
Next steps:
1. Check active AE host and login status
2. Login to AE to get token if needed
3. AE project ID

3.1 アクティブな AE ホストとログイン状態を確認する

最初に AE のウェブアドレスを尋ねないでください。ae-cli にはアクティブな AE ホストが保存されており、認証コマンドから直接使用できます。

まず、現在の認証／ホストの状態を確認します。

ae-cli auth status

アクティブなホストが設定されている場合は、そのホストを .ae-cli/draft.json の meta.host に保存します。auth status が authenticated: true を報告した場合は、ログインを省略してプロジェクト ID に進みます。

ae-cli がアクティブなホストなし／AE ホスト未設定と報告した場合に限り、ユーザーに次のように尋ねます。

「AE のウェブアドレスは何ですか？」

ユーザーの回答後、その値を設定し、同じ値を .ae-cli/draft.json の meta.host に保存します。

ae-cli config set-host <host>

auth status が未認証を報告した場合は、エージェントの分割フローを使用します。AI エージェントからブロッキングする ae-cli auth login を直接実行してはいけません。

ステップ 1 — 認証 URL をリクエストし、制御をユーザーに戻します。

ae-cli auth login --no-wait

返された verification_url をユーザーに表示し、認証を完了するよう依頼します。次のステップで使うため、返された device_code を保持してください。

ステップ 2 — ユーザーが認証の完了を伝えたら、ログインを完了します。

ae-cli auth login --device-code <device_code>
ae-cli auth status

前のコマンドがアクティブなホストが設定されていないことを理由に明示的に失敗した場合を除き、ae-cli auth login --host <host> で再試行しないでください。その場合は、まずホストを設定してから、--no-wait を指定して分割フローを最初から実行してください。

よくあるエラーへの対処方法と自己復旧：

エラー	原因	ユーザーへの説明
Device authorize request failed	エージェントのランタイムが認証サービスに接続できない	デバイスコードが作成されなかったことを、正確なエラーを含めて報告します
not_mac	レガシーのブラウザートークンフローが試行された	分割フローのデバイスコードログインを再試行します。ブラウザートークンをユーザーに求めないでください
NO_TAB_FOUND	レガシーのブラウザートークンフローが試行された	分割フローのデバイスコードログインを再試行します。Chrome を開くようユーザーに求めないでください

トークンは 20 時間キャッシュされます。同じホストであれば、再認証は不要です。

3.2 AE プロジェクト ID を取得してドラフトを更新する

ユーザーに次のように尋ねます。「AE のプロジェクト ID は何ですか？AE Admin →『Project Settings』→『Integration Config』に移動して『Project ID』をコピーするか、AE システムの URL パラメーター currentProjectId=<id> を確認してください」

ユーザーから projectId を受け取ったら、.ae-cli/draft.json の meta.project_id を更新します。

---

フェーズ 4 — アップロード

フェーズ 4 の開始時に、ユーザーに次のように伝えてください。

## Phase 4 — Upload to AE
Checking project's existing plan...

4.1 プロジェクトの既存プランを確認する

アップロードする前に、プロジェクトにトラッキングプランがすでに存在するかを確認します。

AE_LANG=<user_lang> ae-cli tracking plan fetch --project <projectId> > .ae-cli/existing-plan.json

ユーザーがこのコマンドで使用できる到達可能な上書き先を明示的に指定しない限り、ここで --host を追加しないでください。エージェントのサンドボックスでは、ae-cli がサンドボックスから提供された cli-token.json からリクエスト先ホストを解決できます。古い Kubernetes 内部ホストを渡すと、このフォールバックが使われない可能性があります。

結果の判定：

• ファイルが空、またはコマンドエラーが 404 → プロジェクトにプランがありません。直接アップロードします
• ファイルに内容がある → プロジェクトに既存のプランがあります。概要と競合の検出を表示します

既存のプランがある場合に表示：

Project already has a tracking plan:
- Events: XX
- Event properties: YY
- Super properties: ZZ
- User properties: WW

Choose upload mode:
1. Append (keep existing plan, add new events/properties)
2. Replace (delete existing plan, upload new plan)

Append / Replace?

---

4.2 追加モードでの競合検出

ユーザーが「追加」を選択した場合、必ず競合を検出してください（AE の名前によるマージには、競合が黙って破棄されるリスクがあります）。

2 つのファイルを読み取ります：

• 既存のプラン：.ae-cli/existing-plan.json
• 新しいプラン：.ae-cli/draft.json

次の 2 種類の競合を検出します：

競合タイプ A：同名プロパティの型の不一致（重大）

AE のルール：同名のプロパティは同じ型である必要があります。そうでない場合、報告されたデータは破棄されます。

検出ロジック：

event_properties／common_event_properties／user_properties の 3 つのプロパティプールを比較します。

• 新しいプランの各プロパティについて、既存のプランに同名のプロパティがあるか確認します
• 同名で型が異なる場合 → property_type_conflict（重大なエラー）として記録します

競合の表示：

⚠️ Severe conflict: Same-name property type mismatch

The following properties have different types in the existing plan vs. new plan.
Appending will cause reported data to be discarded:

| Property Name | Existing Type | New Plan Type |
|---|---|---|
| order_amount | number | string |
| vip_level | string | number |

Suggestions:
1. Modify the new plan's property types to match the existing plan
2. Or choose "Replace" mode to redefine types

Continue append (without fixing) / Modify draft / Switch to replace?

競合タイプ B：同名イベント（参考情報）

AE の名前によるマージ：同名のイベントは上書きされず、新しい名前のイベントが追加されます。イベント名では大文字と小文字が区別されます（Purchase ≠ purchase）。大文字と小文字だけを変更しても、名前の変更ではなく新しいイベントが作成されます。

検出ロジック：

新しいプランの各イベントについて、既存のプランに同名のイベントがあるか確認します。

• 同名のイベントが存在する場合 → event_exists（参考情報。エラーではありません）として記録します

競合の表示（参考情報のみ）：

⚠️ Advisory: The following events already exist in the project (append mode will not overwrite)

- user_login (existing: 2 properties, new plan: 3 properties)
- order_create (existing: 5 properties, new plan: 5 properties)

After append:
- Existing event property associations will not change
- New properties for existing events will not be added
- New events will be added normally

Continue append? yes / no

---

4.3 アップロードのフロー

競合の検出結果に基づいて判断します。

検出結果	アクション
競合なし	そのままアップロード
参考情報のみ（タイプ B）	ユーザーの確認後にアップロード
重大な競合（タイプ A）	ユーザーが修正するか、置換に切り替え

アップロードコマンド：

AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json --lang <user_lang> [--replace]

• --replace を指定する場合：既存のプロジェクトプランを削除してからアップロードします（ユーザーが「置換」を選択した場合、または重大な競合により置換に切り替える場合）
• --replace を指定しない場合：AE の名前によるマージを行います（競合がない場合、または参考情報のみで、ユーザーが追加を確認した場合）

アップロードコマンドでは、--lang <user_lang> を明示的に指定する必要があります。--lang は生成された xlsx の言語および draft.meta.lang と一致している必要があります。AE_LANG は CLI メッセージと xlsx の再生成コンテキストにのみ使用されます。AE のユーザー言語設定 API は呼び出さず、--switch-lang も使用しないでください。xlsx の言語が誤っている場合は、アップロード前に意図した言語で xlsx を再生成してください。

AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx
AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json --lang <user_lang> [--replace]

アップロードが成功したら、AE Admin で確認するようユーザーに促します。完全な URL を提示してください（トラッキングプランのページ URL 形式：https://<host>/#/data/plan）。

次に、ae-cli を通じてアップロード済みのプランを読み戻し、表示名を、プロジェクトにすでに存在するイベント／プロパティのメタデータに同期します。

AE_LANG=<user_lang> ae-cli tracking plan get --project-id <projectId> --host <host>
AE_LANG=<user_lang> ae-cli tracking plan sync-display-names \
  --project-id <projectId> \
  --draft .ae-cli/draft.json \
  --host <host>

sync-display-names は安全に再実行できるよう設計されています。

• イベント／プロパティのメタデータで表示名が空欄の場合にのみ入力します。
• AE ですでに管理されている空欄でない表示名は上書きしません。
• missing_in_metadata は、そのイベント／プロパティがまだプロジェクトのメタデータに存在しないことを意味します。アップロードの失敗ではありません。該当する名前を報告し、最初の Debug または本番データが AE に届いた後、同じコマンドを再実行してください。
• missing_display_name_in_draft は、生成されたプランが不完全であることを意味します。不足しているローカライズ済みの display_name を追加し、xlsx を再生成して検証した後、アップロード／同期のフローを再実行してください。

---

4.4 アップロード失敗への対応と自動修正

アップロード時には --auto-fix オプションを使用してください（デフォルトで有効）。CLI がエラーを自動検出して修正します。

AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json --lang <user_lang> [--replace]

AE API のエラータイプ

エラータイプ	説明	自動修正
event_prop_display_duplicate	イベントプロパティの表示名の重複	✅ 識別用の接頭辞を追加
complex_event_property_should_has_same_child_property	オブジェクト配列のサブプロパティの不一致	✅ 不足しているサブプロパティを補完
event_name_duplicate	イベント名の重複	✅ 後続の重複を削除
property_type_conflict	プロパティ型の不一致（追加モード）	❌ 置換モードに切り替え

自動修正のフロー

CLI は次の処理を自動実行します。

1. xlsx を AE にアップロード
2. eventErrorMap にエラーがあるか確認
3. 修正可能なエラー → draft.json を自動修正 → xlsx を再生成 → 再アップロード
4. 最大 3 回繰り返します。上限を超えた場合は、ユーザーに手動での対応を促します

出力例：

🔧 Auto-fixing upload errors (attempt 1/3)...
Fixed: Fixed object array sub-property inconsistency, Fixed display name duplicate
[plan-upload] regenerated: .ae-cli/draft.xlsx

---

4.5 成功後のアクション

アップロードと表示名の同期が成功したら、AE Admin で確認するようユーザーに促します。完全な URL を提示してください （トラッキングプランページの URL 形式：https://<host>/#/data/plan）。同期の概要として、更新された件数、既存のまま保持された件数、プロジェクトのメタデータに名前がまだ存在しない項目を簡潔に記載します。

トラッキングコードの生成について尋ねます：

トラッキングプランのアップロードに成功しました。次にトラッキングコードを生成しますか？

• はい → ae-generate-tracking-code スキルを使用するようユーザーに案内します
• いいえ → プランのアーカイブ先 plans/<date>-<plan_name>.xlsx を伝え、いつでも続行できることを案内します

禁止事項

• すべての確認事項を一度に尋ねること
• フェーズ 3 を省略して直接アップロードすること
• .ae-cli/draft.json を経由せず、手動で xlsx を組み立てること
• ユーザー向けの出力（操作プロンプト、プランの概要、イベント／プロパティの説明）で「Super Property」を「超级属性」と翻訳すること — 正しい AE の中国語用語は「公共事件属性」または「公共属性」です
• スキル内で fetch を直接呼び出して AE API にアクセスすること — AE との通信はすべて、プロジェクトのスクリプト／CLI を経由する必要があります

---

内部リファレンス（コントリビューター向け。スキルの使用パスではありません）

• skills/ae-generate-tracking-plan/references/te-api.md — AE バックエンドエンドポイントのキャプチャに関するドキュメント
• skills/ae-generate-tracking-plan/references/xlsx-schema.md — xlsx 形式の仕様（書き込みルールと読み取り互換性）
• skills/ae-generate-tracking-plan/references/autotrack-events.md — SDK の自動トラッキングイベント定義（プラットフォームごとのイベント一覧と SDK タイプのマッピング）
• skills/ae-generate-tracking-plan/references/business-dimension-mapping.md — ビジネスディメンションからイベント／プロパティへのマッピング表（収益モデル／機能エントリー／通貨システムから挿入されるイベント）
• src/plan/types.ts — Draft の TypeScript 型定義