Agent Analytics

核心用法

Agent Analytics 是一个面向 AI 构建者的无头分析管理工具，让 Agent 能够通过 CLI 直接操作分析全流程：创建项目、安装追踪代码、对比多站点、查询数据、运行实验和增长分析。核心入口为 npx --yes @agent-analytics/cli@0.5.21 <command>。

关键工作流：

• 分析优先安装：先扫描网站获取 minimum_viable_instrumentation 和 current_blindspots，再精准安装高优先级事件，避免过度追踪
• 多表面产品支持：适用于主站、文档、博客、引导流程、免费工具等多触点场景
• 项目上下文管理：通过 context get/set 存储激活定义、业务目标和事件词汇表，实现跨会话的智能分析
• 子代理委托：支持将增长审计拆分为多个独立工作流（获取、激活、内容、验证），由父代理综合结果

显著优点：

• 专为 AI Agent 设计，支持代码/聊天/终端三种交互模式
• 无需 API Key，浏览器授权即可使用
• 免费层包含 10 万事件/月、2 个项目
• 提供网站扫描能力，在安装前识别数据盲区
• 中英文文档支持，适配 OpenClaw 等托管运行时

潜在缺点与局限：

• 高级功能（漏斗、留存、会话路径、实验、长周期数据）需 Pro 订阅
• query 命令的 --filter 需手动构造 JSON，存在注入风险
• 不支持按任意属性分组（如 properties.utm_source），复杂归因分析受限
• 依赖 npx 和网络连接，离线环境不可用
• 多项目手动聚合需多次 CLI 调用

适合人群：

• 运营多产品/多站点的独立开发者或小团队
• 希望用自然语言或代码驱动分析流程的 AI 优先团队
• 需要闭环 Agent 工作流（监控→分析→实验→迭代）的构建者

常规风险：

• 需警惕 --filter JSON 构造不当导致的安全问题
• 代理运行时需配置持久化路径存储认证状态，避免重复登录
• 扫描功能仅限用户自有站点，禁止用于未授权网站分析
• 项目命名需符合 ^[a-zA-Z0-9._-]{1,64}$ 正则，避免非法字符

核心用法

Agent Analytics 是一款面向 AI 构建者的无头化（headless）分析管理工具，专为多产品、多表面（multi-surface）场景设计。用户可通过代码、对话或终端三种交互方式，让 Agent 自主完成分析项目创建、追踪代码安装、跨表面数据对比、查询结果解读及增长实验分析等全流程操作。

该 Skill 的核心工作流遵循「分析优先」原则：在创建项目前，先通过 scan 命令对目标站点进行深度扫描，识别当前数据盲区（blindspots）与最小可行埋点方案（minimum viable instrumentation），再基于扫描结果精准安装追踪代码，避免过度采集或冗余事件定义。

主要命令覆盖四大能力域：

• 项目管理：create、projects、context get/set 等，支持多项目组合管理与上下文记忆
• 数据采集：scan 驱动埋点建议、events、properties 验证事件上报
• 分析洞察：stats、insights、breakdown、paths、funnel、retention 等固定查询
• 实验增长：experiments create/list 支持完整 A/B 测试生命周期

显著优点

1. Agent 原生设计：命令结构与输出格式专为 AI Agent 消费优化，支持 JSON 输出与上下文传递，便于自动化流水线集成
2. 多表面统一治理：单一项目可覆盖主站、文档、定价页、演示环境等多元触点，解决构建者常见的「产品矩阵」管理痛点
3. 扫描驱动的精准埋点：通过网站扫描生成数据缺口报告，避免「先埋点再想指标」的反模式，显著降低数据采集的技术债
4. 委托执行支持：内置子 Agent 委派模式（delegation），可将增长审计拆分为并行任务（如获客表面、激活表面、内容表面），提升复杂分析效率
5. 合规与隐私友好：自动采集页面浏览、来源、UTM、设备、会话等标准字段，避免重复定义；支持 GDPR/CCPA 合规的数据最小化原则

潜在缺点与局限性

1. 免费层功能受限：漏斗分析、留存计算、实验功能、更长历史数据查询等进阶能力需要 Pro 订阅（PRO_REQUIRED 提示）
2. 查询灵活性边界：group_by 仅支持内置字段（event/date/user_id/session_id/country），无法直接按任意属性（如 properties.first_utm_source）分组，复杂归因分析需手动聚合
3. CLI 版本锁定依赖：Skill 强制要求使用固定版本 CLI（@agent-analytics/cli@0.5.21），若上游 npm 包出现安全更新或功能变更，Skill 文档可能滞后
4. 认证流程的交互成本：--detached 登录模式需用户完成浏览器授权并回复 finish code，在纯自动化场景（如 CI/CD）中仍需人工介入
5. 中文生态尚处早期：虽有中文文档支持，但社区案例、第三方集成教程仍以英文为主

适合人群

• 多产品技术创业者：同时运营主产品、文档站、营销落地页，需要统一的增长数据视图
• AI-Native 开发团队：希望将分析工作流嵌入 Agent 对话或代码生成流程，而非传统 BI 工具的人工操作
• 增长工程师/产品经理：追求「埋点即策略」的精准数据采集，厌倦「全埋点」后的数据治理噩梦
• OpenClaw/Codex 等 Agent 运行时用户：需要符合特定认证模式（detached login）与执行策略的合规分析工具

常规风险

• 上游 CLI 供应链风险：Skill 本身为纯 Markdown 文档（T-MD），无执行代码，但实际功能依赖 npm 分发的 @agent-analytics/cli，需关注该包的供应链安全
• 数据主权与合规：虽然 Skill 无敏感数据硬编码，但用户在实际使用中需确保 AGENT_ANALYTICS_CONFIG_DIR 路径的访问控制，避免配置泄露
• 版本漂移风险：CLI 版本锁定策略虽保证稳定性，但也可能错过安全补丁；建议用户在关键版本更新后主动触发 Skill 重新认证
• 过度委托的复杂度：子 Agent 委派模式虽提升效率，但若任务边界划分不清（如跨项目数据聚合），可能导致重复计算或上下文丢失