基于 PostHog 的产品分析与增长工程集成指南：为 AI Agent 提供事件捕获、会话回放与特征标志的完整操作手册

• AI 技能
• 人工智能

本文聚焦 marketingskills 仓库中 PostHog 集成指南 的核心内容，系统讲解这款开源产品分析工具如何通过 Capture API、Query API、Feature Flags API 与 JavaScript SDK，为营销与增长团队（尤其是 Claude Code 与 AI Agent 场景）提供事件追踪、会话回放、特征标志与 A/B 测试能力。读完本文，你将掌握 PostHog 的认证方式、七类常用 Agent 操作（事件上报、批量上报、用户查询、HogQL 查询、特征标志、洞察与录制）、JavaScript SDK 埋点模式，并了解如何结合仓库中的 analytics、ab-testing、attribution 等技能在真实增长工程中落地 PostHog。

一、PostHog 是什么：开源产品分析全家桶

PostHog 是一套开源的产品分析平台，核心定位是"Open-source product analytics with session replay and feature flags"，即同时具备传统产品分析（事件追踪）、会话回放（观看真实用户操作录屏）和特征标志（灰度发布）三大能力。与 GA4、Mixpanel 等同类工具相比，PostHog 最大的差异化在于开源可自托管——你可以把它运行在自己的基础设施上，从而满足隐私合规与数据主权要求。

在 marketingskills 仓库的工具注册表中，PostHog 被归类为Analytics（产品分析）类别，与 GA4、Mixpanel、Amplitude、Segment、Adobe Analytics、Plausible 并列，并在 Analytics 分类表中明确标注其定位为"Open-source analytics, session replay"。注册表给出的选型建议是：Google 生态用户从 GA4 入手，深度产品分析选 Mixpanel/Amplitude，隐私优先站点选 Plausible，而 PostHog 的核心适用场景则是开源要求、自托管需求与特征标志管理。

能力矩阵一览

原集成指南（tools/integrations/posthog.md）给出了完整的接入能力矩阵：

从这张表可以得到三个对 Agent 工程实践至关重要的结论：

1. 无 MCP 服务器：PostHog 目前不提供官方 MCP（Model Context Protocol）服务器，因此 AI Agent 无法像 GA4、Stripe 那样通过 MCP 工具直接交互，必须走 HTTP API 或 SDK 路径。这与 工具注册表 中"MCP-Enabled Tools"清单（GA4、Stripe、Mailchimp 等）相互印证——PostHog 不在其中。
2. CLI 仅限本地开发：posthogCLI 面向开发环境（如本地自托管实例），生产环境的数据读写主力是 REST API 与各语言 SDK。
3. 多语言 SDK：JavaScript 之外还有 Python、Ruby、Go 等，这意味着无论你的技术栈是前端站点、后端服务还是数据管道，都能找到对应接入方式。

二、认证机制：两种 API Key 的正确用法

PostHog 的认证是整个集成的基础，原文档给出的要点可以归纳为三条规则：

• 认证类型：API Key（分为 Personal Key 与 Project Key 两类）
• 请求头：Authorization: Bearer {api_key}——这是所有管理类 API（Query、Persons、Insights、Session Recordings）的标准认证方式
• 数据上报：Capture 与 Batch 端点不走 Bearer 头，而是把Project API Key 直接放在请求体 payload 中

两种 Key 的职责边界值得展开说明：

实战要点：事件上报端点（/capture/、/batch/、/decide/）天然是"公开"设计——Project API Key 会出现在前端代码中，这是产品分析工具的通用模式（Mixpanel 同样用公开的 project token 做上报）。而涉及读取数据的 Query API、Persons API 等则必须用带 Bearer 认证的服务端 Key，严禁把 Personal Key 暴露在前端。

仓库中 analytics 技能 的"隐私与合规"章节进一步强调了这种密钥分治的意义：分析属性中不得包含 PII（个人身份信息），Key 的分级管理本身就是防止数据泄露的第一道防线。

三、Agent 常用操作详解：七类核心 API 调用

原集成指南为 AI Agent 提供了七类"开箱即用"的 API 操作模板。以下逐一展开，并补充参数说明与适用场景。

3.1 上报单个事件（Capture API）

POST https://app.posthog.com/capture/ { "api_key": "{project_api_key}", "event": "signup_completed", "distinct_id": "user_123", "properties": { "plan": "pro", "$current_url": "https://example.com/signup" } }

参数解析：

• api_key：Project API Key（公开 Key），必填
• event：事件名。仓库 analytics 技能 强烈建议采用Object-Action（对象-动作）命名规范，如signup_completed、button_clicked、form_submitted、checkout_payment_completed——全小写下划线，具体到对象（cta_hero_clicked优于button_clicked），上下文放进 properties 而非事件名
• distinct_id：用户唯一标识。匿名访客时为匿名 ID，identify()之后为邮箱/UUID
• properties：事件属性，$前缀为 PostHog 保留属性（如$current_url、$browser、$os），自定义属性直接使用业务字段名

3.2 批量上报事件（Batch API）

POST https://app.posthog.com/batch/ { "api_key": "{project_api_key}", "batch": [ {"event": "pageview", "distinct_id": "user_1"}, {"event": "signup", "distinct_id": "user_2"} ] }

batch字段接收事件数组，一次请求可携带多条事件。批量上报有两个关键优势：降低网络请求次数（规避 Cloud 版 10,000 events/second 的瞬时峰值限制）、服务端合并上报（如 webhook 回调、离线补数场景）。

仓库 first-party-tracking 归因指南 中有一个非常典型的生产级用法——在第三方域名（如 SavvyCal 预订工具）的 webhook 中，通过/batch/一次性完成身份合并（$identify）与转化事件上报：

const events = []; if (anonId) { events.push({ event: "$identify", distinct_id: userId, properties: { $anon_distinct_id: anonId, $set: { email: userId, name } }, }); } events.push({ event: "discovery_call_booked", distinct_id: userId, properties: { booking_id, journey_linked: Boolean(anonId) }, }); await fetch(`${POSTHOG_HOST}/batch/`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ api_key: POSTHOG_API_KEY, batch: events }), signal: AbortSignal.timeout(3000), });

这段代码同时示范了三个 Agent 工程要点：① 业务事件（discovery_call_booked）与系统事件（$identify）可以混在同一批次；② webhook 中必须用AbortSignal.timeout限时并保证失败不影响主流程；③ 用journey_linked属性记录归因链路是否打通，便于事后监控覆盖率。

3.3 按 distinct_id 查询用户（Persons API）

GET https://app.posthog.com/api/projects/{project_id}/persons/?distinct_id=user_123 Authorization: Bearer {api_key}

注意此端点有两个路径参数差异：{project_id}是 PostHog 项目的数字 ID（可在项目设置中获取），而认证使用 Bearer 头（Personal Key）。用途包括：确认identify()是否生效、检查用户画像的$initial_*首触属性是否落地、排查匿名用户与已知用户是否成功合并。

3.4 HogQL 查询事件（Query API）

POST https://app.posthog.com/api/projects/{project_id}/query/ { "query": { "kind": "HogQLQuery", "query": "SELECT event, count() FROM events WHERE timestamp > now() - interval 7 day GROUP BY event ORDER BY count() DESC LIMIT 10" } }

HogQL是 PostHog 基于 ClickHouse SQL 封装的查询语言，是理解其"SQL-like query language"定位的关键。这个示例查询了近 7 天的事件频率 Top 10，可用于：

• 快速审计埋点是否生效（pageview、signup_completed是否都在上报）
• 发现未预期的高频事件（排查重复埋点）
• 作为 Agent 自动化报告的数据源

配合 analytics 技能 中的"验证清单"（事件是否在正确触发点上报、属性值是否正确填充、是否存在重复事件），HogQL 就是执行这些校验的底层查询工具。

3.5 查询特征标志（Feature Flags API）

POST https://app.posthog.com/decide?v=3 { "api_key": "{project_api_key}", "distinct_id": "user_123" }

/decide/端点是 SDK 内部获取特征标志决策的底层接口（v=3为当前 API 版本号）。传distinct_id后返回该用户命中的所有特征标志及变量值。在 Agent 场景中，可用它实现服务端灰度判断——例如决定向某批用户展示新定价页还是旧页面。

特征标志是 PostHog 连接"分析"与"实验"的桥梁：ab-testing 技能 明确把 PostHog 列为实验工具之一（与 Optimizely、VWO 并列），而 churn-prevention 技能 更进一步给出了具体实践：用特征标志在服务端把用户切分到不同的取消流程，再用漏斗分析追踪取消流程的每一步（survey → offer → accept/decline → confirm），从而用实验数据驱动流失挽留策略。

3.6 获取洞察（Insights API）

GET https://app.posthog.com/api/projects/{project_id}/insights/ Authorization: Bearer {api_key}

Insights 是 PostHog 中已保存的图表/看板（趋势、漏斗、留存等）。通过 API 拉取它们，Agent 可以将现成的分析看板数据接入自动化报告流程，而无需重新编写 HogQL 查询。

3.7 获取会话录制（Session Recordings API）

GET https://app.posthog.com/api/projects/{project_id}/session_recordings/ Authorization: Bearer {api_key}

会话录制是 PostHog 的差异化能力：回放真实用户会话，用于 UX 洞察。在营销场景中的典型用法包括：观察用户在实际落地页上的滚动/点击行为、识别表单填写卡点、为 cro 转化率优化 提供定性证据。Agent 可通过该 API 拉取录制元数据清单，与事件数据交叉分析。

四、JavaScript SDK 埋点：四步完成前端接入

原文档给出了完整的前端 SDK 四步范式，这是 Web 场景的标配接入路径：

// 1. Initialize（初始化） posthog.init('PROJECT_API_KEY', { api_host: 'https://app.posthog.com' }); // 2. Identify user（识别用户） posthog.identify('user_123', { email: 'user@example.com', plan: 'pro' }); // 3. Track event（上报事件） posthog.capture('signup_completed', { method: 'email' }); // 4. Check feature flag（判断特征标志） if (posthog.isFeatureEnabled('new-pricing')) { // Show new pricing }

对这四个调用的工程解读：

• init：传入 Project API Key 与api_host（自托管实例需把api_host指向你自己的部署域名）。仓库 first-party-tracking 归因指南 提醒：SDK 加载前调用会被队列暂存（stub 机制），这也是为什么读取get_distinct_id()需要做加载完成判断。
• identify：在"知道用户是谁"的时刻调用（注册成功、表单提交、首次付费）。仓库归因指南特别强调身份归一化——分析工具按精确字符串匹配身份，"Corey@x.com"与"corey@x.com"会被拆成两个人，因此上报前必须email.trim().toLowerCase()。配合person_profiles: 'identified_only'配置，identify()的这一刻才会创建用户画像并打上首触属性。
• capture：与 Capture API 等价的前端封装。事件名遵循 analytics 技能 的 Object-Action 规范。
• isFeatureEnabled：对应/decide/端点的 SDK 封装，用于前端灰度判断。

进阶：匿名 ID 的安全读取

在"把匿名用户引导到第三方转化域名并回传归因"的场景中（详见 first-party-tracking 归因指南），Agent 需要在前端安全读取当前匿名 ID。由于 SDK stub 在加载完成前get_distinct_id()返回undefined，归因指南给出了一种先 SDK 后 Cookie 的回退读取实现，并附带严格的匿名性守卫：

export function getPostHogDistinctId() { if (typeof window === "undefined") return null; try { if (window.posthog?.__loaded) { const id = window.posthog.get_distinct_id(); if (id) return isAnonymousDistinctId(id) ? id : null; } } catch {} try { const prefix = `ph_${POSTHOG_API_KEY}_posthog=`; const cookie = document.cookie.split(/;\s*/).find(c => c.startsWith(prefix)); if (!cookie) return null; const parsed = JSON.parse(decodeURIComponent(cookie.slice(prefix.length))); return typeof parsed.distinct_id === "string" && isAnonymousDistinctId(parsed.distinct_id) ? parsed.distinct_id : null; } catch { return null; } }

其中匿名性守卫isAnonymousDistinctId的规则（邮箱身份应用场景）：id.length > 0 && id.length <= 100 && !id.includes("@")——即只允许透传"看起来不像邮箱"的匿名 ID，一旦identify()之后当前distinct_id变成邮箱形状，立即拒绝透传，防止 PII 泄露与错误合并。归因指南给出的铁律是：当身份不明确时，什么都不发送——缺失的归因只是数据缺口，错误的合并则是数据污染。

五、关键能力全景与选型建议

原文档将 PostHog 的六大核心能力总结如下：

• Event tracking（事件追踪）：产品分析的基础能力，覆盖 Web 与移动端
• Session replay（会话回放）：观看真实用户会话，获取 UX 洞察
• Feature flags（特征标志）：控制功能灰度发布与实验分流
• A/B testing（内置实验）：开箱即用的 A/B 测试能力（配合 ab-testing 技能 使用）
• HogQL：SQL 风格的查询语言，底层基于 ClickHouse
• Self-hostable（可自托管）：可在自有基础设施上运行，满足数据主权要求

何时选择 PostHog

原文档给出了五类明确的使用场景：

1. 产品分析 + 隐私优先：需要在分析能力与数据隐私之间取得平衡
2. 会话回放做 UX 洞察：需要看真实用户操作而非仅看数字
3. 特征标志管理：需要服务端灰度与功能开关能力
4. 自托管分析需求：数据必须留在自己的基础设施内
5. 开源要求：代码库与生态完全开源

从仓库 工具注册表 的 Agent 选型建议看，各分析工具的定位是互补的：GA4 适合 Google 生态，Mixpanel/Amplitude 适合深度产品分析，Plausible 适合隐私极简场景，而 PostHog 的独特价值在于开源 + 自托管 + 特征标志 + 会话回放的组合——这是其他商业 SaaS 分析工具难以同时提供的。在 analytics 技能 的工具集成表中，PostHog 与 GA4、Mixpanel、Amplitude、Segment 并列展示，Agent 应根据上述场景而非品牌偏好选择。

六、速率限制：Cloud 与自托管的差异

原文档给出的速率限制信息非常明确：

• Cloud（云托管版）：10,000 events/second（每秒 1 万事件）
• Self-hosted（自托管版）：无限制（取决于你自己的基础设施容量）

对 Agent 工程的意义：批量上报（/batch/）是规避 Cloud 瞬时峰值的最直接手段——把突发的事件流（如 campaign 高峰、webhook 风暴）聚合为批量请求，比逐条上报更稳健。自托管场景下"无限制"仅指软件层面无硬性配额，实际吞吐受 ClickHouse 集群性能约束，扩容规划仍需按事件量设计。

七、PostHog 在仓库增长工程中的完整落地路径

PostHog 在 marketingskills 仓库中不是孤立文档，而是贯穿多条技能链路的底层数据与实验基础设施。综合仓库源码，可以梳理出四条典型的落地路径：

路径一：营销分析（analytics 技能）在 analytics 技能 中，PostHog 是五大推荐分析工具之一。Agent 可参照该技能的 Tracking Plan 框架（Event Name | Category | Properties | Trigger | Notes表格）与 事件库参考 设计埋点计划——例如营销站点事件（cta_clicked、form_submitted、signup_completed）、产品事件（onboarding_step_completed、feature_used、purchase_completed）、电商事件（product_added_to_cart、checkout_started）——再用本文第三节的 Capture/Batch API 落地到 PostHog。

路径二：实验驱动（ab-testing 技能）ab-testing 技能 将 PostHog 列为实验工具（与 Optimizely、VWO 并列），其假设框架"Because [observation], we believe [change] will cause [outcome] for [audience]..."配合 PostHog 的特征标志分流与漏斗分析，构成完整的"提出假设 → 分流实验 → 漏斗度量"闭环。

路径三：自助归因（attribution 技能）first-party-tracking 归因指南 以PostHog + SavvyCal 作为完整工作示例，展示了如何用 PostHog 的identify()、$anon_distinct_id合并、/batch/上报、$initial_*首触属性，把"匿名浏览 → 第三方域名转化"拼接成一条可归因的完整旅程。核心模式可以概括为：拿到匿名 ID → 跨越域名边界携带它 → 在对岸合并身份 → 按首触渠道拆分转化。

路径四：流失挽留（churn-prevention 技能）churn-prevention 技能 给出了一个具体的工程配方：用 PostHog 特征标志在服务端把用户分流到不同取消流程，再用漏斗分析追踪取消流程每步转化（survey → offer → accept/decline → confirm），从而用实验数据优化挽留策略。

八、验证与上线自检清单

综合原文档 API 模板与仓库各技能的工程经验，PostHog 集成上线前建议完成以下验证：

1. 事件链路验证：用 HogQL 查询（SELECT event, count() ...）确认各事件按预期频率上报，且无重复/畸形事件
2. 身份合并验证：用 Persons API（?distinct_id=...）确认匿名浏览历史与已知用户画像成功合并，$initial_utm_source首触属性已落地
3. 特征标志验证：/decide/返回预期标志与变量值，isFeatureEnabled在前端按分流生效
4. 批量上报验证：向/batch/手动 POST 测试 payload，返回{"status":"Ok"}且用户画像正确合并（参考归因指南的验证清单）
5. 隐私合规检查：属性中无 PII（遵循 analytics 技能 的隐私原则），Personal Key 仅存在于服务端

至此，你已经掌握了从 API 认证、七类常用操作、SDK 埋点到真实增长工程落地路径的完整 PostHog 集成知识——这套能力可以直接作为 AI Agent 接入 PostHog 的自动化操作手册使用。

• AI 技能
• 人工智能