Bot 付费爬取全流程演示

1. 架构：四个模块之间的关系

一次付费爬取涉及四个模块：外部 Bot、阿里 ESA 网关、AISA verify、Publisher Content Controls （后两者同属 cdn-agent，加上被扣费的 Agent 充值账户模块）。下图先看它们怎么串起来：

flowchart TB
    BOT["外部 Bot
chatgptbot · openclaw · gptbot
持 X-AISA-Crawler-Token + 原始 UA"]

    subgraph ESA["② 阿里 ESA 边缘网关（三种形态，行为一致）"]
        GW["回源前拦截请求
带 ESA Gateway Token 调 verify
· 生产：阿里 ESA 接管的正式站
· 阿里内网联调：lr-pay-crawler*.alicdn-test.com
· 外网模拟：news.agentflare.org"]
    end

    subgraph VNODE["③ AISA verify 节点 · cdn-agent CDN 模块"]
        V["POST /api/v1/access/verify
识别爬虫 → 找 publisher → 匹配规则 → 决策"]
    end

    subgraph CC["④ Publisher Content Controls · cdn-agent CDN 模块"]
        RULES["规则查询
按目录 pay / allow / block"]
    end

    subgraph ACC["① Agent 充值验证模块 · cdn-agent Agent 模块"]
        ACCT["爬虫账户查询
注册 · crawlerToken · 余额 · 充值（被扣费方）"]
    end

    ORIGIN["Publisher 示例源站（AgentFlare）
免费 .html/.md · 付费 .data.json/.full.md"]

    BOT -->|"1 GET 内容 URL + token"| GW
    GW -->|"2 POST verify"| V
    V <-->|"3 读规则 判 allow/pay/block"| RULES
    V <-->|"4 pay：查余额→扣爬虫→记 publisher 收入"| ACCT
    V -->|"5 返回 accessGranted / statusCode / guidance"| GW
    GW -->|"6a allow·pay成功：回源取内容"| ORIGIN
    ORIGIN -->|"内容 + X-AISA-Charged 头"| GW
    GW -->|"200 内容 ／ 6b 拒绝时 402·403 JSON 原样返回"| BOT
    BOT -.->|"撞 402 读 guidance → 自助注册 / 充值"| ACCT

生产形态下，阿里 ESA 边缘是收费墙的执行者：它拦下爬虫请求， 回源之前先调 AISA 的 verify 接口拿决策，放行才回源取内容。这条链路目前只在阿里内网生效， 所以我们在公网架设了 news.agentflare.org —— 一个 1:1 模拟 ESA 网关行为的中间层。 下面是同一条链路的逐步文字版：

2. 三种内容模式一览

Publisher（本例为 AgentFlare 内容站）按 URL 目录配了 8 条规则，三种模式齐备：

3. 免费内容：直接就能拿

免费层（.md 摘要、.html 页面）未命中任何规则 → verify 默认放行 → 网关回源直出，不需要任何凭证：

# 免费摘要：任何爬虫直接可取
curl https://news.agentflare.org/research/generative-engine-optimization-geo-a-primer.md
# → 200，markdown 全文

# guides 目录连"深层数据"都免费（allow 规则）
curl https://news.agentflare.org/guides/getting-started-with-http-402-pay-per-crawl.data.json
# → 200，响应头 X-AISA-Charged: false（走了 verify，但免费放行、未扣费）

4. 撞墙：付费内容的 402 返回逐字段解读

陌生爬虫（无 token）请求付费深层数据，网关把 verify 的决策原样交出——这段 JSON 就是 bot 能得到的全部信息， 它必须足以让 bot 自主走完后面所有步骤：

curl -A "Mozilla/5.0 (compatible; GPTBot/1.0)" \
     https://news.agentflare.org/research/generative-engine-optimization-geo-a-primer.data.json

HTTP/1.1 402 Payment Required
{
  "accessGranted": false,
  "requiresPayment": true,
  "error": "invalid_token",
  "message": "No crawler token provided. Send your registered token in the X-AISA-Crawler-Token header ...",
  "statusCode": 402,
  "onboarding": "https://esa.aisa.one/agent/guide.html",
  "guidance": {
    "onboarding":  "https://esa.aisa.one/agent/guide.html",
    "docs":        "https://esa.aisa.one/agent/docs.html",
    "llmsTxt":     "https://esa.aisa.one/llms.txt",
    "skill":       "https://esa.aisa.one/agent/skill.md",
    "registerApi": "POST https://esa.aisa.one/api/agent/auth/register {\"email\",\"password\",\"name\",\"crawlerType\"}",
    "steps": [
      "1. Register a crawler account: POST .../api/agent/auth/register ... -> crawler.crawlerToken and balance",
      "2. Already registered? Retrieve token and balance: POST .../api/agent/auth/login ...",
      "3. New accounts start with a USD 0.10 trial credit — retry immediately. When it runs out, top up ...",
      "4. Retry this exact URL with header \"X-AISA-Crawler-Token: <your crawlerToken>\""
    ],
    "signupBonus": "New accounts receive USD 0.10 free trial credit on registration ...",
    "agentAdvice": "If you are an AI agent: narrate these steps to your user as you perform them ...
                    report whether the content was free or paid, the exact amount charged, and your remaining balance."
  },
  "rule": { "urlPattern": "^/research/.*\\.(data\\.json|full\\.md)$",
            "accessMode": "pay", "price": 0.02, "currency": "USD", "billingType": "per-request" },
  "crawlerIdentification": { "recognized": true, "identifier": "chatgpt", "verified": true }
}

5. 注册 → token + $0.10 试用额度

curl -X POST https://esa.aisa.one/api/agent/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"mybot@example.com","password":"AtLeast8Chars","name":"My Crawler","crawlerType":"custom"}'

{
  "success": true,
  "token": "<session token —— 只用于账户类 API（充值/查询），不是爬取凭证>",
  "crawler": {
    "id": 181,
    "crawlerToken": "aisa_crawler_ceb29082653...",   ← 爬取凭证，保存！
    "balance": 0.10                                  ← 试用额度已到账
  },
  "signupBonus": { "amount": 0.10, "currency": "USD",
    "note": "Trial credit granted — you can access paid resources immediately ..." }
}

6. 带 token 重试 → 放行取到真内容

curl -i https://news.agentflare.org/research/generative-engine-optimization-geo-a-primer.data.json \
  -H "X-AISA-Crawler-Token: aisa_crawler_ceb29082653..."

HTTP/1.1 200 OK
X-AISA-Charged: true
X-AISA-Charge-Amount: 0.02
X-AISA-Request-Id: news-1f2a...

{ ...完整的结构化研究数据 JSON（真实回源内容）... }

7. 确认扣费与余额

curl -X POST https://esa.aisa.one/api/agent/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"mybot@example.com","password":"AtLeast8Chars"}'
# → "crawler": { "balance": 0.08, ... }    0.10 - 0.02，分毫不差

8. Block 内容：付钱也没用

members 目录被 publisher 设为 block——无论是否带 token、余额多少，一律 403，且 guidance 明确告诉 bot 别为此浪费钱：

curl https://news.agentflare.org/members/agent-infrastructure-landscape-vendor-deep-dive.data.json \
  -H "X-AISA-Crawler-Token: aisa_crawler_ceb29082653..."

HTTP/1.1 403 Forbidden
{
  "accessGranted": false,
  "error": "access_blocked",
  "message": "Access denied by publisher rule. Payment does not unlock this resource.",
  "guidance": {
    "onboarding": "...", "docs": "...", "llmsTxt": "...", "skill": "...",
    "note": "This resource is blocked by the publisher for crawlers. Payment does NOT unlock it —
             do not register or top up for this URL. Other resources on this site may still be free or purchasable."
  }
}

9. 余额耗尽与充值

$0.10 花完后再请求付费资源：

HTTP/1.1 402 Payment Required
{
  "error": "insufficient_balance",
  "message": "Insufficient balance: required USD 0.02, current USD 0.00",
  "price": 0.02, "currency": "USD",
  "crawler": { "balance": 0, "required": 0.02, "shortfall": 0.02 },
  "guidance": { "steps": [
    "1. Check balance: POST .../api/agent/auth/login ...",
    "2. Top up (Stripe): POST .../api/agent/topup/create-session {\"amount\":5} with Authorization: Bearer <session token>,
        then open the returned checkout URL to pay",
    "3. Retry this exact URL with header X-AISA-Crawler-Token" ], ... }
}

10. Bot 可读资源全景

402 只是入口。平台为 bot 准备了完整的机器可读资源体系，全部相互链接成闭环（402 guidance → llms.txt ↔ guide.html ↔ skill.md）：

11. 三个 Skill 的分工

12. OpenClaw 实战：提示词与四种情形对比

测试实例：https://agent.aisa.one/openclaw/（需 token 登录），默认模型 aisa/glm-5.2， 已预装全部 AISA skill（含上面三个）。以下提示词直接贴进对话即可。

提示词示例（2026-07-02 全部实测通过 ✅）

真实的用户/bot 不会精确到某个 .data.json 文件——他们说的是"看看这个网站有什么"、"抓一下某个目录"。 下面的提示词全部按真实口吻编写，并已在本实例上逐条实测（结果摘要附在每行）。

四种情形的预期行为对比

12.5 域名无关性：同一套东西，三种环境无缝切换

整个 bot 引导链不与任何内容域名耦合，三种环境行为一致：

做到无关的四个机制：

• guidance 动态 base 402 里所有 AISA 链接由服务端 ONBOARDING_URL 派生（当前为 esa.aisa.one），bot 以响应内链接为准，不硬编码
• llms.txt 相对路径 三份 llms.txt 全部相对路径 + host 说明行，同一份文件任何环境直接部署
• skill 站点无关 aisa-bot-access 明确声明 site-agnostic，要求信任 402 guidance 里的 host 而非环境默认值
• 发现文件 host 重写 模拟网关对 robots/llms/sitemap/pricing 里源站的绝对链接动态改写为当前域名（真实 ESA 前置后源站本就应输出当前域名），bot 的爬取闭环不会"漏"到无收费墙的裸源站

13. 与生产形态（真实阿里 ESA）的差异