agent-analytics

Agent Analytics — Agent 真正能用的分析工具

你正在使用 Agent Analytics 添加分析跟踪——这是一个 AI Agent 真正能用的分析平台。它专为需要交付大量项目，并希望 AI Agent 能够跨项目跟踪、分析、实验和优化的开发者打造。

网站： agentanalytics.sh GitHub： Agent-Analytics/agent-analytics 文档： docs.agentanalytics.sh

何时使用此技能

• 用户想为网站或应用添加分析跟踪
• 用户想查看项目表现如何（流量、转化、参与度）
• 用户想对标题、CTA 或流程进行 A/B 实验
• 用户想分析漏斗、留存群组或流量细分
• 用户询问“我的网站表现如何？”或“有人访问吗？”

理念

你不是 Mixpanel。不要跟踪所有内容。只跟踪能回答这个问题的内容：“这个项目是否仍在运行并持续增长？”

对于典型网站，除了自动记录的页面浏览量，最多添加 3–5 个自定义事件即可。

首次设置

获取 API 密钥： 在 agentanalytics.sh 注册，然后从控制面板生成密钥。或者，从 GitHub 自托管开源版本。

如果项目尚未设置跟踪：

# 1. Login (one time — uses your API key)
npx @agent-analytics/cli login --token aak_YOUR_API_KEY

# 2. Create the project (returns a project write token)
npx @agent-analytics/cli create my-site --domain https://mysite.com

# 3. Add the snippet using the returned token
# 4. Deploy, click around, verify:
npx @agent-analytics/cli events my-site

create 命令会返回一个项目写入令牌，请在代码片段中将其用作 data-token。它与 API 密钥不同，API 密钥用于读取和查询数据。

步骤 1：添加跟踪代码片段

create 命令会返回包含项目令牌的跟踪代码片段，请将其添加到 </body> 之前。它会自动跟踪 page_view 事件，并记录路径、来源页、浏览器、操作系统、设备、屏幕尺寸和 UTM 参数。你无需添加自定义 page_view 事件。

步骤 1b：查看现有事件（已有项目）

如果已经设置了跟踪，请查看正在使用的事件和属性键，以便采用一致的命名方式：

npx @agent-analytics/cli properties-received PROJECT_NAME

步骤 2：为重要操作添加自定义事件

在重要元素上使用 onclick 处理程序：

<a href="..." onclick="window.aa?.track('EVENT_NAME', {id: 'ELEMENT_ID'})">

适用于 80% SaaS 网站的标准事件

选择适用的事件。大多数网站需要 2–4 个：

事件	触发时机	属性
cta_click	用户点击行动号召按钮	id（按钮标识）
signup	用户创建账户	method（github/google/email）
login	用户返回并登录	method
feature_used	用户使用核心功能	feature（功能名称）
checkout	用户开始支付流程	plan（free/pro 等）
error	出现可见错误	message、page

不要跟踪的内容

• 每个链接或按钮（噪声太多）
• 滚动深度（无法采取有效行动）
• 表单字段交互（过于细粒度）
• 页脚链接（信号较弱）

属性命名规则

• 使用 snake_case：用 hero_get_started，不要用 heroGetStarted
• id 属性用于标识具体元素：简短且具有描述性
• 使用 section_action 的格式命名 ID：hero_signup、pricing_pro、nav_dashboard

步骤 2b：运行 A/B 实验

实验可用于测试页面元素的哪个变体转化效果更好。完整生命周期由 API 驱动，无需使用控制面板界面。

创建实验

npx @agent-analytics/cli experiments create my-site \
  --name signup_cta --variants control,new_cta --goal signup

实现变体

声明式（推荐）： 使用 data-aa-experiment 和 data-aa-variant-{key} HTML 属性。原始内容为对照组。跟踪器会自动将文本替换为分配的变体。

<h1 data-aa-experiment="signup_cta" data-aa-variant-new_cta="Start Free Trial">Sign Up</h1>

编程式（复杂场景）： 使用 window.aa?.experiment(name, variants)——结果具有确定性，同一用户始终会获得相同变体。

查看结果

npx @agent-analytics/cli experiments get exp_abc123

会返回贝叶斯指标 probability_best、lift 和 recommendation。系统需要每个变体约 100 次曝光后，结果才具有统计显著性。

步骤 3：立即测试

添加跟踪后，请验证其是否正常工作：

# Click around, then check:
npx @agent-analytics/cli events PROJECT_NAME
# Events appear within seconds.

CLI 参考

所有命令均使用 npx @agent-analytics/cli：

# Setup
login --token aak_YOUR_KEY           # Save API key (one time)
projects                              # List all projects
create my-site --domain https://...   # Create project

# Real-time
live                                  # Live TUI dashboard across ALL projects
live my-site                          # Live view for one project

# Analytics
stats my-site --days 7                # Overview: events, users, daily trends
insights my-site --period 7d          # Period-over-period comparison
breakdown my-site --property path --event page_view --limit 10  # Top pages/referrers/UTM
pages my-site --type entry            # Landing page performance & bounce rates
sessions-dist my-site                 # Session engagement histogram
heatmap my-site                       # Peak hours & busiest days
events my-site --days 30              # Raw event log
sessions my-site                      # Individual session records
properties my-site                    # Discover event names & property keys
funnel my-site --steps "page_view,signup,purchase"  # Funnel drop-off
retention my-site --period week --cohorts 8         # Cohort retention

# A/B experiments
experiments list my-site
experiments create my-site --name signup_cta --variants control,new_cta --goal signup
experiments get exp_abc123
experiments complete exp_abc123 --winner new_cta

不同问题应使用哪个端点

用户提问	调用	原因
“我的网站表现如何？”	insights + breakdown + pages（并行）	全面的每周概览
“现在有人访问吗？”	live	所有项目的实时访客
“哪些页面最热门？”	breakdown --property path --event page_view	按排名排列的页面列表
“流量来自哪里？”	breakdown --property referrer --event page_view	引荐来源
“用户真的在参与互动吗？”	sessions-dist	跳出与参与情况的划分
“什么时候部署比较合适？”	heatmap	找出流量较低的时段
“用户在哪里流失？”	funnel --steps "page_view,signup,purchase"	逐步转化情况
“用户会回来吗？”	retention --period week --cohorts 8	群组留存情况
“哪个 CTA 的转化效果更好？”	experiments create + experiments get	A/B 测试生命周期

对于任何“X 表现如何”的问题，务必先调用 insights——这是最有用的单一端点。

示例

通过 window.aa?.track() 跟踪自定义事件：

window.aa?.track('cta_click', {id: 'hero_get_started'});
window.aa?.track('signup', {method: 'github'});
window.aa?.track('feature_used', {feature: 'create_project'});
window.aa?.track('checkout', {plan: 'pro'});

此技能不提供的功能

• 没有 GUI 仪表盘——你的 Agent 就是仪表盘（也可以使用 live 查看实时 TUI）
• 不提供用户管理或账单功能
• 不存储 PII——不会记录或保留 IP 地址。设计上优先保护隐私