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

instrument-product-analytics

数据与分析

查看项目

更新于 10-15 03:31

技能介绍

用途

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

主要能力

  • 检测代码库平台与包管理器，判断是否已存在 PostHog 设置。
  • 针对检测到的框架查找参考文件，作为 SDK 初始化、Provider 设置和事件捕获模式的依据。
  • 安装并初始化 PostHog SDK。
  • 规划事件追踪：从项目文件列表中选取 10 到 15 个可能具有业务价值的文件，重点关注转化和流失事件；查找与登录相关的文件用于识别用户，以及错误处理相关文件；查找已有的 posthog.capture() 代码，注意事件命名格式，不重复已有事件。
  • 实现事件捕获：为每个规划的事件添加带属性的 posthog.capture() 调用；若文件已有其他工具或服务的集成代码，不覆盖或删除，将 PostHog 代码置于其下；不改变现有文件的根本架构，仅做最小化、有针对性的添加。
  • 识别用户：在客户端登录和注册事件时添加 PostHog identify() 调用，使用登录和注册表单内容在提交时识别用户；若前后端都存在，通过 X-POSTHOG-DISTINCT-ID 和 X-POSTHOG-SESSION-ID 请求头将客户端会话和 distinct ID 传递给服务端代码。
  • 添加错误追踪：在相关文件中添加 PostHog 异常捕获错误追踪，尤其是关键用户流程和 API 边界附近。
  • 设置环境变量：检查项目是否已配置 PostHog 环境变量；若缺少项目 token，使用 PostHog MCP 服务器的 projects-get 工具获取 api_token；若返回多个项目则询问用户；若 MCP 服务器未连接或未认证，则询问用户提供 token。对于 host URL，检查 projects-get 响应中的 region 字段，US 对应 https://us.i.posthog.com，EU 对应 https://eu.i.posthog.com；若无法确定则询问用户，不假设为 US Cloud。将值写入适当的环境文件，并在代码中引用环境变量而非硬编码。
  • 验证与清理：检查项目错误，查找类型检查或构建脚本；确保创建的组件被实际使用；仅对本次会话编辑或创建的文件运行 linter 或 prettier 类脚本，不跨整个代码库运行。

使用方式

按顺序执行以下步骤：

  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 设置，若已安装并初始化则跳至第 5 步。
  2. 研究集成（若已设置则跳过）。找到与检测到的框架匹配的参考文件，它是 SDK 初始化、Provider 设置和事件捕获模式的依据；若无匹配参考，回退到通用知识和网络搜索，以 posthog.com/docs 为主要搜索来源。
  3. 安装 PostHog SDK（若已设置则跳过）。为检测到的平台添加 PostHog SDK 包，不要手动编辑 package.json，使用包管理器的安装命令。
  4. 初始化 PostHog（若已设置则跳过）。遵循框架参考确定初始化的位置和方式，不同框架差异显著（例如 Next.js 15.3+ 使用 instrumentation-client.ts，Django 使用 AppConfig.ready()，Flask 使用 create_app()）。
  5. 规划事件追踪。从项目文件列表中选取 10 到 15 个可能具有业务价值的文件，尤其是转化和流失事件；查找与登录相关的文件用于识别用户，以及错误处理相关文件；查找已有的 posthog.capture() 代码，注意事件命名格式，不重复已有事件，而是补充它们；仅追踪动作而非页面浏览（页面浏览可自动捕获），转化漏斗顶部的“viewed”类事件可例外；若项目包含任何可插桩的服务端代码（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 项目 token，使用 PostHog MCP 服务器的 projects-get 工具获取项目的 api_token；若返回多个项目，询问用户使用哪个项目；若 MCP 服务器未连接或未认证，则询问用户提供 PostHog 项目 token。对于 PostHog host URL：检查 projects-get MCP 响应中的 region 字段，US 映射到 https://us.i.posthog.com，EU 映射到 https://eu.i.posthog.com；若 MCP 响应或现有项目配置中无法获得 region，询问用户：“Are you on PostHog US Cloud or EU Cloud?”，不要假设 US Cloud。使用框架的命名约定将这些值写入适当的环境文件；在代码中引用这些环境变量而非硬编码。
  10. 验证与清理。检查项目错误，查找 package.json 中的类型检查或构建脚本；确保创建的组件被实际使用；运行 package.json 中找到的 linter 或 prettier 类脚本，但仅对本次会话中编辑或创建的文件运行，绝不跨整个项目代码库运行格式化或 linting。

参考文件

该技能包含大量参考文件，涵盖各框架的示例项目代码和集成指南，包括：

  • 示例项目代码：next-app-router、next-pages-router、react-react-router-6、react-react-router-7-framework、react-react-router-7-data、react-react-router-7-declarative、nuxt-3-6、nuxt-4、vue-3、react-tanstack-router-file-based、react-tanstack-router-code-based、tanstack-start、sveltekit、astro-static、astro-view-transitions、astro-ssr、astro-hybrid、angular、django、flask、fastapi、python、laravel、php、ruby-on-rails、ruby、android、swift、react-native、expo。
  • 框架集成指南：next-js、react-router-v6、react-router-v7-framework-mode（remix v3）、react-router-v7-data-mode、react-router-v7-declarative-mode、nuxt-js-3-6、nuxt-js、vue-js、tanstack-start、svelte、astro、angular、django、flask、python、posthog-python、dotnet、elixir、go、laravel、php、ruby-on-rails、ruby、android、ios、usage（iOS SDK 使用）、configuration（iOS SDK 配置）、flutter、react-native、identify-users、COMMANDMENTS（集成必须遵循的框架特定规则）。

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

关键原则

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

适用场景

  • 实现新功能后，需要追踪关键用户行为。
  • 审查 PR 时，确保有意义的用户动作被捕获。
  • 项目尚未安装 PostHog，需要初始 SDK 设置。
  • 需要跨多种框架和语言（Web、移动端、后端）统一接入产品分析。

限制

  • 该技能的具体收费、价格、平台限制等信息暂未提供。
  • 事件追踪规划需人工判断业务价值，选取 10 到 15 个文件。
  • 服务端事件在存在可插桩服务端代码时为必需。
  • 环境变量配置依赖 PostHog MCP 服务器或用户提供 token，region 无法确定时需询问用户。