Agent Analytics

面向 AI 智能体的产品分析能力。当用户希望智能体安装 Agent Analytics、查询产品行为、诊断激活或留存问题、检查用户路径与转化漏斗、读取实验数据，或决定下一步增长动作时，请使用本技能。

CLI 是执行底层环境。只要存在代码仓库访问权限，就应始终从用户的代码库、项目目标和产品工作流出发。框架级使用范例应统一存放在 references/growth-recipes.md 中，而非作为独立技能分散管理。

强制执行策略

• 执行实时 Agent Analytics 任务时，必须使用：npx --yes @agent-analytics/cli@0.5.34 。
• 除非用户明确要求，否则禁止用原始 API 调用、curl、本地仓库脚本、MCP 工具或本地安装的二进制文件替代 CLI。
• 优先使用预定义命令：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 的运行时，或无头（headless）运行时，以及浏览器回调不可用时，才启用分离式（detached）登录。
• 禁止向用户索要原始 API 密钥或密钥类凭证。常规配置、付费升级及已恢复的智能体任务，均应在浏览器授权的 CLI 会话中完成。
• 若 CLI 返回 PRO_REQUIRED 或免费版读取配额已达上限，请说明被阻断的原因，执行：upgrade-link --detached --reason "<为何需要 Pro 版>" --command "<被阻断的命令>"，发送控制台交接链接，在升级完成后运行 whoami，再重试被阻断的命令。仅当明确需要轮询（polling）时，才可使用 upgrade-link --wait。控制台页面将首先确认当前账户与 CLI 一致，并展示被阻断的命令及其原因。
• 执行 create 前需校验项目名称格式：^[a-zA-Z0-9._-]{1,64}$。

认证与初始化

对于 Claude Code、Codex、Cursor 及本地 CLI 运行时，请始终从标准浏览器授权流程开始：

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

切勿仅因任务在智能体内执行，就选择分离式登录。对于 Paperclip、OpenClaw 及其他基于 Issue 的运行时，请运行 login --detached，发送授权 URL，等待完成码（finish code），再执行打印出的交换命令（exchange command）完成登录。

在 OpenClaw 及类似托管运行时中，请使用持久化认证存储，且**绝不可提交该存储内容**：

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

--config-dir "$PWD/.openclaw/agent-analytics" 同样有效。请**切勿提交** .openclaw/agent-analytics/config.json。更多初始化细节请参阅 references/setup-auth.md。

执行前分类

Agent Analytics 以项目为第一单位，并具备组合（portfolio）感知能力。在初始化、分析读取或埋点建议之前，须先将目标归类为：项目本地任务、项目内某表面（surface）、或跨项目的组合级任务。

• 项目是本地产品认知的基本单元。它拥有事件、激活、留存、生命周期、版本发布、实验、目标及 project_context。
• 一个项目可包含多个表面：应用（app）、营销页、文档、博客、定价页、注册页、新手引导、子域名、移动端客户端、本地预览 URL、部署预览等。
• 组合（portfolio）是关联项目间的跨项目增长系统。当配置完成后，它可连接有意分组的组合内项目，实现共享目标、角色、里程碑及身份感知型读取。
• 保持项目本地事实的本地性。切勿让组合上下文覆盖各项目的激活逻辑、事件含义、生命周期或目标设定。

决策规则示例：子域名通常属于表面；移动端 App 若与主站共享激活逻辑与生命周期，则视为表面；免费工具若服务于同一产品闭环，则视为表面；localhost、预发环境（staging）、局域网 URL 及各类预览 URL 属于初始化或 QA 表面；独立产品应作为独立项目纳入同一组合下。若某 URL 不符合预期，不应立即判定为失败，而应主动澄清其所属项目及表面。

命令作用域说明：项目本地初始化或分析使用项目级命令；关联项目分组使用 portfolios create、portfolios update 和 portfolios list；共享目标、角色与里程碑仅存在于组合级解读中。权威文档地址：https://docs.agentanalytics.sh/guides/projects-surfaces-portfolios/。

跨项目身份归因（identity stitching）需双向配置：追踪器的 data-link-domains 可在相关域名间透传匿名 _aa 值，但**仅服务端组合范围（server-side portfolio scope）才能使不同项目共享用户身份**。如需构建身份组合，请使用 portfolios create、portfolios update 和 portfolios list 设定成员边界与隐私优先的邮箱查找范围。data-link-domains 单独使用仅用于链接装饰，**无法使不同项目共享身份**。除非两端均已正确配置，否则不得声称跨项目严格用户转化。

基于用户同意的追踪器初始化策略

安装追踪或事件时，必须采用基于用户同意、由项目自主拥有的工作流。禁止猜测、禁止过度埋点、禁止安装未映射至用户确认的产品目标或代码仓库中具体工作流的通用事件。

初始化顺序如下：

1. 明确项目 / 表面 / 组合的作用域。
2. 向用户提出或征询初始项目 / 组合目标，并在持久化上下文前获得确认。
3. 若具备代码仓库访问权限，需检查路由、表单、CTA 处理器、认证 / 初始化 / 支付流程、现有分析调用、服务端持久化结果及测试用例。
4. 按需执行登录。
5. 使用 create --domain 或 projects 创建或识别项目；其中 --domain 是初始化来源（setup origin），并非项目身份标识（project identity）。
6. 精确安装该项目返回的追踪代码片段。将基础追踪器片段视为埋点起点，而非完整埋点方案。
7. 仅添加最小集、有明确业务意义的命名事件及追踪器用户授权（opt-in）项，且须全部对应该用户已确认的目标。
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. 禁止为自动信号重复添加自定义事件：页面浏览（page views）、路径（paths）、来源（referrers）、UTM 参数、会话（sessions）、首次访问天数、首触归因（first-touch attribution）、设备 / 浏览器字段、国家等。
11. 逐条解释每个事件所支持的分析能力，使用 events 验证首个有用事件，并总结已安装事件目前可使用户智能体回答哪些问题。

可复制的初始化交接说明：

为此项目配置 Agent Analytics。若需浏览器授权，请打开并等待我操作。我将使用 Google 或 GitHub 登录并完成授权。若浏览器回调无法恢复你当前会话，请向我索取完成码（finish code）作为备用方案。之后，请创建或识别匹配的 Agent Analytics 项目，询问我确认初始产品目标后再持久化上下文，安装该项目专属的追踪器，仅添加与本仓库产品工作流及该目标强相关的有意义自定义事件，逐条解释每个事件的作用，并验证首个有用事件。

产品上下文闭环

使用 context get 和 context set 作为轻量、自优化的记忆机制。在任何项目级分析启动前，先解析出项目，再执行 context get 。context set 将完全替换已存储的上下文；因此务必先读取现有上下文，再合并你的变更，并保留仍有效的目标、激活事件、术语表（glossary）条目及注释。

保持上下文简短。仅保存持久化产品事实：目标、激活定义、绑定至 event_name 的事件含义，以及重大产品变更的时间标注（landing page、定价、新手引导、功能、发布、实验等变更）。

更新术语表条目前，请先通过 properties 或 properties-received 检查当前事件名称。

跳过噪声信息：周度指标值、临时峰值、粘贴的报告、原始会议纪要、长篇笔记、用户列表、PII（个人身份信息）、密钥、git 提交日志及主观猜测。禁止存储 git 提交日志。禁止发明不被支持的字段（如 findings、learnings、open_questions）；仅允许存储符合 goals、activation_events、事件名 glossary 及 annotations 结构的内容。

注释（annotations）使用 occurred_at、title 及可选的 note 字段。注释应极为精炼：总数上限 100 条，JSON 主体大小上限 512KB。分析响应中仅包含请求日期范围内及前后各一天的注释；context get 则返回全部注释。对于多项目或多域名系统，除非用户明确声明其含义共享，否则应保持激活定义与术语表相互独立。示例激活路径：试用注册 + 首个条目创建；邀请队友。这正是下一次分析更智能的起点。

分析闭环

针对“激活流失点在哪”、“下一步应修复什么”、“该运行哪个实验”等宽泛问题，请采用此闭环式增长范式。它提供的是指导原则，而非刚性协议。

1. 完成认证与项目解析；全账户级问题以 projects 为起点。

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

2. 读取 context get ，并将已配置的激活事件视作激活真相源（source of truth）。若缺失激活定义，请主动询问或配置，禁止静默猜测。
3. 使用 properties 、properties-received 及近期 events 探索真实现状。
4. 使用 funnel 分析有序激活漏斗中的流失（leakage），涵盖人群、时间窗口、步骤事件、身份依据、严格幸存者（strict survivors）、最大绝对流失量与最大相对流失量。当步骤或标签需精确表达时，优先使用 --steps-json。
5. 使用 paths 分析围绕激活目标的会话级入口、出口、绕行与流失行为；切勿将路径呈现为长周期归因（long-cycle attribution）。
6. 围绕最大流失点，使用 breakdown 按已有维度进行拆解：路径、来源、引荐方、CTA 标签、设备、浏览器、国家、广告系列、套餐、表面、新手引导步骤等。
7. 仅在代表性抽样检查或埋点合理性验证时，才使用 events 或 journey。
8. 当 sessions 标记某代表性会话含 ▶ replay 时，若可视化行为有助于解释漏斗或路径发现，请运行 replays open --session --project 。将回放视为该会话的定性证据，**绝非聚合性证明**。该命令将打开最新可播放片段，并在存在更多片段时予以提示。
9. 使用 retention 分析同期群（cohorts），而非混杂的活跃用户声明。应在相同生命周期阶段对比同期群，并注明右删失（right-censored）时段。
10. 实验分析应以业务目标事件为基准，而非曝光次数（exposure count）。在样本量、因果性、护栏指标（guardrail）、实际显著性等前提下，判断“保留 / 修改 / 终止 / 完成”。
11. 默认推荐一项窄口径实验。当追踪、激活、样本、身份或实验重叠等问题阻碍结果读取时，应推荐就绪性修复（readiness fix），而非实验。

漏斗分析师行为准则：明确说明人群与转化窗口、展示数量与比率、指出最大驱动因素、检查细分或表面集中度、避免模糊的追踪建议。

组合级表面-角色诊断：先明确各项目在增长系统中的角色，再据此解读项目本地指标。除非用户明确定义，否则不得在 App、文档、目录、落地页或线索生成（lead-gen）等不同项目间复用同一激活定义。

分析回答契约

回答应以**决策建议**开篇，再用**指标证据**支撑。对于漏斗、留存、路径、实验、归因及审计类问题，统一按以下结构作答：

1. 最优判断或诊断结论。
2. 指标定义：人群、时间窗口、事件名称、身份依据、转化窗口。
3. 证据：数量、比率、原始活动、严格幸存者、流转过程、最大驱动因素。
4. 问题集中所在的细分、同期群或表面。
5. 限制条件：身份识别、样本量、右删失数据、归因局限、因果性、埋点限制等。
6. 一项边界清晰的后续查询或动作。

指标审慎性原则：注册（signup）≠ 激活（activation）。相比注册量，应更关注留存的激活用户、收入、投资回收期（payback）或持久价值。漏斗可诊断流失点，但无法证明用户流失原因。未经实验或因果设计，不得将相关性等同于因果性。实验不能仅因转化率上升就宣称“获胜”。应添加最小必要事件或属性，以解锁对应增长问题。

示例：

最优判断：解决激活流程中的设置摩擦。
指标：App 新手引导页 → 设置文案页 → 注册 → 项目创建 → 7 天内首次事件接收。
证据：原始注册 / 项目活动存在，但严格幸存者在 first_event_received 前即大幅衰减。
限制条件：跨项目身份识别仅在组合成员关系与 link-domain 透传均配置后才生效。
后续动作：按所选运行时与 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 或预览 URL 单独创建项目。
• 禁止为追踪器自动信号（如点击、页面浏览）重复安装通用事件。
• 禁止在上下文中存储临时指标、报告、PII、密钥或 git 提交日志。
• 禁止仅以原始数字堆砌作答；必须遵循分析回答契约。
• 禁止仅凭注册量对渠道排序；未配置身份识别时，不得声称跨项目严格用户转化；不得将相关性推断为因果性。
• 若用户未升级，禁止近似模拟仅限付费版的读取能力。

验证

完成初始化或分析前，请执行以下验证：

• 在必要时，使用 auth status 或 whoami 验证认证状态。
• 使用 projects 或 project 验证项目身份与来源（origins）。
• 验证用户项目已精确安装对应的追踪代码片段。
• 使用 events --event --days 7 --limit 20 验证至少一个首个有用事件已成功上报。
• 验证上下文读写操作能准确保留现有持久化事实。
• 验证最终回答严格遵循：诊断结论 → 指标定义 → 证据 → 细分 / 表面 → 限制条件 → 一项边界清晰的后续动作。