Scavenge — deterministische Web-Evidenz für Menschen und Coding-Agenten

Scavenge untersucht ein Feld auf einer Webseite und meldet jede Stelle, an der dieses Feld erscheint, was jede Darstellung aussagt und genau, woher jeder Wert stammt.

Es sammelt Feldbeobachtungen mit genauer Herkunft. Es bestimmt nicht, welche Beobachtung semantisch korrekt ist. Dieses Urteil erfordert Wissen über die Bedeutung der Seite, und die Engine ist bewusst nicht dazu in der Lage – siehe Warum es dort aufhört.

Was es tut

$ 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

Das rohe HTML sagt 99.00, die gerenderte Seite sagt 79.00, und ein API-Aufruf erklärt warum. Sie können das in zwei Sekunden sehen; die Engine behauptet es nicht.

Related MCP server: mcp-ux-vision

Warum es existiert

Eine Seite gibt dieselbe Tatsache an mehreren Stellen an – sichtbares HTML, JSON-LD, ein Hydration-Blob, das gerenderte DOM, eine XHR-Antwort – und sie widersprechen sich öfter, als man denkt. Herauszufinden, welche davon Ihr Feld enthalten, ist eine DevTools-Aufgabe, von Hand erledigt, einmal pro Ziel, für immer. Ein Agent kann es auch tun, aber nicht reproduzierbar und nicht mit genauer Herkunft.

Warum es dort aufhört

Das ursprüngliche Ziel war ehrgeiziger: deterministisch zu entscheiden, ob in verschiedenen Darstellungen gefundene Werte sich auf dasselbe reale Objekt bezogen, und zu berichten, wo sie übereinstimmten oder nicht.

Echte Onlineshops haben diese Annahme widerlegt. Werte, die vergleichbar aussahen, gehörten zu Empfehlungskarussells, Warenkörben, Finanzierungstabellen, Store-Locators, Produktvarianten und zweiten Product-Blöcken auf derselben Seite. Ein Validierungslauf über 12 Onlineshops ergab, dass jede von der Engine gemeldete Abweichung von dieser Art war – die Werte und die Herkunft waren richtig, der Vergleich war falsch.

Eine ordentliche Behebung wird zur Entitätsauflösung. Also hört Scavenge einen Schritt früher auf: die Beweise deterministisch sammeln und einen Menschen oder einen Agenten interpretieren lassen. Der vollständige Bericht, einschließlich der Ergebnisse, die das frühere Design zunichtemachten, befindet sich in docs/research/.

Unterstützte Felder

price und availability. Zwei, nicht „beliebig“.

Unterstützte Kanäle

RAW_DOM · STRUCTURED_DATA · EMBEDDED_STATE · RENDERED_DOM · NETWORK_JSON

Sie sind nicht gleich gut validiert. In einer 23-seitigen Validierung über 12 Onlineshops hinweg lieferte STRUCTURED_DATA in 28 von 46 Durchläufen Werte und EMBEDDED_STATE nur in 6.

MCP

Ein Werkzeug, inspect_web_field(url, field), das strukturierte Beweise zurückgibt – keine Prosa.

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

Der Server denkt über nichts nach, generiert keinen Scraping-Code und ruft kein Modell auf.

Strukturierte Ausgabe

{
  "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": []
}

Architektur

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

Eine Engine. Beide Schnittstellen rufen sie auf; ein Test stellt sicher, dass das JSON der CLI das JSON der Engine ist.

Installation

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

Noch nicht auf PyPI – bewusst, bis die API eine Runde externes Feedback überstanden hat.

--no-render überspringt den Browser und meldet die HTTP-only-Kanäle.

Sicherheitsgrenzen

Nur http/https. file://, localhost, Loopback, link-lokale und private Bereiche werden vor jeder Anfrage abgelehnt – was unter MCP wichtiger ist, wo ein Agent URLs liefert, ohne dass ein Mensch sie sieht. Antwortkörper auf 512 KB begrenzt, JSON-Antworten auf 40 begrenzt, begrenzte Wartezeiten, begrenzter Robots-Abruf. robots.txt wird beachtet, und ein Timeout oder eine nicht erreichbare robots.txt wird niemals als Erlaubnis behandelt. Keine aufgezeichnete Anfrage wird wiederholt, keine authentifizierte Anfrage erneut gesendet, nichts von einer Seite ausgeführt.

Was es explizit nicht tut

• Entscheiden, welche Beobachtung korrekt ist. v0.1 veröffentlicht überhaupt keinen Vergleich.

• Entitätsauflösung. Es kann nicht zuverlässig das Produkt der Seite von einem zweiten Product-Block, einer Upsell-Kachel, einem Warenkorb-Gesamtbetrag oder einer Store-Locator-Zeile unterscheiden.

• Crawlen, planen oder Links folgen.

• Anti-Bot-Systeme überwinden. Es erkennt eine offensichtliche Herausforderung und sagt dies; es umgeht niemals eine.

• Ein LLM aufrufen, in keinem Modus.

Bekannte Einschränkungen

1. Kein Vergleich in v0.1. Eine frühere Version veröffentlichte EQUAL/DIFFERENT-Beziehungen. Die reale Validierung ergab, dass jedes DIFFERENT, das es auf echten Onlineshops produzierte, zwei verschiedene Entitäten verglich, daher wurde das Feature entfernt statt repariert. Das vollständige Ergebnis befindet sich in docs/research/OSS-FINAL-CORRECTNESS.md.

2. Währung ist oft null. $ benennt ein Dutzend Währungen; ohne deklarierten Nachweis wird der Betrag behalten und die Währung abgelehnt. Unbekannt ist häufig; falsch sollte abwesend sein.

3. Kleinere Einheiten werden nicht modelliert – ein Shopify 2950 und ein angezeigtes 29.50 sind zwei verschiedene Beobachtungen.

4. Determinismus bezieht sich auf die Berichterstellung, nicht auf das Web. Gleiche Bytes rein, gleicher Bericht raus. Dieselbe URL liefert nicht immer dieselben Bytes.

5. Eine blockierte Darstellung wird nur anhand benannter Signale erkannt; eine dünne unbenannte Hülle nicht.

6. Robots-respektierender Zugriff schließt viele große Einzelhändler vollständig aus.

Lizenz

Apache-2.0.

Status

Experimentell v0.1. Veröffentlicht für technisches Feedback, nicht für die Produktion. Die API kann sich ändern. Es wurde auf 23 Seiten über 12 Onlineshops hinweg validiert, plus einer deterministischen Fixture-Suite; das ist eine kleine Stichprobe und kein Benchmark.

Der Forschungsbericht – einschließlich der Ergebnisse, die frühere Versionen dieser Idee zunichtemachten – befindet sich in docs/research/.