用途
该技能面向 Web 应用，帮助添加或审计产品分析、监控与可用性检查。核心目标是为项目接入三类可观测性能力：PostHog 事件追踪、Sentry 错误追踪、以及用于正常运行时间监控的健康检查端点。
主要能力与工作流程
第 1 阶段：检测技术栈
读取项目并判断需要安装什么。
- 框架检测：
next.config.*→ Next.js（检查 App Router 还是 Pages Router）；vite.config.*→ Vite / React SPA；astro.config.*→ Astro；nuxt.config.*→ Nuxt；Python 后端（main.py、app.py、manage.py）→ FastAPI / Django / Flask。 - 现有分析检测：
posthog-js或posthog-node→ 已存在 PostHog；@sentry/nextjs、@sentry/react或sentry-sdk→ 已存在 Sentry；@vercel/analytics→ 已存在 Vercel Analytics；@google-analytics或gtag→ 已存在 GA。若已安装，则改为审计现有配置，检查是否存在缺口（缺少 error boundary、无服务端追踪、无健康端点）。 - 向用户确认：检测到的框架、已有分析工具、将要配置的三项内容（PostHog 事件追踪与用户识别与功能开关、Sentry 带源码映射的错误追踪、
/api/status健康端点），并索取 PostHog API key（app.posthog.com → Project Settings）与 Sentry DSN（sentry.io → Project Settings → Client Keys），或先完成代码后补 key。
第 2 阶段：实现可观测性
只加载本项目所需的实现参考：
- PostHog 分析：添加客户端或服务端追踪、页面浏览、用户识别或类型化事件前，先阅读
references/posthog.md。 - Sentry 错误追踪：配置 Sentry、error boundary 或结构化日志前，先阅读
references/sentry.md。 - 健康端点：添加 Next.js 或 FastAPI 状态路由及正常运行时间监控前，先阅读
references/health-endpoint.md。
保留已有集成。若系统已存在，使用对应参考审计缺口，而不是重新安装。所有示例需匹配检测到的框架与认证模型。
第 3 阶段：环境变量
添加到 .env.local（或 .env）：
# PostHog
NEXT_PUBLIC_POSTHOG_KEY=phc_...
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
POSTHOG_API_KEY=phc_... # Same key, used server-side
# Sentry
NEXT_PUBLIC_SENTRY_DSN=https://xxx@o123.ingest.sentry.io/456
SENTRY_AUTH_TOKEN=sntrys_... # For source map uploads
SENTRY_ORG=your-org
SENTRY_PROJECT=your-project
确认这些变量未被提交到 git，检查 .gitignore 是否包含 .env*。
第 4 阶段：验证
接线完成后逐项测试：
- PostHog：打开应用 → 检查 PostHog 面板是否出现 pageview 事件；页面间导航 → 每个页面触发 pageview；登录 → 用户以邮箱/姓名出现在 PostHog（已识别）；追踪自定义事件 → 出现在 PostHog 事件中；登出 → 调用
posthog.reset()，产生新的匿名会话。 - Sentry：在页面临时添加
throw new Error('sentry test')→ 加载页面，错误出现在 Sentry 面板；检查源码映射是否解析（看到真实代码而非压缩代码）；移除测试错误；error boundary 渲染回退 UI（而非白屏）。 - 健康端点：
GET /api/status返回 200 及 uptime 与数据库状态；若数据库宕机返回 503；设置监控服务每 5 分钟 ping 一次。
最后告知用户哪些系统已上线并正常工作。
适用场景
需要为 Web 应用添加或审计产品分析、错误监控、可用性/uptime 检查时使用。支持 Next.js、Vite / React SPA、Astro、Nuxt，以及 FastAPI / Django / Flask 等 Python 后端。
限制与注意事项
- PostHog 免费层：每月最多 1M 事件。在依赖其额度前，请确认当前套餐限制。
- Sentry 免费层：每月最多 5K 错误。在依赖其额度前，请确认当前套餐限制。
- 不要在 PostHog 事件中记录 PII（禁止密码、信用卡号）。用户 ID 和邮箱可以。
- 采样率很重要。生产环境 10% 追踪可将成本保持在接近零；仅在调试特定问题时提高。
- 源码映射对 Sentry 至关重要。没有它，错误堆栈显示压缩代码。Sentry 向导可为 Next.js 处理；其他框架需在构建时上传映射。