crawl-census-client

先问再抓取。 一个即插即用的客户端，让你的爬虫不再把请求浪费在关闭的门上，也不再绕过别人试图出售的内容。

阅读 robots.txt 回答了一个问题，却隐藏了另外两个。根据 Crawl Census 对 23,482 个域名 的测量：

• 2,874 个域名在 robots.txt 中允许 AI 代理，却在网络边缘拒绝这些相同的代理。 解析器看到的是允许；抓取返回 403。你为往返付费，却一无所获。

• 208 个域名以 HTTP 402 Payment Required 回应 AI 用户代理。 这是一个价格，而不是拒绝。将其视为阻止，就会放弃运营商想要卖给你的内容。绕过它重试，则拿走了他们收费的东西。

无依赖。无需密钥。

MCP 服务器

同样的测量结果以远程 MCP 服务器的形式提供，因此代理可以在抓取之前询问，而不是在失败之后。已在 官方 MCP 注册表 中列为 io.github.taylorsmithgg/crawl-census。

{ "mcpServers": { "crawl-census": { "url": "https://crawlcensus.com/mcp" } } }

读取工具无需认证。支持流式 HTTP。

Related MCP server: Maango-mcp

安装

npm i github:taylorsmithgg/crawl-census-client
pip install git+https://github.com/taylorsmithgg/crawl-census-client

使用

import { politeFetch } from "crawl-census-client";

const r = await politeFetch("https://example.com/", { agent: "gptbot" });
if (r.skipped) console.log(r.verdict, r.reason);   // disallow | refuse | pay
else           process(await r.response.text());

from crawl_census import polite_fetch

r = polite_fetch("https://example.com/", agent="gptbot")
if r.skipped:
    print(r.verdict, r.reason)
else:
    process(r.body)

跳过是返回的，而不是抛出的。对于网络上的大部分内容来说，这是正常结果，爬虫循环应该能够统计跳过次数，而无需在每个 URL 周围使用 try/except。

在爬取之前拆分队列

每 1,000 个域名一次调用，而不是每个主机一次：

const { crawl, skip, pay, unknown } = await partition(urls, { agent: "gptbot" });

p = partition(urls, agent="gptbot")
p.crawl, p.skip, p.pay, p.unknown

或者直接获取文件

对于只需要在内存中维护拒绝列表的抓取器，完全跳过按域名的调用：

curl https://crawlcensus.com/agents/gptbot/blocklist.txt   # one domain per line, commented header

const sync = await syncBlocklist("gptbot");   // full list once
if (sync.blocked.has(host)) skip();
setInterval(() => sync.refresh(), 3600_000);  // then deltas only, a few hundred bytes

sync = BlocklistSync("gptbot")
if host in sync: skip()
sync.refresh()          # {'added': 3, 'removed': 1, 'size': 3310, 'cursor': ...}

增量源是 https://crawlcensus.com/agents/<agent>/changes.json?since=<unix>，每个响应都带有 next_since，因此长时间运行的爬虫每小时只需几百字节即可保持最新，而无需重新下载列表。

该文件仅涵盖 robots.txt。边缘拒绝和 HTTP 402 是每次请求的行为，仍然需要 preflight 或 politeFetch。

一次爬取对普查的成本

这是测量出来的，不是断言。并发抓取二十个主机过去需要二十次 preflight 调用，每次携带一个域名；同一个主机同时请求三次需要三次，因为缓存只在第一次查找解析后才有帮助。匿名配额是每小时 240 次调用，因此当一次调用覆盖二十五个主机时，爬虫在 240 个主机时达到上限。

politeFetch 现在自动共享工作：在同一 tick 中发出的查找会合并为一次批量调用，同一主机的并发查找会等待单个请求。

batchSize 默认为 25，即没有密钥时的每次调用上限。使用 Pro 或 Data 密钥可以提高它。batchWaitMs 扩大了并发到达的合并窗口，而不是一次性全部到达；默认值为零，会在下一个 tick 刷新。

当源站报价时付费

当源站指定了金额时，pay 裁决会携带该金额：

const r = await politeFetch(url, { agent: "claudebot" });
if (r.verdict === "pay") console.log(r.price);   // "USD 0.5", or null if none was quoted

有两件事值得了解。大多数响应 HTTP 402 的源站根本没有指定金额，因此 price 通常为 null，安排必须在带外进行。而且定价是按爬虫计算的：在测量的语料库中，213 个收费源站中有 78 个对某些代理收费，对其他代理免费，因此请使用自己的令牌询问，而不是假设列表中的域名会向您收费。

两种未知

partition 将工作队列拆分为 crawl、pay、skip、unknown 和 undecidable。

最后两个看起来相似，但并非如此。unknown 表示普查尚未测量该域名：提交它，下一轮就会得到真正的裁决。undecidable 表示该网站的 robots.txt 不允许 CrawlCensusBot，因此这份普查永远不会测量它——重试是必然的浪费，每轮重新提交未知项的循环会永远重新提交这些项。服务器用 measurable 布尔值标记差异；读取该值，而不是 reason 文本。

const p = await partition(urls, { agent: "gptbot" });
await Promise.all(p.crawl.map(politeFetchOne));
if (p.unmeasured.length) await submitUnmeasured(p, { agent: "gptbot" });
// p.undecidable: read their robots.txt yourself. Asking us again cannot help.

提交是有意单独调用的。一个在看似查找的过程中悄悄 POST 的库是不良公民，您应该选择何时消耗队列位置。

跳过所有不会为您服务的内容

拒绝列表是较小的一半。根据实时普查测量，只跳过 robots 禁止的爬虫每轮仍会在 robots.txt 允许但在边缘拒绝的域名上花费约 2,900 个请求，或者响应 HTTP 402 的域名——对于 PerplexityBot 来说，这个集合比其拒绝列表还要大。这些抓取不会返回任何内容，每次都会花费一次往返。

const skip = await syncSkipList("gptbot");
if (skip.has(host)) continue;        // disallowed, refused at the edge, or priced
skip.why(host);                      // "disallow" | "pay" | "refuse" | null
setInterval(() => skip.refresh(), 3600_000);

这三个集合在内部保持分离，因此更改会移动它所属的那个。why() 遵循与 preflight 相同的优先级：禁止高于价格，因为价格不是许可。

保持拒绝列表最新

syncBlocklist / BlocklistSync 下载一次列表，然后只应用更改的内容。

列表以构建时的变更源中的确切位置提供，位于 x-cursor 标头和 # cursor: 注释中。客户端读取它并从那里恢复，因此快照和第一次轮询之间没有间隙，也不依赖您的时钟与服务器同步。按秒轮询无法表达一秒内的位置，而爬取批次会将数十个事件写入一个事件中，因此按秒粒度恢复可能会丢失其余部分：实时测量，在三个同秒更改中的第一个之后恢复，通过游标恢复了两个兄弟，而按秒则一个也没有恢复。

const sync = await syncBlocklist("gptbot");   // cursor comes from the list itself
if (sync.blocked.has(host)) skip();
setInterval(() => sync.refresh(), 3600_000);  // a few hundred bytes per poll

refresh() 只将 robots 转换应用于列表，因为这就是列表的构成。边缘拒绝、新价格和 llms.txt 更改会返回到 other 中，供您单独处理——早期版本会从拒绝列表中删除这些域名，因此爬虫会重新开始抓取刚刚开始拒绝它的内容。

裁决

每个裁决的权威定义——它意味着什么，它要求爬虫做什么，以及再次询问是否会改变它——以数据形式发布在 /api/v1/verdicts。下面的列表是摘要；如果两者不一致，端点是正确的，此文件已过时。

politeFetch 默认跳过 disallow、refuse 和 pay，这是端点派生的 do_not_fetch 集合。这里的副本是故意的——爬虫循环不需要网络调用来决定——并且测试会比较两者，以免它悄悄漂移。

onPay: "fetch"（on_pay="fetch"）覆盖付费墙默认值。这是一个明确的加入选项，并记录在结果中为 paidRouteOverridden，因此它会出现在您的日志中。

它会降级，不会失败

如果普查不可达，每个裁决都会变成 unknown，您的爬取会像往常一样继续。第三方中断绝不能停止您的管道。正好有一个实时测试来验证这一点。

我们发布关于您的代理的哪些信息

const p = await agentProfile("claudebot");
// robots disallow rate, edge refusal rate, operator page, correction channel

如果某个数字有误，更正渠道就在该响应和您的 操作员页面 中。注册表事实无需争论即可更正；有争议的测量结果会与争议和底层扫描记录一起发布，而不是悄悄修改。

限制

匿名每次 preflight 调用 25 个域名，使用 Pro 密钥 200 个，使用 Data 密钥 1,000 个。传递 apiKey。详情请见 https://crawlcensus.com/for-crawlers。

测试

node test.mjs 特意针对实时普查运行。这个客户端的价值在于其裁决是否与现实相符，而模拟测试只会断言模拟与自身一致。

MIT。数据采用 CC BY 4.0，署名方式为“来源：Crawl Census (crawlcensus.com)”。