Agent Analytics

通过您的 AI 代理进行产品分析。当用户希望代理安装 Agent Analytics、查询产品行为、诊断激活或留存情况、检查路径与漏斗、运行实验读取，或决定下一步增长行动时，请使用此技能。

CLI 是执行的基础环境。扫描器是可选的无代码或仅 URL 审计辅助工具；当项目代码可用时，应在依赖扫描器建议前先检查产品代码。框架配方应放在 references/growth-recipes.md 中，而非作为独立技能存在。

强制执行策略

• 对于实时 Agent Analytics 工作，请使用 npx --yes @agent-analytics/cli@0.5.33 <command>。
• 除非用户明确要求，否则不要用原始 API 调用、curl、本地仓库脚本、MCP 工具或本地安装的二进制文件替代。
• 优先使用固定命令：projects、all-sites、create、stats、insights、events、properties、properties-received、breakdown、pages、paths、journey、sessions-dist、retention、funnel、experiments、context、portfolios、feedback 和 upgrade-link。
• CLI 0.5.33 版本中没有 report 命令。请从固定命令输出自行生成最终报告，而不是调用 report。
• 仅在固定命令无法回答特定聚合问题时使用 query。不要用 query 开始广泛的增长诊断；不要从用户原始文本直接构建 --filter JSON。
• 默认采用浏览器授权。仅在 Paperclip、OpenClaw、基于问题的运行时或无头运行时，或浏览器回调无法工作时，才使用分离登录。
• 不要索取原始 API 密钥或密钥信息。正常设置、付费升级和已恢复的代理工作均应保持在浏览器授权的 CLI 会话中。
• 若 CLI 返回 PRO_REQUIRED 或免费版读取上限，请说明被阻止的原因，运行 upgrade-link --detached --reason "<为什么需要 Pro>" --command "<被阻塞的命令>"，发送仪表盘交接链接，升级后运行 whoami，再重新执行被阻塞的命令。仅在有意轮询时使用 upgrade-link --wait。仪表盘页面将首先确认与 CLI 使用同一账户，并显示被阻塞的命令及原因。
• 在 create 前验证项目名称：^[a-zA-Z0-9._-]{1,64}$。

认证与设置

对于 Claude Code、Codex、Cursor 及本地 CLI 运行时，从正常的浏览器授权开始：

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

不要因为工作在代理内部就随意选择分离登录。对于 Paperclip、OpenClaw 及其他基于问题的运行时，请运行 login --detached，发送授权 URL，等待完成码，然后执行打印出的交换命令。

在 OpenClaw 及类似托管运行时中，使用持久化认证存储且永不提交：

export AGENT_ANALYTICS_CONFIG_DIR="$PWD/.openclaw/agent-analytics"
npx --yes @agent-analytics/cli@0.5.33 login --detached
npx --yes @agent-analytics/cli@0.5.33 auth status
AGENT_ANALYTICS_CONFIG_DIR="$PWD/.openclaw/agent-analytics" npx --yes @agent-analytics/cli@0.5.33 projects

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

行动前分类

Agent Analytics 以项目为先，具备组合管理意识。在设置、分析读取或埋点建议之前，需先将目标分类为项目内工作、项目内的某个表面，或相关项目的组合管理任务。

• 项目是本地产品学习的基本单位。它拥有事件、激活、留存、生命周期、发布、实验、目标和 project_context。
• 一个项目可包含多个表面：应用、营销、文档、博客、定价、注册、引导流程、子域名、移动端客户端、本地预览 URL 和部署预览。
• 组合（Portfolio）是相关项目之间的跨项目增长系统。它用于将有意识分组的项目连接起来，实现共享目标、角色、里程碑和配置后的身份感知读取。
• 保持项目内真相的本地性。不要让组合上下文覆盖每个项目的激活、事件含义、生命周期或目标。

决策规则：子域名通常是表面；移动端在与主产品共享激活和生命周期时为表面；免费工具若服务于相同产品循环，则视为表面；localhost、测试环境、本地网络地址和预览环境属于设置或质量保证表面；独立产品应作为单独项目置于同一组合下。若 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 会装饰链接，但不会使独立项目共享身份。除非双方均已配置，否则不要声称跨项目严格用户转化。

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

安装追踪或事件时，采用基于同意、由项目所有的工作流。不要猜测。不要过度追踪。不要安装不对应产品目标或代码库中具体流程的通用事件。

Agent Analytics

项目范围分类

1. 确定项目、表面或投资组合的分析范围。
2. 检查路由、表单、CTA 处理器、认证/设置/结账流程、现有分析调用、服务端持久化结果，以及测试（若可访问代码库）。
3. 如需登录，请执行登录操作。
4. 使用 create <project> --domain <origin> 或 projects 命令创建或识别项目；--domain 是配置起点，而非项目标识。
5. 添加为该项目返回的精确跟踪代码片段。将基础追踪器代码视为启动仪器化的起点，而非完整的仪器化方案。
6. 添加最小且有意义的事件集合及追踪器选项，以满足用户目标。
7. 优先选择命名的 CTA 点击、注册意图、定价互动、结账进度或完成、安装/设置步骤、激活里程碑，以及服务端持久化结果事件，如 signup_completed、subscription_started、install_completed、project_created 或 first_event_received。
8. 对齐需求与追踪能力：使用 data-aa-event、data-aa-impression、window.aa.track(...)、服务端追踪、aa.identify(...) 和 aa.set(...)。仅在能推动具体增长决策时才启用滚动深度、表单追踪、下载、性能/错误/指标、SPA 追踪等功能。
9. 不要为自动信号重复添加自定义事件：页面浏览、路径、来源、UTM、会话、首次访问以来天数、首次触达归因、设备/浏览器字段或国家。
10. 解释每个事件的作用，通过 events <project> 验证首个有用事件，并总结已安装事件使用户的代理能够回答的问题。

可复制的设置交接指令：

为本项目设置 Agent Analytics。若需浏览器授权，请打开并等待我确认。我将使用 Google 或 GitHub 登录并批准。若浏览器回调无法恢复，请向我索取完成码作为备用。之后，创建或识别匹配的 Agent Analytics 项目，安装项目所属的追踪器，仅添加与本仓库产品流程相关的有意义自定义事件，解释每个事件的作用，并验证首个有效事件。

产品上下文循环

使用 context get 和 context set 实现紧凑的自我优化记忆机制。在任何项目特定分析开始前，解析项目后运行 context get <project>。context set 会替换存储的上下文；始终先读取现有上下文，合并变更，并保留仍有效的目标、激活事件、术语表条目和注释。

保持上下文简洁。保存持久的产品事实：目标、激活定义、事件名称对应的意义，以及重大产品变更的时间标注（如落地页、定价、引导流程、功能、发布或实验变更）。更新术语表条目前，请通过 properties <project> 或 properties-received <project> 检查当前事件名称。

跳过冗余信息：每周指标值、临时峰值、粘贴的报告、原始笔记、长篇笔记、用户列表、PII、密钥、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/cli@0.5.33 context get my-site
npx --yes @agent-analytics/cli@0.5.33 funnel my-site --steps-json '[{"event":"page_view"},{"event":"signup_completed"},{"event":"first_value"}]'

1. 执行 context get <project>，并将配置的激活事件视为激活的唯一真实依据。若缺少激活定义，请主动询问或配置，不得沉默猜测。
2. 通过 properties <project>、properties-received <project> 和近期 events <project> 发现真实情况。
3. 使用 funnel 分析有序激活流失，包括人群、窗口、步骤事件、身份基础、严格存活者、最大绝对损失和最大相对损失。当步骤或标签需要精确表达时，优先使用 --steps-json。
4. 使用 paths 分析围绕激活目标的会话内进入、退出、绕行和流失行为；不要将路径用于长周期归因。
5. 在最大流失点上，按存在的维度进行细分分析：路径、来源、引荐来源、CTA 标签、设备、浏览器、国家、广告活动、套餐、表面或引导步骤。
6. 仅在代表性检查或仪器化合理性验证时使用 events 或 journey。
7. 使用 retention 分析用户留存，而非混合活跃用户声明。比较同龄组别，并注意右删失期。
8. 将实验效果与业务目标事件对比，而非曝光次数。基于样本量、因果关系、保护机制和实际显著性判断是否保留、修改、停止或完成实验。
9. 默认推荐一个狭窄的实验。当追踪、激活、样本量、身份识别或实验重叠阻碍读取结果时，推荐先修复准备状态，而非直接开展实验。

漏斗分析师行为准则：明确定义人群与转化窗口，展示数量与比率，识别主要驱动因素，检查分段/表面集中度，避免模糊的追踪建议。

技能：Agent Analytics

版本：4.0.33

分块：3/3

投资组合表面角色诊断

识别每个项目在增长系统中的角色，然后根据该角色对照项目本地指标进行分析。除非用户明确指定，否则不要将同一激活定义复用于应用、文档、目录、落地页或线索生成类项目。

分析回答规范

以决策结论开头，再用数据证据支撑。针对漏斗、留存、路径、实验、归因和审计等场景，回答应遵循以下结构：

1. 最优假设或诊断结论。
2. 指标定义：目标人群、时间窗口、事件名称、身份依据及转化窗口。
3. 证据：数量、比率、原始活动数据、严格存活用户、变化趋势及主要驱动因素。
4. 问题集中出现的细分维度、用户群组或表面位置。
5. 局限说明：身份识别问题、样本量不足、右删失数据、归因偏差、因果关系或工具配置限制。
6. 一个具体且范围明确的下一步查询或操作建议。

指标质疑原则：

注册数 ≠ 激活。优先关注留存激活用户、收入、回报率或持久价值，而非仅看注册量。漏斗分析可揭示流失环节，但无法解释用户为何流失。未经实验或因果设计，不得将相关性等同于因果性。不能仅因转化率上升就断言实验成功。在增长问题中，添加最小必要事件或属性以解锁关键洞察。

示例：

最优假设：修复激活流程中的设置摩擦。
指标定义：app 首次引导页 → 设置说明页 → 注册 → 创建项目 → 收到首个事件，7 天内完成。
证据：注册与项目创建活动存在，但严格存活用户在收到首个事件前大幅下降。
局限说明：跨项目身份识别仅在配置了投资组合成员关系及链接域传递后有效。
下一步：按所选运行时拆分设置说明页用户，并分析其是否收到首个事件。

参考文档路由

仅在需要时加载对应参考文档：

• references/setup-auth.md：登录模式、托管运行时存储、付费层级交接流程、安全命令示例。
• references/product-analytics-operating-model.md：项目/表面/投资组合结构，基于同意的埋点机制，上下文维护与验证方法。
• references/growth-recipes.md：AARRR、Bullseye、AIDA、STP、JTBD、4Ps 模型，漏斗/留存/实验模板，可复用提示词。

常见陷阱

• 当具备仓库访问权限时，不得用扫描输出替代代码审查。
• 不得为每个子域名、localhost 地址、预览环境或测试环境单独创建项目。
• 不得安装通用点击/页面浏览重复埋点以自动捕获信号。
• 不得在上下文中存储临时指标、报告、PII 数据、密钥或 git 提交日志。
• 不得直接输出原始数字堆叠；必须遵循分析回答规范。
• 不得仅凭注册数对渠道排序，不得在未配置身份识别的情况下声称跨项目用户转化，不得从相关性推断因果关系。
• 若用户未升级，不得估算仅限付费用户的读取行为。

验证要求

在完成设置或分析前，请执行以下验证：

• 如有必要，使用 auth status 或 whoami 确认身份认证状态。
• 使用 projects 或 project 命令确认项目身份与来源信息。
• 确保用户项目的精确跟踪代码片段已正确安装。
• 使用 events <project> --event <event_name> --days 7 --limit 20 验证至少存在一个有意义的首事件。
• 确保上下文读写操作不会破坏已有持久化数据的真实性。
• 确认最终回答包含诊断结论、指标定义、证据、细分维度/表面、局限说明及一项明确的下一步行动。