先说一个几乎每家公司都经历过的场景。产品同学要上一版新功能，需求文档末尾写了一句「加几个埋点」。开发按自己的理解埋了 click_btn、submit_ok、page_view 三个事件，上线两周后产品想看「提交成功率」，在报表里翻了半小时没找到，最后发现埋点是有的，只不过名字跟谁想的都不一样，字段也对不上。这种乱不是技术问题，是口径问题。
而口径这件事，恰恰是最适合让 Agent 先干一遍的：命名、字段、上报时机、文档、上线后核对，全是有规则可依的重复劳动，而且做得越早越省事。
先说清这篇的位置。站内相邻的三篇都不是这个角度：AI Agent 数据分析怎么搭 管的是数据进仓库之后怎么算、怎么出报告；OpenClaw 数据质量门禁怎么设 管的是数据已经进来之后怎么拦空值、重复和异常波动；用 AI Agent 处理 Excel 表格 管的是表格层面的清洗与汇总。这一篇管的是更前面那一步——事件本身还没产生的时候，怎么把「埋什么、叫什么、什么时候上报」定清楚，并且上线之后能核对回来。前者是「算得对不对」，这一篇是「数据本身长得对不对」。
一、埋点乱起来，通常是三个原因
在谈怎么让 Agent 干活之前，先把病因说清。埋点出问题，九成是这三类：
- 命名没有统一规则。同一个动作，有人写
submit、有人写submit_click、有人写button_submit。下游做报表的人只能靠猜，猜错一次就是一次「数据不准」的争论。 - 属性字段各写各的。同一个「来源渠道」字段，A 页面传的是渠道 ID，B 页面传的是中文名，C 页面干脆没传。字段一旦没法对齐，后面所有按渠道拆分的分析全部作废。
- 埋完就没人管了。需求文档里那几行字，上线之后既没有清单也没有负责人，改版时随手删掉一段上报代码，没人知道，报表悄悄掉量，等到季度复盘才发现数据断了三个月。
三个原因背后其实是同一个问题：埋点是「先施工、后验收」的活，而绝大多数团队只有施工规范，没有验收动作。
二、先分工：Agent 该管什么、不该管什么
把 Agent 放进这条线，最容易的失败方式是一上来就让它「设计整套埋点」。它确实能生成一版看起来挺完整的方案，但里面会混进一堆猜的业务假设，反而给后面埋坑。更稳的分工是这样：
- Agent 负责一致性和完整性：按规范生成事件名、按模板补全字段、把文档和代码做对照、把缺口列成清单。
- Agent 负责重复执行：每次版本上线前跑一遍核对，把「新增没登记」「登记了没上报」「上报了字段不对」三类问题一次性列出来。
- 人负责定义口径：什么算「提交成功」、什么算「有效线索」，这是业务判断，不能交给模型猜。
换句话说，Agent 在这条线上是质检员和登记员，而不是产品经理。这条边界和 AI Agent 做 A/B 实验设计时怎么定指标口径 里讲的道理一样：口径这件事必须写死，机器才能沿着规则去查。
三、事件命名：一套能自动校验的规范
命名规范不用很复杂，但必须满足一个条件——能用正则表达出来，否则没法自动校验。一套够用的规则大致是这几条：
- 只小写字母加下划线，不用驼峰、不用中文、不用缩写。缩写是埋点混乱的头号来源，因为每个人对缩写的理解都不一样。
- 结构固定为「对象_动作_结果」，例如
order_submit_success、form_submit_fail。三段式的好处是同一批事件能按前缀聚合，报表层面天然可分组。 - 动作词只用一份受控词表，比如 view、click、submit、success、fail、cancel 六个就够覆盖大多数场景。词表之外的动词一律驳回，逼着团队收敛。
- 不许带版本号和日期。
submit_v2、submit_2026这种名字一旦出现，说明设计时没想清版本怎么区分，版本应该落在字段里。
让 Agent 干这件事的价值在于「守门」：新提的事件名一旦不符合词表和结构，直接标红并给出改名建议，而不是等到报表阶段才发现对不上。这一步是纯规则校验，准确率高、几乎不用人复核，属于投入产出最划算的一段。
四、属性字段：必填、可选和「不许埋」
字段比事件名更容易出事。建议每个事件都按三类处理：
- 公共必填字段：用户身份、设备与端、页面标识、时间戳、版本号。这几个字段要由 SDK 统一注入，业务方不许自己传，避免同一字段在不同页面口径不一致。
- 事件可选字段：只跟某个事件相关的上下文，比如列表页的排序方式、搜索的关键词长度区间。可选字段要规定取值格式，不接受自由文本。
- 明确「不许埋」的字段：手机号、证件号、精确地址、聊天原文这类个人信息一律不进事件属性。这一点别指望写文档就能约束住，得在规则里做成硬拦截，思路可以直接沿用 AI Agent 处理个人信息怎么合规 里那套分级加最小字段的做法。
Agent 在这里做两件事：一是对着字段字典检查新方案，缺必填的标红；二是拿已有的埋点定义反查代码，把「代码里传了但字典里没有」的野字段挑出来。野字段是数据泄漏最常见的口子，定期扫一遍比出事后再查便宜得多。
五、上报时机：曝光、点击、完成要分开
「按钮点击数」和「提交成功数」在马虎的实现里经常被混成一个事件，最后做漏斗发现每一层都对不上。上报时机至少要分清三种：
- 曝光：元素真正进入可视区才算，而不是接口返回就算。判断标准要写死，比如「可见面积超过一半且持续 500 毫秒」。
- 点击：只记录用户意图，不记录结果。点击之后接口失败也是有点击的。
- 完成：以业务结果为准，成功和失败分开成两个事件，别用一个事件加一个布尔字段糊过去——布尔字段在报表层最难按天对比。
另外两个常被忽略的细节值得写进规范：去重（同一次会话内重复曝光怎么算）和补报（断网后恢复要不要补，补的话时间戳用哪个）。这两条不写清，数据从第一天开始就脏。
六、埋点文档：从散落的注释到一份可检索清单
文档这件事，关键不是写得漂亮，而是能被机器读。建议不要用一份大 Word 硬维护，而是做成结构化的清单：一个事件一行，字段包括事件名、中文说明、触发时机、必填属性、负责人、上线版本、当前状态。格式用 Markdown 表或 CSV 都行，能被脚本直接读就够。
有了这份清单，Agent 能做的核对就具体了：新增事件是否登记、登记的事件是否已在代码中出现、字段是否与字典一致、负责人是否为空。清单里「负责人」这一列千万别省，它是后面所有问题能找到人的前提。归档与版本维护的动作可以直接参考 OpenClaw 做文档归档与借阅管理 里的编号和版本状态做法。
七、上线后核对：文档、代码、真实数据三路对齐
这是整条线里最值钱的一步，也是最容易被跳过的。上线后要核对三路数据，两两之间都要能对上：
- 文档与代码：清单里登记的事件，代码里是否真的有上报点；反过来，代码里的上报点是否都在清单里。
- 代码与数据：上报点存在，不等于数据真的到了。要抽几个事件在测试环境真实触发一次，确认在数据源里能查到。
- 数据与预期：上线首日的数据量级是否符合大致预期。突然为 0，通常是被前置条件挡掉；突然暴涨，通常是循环里误埋了上报。
这三路核对建议做成版本级动作，跟发布流程绑在一起。做法上和 OpenClaw 变更后验证清单 是同一套思路：变更之后必须验，否则改动就是不可信的。抽样方法可以借用 OpenClaw 人工复核抽检 的思路——不用全量查，但新增和高价值事件必须查。
八、四条边界
埋点这条线上的 Agent，有四件事必须明确不做：
- 不替业务定口径。「什么算转化」是业务决策，Agent 只能把现有口径翻译成可校验的规则。
- 不自动改线上代码。它可以生成补丁建议和问题清单，合并动作由人来做，避免误改上报逻辑导致数据断档。
- 不承诺一次埋全。它只能保证「已经登记的事件」内部一致，不能保证业务上有没有漏掉场景，漏场景还得靠产品与数据同学一起过需求。
- 不把候选人式信息写进事件。用户标识只存内部 ID，不落手机号、邮箱和姓名，敏感字段一律不进事件属性。
九、五个坑
- 把埋点方案一次性交给模型生成。生成的东西看着全，但业务假设靠猜，事后纠正的成本比从头定更高。
- 只校验命名不校验字段。名字统一了，字段各写各的，报表照样对不上。两边必须一起管。
- 文档和代码两条线维护。只要文档是人工同步的，三个月后一定不同步，必须让核对动作跑起来。
- 拿线上数据做埋点测试。测试事件混进生产数据源，最轻的代价是要清洗一批脏数据，重的会污染报表历史。
- 没定谁负责收口。埋点问题最常见的归宿是「谁都能提，谁都不改」，指定一个收口人比多加十个规则有用。
十、哪类团队适合这么干
如果你们是这三种情况，投入做这套规则的回报会很直接：一是产品迭代快、每两三个月就有一批新功能，埋点是长期反复的活；二是已经有相对固定的报表体系，口径混乱带来的争议成本高；三是团队里同时有产品、开发和数据三方，沟通成本本身就是主要开销。
反过来，如果只有一两个人维护、埋点需求一两个月才动一次，那先用一份受控词表和一份清单文档把规矩立住就够了，不必上更复杂的自动化。埋点这件事，规范的价值永远大于工具——工具只是让规范能被自动执行而已。
0 条评论