crawl-census-client

Спрашивайте перед загрузкой. Готовый клиент, который не даёт вашему краулеру тратить запросы на закрытые двери и не позволяет ему обходить контент, который кто-то пытается продать.

Чтение robots.txt отвечает на один вопрос и скрывает два других. По измерениям на 23 482 доменах от Crawl Census:

• 2 874 домена разрешают ИИ-агентов в robots.txt, а затем отказывают тем же агентам на сетевом уровне. Парсер видит разрешение; запрос возвращает 403. Вы платите за круговой путь и ничего не получаете.

• 208 доменов отвечают ИИ-агенту кодом HTTP 402 Payment Required. Это цена, а не отказ. Относиться к этому как к блокировке — значит уходить от контента, который оператор хочет вам продать. Повторные попытки в обход — это взятие того, за что они берут плату.

Без зависимостей. Без ключа.

MCP-сервер

Те же измерения доступны как удалённый MCP-сервер, так что агент может спросить перед загрузкой, а не после неудачи. Указан в официальном реестре MCP как io.github.taylorsmithgg/crawl-census.

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

Без аутентификации для инструментов чтения. Streamable 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)

Пропуск возвращается, а не выбрасывается. Это нормальный исход для большой доли веба, и цикл обхода должен уметь считать пропуски без try/except вокруг каждого URL.

Разделите очередь перед обходом

Один вызов на 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 теперь автоматически разделяет работу: запросы, отправленные в одном тике, уходят как один пакетный вызов, а одновременные запросы к одному хосту ожидают один запрос.

batchSize по умолчанию 25 — это лимит на вызов без ключа. Увеличьте его с ключом Pro или Data. batchWaitMs расширяет окно объединения для параллелизма, который приходит волнами, а не сразу; значение по умолчанию 0 сбрасывается на следующем тике.

Оплата, когда источник называет цену

Вердикт 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, и договорённость должна быть достигнута вне канала. И цены зависят от краулера: по измеренному корпусу, 78 из 213 источников, берущих плату, берут с одних агентов и обслуживают других бесплатно, так что спрашивайте со своим токеном, а не предполагайте, что домен из списка возьмёт с вас плату.

Два вида неизвестности

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, всё ещё тратит около 2 900 запросов за проход на домены, которые разрешают его в robots.txt и отказывают на границе, или отвечают 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

Если цифра неверна, канал исправления указан в этом ответе и на вашей странице оператора. Факты реестра исправляются без споров; спорные измерения публикуются вместе со спором и базовыми записями сканирования, а не тихо изменяются.

Лимиты

25 доменов на вызов preflight анонимно, 200 с ключом Pro, 1 000 с ключом Data. Передайте apiKey. Подробности на https://crawlcensus.com/for-crawlers.

Тесты

node test.mjs намеренно работает против живой переписи. Ценность этого клиента в том, совпадают ли его вердикты с реальностью, а мок-тест утверждал бы только, что мок согласен сам с собой.

MIT. Данные — CC BY 4.0, атрибуция: "Source: Crawl Census (crawlcensus.com)".