SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场product-tracking-implement-tracking

product-tracking-implement-tracking

数据与分析

查看项目

更新于 10-15 10:51

技能介绍

用途

该技能扮演产品遥测工程师的角色，执行增量计划（delta plan），把当前追踪状态与目标追踪计划之间的差异转化为真实、可运行的埋点代码。其目标是将增量计划（或完整目标计划）翻译为可直接实施的代码，包括：与追踪计划匹配的带类型事件定义、每个事件的 SDK 封装函数、身份管理（identify/group）、可选的开发期校验辅助函数，以及面向现有代码库的集成指南。最终输出为追踪代码，以及反映实际实现情况的更新版追踪计划。

前置条件

技能会先继承上下文：在提问前读取 .telemetry/instrument.md 与 .telemetry/product.md。实施指南包含 SDK 模式、架构决策与钩子放置位置；产品模型包含技术栈与语言。技能会先呈现已发现的信息，仅在缺失时才提问。

开始前需检查：

  • .telemetry/instrument.md（必需）——SDK 专属实施指南。若不存在，需先运行 product-tracking-generate-implementation-guide 技能创建。
  • .telemetry/tracking-plan.yaml（必需）——目标追踪计划。若不存在，需先运行 product-tracking-design-tracking-plan 技能创建。
  • .telemetry/delta.md（推荐）——若存在，优先实施增量；若仅有目标计划，则实施完整计划。

输入

  • 实施指南（.telemetry/instrument.md）——SDK 专属模式、模板代码、API 端点
  • 目标计划（.telemetry/tracking-plan.yaml）——应存在的内容
  • 增量计划（.telemetry/delta.md）——需要变更的内容（若有）
  • 当前状态（.telemetry/current-state.yaml）——当前已存在的内容（若有）
  • 环境——浏览器、Node.js 或两者
  • 语言——项目主要语言（JS 项目推荐 TypeScript）

实施流程

  1. 确认配置：读取 .telemetry/instrument.md，确认语言/框架与环境（浏览器、Node.js 或两者）。目标 SDK、API 端点与 SDK 专属模式已在 instrument.md 中定义，不再重复询问或重读原始 SDK 参考。

  2. 生成类型：为每个事件生成一个带类型定义。必需属性为非可选，可选属性使用 ?（或语言等价写法），枚举转为联合类型，PII 仅出现在 trait 接口中。严格遵循追踪计划中的实体与事件形状。对于无 group 层级的 B2C 产品，跳过 group 相关类型与函数，追踪模块只需 identify() 与 track() 封装。

  3. 生成 SDK 封装：按 .telemetry/instrument.md 中的模式生成带类型的封装函数，直接使用指南中的 SDK 调用签名、API 端点、认证模式与模板代码，不偏离指南模式。指南涵盖 identify()、group()、track() 的调用签名与映射，以及初始化、关闭/刷新、客户端与服务端路由等架构内容。每个事件生成一个函数。

  4. 生成校验辅助函数：可选，除非用户要求否则跳过。TypeScript 项目通常编译期检查已足够；仅当用户要求运行时校验或代码库使用无 TypeScript 的 JavaScript 时生成。

  5. 生成使用示例：展示如何在上下文中使用生成的代码。

  6. 生成集成指南：在 tracking/ 目录创建 README.md，说明如何安装 SDK 依赖、设置环境变量、导入与使用函数、计划变更后如何重新生成。

输出结构

输出结构随项目技术栈调整。TypeScript/JavaScript（默认）：tracking/ 目录下含 types.ts、tracking.ts、validate.ts（可选）、examples.ts、index.ts、README.md。Ruby、Python、Go 等其他语言：tracking/ 目录下含 events.[ext]、tracking.[ext]、examples.[ext]、README.md。非 TypeScript 语言需用语言等价物替换接口（Ruby 模块、Python dataclass、Go struct），保持集中式事件定义、带类型/文档化函数、不散落原始字符串的原则。若实施指南引用通用 HTTP 架构，则用项目原生语言实现基于队列的模式。

增量驱动实施

当存在增量计划时，实施应围绕增量组织。钩子位置映射是本技能的职责：实施指南展示模式与 SDK 语法，本技能将每个事件映射到代码库中具体文件与函数。需扫描代码库识别正确的钩子点（控制器、服务、回调、处理器）。

  • 新增事件：生成新类型接口、新追踪函数，识别调用应放置的具体文件与函数，提供上下文代码片段。
  • 重命名事件：生成正确名称的新追踪函数，识别旧调用所在文件，提供搜索替换指引。
  • 变更事件（属性错误）：生成更新后的类型接口，识别调用点，展示每处的前后对比。
  • 移除事件：识别调用点，提供移除指引。

增量更新

当 tracking/ 代码已存在时：先读取现有代码理解模块结构；应用增量而非重新生成；保留用户自定义修改；更新类型与导出；更新版本注释。

置信度检查

实施完成前需确认：目标计划中每个事件都有带类型函数；身份管理（identify + group）已覆盖；SDK 专属模式正确（非通用）；服务端关闭已处理（若 Node.js）；环境变量已记录；示例覆盖最常见用法。

验证

在 tracking/README.md 中包含供用户运行的验证步骤（技能本身不运行追踪调用、不发送事件、不使用 API 密钥）：开发环境试运行至少一次 track、identify、group 调用；检查分析目标调试控制台或日志确认事件送达；验证事件属性类型与值正确；确认开发/预发事件进入独立来源或项目而非生产；验证投递失败不会导致应用崩溃或阻塞用户操作。

行为规则

生成可编译运行的真实代码而非伪代码；遵循实施指南作为 SDK 模式的主要来源；完整读取所有输入；集中式事件名常量不可妥协（代码库中不得出现原始事件名字符串，所有 track 调用引用中央常量）；每个事件一个函数（除非事件名是计算得出的，此时用联合类型或查找表约束输入）；单一投递任务（队列投递使用一个任务类加方法参数）；增量优先、完整计划其次；包含难点（服务端关闭、group 上下文、PII 分离、错误处理、内部用户排除）；实施后更新计划；写入文件并在对话中简要总结（不超过 20 行代码）；呈现决策而非思考过程。

生命周期与后续

生命周期：model → audit → design → guide → implement ← feature updates。实施后建议用户运行 product-tracking-audit-current-tracking（可选重新审计以验证实现与计划一致）或 product-tracking-instrument-new-feature（新功能发布时保持追踪一致）。