posthog-analytics（PostHog数据分析技能）Skill 是什么？

PostHog数据分析技能Skill：让 AI 用对话方式安全查询生产环境的用户行为数据

一句话定位：把「打开 PostHog 后台、点筛选器、导数据」的繁琐流程，变成「用自然语言提问 + AI 生成 HogQL 查询」的一步到位体验。
核心能力：内置事件字典、仪表板地图、功能标志清单与常用查询模板，覆盖入职漏斗、试用转化、错误率、LLM 调用成本等高频分析场景。
安全优先：强制通过环境变量加载只读密钥，禁止在命令与输出中回显 API Key，并在查询前执行验证清单。
开箱可用：技能自带生产/本地双项目区分、jq 输出格式化规范与故障排除指引，减少「查错项目、看错数据」的低级失误。
适用人群：产品经理、增长运营、客户成功、前端与后端工程师，以及需要核算 AI 调用成本的 LLM 应用团队。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能基本信息

项目	内容
中文名	PostHog数据分析技能Skill
英文名	posthog-analytics
技能ID	13659
核心定位	在调查用户行为、分析指标、检查功能标志状态或调试用户问题时，通过查询 PostHog 生产数据来完成分析

它解决什么问题

PostHog 本身是一个功能完整的产品分析平台，但日常使用中存在三类摩擦：

入口摩擦：想看一个转化漏斗，需要登录后台、找到对应项目、选仪表板、拖时间范围，一次分析动辄几分钟。
知识摩擦：团队里到底埋了哪些事件？onboarding_step_transition 和 onboarding_phase_completed 有什么区别？新人往往要翻文档或问同事。
安全摩擦：想让 AI 帮忙查数据，又担心把 API Key 写进命令历史、贴进聊天窗口，造成密钥泄露。

这个技能把上述三类问题一次性收敛：它把事件字典、仪表板地图、功能标志清单、HogQL 查询模板、安全凭证加载范式打包成一份可被 AI 直接调用的「操作手册」，让 AI 在你提问时能立刻产出正确的查询命令，而不是凭空编造字段名。

一键安装的思路与步骤

确认前提：你需要有一个可用的 AI 编程助手/智能体运行环境（支持技能或插件机制），以及一个 PostHog 账号与只读个人 API 密钥（前缀通常为 phx_）。具体支持的环境与安装入口，以官方说明为准。
安装技能：在技能市场中检索技能名 posthog-analytics 或技能ID 13659，执行安装/启用操作；也可按官方文档将技能目录放入本地技能路径。具体的命令、路径与配置方式，以官方说明为准。
配置凭证：在项目根目录的 .env 文件中写入只读密钥，例如 POSTHOG_READ_ONLY_KEY=phx_...。注意：仅使用只读密钥，不要使用具备写入权限的密钥。
验证是否生效：向助手提出一个典型的触发问题，例如「最近 7 天有哪些事件量最高？」。若技能生效，助手会先声明「我正在使用 posthog-analytics 技能来安全查询 PostHog 数据。」，随后给出带凭证加载步骤的查询命令。
二次验证：执行身份校验查询，确认返回你的邮箱与组织名，说明密钥与项目访问权限均正常。

2. 该技能的主要功能和特点

内置事件字典，避免字段瞎猜：技能按业务域整理了事件清单，包括入职与试用（onboarding_field_started、onboarding_completed、trial_started、trial_converted_to_paid、trial_churn_risk_detected 等）、草稿与联系人（drafts_created、contact_scoring_failed、linkedin_processing_failed 等）、活动（campaign_created）、账单订阅（user_cancel_subscription、subscription_state_updated）、系统错误（javascript_error_occurred、unhandled_promise_rejection、react_query_error、circuit_open、ai_fallback）以及 LLM 事件（$ai_generation）。
仪表板地图：列出生产环境常用仪表板及其 ID 与用途，例如「转化（简化版）」「功能采用漏斗」「入职健康」「试用与转化分析」「留存（简化版）」「AARRR – 海盗指标」等，并给出在浏览器中直接打开对应仪表板的命令范式，省去逐层点击。
功能标志实时核查：既能列出项目下全部功能标志及其激活状态（如 trial-duration、payment-integration、onboarding-flow、campaign-creation-tour），也能针对单个用户做本地评估，回答「这个用户为什么没看到新流程」这类问题。
HogQL 自定义查询能力：技能提供 HogQL 速查（events、persons、groups 三张表，properties.$ai_model 点号访问与 properties['$ai_model'] 括号访问两种写法），并内置多个可直接复用的查询模板。
LLM/AI 成本与性能分析：这是它区别于通用「查事件」工具的最大亮点。技能内置 $ai_trace_id、$ai_model、$ai_provider、$ai_input_tokens、$ai_output_tokens、$ai_total_tokens、$ai_latency、$ai_service 等属性的语义说明，并给出「按模型统计调用数与令牌」「按服务统计令牌消耗」「筛选延迟超过 5 秒的慢调用」三类现成查询。技能中还附带了一份活动模型快照示例（例如某 7 天内 gpt-4o-mini-2024-07-18 约 2.29 万次调用、gpt-5-nano 约 25 次调用等），用于说明数据的实际样貌。
安全凭证范式：技能强制使用 set -a && source .env && set +a 的方式加载环境变量，并明确列出两类反面示例——把 Key 直接写进 curl -H "Authorization: Bearer phx_..."、或 echo "$POSTHOG_READ_ONLY_KEY" 打印密钥。这种「正例 + 反例」的写法，让 AI 生成的命令天然规避了密钥泄露风险。
生产/本地项目隔离：明确约定生产项目 ID 与本地开发项目 ID 的用途差异，并要求所有生产查询默认使用生产项目，从流程上防止「拿测试数据当结论」。
输出可读性规范：统一用 jq 做 JSON 解析、用表格格式输出列表、用切片限制大结果集返回条数，避免 AI 一次吐出几百行原始 JSON。
完成前验证清单：凭证是否安全加载、项目 ID 是否正确、输出是否格式化、敏感用户数据是否妥善处理——四项自检收尾，把「随手一查」变成「有质量的分析」。

和普通工具比强在哪：普通 BI 工具需要人来选维度、拖指标；通用 AI 助手则容易编造不存在的字段。这个技能的价值在于把团队私有的数据契约（事件名、属性名、仪表板 ID、标志键）显式交给 AI，让生成的查询可直接执行。

3. 如何使用该技能？

第 1 步：安全加载凭证

set -a && source /path/to/your/project/.env && set +a

请把路径替换为你项目实际的 .env 文件位置。技能示例中给出的是一台机器上的具体路径，实际使用时需按自己的环境调整。

第 2 步：验证身份，确认连通性

curl -s "https://us.posthog.com/api/users/@me/" \
  -H "Authorization: Bearer $POSTHOG_READ_ONLY_KEY" \
  -H "Content-Type: application/json" | jq '{email: .email, org: .organization.name}'

返回邮箱与组织名即表示密钥有效。注意域名 us.posthog.com 对应美区实例，若你的数据在欧盟实例，需按官方说明替换域名。

第 3 步：用「提问 → 查询」的方式做分析

你可以直接这样问：

「最近 7 天事件量 Top 30 是哪些？」
「过去 30 天每日活跃用户趋势如何？」
「入职完成率是多少？」
「最近 24 小时错误事件各有多少？」

助手会据此生成 HogQL 查询。例如入职完成率的查询形如：

{
  "query": {
    "kind": "HogQLQuery",
    "query": "SELECT count(DISTINCT if(event = 'onboarding_field_started', distinct_id, NULL)) as started, count(DISTINCT if(event = 'onboarding_completed', distinct_id, NULL)) as completed FROM events WHERE timestamp > now() - INTERVAL 30 DAY"
  }
}

第 4 步：查功能标志状态

curl -s "https://us.posthog.com/api/projects/{项目ID}/feature_flags/" \
  -H "Authorization: Bearer $POSTHOG_READ_ONLY_KEY" | \
  jq -r '.results[] | "\(.key): active=\(.active)"'

第 5 步：排查单个用户

先通过邮箱定位用户：/api/projects/{项目ID}/persons/?email=... 拿到 distinct_ids，再拉取该用户最近 50 条事件构成「用户旅程」，必要时调用功能标志的本地评估接口，确认该用户命中哪些标志、返回什么值。

第 6 步：核算 AI 成本

围绕 $ai_generation 事件，按 $ai_model 或 $ai_service 分组统计调用次数、总令牌数与平均延迟；再用延迟阈值（如大于 5 秒）筛出慢调用明细。

第 7 步：格式化与收尾

统一用 jq '.results'、jq -r '.results[] | "\(.id)\t\(.name)"' | column -t、jq '.results[:10]' 等方式输出，最后对照验证清单自查。

4. 同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
posthog-analytics（本技能）	面向 AI 助手的 PostHog 数据查询技能	事件字典、仪表板地图、功能标志核查、HogQL 模板、LLM 成本分析、安全凭证范式	需支持技能机制的环境 + PostHog 只读密钥；门槛低，安装后即可自然语言提问	日常指标速查、单用户排障、AI 成本核算	优势：上下文精准、字段不瞎猜、内置安全规范；不足：与特定 PostHog 项目的数据契约强绑定，换项目需补事件字典
PostHog 官方 Web 后台	官方可视化分析平台	仪表板、漏斗、留存、会话回放、功能标志管理	门槛最低，浏览器登录即可	探索式分析、看板分享、非技术同事自助查看	优势：图形化直观、功能最全；不足：无法被 AI 直接调用，重复性查询需手工点选，批量导出不便
Amplitude / Mixpanel 等第三方分析平台	商业化产品分析 SaaS	事件分析、漏斗、留存、群组、实验	需重新接入 SDK 与埋点，迁移成本高	已有该技术栈的团队	优势：分析模型成熟、生态完善；不足：与本项目现有 PostHog 埋点不互通，无法直接复用已有事件数据
Metabase / 自建数仓 + SQL	通用 BI 与数据仓库方案	任意 SQL 查询、可视化看板、权限体系	门槛较高，需数据同步管道与建模	跨数据源的统一报表、长期数据资产沉淀	优势：灵活度最高、可跨源；不足：需自建 ETL，实时性依赖同步频率，且同样缺乏「AI 直接可读的事件语义」
直接在对话中粘贴 HogQL 让通用 AI 生成	通用大模型辅助	生成 SQL/HogQL 语句	门槛最低	一次性临时查询	优势：零配置；不足：模型不了解你的事件命名与属性结构，极易编造字段，且缺乏密钥安全与项目隔离约束

5. 该技能的典型应用场景与实际体验情况

场景一：产品经理复盘入职漏斗

痛点是「知道有用户在入职环节流失，但说不清卡在哪一步」。使用方式是直接问「过去 30 天入职各阶段完成情况」，技能会基于 onboarding_step_transition、onboarding_phase_completed、onboarding_completed 等事件拼出查询，并可用 onboarding_dropout_risk_detected 拉出高风险用户名单。实际体验上，最大收益是免去了回忆事件名的过程——技能内置的字典让人不必翻埋点文档；需要注意的是，漏斗结论应结合时间窗口一起看，短窗口容易受活动影响而失真。

场景二：客户成功排查单个用户问题

用户反馈「新功能没出现」。传统做法是来回确认用户 ID、再找研发查标志。使用本技能后，先按邮箱查到用户档案与 distinct_ids，再拉该用户最近 50 条事件还原旅程，最后对该用户做功能标志本地评估，确认 onboarding-flow 或 trial-duration 的命中情况。体验上响应速度明显快于跨团队沟通；注意事项是查询输出可能包含用户属性等敏感信息，需按技能验证清单做脱敏处理。

场景三：工程团队盯错误率与异常恢复

针对 javascript_error_occurred、unhandled_promise_rejection、react_query_error、drafts_creation_failed、contact_scoring_failed 这组错误事件，可以一条查询拿到过去 24 小时各错误类型的计数排序；再结合 circuit_open、job_unblocked、stale_blocked_jobs_recovered 观察系统自愈动作。上手难度低，几乎就是「问一句话」；注意事项是错误事件量可能很大，务必用限制条数与时间窗口控制输出。

场景四：AI 团队核算 LLM 调用成本

这是技能中最有差异化的一块。按 $ai_model 分组可拿到各模型调用次数、总令牌与平均延迟；按 $ai_service 分组可定位哪个业务服务最「烧钱」；用 $ai_latency > 5 可捞出慢调用明细，配合 $ai_trace_id 回溯单次生成链路。实际体验是「从不知道花了多少，到能按服务归因」；注意事项是模型名会随供应商版本变化（技能中的活动模型快照仅代表某个时间点的样貌），分析时应动态按实际出现的 $ai_model 分组，而非写死模型名。

6. 该技能能为用户带来的价值

效率提升：把「登录后台 → 选项目 → 找仪表板 → 调时间范围 → 读图」的多步操作，压缩为「一句话提问 → 拿到查询结果」。对于每天都要看几眼核心指标的角色，节省的是高频重复动作的时间。
门槛降低：HogQL 有一定学习曲线，事件名与属性名更是团队私有知识。技能把这两层知识都前置提供给 AI，让不写 SQL 的产品、运营也能自己拿到数据结论。
错误率下降：生产/本地项目隔离、字段访问写法规范、输出条数限制、四项验证清单，共同减少了「查错环境」「字段拼错」「结果太乱看不懂」三类常见失误。
安全合规兜底：强制环境变量加载 + 明确禁止回显密钥 + 只读密钥约定，把「让 AI 碰生产数据」这件事的风险控制在可接受范围内。
长期价值：技能本质是一份活的数据契约文档。随着事件字典和仪表板地图持续维护，团队的数据知识不再散落在个人脑中，而是变成了 AI 可复用、可传承的资产。

7. 常见问题 FAQ

Q1：这个技能怎么安装？需要付费吗？

A：安装方式取决于你所使用的 AI 助手/智能体平台，通常是在技能市场中检索 posthog-analytics 或技能ID 13659 后启用，具体入口与命令以官方说明为准。技能本身是查询 PostHog 数据的操作规范，不额外收费；但 PostHog 平台自身按其套餐计费，同样以官方说明为准。

Q2：它会不会把我的 API Key 泄露出去？

A：技能从设计上就要求使用 set -a && source .env && set +a 加载环境变量，并明确禁止在命令中直接写 Bearer phx_...、禁止用 echo 打印密钥。同时建议只配置只读密钥。需要注意的是，安全性最终仍取决于你的使用习惯：不要把密钥贴进聊天窗口，.env 文件不要提交到代码仓库。

Q3：换了一个 PostHog 项目还能用吗？

A：可以，但需要调整。技能中的事件字典、仪表板 ID、功能标志键、项目 ID 都是围绕某个具体项目整理的示例。切换项目后，建议先用 /api/projects/ 列出可用项目确认访问权限，再逐步补充你自己的事件清单。若不做替换，AI 可能生成指向旧项目或不存在事件的查询。

Q4：它和直接问通用 AI「帮我写个 HogQL」有什么区别？

A：关键差别在上下文准确性与安全约束。通用 AI 不知道你的事件叫 onboarding_field_started 还是 onboarding_started，很容易编字段；本技能把真实事件名、属性名、仪表板 ID 都写进上下文，并且内置了凭证加载范式与结果格式化规范。对于一次性临时查询，通用 AI 够用；但涉及生产数据、需要可复现的分析时，本技能更靠谱。

Q5：适合谁用？不适合谁？

A：适合产品/增长/客户成功/工程等需要频繁查 PostHog 数据、且愿意用命令行与 AI 助手协作的团队。不太适合完全不想接触命令行、只想看现成图表的同事——这类场景直接用 PostHog 官方仪表板或打开技能中列出的仪表板链接会更顺手。另外，如果团队尚未建立稳定的事件命名规范，建议先补埋点体系，再引入本技能，效果会更好。