agent-analytics

Agent Analytics

与 AI Agent 搭配使用的产品分析工具。当用户希望 Agent 安装 Agent Analytics、查询产品行为、诊断激活或留存情况、检查路径和漏斗、读取实验结果，或决定下一步采取什么增长行动时，请使用此技能。

CLI 是执行基础。只要可以访问仓库，就从用户的代码库、项目目标和产品工作流着手。框架方案应放在 references/growth-recipes.md 中，而不是拆分成单独的技能。

强制执行策略

• 对于实时的 Agent Analytics 工作，请使用 npx --yes @agent-analytics/[email protected] <command>。
• 除非用户明确要求，否则不要使用原始 API 调用、curl、仓库本地脚本、MCP 工具或本地安装的二进制文件来替代。
• 首先使用固定命令：projects、all-sites、create、stats、insights、events、properties、properties-received、breakdown、pages、paths、journey、sessions、sessions-dist、replays、retention、funnel、experiments、context、portfolios、feedback 和 upgrade-link。
• CLI 0.5.34 中没有 report 命令。请根据固定命令的输出自行生成最终报告，而不要调用 report。
• 只有固定命令无法回答的精简聚合查询才使用 query。不要用 query 开始宽泛的增长诊断；不要根据用户的原始文本构建 --filter JSON。
• 默认使用浏览器批准。仅在 Paperclip、OpenClaw、基于 issue 的运行时或无头运行时中，或浏览器回调无法工作时，使用分离式登录。
• 不要索要原始 API 密钥或机密信息。常规设置、付费升级和恢复 Agent 工作都应继续使用经过浏览器批准的 CLI 会话。
• 如果 CLI 返回 PRO_REQUIRED 或免费套餐读取上限错误，请说明受阻的答案，运行 upgrade-link --detached --reason "<why Pro is needed>" --command "<blocked command>"，发送仪表板交接链接，然后在升级后运行 whoami，再重新运行受阻命令。仅在确实需要轮询时使用 upgrade-link --wait。仪表板页面会先确认与 CLI 相同的账户，并显示受阻命令和原因。
• 创建前验证项目名称：^[a-zA-Z0-9._-]{1,64}$。

身份验证和设置

对于 Claude Code、Codex、Cursor 和本地 CLI 运行时，请先使用常规浏览器批准：

npx --yes @agent-analytics/[email protected] login
npx --yes @agent-analytics/[email protected] create my-site --domain https://mysite.com
npx --yes @agent-analytics/[email protected] events my-site --event <first_useful_event> --days 7 --limit 20

不要仅仅因为工作在 Agent 中进行就选择分离式登录。对于 Paperclip、OpenClaw 和其他基于 issue 的运行时，请运行 login --detached，发送批准 URL，等待完成代码，然后执行打印出的交换命令。

在 OpenClaw 和类似的托管运行时中，请使用持久化身份验证存储，并且绝不要提交该存储：

export AGENT_ANALYTICS_CONFIG_DIR="$PWD/.openclaw/agent-analytics"
npx --yes @agent-analytics/[email protected] login --detached
npx --yes @agent-analytics/[email protected] auth status
AGENT_ANALYTICS_CONFIG_DIR="$PWD/.openclaw/agent-analytics" npx --yes @agent-analytics/[email protected] projects

--config-dir "$PWD/.openclaw/agent-analytics" 也有效。绝不要提交 .openclaw/agent-analytics/config.json。更多设置详情请参阅 references/setup-auth.md。

行动前先分类

Agent Analytics 以项目为优先，并兼顾项目组合。在设置、读取分析数据或提出埋点建议之前，应先将目标归类为项目本地工作、项目内的某个界面，或相关项目的组合工作。

• 项目是进行本地产品学习的单位。它拥有事件、激活、留存、生命周期、发布、实验、目标和 project_context。
• 一个项目可以包含许多界面：应用、营销页面、文档、博客、定价页面、注册页面、新手引导、子域名、移动客户端、本地预览 URL 和部署预览。
• 项目组合是相关项目的跨项目增长系统。配置后，它会连接有意归入同一组的项目组合项目，用于共享目标、角色、里程碑以及与身份关联的数据读取。
• 项目本地的事实应保留在项目本地。不要让项目组合上下文覆盖各项目的激活、事件含义、生命周期或目标。

决策规则：子域名通常属于界面；如果移动应用与其他界面共享激活和生命周期，则它属于一个界面；如果免费工具会引入同一产品循环，则它属于一个界面；localhost、staging、本地网络 URL 和预览属于设置或 QA 界面；独立产品应作为单独的项目归入一个项目组合。如果 URL 与预期不符，不要立即判定为失败。请先明确它属于哪个项目和界面。

范围命令：项目本地设置或分析使用项目命令；相关项目分组使用 portfolios create、portfolios update 和 portfolios list；共享目标、角色和里程碑仅用于项目组合层面的解读。规范文档：https://docs.agentanalytics.sh/guides/projects-surfaces-portfolios/.

要关联跨项目身份，需配置两侧：追踪器 data-link-domains 会在相关域名间传递匿名 _aa 值，但只有服务器端的项目组合范围才能让不同项目共享身份。使用 portfolios create、portfolios update 和 portfolios list 创建身份项目组合，以设定成员边界和优先保护隐私的邮箱查询范围。仅配置 data-link-domains 只会为链接添加标记，无法让不同项目共享身份。除非两侧都已配置，否则不要声称能够严格统计跨项目的用户转化。

基于用户同意的追踪器设置策略

安装追踪或事件时，应采用基于用户同意、由项目所有者负责的工作流。不要猜测，也不要过度追踪。不要安装无法对应用户确认的产品目标或仓库中特定工作流的通用事件。

设置顺序：

1. 确定项目／界面／产品组合的范围。
2. 询问用户或提出初始项目／产品组合目标，并在存储持久化上下文之前获得确认。
3. 有仓库访问权限时，检查路由、表单、CTA 处理程序、身份验证／设置／结账流程、现有分析调用、服务器端持久化结果和测试。
4. 如有需要，登录。
5. 使用 create <project> --domain <origin> 或 projects 创建或识别项目；--domain 是设置来源，而不是项目身份。
6. 为该项目添加返回的准确追踪代码片段。将基础追踪器代码片段视为埋点工作的起点，而非完整的埋点计划。
7. 添加数量最少、名称明确且有意义的事件和追踪器选项，以满足用户确认的目标。
8. 优先选择命名明确的 CTA 点击、注册意向、定价互动、结账进度或完成情况、安装／设置步骤、激活里程碑，以及服务器端持久化结果事件，例如 signup_completed、subscription_started、install_completed、project_created 或 first_event_received。
9. 将需求映射到追踪器功能：data-aa-event、data-aa-impression、window.aa.track(...)、服务器端追踪、aa.identify(...) 和 aa.set(...)。仅在这些功能能帮助做出具体的增长决策时，才使用滚动深度、表单追踪、下载、核心指标／错误／性能和 SPA 追踪。
10. 不要为自动采集的信号添加重复的自定义事件：页面浏览量、路径、引荐来源、UTM 参数、会话、距首次访问的天数、首次触点归因、设备／浏览器字段或国家／地区。
11. 说明每个事件能实现什么，使用 events <project> 验证首个有用事件，并总结已安装的事件现在能让用户的 Agent 解答什么问题。

可复制的设置交接内容：

Set up Agent Analytics for this project. If browser approval is needed, open it and wait for me. I will sign in with Google or GitHub and approve it. If the browser callback cannot resume you, ask me for the finish code as a fallback. After that, create or identify the matching Agent Analytics project, ask me to confirm the initial product goal before storing durable context, install the project-owned tracker, add only meaningful custom events tied to this repo's product workflows and that goal, explain what each event enables, and verify the first useful event.

产品上下文循环

使用 context get 和 context set 作为精简的自我改进记忆。在开始任何特定于项目的分析时，先确定项目，然后运行 context get <project>。context set 会替换已存储的上下文；始终先读取现有上下文，再合并变更，并保留仍然有效的目标、激活事件、术语表条目和注释。

保持上下文简短。保存持久的产品事实：目标、激活定义、与 event_name 关联的事件含义，以及重大产品变更的日期注释，例如着陆页、定价、引导流程、功能、版本发布或实验变更。更新术语表条目前，使用 properties <project> 或 properties-received <project> 检查当前事件名称。

跳过嘈杂的发现：每周指标值、暂时性峰值、粘贴的报告、原始会议记录、冗长笔记、用户列表、个人身份信息、机密信息、Git 提交日志和猜测。不要存储 Git 提交日志。不要编造不受支持的字段，例如 findings、learnings 或 open_questions；只存储适用于 goals、activation_events、事件名称 glossary 和 annotations 的内容。

注释使用 occurred_at、title 和可选的 note。注释应少而精：最多 100 条，JSON 请求正文最大 512KB。分析响应只包含所请求分析日期范围前后各一天内的注释；context get 会返回所有注释。对于多项目或多域名系统，除非用户明确表示含义相同，否则应分别维护激活事件和术语表。激活事件示例：试用注册后创建首个条目；邀请队友。这能让下一次分析从更好的基础开始。

分析闭环

对于“激活在哪一步流失”“下一步该修复什么”或“该运行哪项实验”等宏观问题，请使用这套闭环增长方法。这是指导原则，不是僵化的流程。

1. 解析身份验证和项目；账户级问题从 projects 开始。

npx --yes @agent-analytics/[email protected] context get my-site
npx --yes @agent-analytics/[email protected] funnel my-site --steps-json '[{"event":"page_view"},{"event":"signup_completed"},{"event":"first_value"}]'

2. 阅读 context get <project>，并将已配置的激活事件视为激活情况的唯一事实来源。如果缺少激活事件，请询问或进行配置；不要默默猜测。
3. 使用 properties <project>、properties-received <project> 和近期的 events <project> 了解实际情况。
4. 使用 funnel 分析有序激活流程中的流失情况，包括用户群体、时间窗口、各步骤事件、身份判定依据、严格留存人数、绝对流失最多的环节和相对流失最多的环节。如果需要精确指定步骤或标签，优先使用 --steps-json。
5. 使用 paths 分析围绕激活目标的会话内入口、退出、绕行和流失行为；不要将路径分析说成长周期归因。
6. 按照实际存在的维度分析最大流失环节：路径、来源、引荐来源、CTA 标签、设备、浏览器、国家/地区、营销活动、套餐、界面或引导步骤。
7. 仅在检查代表性案例或验证埋点是否正常时使用 events 或 journey。
8. 当 sessions <project> 用 ▶ replay 标记代表性会话时，如果视觉行为可能解释漏斗或路径分析的发现，请使用 replays open --session <session_id> --project <project>。回放只能作为该会话的定性证据，不能作为汇总证明。该命令会打开最新的可播放片段，并提示是否还有更多片段。
9. 使用 retention 分析群组，而不是将活跃用户混合后得出结论。按相同的群组生命周期比较，并注明右删失时段。
10. 根据业务目标事件而不是曝光次数解读实验。结合样本量、因果关系、护栏指标和实际显著性方面的注意事项，决定保留、调整、停止还是完成实验。
11. 默认只推荐一项范围明确的实验。如果追踪、激活、样本量、身份识别或实验重叠问题妨碍结果判读，请改为推荐一项准备工作修复，而不是实验。

漏斗分析行为：明确说明用户群体和转化时间窗口，展示人数和比率，找出最大的驱动因素，检查问题是否集中在特定细分群体或界面，并避免给出含糊的追踪建议。

产品组合界面角色诊断：先识别每个项目在增长系统中的作用，再依据该作用分析项目本地指标。除非用户明确指定，否则不要对应用、文档、目录、落地页或潜在客户获取项目套用同一种激活定义。

分析回答规范

先给出决策，再用指标证明。对于漏斗、留存、路径、实验、归因和审计，请按以下结构作答：

1. 最佳方案或诊断结论。
2. 指标定义：用户群体、时间窗口、事件名称、身份判定依据和转化时间窗口。
3. 证据：人数、比率、原始活动量、严格留存人数、变化情况和最大驱动因素。
4. 问题集中的细分群体、用户群组或界面。
5. 注意事项：身份识别、样本量、右删失数据、归因、因果关系或埋点限制。
6. 一项范围明确的后续查询或操作。

审慎看待指标：注册不等于激活。与注册量相比，优先关注留存的已激活用户、收入、回本情况或持久价值。漏斗可以诊断流失，但无法证明用户流失的原因。没有实验或因果设计时，不要把相关性称为因果关系。不要仅仅因为转化率上升就说实验成功。添加能够解答增长问题的最少事件或属性。

示例：

Best bet: fix activation setup friction.
Metric: app onboarding view -> setup copy -> signup -> project_created -> first_event_received within 7d.
Evidence: raw signup/project activity exists, but strict survivors collapse before first_event_received.
Caveat: cross-project identity only counts when portfolio membership and link-domain carrying are configured.
Next: split setup-copy users by selected runtime and first_event_received.

参考资料路由

仅在需要时加载参考资料：

• references/setup-auth.md：登录模式、托管运行时存储、付费层级升级流程，以及安全的命令示例。
• references/product-analytics-operating-model.md：项目/界面/产品组合、基于同意的埋点、上下文维护和验证。
• references/growth-recipes.md：AARRR、Bullseye、AIDA、STP、JTBD、4Ps、漏斗/留存/实验配方，以及可复制的提示词。

注意事项

• 如果可以访问代码库，不要只根据 URL 做假设，而不检查代码。
• 不要为每个子域名、localhost URL、预发布 URL 或预览版都创建一个项目。
• 不要为自动跟踪器信号安装通用的点击/页面浏览重复事件。
• 不要在上下文中存储临时指标、报告、PII、机密或 git 提交日志。
• 不要只罗列原始数字；请遵循分析回答规范。
• 不要仅根据注册量对渠道排名；如果未配置身份识别，不要声称跨项目可严格追踪用户转化；也不要根据相关性推断因果关系。
• 如果用户不升级，不要近似处理仅限付费层级的数据读取。

验证

完成设置或分析前：

• 在适用时，通过 auth status 或 whoami 验证身份验证。
• 通过 projects 或 project 验证项目身份和来源。
• 验证用户项目已安装准确的跟踪代码片段。
• 通过 events <project> --event <event_name> --days 7 --limit 20 验证至少一个有用的首个事件。
• 验证上下文的读取/写入不会覆盖已有的持久事实。
• 验证最终回答遵循诊断、指标定义、证据、细分/界面、注意事项和一项范围明确的后续行动。