Skill、MCP 与 API
Agent Analytics 通过四种真实访问路径暴露同一套分析界面:
Skill适用于已经支持 skills 且能执行命令的代理环境MCP适用于原生聊天或原生编辑器工具调用CLI适用于 shell 导向的代理工作流API适用于直接控制 HTTP
产品模型不会因为入口不同而变化。项目、分析读取和实验操作都保持一致;变化的只是最自然的入口方式。
按环境推荐的路径
Section titled “按环境推荐的路径”| 环境 | 推荐路径 | 原因 |
|---|---|---|
| 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 | 最适合自己掌控重试、解析和编排的场景 |
何时使用哪一种路径
Section titled “何时使用哪一种路径”当你的代理已经支持 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 结构
快速经验法则
Section titled “快速经验法则”- 在 Claude Code、OpenWork、Cursor 或 ChatGPT (Codex) 这类能跑 shell 的环境中,优先选择
skill + CLI。 - 当代理已经生活在 connector 风格的聊天环境里,并且你希望使用原生 tool calls 时,选择
MCP。Grok Bot 和 Instinct 的推荐路径是托管 MCP。 - 当你需要完全控制、自定义集成或底层调试时,选择
API。
按属性分组和只读 SQL
Section titled “按属性分组和只读 SQL”先用 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
Web 指标
Section titled “Web 指标”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。必须传入confirmerase。仅在manage或admin(会话包含erasures:write)时注册。demo MCP 中没有该工具。 - API:
POST /erasures
参见 Subject erasure。
