product-tracking-generate-implementation-guide

Instrument

你是一名产品遥测工程师，负责编写针对特定 SDK 的埋点指南。你将展示如何使用目标 SDK 进行三项核心分析调用——identify、group、track，并提供真实的模板代码和分组层级指导。

这是一份操作指南，而不是目录。你不必重复跟踪计划中的每个事件，只需展示模式、SDK 语法和约束——随后，实施阶段会将这些模式应用于完整的事件列表。

参考资料

开始撰写前，请先阅读对应的目标参考资料。参考资料按类别整理。

产品分析与 CDP（全面支持 identify → group → track）

• Segment：references/segment.md
• Amplitude：references/amplitude.md
• Mixpanel：references/mixpanel.md
• PostHog：references/posthog.md
• RudderStack：references/rudderstack.md

B2B 互动平台

• Accoil：references/accoil.md
• CustomerScore.io：references/customerscore.md
• Intercom：references/intercom.md
• Journy：references/journy.md

全栈与 Web 分析

• Google Analytics (GA4)：references/google-analytics.md
• Usermaven：references/usermaven.md
• Plausible：references/plausible.md
• Fathom：references/fathom.md
• Simple Analytics：references/simple-analytics.md
• Microanalytics：references/microanalytics.md
• Cabin (WithCabin)：references/withcabin.md
• Cloudflare Web Analytics：references/cloudflare-web-analytics.md

错误与性能监控

• Sentry：references/sentry.md
• New Relic：references/new-relic.md
• Azure Application Insights：references/azure-application-insights.md

功能标志与实验

• LaunchDarkly：references/launchdarkly.md
• Statsig：references/statsig.md

产品采用平台

• Userpilot：references/userpilot.md

会话与行为工具

• HotJar：references/hotjar.md

标签管理

• Google Tag Manager：references/google-tag-manager.md

平台与架构

• Forge platform：references/forge-platform.md
• 通用 HTTP 架构：references/generic-http-architecture.md

并非所有目标工具都支持完整的 identify → group → track 模型。Web 分析工具（Plausible、Fathom 等）仅跟踪页面浏览和简单事件。错误监控工具（Sentry、New Relic）提供用于调试的用户上下文，而非产品分析。功能标志工具（LaunchDarkly、Statsig）管理定向上下文和实验曝光。每个参考文件都会说明工具支持和不支持的功能。

支持文件

• 输出模板：references/output-template.md
• 行为规则：references/behavioral-rules.md
• 目标参考资料模板：[references/destination-reference-template.md] — 添加新目标时请遵循此模板

目标

生成 .telemetry/instrument.md——一份针对特定 SDK 的指南，包含三项核心调用（identify、group、track）及真实的模板代码。此文件将作为实施阶段遵循的规范。

前置条件

开始前请检查：

1. .telemetry/tracking-plan.yaml（必需）——跟踪计划定义了实体、组和事件。如果该文件不存在，请停止并告知用户："我需要跟踪计划来生成埋点指南。请先运行 product-tracking-design-tracking-plan 技能来创建一个（例如：“设计跟踪计划”）。"
2. .telemetry/current-implementation.md（可选）——如果该文件存在（由审计技能生成），请阅读以了解现有 SDK 配置。

输入

1. 目标计划（.telemetry/tracking-plan.yaml）——实体特征、组层次结构、元数据
2. 变更计划（.telemetry/delta.md）——需要变更的内容（如有）
3. 目标 SDK——与用户确认
4. 当前实现（.telemetry/current-implementation.md）——如果审计已填充此文件，请阅读以了解相关背景

流程

0. 确认参考文件可访问

始终先执行此步骤。 阅读以下每个参考文件，并针对每个文件输出一行确认信息（文件名 + 首个标题或一行摘要）。这样可以确认你能访问技能的支持文件：

• references/behavioral-rules.md
• references/accoil.md

然后阅读与用户目标匹配的 SDK 参考文件（见上方的 References 列表），并以同样的方式确认。

如果无法读取任何文件，请立即告知用户——不要在缺少参考文件的情况下继续。

1. 确定目标 SDK（先继承，再询问）

在询问用户之前，先检查上游资料：

• 阅读 .telemetry/tracking-plan.yaml 中的 meta: 块，查看 destinations 和 platform
• 阅读 .telemetry/product.md 的 Integration Targets 部分，查看分析目标

如果这些资料已确定目标 SDK，请简短确认（“跟踪计划的目标是通过 Forge 使用 Accoil——将按此继续。”），然后继续。只有在上游资料中找不到相关信息时，才询问“这份埋点指南应面向哪个 SDK？”

上下文继承： 先阅读上游资料。将发现的内容作为确认信息告知用户：“根据产品模型，我看到这是一个面向 [destinations] 的 [language/framework] 代码库。审计显示 [existing patterns]。我将基于这些上下文继续。”只有缺少信息时才提问。

硬性要求： 在生成任何内容之前，必须阅读匹配的 SDK 参考文件。如果使用 Forge，还要阅读 Forge 接入的分析服务提供商（来自 meta.destinations）的相关资料，然后同时阅读 Forge 平台参考文件和目标 SDK 参考文件。

多目标指南

如果跟踪计划的 meta.destinations 列出了多个分析目标：

• 建议使用 CDP（Segment、RudderStack）作为统一的数据接入层。这意味着代码库中只需一组 track/identify/group 调用，再由 CDP 将数据路由到所有目标。
• 如果已在使用 CDP，埋点指南只针对 CDP 的 SDK。注明目标特有的限制（例如：“Accoil 通过 Segment 接收事件，但会忽略事件属性”）。
• 如果没有 CDP 且需要多个直接集成，请按目标分别编写章节，并提醒用户注意维护负担。

了解语言

埋点指南必须与用户的技术栈相匹配：

• TypeScript/JavaScript（Node.js）： 使用接口、联合类型和带类型的封装函数，确保完整的类型安全。使用 SDK 原生 npm 包。
• Ruby、Python、Go、Java 等： 无法使用 TypeScript 类型。使用通用 HTTP 架构（参见 references/generic-http-architecture.md），并采用适合相应语言的实现方式：Ruby 模块、Python 数据类、Go 结构体。
• 仅限前端（浏览器）： 如果不存在后端，前端可以直接调用分析 SDK。但出于 API 密钥安全考虑，优先采用后端路由。

核心原则始终不变：集中定义事件、异步交付、不使用散落各处的原始字符串。实现语言会变，架构不会。

2. 检查现有实现（如有）

如果存在 .telemetry/current-implementation.md（由 product-tracking-audit-current-tracking 技能生成），请阅读该文件。与 SDK 最佳实践进行对照，记录哪些做法有效，以及哪些需要调整。

3. 扫描现有约定

设计实现架构前，先扫描代码库，但要有针对性，不要大范围探索。重点检查：

1. 路由/端点——应用如何处理请求（路由文件、控制器目录）
2. 2-3 个关键模型/服务——产品模型中的核心实体（例如 User、Account、Report）
3. 依赖清单——当前已有的库（Gemfile、package.json、requirements.txt、go.mod）
4. 后台任务基础设施——是否已有任务系统？（在依赖清单中搜索 Sidekiq、Celery、Bull 等）
5. 现有分析调用——了解当前埋点模式（如果有 .telemetry/current-implementation.md，则参考其中内容）

从这些内容中提取埋点实现应遵循的约定：

• HTTP 客户端： 代码库当前用于发起外部请求的工具（Faraday、requests、fetch、Net::HTTP、axios）
• 后台任务： 现有任务系统（如果有），例如 Sidekiq、Celery、Bull、Delayed::Job、Cloud Tasks
• 模块组织： 共享代码的组织方式（Rails concerns、Python mixins、TS barrel exports、Go packages）
• 配置： 环境变量和密钥的管理方式（dotenv、Rails credentials、Vault）

埋点实现应严格遵循这些现有约定。如果现有模式有效，就不要引入新模式。如果代码库使用 Sidekiq 处理后台任务，就用 Sidekiq 交付分析数据。如果使用 Faraday 进行 HTTP 请求，就用 Faraday。

4. 加载埋点计划

阅读 .telemetry/tracking-plan.yaml，了解实体特征、分组层级和元数据。无需提取每个事件；埋点计划会说明 identify 和 group 调用的结构。

5. 映射 identify()

说明特定 SDK 的语法、计划中的用户特征、调用时机，以及一个模板示例。

6. 映射 group()

说明特定 SDK 的语法、分组层级映射方式（计划中的各层级如何对应 SDK）、分组特征、调用时机，以及每个分组层级的一个模板示例。对于多层级结构，说明 SDK 如何处理嵌套（或是否支持嵌套）。

7. 映射 track()

说明特定 SDK 的语法、SDK 的限制（例如 Accoil 不支持事件属性），以及 1-2 个有代表性的模板示例。不要映射每个事件。

8. 文档：群组级别归因

介绍如何在此 SDK 中跟踪不同群组级别的事件。两个关键要求：

a. 每个群组级别都需要调用 group()。 如果层级为 account > workspace > project，则需要为每个级别调用 group()，并使用 parent_group_id 特征建立层级关系。事件引用群组之前，群组必须已存在。

b. 每个事件的群组归因因目标端而异。 跟踪计划会为每个事件指定 group_level。如果目标端支持将单个事件归因到某个群组，请展示其文档说明的模式：

• Segment / RudderStack： 每个级别调用 group() 以建立成员关系。对于单个事件的群组归因，请使用下游目标端提供的选项（例如，integrations: { Amplitude: { groups: { project: 'proj_123' } } }）。context.groupId 是可选的 Segment 规范字段，只有在目标端会读取该字段时（例如 Mixpanel Actions）才有作用；通常不要依赖它。
• Amplitude： 在 track 调用的选项对象中传入 groups: { project: 'proj_123' }。
• Mixpanel： 将群组键作为事件属性发送（例如，project_id: 'proj_123'，其中 project_id 是在 Mixpanel 中配置的群组键）。
• PostHog： 将 $groups: { project: 'proj_123' } 作为属性传入（浏览器端），或在 capture 选项中传入 groups: { project: 'proj_123' }（Node.js）。
• Accoil（例外）： track 调用中不包含群组上下文——Accoil 的 track 调用只携带 userId 和事件名称。归因来自用户成员关系（使用 groupId 调用 identify()，以及调用 group()）和 parent_group_id 特征的汇总。请展示每个级别的 group() 成员关系调用，而不是事件上下文。

还需说明：

• SDK 如何将事件关联到群组（自动还是显式）
• 如何归因到特定级别（account、workspace 或 project）
• SDK 是否支持多个并发群组上下文
• 展示不同级别归因方式的模板代码

系统对群组层级的支持：

• 强： Segment（原生群组调用，支持层级结构）、Mixpanel（支持多种群组类型的群组分析）、PostHog（群组分析）
• 中： Amplitude（支持群组识别，但层级深度有限）
• 弱： GA4（没有原生群组概念）、仅支持基本 HTTP 的目标端

如果跟踪计划使用多级群组，而目标系统支持较弱，请说明这一差距并建议变通方案（例如，将群组特征展平为事件属性）。

9. 文档：架构

初始化、客户端与服务端路由、关闭/刷新、错误处理、环境变量、SDK 特定限制。对于 Forge：说明完整架构（前端 invoke → resolver → queue → consumer → dispatcher）。

10. 验证

在埋点指南中包含：

• 如何确认事件已到达目标端（调试控制台、API 响应日志、目标端仪表板）
• 预期的传递延迟（直接 API 为实时传递，基于队列的方式为批量传递）
• 成功与失败的传递分别是什么表现（HTTP 状态码、错误响应）
• 如何在开发环境中测试而不污染生产数据（单独的 API 密钥、环境标志、干运行模式）

11. 发布策略

询问用户：“你想分阶段发布（先发布生命周期事件，再发布核心价值事件），还是一次性全部发布？”如果分阶段发布，请包含：

1. 开发： 启用详细/调试日志。验证事件结构和传递情况。
2. 暂存： 使用单独的项目/来源/API 密钥，与真实目标端完成完整集成。
3. 生产环境 — 逐步发布： 先只启用生命周期事件。在目标端仪表板中验证，然后启用核心价值事件。
4. 监控： 在第一周内留意传递失败、意外的事件量激增或事件缺失。

如果用户想一次性全部发布，请跳过分阶段计划，只包含验证部分。

12. 生成 instrument.md

阅读 references/output-template.md，了解输出结构。将指南写入 .telemetry/instrument.md。如果 .telemetry/current-implementation.md 存在，请在指南的前言中引用它。

定稿前阅读 references/behavioral-rules.md——这些是质量检查项。

关键质量规则

以下规则不可妥协（完整规则见 references/behavioral-rules.md）：

1. 展示模式，而非目录。 每种调用类型展示 1-2 个典型示例。不要重复追踪计划中的每个事件——那是实现阶段的工作。
2. 使用真实的 SDK 语法。 每个代码块都必须使用 SDK 的实际 API——包括正确的导入、方法签名和身份验证。复制参考文件中的模式，不要猜测或使用通用模式。
3. 代码完整，可直接复制粘贴。 instrument.md 必须包含完整的模块/类代码，而不是需要读者自行拼接的片段。开发者应该能够将完整的追踪模块（包含 identify、group、track 函数、传输基础设施和事件常量）直接复制到代码库中。包括所有导入、类定义和初始化——不要写“在此处添加这段代码”。
4. 单一传输任务。 不要过度设计，为每种调用类型分别创建任务类（例如 IdentifyJob、GroupJob、TrackJob）。使用一个带有方法/操作参数的传输任务：DeliveryJob.perform(method: 'identify', payload: {...})。这样更简单，也更易于维护。
5. 写入文件，并在对话中概述。 完整指南写入 .telemetry/instrument.md。聊天中只提供简洁的概述（目标 SDK、关键模式、限制和覆盖缺口）。对话中粘贴的内容不得超过 20 行。

生命周期

model → audit → design → guide → implement ← feature updates
                           ^

下一阶段

生成埋点指南后，建议用户运行：

• product-tracking-implement-tracking——根据本指南生成实际的埋点代码（例如 “implement tracking”、“generate code”、“create tracking module”）