brightdata-gatekeeper

Bright Data Scraper Studio 자가 치유를 위한 증거 기반 승인.

Bright Data는 고장난 스크레이퍼를 수리합니다. 수리가 올바른지 여부는 판단하지 않습니다. Gatekeeper가 그 역할을 합니다 — 중단을 감지하고, 힐 브리프를 작성한 다음, 스크레이퍼가 정상일 때 기록된 행과 제안된 수정을 비교하여 판단하고, 일치하지 않으면 거부합니다.

이 도구가 메우는 공백

Bright Data 자체 CLI 문서는 이를 분명히 밝힙니다:

당신이 탐지기입니다. CLI는 스크레이퍼가 고장났다고 스스로 판단하지 않습니다 — 실행 출력을 검사하고 결정하는 것은 당신입니다. […] 모호한 프롬프트는 모호한 힐을 만들어냅니다.

scraper heal은 수집기의 템플릿을 다시 작성하고 승인 게이트에서 멈춥니다. approve 가 이를 커밋합니다. --auto-approve는 질문을 건너뜁니다. 아무도 답을 확인하지 않습니다.

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

이 순환은 다른 어디에서도 접근할 수 없습니다. Bright Data의 Python SDK는 Scraper Studio의 트리거/폴링/페치를 다루지만 heal이나 approve는 다루지 않습니다. 69개 도구를 갖춘 MCP 서버에는 Scraper Studio 도구가 전혀 없습니다. Gatekeeper는 MCP 서버를 제공하므로 에이전트가 이를 구동할 수 있습니다.

Related MCP server: scraper-health-mcp

중요한 결과

의도적으로 고장난 페이지의 라이브 수집기를 대상으로, Bright Data의 힐은 네 개 필드를 올바르게 복구하고 다섯 번째 필드를 조용히 null로 떨어뜨렸습니다. units는 선택 사항으로 선언되어 있어 모든 스키마, 유형 및 범위 검사를 통과했습니다 — 깨진 발견 사항 0건:

--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는 단위 수집을 조용히 중단한 스크레이퍼를 커밋했을 것입니다. 거부 사유는 다음 브리프에 포함되었고, 재시도는 비교된 모든 행에서 골든과 일치했으며, 수정은 새로운 라이브 실행에서 검증되었습니다.

빠른 시작

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는 경고하지만 레이아웃 변경이 아닙니다.

• 증거 없이 절대 승인하지 마세요. 골든 행이 없으면 승인이 아니라 기권입니다.

• 커밋 후 검증하세요. 미리보기는 약속이고, 라이브 실행은 증거입니다.

수집기

네 개의 관리형 수집기, 그중 세 개는 실제 사이트이며, Bright Data의 1,743개 사전 구축 스크레이퍼에는 없습니다 — 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

네트워크도 크레딧도 없음: bdata CLI는 서브프로세스 경계에서 스텁 처리되고 루프는 스크립트된 클라이언트를 대상으로 실행되므로, 거부-재수렴을 포함한 전체 상태 머신이 오프라인에서 검증됩니다.

참고 사항

배포 및 대시보드가 자격 증명 없이 게시되는 방법: docs/DEPLOY.md. 라이브 API가 문서가 알려주지 않은 것을 가르쳐준 것들: docs/FINDINGS.md.

MIT.