第一章 埋点方案核心目标：Reach与Impact数据定义、业务价值、衡量指标对齐
1.1 边界：Reach 与 Impact 的数据采集范围
Agent 埋点方案的首要任务是在用户的完整行为链路中准确划定两类核心数据的采集边界：Reach（触达）与Impact（影响）。Reach 衡量 Agent 向用户“展示”了什么，Impact 衡量这种展示“改变了”什么。边界不清晰会导致埋点过度冗余或关键事件遗漏。
| 维度 | Reach（触达） | Impact（影响） |
|---|---|---|
| 定义 | Agent 推送消息、显示卡片、播放语音等可见/可感知的展示行为 | 用户因 Agent 展示产生的点击、转化、留存、付费等后续行为 |
| 采集时机 | Agent 输出渲染完成时（曝光前/后） | 用户触发交互动作时（点击、提交、关闭） |
| 典型事件 | push_receive, card_show, voice_play, screen_show | card_click, link_click, purchase, user_retention |
| 数据敏感度 | 中间过程数据，不计入收入 | 直接关联业务 KPI，需高频校验 |
边界决策原则：Reach 数据只记录“Agent 的输出侧”，不依赖用户主动上报；Impact 数据必须依赖用户交互事件，且需携带 Reach 事件的唯一 ID 形成链路。
1.2 分层：Reach-Impact 数据采集架构
为实现边界隔离与事件关联，Reach 与 Impact 数据在架构上可分为三层。
- 事件采集层：SDK 自动捕获 Agent 渲染完成事件（Reach）和用户手势/点击事件（Impact）。
- 链路关联层：为每一条 Reach 记录生成全局唯一 session_id，Impact 事件携带该 session_id 实现归因。
- 指标计算层：基于关联后的宽表计算触达人数、点击率、转化率、留存率等。
1.3 业务价值对齐
- Reach 价值：量化 Agent 的信息触达效率。例如推送到达率、卡片展现率、语音播报完成率。缺少 Reach 埋点，无法判断 Agent 是否真正“开口”。
- Impact 价值：评估 Agent 对业务目标的撬动作用。例如点击率、转化率、用户时长、留存率。Impact 是 ROI 计算的直接输入。
- 联动价值：通过 session_id 归因，可计算“每触达千次的转化成本”（CPM → CPA），优化 Agent 的展示策略与话术。
1.4 衡量指标对齐（From Business KPI to Event Field）
定义好 Reach 与 Impact 事件后，需要将业务指标映射到具体埋点字段，确保计算口径一致。
| 业务指标 | 对应埋点事件 | 关键字段 | 计算逻辑 |
|---|---|---|---|
| 触达率 | reach_show | session_id, agent_id, content_id, timestamp | distinct session_id / 目标用户池 |
| 点击率 (CTR) | impact_click | session_id, element_id, click_type | count(click) / count(show) 分组 |
| 转化率 (CVR) | impact_convert | session_id, order_id, amount | count(convert) / count(click) |
| 7 日留存 | impact_retention | user_id, session_id, day_offset | 回访 user_id / 首日活跃 user_id |
对齐建议：指标定义应提前与业务方、数据产品经理对齐，形成《埋点指标字典》，避免后续出现“同指标不同值”的现象。
1.5 选型权衡与风险点
- Reach 埋点性能：高频 Reach 事件（如每帧渲染）可能消耗 Agent 端资源，需做采样或降频。权衡：粗粒度损失归因精度，细粒度增加带宽。
- Impact 归因窗口：Reach 到 Impact 的时间窗口过长可能导致归因混淆（如用户隔天再点击）。建议默认窗口 10 分钟，业务可配置。
- 数据一致性风险：Reach 事件若因网络延迟未上报，后续 Impact 事件将成为“孤儿事件”。需设计补发机制或离线对账。
1.6 落地步骤（第一阶段）
- 确定关键 Reach 事件列表（至少 3 类：push、card、voice）。
- 确定关键 Impact 事件列表（点击、提交、关闭、转化）。
- 定义 session_id 生成规则与传递链路（Agent → 前端 → 后端）。
- 制定 Reach 事件的上报频率与采样率策略。
- 搭建离线对账任务，定时校验 Reach 与 Impact 的 session_id 链路完整度。
1.7 验收标准
- Reach 事件在 Agent 渲染完成后 500ms 内发出，不可遗漏。
- Impact 事件必须携带正确的 session_id，链路完整度 ≥ 99.5%。
- Reach 与 Impact 的指标口径与业务方签字确认的《指标字典》完全一致。
- 压测条件下（10 条/秒 Reach + 2 条/秒 Impact），Agent 端 CPU 增量 ≤ 5%。