omnibus-instrument-product-analytics

添加 PostHog 产品分析事件

使用此技能添加产品分析事件（capture 调用），以追踪新代码或变更代码中的重要用户行为。在实现功能或审查 PR 后使用此技能，确保捕获关键用户行为。如果尚未安装 PostHog，此技能也涵盖 SDK 的初始设置。支持任何框架或语言。

支持的框架：Next.js、React Router、Nuxt、Vue、TanStack Start、SvelteKit、Astro、Angular、Django、Flask、FastAPI、Laravel、Ruby on Rails、Android、iOS、React Native、Expo 等。

说明

请按以下步骤顺序执行：

STEP 1：分析代码库并检测平台。

• 查找依赖文件（package.json、requirements.txt、Gemfile、composer.json、go.mod 等），以确定框架和语言。
• 查找锁文件（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb），以确定包管理器。
• 检查是否已配置 PostHog。如果 PostHog 已安装并初始化，请跳至 STEP 5。

STEP 2：研究集成方式。（如果已配置 PostHog，则跳过。） 2.1. 找到下方与检测到的框架匹配的参考文件——它是 SDK 初始化、Provider 设置和事件捕获模式的权威依据。现在就阅读该文件。 2.2. 如果没有匹配的参考文件，请参考你的通用知识并进行网络搜索。优先搜索 posthog.com/docs。

STEP 3：安装 PostHog SDK。（如果已配置 PostHog，则跳过。）

• 为检测到的平台添加 PostHog SDK 包。不要手动编辑 package.json——使用包管理器的安装命令。
• 始终将包安装作为后台任务运行。不要等待安装完成；启动安装后立即继续其他工作。

STEP 4：初始化 PostHog。（如果已配置 PostHog，则跳过。）

• 按照框架参考中说明的位置和方式进行初始化。不同框架的差异很大（例如，Next.js 15.3+ 使用 instrumentation-client.ts，Django 使用 AppConfig.ready()，Flask 使用 create_app()）。

STEP 5：规划事件跟踪。

• 根据项目的文件列表，选出 10 到 15 个可能具有业务价值的文件来跟踪事件，尤其是转化和流失事件。
• 还要查找与登录相关的文件，以便识别用户，并查找错误处理相关文件。
• 查找现有的 posthog.capture() 代码，并记下事件名称的格式。不要重复已有事件；应在其基础上补充。
• 仅跟踪操作，不跟踪页面浏览（页面浏览可自动捕获）。转化漏斗顶部的“已查看”类事件可作为例外。
• 如果项目包含任何可埋点的服务端代码（API 路由、服务端操作、Webhook 处理程序、支付/结账完成处理、身份验证端点），则必须跟踪服务端事件。

STEP 6：实现事件捕获。

• 为每个规划的事件添加 posthog.capture() 调用，并附上有用的属性。
• 如果文件中已有其他工具或服务的集成代码，不要覆盖或删除这些代码。将 PostHog 代码添加在其后。
• 不要改变现有文件的基本架构。尽量只做必要且有针对性的改动。
• 尝试写入文件前，必须立即阅读该文件。

STEP 7：识别用户。

• 在登录和注册事件期间，在客户端添加 PostHog identify() 调用。提交时使用登录和注册表单的内容识别用户。
• 如果同时存在前端和后端，请使用 X-POSTHOG-DISTINCT-ID 和 X-POSTHOG-SESSION-ID 请求头将客户端会话和 distinct ID 传递给服务端代码。在服务端确保事件具有匹配的 distinct ID。

STEP 8：添加错误跟踪。

• 在相关文件中添加 PostHog 异常捕获错误跟踪，尤其是在关键用户流程和 API 边界处。

STEP 9：设置环境变量。

• 如果已连接 env-file-tools MCP 服务，请使用 check_env_keys 检查已有的键，然后使用 set_env_values 创建或更新 PostHog API 密钥和主机。
• 在代码中引用这些环境变量，而不要硬编码。

STEP 10：验证并清理。

• 检查项目是否存在错误。查找 package.json 中的类型检查或构建脚本。
• 确保创建的组件确实已被使用。
• 运行 package.json 中找到的任何代码检查或 Prettier 类脚本。

参考文件

• references/EXAMPLE-next-app-router.md - next-app-router 示例项目代码
• references/EXAMPLE-next-pages-router.md - next-pages-router 示例项目代码
• references/EXAMPLE-react-react-router-6.md - react-react-router-6 示例项目代码
• references/EXAMPLE-react-react-router-7-framework.md - react-react-router-7-framework 示例项目代码
• references/EXAMPLE-react-react-router-7-data.md - react-react-router-7-data 示例项目代码
• references/EXAMPLE-react-react-router-7-declarative.md - react-react-router-7-declarative 示例项目代码
• references/EXAMPLE-nuxt-3.6.md - nuxt-3.6 示例项目代码
• references/EXAMPLE-nuxt-4.md - nuxt-4 示例项目代码
• references/EXAMPLE-vue-3.md - vue-3 示例项目代码
• references/EXAMPLE-react-tanstack-router-file-based.md - react-tanstack-router-file-based 示例项目代码
• references/EXAMPLE-react-tanstack-router-code-based.md - react-tanstack-router-code-based 示例项目代码
• references/EXAMPLE-tanstack-start.md - tanstack-start 示例项目代码
• references/EXAMPLE-sveltekit.md - sveltekit 示例项目代码
• references/EXAMPLE-astro-static.md - astro-static 示例项目代码
• references/EXAMPLE-astro-view-transitions.md - astro-view-transitions 示例项目代码
• references/EXAMPLE-astro-ssr.md - astro-ssr 示例项目代码
• references/EXAMPLE-astro-hybrid.md - astro-hybrid 示例项目代码
• references/EXAMPLE-angular.md - angular 示例项目代码
• references/EXAMPLE-django.md - django 示例项目代码
• references/EXAMPLE-flask.md - flask 示例项目代码
• references/EXAMPLE-fastapi.md - fastapi 示例项目代码
• references/EXAMPLE-python.md - python 示例项目代码
• references/EXAMPLE-laravel.md - laravel 示例项目代码
• references/EXAMPLE-ruby-on-rails.md - ruby-on-rails 示例项目代码
• references/EXAMPLE-ruby.md - ruby 示例项目代码
• references/EXAMPLE-android.md - android 示例项目代码
• references/EXAMPLE-swift.md - swift 示例项目代码
• references/EXAMPLE-react-native.md - react-native 示例项目代码
• references/EXAMPLE-expo.md - expo 示例项目代码
• references/next-js.md - Next.js - 文档
• references/react-router-v6.md - React router v6 - 文档
• references/react-router-v7-framework-mode.md - React router v7 framework mode (remix v3) - 文档
• references/react-router-v7-data-mode.md - React router v7 data mode - 文档
• references/react-router-v7-declarative-mode.md - React router v7 declarative mode - 文档
• references/nuxt-js-3-6.md - Nuxt.js (v3.0 to v3.6) - 文档
• references/nuxt-js.md - Nuxt.js - 文档
• references/vue-js.md - Vue.js - 文档
• references/tanstack-start.md - Tanstack start - 文档
• references/svelte.md - Svelte - 文档
• references/astro.md - Astro - 文档
• references/angular.md - Angular - 文档
• references/django.md - Django - 文档
• references/flask.md - Flask - 文档
• references/python.md - Python - 文档
• references/posthog-python.md - PostHog python SDK
• references/laravel.md - Laravel - 文档
• references/ruby-on-rails.md - Ruby on rails - 文档
• references/ruby.md - Ruby - 文档
• references/android.md - Android - 文档
• references/ios.md - Ios - 文档
• references/react-native.md - React native - 文档
• references/identify-users.md - 识别用户 - 文档

每个框架参考文件都包含特定于 SDK 的安装、初始化和使用模式。请查找与用户技术栈匹配的文件。

核心原则

• 环境变量：始终使用环境变量存储 PostHog 密钥。不要将密钥硬编码。
• 尽量少改动：在现有集成旁添加 PostHog 代码。不要替换或重构现有代码。
• 遵循文档：严格遵循框架参考文件中的初始化和采集模式。