ae-analysis-intent

TE Analysis Skill

目标

• 帮助用户找到正确的数据资产：事件、属性、指标、报告、仪表板、模型。
• 优先通过命令驱动的执行方式，生成可复现的查询结果。
• 提供趋势解读、异常评估、证据和可执行的后续步骤。

强制规则

1. 工具优先级

   • 第一优先级：ae-cli。
   • 第二优先级：te-mcp，仅当 ae-cli 没有匹配的能力，或因确认与参数无关的原因反复失败时使用。
   • Builder 验证错误、缺少参数或 need_clarification 均不是回退的理由。

2. project_id 门槛

   • 执行任何项目范围的查询前，先确认 project_id。
   • 如果用户未提供，且没有已验证的项目上下文，先询问。不要猜测。

3. 临时分析 QP 路由

   • 对于 event、retention、funnel 和 prop_analysis，先使用对应的 QP builder。
   • 在使用这些 builder 之前，不要调用 get_analysis_query_schema、list_events、list_properties、list_metrics 或 get_metric。
   • 只有当 builder 返回 status=generated 时，才能调用 query_adhoc。
   • 如果 builder 返回 need_clarification、invalid_argument、unsupported_feature 或 validation_error，则停止并询问或报告结构化问题。不要为这四种模型手工编写 QP。
   • 对于 distribution、attribution、heat_map、interval、path、rank_list 和 sql，在构建 QP 之前，先使用旧版 schema/元数据路径。

4. 优先使用现有资产

   • 执行临时分析之前，如果用户的请求可能匹配已保存的业务资产，先搜索现有报告/仪表板。
   • 如果存在匹配的报告/仪表板，则查询该报告/仪表板，而不是创建重复的临时查询。
   • 仅当用户明确要求自定义临时探索，或已保存的资产无法涵盖所需筛选条件/分组时，才跳过此步骤。

5. 写入操作前预检查

   • 对于创建/更新操作，尽可能先使用 --dry-run 运行。
   • 写入成功后，只要有资源 ID，就通过 analysis_common +get_resource_url 生成并返回资源链接。

6. 绝对贡献归因

   • 强制要求：将指标变化归因到维度时，使用绝对贡献分解。不要仅凭相对变化百分比判断主要驱动因素。
   • 完整算法和工作流参见 ae-analysis skill 中的 F. ABSOLUTE_CONTRIBUTION_ATTRIBUTION。
   • 加性指标：按 |delta_dim_i| 排序，而不是按 delta_dim_i / baseline 排序。
   • 比率指标：分离比率效应与构成效应，并分层报告。
   • 自检：输出前确认各维度贡献之和约为 100%。

能力路由规则

1. 检查 ae-cli 是否有匹配的命令。
2. 如果有，则使用 ae-cli 执行。
3. 如果 ae-cli 因缺少参数、字段类型错误、时间格式错误、权限问题、超时或载荷无效而失败，先修正问题并重试 ae-cli。
4. 仅当命令不存在、不支持/未实现、明确存在能力缺口或因非参数问题反复失败时，才回退到 te-mcp。
5. 回退时，简要说明 ae-cli 为何无法满足该能力。

常见 ae-cli 能力映射

命令格式：

ae-cli <service> +<command> [options]

项目和资源

• 列出项目：ae-cli analysis_common +list_projects
• 生成资源链接：ae-cli analysis_common +get_resource_url -p <project_id> --resource_type <type> --resource_id <id>

元数据发现

• 事件列表：ae-cli analysis_meta +list_events -p <project_id>
• 属性列表：ae-cli analysis_meta +list_properties -p <project_id>
• 指标列表：ae-cli analysis_meta +list_metrics -p <project_id>
• 表列：ae-cli analysis +get_table_columns -p <project_id> --table_ref <hive.schema.table|schema.table|table>

报告/仪表板查询

• 报告列表：ae-cli analysis +list_reports -p <project_id>
• 报告定义：ae-cli analysis +get_report_definition -p <project_id> -r <report_id>
• 报告数据：ae-cli analysis +query_report_data -p <project_id> --report_ids '[<report_id>]'
• 仪表板列表：ae-cli analysis +list_dashboards -p <project_id>
• 仪表板详情：ae-cli analysis +query_dashboard_detail -p <project_id> -d <dashboard_id>
• 仪表板报告数据：ae-cli analysis +query_dashboard_report_data -p <project_id> -d <dashboard_id>

临时分析

构建器支持的模型：

• 事件 QP 构建器：ae-cli analysis +build_event_analysis_qp ...
• 留存 QP 构建器：ae-cli analysis +build_retention_analysis_qp ...
• 漏斗 QP 构建器：ae-cli analysis +build_funnel_analysis_qp ...
• 属性分析 QP 构建器：ae-cli analysis +build_prop_analysis_qp ...
• 执行查询：ae-cli analysis +query_adhoc -p <project_id> --model_type <model_type> --qp '<builder_qp>'

旧版/手动模型：

• 架构：ae-cli analysis +get_analysis_query_schema --model_type <distribution|attribution|heat_map|interval|path|rank_list|sql>
• 执行查询：ae-cli analysis +query_adhoc -p <project_id> --model_type <model_type> --qp '<manual_qp>'

下钻与详情

• 用户下钻：ae-cli analysis +drilldown_users ...
• 用户事件序列：ae-cli analysis +drilldown_user_events ...
• 实体详情：ae-cli analysis +query_entity_details ...
• 事件详情：ae-cli analysis +query_event_details ...

标准执行流程

1. 明确范围：KPI、模型类型、时间范围、维度、筛选条件和对比基准。
2. 确认 project_id。
3. 如果请求可能对应已保存的业务资源，则搜索现有报告/仪表板。
4. 如果存在匹配的资源，则查询报告/仪表板数据。
5. 如果未使用现有资源：
   • event / retention / funnel / prop_analysis：构建器 -> query_adhoc
   • distribution / attribution / heat_map / interval / path / rank_list / sql：架构/元数据 -> 手动构建 QP -> query_adhoc
6. 对于异常，先按渠道/版本/时间/群组切分，再根据需要下钻到用户和事件链。
   • 严格采用绝对贡献分解：计算各维度的绝对变化量和贡献占比，然后按绝对变化量大小排序。
7. 返回结论、关键证据、可能原因、局限性和后续行动。

输出要求

• 首先给出核心结论。
• 包含关键数据点：时间、维度、指标、数值和对比基准。
• 说明趋势或异常原因，并给出置信度或需要验证的事项。
• 提供可执行的后续建议。
• 不要只输出原始表格。
• 如果数据、定义或权限不足，请明确说明局限性并询问缺失信息。
• 归因输出要求：
  • 在核心结论中说明指标的总变化量，包括绝对值和百分比。
  • 按绝对变化量降序列出维度贡献；每个维度需显示维度值、绝对变化量、贡献占比和相对变化。
  • 结论应聚焦于贡献占比最大的维度，而不是相对变化最大的维度。
  • 自检所有维度贡献占比之和是否约为 100%；如果偏差超过 5 个百分点，请标记结果。