ae-data-integration

AE 数据集成

跨技能协作

当剩余工作超出此技能的范围，或必要的前置条件需要另一项能力时，请遵循协作协议。根据能力从本次运行可用的技能中选择，保留已验证的上下文，并继续完成剩余任务。如果已加载此协议，请重复使用。

通过一个固定的四个子模块流程，将本地／离线文件和飞书表格／多维表格 URL 转换为 AE 数据：Source → Tracking plan → Transform → Sink。文件或表格不会仅仅因为存在就被上传：必须先理解其业务含义，由人工确认一次，然后才能摄取。跟踪计划会在摄取前生成并确认（数据治理左移）——请参阅 references/tracking-plan.md。

有两个入口：AE Agent 对话框（附件／加号按钮上传）和 ae-cli。有两种 Sink 路径：用于一次性／小批量加载的 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 数据。
• 在用户看到目标、映射、有效／隔离数量、批次和 dry-run 结果并明确确认上传之前，绝不要执行 data-integration upload。
• 被阻止的清单需要用户再次明确决定是否使用干净子集。切勿隐式添加 --allow-clean-subset。
• 如果批次超时或网络中断，应将该批次视为状态未知。停止操作。请用户核实接收端／AE 数据，然后再由用户选择 --resume-from；切勿自动恢复。
• 本地分析须保留在本地。AE Agent 附件是单独的、经确认的分支，每个文件的大小上限为 50 MB。
• data-integration upload 不具备幂等性——每次执行都会再次提交到接收端。切勿仅为检查响应而重新运行；应读取首次运行保存的 JSON 输出。--dry-run 仅预览请求，不会返回接收端的真实响应。

适用场景 / 不适用场景

当用户想要将本地数据文件（CSV/TSV/TXT/JSON/JSONL/XLS/XLSX）或飞书表格 / 多维表格 URL 导入 AE，或在不上传文件的情况下分析本地文件时，使用此技能。

用户意图	改用此技能
如何集成 SDK / 埋点代码 / LogBus2 配置 / 上报错误排查（使用问答，不涉及本地文件）	ae-data-integration-helper
直接同步数据库 / 数据源（MySQL、DataX、数据仓库、data-dev 平台）	ae-dataops
社区内容（帖子 / 评论 / 聊天 / 企业微信群）洞察或提交	ae-community
生成 / 上传项目级埋点方案（源材料为 PRD / 聊天 / 模板 / 代码；交付物为真实的平台埋点方案）	ae-generate-tracking-plan
上传文档 / URL 到知识库	ae-kb
对 AE 中已有数据进行报告 / 仪表板 / 查询 / 治理	ae-analysis
将维度 / 字典数据（稳定实体查询数据，如城市 / 产品 / 设备）加载为绑定到某个属性的维度表	ae-metadata

此技能还会生成一份埋点方案草稿（source_type: data）作为治理前置条件；该草稿是 ae-generate-tracking-plan 的输入，而非其五阶段平台方案的替代品。

工作流

按顺序遍历四个子模块。每个子模块都有自己的参考文档；按文档说明操作，然后返回此处继续下一步。

1. Source — 业务识别。 数据源可以是本地文件（阅读 references/source-inspect.md），也可以是在线文档 URL。飞书表格链接请阅读 references/lark-sheet-source.md，Bitable（多维表格 / /base/）链接请阅读 references/lark-bitable-source.md；这两种流程都会自行检查 lark-cli 环境（是否已安装、已登录且具有访问权限），并先将文档快照保存到本地文件（表格为 XLSX，Bitable 为 JSONL），然后返回此步骤。其他在线文档（腾讯文档 / 钉钉 / WPS / Google Sheets / Notion）没有 CLI 读取路径——请阅读 references/manual-export-source.md，该文档会让用户自行导出文件，然后返回此步骤。全面分析每个文件，并根据业务文档 / 用户提示词先验推断其业务含义，然后通过 references/ue-routing.md 选择分支：UE 接入、维度路由（references/dimension-routing.md）或本地分析。
2. 复用检查。 如果 profile 为 ue_eligible，请阅读 references/reuse.md，并将推荐的映射与交接索引进行匹配。reuse 会从当前目录的 .ae-cli/data-integration/ 开始向上搜索，然后搜索 ~/.ae-cli/data-integration/，因此写入其他位置的包也能被找到。匹配成功后会提出一个冻结包；在获得一次明确确认后，运行返回的 transform.mjs 命令，并跳转到 Sink（第 5 步）。未匹配到 → 继续。
3. Tracking plan。 请阅读 references/tracking-plan.md。计划根据映射生成（plan --mapping），因此请先与用户确认推荐映射中的关键系统字段——mode、#account_id/#distinct_id、#time + 时区、#event_name、#ip/#uuid（参见 references/transform.md 步骤 1–5）——然后生成事件 / 属性计划，并在处理数据前取得用户一次明确确认。计划与 transform mapping 是两个独立且必需的交付物：用户若直接提供了列→字段映射，并不代表已完成此步骤，因此仍须根据已确认的映射构建计划。user_set 仍需要计划（无事件；每个属性都成为用户属性）。每个文件都必须执行此步骤：第二个及后续文件会将新增事件和属性合并到现有项目计划中（tracking-plan.md 步骤 4）——已有计划绝不是跳过此步骤的理由。
4. Transform。 请阅读 references/transform.md。将列映射到 AE 系统字段和属性，进行转换，并根据 references/ue-mapping.md 隔离脏数据行。
5. Sink — 上传。 请阅读 references/sink-upload.md。确定目标位置，执行 dry-run，确认后根据 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 的绝对路径、包目录，以及运行下一个同类型文件的一行命令。

错误处理

步骤失败时，先对失败进行分类，再采取行动——请参阅 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 对话。

完成响应

说明运行了哪些子模块、源指纹和选定的数据集、跟踪计划状态、生成的文件路径、映射置信度、有效/隔离数量，以及上传/附件状态。将事实与建议分开，并明确说明是否已验证持久化。