adding-analytics：讓 AI Agent 按標準流程給 Web 應用接入 PostHog

大模型Skills Agent Skill PostHog 產品分析 Cursor 埋點 2026-08-15 62 閱讀

前言

產品剛上線，最常見的下一步是加分析：頁面有沒有人看、註冊有沒有走完、付費卡在哪一步。這件事本身不復雜，但落到具體倉庫裏很容易散掉——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
羽毛球分组比赛记分
小程序二维码

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

小夜