omnibus-instrument-error-tracking

添加 PostHog 错误追踪

使用此技能添加 PostHog 错误追踪，以捕获和监控应用程序中的异常。实现功能或审查 PR 后使用此技能，确保错误能够连同完整的堆栈跟踪和源映射一起被追踪。如果尚未安装 PostHog，此技能也涵盖 SDK 的初始设置。支持任何平台或语言。

支持的平台：React、Next.js、Web（JavaScript）、Node.js、Python、Ruby、Ruby on Rails、Go、Angular、Svelte、Nuxt、React Native、Flutter、Android 和 Hono。

说明

请按顺序执行以下步骤：

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

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

STEP 2：研究埋点。（如果已配置 PostHog，则跳过。） 2.1. 在下方找到与检测到的平台相匹配的参考文件——它是 SDK 初始化、异常自动捕获和特定框架错误追踪模式的权威依据。现在阅读该文件。 2.2. 如果没有匹配的参考文件，请使用已有知识并进行网络搜索。优先搜索 posthog.com/docs。

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

• 为检测到的平台添加 PostHog SDK 包。不要手动编辑 package.json——请使用包管理器的安装命令。
• 始终将包安装作为后台任务。不要等待安装完成；启动安装后立即继续其他工作。
• 按照框架参考文档确定初始化的位置和方式。

STEP 4：启用异常自动捕获。

• 按照平台参考文档启用异常自动捕获。这样无需额外代码即可自动捕获未处理的异常。

STEP 5：添加手动错误捕获。

• 找出错误边界、catch 代码块以及需要显式捕获错误的关键用户流程。
• 在这些位置添加 posthog.captureException() 或平台对应的方法。
• 不要改变现有错误处理的基本架构。只进行最少且有针对性的补充。
• 尝试写入文件前，必须立即先读取该文件。

STEP 6：上传源映射（仅限前端／移动端）。

• 配置源映射上传，使堆栈跟踪能够还原到原始源代码，而不是压缩后的代码包。
• 按照平台专属参考文档配置上传（构建插件、CI 脚本等）。

STEP 7：设置环境变量。

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

STEP 8：验证并清理。

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

参考文件

• references/react.md - React 错误跟踪安装文档
• references/web.md - Web 错误跟踪安装文档
• references/nextjs.md - Next.js 错误跟踪安装文档
• references/node.md - Node.js 错误跟踪安装文档
• references/python.md - Python 错误跟踪安装文档
• references/ruby.md - Ruby 错误跟踪安装文档
• references/ruby-on-rails.md - Ruby on rails 错误跟踪安装文档
• references/go.md - Go 错误跟踪安装文档
• references/angular.md - Angular 错误跟踪安装文档
• references/svelte.md - Sveltekit 错误跟踪安装文档
• references/nuxt.md - Nuxt 错误跟踪安装文档（v3.7 及以上）
• references/react-native.md - React native 错误跟踪安装文档
• references/flutter.md - Flutter 错误跟踪安装文档
• references/android.md - Android 错误跟踪安装文档
• references/hono.md - Hono 错误跟踪安装文档
• references/fingerprints.md - 指纹文档
• references/alerts.md - 发送错误跟踪告警
• references/monitoring.md - 监控和搜索问题
• references/assigning-issues.md - 将问题分配给团队成员
• references/upload-source-maps.md - 上传源映射

每个平台的参考文件都包含特定于其 SDK 的安装说明和手动捕获模式。请找到与用户技术栈匹配的文件。

核心原则

• 环境变量：始终使用环境变量存储 PostHog 密钥。切勿将其硬编码。
• 最小改动：在现有错误处理中添加错误跟踪。不要替换或重构现有代码。
• 优先自动捕获：先启用异常自动捕获，再添加手动捕获。
• 源映射：上传源映射，以便堆栈跟踪解析到原始源代码，而不是压缩后的代码包。
• 在边界处手动捕获：对于不会传播到全局处理程序的错误，在错误边界和 catch 块中使用 captureException()。