brightdata-gatekeeper

Evidenzbasierte Freigabe für die Selbstheilung von Bright Data Scraper Studio.

Bright Data repariert defekte Scraper. Es entscheidet nicht, ob eine Reparatur korrekt ist. Gatekeeper übernimmt das — es erkennt den Bruch, verfasst den Heilungsauftrag, bewertet dann den vorgeschlagenen Fix anhand von Zeilen, die bei gesundem Scraper aufgezeichnet wurden, und lehnt ihn ab, wenn sie nicht übereinstimmen.

Die Lücke, die es schließt

Bright Datas eigene CLI-Dokumentation sagt es deutlich:

Sie sind der Detektor. Die CLI entscheidet nie von sich aus, dass ein Scraper defekt ist — Sie prüfen die Ausgabe des Laufs und entscheiden. […] Vage Prompts erzeugen vage Heilungen.

scraper heal schreibt die Vorlage eines Collectors neu und stoppt an einem Freigabe-Gate. approve übernimmt sie. --auto-approve überspringt die Frage. Niemand prüft die Antwort.

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

Der Zyklus ist auch von sonst nirgendwo erreichbar. Bright Datas Python-SDK deckt Trigger/Poll/Fetch von Scraper Studio ab, aber nicht heal oder approve; sein MCP-Server mit 69 Tools hat überhaupt keine Scraper-Studio-Tools. Gatekeeper liefert einen MCP-Server mit, sodass ein Agent ihn steuern kann.

Related MCP server: scraper-health-mcp

Das Ergebnis, das zählt

Gegenüber einem Live-Collector auf einer absichtlich defekten Seite stellte Bright Datas Heilung vier Felder korrekt wieder her und setzte das fünfte stillschweigend auf null. units ist als optional deklariert, sodass alle Schema-, Typ- und Bereichsprüfungen bestanden wurden — null defekte Befunde:

--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 hätte einen Scraper übernommen, der stillschweigend aufgehört hätte, Stückzahlen zu erfassen. Der Ablehnungsgrund floss in den nächsten Auftrag ein, der erneute Versuch stimmte in jeder verglichenen Zeile mit den Golden Rows überein, und der Fix wurde in einem frischen Live-Lauf verifiziert.

Schnellstart

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

Als MCP-Server, damit ein Agent den Zyklus steuern kann:

claude mcp add gatekeeper -- gatekeeper mcp

preview_heal_brief zeigt den Prompt, der gesendet würde, ohne einen AI-Flow-Job zu verbrauchen.

Regeln, die der Zyklus befolgt

• Vertraue niemals einem Exit-Code. Ein Lauf, der 200 mit leeren Feldern zurückgibt, ist der Fehler, der zählt.

• Heile niemals eine Blockade. blocked und dead_page alarmieren, sind aber keine Layoutänderungen.

• Genehmige niemals ohne Belege. Keine Golden Rows bedeutet Enthaltung, nicht Genehmigung.

• Verifiziere nach der Übernahme. Eine Vorschau ist ein Versprechen; ein Live-Lauf ist ein Beleg.

Collectors

Vier verwaltete Collectors, drei davon echte Websites, keiner in Bright Datas 1.743 vorgefertigten Scrapern — was gatekeeper coverage <url> prüft, statt es zu behaupten.

Details, einschließlich des Golden-Bootstrap-Problems: docs/SITES.md.

Layout

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

Tests

$ pytest -q
138 passed

Kein Netzwerk und keine Credits: Die bdata-CLI wird an der Subprocess-Grenze gestubbt, und der Zyklus läuft gegen einen skriptbasierten Client, sodass die gesamte Zustandsmaschine — einschließlich Ablehnen-und-Wiederangleichen — offline verifiziert wird.

Anmerkungen

Bereitstellung und wie das Dashboard ohne Anmeldedaten veröffentlicht wird: docs/DEPLOY.md. Dinge, die uns die Live-API gelehrt hat, die die Dokumentation nicht enthielt: docs/FINDINGS.md.

MIT.