ae-data-integration

AE Data Integration

スキル間の連携

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

ローカル／オフラインのファイルと Feishu のシート／Bitable（多维表格）URL を、4 つのサブモジュールからなる固定パイプライン「Source → Tracking plan → Transform → Sink」を通じて AE データに変換します。ファイルやシートが存在するというだけでアップロードすることはありません。まず業務上の意味を把握し、人間が一度確認してから、初めて取り込みます。トラッキングプランは取り込み前に生成して確認します（データガバナンスのシフトレフト）。references/tracking-plan.mdを参照してください。

入口は 2 つあります。AE Agent のダイアログ（添付／プラスボタンからのアップロード）と ae-cli です。Sink の経路は 2 つあります。単発／少量のデータロード向けの RESTful API（現行フェーズ）と、定期的／大量のデータロード向けの LogBus / DataX（次フェーズ）です。Source と Sink はプラグイン可能であり、追加してもメインパイプラインは変わりません。

必須の安全ルール

• ファイルパス、受信先エンドポイント、APPID、マッピング、生成されたアーティファクト、未加工の行は機密情報として扱ってください。
• 調査中にソースの値を表示しないでください。型、割合、件数、警告、フィンガープリントのみを要約してください。
• サンプルの調査は範囲を限定しますが、サンプルも機密情報です。要約し、生のサンプル値をチャットの要約に貼り付けないでください。
• アカウント ID、distinct ID、イベント時刻、イベント名、プロジェクト、APPID、受信先、タイムゾーンを捏造しないでください。
• value_mapping と random_pool はユーザーが明示的に決める項目です。決して独自に設定しないでください。
• track／track_* の行で時刻が欠けていても、自動で補完しないでください。ユーザープロファイルの行で時刻が欠けている場合は、ユーザーが明示的に確認した後に限り、missing_time: 'now' を設定して現在時刻を補完できます。
• マッピングの補完オプション（missing_time: 'now'、account_id_value／distinct_id_value、random_pool、exclude_columns、value_mapping）は、ユーザーがすでに行った判断を記録するためのものです。検証失敗を解消するために使用してはいけません。convert が行を隔離した場合は、失敗内容を最初に提示してください。code エラー、行数、全体に占める割合、影響を受けるイベントまたは時間範囲を示し、「3,000 件のイベントに、実際の発生時刻ではない時刻が付与されることになります」のように、ユーザーにとっての影響を説明してください。その説明をユーザーが確認した後に限り、これらのオプションを設定できます。根拠が不十分な場合は、バッチを不合格として報告し、顧客データの提供待ちとしてください。合格を作り出すためにアップロード範囲を縮小してはいけません。
• AE アクセストークンまたは CLI トークンを読み取ったり、/sync_json に送信したりしないでください。受信先へのリクエストで使用するのは APPID と UE データのみです。
• ユーザーが送信先、マッピング、有効件数／隔離件数、バッチ、ドライランの内容を確認し、アップロードを明示的に承認するまで、data-integration upload を実行しないでください。
• マニフェストがブロックされた場合、クリーンサブセットを使うには、別途、明示的な判断が必要です。暗黙的に --allow-clean-subset を追加してはいけません。
• バッチがタイムアウトした場合、またはネットワークが切断された場合、そのバッチは状態不明として扱ってください。停止し、ユーザーが --resume-from を選ぶ前に、受信先／AE のデータを確認するよう依頼してください。自動的に再開してはいけません。
• ローカルでの分析はローカルにとどめてください。AE Agent への添付は、別途確認が必要な経路であり、1 ファイルあたりの上限は 50 MB です。
• data-integration upload は冪等ではありません。実行するたびに、再度受信先へ送信します。応答を確認するだけのために再実行してはいけません。初回実行で保存された JSON 出力を読み取ってください。--dry-run はリクエストのプレビューのみを行い、受信先からの実際の応答は取得しません。

使用する場合／使用しない場合

ユーザーがローカルデータファイル（CSV/TSV/TXT/JSON/JSONL/XLS/XLSX）またはFeishu シート／Bitable（多维表格）URLを AE に取り込む場合、あるいはアップロードせずにローカルファイルを分析する場合に、このスキルを使用します。

ユーザーの意図	代わりに使用するもの
SDK／トラッキングコード／LogBus2 設定／レポートエラーのトリアージの統合方法（ローカルファイルを使わない利用方法の Q&A）	ae-data-integration-helper
データベース／データソースとの直接同期（MySQL、DataX、データウェアハウス、data-dev プラットフォーム）	ae-dataops
コミュニティコンテンツ（投稿／コメント／チャット／WeCom グループ）の分析または送信	ae-community
プロジェクトレベルのトラッキング計画の生成／アップロード（元資料は PRD／チャット／テンプレート／コードで、成果物は実際のプラットフォーム上のトラッキング計画）	ae-generate-tracking-plan
ドキュメント／URL のナレッジベースへのアップロード	ae-kb
AE にすでにあるデータに関するレポート／ダッシュボード／クエリ／ガバナンス	ae-analysis
ディメンションテーブルとしてプロパティに関連付けるディメンション／辞書データ（都市／製品／デバイスなど、安定したエンティティの参照データ）の読み込み	ae-metadata

このスキルは、ガバナンスの前提条件としてトラッキング計画のドラフト（source_type: data）も作成します。このドラフトは ae-generate-tracking-plan への入力であり、同スキルの5フェーズからなるプラットフォーム計画の代替ではありません。

ワークフロー

4つのサブモジュールを順番に確認します。各サブモジュールはそれぞれ独立したリファレンスです。内容に従って作業し、次のステップに進むためにここへ戻ってください。

1. ソース — 業務上の識別。 ソースはローカルファイルまたはオンラインドキュメントの URL です。ローカルファイルの場合は references/source-inspect.md を読みます。Feishu シートのリンクの場合は references/lark-sheet-source.md、Bitable（多维表格 / /base/）のリンクの場合は references/lark-bitable-source.md を読みます。各リファレンスでは、lark-cli 環境（インストール済み、ログイン済み、アクセス権あり）を自己チェックし、ドキュメントをローカルファイル（シートは XLSX、Bitable は JSONL）にスナップショットしてから、このステップに戻ります。その他のオンラインドキュメント（Tencent Docs / DingTalk / WPS / Google Sheets / Notion）には CLI で読み込む方法がありません。references/manual-export-source.md を読み、ユーザー自身にファイルをエクスポートしてもらってから、このステップに戻ります。すべてのファイルを完全にプロファイリングし、業務ドキュメント／ユーザープロンプトの事前情報を使って業務上の意味を推定したうえで、references/ue-routing.md に従って分岐先（UE 取り込み、ディメンションのルーティング（references/dimension-routing.md）、またはローカル分析）を選択します。
2. 再利用チェック。 プロファイルが ue_eligible の場合は、references/reuse.md を読み、推奨マッピングをハンドオフインデックスと照合します。reuse は、現在のディレクトリから上位へ .ae-cli/data-integration/ を検索し、その後 ~/.ae-cli/data-integration/ を検索するため、別の場所に書き込まれたパッケージも見つかります。一致するものがあれば、固定済みパッケージを提案します。明示的な確認を1回得た後、返された transform.mjs コマンドを実行し、Sink（ステップ5）に進みます。一致しない場合は続行します。
3. トラッキングプラン。 references/tracking-plan.md を読みます。プランはマッピングから生成される（plan --mapping）ため、まず推奨マッピングの主要なシステムフィールド（mode、#account_id／#distinct_id、#time とタイムゾーン、#event_name、#ip／#uuid。詳しくは references/transform.md のステップ1～5を参照）をユーザーに確認してから、イベント／プロパティプランを生成し、データに触れる前にユーザーから明示的な確認を1回得ます。プランは変換マッピングとは別個の必須成果物です。列→フィールドのマッピングをユーザーから直接提示されても、このステップを完了したことにはなりません。そのため、確認済みマッピングからプランを作成してください。user_set でもプランが必要です（イベントはなく、すべてのプロパティがユーザープロパティになります）。このステップはすべてのファイルで実行します。2つ目以降のファイルでは、新しいイベントとプロパティを既存のプロジェクトプランにマージします（tracking-plan.md のステップ4）。既存のプランがあることを理由に、このステップを省略してはいけません。
4. 変換。 references/transform.md を読みます。列を AE システムフィールドとプロパティにマッピングして変換し、references/ue-mapping.md に従って不正な行を隔離します。
5. Sink — アップロード。 references/sink-upload.md を読みます。送信先を確定し、ドライランを行って確認を得た後、references/sync-json-upload.md に従ってアップロードします。receiver_accepted は永続化を意味しません。約1分の取り込み遅延の後、コンソールを確認するようユーザーに伝えるのではなく、ae-cli（tracking live-data list / tracking ingest summary / tracking ingest-error list）でデータが到着したことを確認します。
6. ハンドオフ。 references/handoff.md を読みます。再利用可能なパッケージ（パイプライン記述子＋固定済みマッピング＋ステージ実行プログラム＋ドキュメント）と共有用 zip をエクスポートします。完了時の応答には、zip の絶対パス、パッケージディレクトリ、および次に同じ形式のファイルを処理するための1行の実行方法を記載します。

エラー処理

ステップが失敗した場合は、対応する前に失敗を分類してください。詳しくはreferences/error-handling.mdを参照してください。隔離された行、不規則な行、ディスク容量不足は、それぞれ異なる問題であり、対応も異なります。エラーのcodeに基づいて判断し、推測したエンコーディングで解析エラーを再試行せず、プログラムの失敗をデータの問題として報告しないでください。

ローカル分析ブランチ

UE の前提条件を満たさない場合、ファイルが集計／分析テーブルである場合、またはユーザーが取り込みではなく分析を希望する場合は、取り込みパイプラインではなくreferences/local-analysis.mdを使用してください。

AE Agent への任意の添付ファイル引き継ぎ

ユーザーが AE Agent での続行を求めた場合にのみ提案してください。ファイルがローカルマシンの外部に送信されることを説明し、プライバシーについて明示的な確認を求めてください。

• 50 MB を超えるファイルは拒否し、ローカル分析またはユーザー自身による分割を提案してください。
• 呼び出す前に、ae-agent の+add-attachmentリファレンスを読んでください。
• まずドライランを実行し、ファイル名／種類／サイズを表示して、確認を待ってください。
• その後、ae-cli agent +add-attachment --file '<path>'を実行してください。
• 添付ファイルの結果、コピー可能な分析プロンプト、AE Agent を開く手順を返してください。
• Agent の会話を作成または実行しないでください。

完了時の応答

実行したサブモジュール、ソースのフィンガープリントと選択したデータセット、トラッキング計画のステータス、生成された成果物のパス、マッピングの信頼度、有効件数／隔離件数、アップロード／添付ファイルのステータスを伝えてください。事実と推奨事項を分け、永続化が検証済みかどうかを明確に伝えてください。