事件分析 MCP | 产品方案
一、产品定位
为 AI Agent 提供基于事件明细数据的用户行为分析能力，精准回答“用户在做什么”和“行为分布长什么样”两类核心业务问题。
能力差异化对比：看大盘 vs 做分析
| 对比维度 | KPI 报表查数 (预聚合) | 事件分析 MCP (明细) |
|---|---|---|
| 数据粒度 | 天级/渠道级等固化的宏观聚合值 | 精确到单次事件触发的底层明细记录 |
| 查询灵活性 | 受限于预先开发好的固定报表结构 | 任意事件 × 任意属性 × 任意筛选/分组 |
| 人群限定能力 | 不支持下钻特定人群 | 完全支持（作为 filters 传入 segment_id） |
| 解决的典型问题 | "昨天大盘 DAU 和总收入是多少？" | "过去7天完成困难副本的人均次数，按渠道分组是多少？" |
二、全局演示：一次高阶事件分析连招
业务背景：运营团队想分析高价值用户在购买道具时的行为偏好与客单价特征。
三、能力范围
事件明细分析核心矩阵
事件指标分析
核心方法：analyze_event
属性分布分析
核心方法：analyze_distribution
灵活分析条件
支持对分析过程施加多重维度
联动人群分析MCP
与外部人群运营 MCP 无缝集成
四、MCP 工具集
4.1 事件分析 Tool Group
🛠 工具清单 点击卡片侧滑查看详细 MCP 协议
analyze_event
对指定事件计算一个或多个指标，支持事件级（触发次数）或属性级（数值求和）聚合。
4.2 分布分析 Tool Group
🛠 工具清单 点击卡片侧滑查看详细 MCP 协议
analyze_distribution
对指定事件的某个数值型属性查看分布形状（直方图），支持自定义 buckets 区间。
4.3 语义层字典 (复用基础设施)
事件分析 MCP 不新增自身的语义字典工具，直接复用原人群 MCP 中的 3 个字典 API，为 Agent 提供事件名和属性名的正确枚举，彻底杜绝大模型在拼写 SQL 字段时产生幻觉。
核心字典表结构定义
| 字段名 (Field) | 数据类型 | 业务含义 & MCP 约束规则 |
|---|---|---|
| name | string | 属性英文唯一代号（如 vip_level） |
| display_name | string | 前端展示中文名（如 VIP等级） |
| data_type | enum | 枚举限制：string | number | boolean | date | enum |
| applicable_in | array | 防幻觉 指定可用模块，可用于 event 的 filters/group_by |
| supported_operators | array | 防幻觉 限制可使用的过滤算子，如 [eq, neq, gt, between] |
| enum_values | array | 若数据为枚举，提供大模型可填入的值映射字典 [{value: "iOS", label: "苹果"}] |
| 字段名 (Field) | 数据类型 | 业务含义 & MCP 约束规则 |
|---|---|---|
| name | string | 埋点事件底层代号（如 activity_join） |
| display_name | string | 事件前端展示中文名（如 参与活动） |
| description | string | 详细口径与触发时机描述，供 Agent 做自然语言语义理解匹配 |
| has_attributes | boolean | 指引 Agent 是否需要继续调取 list_event_attributes 探查参数 |
| sub_events | array | 级联下钻的子事件字典，用于同一事件的多实例区分（如具体哪个副本） |
| 字段名 (Field) | 数据类型 | 业务含义 & MCP 约束规则 |
|---|---|---|
| event_name | string | 绑定的父事件代号（如 payment） |
| name | string | 参数字段英文标识（如 pay_amount） |
| supported_operators | array | 防幻觉 针对此参数可用的算子，如 [gt, lt, between] |
| enum_values | array | 若参数为枚举型，提供键值映射约束 |
🛠 工具清单 点击卡片侧滑查看详细 MCP 协议
list_user_attributes
检索当前底表支持的所有用户属性枚举，杜绝胡乱拼写字段。
list_events
根据人类指令的关键字，寻找底层对应的事件真实代号与子集。
list_event_attributes
查阅特定事件所附带的详细参数字段体系（如金额、渠道）。
五、Text2DSL 架构设计 (防幻觉系统)
大模型直接生成复杂分析语句极易产生字段捏造和结构错乱。我们将 Text2DSL 过程拆解为标准四步工作流，通过“字典强对齐”与“网关强校验”层层设卡，确保最终投递到计算引擎的 DSL 100% 准确可执行。
NL (自然语言) 拆解重构
Agent 需在第一步分离出分析的骨架结构
System Prompt 控制台规则注入
严禁捏造实体
Agent System Prompt 强制规定，所有 event_name 和 attribute_name 必须调用字典 API 获取。如果凭常识臆造（如将“购买”拼写为 purchase 但实为 buy_item），将被严厉禁止。
算子逻辑约束
提供精准的映射规则库：明确教导大模型如何区分“求总次数”（event_level）与“求金额总和”（attribute_level），大幅降低组装 Metrics 时的逻辑错位率。
Schema 必填强验
告诉大模型：“底层 API 已经配置了极为严格的校验体系。任何缺少 time_range，或 operator 拼写错误的请求都会被驳回，请仔细核对生成的结构。”