核心用法
Agent Analytics 是一款面向 AI 构建者的无头化（Headless）分析管理工具，专为跨多终端（multi-surface）产品设计的增长运营基础设施。安装后，AI Agent 可直接通过命令行、对话或代码工作流完成：项目创建、跟踪代码埋设、多终端对比、数据查询、增长分析与实验运行等全流程操作。
典型工作流：
1. 身份验证：npx --yes @agent-analytics/cli@0.5.28 login [--detached]
2. 项目创建/识别：create <project> --domain <origin>
3. 埋点安装：将 CLI 返回的跟踪代码片段嵌入页面
4. 自定义事件配置：基于产品流程添加有意义的决策级事件（如 signup_completed、first_event_received）
5. 数据验证：events <project> --event <event_name> --days 7
6. 增长分析：使用 funnel、retention、paths、experiments 等命令诊断瓶颈
关键命令体系：
- 项目层：
projects、create、stats、insights、context get/set - 行为分析：
events、breakdown、pages、paths、funnel、retention - 实验增长：
experiments list/create - 组合管理：
portfolios list/create（跨项目身份关联）
显著优点
1. AI-Native 设计哲学：区别于传统 BI 工具需要人工操作仪表盘，Agent Analytics 将完整分析能力暴露为 CLI/API，天然适配 Agent 自动化工作流，支持子代理委托（delegation）并行处理多终端增长审计。
2. 终端-项目-组合三级架构：清晰区分 Surface（展示终端）、Project（学习单元）、Portfolio（跨项目增长系统），避免多域名/子域名场景的模型混乱，支持复杂的跨项目身份拼接（data-link-domains + portfolio 配置）。
3. 隐私优先的身份机制：aa.identify() 使用稳定非邮箱用户 ID，原始邮箱仅通过 HTTPS 传输用于服务端 HMAC 索引计算，不存储于事件行或特征中；支持邮箱模糊查询但绝不回显敏感值。
4. 上下文持久化记忆：通过 context set/get 存储产品目标、激活事件定义、事件术语表与业务注解，实现"自改进"的分析循环——每次分析基于历史上下文，发现的新认知即时回写。
5. 执行策略严格锁定：强制使用固定版本 CLI（@agent-analytics/cli@0.5.28），禁止原始 HTTP/curl/MCP 替代，确保行为可预测、可审计、可复现。
潜在缺点与局限性
1. 免费层能力受限：10万事件/月、2 项目上限；漏斗、留存、会话路径、长周期历史查询等核心增长功能需 Pro 订阅（PRO_REQUIRED 阻断）。
2. 查询能力边界：query 命令的 --filter 仅支持有限字段（event、user_id、date、country、session_id、timestamp）；group_by 不支持任意 properties.* 字段，复杂归因分析需反馈申请或手动聚合。
3. 时间窗口限制：不支持 24h 等小时级简写，精确滚动窗口需手动计算时间戳并构造 JSON 过滤器。
4. 委托并发约束：Hermes 默认 max_concurrent_children=3，四工作流并行需分批或显式提升限制。
5. 中文生态适配：虽然提供中文文档，但核心 CLI 输出、事件命名、术语体系仍为英语优先，国内团队需额外对齐命名规范。
适合人群
- AI 优先的产品团队：使用 Claude Code、Codex、Cursor、OpenClaw 等 Agent 环境进行日常开发
- 多终端产品构建者：同一产品覆盖主站、文档、博客、落地页、免费工具、移动端的复杂场景
- Portfolio 运营者：管理多个相关产品的增长系统，需要跨项目身份识别与组合分析
- Headless 自动化需求：希望将分析工作流嵌入 CI/CD、定时任务、Issue 工作流而非人工仪表盘
常规风险
| 风险类型 | 描述 | 缓释措施 |
|---------|------|---------|
| **版本漂移** | 未锁定 CLI 版本导致行为不一致 | 强制使用 `@0.5.28` 固定版本 |
| **过度采集** | 默认埋点外盲目添加自定义事件 | 遵循"最小有意义事件"原则，禁止为自动采集信号（页面浏览、设备、UTM 等）添加重复事件 |
| **身份泄露** | 错误配置导致邮箱/用户 ID 暴露 | CLI 绝不回显原始邮箱或 HMAC 值；禁止在 `context` 中存储 PII |
| **跨域身份断裂** | 多域名场景未配置 `data-link-domains` 和 portfolio | 显式配置双端身份传递机制 |
| **授权凭证泄露** | 要求用户粘贴 API Key 或 secret 到对话 | 默认浏览器授权，Detached 模式下仅用 finish-code，禁止 API Key 方式 |
| **因果误读** | 将相关性推断为因果，或将漏斗流失直接归因于某步骤 | 强制标注"identity basis""conversion window""caveat"等限定条件，实验结果需检验 guardrail 与统计显著性 |