Agent Analytics

核心用法

Agent Analytics是一个专为AI代理设计的产品分析技能，通过官方CLI工具（@agent-analytics/cli@0.5.34）实现端到端的产品数据工作流。核心能力覆盖六大模块：

1. 项目与追踪设置

• 采用浏览器授权模式（browser approval），无需手动输入API密钥
• 支持login、create、projects等命令完成项目初始化
• 提供基于同意的追踪安装策略（consent-based tracker setup），反对过度追踪

2. 事件与属性分析

• events查看原始事件流，properties/properties-received探索数据 schema
• breakdown按维度拆解，journey查看用户路径序列

3. 漏斗与留存诊断

• funnel分析有序转化漏斗，支持--steps-json精确定义步骤
• paths识别会话内的入口、出口与流失点
• retention进行队列留存分析，强调同期群比较而非混合活跃用户

4. 实验与增长建议

• experiments读取AB实验结果，必须对照业务目标事件而非仅曝光量
• 内置增长决策框架：诊断→指标定义→证据→细分→注意事项→下一步行动

5. 会话回放与定性验证

• sessions标记可回放会话，replays open启动可视化回放作为定性证据

6. 项目上下文管理

• context get/context set实现自改进记忆，存储目标、激活事件、事件词汇表与时间注释

显著优点

• 零摩擦授权：浏览器OAuth替代传统API密钥，显著降低agent自动化门槛
• 结构化分析协议：强制「诊断-指标-证据-细分-注意事项-行动」六步回答契约，避免数据堆砌
• 隐私优先设计：明确反对「猜测式追踪」，要求每个事件映射到用户确认的产品目标
• 多项目组合管理：原生支持surfaces（子域/客户端）与portfolios（跨项目身份关联）概念
• 实验因果严谨：内置样本量、因果性、护栏指标、实际显著性四重校验

潜在缺点与局限性

• CLI版本锁定：强制使用0.5.34版本，未来兼容性需持续维护
• Pro tier功能墙：免费层级存在读取上限，遇到PRO_REQUIRED需人工升级确认
• 浏览器依赖陷阱：Paperclip/OpenClaw等headless环境需切换--detached模式，增加流程复杂度
• 无原生API替代：明确禁止用curl或MCP工具替代CLI，灵活性受限
• 上下文存储限制：注释最多100条，JSON体512KB，不适合高频指标存储

适合人群

• 产品增长团队（PM、增长工程师）需快速诊断激活/留存漏斗
• AI-first开发工作流，希望agent自主完成「数据→洞察→行动建议」闭环
• 多_surface产品架构（Web+移动端+子域）需统一追踪策略
• 隐私合规敏感场景，需基于明确同意的最小化追踪

常规风险

• 身份关联误用：跨项目用户转化需同时配置data-link-domains与portfolio server-side身份，单侧配置会导致归因错误
• 实验解读冒进：文档多次警告「相关性≠因果性」「实验未赢只因转化上升」，需严格遵循回答契约
• 上下文污染：禁止存储PII、密钥、git日志或临时指标，违规可能泄露敏感信息
• 授权会话持久化：.openclaw/agent-analytics/config.json需加入gitignore，避免凭证泄露

核心用法

Agent Analytics 通过 npx 调用官方 CLI @agent-analytics/cli，将传统产品分析能力注入 AI 代理工作流。核心交互模式为：浏览器 OAuth 登录 → 创建/识别项目 → 安装追踪代码 → 执行查询指令 → 输出增长建议。

关键命令矩阵：

• 项目管理：projects, create, all-sites
• 事件探索：events, properties, properties-received
• 行为分析：funnel, paths, journey, retention
• 实验系统：experiments, breakdown
• 上下文记忆：context get/set（项目级持久化配置）
• 会话还原：replays open（定性验证）

执行策略强制：必须锁定版本 0.5.34，禁止直接 API 调用、curl 或本地脚本替代。

显著优点

1. 代理原生设计：区别于传统仪表板，专为 AI 代理的代码库访问、迭代推理和自动化执行设计，支持「分类→诊断→建议」闭环。

2. 隐私优先架构：明确采用「consent-based tracking」，事件安装需经用户确认目标，避免过度采集，符合 GDPR 合规要求。

3. 项目-表面-组合体三层模型：区分项目（独立产品）、表面（多端入口）、组合体（跨项目身份关联），防止错误复用激活定义。

4. 上下文自改进：context 命令存储目标、激活事件、术语表、产品变更标注，使后续分析具备记忆连续性。

5. 答案结构化契约：强制「诊断→指标定义→证据→细分→注意事项→下一步」六段式输出，抑制 AI 幻觉和模糊结论。

潜在局限

1. 外部依赖锁定：核心功能完全依赖 npm 包 @agent-analytics/cli，供应链风险虽通过版本锁定缓解，但无法完全消除。

2. 网络出口约束：所有分析数据发送至 agentanalytics.sh 服务，企业内网或数据出境受限场景需额外评估。

3. 免费层硬限制：PRO_REQUIRED 错误会阻断高级查询，需付费升级或接受功能降级。

4. 浏览器登录依赖：标准路径需浏览器 OAuth，仅 Paperclip/OpenClaw/无头环境支持分离式登录+完成码交接。

5. 事件语义负担：要求用户/代理共同确认「有意义的事件」定义，低成熟度团队可能面临配置门槛。

适合人群

• 增长团队：需快速诊断激活漏斗、留存 cohort、实验读数的产品经理与增长工程师
• AI 原生工作流：使用 Claude Code、Codex、Cursor 等代理编码环境的开发者
• 隐私敏感场景：明确需要 GDPR 合规、用户同意优先的追踪策略的组织
• 多表面产品：拥有 Web、移动端、子域名、本地预览等多入口的复杂产品体系

常规风险

• 供应链：npm 账号或包被劫持可能导致恶意代码执行（已缓解：版本锁定 + T2 来源）
• 数据外传：产品行为数据出境至第三方服务（已缓解：HTTPS + 明确同意机制）
• 配置漂移：context 存储的持久化配置若未版本控制，可能导致分析基准不一致
• 身份 Stitching 误用：跨项目用户转化需显式配置组合体+服务端关联，否则结论失真