# 站迹统计 开发者文档

> SiteTrace Analytics：免注册的独立网站统计服务。浏览器行为与 HTTP 请求两本账分开统计，区分疑似真人、已验证 AI、自称 AI、其他自动化与未知。数据默认私有。

## 文档目录

- [快速开始](/docs/quickstart)：创建工作区、安装代码、读取第一份报表
- [认证与权限](/docs/authentication)：会话、恢复密钥、API 凭证、OAuth、scope
- [指标与维度](/docs/metrics)：机器可读指标字典的中文说明
- [MCP 接入](/docs/mcp)：Remote MCP 工具列表与授权方式
- [访问者分类](/docs/classification)：五类访问者、AI 客户端注册表与验证方式
- [示例](/docs/examples)：curl、TypeScript、Python、MCP 客户端

## 机器可读入口

| 入口 | 地址 | 说明 |
|---|---|---|
| OpenAPI | [/openapi.json](/openapi.json) | 由操作合同生成，与路由同源 |
| MCP | `https://openstatx.com/mcp` | Streamable HTTP；Bearer API 凭证或 OAuth 授权码 + PKCE |
| llms.txt | [/llms.txt](/llms.txt) | 给 LLM 的导航 |
| ARD | [/.well-known/ard.json](/.well-known/ard.json) | Agent Resource Discovery |
| Agent Card | [/.well-known/agent-card.json](/.well-known/agent-card.json) | 能力卡片 |
| 指标字典 | [/api/v1/schema/metrics](/api/v1/schema/metrics) | 公开，无需认证 |
| 能力表 | [/api/v1/capabilities/public](/api/v1/capabilities/public) | implemented / enabled / configured / available |

每个文档页都有 Markdown 版本：在地址后加 `.md`，例如 [/docs/quickstart.md](/docs/quickstart.md)。

## 数据新鲜度

- 浏览器与 HTTP 采集写入后即可查询（near_real_time，通常 60 秒内）。
- 会话在 30 分钟无活动后结算；未结算的数据标记为 provisional。
- 15 分钟汇总由每 5 分钟一次的定时任务生成；热明细默认保留 7 天，小时汇总 90 天，日汇总 365 天。

## 限制

- 本服务不提供 AI 训练次数、AI 回答引用次数或模型收录量；日志无法证明这些事实。
- Site ID 是公开标识，只能写入，不能读取任何数据。
- 本服务不修改你的安全规则、不自动封禁访客。