Scavenge — 人間とコーディングエージェントのための決定論的ウェブ証拠収集ツール

Scavengeは、1つのウェブページ上の1つのフィールドを検査し、そのフィールドが現れるすべての場所、各表現の内容、そして各値の正確な出所を報告します。

フィールドの観測結果を正確な出所とともに収集します。どの観測結果が意味的に正しいかを判断することはしません。 その判断にはページの意味を理解する必要があり、本エンジンは意図的にその能力を持ちません — 詳しくはなぜそこで止めるのかを参照してください。

機能

$ scavenge inspect https://example.com/product/123 --field price

FIELD: price
  RAW_DOM          99.00 USD   [raw_dom:0]
                     raw:    '$99.00'
                     source: div.product-price
  STRUCTURED_DATA  99.00 USD   [structured_data:0]
                     raw:    '99.00'
                     source: script[0]/offers/price
  EMBEDDED_STATE   not observed
  RENDERED_DOM     79.00 USD   [rendered_dom:0]
                     raw:    '$79.00'
                     source: div.product-price
  NETWORK_JSON     79.00 USD   [network_json:0]
                     raw:    '79.00'
                     source: GET https://example.com/api/products/123 /price

ACQUISITION
  HTTP    200  48213 bytes  0.31s
  RENDER  OK
  JSON responses observed: 12

生のHTMLは99.00と表示し、レンダリングされたページは79.00と表示し、API呼び出しがその理由を説明します。これを2秒で確認できますが、エンジンはそれを主張しません。

Related MCP server: mcp-ux-vision

存在理由

ページは同じ事実を複数の場所で示します — 可視HTML、JSON-LD、ハイドレーションブロブ、レンダリングされたDOM、XHRレスポンス — そしてそれらは想定以上に頻繁に食い違います。どの場所に目的のフィールドが含まれているかを特定するのは、手作業で行うDevToolsの仕事であり、ターゲットごとに一度だけ、永遠に続きます。エージェントも同様の作業を行えますが、再現性がなく、正確な出所もありません。

なぜそこで止めるのか

当初の目標はより野心的でした：異なる表現で見つかった値が同じ現実世界のものを指しているかを決定論的に判断し、一致または不一致の箇所を報告することでした。

実際のストアフロントはその前提を破りました。比較可能に見えた値は、レコメンデーションカルーセル、カート、分割払いテーブル、ストアロケーター、商品バリエーション、同じページ上の2つ目のProductブロックに属していました。12のストアフロントでの検証実行では、エンジンが報告したすべての不一致がこの種のものでした — 値と出所は正しかったが、比較が間違っていました。

これを適切に修正するにはエンティティ解決が必要になります。そのためScavengeは一歩手前で止まります：証拠を決定論的に収集し、人間またはエージェントに解釈を委ねます。 以前の設計を破棄させた結果を含む完全な説明は、docs/research/にあります。

対応フィールド

price（価格）とavailability（在庫状況）。2つだけです。「任意」ではありません。

対応チャネル

RAW_DOM · STRUCTURED_DATA · EMBEDDED_STATE · RENDERED_DOM · NETWORK_JSON

これらは同等に検証されていません。 12のストアフロントでの23ページの検証において、STRUCTURED_DATAは46回の実行中28回で値を生成し、EMBEDDED_STATEはわずか6回でした。

MCP

1つのツール、inspect_web_field(url, field)が、構造化された証拠を返します — 散文ではありません。

{
  "mcpServers": {
    "scavenge": { "command": "python", "args": ["-m", "scavenge.mcp"] }
  }
}

サーバーは何も推論せず、スクレイピングコードを生成せず、モデルを呼び出しません。

構造化出力

{
  "schema_version": 3,
  "target": "https://example.com/product/123",
  "field": "price",
  "observations": [
    {
      "id": "raw_dom:0",
      "channel": "RAW_DOM",
      "normalized_value": {"kind": "money", "amount": "99.00", "currency": "USD"},
      "raw": "$99.00",
      "provenance": {"selector": "div.product-price"},
      "subject": {"scope": "PAGE", "key": "", "reason": ""},
      "status": "OK",
      "note": ""
    }
  ],
  "acquisition": {
    "http_status": 200, "http_bytes": 48213, "http_challenge": "",
    "render_status": "OK", "json_responses": 12
  },
  "warnings": []
}

アーキテクチャ

  MCP ─┐
       ├─→ evidence engine ─→ HTTP · raw DOM · structured data
  CLI ─┘                      embedded state · rendered DOM · network JSON

1つのエンジン。両方のインターフェースがそれを呼び出します。テストはCLIのJSONがエンジンのJSONと同じであることを検証します。

インストール

pip install git+https://github.com/aarohim24/Scavenge.git
python -m playwright install chromium     # required for rendered DOM and network channels
scavenge inspect https://example.com/p/1 --field price

まだPyPIにはありません — APIが外部からのフィードバックを一巡するまでは意図的に公開していません。

--no-renderはブラウザをスキップし、HTTPのみのチャネルを報告します。

セキュリティ境界

http/httpsのみ。file://、localhost、ループバック、リンクローカルおよびプライベート範囲は、リクエスト前に拒否されます — これはMCP下で、エージェントが人間の確認なしにURLを提供する場合に特に重要です。本文は512KB、JSONレスポンスは40に制限され、待機時間とrobots.txtの取得にも制限があります。robots.txtは尊重され、タイムアウトや到達不能なrobots.txtは決して許可として扱われません。キャプチャされたリクエストは再実行されず、認証済みリクエストは再発行されず、ページからの何も実行されません。

明示的に行わないこと

• どの観測結果が正しいかの判断。 v0.1では比較を一切公開しません。

• エンティティ解決。 ページの商品を2つ目のProductブロック、アップセルタイル、カート合計、ストアロケーター行から確実に区別できません。

• クロール、スケジュール、リンクの追跡。

• アンチボットシステムの回避。明らかなチャレンジを検出して報告しますが、決してバイパスしません。

• いかなるモードでもLLMを呼び出しません。

既知の制限事項

1. v0.1では比較機能なし。 以前のバージョンはEQUAL/DIFFERENT関係を公開していました。実世界の検証で、実際のストアフロントで生成されたDIFFERENTのすべてが異なるエンティティを比較していたため、この機能は修正ではなく削除されました。完全な結果はdocs/research/OSS-FINAL-CORRECTNESS.mdにあります。

2. 通貨はしばしばnull。 $は十数の通貨を指します。宣言された証拠がない場合、金額は保持され通貨は拒否されます。不明は一般的ですが、誤りは避けるべきです。

3. 補助通貨単位はモデル化されていません — Shopifyの2950と表示された29.50は異なる観測結果です。

4. 決定論的であるのはレポート生成であり、ウェブ自体ではありません。 同じバイト入力から同じレポート出力が得られます。同じURLが常に同じバイトを返すとは限りません。

5. レンダリングのブロックは名前付きシグナルからのみ検出されます。名前のない薄いシェルは検出されません。

6. robots.txtを尊重するアクセスでは、多くの大規模小売業者が完全に除外されます。

ライセンス

Apache-2.0。

ステータス

実験的v0.1。 技術的なフィードバックのために公開されており、本番環境用ではありません。APIは変更される可能性があります。12のストアフロントで23ページ、および決定論的フィクスチャスイートで検証されています。これは小さなサンプルであり、ベンチマークではありません。

研究記録 — このアイデアの以前のバージョンを破棄させた結果を含む — はdocs/research/にあります。