instrument-product-analytics

添加 PostHog 产品分析事件

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

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

说明

按以下步骤依次执行：

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

查找依赖文件（package.json、pubspec.yaml、Podfile、Package.swift、requirements.txt、Gemfile、composer.json、go.mod、mix.exs 等），以确定框架和语言。

查找锁文件（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb、go.sum、pubspec.lock、Podfile.lock、Package.resolved、mix.lock），以确定包管理器。

• 检查是否已配置 PostHog。如果已安装并初始化 PostHog，跳到步骤 5。

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

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

• 为检测到的平台添加 PostHog SDK 包。不要手动编辑 package.json——请使用包管理器的安装命令。

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

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

步骤 5：规划事件追踪。

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

步骤 6：实现事件捕获。

• 为每个计划添加的事件，调用 posthog.capture() 并附上有用的属性。
• 如果文件中已有用于其他工具或服务的集成代码，不要覆盖或移除此代码。请在其下方添加 PostHog 代码。
• 不要改变现有文件的基本架构。添加内容应尽量精简且有针对性。
• 写入文件前，必须立即读取该文件。

步骤 7：识别用户。

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

步骤 8：添加错误追踪。

• 在相关文件中添加 PostHog 异常捕获错误追踪，尤其是在关键用户流程和 API 边界处。 步骤 9：设置环境变量。
• 检查项目是否已配置 PostHog 环境变量（例如在 .env、.env.local 或框架专用的环境变量文件中）。如果已有有效值，则跳过此步骤。
• 如果缺少 PostHog 项目令牌，请使用 PostHog MCP 服务的 projects-get 工具检索项目的 api_token。如果返回多个项目，请询问用户要使用哪个项目。如果 MCP 服务未连接或未通过身份验证，请改为向用户索取其 PostHog 项目令牌。
• 对于 PostHog 主机 URL：检查 projects-get MCP 响应中是否有 region 字段——US 对应 https://us.i.posthog.com，EU 对应 https://eu.i.posthog.com。如果 MCP 响应或现有项目配置中没有区域信息，请询问用户：“您使用的是 PostHog US Cloud 还是 EU Cloud？”不要默认使用 US Cloud。
• 使用框架的命名约定，将这些值写入适当的环境变量文件。
• 在代码中引用这些环境变量，而不是将其硬编码。

步骤 10：验证并清理。

• 检查项目是否存在错误。查看 package.json 中是否有类型检查或构建脚本。
• 确保创建的组件确实已被使用。
• 运行 package.json 中找到的任何 linter 或 Prettier 类脚本，但只能针对本次会话中编辑或创建的文件。切勿对整个项目代码库运行格式化或 lint。

参考文件

• 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-php.md - php 示例项目代码
• 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 框架模式（remix v3）
• references/react-router-v7-data-mode.md - React router v7 数据模式
• references/react-router-v7-declarative-mode.md - React router v7 声明式模式
• references/nuxt-js-3-6.md - Nuxt.js（v3.0 到 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/dotnet.md - .net
• references/elixir.md - Elixir
• references/go.md - Go
• references/laravel.md - Laravel
• references/php.md - Php
• references/ruby-on-rails.md - Ruby on rails
• references/ruby.md - Ruby
• references/android.md - Android
• references/ios.md - Ios
• references/usage.md - Ios SDK 用法
• references/configuration.md - Ios SDK 配置
• references/flutter.md - Flutter
• references/react-native.md - React native
• references/identify-users.md - 识别用户
• references/COMMANDMENTS.md - 集成必须遵循的特定框架规则

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

核心原则

• 环境变量：始终使用环境变量存储 PostHog 密钥。切勿将密钥硬编码。
• 最小改动：在现有集成旁添加 PostHog 代码。不要替换或重构现有代码。
• 遵循文档：严格按照框架参考中的初始化和捕获模式操作。