brightdata-gatekeeper

Bright Data Scraper Studio の自己修復に対するエビデンスベースの承認。

Bright Data は壊れたスクレイパーを修復する。しかし、修復が正しいかどうかを判断するのは Bright Data ではない。それを判断するのが Gatekeeper である。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 の trigger/poll/fetch をカバーしているが、heal と approve はカバーしていない。同社の 69 ツールの MCP サーバーには Scraper Studio ツールがまったくない。Gatekeeper は MCP サーバーを同梱しているため、エージェントがこのサイクルを駆動できる。

Related MCP server: scraper-health-mcp

重要な結果

意図的に壊したページ上のライブコレクターに対して、Bright Data の heal は 4 つのフィールドを正しく復元し、5 つ目を黙って 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 を使っていれば、ユニット数を黙って収集しなくなったスクレイパーをコミットしていただろう。拒否理由は次のブリーフに反映され、再試行は比較されたすべての行でゴールデン行と一致し、修正は新しいライブ実行で検証された。

クイックスタート

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 は警告を発するが、レイアウト変更ではない。

• エビデンスなしに承認するな。 ゴールデン行がなければ承認ではなく棄権である。

• コミット後に検証する。 プレビューは約束であり、ライブ実行はエビデンスである。

コレクター

4 つの管理対象コレクター。うち 3 つは実在のサイトで、いずれも 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.