埋点方案设计使用说明

适用前提：已按《Sensors CLI 接入与使用》完成 CLI 安装、首次配置和 AI Skills 安装 核心依赖 Skill：sensors-tracking

简介

AI 埋点方案设计用于将 PRD、需求说明、设计稿、截图、历史方案或自然语言需求，转化为标准化、可评审、可交付给研发实施的埋点采集方案。

核心依赖 Skill：sensors-tracking

使用前准备

本文默认您已经完成 Sensors CLI 的安装、配置和 AI Skills 安装。安装包解压、Base URL、API Key、Project、健康检查等基础接入步骤，请参考《Sensors CLI 接入与使用》，本文不重复展开。

开始前请准备以下信息：

准备项	说明
需求材料	PRD、需求说明、设计稿说明、截图、历史埋点方案、指标说明或自然语言需求
输入目录	在需要生成方案的项目目录或资料目录中打开 AI 编程工具
目标神策项目	默认使用 Sensors CLI 当前配置中的Project，用于查询已有事件、属性和用户属性
源码目录（可选）	当需要判断触发位置、端覆盖或属性是否可采集，可提供源码目录

建议先执行一次健康检查：

sensors doctor

若健康检查未通过，请先修复 CLI 配置，再发起埋点方案设计。

推荐材料格式

如果已有完整 PRD，可以直接提供 PRD 路径或链接。若材料比较分散，建议先整理一个入口文档，把业务背景、材料位置和本次范围写清楚，比如类似下述方式：

# 会员中心改版埋点需求

## 输入材料

- PRD：docs/prd/会员中心改版.md
- 设计稿说明：docs/design/会员中心页面说明.md
- 历史埋点方案：docs/history/会员中心历史埋点.xlsx
- 关键截图：docs/screenshots/

## 本次范围

- 会员中心首页
- 会员权益领取
- 会员任务完成

## 主要分析诉求

- 看用户是否能顺利发现并领取权益
- 看任务入口和任务完成转化
- 对比不同会员等级的权益使用差异

不需要提前手工编写完整事件表。AI 会先理解业务目标和指标，再推导事件、属性、触发时机和复用关系。

发起埋点方案设计

您可以通过以下两种方式唤起 sensors-tracking 的方案设计能力。

方式一：自然语言发起（推荐）

在 AI 编程工具中，直接描述您的需求并指定材料路径或链接：

请使用 sensors-tracking 为当前项目生成埋点采集方案，需求材料在 docs/会员中心改版PRD.md。

如果需求材料是在线文档，也可以直接提供链接：

请使用 sensors-tracking 根据这个 PRD 链接生成埋点采集方案：https://example.com/prd。

如果希望 AI 同时结合源码判断触发位置和属性来源，可以补充说明：

请使用 sensors-tracking 基于 docs/支付流程PRD.md 生成埋点采集方案，并结合当前项目源码判断触发时机和属性来源。

方式二：快捷命令

如果您习惯使用快捷命令，可直接执行：

/sensors-tracking plan --requirements <需求材料路径或链接>

需要指定目标项目或源码目录时，可使用：

/sensors-tracking plan --requirements <需求材料路径或链接> \
  --target-project <神策项目英文名> \
  --source-root <源码目录>

通常不需要传 --target-project。未指定时，AI 默认读取当前 Sensors CLI 配置中的 Project。只有需要临时切换目标项目或覆盖当前配置时，才建议显式传入。

设计过程与确认节点

发起指令后，AI 会自动执行标准化流程。过程中遇到需要业务判断的节点时，AI 会暂停并请您确认。

Step 1：需求解析与证据整理

AI 会读取 PRD、文档、截图、历史方案或自然语言输入，并整理本次需求中的业务范围、目标候选、分析诉求、页面路径、关键行为和不确定项。

您需要关注：本次范围是否正确，是否遗漏关键页面、关键流程或关键分析诉求。

Step 2：确认业务目标

AI 会根据需求材料生成业务目标候选。您需要确认主目标，以及是否需要保留次目标。

确认重点：

• 本次埋点要支持什么业务结果或决策。
• 指标变化后业务方可以采取什么动作。
• 是否存在需要补充说明的目标人群、时间范围或成功定义。

Step 3：确认指标口径

AI 会从已确认业务目标拆解决策问题和指标口径。您需要确认每个指标是否符合真实分析诉求。

确认重点：

• 指标名称和口径是否准确。
• 统计主体、时间窗口、维度和过滤条件是否符合预期。
• 数据依赖是否合理，例如来自前端行为、后端结果、业务 ID 串联或已有神策元数据。

Step 4：确认事件框架

AI 会根据指标反推用户路径、关键触发点、前后端责任边界和业务 ID 串联方式，并生成事件框架。

确认重点：

• 事件命名策略是否符合团队规范。
• 事件颗粒度是否合适，是拆事件还是用属性表达状态。
• 触发时机是否能指导研发实施，例如“支付成功回调后”而不是“支付时”。
• 哪些事件由前端上报，哪些由后端上报，是否需要业务 ID 或 trace_id 串联。
• 公共属性、枚举字典和全埋点/标准事件复用是否合理。

Step 5：确认最终方案

AI 会通过 Sensors CLI 查询目标神策项目已有事件、事件属性和用户属性，优先判断复用；无法复用时生成新增差量，并执行机器校验。

最终确认前请重点检查：

• 全量事件和属性是否覆盖本次业务范围。
• 事件显示名、属性显示名、属性类型和是否必填是否正确。
• 复用已有事件/属性的结论是否合理。
• 新增事件和新增属性是否需要先在神策平台准备。
• 报告中是否存在阻断项或待人工处理项。

完成标准

当 AI 完成方案设计后，您应至少拿到以下两类可交付产物：

1. 全量埋点采集方案 Excel：用于团队评审，并作为后续埋点实施输入。
2. 埋点方案设计报告：用于查看本次需求、目标、指标、事件设计、确认记录、风险和后续待办。

如果方案中包含新增元数据，还会生成元数据差量文件和批量创建 Excel，供平台元数据准备使用。

如果存在未解决的阻断项，例如平台元数据缺失、属性类型冲突、用户属性未处理、源码证据不足等，AI 会在报告中标明。此时可以先完成方案评审，但进入实施前需要处理这些阻塞问题。

查看最终产物和报告

方案设计完成后，主要产物会生成在当前项目目录下：

analytics/planning/results/
analytics/planning/reports/

常用产物如下：

产物名称	用途
*_埋点采集方案.xlsx	核心交付物。包含本次全量事件、属性、触发时机、上报端、复用/新增结论。后续埋点实施使用这个文件作为输入
埋点方案设计报告.html	面向产品、研发、测试、数据和交付团队的正式报告，用于查看方案结论、确认记录、风险和后续待办
埋点方案设计调试报告.html	面向研发和交付排查的调试报告，用于查看过程状态、内部产物、哈希和阻断原因
*_神策批量创建.xlsx	仅包含新增事件、新增属性和待建立关系，用于元数据审核或人工处理兜底

日常查看顺序建议：

1. 先打开 埋点方案设计报告.html，确认整体结论、风险和待办。
2. 再打开 *_埋点采集方案.xlsx，逐项评审事件、属性、触发时机和上报端。
3. 若报告提示元数据待处理，再查看 *_神策批量创建.xlsx。
4. 若报告提示阻断或异常，再查看 埋点方案设计调试报告.html。

进入后续埋点实施

确认全量采集方案后，可参考《埋点实施》继续执行代码落地：

/sensors-tracking implement --plan <全量埋点采集方案.xlsx> --server-url <数据接收地址>

注意：

• server_url 必须包含非空 project 参数，例如 https://example.com/sa?project=default。
• server_url 用于 SDK 上报，可能与 Sensors CLI 的 Base URL 不同，但必须同属一套神策环境。
• 埋点实施会重新执行实施侧元数据校验，不能用方案设计阶段的结论跳过。
• *_神策批量创建.xlsx 只包含新增差量，不能作为实施输入；实施输入必须使用全量埋点采集方案 Excel。

代码实施完成后，可参考《埋点测试》执行运行时 Debug 验证：

/sensors-tracking verify --debug

常见问题

问题现象	解决方案
不知道是否需要指定目标项目	通常不需要。默认使用当前 Sensors CLI 配置中的Project
需求材料只有 PRD，没有源码	可以先生成埋点方案；如果触发位置或属性可得性无法证明，报告中会提示补充源码或人工确认
只生成埋点方案设计，不需要写入元数据	可以停在方案交付阶段，不执行元数据写入授权
方案提示事件或属性未创建	根据metadata-delta.json 或批量创建 Excel 补齐平台元数据后，再进入实施
方案包含用户属性或用户关联变更	根据报告中的待办完成处理后，再判断是否可实施