mcpField
O
omnibus-instrument-integration

omnibus-instrument-integration

github.com/posthog开发76100 次安装今天更新
代码仓库

关于 omnibus-instrument-integration

用于在应用中添加或审查 PostHog SDK 集成的技能。它会识别项目技术栈，并指导安装、初始化、用户识别、配置及验证，覆盖多种框架和语言。

主要功能

  1. 01识别框架与包管理器
  2. 02提供框架专属设置参考
  3. 03指导 SDK 安装与初始化
  4. 04涵盖用户识别和环境变量
  5. 05包含验证与清理步骤

适用场景

  1. 01为新应用添加 PostHog
  2. 02审查 PostHog 设置相关的拉取请求
  3. 03配置前后端 PostHog 集成

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/posthog/skills --skill omnibus-instrument-integration

安装后在 Claude Code 中输入/omnibus-instrument-integration确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
android.md
angular.md
astro.md
django.md
EXAMPLE-android.md
EXAMPLE-angular.md
EXAMPLE-astro-hybrid.md
EXAMPLE-astro-ssr.md
EXAMPLE-astro-static.md
EXAMPLE-astro-view-transitions.md
EXAMPLE-django.md
EXAMPLE-expo.md
EXAMPLE-fastapi.md
EXAMPLE-flask.md
EXAMPLE-javascript-node.md
EXAMPLE-javascript-web.md
EXAMPLE-laravel.md
EXAMPLE-next-app-router.md
EXAMPLE-next-pages-router.md
EXAMPLE-nuxt-3.6.md
EXAMPLE-nuxt-4.md
EXAMPLE-python.md
EXAMPLE-react-native.md
EXAMPLE-react-react-router-6.md
EXAMPLE-react-react-router-7-data.md
EXAMPLE-react-react-router-7-declarative.md
EXAMPLE-react-react-router-7-framework.md
EXAMPLE-react-tanstack-router-code-based.md
EXAMPLE-react-tanstack-router-file-based.md
EXAMPLE-react-vite.md

详细介绍

添加 PostHog SDK 集成

使用此技能将 PostHog SDK 添加到应用中。适用于首次设置 PostHog，或审核需要初始化 PostHog 的 PR。涵盖 SDK 安装、提供程序设置和基本配置。支持任何框架或语言。

支持的框架：Next.js、React、React Router、Vue、Nuxt、TanStack Start、SvelteKit、Astro、Angular、Django、Flask、FastAPI、Laravel、Ruby on Rails、Android、Swift、React Native、Expo、Node.js 和原生 JavaScript。

说明

请按顺序执行以下步骤：

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

  • 查找依赖文件（package.json、requirements.txt、Gemfile、composer.json、go.mod 等），以确定框架和语言。
  • 查找锁文件（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb），以确定包管理器。
  • 检查是否已有 PostHog 配置。如果 PostHog 已安装并初始化，请勿修改其代码。告知用户并跳至验证步骤。

步骤 2：研究集成方式。 2.1. 在下方查找与检测到的框架匹配的参考文件——它是 SDK 初始化、提供程序设置和配置模式的权威来源。现在阅读该文件。 2.2. 如果没有匹配的参考文件，请使用常识并进行网页搜索。优先搜索 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()）。
  • 如果框架需要，请设置 PostHog 提供程序/包装器组件。

步骤 5：识别用户。

  • 在客户端的登录和注册事件中添加 PostHog identify() 调用。
  • 如果同时存在前端和后端，请通过 X-POSTHOG-DISTINCT-ID 和 X-POSTHOG-SESSION-ID 标头，将客户端会话和 distinct ID 传递给服务端代码。

步骤 6：设置环境变量。

  • 将 PostHog API 密钥和主机存储在环境变量中（例如 .env 或框架专用的环境文件）。
  • 在代码中引用这些环境变量，不要硬编码。

步骤 7：验证并清理。

  • 检查项目是否存在错误。查找 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-react-vite.md - react-vite 示例项目代码
  • 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-javascript-node.md - javascript-node 示例项目代码
  • references/EXAMPLE-javascript-web.md - javascript-web 示例项目代码
  • 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.md - React - 文档
  • 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/js.md - JavaScript web - 文档
  • references/posthog-js.md - PostHog JavaScript web SDK
  • references/node.md - Node.js - 文档
  • references/posthog-node.md - PostHog Node.js SDK
  • 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 代码。不要替换或重构现有代码。
  • 遵循示例：实现应尽可能遵循示例项目的模式。
  • 分析约定：将事件名称、属性名称和功能标志键视为分析约定的一部分。复用项目中已有的名称和模式。引入新名称时，应确保清晰、描述性强，并与现有约定保持一致。

评论

支持 Markdown