analyga

analyga

面向 Agent 的 MCP + Web 流量分析——从终端或 MCP 客户端查询、埋点和配置。无需浏览器，也无需仪表板。

仪表板是给人看的。tga 是给 Agent 用的。

一个分析界面，覆盖现代流量的两部分：网站仍然获得的 Web 访问，以及日益推动网站发展的 Agent/MCP 调用。分析工具通常假设有人正盯着图表看，但越来越多时候，需要数据的是 Agent：它触发了事件，想知道事件是否成功记录，还想拿到五个数字，而不是一个需要渲染的仪表板。analyga 为 Agent 提供了一个可自行驱动的界面：安装一次，就能跨 Web 和 MCP 查询统计数据和漏斗、发送服务端事件，并读取自身架构——全部以结构化 JSON 呈现，无需抓取屏幕内容。

适用于： Claude Code · Cursor · Cline · Windsurf · Aider · Codex · 任意 MCP 客户端

一个 Agent，一个终端——60 秒内从查询到漏斗。观看完整演示。

实际演示

没有模型图——每段视频都是通过预置租户运行的实时 tga 会话。点击任意 GIF 即可观看完整分辨率视频。

查询 → 漏斗	Agent 自助注册	服务端数据接入
一个 Agent，一个终端，60 秒	无密钥引导——无需管理员介入	使用稳定的 --id 发送事件

MCP 客户端	人类使用的仪表板
Claude Code / Cursor 中的 13 个原生工具	Agent 捕获的所有内容，都集中在一个实时 UI 中

安装

npm install -g analyga

npm 包名为 analyga；命令为 tga。

快速开始

# No account yet? Create a tenant and its first key — no card, no admin in the loop
tga signup --slug acme --name "Acme" --username you --password <8+ chars>

# Point at a tenant
tga login --key <your-api-key>     # or set ANALYGA_KEY

# Confirm WHICH tenant you are about to write to (shows tenant + key scope for a tga_ key)
tga whoami

# What can this credential see?
tga websites

# Five numbers, not a dashboard
tga stats <websiteId> --from 7d

# Full reference
tga --help

每条命令都支持 --json——机器接口是一等功能，而非事后补充：

tga stats <websiteId> --from 7d --json

查阅契约，不要猜标志

tga agent-schema --json

它会返回所有命令、参数、标志、类型、是否为只读，以及完整的错误代码列表——内容由驱动解析器、帮助文本和 MCP 工具的同一张表生成，因此不会与 CLI 的实际行为不一致。架构中没有的功能，就不存在。

查询——统计数据、事件、漏斗

询问 Agent 发布后真正关心的问题：事件是否成功记录？有没有人走完整个流程？

# Traffic and top-line stats for a window
tga stats <websiteId> --from 7d
tga events <websiteId> --from 24h

# Define a funnel once, then run it whenever
tga funnel define <websiteId> --name signup --steps "/,/pricing,/signup"
tga funnel list <websiteId>
tga funnel run <funnelId> --from 30d

# Cross-site rollup for a team
tga network <teamId> --from 7d

全部只读，全部支持 --json——Agent 可以根据数字采取不同操作，而不必解析图表。

身份标识 — 传入 --id，否则你的 Agent 会合并成一个访客

匿名身份根据 IP 和用户代理生成。Agent 流量会共用两者：同一个 CLI 版本意味着同一个用户代理，而且 Agent 往往共用一个出口 IP，因此如果没有稳定的 ID，该 IP 后面的所有 Agent 都会合并成一个访客。 无法事后补录。

tga send <websiteId> --name cli_signup --id <stable-user-id> --data '{"source":"cli"}'

在服务端发送事件

# Mint a per-website ingest key first (shown ONCE; regenerating rotates it)
tga ingest-key create <websiteId>

tga send <websiteId> --name cli_signup --id <stable-user-id> \
  --ingest-key <per-site-key> --data '{"plan":"pro"}'

tga ingest health <websiteId> --from 24h    # did anything actually land?

tga ingest-key revoke <websiteId>           # kill server-side ingest for this site

被丢弃的事件仍会返回 HTTP 200。 如果摄取端点将事件作为机器人流量丢弃，就会返回 {"beep":"boop"}。此 CLI 会将其视为带提示的严重失败，而不是报告成功，因此 Agent 不会误以为被丢弃的事件已成功发送。

服务端摄取使用单独的网站级密钥（ANALYGA_INGEST_KEY 或 --ingest-key），密钥仅限一个网站使用，因此只能写入该网站的流量。使用 tga ingest-key create <websiteId> 创建密钥，并使用 tga ingest-key revoke <websiteId> 撤销密钥——明文只显示一次，系统仅存储其哈希值。

账单 — 将结账 URL 交给人工处理

Agent 使用其租户密钥进行身份验证，指定套餐，然后获取一个 Stripe Checkout URL，交给完成付款的人工：

tga billing checkout --plan pro

租户由服务端根据密钥固定。免费套餐（以及任何未配置价格的套餐）不可购买，内部的同系列技术栈租户也永远不会被计费。

MCP 服务

更喜欢使用工具而不是 CLI？analyga 附带 MCP 服务。将 Claude Code（或任何 MCP 客户端）指向该服务，Agent 即可使用 13 个原生工具，涵盖统计数据、事件、漏斗、网站、身份标识、服务端摄取（包括创建和撤销摄取密钥）以及账单结账。

tga mcp-serve        # stdio, for Claude Code / Cursor / Cline / Windsurf

对于使用 JSON 配置的客户端，通过 ANALYGA_KEY 传入密钥。MCP 服务在项目目录之外运行，因此不会读取 .analyga/config.json：

{
  "mcpServers": {
    "analyga": {
      "command": "tga",
      "args": ["mcp-serve"],
      "env": { "ANALYGA_KEY": "your-key" }
    }
  }
}

只读工具会标记为只读，因此客户端不会提示人工确认读取操作。每个工具都声明了一个 outputSchema，Agent 无需解析文本或猜测字段名称；工具结果与 --json 输出是完全相同的字节，让客户端可以在两个入口中通用。未配置密钥的会话只能看到引导入口——了解如何连接，以及用于创建自身租户的 analyga_signup——而无法访问完整工具集。

错误代码

失败会附带稳定的 code 和独立的退出代码，因此 Agent 可以根据结果采取不同操作，而不必匹配错误消息中的字符串。

退出代码	含义	处理方式
2	用法错误	修正调用，不要重试
3	身份验证失败	修正凭据
4	权限不足	不要重试，升级处理
5	未找到	检查 ID
6	验证失败	修正负载
7	速率受限	等待后重试
8	网络错误	可以重试
9	服务端错误	重试一次，然后报告

退出代码 1 专用于未处理的崩溃，因此已分类的失败不会产生歧义。如果服务端能说明接下来该怎么做，就会在单独一行中返回 hint。

配置

按优先级从高到低解析：

1. --key 标志
2. ANALYGA_KEY 环境变量
3. 当前目录中的 .analyga/config.json

tga whoami 会报告最终采用了上述哪一项。在多租户平台上，“我接下来要写入哪个租户”是最重要的问题。.analyga/ 中保存着有效凭据，请勿将其纳入版本控制。

功能

• 自助注册 — tga signup 无需银行卡，也无需管理员介入，即可创建租户和第一个 API 密钥；无需密钥，因此在你拥有凭据之前也能使用
• 感知租户的身份信息 — 对于 tga_ 密钥，tga whoami 会显示固定的租户和密钥权限范围；对于会话登录，则会显示用户和团队
• 统计数据与事件 — 查看任意时间范围内的总体流量和事件数量；所有操作均为只读，且都支持 --json
• 漏斗 — 定义一次，随时运行；查看某个站点逐步转化情况
• 网络汇总 — 查看整个团队跨站点的统计数据
• 服务端数据采集 — 使用限定站点范围的密钥运行 tga send；使用 tga ingest-key create|revoke 创建、轮换或撤销密钥；被判定为机器人而丢弃的事件会明确报错，而不是伪造 200 响应
• 账单结账 — tga billing checkout --plan <id> 会返回 Stripe URL，供你转交给他人
• 稳定身份标识 — --id 可避免多个 Agent 被合并为同一个匿名访客
• agent-schema — 一条命令即可输出完整契约（命令、标志、类型、错误代码），让 Agent 无需猜测
• MCP 服务 — 提供 13 个工具（tga mcp-serve），支持 Claude Code、Cursor、Cline、Windsurf 及任何 MCP 客户端
• 分类错误 — 每种失败类别都有稳定的 code 和独立的退出代码，并提供可执行的 hint

Agent 集成

将以下内容添加到你的 CLAUDE.md、.cursorrules、.clinerules、.windsurfrules 或 AGENTS.md 中：

## Analyga
This project uses Analyga for analytics. Use the `tga` CLI.
Config is in .analyga/config.json (auto-loaded), or set ANALYGA_KEY.
If not configured: tga login --key YOUR_KEY

Run `tga agent-schema --json` — it returns every command + valid flags + error codes.
This is the single source of truth: if it is not in the schema, do not use it.
Always pass --id on `tga send`, or agent traffic collapses into one visitor.

为什么要构建它

我用过的每款分析工具都假设使用者是盯着图表看的人，但真正需要这些数据的，是触发事件的 Agent。因此，CLI 和 MCP 服务是这里的主要接口，而不是附加在 REST API 上的包装层。项目还处于早期阶段，迭代很快：如果有不完善或缺失之处，请提交问题。

文档

目前，tga --help 和 tga agent-schema --json 是权威参考。

状态

早期阶段。现已发布，供 Tyga 旗下姐妹项目团队试用。接口可能会变化；错误代码一经发布就不会再改写，因为 Agent 会根据它们进行分支处理。

许可证

专有 — Tyga.Cloud Ltd. 详见 LICENSE。