thereal-baitjet/santos-audit-api
GitHub: thereal-baitjet/santos-audit-api
Santos Audit API 是一个基于 x402 微额支付协议的网站智能审计 API，专为 AI Agent 评估网站的可发现性、可理解性、可调用性与可信度而设计。
Stars: 1 | Forks: 0
# Santos Website Intelligence API
**面向 Agentic Web 的 AI 网站智能与 Agent Readiness** — 衡量公共网站是否能被 agent 发现、理解、信任和使用。Quick、Agent Readiness 以及浏览器渲染的 Deep 审计会返回结构化证据和优先修复建议。无需账户或传统的 API key；付费资源使用 [x402 协议](https://x402.org) 通过 Base 上的 USDC 进行支付。
从可发现到可调用。
[](https://www.santosautomation.com/)
[](https://vercel.com/thereal-baitjets-projects/santos-api)
[](https://api.santosautomation.com/openapi.json)
[](https://x402.org/)
[](https://api.santosautomation.com/openapi.json)
[](package.json)
实时环境：API 位于 **https://api.santosautomation.com** · 落地页位于
**https://www.santosautomation.com**（同一个应用，两个主机名）
该公共站点被定位为 Santos Website Intelligence。其响应式导航使用了来自 `public/assets` 的金色 Santos 鹰 SVG 标志。
| 接口 | URL |
|---|---|
| Quick Intelligence Audit ($0.005 USDC, 同步) | `GET /api/audit?url=https://example.com` |
| **Agent Readiness** ($0.025 USDC, 有限的被动评估) | `GET /api/agent-readiness?url=https://example.com&depth=quick` |
| **Deep Website Intelligence Audit** ($0.075 USDC, 异步任务) | `POST /v1/audits` `{"url": "https://example.com"}` |
| 免费演示（每个 IP 每天 1 次） | `GET /api/audit/demo?url=https://example.com` |
| OpenAPI 3.1 | [`/openapi.json`](https://api.santosautomation.com/openapi.json) |
| llms.txt | [`/llms.txt`](https://api.santosautomation.com/llms.txt) |
| MCP 服务器 (工具: `audit_website_preview`, `audit_agent_readiness`) | `POST /mcp` |
| Service manifest | [`/api`](https://api.santosautomation.com/api) |
| Capability manifest | [`/capabilities.json`](https://api.santosautomation.com/capabilities.json) |
| Well-known capability manifest | [`/.well-known/agent-capabilities.json`](https://www.santosautomation.com/.well-known/agent-capabilities.json) |
| Sitemap / 爬虫规则 | [`/sitemap.xml`](https://www.santosautomation.com/sitemap.xml) · [`/robots.txt`](https://www.santosautomation.com/robots.txt) |
## Website Intelligence 模型
Santos 在已完成的适用检查中衡量四个维度：
- **Discoverable** — 爬虫访问、canonical URL、sitemaps、`llms.txt`、文档和界面链接。
- **Understandable** — 结构化身份、JSON-LD、语义化 HTML、元数据、定价和业务上下文。
- **Callable** — OpenAPI、MCP、capability manifest、类型化 schema、稳定的错误、job endpoint 以及适用情况下的 x402。
- **Trustworthy** — HTTPS、安全标头、可访问性、性能、浏览器行为、支持和证据质量。
加和性的 `website_intelligence_score` 和 `website_intelligence` 字段会与历史 Quick Audit 字段一同出现。现有的 `overall_score`、类别分数、endpoint 路径、capability id 和支付行为保持兼容。
## 公共产品页面
- [AI Website Intelligence](https://www.santosautomation.com/ai-website-intelligence)
- [Agent Readiness Audit](https://www.santosautomation.com/agent-readiness-audit)
- [Website Intelligence API](https://www.santosautomation.com/website-intelligence-api)
- [MCP Readiness Checker](https://www.santosautomation.com/mcp-readiness-checker)
- [llms.txt Checker](https://www.santosautomation.com/llms-txt-checker)
- [OpenAPI Readiness Checker](https://www.santosautomation.com/openapi-readiness-checker)
- [Agent Readiness Methodology](https://www.santosautomation.com/methodology/agent-readiness)
- [Sample Agent Readiness Report](https://www.santosautomation.com/reports/sample-agent-readiness)
- [学习指南](https://www.santosautomation.com/learn/what-is-ai-website-intelligence)
## Agent 如何支付 (x402)
```
GET /api/audit?url=example.com
← 402 · PAYMENT-REQUIRED:
→ retry with PAYMENT-SIGNATURE:
← 200 OK · audit JSON · PAYMENT-RESPONSE:
```
协议：**x402 v2**（已于 2026-07-17 迁移；不再接受旧版 v1 `X-PAYMENT` 客户端）。
**仅在成功响应后**进行支付结算 —— 如果是错误的 URL 或无法访问的目标，agent 无需支付任何费用。
### JavaScript / TypeScript
```
import { privateKeyToAccount } from "viem/accounts";
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
const account = privateKeyToAccount(process.env.BUYER_PRIVATE_KEY);
const fetchWithPay = wrapFetchWithPaymentFromConfig(fetch, {
schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});
const res = await fetchWithPay(
"https://api.santosautomation.com/api/audit?url=example.com"
);
const report = await res.json(); // { overall_score, scores, checks, issues, ... }
```
可用脚本：[`buy-audit.js`](buy-audit.js)（本地开发）和
[`buy-live.js`](buy-live.js)（生产环境）。Python 示例：
[`examples/audit_client.py`](examples/audit_client.py)。
### 先尝试免费演示
相同的报告结构，无需支付，每个 IP 每天 1 次：
```
curl "https://api.santosautomation.com/api/audit/demo?url=example.com"
```
## Deep Website Intelligence（浏览器渲染层）
在隔离的 Fly.io worker 中通过 Playwright 运行真实的 Chromium：Lighthouse 实验室指标、渲染后的 axe-core 可访问性检查结果（带选择器）、浏览器网络/控制台证据、截图以及被动安全检查。异步：$0.075 的支付购买的是**有界的计算预留**（在任务受理时结算，而非在报告完成时）。带有 `Idempotency-Key` 标头的 `POST /v1/audits` -> 使用返回的一次性 `access_token` 轮询 `status_url` -> 获取 `report_url`（版本化的 `schema_version: 3.0.0` JSON + 签名的 artifact URL）。
可用的买家示例：[`buy-deep.js`](buy-deep.js)。架构及上线运行手册：[`docs/deep-audit.md`](docs/deep-audit.md)。
## Agent 准备情况
版本化的 `AgentReadinessResult` 评估公共的面向 agent 的可发现性、结构化身份、OpenAPI、MCP、操作信任度以及 x402/机器商务信号。它首先会对适用性进行分类，因此普通网站不会因为缺少 API、MCP 服务器或支付接口而受到惩罚。独立的快速扫描最多使用八个有界请求，并且绝不会对受审计目标进行身份验证或支付、提交表单、创建目标账户、调用目标工具或执行代码。
Agent Readiness 也可作为 `POST /v1/audits` 的选 opt-in `agent-readiness` 模块使用，可通过 MCP 的 `audit_agent_readiness` 付费 HTTP 交接进行调用，并以加和形式作为 Quick Audit 响应内的低覆盖率嵌入式预览。
独立结果通过 x402 v2 对**每次成功响应收取 $0.025 USDC**；失败的审计不进行结算。现有的 Quick Audit `overall_score` 保持不变。
独立响应还包含加和性的 Website Intelligence 分数和四维呈现，当目标未公布可调用服务时，`callable` 将被标记为不适用。
计分和标准基线记录在
[`docs/agent-readiness-scoring.md`](docs/agent-readiness-scoring.md) 和
[`docs/agent-readiness-spec-baseline.md`](docs/agent-readiness-spec-baseline.md) 中。
## 响应结构（Quick Intelligence Audit）
```
{
"tier": "paid",
"url": "https://example.com/",
"http_status": 200,
"timing_ms": { "ttfb": 166, "total": 168 },
"overall_score": 68,
"scores": { "performance": 100, "seo": 40, "accessibility": 100, "security": 33 },
"website_intelligence_score": 74,
"website_intelligence": {
"dimensions": {
"discoverable": 81,
"understandable": 68,
"callable": null,
"trustworthy": 73
},
"applicability": { "callable": "not_applicable" },
"coverage": { "tests_executed": 28, "tested_percent": 88 },
"confidence": 0.86,
"priority_fixes": []
},
"checks": { "performance": [ { "pass": true, "detail": "TTFB 166ms" } ] },
"issues": ["Missing canonical link", "Missing Content-Security-Policy header"]
}
```
错误格式为 `{ "error": "", "code": "" }`，错误代码包括 `INVALID_URL`、`UNSUPPORTED_SCHEME`、`PRIVATE_ADDRESS_BLOCKED`、`RATE_LIMITED`、`AUDIT_TIMEOUT`、`TARGET_UNREACHABLE`、`AUDIT_FAILED`。
## 技术栈
运行在 Vercel 上的 Next.js App Router。支付：`@x402/next` v2 (`withX402` 包装器) + `@x402/core`/`@x402/evm` 与 `@coinbase/x402`（Coinbase CDP facilitator —— 实际在 Base mainnet 上结算 USDC 的组件）以及 `@x402/extensions` Bazaar 发现扩展。审计引擎：`fetch` + `cheerio`，无无头浏览器。
防范 SSRF：阻断私有/保留/元数据 IP，每次重定向跳转均进行重新验证，15秒超时，5 次重定向，5 MB 上限 (`lib/safe-fetch.js`)。
## 开发
```
npm install
cp .env.example .env.local # fill in values
npm run dev # http://localhost:3000
npm test # e2e checks against BASE (default localhost:3000)
BASE=https://api.santosautomation.com EXPECT_NETWORK=base npm test
```
针对 Website Intelligence 层的专项检查：
```
npm run test:agent-readiness
npm run test:website-intelligence
npm run build
```
### 环境变量
请参阅 [`.env.example`](.env.example)。生产环境中必需：`CDP_API_KEY_ID`、`CDP_API_KEY_SECRET`（facilitator 身份验证）。可选：`DISCORD_WEBHOOK_URL`（支付通知）、`PUBLIC_API_BASE_URL`（文档输出中的规范主机名）、审计调优参数。
### 部署
在已关联的检出分支中使用 `vercel --prod`。Vercel 部署网站和 API 控制平面；浏览器渲染的 worker 是独立的 Fly.io 部署，必须在 worker 代码更改时独立发布。接收钱包和网络被有意硬编码在 `app/api/audit/route.js` 中 —— 过期的环境变量绝不能静默地将 API 切换回测试网。
## Registry 列表
用于 x402 目录和 MCP registry 的可直接复制的提交文本：
[`docs/registry-submissions.md`](docs/registry-submissions.md)。
## 运营方
Santos Automation (Juan Santos) — 定制 x402 API、Web 应用、电子商务和自动化系统。info@santosautomation.com · https://santosautomation.com
标签：AI代理, API服务, OpenAPI, SEO分析, Web审计, x402协议, 无密钥认证, 特征检测, 自定义脚本