brightdata-gatekeeper

Проверка на основе доказательств для самовосстановления Bright Data Scraper Studio.

Bright Data чинит сломанные скрейперы. Но он не решает, правильно ли исправление. Это решает Gatekeeper: он обнаруживает поломку, создаёт бриф на восстановление, затем сверяет предложенное исправление со строками, записанными, пока скрейпер был здоров, и отклоняет его, если они расходятся.

Какой пробел это закрывает

В документации самого CLI Bright Data это сказано прямым текстом:

Детектор — это вы. CLI никогда не решает сам, что скрейпер сломан, — вы смотрите на результат и решаете. […] Расплывчатые промпты дают расплывчатые исправления.

scraper heal переписывает шаблон коллектора и останавливается у гейта подтверждения. approve фиксирует результат. --auto-approve пропускает вопрос. Ответ никто не проверяет.

run → validate → diagnose → brief → heal → verify → approve or reject → re-brief

У этого цикла нет другой точки входа. Python SDK Bright Data охватывает trigger/poll/fetch для Scraper Studio, но не heal или approve; его MCP-сервер с 69 инструментами вообще не содержит инструментов Scraper Studio. Gatekeeper поставляет MCP-сервер, поэтому агент может управлять циклом.

Related MCP server: scraper-health-mcp

Результат, который имеет значение

На живом коллекторе с намеренно сломанной страницей heal от Bright Data восстановил четыре поля корректно и молча уронил пятое в null. units объявлено необязательным, поэтому все проверки схем, типов и диапазонов прошли — ноль выявленных поломок.

--auto-approve would : APPROVE   preview passes every field check
gatekeeper decided   : REJECT    2/2 golden rows disagree
                                 units: expected '118500', preview has 'null'

--auto-approve зафиксировал бы скрейпер, который молча перестал собирать значения units. Причина отклонения попала в следующий бриф, повторная попытка сошлась с эталоном по каждой сравниваемой строке, и исправление было проверено на свежем боевом запуске.

Quick start

uv sync --all-extras
npm install -g @brightdata/cli        # Node >= 20
cp .env.example .env                  # add BRIGHTDATA_API_KEY

gatekeeper doctor                     # check the setup
gatekeeper spec add specs/mutant-recalls.json
gatekeeper status                     # survey every collector
gatekeeper check   <collector_id>     # detect
gatekeeper golden  <collector_id>     # record known-good rows
gatekeeper heal    <collector_id>     # run the loop
gatekeeper history <collector_id>     # why a fix was committed or rejected
gatekeeper serve                      # dashboard on :8000

В роли MCP-сервера, чтобы агент мог вести цикл:

claude mcp add gatekeeper -- gatekeeper mcp

preview_heal_brief показывает промпт, который будет отправлен, не расходуя задачу AI-Flow.

Правила цикла

• Никогда не доверяй коду возврата. Запуск с кодом 200 и пустыми полями — именно тот сбой, который важен.

• Никогда не лечи блок. blocked и dead_page — тревожный сигнал, но не изменение вёрстки.

• Никогда не подтверждай без доказательств. Нет эталонных строк — значит воздержаться, а не подтвердить.

• Проверяй после фиксации. Превью — обещание, боевой запуск — доказательство.

Коллекторы

Четыре управляемых коллектора, три из них — реальные сайты, ни один не входит в 1743 готовых скрейпера Bright Data — gatekeeper coverage <url> проверяет это, а не просто утверждает.

Подробности, включая проблему создания эталонных строк с нуля: docs/SITES.md.

Структура

src/gatekeeper/
  detector/    rules, baselines, engine — decides a scraper broke
  brief/       diagnosis → typed heal prompt
  approver/    judges a preview against golden rows
  brightdata/  bdata CLI wrapper, envelopes, coverage check
  controller   the closed loop
  mcp          agent-callable tools
  api, static  the dashboard
mutant/        the mutation target, deployed as a Worker

Тесты

$ pytest -q
138 passed

Без сети и без кредитов: CLI bdata подменяется заглушкой на границе подпроцесса, а цикл гоняется на скриптовом клиенте, поэтому вся машина состояний — включая сценарий «отклонить и сойтись заново» — проверяется автономном.

Примечания

Развёртывание и публикация панели без учётных данных: docs/DEPLOY.md. Чего живой API научил нас сверх документации: docs/FINDINGS.md.

MIT.