ae-generate-tracking-code

ae-generate-tracking-code

会話の言語：このスキル文書は英語ですが、ユーザーへの出力はすべて、ユーザーの入力言語で行う必要があります。 英語の入力 → 英語で返信、中国語の入力 → 中国語で返信、日本語の入力 → 日本語で返信。 判断に迷う場合は、英語を既定とします。 これは、セクションタイトル、フェーズ名、テンプレートのプロンプト、コードコメントなど、すべての出力に適用されます。 ⚠️ 重要：参考資料（Wiki の SDK ドキュメント、コード例など）の多くには中国語のテキストが含まれています。英語または日本語のユーザーに回答する際に中国語の資料を読む場合は、見出し、説明、コメントを必ずユーザーの言語に翻訳してください。参照元の言語は、ユーザーの言語ではありません。用語集を参照して、用語を正確に置き換えてください。 この文書に含まれる中国語のテキストを、英語または日本語の返信にそのままコピーしないでください。

ドキュメントリンクの言語：公式ドキュメントの URL を提示する場合、中国語ユーザーには lan=zh-CN、それ以外のユーザーには lan=en-US を使用してください。

用語集

中国語	英語	備考
埋点方案	トラッキングプラン	AE プロジェクトレベルのイベント／プロパティ定義
代码埋点	トラッキングコードの生成	プランから SDK／LogBus コードを生成すること
埋点代码	トラッキングコード	生成される SDK 初期化コード＋track() 呼び出し＋ヘルパー
输出方式	出力モード	insert（挿入）または snippet（ファイルでの提供）
插入	挿入	ユーザーのプロジェクトにコードを直接挿入すること
片段 / 代码片段	スニペット	.ae-cli/output/ 配下のファイルとして提供されるコード
采集端	収集プラットフォーム／プラットフォーム	イベントの送信元：クライアント、サーバー、または両方
客户端	クライアント	クライアント側 SDK（Android／iOS／Web など）
服务端	サーバー	サーバー側 SDK（Java／Python／Go など）
两端都采集	両方	クライアントとサーバーの両方で収集するイベント
SDK 集成模式	SDK 統合モード	client_only／server_only／both
用户体系	ユーザー ID 体系	distinct_id／account_id の方針
校验脚本	検証／デバッグスクリプト	トラッキングが機能することを確認するテストコード
LogBus2 配置	LogBus2 設定	LogBus2 ログ同期ツール用の daemon.json
LoggerConsumer	LoggerConsumer	イベントをローカルのログファイルに書き込むサーバー SDK のコンシューマー
BatchConsumer	BatchConsumer	イベントをバッチでアップロードするサーバー SDK のコンシューマー
公共属性	スーパー・プロパティ	すべてのイベントに自動的に付与されるプロパティ。⚠️ AE における正しい中国語用語は「公共属性」または「公共事件属性」です。「Super Property」を「超级属性」と訳さないでください。これは AE で有効な用語ではありません。
预置属性	プリセットプロパティ	# で始まるシステムプロパティ（例：#device_id、#time）
事件属性	イベントプロパティ	特定のイベントに設定するカスタムプロパティ
用户属性	ユーザープロパティ	ユーザープロファイルに設定するプロパティ
上报地址	SERVER_URL	データ取り込みエンドポイント（Web URL とは異なります！）
APP_ID	APP_ID	AE 管理画面 →「Integration Config」に表示されるアプリケーション ID
project_id	プロジェクト ID	AE プロジェクト識別子（APP_ID とは異なります）
自动采集	自動トラッキング	自動収集されるイベント（アプリのインストール、起動、表示、クリック）
埋点方案上传	プランのアップロード	トラッキングプランの xlsx を AE にアップロードすること

起動条件

ユーザーが「トラッキングコードを生成して」「Web トラッキングを追加して」「LogBus 設定を生成して」「サーバーサイドのレポートコードを生成して」などと依頼した場合に起動します。複数のプラットフォームに対応し、プラットフォームごとに個別に出力モードを選択できます。

フェーズ 0 — 前提の確認（1 メッセージにつき質問は 1 つ）

事前確認：draft.json から既存の設定を読み込む

まず、.ae-cli/draft.json が存在するか確認し、既存の設定を読み込みます。

設定項目	draft.json のフィールド	対応
AE プロジェクト ID	meta.project_id	値がある場合 → 確認する；ない場合 → 尋ねる
AE の Web アドレス	meta.host	値がある場合 → 確認する；ない場合 → 尋ねる
SERVER_URL	meta.server_url	値がある場合 → 確認する；ない場合 → プロジェクト設定からの検索を試し、見つからなければ尋ねる
APP_ID	meta.app_id	値がある場合 → 確認する；ない場合 → アクセス可能なプロジェクト一覧からの検索を試し、見つからなければ尋ねる
SDK の統合モード	meta.sdk_integration_mode	値がある場合 → そのまま使用する
クライアント SDK の種類	meta.client_platforms（優先）または meta.client_sdk_type	値がある場合 → そのまま使用する
サーバーの言語	meta.server_language	値がある場合 → そのまま使用する
ユーザー ID システム	meta.user_identity	値がある場合 → そのまま使用する

重要：project_id ≠ APP_ID であり、host ≠ SERVER_URL です。project_id と host がすでに設定されていても、SERVER_URL と APP_ID は個別に解決して確認する必要があります。まず検索し、検索できない場合、または結果が曖昧な場合にのみユーザーに尋ねてください。

マルチプラットフォーム対応：

• client_platforms が存在する場合（配列）：マルチプラットフォームのシナリオ — 各プラットフォームのコードを生成する
• client_sdk_type のみが存在する場合：単一プラットフォーム（後方互換）
• 例：client_platforms: ["android", "openharmony"] → Android と OpenHarmony のコードを生成する

言語対応：

• Android SDK：Java / Kotlin に対応（両方生成可能）
• iOS SDK：Objective-C / Swift に対応（両方生成可能）
• その他の SDK：言語は固定されており、選択不要

言語設定の参照元：

• meta.client_platform_languages を優先する（例：{"android": ["java", "kotlin"]}）
• 設定されていない場合、Android / iOS プラットフォームに限りユーザーに尋ねる

確認フロー：

• 値がある場合 → **「draft.json の設定を使用しますか：？ はい／新しい値を入力」**と尋ねる
• ユーザーが yes と回答 → draft の値を使用する
• ユーザーが新しい値を入力 → draft.json を更新し、新しい値を使用する

必須の設定項目（各項目を解決して確認してください）

⚠️ 重要：SERVER_URL と APP_ID は独立した設定項目です。draft.json に project_id と host があっても、必ず両方を解決して確認してください。project_id ≠ APP_ID、host ≠ SERVER_URL です。

1. APP_ID — ユーザーに尋ねる前に、可能であれば自動検索します。
   • meta.project_id がわかっている場合は、現在の host に対して ae-cli project info list を一度実行します。
   • projectId が meta.project_id と一致するプロジェクトを探します。
   • 一致するプロジェクトに appId がある場合は、次のように尋ねます。「プロジェクト <projectId> の APP_ID <appId> が見つかりました。これを使用しますか？ はい／新しい値を入力」
   • プロジェクトが見つからない、特定できない、または appId がない場合は、AE Admin →「Project Settings」→「Integration Config」から APP_ID をコピーするようユーザーに依頼します。
2. SERVER_URL — データ取り込みエンドポイントです（Web URL とは異なります。AE Admin →「Project Settings」→「Integration Config」→「Public URL」を入力してください）。
   • meta.project_id がわかっている場合は、ae-cli project info get --project-id <project_id> を一度実行してもかまいません。
   • 応答に serverUrl、pushUrl、push_url、receiverUrl、publicUrl、publicReceiverAddress、privateReceiverAddress などの受信 URL フィールド、または同等のデータ取り込みエンドポイントフィールドが明示的に含まれている場合に限り、返された値を使用します。
   • publicReceiverAddress と privateReceiverAddress の両方がある場合、ユーザーが内部／プライベートネットワークの受信先を明示的に必要としていない限り、生成するコードスニペットでは publicReceiverAddress を SERVER_URL として優先します。
   • 値が見つかった場合は、次のように尋ねます。「プロジェクト <projectId> の SERVER_URL <url> が見つかりました。これを使用しますか？ はい／新しい値を入力」
   • ⚠️「Public URL」は事前に入力されている場合のみ表示されます。空欄の場合、この項目は表示されません。
   • 対応方法：URL を運用チームに問い合わせるか、この手順をスキップします（コード内で SERVER_URL または PUSH_URL プレースホルダーを使用します）。

host の扱い（任意）：

• AE からプランを取得する必要がある場合（ローカルに draft.json がない場合）は、host を尋ねます。
• ローカルに draft.json がある場合、コード生成に host は必要ありません。
• Debug 検証の前に ae-cli config current を実行し、アクティブな host が対象の AE 環境と一致することを確認します。一致しない場合は、ae-cli config set-host <AE_HOST> を実行します。
• 既定では ae-cli tracking debug-device と ae-cli tracking debug-data を使用して Debug 検証を完了します。これらの CLI 機能を使用できない場合に限り、AE Debug ページを開くようユーザーに案内します。

xlsx ファイルのみがある場合（draft.json がない場合）

まず、.ae-cli/draft.json と .ae-cli/draft.xlsx の両方があるか確認します。

どちらもない場合 — 現在の環境では、トラッキングプランがまだ生成されていません。次の2つの選択肢があることをユーザーに伝えます。

1. 先にトラッキングプランを生成しますか？

   • はい → ae-generate-tracking-plan スキルの使用を提案します。
   • 参考：ユーザーから提供されたトラッキングプラン文書をソース資料として使用します。

2. すでにトラッキングプランがある場合

   • xlsx ファイルのパスを指定し、ae-cli tracking code import-template --template を使用してインポートします。
   • または、xlsx ファイルを .ae-cli/draft.xlsx に配置して、再実行します。

xlsx ファイルがある場合（ae-cli tracking code import-template --template で指定した場合、または .ae-cli/draft.xlsx に配置した場合）：

ステップ 1：xlsx ファイルを解析する

ae-cli tracking code import-template --template <xlsx-path> --out .ae-cli/draft.json

このコマンドは次の処理を行います。

1. xlsx からイベント、イベントプロパティ、スーパー プロパティ、ユーザープロパティを読み取ります。
2. イベントの platform フィールドから sdk_integration_mode を推測します。
3. draft.json を出力します（meta セクションには events と plan_name のみが含まれます）。

ステップ 2：xlsx から推測できる内容

フィールド	推測可能？	備考
イベント一覧	✅	#event data シートから取得
イベントプロパティプール	✅	#event data シートから取得
スーパープロパティ	✅	#super property シートから取得
ユーザープロパティ	✅	#user data シートから取得
sdk_integration_mode	⚠️ 一部可能	xlsx の「Platform」列から推測できます（client/server/both）。列がない場合は、必ず確認してください
client_platforms	❌	ユーザーへの確認が必要です
client_platform_languages	❌	ユーザーへの確認が必要です（Android/iOS のみ）
server_language	❌	ユーザーへの確認が必要です（sdk_integration_mode に server が含まれる場合のみ）
user_identity	❌	ユーザーへの確認が必要です
host / project_id	❌	確認するか、スキップしてください

「Platform」列の解析ルール：

• 空欄／列なし → プラットフォームを推測できません。デフォルトではクライアント側のコードを生成します（後方互換性あり）
• 客户端 / client → クライアント専用の収集。platform: "client" として解析されます
• 服务端 / server → サーバー専用の収集。platform: "server" として解析されます
• 客户端,服务端 / client,server / 服务端,客户端 / server,client → 両方のプラットフォーム。platform: "both" として解析されます

内部表現：xlsx の「Platform」列の値は、ae-cli tracking code import-template --template によって内部の platform フィールド値に解析されます：

• client → クライアント側の収集
• server → サーバー側の収集
• both → 両方のプラットフォーム

コード生成時のプラットフォームフィルタリング：

• クライアントコード：platform === "client" または platform === "both" のイベントのみを生成します
• サーバーコード：platform === "server" または platform === "both" のイベントのみを生成します
• xlsx にプラットフォーム列がない場合：クライアントとサーバーの両方について、すべてのイベントを生成します（後方互換性あり）

ステップ 3：不足している設定を確認する

以下の順番で、1 回のメッセージにつき 1 項目ずつ確認します。

1. SDK 統合モード：**「トラッキングはクライアント側とサーバー側のどちらから送信しますか？ client / server / both」**と質問します

2. クライアントプラットフォーム（sdk_integration_mode に client が含まれる場合のみ）： **「アプリのプラットフォームは何ですか？」**と質問します

   • Android / Android SDK
   • iOS / iOS SDK
   • OpenHarmony / OpenHarmony SDK（中国のユーザーのみ）
   • Web / H5（JavaScript SDK）
   • WeChat ミニプログラム（Mini-program SDK）（中国のユーザーのみ）
   • WeChat ミニゲーム（Mini-game SDK）（中国のユーザーのみ）
   • Unity ゲーム（Unity SDK）
   • Cocos ゲーム（CocosCreator / Cocos2d-x / Cocos2d-Lua / LayaAir — Cocos2d-Lua と LayaAir は中国のユーザーのみ）
   • React Native / Flutter / uni-app
   • その他

   → ユーザーが選択した後、Android または iOS が選択された場合のみ、次の質問をします：

   • Android → **「プログラミング言語は何ですか？ Java / Kotlin / both」**と質問します
   • iOS → **「プログラミング言語は何ですか？ Objective-C / Swift / both」**と質問します

3. サーバー言語（sdk_integration_mode に server が含まれる場合のみ）： **「サーバー側の言語は何ですか？」**と質問します

   • Java
   • Python
   • Go
   • Node.js
   • PHP
   • C# / .NET
   • その他

4. ユーザー ID システム：

   • アカウント ID の取得元：user_account / role_id / none
   • ビジター ID の方式：auto / device_id / custom

5. APP_ID / SERVER_URL：上記の検索優先フローで値を解決し、見つかった値をユーザーに確認します。見つからない値、またはユーザーが拒否した値のみを質問します。

ステップ 4：設定を統合してフェーズ 1 に進む

収集した情報を .ae-cli/draft.json の meta セクションに書き込み、フェーズ 1 に進みます。

---

ローカルのプランファイルがない場合

.ae-cli/draft.json または .ae-cli/remote-plan.json がない場合：

1. AE projectId — AE Admin から取得します

2. AE のウェブアドレス — プランの取得に必要です

3. ae-cli tracking plan fetch を実行して、トラッキングプランを取得します

   追加確認ルール（統合モードに基づいて、コードを生成するプラットフォームを判断します）：

   統合モード	コードを生成するプラットフォーム／側
   client_only	クライアントプラットフォーム 1 つ（プランの client_sdk_type から取得するか、確認します）
   server_only	サーバー言語 1 つ（プランの server_language から取得するか、確認します）
   both	クライアントプラットフォームとサーバー言語（両方が必要）

---

プラットフォームの定義

クライアントプラットフォーム（クライアント SDK に対応）：

プランのフィールド	プラットフォーム	SDK
android	Android	Android SDK
ios	iOS	iOS SDK
openharmony	OpenHarmony	OpenHarmony SDK
javascript	Web / H5	JavaScript SDK
miniprogram	ミニプログラム	ミニプログラム SDK
unity	Unity	Unity SDK
game_engine	ゲームエンジン	Cocos / Laya / Unreal

サーバー言語（サーバー SDK に対応）：

プランのフィールド	言語	SDK
java	Java	Java SDK
python	Python	Python SDK
go	Go	Go SDK
nodejs	Node.js	Node SDK
php	PHP	PHP SDK
csharp	C#	C# SDK

SDK ドキュメントのパス：

• このセクションに記載されている、ハードコードされた wiki のパスは使用しないでください。
• まず必ず references/sdk-index.md を読み、選択した SDK に記載されているパスを使用してください。
• references/sdk-index.md のパスがローカルの wiki ミラーに存在しない場合は、~/.ae-cli/wiki/raw/ の下を SDK 固有のキーワードで検索し、最新のメインドキュメントとして最適なものを使用してください。

---

出力モードの定義

各プラットフォームでは、次の 2 つの出力モードから選択できます：

モード	説明	パラメーター	成果物
insert	ユーザープロジェクトへ直接編集して挿入	プロジェクトパス（絶対パス）が必要	コードを対象ディレクトリに書き込み
snippet	Markdown を表示し、コードファイルを生成	パス不要	.ae-cli/output/<platform>-sdk.<ext>

サーバー側のデフォルト（サーバー向けに常に生成）：

• LoggerConsumer コード（insert または snippet。ユーザーの選択に合わせます）
• LogBus2 設定ファイル（.ae-cli/output/daemon.json）
• 公式ドキュメントへのリンク：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

スタンドアロンのオプション：

• debug — 検証スクリプト（テスト送信用のコードを生成）

---

フェーズ 1 — プランの読み込み

ae-cli auth login --host <host>
ae-cli auth status
ae-cli tracking plan fetch --project <projectId> --host <host> > .ae-cli/remote-plan.json

失敗時のフォールバック：

• AE に接続できない場合 → .ae-cli/draft.json（ローカルに存在するプラン）を使用するか、ユーザーに確認します
• どちらも利用できない場合 → 中止し、先に ae-generate-tracking-plan を実行するよう提案します

SDK 統合設定の読み込み： プランファイルから次を読み取ります：

• meta.sdk_integration_mode — SDK 統合モード
• meta.client_sdk_type — クライアント SDK の種類（client_only または both の場合）
• meta.server_language — サーバー言語（server_only または both の場合）
• meta.user_identity — ユーザー ID 設定（login() / identify() の呼び出し生成に使用）
• user_properties — ユーザープロパティの一覧（各エントリーの name と update_type を使用して、user_set / user_setOnce / user_add の呼び出しを生成）

コードを生成するプラットフォームの一覧を決定：

platforms = {
  client: [client_sdk_type]  // e.g. ['android'] or ['javascript']
  server: [server_language]  // e.g. ['java'] or ['python']
}

---

フェーズ 2 — モードの選択（出力モードの選択）

2.1 プラットフォーム一覧の表示

フェーズ 1 の設定に基づき、コードが必要なプラットフォームを表示します：

Platforms requiring code generation:

Client:
- android (Android SDK)

Server:
- java (Java SDK, default LoggerConsumer + LogBus2)

2.2 クイックオプション

操作を簡単にするためのショートカットを用意します：

オプション 1：ワンクリック生成（推奨）

• すべてのプラットフォームで snippet モードを使用
• すべてのコードファイルを .ae-cli/output/ に一括生成
• プロジェクトパスは不要 — そのままコピーできるコードを提供
• コードをすばやく確認し、手動で統合する場合に最適です

オプション 2：プロジェクトへの挿入

• プラットフォームごとに insert または snippet を選択
• プロジェクトパスが必要 — コードをプロジェクトディレクトリに直接書き込み
• コードを書き込む場所が決まっている既存プロジェクトに最適です

2.3 プラットフォームごとの選択フロー

ユーザーが「プラットフォームごとに選択」を選んだ場合、プラットフォームの順に尋ねます：

クライアントプラットフォームのプロンプト：

Client android — choose output mode:
1. insert — requires project path
2. snippet — no path needed, generates code file

Your choice: insert / snippet

• insert → **「プロジェクトパスを入力してください（絶対パス）」**と尋ねます
• snippet → 追加のパラメーターは不要です

サーバー言語のプロンプト：

Server java — choose output mode:
1. insert — requires project path
2. snippet — no path needed, generates code file

Your choice: insert / snippet

(Defaults included: LoggerConsumer + LogBus2 config + official docs link)

• insert → **「プロジェクトパスを入力してください（絶対パス）」**と尋ねます
• snippet → 追加のパラメーターは不要です
• モードに関係なく、サーバー向けには常に .ae-cli/output/daemon.json を生成します
• 必ず LogBus2 の公式ドキュメントへのリンクを提示してください：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

2.4 単独オプション

プラットフォームの選択が完了したら、次の質問をします。

「デバッグ検証スクリプトを生成しますか？ はい／いいえ」

• yes → .ae-cli/output/te-debug.<ext> を生成します
• no → スキップします

2.5 選択内容の概要

最終的な選択内容を表示します。

Output mode summary:

Client android: snippet
  Deliverables: .ae-cli/output/android-sdk.java

Server java: snippet
  Deliverables: .ae-cli/output/java-sdk.java
                .ae-cli/output/daemon.json

LogBus2 official docs: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

Standalone option: debug
  Deliverable: te-debug.java

Confirm? yes / no

---

フェーズ 3 — 実行（プラットフォームごと）

3.1 実行前チェック

フェーズ 3 を開始する前に、次を確認します。

test -z "$(git status --porcelain)" || echo "uncommitted changes present"

処理ルール：

• snippet／debug → チェック不要です（ユーザーのコードには触れません）
• insert の選択 → git のステータスを確認します
  • git がクリーン → 続行します
  • git がダーティ → 一時停止し、ユーザーの選択を待ちます。

    未コミットの変更が検出されました。insert モードにはクリーンな git ワークスペースが必要です。
    
    選択してください：
    1. 先にコミット／スタッシュしてから、その旨を伝えてください。insert モードで続行します
    2. コードスニペットは snippet モードに切り替えます（insert を行う場合は、後でスキルを再実行してください）
    

    • ユーザーが 1 を選択 → ユーザーがコミット／スタッシュを完了した後、フェーズ 3.1 を再確認してから、insert で続行します
    • ユーザーが 2 を選択 → 今回の実行では、すべての insert モードを snippet に切り替えます

3.2 プラットフォーム別の振り分けと実行

イベントのプラットフォーム絞り込みルール（重要）：

• xlsx の「Platform」列の値を platform フィールドに次のように対応付けます。
  • 客户端／client → platform: "client"
  • 服务端／server → platform: "server"
  • 客户端,服务端／client,server → platform: "both"
• クライアントコード：platform === "client" または platform === "both" のイベントのみを生成します
• サーバーコード：platform === "server" または platform === "both" のイベントのみを生成します
• xlsx にプラットフォーム列がない場合（旧形式のプラン）：すべてのイベントを生成します（後方互換）
• platform === undefined（xlsx に列がない場合）→ クライアント側とサーバー側の両方に生成します

クライアントコードの生成：

出力モード	実行フロー
insert	references/client-sdk-insert.md を読み込む → プロジェクトを調査する → 挿入計画を立てる → 編集して書き込む
snippet	references/snippet-delivery.md を読み込む → Markdown を出力し、.ae-cli/output/<platform>-sdk.<ext> を生成する

platform === "client" または platform === "both" のイベントのみを生成します

⚠️ 厳守事項：SDK のインポートを推測しないでください

• 生成前に、必ず references/sdk-index.md を読み込み、該当する SDK wiki のメインドキュメントを特定して、パスの存在を確認してから、そのメインドキュメントを読み込んでください
• インポート文とパッケージ名は、必ず wiki のメインドキュメントからコピーしてください。推測してはいけません
• 例：JavaScript SDK の npm パッケージは thinkingdata-browser、インポート変数は ta です
• 生成したコードが wiki のドキュメントと一致しない場合（例：TDAnalytics／te／@thinkingdata/web-sdk）、wiki を再度読み込んで修正してください
• コードを生成する前に、毎回ドキュメントを再度読み込んでください。「覚えている」コードに頼ってはいけません

---

サーバーコードの生成：

出力モード	実行フロー
insert	references/server-sdk-insert.md を読み込む → プロジェクトを調査する → 挿入計画を立てる → 編集して書き込む
snippet	references/snippet-delivery.md を読み込む → Markdown を出力し、.ae-cli/output/<language>-sdk.<ext> を生成する

platform === "server" または platform === "both" のイベントのみを生成します

サーバー側のデフォルト設定（常に含める）：

• LoggerConsumer モードのコードを生成します（ローカルのログファイルに書き込みます）
• .ae-cli/output/daemon.json（LogBus2 設定）を生成します
• LogBus2 の公式ドキュメントへのリンクを必ず記載してください：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

⚠️ 厳守事項：SDK のインポートを推測しないでください

• 生成前に、必ず references/sdk-index.md を読み込み、該当する SDK wiki のメインドキュメントを特定して、パスの存在を確認してから、そのメインドキュメントを読み込んでください
• インポート文とパッケージ名は、必ず wiki のメインドキュメントからコピーしてください。推測してはいけません
• コードを生成する前に、毎回ドキュメントを再度読み込んでください。「覚えている」コードに頼ってはいけません

---

単独オプションの実行：

オプション	実行フロー
debug	references/debug-script.md を読み込む → .ae-cli/output/te-debug.<ext> を生成する

---

フェーズ 4 — 提供（出力マニフェスト）

選択した出力モードに応じて、成果物を表示します。

添付ファイルのアップロード

すべての .ae-cli/output/ ファイルが生成されたら、生成された出力ファイルをすべて Agent の添付ファイルライブラリにアップロードしてください。ユーザーはファイル／添付ファイル管理エントリーからダウンロードできます。

既存の添付ファイルコマンドを使用します。

ae-cli agent +add-attachment --files '<json-array-of-generated-output-files>'

アップロードリストのルール：

• .ae-cli/output/ 内にある、生成されたスニペットファイルをすべて含めます。
• .ae-cli/output/daemon.json や LogBus README ファイルなど、生成されたサーバー設定ファイルを含めます。
• .ae-cli/output/README.md を含めます。
• ユーザーがデバッグオプションを選択した場合は、生成されたデバッグスクリプトを含めます。
• ユーザーのプロジェクトに直接挿入されたファイルはアップロードしません。生成された出力成果物のみをアップロードします。

添付ファイルのアップロード互換性

Agent の添付ファイルバックエンドで受け付けられるドキュメント MIME タイプは限られています。.java、.kt、.swift、.m、.ets、.cs、.py、.go、.ts、.js、.php、.json などのコード／設定ファイルは、直接アップロードすると拒否される場合があります。

ae-cli agent +add-attachment を実行する前に、次のようにアップロードリストを準備します。

• 元の生成ファイルはすべて .ae-cli/output/ 内に変更せず保持します。
• 拡張子が添付ファイルバックエンドでサポートされていない可能性がある生成テキスト成果物ごとに、ファイル名の末尾に .txt を追加した、アップロード専用のコピーを作成します。
  • 例：.ae-cli/output/java-sdk.java → .ae-cli/output/java-sdk.java.txt
  • 例：.ae-cli/output/daemon.json → .ae-cli/output/daemon.json.txt
• .txt コピーの内容は元のファイルと同一でなければなりません。Markdown のコードフェンスで囲んだり、ヘッダーを追加したり、意図的に改行コードを変更したりしないでください。
• サポート対象外の元ファイルの代わりに、.txt 互換コピーをアップロードします。
• .md、.txt、.csv の成果物はそのままアップロードリストに含めます。
• 最終回答では、最初に元の成果物のパスを列挙し、その後、添付ファイルのアップロードにのみ使用した .txt 互換コピーについて説明します。

アップロードが成功した場合は、最終回答に添付ファイルのアップロード結果を含め、ファイルがファイル／添付ファイル管理エントリーから利用できることをユーザーに伝えます。Agent の添付ファイル認証情報が利用できずアップロードに失敗した場合は、.ae-cli/output/ 内のローカルファイルを保持し、アップロードが完了しなかったことをユーザーに伝えます。

すべてのスニペット

Deliverables:

Client:
- .ae-cli/output/android-sdk.java (Android SDK code snippet)

Server:
- .ae-cli/output/java-sdk.java (Java SDK LoggerConsumer code)
- .ae-cli/output/daemon.json (LogBus2 configuration)

LogBus2 official docs: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

Standalone:
- .ae-cli/output/te-debug.java (validation script)

README: .ae-cli/output/README.md (usage instructions)

Attachment upload: uploaded generated output files to the file/attachment management entry

混在（挿入とスニペットの両方）

Deliverables:

Client android (insert):
- <project-path>/src/main/java/.../TrackingHelper.java (SDK init + event calls)

Server java (snippet):
- .ae-cli/output/java-sdk.java (LoggerConsumer code snippet)
- .ae-cli/output/daemon.json (LogBus2 configuration)

LogBus2 official docs: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

Standalone:
- .ae-cli/output/te-debug.java (validation script)

Attachment upload: uploaded generated output files to the file/attachment management entry

Markdown コードスニペットの表示

すべての snippet 選択について、Markdown の回答内でコードをプラットフォームごとにまとめて表示します。

## Client Android

### SDK Initialization
```java
TDAnalytics.init(this, SERVER_URL, APPID);

スーパー プロパティ

Map<String, Object> superProperties = new HashMap<>();
superProperties.put("channel", "app_store");
TDAnalytics.setSuperProperties(superProperties);

イベントグループ：auth

user_login

TDAnalytics.track("user_login", new HashMap<String, Object>() {{
    put("login_method", "phone");
}});

...

---

## Phase 5 — Validate hint

Provide validation guidance based on selected platforms:

### Validation Steps

検証手順：

1. アクティブな AE 環境を確認します。 ae-cli config current

2. 既存の Debug デバイスを一覧表示します。 ae-cli tracking debug-device list --project-id <project_id>

3. スクリプトの固定デバイス ID が存在しない場合は作成し、そのデバイスを選択します。 ae-cli tracking debug-device add --project-id <project_id> --device-id <device_id> --device-name ae-cli tracking debug-device select --project-id <project_id> --device-id <device_id>

4. 検証スクリプトを実行します。

   • クライアント：.ae-cli/output/te-debug-client. を実行します
   • サーバー：.ae-cli/output/te-debug-server. を実行します

5. 直近1時間の Debug データを照会します。 ae-cli tracking debug-data list --project-id <project_id> --device-id <device_id>

6. has_data=true を確認し、イベント名、プロパティ構造、エラーフィールドを調べます。 必要に応じて、--event-name <event_name> または --start-time "YYYY-MM-DD HH:mm:ss" を追加します。

7. CLI 機能を利用できない場合に限り、AE Debug ページを開きます。 https:///#/data/debug

8. LogBus2 の場合：

   • daemon.json を LogBus2 の conf/ ディレクトリにコピーします
   • 起動します：./logbus start
   • 公式ドキュメント：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

### After validation passes

- Remind user to commit changes (if any `insert` was used)
- Remind user to call `login()` / `identify()` (associate user IDs) and `user_set` / `user_setOnce` / `user_add` (set user properties) at the right business moments
- Remind user to copy daemon.json to LogBus2 conf/ directory

### Validation failure

- Ask user to paste error text for debugging
- Check SERVER_URL / appId correctness
- Check network connectivity
- Check LogBus2 config file format

---

## Prohibitions

- **Any `insert` without running `git status` check first (IMPORTANT: must check first; refuse execution if uncommitted changes exist)**
- Skipping reference docs in Phase 3 and inserting code arbitrarily
- Ignoring `// @tracking <event>` comment incremental detection
- Reusing web host as SERVER_URL (must be separate)
- **Using LogBus v1 (deprecated — only use LogBus2)**
- Generating LogBus2 config without providing official documentation link
- Including `platform === "server"` exclusive events in client code
- Including `platform === "client"` exclusive events in server code (unless `platform === "both"`)
- **Skipping SDK main doc read and guessing integration method** — each SDK has different integration approaches; must read wiki main doc's "Integrate SDK" section first, and choose the correct method based on project characteristics (with/without build tools)
- **Translating "Super Property" as "超级属性" in any user-facing output (code comments, interaction prompts, markdown) — the correct AE Chinese term is "公共事件属性" or "公共属性"**
- **Entering Phase 1 before Phase 0.5 is complete** — SDK integration must be confirmed before inserting code, otherwise generated track() calls won't work

---

## Internal Reference

All output mode rules are in `references/*.md`. This SKILL.md only handles phase orchestration.

**SDK document index**:
- `references/sdk-index.md` — All SDK wiki document path index (canonical source)

**Output mode references**:
- `references/client-sdk-insert.md` — Client code insertion workflow
- `references/snippet-delivery.md` — Code snippet generation workflow
- `references/server-sdk-insert.md` — Server code insertion workflow (LoggerConsumer + LogBus2)
- `references/logbus-config.md` — LogBus2 configuration generation (includes official docs link)
- `references/debug-script.md` — Validation script generation

**LogBus2 official documentation** (must provide when generating config):
- User guide: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US
- Download link is in the official doc's "二、Download LogBus2" section

**Wiki directory structure** (see `~/.ae-cli/wiki/schema.md`):
- `~/.ae-cli/wiki/raw/` — AE official documentation mirror (read-only, maintained by crawler)
- `~/.ae-cli/wiki/synthesis/` — LLM-synthesized overview documents

**Document reading order during code generation**:
1. Read `references/sdk-index.md` to find the selected SDK's main document and advanced guide paths.
2. Verify the main document path exists in the local wiki mirror before reading it.
3. If the indexed path is missing, search under `~/.ae-cli/wiki/raw/` with SDK-specific keywords such as SDK name, platform name, language name, and `main doc`; choose the latest main document, not historical/versioned documents.
4. Read the wiki main doc first (initialization, imports, package names, basic API).
5. Read the advanced guide only after the main doc (LoggerConsumer, user properties, auto-track, preset properties, etc.).
6. Check advanced guide sub-documents if needed.