Agent Analytics

核心用法

Agent Analytics 是一款专为AI Agent设计的CLI优先分析工具，通过npx @agent-analytics/cli@0.5.16命令即可完整操作。核心能力包括：

1. 智能分析先行：scan命令自动分析网站结构，输出minimum_viable_instrumentation推荐，避免过度追踪
2. 闭环工作流：项目创建→追踪代码部署→事件验证→查询分析→实验迭代，全程命令行完成
3. 多维度分析：内置stats、insights、breakdown、funnel、retention、paths等固定命令，覆盖流量、转化、留存、用户路径全场景
4. A/B实验管理：支持实验创建、变体配置、目标事件绑定和结果追踪

显著优点

• Agent原生设计：English-first工作流，支持OpenClaw等托管运行时的分离式认证（--detached），无需API Key即可浏览器授权
• 分析优先策略：拒绝猜测式埋点，scan输出明确告知每个事件解锁的分析能力
• 多项目批量操作：projects列出所有项目后循环查询，适合代理自动化跨项目报表
• 开源透明：CLI完全开源（MIT），100k事件/月的免费托管层
• 中文支持：文档和安装指南提供中文版本

潜在局限

• 时间粒度限制：API不支持24h小时级简写，精确到小时的查询需手动构建时间戳JSON filter
• 属性分组受限：group_by仅支持内置字段（event/date/user_id/session_id/country），无法按任意properties.*字段分组，需反馈请求而非手动实现
• 复杂filter风险：--filter接受原始JSON，存在注入和构造错误风险，文档明确禁止直接传递用户原始文本
• MCP/HTTP非主流路径：官方强制CLI优先，其他传输方式需用户显式请求

适合人群

• 需要闭环自动化分析的Agent开发者和增长团队
• 运营多项目矩阵、厌倦逐个仪表盘切换的工程师
• 追求最小可行埋点、拒绝数据垃圾的精益团队
• 使用OpenClaw、Codex等托管Agent运行环境的用户

常规风险

• 认证安全：需正确配置AGENT_ANALYTICS_CONFIG_DIR避免凭证泄漏，.openclaw/目录必须gitignore
• 版本锁定：强制@0.5.16精确版本，避免自动升级带来的行为漂移
• filter构造：手动JSON filter易出错，优先使用固定命令
• 会话边界误解：paths命令仅限单会话内路径，不适用于跨会话归因分析

核心功能

Agent Analytics 是一款专为 AI 代理设计的纯文档型分析工具 Skill，让代理能够在不打开传统仪表板的情况下完成端到端的增长分析工作流。通过封装官方 CLI (npx @agent-analytics/cli@0.5.16)，代理可直接执行项目创建、埋点配置、数据查询、漏斗分析、留存计算和 A/B 实验等全套操作。

显著优点

1. Agent-First 设计：专为对话式 AI 工作流优化，支持"分析-埋点-验证-迭代"的闭环自动化，无需人工切换上下文
2. 智能埋点分析：内置 scan 命令可自动分析网站结构，输出 minimum_viable_instrumentation 建议，避免过度追踪
3. 安全授权机制：默认采用浏览器 OAuth 或 --detached 分离式授权，避免 API Key 硬编码；支持 Paperclip/OpenClaw 等 issue-based 运行时的异步登录流程
4. 多项目批量管理：代理可通过 projects 命令遍历所有项目，执行聚合查询，突破传统 SaaS 的单仪表板限制
5. 中英双语支持：文档和安装指南提供中文版本，适合中国团队使用
6. 供应链安全：固定 CLI 版本号 (@0.5.16)，避免 npm 包的供应链攻击风险

潜在局限

• 功能边界依赖 CLI：Skill 本身无可执行代码，所有功能受限于官方 CLI 版本能力；高级需求需通过 feedback 命令反馈
• 分组能力受限：query 命令仅支持 event/date/user_id/session_id/country 等内置字段分组，无法直接按 properties.first_utm_source 等任意属性分组，复杂归因分析需手动聚合
• 实时性限制：--days 参数仅支持整天粒度，精确到小时的滚动窗口需自行计算 Unix 时间戳构建 --filter JSON
• 网络依赖：需稳定访问 api.agentanalytics.sh 和 npm registry，离线环境不可用

适合人群

• AI 原生团队：已采用 OpenClaw、Codex 或类似 agent runtime 的开发者
• 增长/数据分析师：希望将重复性分析任务（如每日漏斗检查、多项目数据汇总）自动化的从业者
• 中国出海团队：需要中英文双语支持，且希望代理直接操作分析基础设施的国际化团队
• 安全敏感组织：偏好 OAuth 授权、避免硬编码密钥的企业环境

常规风险

| 风险类型 | 评估 | 说明 |

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

| 代码执行风险 | **极低** | 纯文档型 Skill，无本地代码执行 |

| 供应链风险 | **低** | 固定版本 CLI + 官方 npm 组织，但仍依赖 npx 运行时 |

| 数据隐私风险 | **低** | 数据发送至官方托管服务 (agentanalytics.sh)，免费版含 100k 事件/月限额 |

| 授权泄露风险 | **极低** | 推荐 OAuth 流，Token 存储于隔离目录，文档明确禁止提交至 Git |

| 误操作风险 | **中** | `--filter` JSON 构造复杂，文档明确警告"勿将原始用户文本直接传入" |

使用建议

严格遵循"分析优先"策略：先执行 scan 获取埋点建议，再按 minimum_viable_instrumentation 实施，最后通过 events 命令验证数据流入。避免预装通用事件（如 generic click、signup），确保每个埋点都服务于可回答的具体业务问题。