adding-analytics：让 AI Agent 按标准流程给 Web 应用接入 PostHog

大模型Skills Agent Skill PostHog 产品分析 Cursor 埋点 2026-08-15 61 阅读

前言

产品刚上线，最常见的下一步是加分析：页面有没有人看、注册有没有走完、付费卡在哪一步。这件事本身不复杂，但落到具体仓库里很容易散掉——Next.js App Router 和 Pages Router 初始化位置不一样，SPA 切路由常常记不上 $pageview，项目密钥被写进源码，Feature Flag 和会话回放又各写一套。

让 AI 编程助手「帮我加个 PostHog」时，如果没有一份固定流程，它可能漏装服务端 SDK、用错环境变量前缀，或者在单页应用里依赖默认的整页刷新统计。adding-analytics 就是把这套「加埋点」步骤写成 Agent Skill，让助手按同一份清单做完识别框架、安装 SDK、初始化、页面浏览、自定义事件，以及按需打开 Feature Flag 和会话回放。

这是什么

adding-analytics 是一份通用格式的 SKILL.md，frontmatter 里的名称是 adding-analytics，描述是：为 Web 应用接入 PostHog 分析，覆盖事件追踪、页面浏览、Feature Flag 和会话回放。触发条件写得很直白：用户提到加 analytics、event tracking、page views、feature flags 或 session replay 时使用。

它收录在 spencerpauly/awesome-cursor-skills 的 resources/adding-analytics/ 目录，该仓库是一份 Cursor Skill 精选列表，许可证为 Creative Commons Zero（CC0）。原文只有一个 SKILL.md，没有额外的 scripts/ 或 references/。同仓库的 Analytics & Tracking 分组里，posthog-llm-analytics 和 posthog-migrations 指向 PostHog 官方技能仓库；adding-analytics 本身是这份精选列表里的独立短流程，不是 PostHog/skills 里的官方插件。

它解决的问题很具体：不要让 Agent 每次临时拼一套埋点方案，而是先认框架、再装对应 SDK、把密钥放到环境变量、在 SPA 里补页面浏览，然后才按用户要求加自定义事件和可选能力。

核心流程

Skill 正文按 8 步写，顺序固定。

1、识别框架。先看 next.config.*、vite.config.*、package.json 的 scripts，或 index.html，判断是 Next.js、React（Vite / CRA）、Vue、Svelte 还是纯 HTML。后面的初始化代码以 Next.js 写得最细，其他框架主要用到「认栈 + 装包」这一层。

2、安装 SDK。按运行位置选包，命令在 Skill 里写死了：

# Next.js / React 客户端
npm install posthog-js

# Next.js 还要在服务端打点时
npm install posthog-js posthog-node

# Python
pip install posthog

# Node.js 后端
npm install posthog-node

这几条与 PostHog 官方文档一致：Web 端用 posthog-js，Next.js 服务端用 posthog-node，Python 官方库也是 pip install posthog。

3、建 Provider / 初始化模块。Next.js App Router 要求在 app/providers.tsx 里用 "use client" 初始化，因为 posthog-js 只能在浏览器里跑。Pages Router 则写在 _app.tsx 的 useEffect 中。根布局里要用 Provider 包住 {children}。

4、补页面浏览。SPA 不会每次都整页刷新。Skill 的做法是关掉自动 pageview，在路由变化时手动 posthog.capture('$pageview')，路由事件用各框架自己的 router。

5、写环境变量。向用户要 PostHog 项目 API key 和 host，写入 .env，并同步到 .env.example。密钥禁止写进源码。

6、自定义事件。用户点名要追踪的行为（例如 sign-up、purchase），在对应 handler 里调用 posthog.capture("event_name", { ...properties })。

7、Feature Flag（可选）。用户明确要求时，再用 posthog.isFeatureEnabled("flag-name") 或 React 的 useFeatureFlagEnabled hook。

8、会话回放（可选）。用户明确要求时，在 init 配置里加上 session_recording。

另外还有三条约束：密钥只用环境变量；项目若有 Content Security Policy，要把 posthog-js 相关域名加进去；monorepo 把包装在真正渲染 UI 的那个 package 里，不要装到仓库根上却不引用。

安装与启用

这份 Skill 是标准的 Agent Skills 目录：文件夹名与 YAML 里的 name 一致，里面放 SKILL.md。复制到对应工具能扫描到的位置即可。awesome-cursor-skills 的说明是拷进 .cursor/skills/。

从仓库拷一份到当前项目（Cursor 项目级）：

git clone https://github.com/spencerpauly/awesome-cursor-skills.git
mkdir -p .cursor/skills/adding-analytics
cp awesome-cursor-skills/resources/adding-analytics/SKILL.md \
  .cursor/skills/adding-analytics/SKILL.md

各工具的扫描目录如下（以官方文档为准）：

  • Cursor：项目级 .cursor/skills/ 或 .agents/skills/，用户级 ~/.cursor/skills/ 或 ~/.agents/skills/。为了兼容，也会加载 .claude/skills/、.codex/skills/ 以及对应的用户目录。Agent 可根据 description 自动选用，也可以在对话里用 / 搜索技能名手动调用。
  • Claude Code：项目级 .claude/skills/adding-analytics/SKILL.md，用户级 ~/.claude/skills/adding-analytics/SKILL.md。
  • Codex CLI：从当前工作目录向上到仓库根扫描 .agents/skills，用户级是 $HOME/.agents/skills。

目录名必须是 adding-analytics，与 frontmatter 的 name 一致，否则有的工具不会按技能名找到它。

如果要用 PostHog 官方维护、覆盖更多框架的集成技能，那是另一条线：把 PostHog/skills 加进 Claude Code 的 plugin marketplace，再安装 posthog-integration。它和 adding-analytics 目标相近，但不是同一份文件，流程和示例以各自仓库为准。

典型用法

启用之后，直接用自然语言触发即可，不必先背命令。例如：

给这个 Next.js App Router 项目接入 PostHog：
记录页面浏览，以及注册成功、完成购买这两个自定义事件。
密钥用环境变量，不要写进代码。

需要 Flag 或回放时把需求写清楚，Skill 才会走第 7、8 步：

同样接入 PostHog，并加上 feature flag「new-checkout」，
以及会话回放。

下面这些代码来自 Skill 原文，也是 Agent 应当落地的形状。

Next.js App Router 的 app/providers.tsx：

"use client";
import posthog from "posthog-js";
import { PostHogProvider as PHProvider } from "posthog-js/react";
import { useEffect } from "react";

export function PostHogProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
      api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST ?? "https://us.i.posthog.com",
      capture_pageview: false, // we capture manually for SPAs
    });
  }, []);
  return <PHProvider client={posthog}>{children}</PHProvider>;
}

环境变量（Skill 使用的变量名）：

NEXT_PUBLIC_POSTHOG_KEY=phc_...
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

NEXT_PUBLIC_ 前缀是为了让 Next.js 把值暴露给浏览器。host 以 PostHog 项目设置里的地址为准，上面的 https://us.i.posthog.com 只是 Skill 和官方文档里的美国云示例，不能当成所有项目的固定值。

自定义事件、页面浏览、Feature Flag 的调用方式：

posthog.capture("$pageview");
posthog.capture("sign_up", { plan: "pro" });
posthog.capture("purchase", { amount: 99 });

if (posthog.isFeatureEnabled("flag-name")) {
  // 打开新功能
}

会话回放在 Skill 里是往 init 里加：

posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
  api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST ?? "https://us.i.posthog.com",
  capture_pageview: false,
  session_recording: { maskAllInputs: false },
});

适用场景与注意事项

适合已经有 Web 前端（尤其是 Next.js / React），准备接 PostHog，又不想每次让 Agent 从零搜文档的团队。Skill 把「识别框架 → 装包 → Provider → 环境变量 → 事件」写成清单，对第一次埋点、把分析从「只有自动采集」补成「关键业务事件可查」比较直接。

使用时有几处要对着官方文档看，不要把 Skill 里的示例当成 PostHog 当前唯一正确写法。

1、环境变量名。Skill 用 NEXT_PUBLIC_POSTHOG_KEY。PostHog 现行 Next.js 文档用的是 NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN。两边都要求 NEXT_PUBLIC_ 前缀；接现有项目时先看仓库里已经在用哪一个，不要并存两套。

2、React 包路径。Skill 从 posthog-js/react 引入 PostHogProvider。官方 Next.js / React 文档现在写的是 @posthog/react。若当前 posthog-js 版本已经拆出独立 React 包，应按你安装的包和官方文档调整 import，而不是机械粘贴。

3、页面浏览。Skill 把 capture_pageview 设为 false，再在路由变化时手动打 $pageview，这是针对 SPA 的老做法。PostHog 现行文档更推荐在 init 里设置 defaults（例如 '2026-05-30'），此时 capture_pageview 的默认值是 'history_change'，会监听 History API，单页跳转也能记 pageview。两种都能工作；新项目可以优先跟官方 defaults，旧项目若已经手动采集，不要两套同时开，否则会重复计算。

4、会话回放与输入框脱敏。PostHog 文档写明：会话录制在 SDK 里默认是开的（disable_session_recording 默认为 false），输入框内容默认脱敏（maskAllInputs 默认为 true）。Skill 示例写的是 maskAllInputs: false，等于主动关掉输入脱敏。官方隐私文档把输入框视为高敏感区域，密码框无论如何都会遮罩，但仍建议至少保持密码类输入脱敏。生产环境不要原样抄 maskAllInputs: false，除非已经单独评估过合规要求。

5、CSP。Skill 只提醒「有 CSP 就要把 posthog-js 加进去」。PostHog 官方更具体：SDK 还会从 CDN 懒加载会话回放等脚本，并向采集域名发请求。文档给出的通配示例如下（域名以官方文档为准，且可能变化）：

script-src 'self' https://*.posthog.com;
connect-src 'self' https://*.posthog.com;
worker-src 'self' blob: data:;

缺 connect-src 时，看起来代码接好了，事件却发不出去。

6、覆盖范围。Skill 提到 Vue、Svelte、纯 HTML 和 Python / Node 后端装包，但可运行的 Provider 示例只给了 Next.js。其他框架需要 Agent 结合 PostHog 对应文档补初始化，不能指望这一份 SKILL.md 写全。Next.js 15.3+ 官方还提供 instrumentation-client.ts 作为另一种客户端初始化方式，Skill 未覆盖。

7、它不会替你设计事件模型。事件名、属性、是否 identify 用户，仍要产品自己定。PostHog 文档要求登录后用稳定的用户 ID 调用 identify，登出调用 reset；这些不在 adding-analytics 的步骤里。

小结

adding-analytics 不提供新的分析产品，而是把「给 Web 应用接 PostHog」收成一份可复用的 Agent 流程：认框架、装 SDK、初始化、补 SPA 页面浏览、用环境变量管密钥，再按需加自定义事件、Feature Flag 和会话回放。文件短、步骤清楚，适合作为 Cursor / Claude Code / Codex CLI 的项目级技能。

落地时以 Skill 原文为准，配置项以 PostHog 当前文档为准，两者不一致的地方（变量名、React 包名、pageview 默认行为、输入脱敏）按项目现状二选一，不要混用。

Skill 原文：https://github.com/spencerpauly/awesome-cursor-skills/blob/main/resources/adding-analytics/SKILL.md

PostHog 官方 Next.js 集成：https://posthog.com/docs/libraries/next-js

PostHog 官方 Skills 仓库：https://github.com/PostHog/skills

相关文章

Cursor 3 多 Agent 架构：Planner/Worker 分工最高降本 15 倍 2026-07-29 Cursor 多 Agent 蜂群用 1339 美元重建 SQLite：Planner/Worker 分层才是 Agent 经济学 2026-07-30 600 亿美元收购 Cursor：SpaceX/xAI 要重塑 AI 编程工具格局？ 2026-07-31 Cursor 3 多 Agent 架构：Planner/Worker 分层如何将编码成本降低 15 倍 2026-08-01 GitHub 爆火 Ponytail：让 AI Agent 像「最懒的高级工程师」一样写代码 2026-08-02
羽毛球分组比赛记分
小程序二维码

欢迎使用《羽毛球分组比赛记分》微信小程序

小夜