核心用法
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为只读/写入分析数据不涉及代码执行。主要风险集中于配置路径权限管理与用户侧的过滤参数构造。