跳转到内容

Skill、MCP 与 API

Agent Analytics 通过四种真实访问路径暴露同一套分析界面:

  • Skill 适用于已经支持 skills 且能执行命令的代理环境
  • MCP 适用于原生聊天或原生编辑器工具调用
  • CLI 适用于 shell 导向的代理工作流
  • API 适用于直接控制 HTTP

产品模型不会因为入口不同而变化。项目、分析读取和实验操作都保持一致;变化的只是最自然的入口方式。

环境 推荐路径 原因
Claude Code Skill 优先 保持 agent-native workflow,不强依赖原始 MCP
Claude Desktop / Cowork Hosted MCP 最适合 connector 风格聊天工具的原生 tool call
OpenWork Skill 优先 最适合同一应用内需要本地 skill、自动化及可选 MCP 的情况
Cursor Skill + CLI 优先 当代理已经能执行命令时,通常比 MCP 开销更低
ChatGPT (Codex) 托管 MCP 或 skill + CLI ChatGPT 里的编码代理。原生工具调用或终端工作流;参见 ChatGPT (Codex)
ChatGPT Settings 中的托管 MCP ChatGPT 应用在 Settings、Plugins 下添加自定义 MCP。参见英文指南
OpenClaw Skill 优先 在聊天里跑定时分析 workflow 的最干净路径
Grok Bot 托管 MCP 在聊天中连接 https://mcp.agentanalytics.sh/mcp。Agent Analytics 不在 Connect Apps 目录中。参见英文指南
Instinct 托管 MCP 在聊天中连接 https://mcp.agentanalytics.sh/mcp,并用 Google 或 GitHub 登录。运行环境无法调用 MCP 时,用 CLI 作为后备。参见英文指南
Custom runtime 或内部代理 API 最适合自己掌控重试、解析和编排的场景

当你的代理已经支持 skills,并且能在同一环境里执行命令时,使用 skill。

Skill 通常最适合以下情况:

  • 你想给常见分析任务加上一层引导式 workflow
  • 你的代理已经有终端访问能力
  • 你想留在代理自己的原生闭环里,而不是切换到 tool-call 更重的 MCP 流程

当你的代理已经运行在支持 connectors 或 MCP servers 的工具中时,使用 MCP。

MCP 通常最适合以下情况:

  • 你希望安装过程在聊天里显得更原生
  • 你想使用工具调用,而不是 shell 命令
  • 你不想手动拼 auth header 或请求 payload
  • 你想快速获得项目或账户级摘要,并通过结构化工具结果返回

权衡:

  • MCP 往往比 skill + CLI 流程带来更高的延迟和 token 开销,因为模型需要管理更多工具调用往返和工具结果 payload。

当你的代理已经具备终端访问能力并且擅长执行命令时,使用 CLI。

CLI 通常最适合以下情况:

  • 你的代理本来就运行在 shell-first 环境中
  • 你希望得到稳定、可预测的命令输出
  • 你更喜欢组合命令,而不是集成工具
  • 你在像 Cursor 这样的编辑器代理里,希望获得比 MCP 更低的开销
  • 你想使用像 login 和 logout 这样的本地 auth 辅助命令

login --project <name> --level read|manage|admin 请求一个项目和一个级别。默认级别是 read。whoami 打印被授予的项目(名称,All projects 时为 null)和级别(read、manage、admin 或 legacy)。授权只有一个项目时,MCP 工具把这个项目当作默认的 project 参数。客户端如果提供了项目或级别,OAuth 启动请求会带上可选的 project 和 level。404 和 403 以清楚的错误文本返回。

如果你需要安装方式、登录流程、常见命令以及 CLI 到 API 的映射,请继续阅读独立的 CLI 页面。

当你希望完全控制请求、重试策略和响应解析时,使用 API。

API 通常最适合以下情况:

  • 你在自己的代码中集成
  • 你需要精确的 HTTP 级行为
  • 你正在直接调试 auth 或 payload 结构
  • 在 Claude Code、OpenWork、Cursor 或 ChatGPT (Codex) 这类能跑 shell 的环境中,优先选择 skill + CLI。
  • 当代理已经生活在 connector 风格的聊天环境里,并且你希望使用原生 tool calls 时,选择 MCP。Grok Bot 和 Instinct 的推荐路径是托管 MCP。
  • 当你需要完全控制、自定义集成或底层调试时,选择 API。

先用 query。group_by 可以包含 event、date、user_id、session_id、country,以及最多一个 properties.<key>。两个 properties.* 返回 400 INVALID_GROUP_BY。POST /sql 是 Pro。免费账户收到 403 PRO_REQUIRED,该响应不计为读取。每个账户数据库一次只运行一条查询,因此很重的 SQL 会推迟进入的事件。可选 days(默认 7,最多 90),或发送 date_from 和 date_to(YYYY-MM-DD,跨度最多 90 天),日期解析与 POST /query 相同。响应包含 window,其中有 date_from 和 date_to。非法窗口是 400 INVALID_WINDOW。服务器按 date 列过滤 events 和 sessions(date >= ? AND date <= ?,含首尾的 UTC 日,使用 idx_events_project_date 和 idx_sessions_project_date)。events 和 sessions 各自最多引用一次。允许一次 events 与 sessions 的连接。不允许表与自身连接。递归 CTE 会被拒绝(400 INVALID_SQL)。FROM、JOIN 或 IN 之后只允许 events、sessions、CTE 名称,或括号中的子查询或列表。LIMIT 必须是纯整数。randomblob 和 zeroblob 会被拒绝。数据库返回的 SQL 错误是 400 INVALID_SQL。自行托管的 rows 与托管版一样是对象。托管版上,第二条正在运行的查询是 429 SQL_BUSY,并带 Retry-After(租约在 15 秒后过期)。HTTP 超时为 10 秒(504 SQL_TIMEOUT),查询仍可能在数据库内完成。每账户每分钟最多 10 次(429 RATE_LIMITED,reason 为 sql_rate_limit)。一次读取超过 5,000,000 行会阻断该账户的 /sql 60 秒(429 SQL_COOLDOWN,带 Retry-After)。每月预算仍是 100,000,000 行读取(429 SQL_BUDGET)。expensive 仍在超过 1,000,000 行时为真。Cloudflare D1 API 返回 429 时,响应是 429 SQL_UPSTREAM_RATE_LIMITED,并带 Retry-After(采用 Cloudflare 的值,否则为 60)。该调用不会重试,且只在托管版出现。自行托管只应用时间窗口、各自最多一次表引用,以及超时。

  • CLI:aa sql <project> --sql '...' 或 aa sql <project> -f file.sql
  • MCP:run_sql。不在 demo MCP 中。先用 query 或 analytics_breakdown。
  • API:POST /sql

POST /vitals 和 GET /vitals 是 Pro 读取。免费账户收到 403 PRO_REQUIRED,该响应不计为读取。一次成功响应计为一次读取。事件是 page_view。p75 是标题数字。

  • CLI (@agent-analytics/cli@0.5.41):npx --yes @agent-analytics/cli@0.5.41 vitals <project> [--days N] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--by device|path] [--limit N] [--json]
  • MCP:web_vitals,参数为 project、days、date_from、date_to、group_by、limit
  • API:POST /vitals 或 GET /vitals

托管版把 cwv_* 存在 page_view 上。自行托管的 core 把同样的键存在 $web_vitals 上。CLS 和 INP 只在 Chromium 中采集,其他浏览器上该键不存在,也不是 0。见 Web 指标。

每次请求一个主体,所有套餐都可用。擦除需要 manage 或 admin。erasures:write 包含在 manage 和 admin 中,不包含在 read 中。旧账户密钥(aak_*)不能擦除。项目密钥(aapk_*)在 manage 或 admin 时可以擦除,并且只能擦除它所属的那一个项目。旧会话保留已保存的 scopes。每个账户每小时可以接受 20 次擦除。已擦除 id 的迟到事件会在 7 天内被丢弃。审计行将哈希保留 24 个月。哈希仍然是标识符。

  • CLI:aa erase <project> --user-id <id> --confirm erase,或 --session-id,或 --email。aa erasures <project> 和 aa erasures get <id>。级别不够时,命令会打印一句清楚的提示。whoami 打印项目和级别。
  • MCP:erase_subject。readOnlyHint 为 false,destructiveHint 为 true。必须传入 confirm erase。仅在 manage 或 admin(会话包含 erasures:write)时注册。demo MCP 中没有该工具。
  • API:POST /erasures

参见 Subject erasure。