Agent Analytics

核心用法

Agent Analytics 是一款专为AI Agent设计的分析基础设施，通过 npx --yes @agent-analytics/cli@0.5.20 命令行工具实现完全无仪表板的分析工作流。核心能力覆盖四大维度：

项目与埋点管理：scan 命令自动分析网站结构并输出 minimum_viable_instrumentation 建议，避免过度埋点；create 生成项目令牌与追踪代码片段；支持 data-aa-event、data-aa-impression 等声明式埋点及 window.aa.track() 程序化埋点。

数据查询与分析：固定命令优先设计，涵盖 stats、insights、events、breakdown、funnel、retention、paths、experiments 等场景。query 命令支持高级过滤但需谨慎处理 JSON 参数，内置字段仅限 event、user_id、date、country、session_id、timestamp，自定义属性需通过 properties.<key> 访问。

实验与迭代：完整支持A/B测试生命周期，从创建实验到追踪转化目标；context get/set 实现项目级持久化知识，存储激活定义、业务目标、事件术语表，使后续分析具备上下文记忆。

认证与运行时适配：默认浏览器OAuth授权，OpenClaw/Paperclip等Issue型运行时强制使用 login --detached 分离式授权；AGENT_ANALYTICS_CONFIG_DIR 指定持久化配置路径避免沙箱丢失。

显著优点

• Agent-First架构：所有操作均可通过CLI完成，天然适合自动化脚本与对话式Agent工作流
• 智能埋点建议：scan 输出优先级分级的埋点方案，杜绝"先全埋再分析"的反模式
• 中文原生支持：文档、CLI输出、技术支持均提供中文版本，OpenClaw指南独立维护
• 免费层实用：10万事件/月、2个项目足以验证MVP；Pro层解锁漏斗、留存、会话路径、365天数据保留等深度分析
• 开放透明：CLI开源（MIT协议），API文档完整，无黑盒推理

潜在局限

• 分组能力受限：group_by 仅支持内置字段，无法直接按 properties.hostname、first_utm_source 等属性分组，复杂归因分析需借助反馈机制或手动聚合
• 时间精度限制：不支持 24h 小时级简写，精确到小时的滚动窗口需自行构造 epoch 毫秒时间戳配合 query
• Pro功能门槛：漏斗、留存、热图、实时读取等核心增长功能需付费，免费层遇到 PRO_REQUIRED 会中断分析流
• CLI版本锁定：强制 pinned 0.5.20 版本，自动更新可能带来行为变化

适合人群

• 希望用自然语言驱动数据分析的Agent开发者与产品经理
• 运营多项目、需要批量监控而非逐个登录仪表板的增长团队
• 追求"对话即分析"闭环的AI原生工作流构建者
• 需要中英双语支持的中国市场团队

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| 授权凭证泄露 | 分离式授权需传递 finish code，存在截获风险 | 使用 `--detached` 不轮询，用户人工确认后再交换 |

| 配置持久化失败 | 沙箱环境 `/home` 路径可能重置 | 显式设置 `AGENT_ANALYTICS_CONFIG_DIR` 到工作区 |

| 过度埋点 | 忽略 `scan` 建议导致数据噪音 | 严格执行"分析优先"策略，仅安装高优先级事件 |

| 付费阻断 | 免费层分析中途遇 `PRO_REQUIRED` | 提前说明限制，使用 `upgrade-link --detached` 优雅降级 |

| JSON注入 | `--filter` 接受原始JSON，构造不当可能异常 | 禁止直接拼接用户输入，使用固定命令优先 |

安全等级评估

• S（高）：MIT开源可审计，OAuth不暴露长期API密钥，无PII强制收集，CLI为只读/写入分析数据不涉及代码执行。主要风险集中于配置路径权限管理与用户侧的过滤参数构造。

Agent Analytics是一款面向AI Agent设计的端到端增长分析自动化工具，由GitHub组织Agent-Analytics官方维护，采用MIT开源协议。该Skill本身为纯文档型包装器，核心价值在于通过标准化提示词引导Agent调用官方发布的@agent-analytics/cli命令行工具，实现无需人工干预的闭环分析工作流。

核心用法

Skill采用严格的"分析优先"安装策略。首次使用时，Agent需先执行npx --yes @agent-analytics/cli@0.5.20 scan <url> --json对目标网站进行智能分析，获取minimum_viable_instrumentation建议清单。随后通过login --detached完成OAuth浏览器授权（在OpenClaw等Issue型运行时采用分离式授权+完成码回传的异步模式），创建项目后仅安装高优先级事件，并验证首个有效事件的数据上报。日常分析支持项目列表查询、全站统计、事件明细、属性拆解、用户路径、漏斗转化、留存队列、热力图和实验管理等完整功能栈。

显著优点

第一，零仪表盘操作：Agent可在对话循环中完成从埋点设计到实验分析的全流程，真正实现"对话即分析"。第二，智能分析优先：scan命令基于网站结构输出个性化埋点建议，避免过度追踪和通用事件泛滥。第三，多项目批处理能力：支持跨项目数据聚合，适合SaaS多租户或矩阵产品场景。第四，中文本地化支持：文档、安装指南和CLI输出均提供中文支持，适配国内团队需求。第五，项目上下文记忆：通过context get/set实现分析知识的持久化沉淀，让后续Agent对话越用越准。

潜在缺点与局限性

首先，功能分层限制：漏斗、留存、会话路径、实时读取等深度分析需要Pro付费层级，免费层仅支持10万事件/月和基础读取。其次，查询能力边界：query命令不支持按任意properties.*字段分组，复杂归因分析需反馈产品团队而非即时解决。第三，时间窗口限制：API不支持小时级简写（如24h），精确滚动窗口需手动计算epoch时间戳构造filter JSON。第四，CLI版本锁定：Skill固定引用0.5.20版本，需手动更新以获得新功能或安全修复。

适合的目标群体

• 增长产品经理：需要快速验证假设、迭代实验而无需等待数据团队排期
• 全栈开发者/SaaS创始人：希望为产品内嵌自动化分析能力，减少第三方仪表盘切换成本
• AI Agent开发者：构建闭环Agent工作流（监控→分析→实验→迭代）的核心基础设施
• 多项目运营团队：管理多个子产品或落地页，需要批量视角而非单点仪表盘

常规使用风险

依赖项风险：运行时依赖npx和Node.js环境，且需从npm动态下载@agent-analytics/cli，网络不稳定或npm registry访问受限时可能失败。认证持久化风险：在OpenClaw等托管运行时中，需显式设置AGENT_ANALYTICS_CONFIG_DIR指向工作区持久化路径，否则认证状态可能随会话丢失。数据隐私考量：追踪代码会收集页面浏览、点击事件、UTM来源等用户行为数据，需确保网站隐私政策合规。版本漂移风险：固定版本策略虽保证稳定性，但可能错过官方安全更新，建议关注上游CLI版本发布。误操作风险：context set为全量替换而非增量更新，未先读取现有上下文可能导致配置丢失。