brightdata-gatekeeper

Aprobación basada en evidencia para la autocuración de Bright Data Scraper Studio.

Bright Data repara scrapers rotos. No decide si una reparación es correcta. Gatekeeper sí lo hace: detecta la rotura, escribe el informe de curación y luego juzga la corrección propuesta contra las filas registradas mientras el scraper estaba sano, y la rechaza si no coinciden.

La brecha que esto cubre

La propia documentación de la CLI de Bright Data lo afirma claramente:

Tú eres el detector. La CLI nunca decide por sí sola que un scraper está roto: tú inspeccionas la salida de la ejecución y decides. […] Las indicaciones vagas producen curaciones vagas.

scraper heal reescribe la plantilla de un collector y se detiene en una puerta de aprobación. approve la confirma. --auto-approve omite la pregunta. Nadie comprueba la respuesta.

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

El ciclo también es accesible desde ningún otro lugar. El SDK de Python de Bright Data cubre el trigger/poll/fetch de Scraper Studio, pero no heal ni approve; su servidor MCP de 69 herramientas no tiene ninguna herramienta de Scraper Studio. Gatekeeper incluye un servidor MCP, por lo que un agente puede manejarlo.

Related MCP server: scraper-health-mcp

El resultado que importa

Contra un collector en vivo en una página deliberadamente rota, la curación de Bright Data recuperó cuatro campos correctamente y silenciosamente dejó el quinto en null. units se declara opcional, por lo que todas las comprobaciones de esquema, tipo y rango pasaron — cero hallazgos rotos:

--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 habría confirmado un scraper que silenciosamente dejó de recopilar recuentos de unidades. La razón del rechazo se incluyó en el siguiente informe, el reintento coincidió con las filas doradas en cada fila comparada, y la corrección se verificó en una nueva ejecución en vivo.

Inicio rápido

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

Como servidor MCP, para que un agente pueda manejar el bucle:

claude mcp add gatekeeper -- gatekeeper mcp

preview_heal_brief muestra la indicación que se enviaría sin gastar un trabajo de AI-Flow.

Reglas que el bucle obedece

• Nunca confíes en un código de salida. Una ejecución que devuelve 200 con campos vacíos es el fallo que importa.

• Nunca cures un bloqueo. blocked y dead_page alarman pero no son cambios de diseño.

• Nunca apruebes sin evidencia. Sin filas doradas significa abstenerse, no aprobar.

• Verifica después de confirmar. Una vista previa es una promesa; una ejecución en vivo es evidencia.

Collectors

Cuatro collectors gestionados, tres de ellos sitios reales, ninguno en los 1.743 scrapers preconstruidos de Bright Data — que gatekeeper coverage <url> comprueba en lugar de afirmar.

Detalles, incluido el problema del arranque dorado: docs/SITES.md.

Diseño

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

Pruebas

$ pytest -q
138 passed

Sin red y sin créditos: la CLI bdata está simulada en el límite del subproceso y el bucle se ejecuta contra un cliente con guion, por lo que toda la máquina de estados — incluido el rechazo y la reconvergencia — se verifica sin conexión.

Notas

Despliegue, y cómo se publica el panel sin credenciales: docs/DEPLOY.md. Cosas que la API en vivo nos enseñó que los documentos no: docs/FINDINGS.md.

MIT.