# 站迹统计 (SiteTrace Analytics)

> 免注册的独立网站统计服务（CNZZ 风格中文报表）。浏览器行为与 HTTP 请求两本账分开；访问者分为 human_likely / ai_verified / ai_claimed / other_automation / unknown 五类；AI 抓取与 AI 引荐分开统计。数据默认私有。

## What this service does
- 为网站提供 PV、UV、会话、来源、页面、事件、转化、AI 与自动化请求等统计报表
- 提供 REST API（/api/v1）与 Remote MCP（/mcp），与网页后台共用权限、指标与查询服务

## Main capabilities
- 浏览器 JS 采集（含 SPA、CNZZ _czc 兼容层）与签名的服务端/边缘 HTTP 请求采集
- AI 客户端识别：官方 IP 清单验证与 UA 声明分开（ai_verified vs ai_claimed）
- 结构化查询（白名单指标/维度，不接受 SQL）、多站对比、导出、历史导入、报表计划

## Important endpoints
- OpenAPI: https://openstatx.com/openapi.json
- MCP: https://openstatx.com/mcp （Bearer API 凭证或 OAuth 2.1 授权码 + PKCE）
- 指标字典（公开）: https://openstatx.com/api/v1/schema/metrics
- 维度字典（公开）: https://openstatx.com/api/v1/schema/dimensions
- 能力表（公开）: https://openstatx.com/api/v1/capabilities/public
- ARD: https://openstatx.com/.well-known/ard.json
- Agent Card: https://openstatx.com/.well-known/agent-card.json

## Documentation
- [开发者文档](https://openstatx.com/docs.md)（入口）: 站迹统计（SiteTrace Analytics）开发者文档入口：快速开始、认证、指标口径、REST、MCP 与示例。
- [快速开始](https://openstatx.com/docs/quickstart.md): 五分钟接入站迹统计：创建匿名工作区、安装 JS、查看报表、用 API 读取数据。
- [认证与权限](https://openstatx.com/docs/authentication.md): 站迹统计的凭证分层：Site ID、浏览器会话、恢复密钥、API 凭证、采集凭证、OAuth 令牌与 scope。
- [指标与维度](https://openstatx.com/docs/metrics.md): 站迹统计指标字典：口径、单位、数据集、可加性、去重范围、隐私前提与所需权限。
- [MCP 接入](https://openstatx.com/docs/mcp.md): 站迹统计 Remote MCP：地址、认证方式与全部工具说明。
- [访问者分类](https://openstatx.com/docs/classification.md): 五类访问者定义、AI 客户端注册表、官方 IP 清单验证与 AI 引荐识别规则。
- [CNZZ 兼容](https://openstatx.com/docs/cnzz.md): 站迹统计 _czc 兼容层支持的命令、参数与迁移说明。
- [示例](https://openstatx.com/docs/examples.md): curl、TypeScript、Python 与 MCP 客户端调用站迹统计的完整示例。

## Data sources
- 统计数据来自各网站自己安装的 SDK 与授权部署的边缘/服务端采集器；本服务不抓取第三方网站
- AI 客户端注册表来自各提供方官方文档与官方 IP 清单（见 /docs/classification）

## Data freshness
- 报表：near_real_time（写入后通常 60 秒内可查）；会话 30 分钟无活动后结算
- 每个响应的 meta 包含 data_as_of、processing_status 与 quality_by_metric

## Limitations
- 所有网站数据都是私有的：需要工作区所有者创建的 API 凭证或经同意页授权的 OAuth 令牌
- 不提供 AI 训练次数、AI 回答引用次数或模型收录量
- Site ID 是公开写入标识，不能读取数据
- 高风险动作（删除、缩短保留期、公开分享）只能由人在浏览器中确认；AI 只能预览

## API
- 基础路径 https://openstatx.com/api/v1；响应 { data, meta, pagination }；错误 { error: { code, message, request_id, retryable } }

## MCP
- https://openstatx.com/mcp；工具：discover_analytics, list_sites, get_report, query_analytics, get_realtime, get_sessions, get_event_details, explain_classification, compare_sites, create_export, get_export, get_data_quality, get_usage, traffic_overview, traffic_breakdown, traffic_explain, add_site, check_installation, start_site_verification, check_site_verification, manage_goals, manage_funnels, manage_site_config, manage_saved_reports, manage_schedules, manage_imports, manage_public_shares, preview_action