Scavenge — 인간과 코딩 에이전트를 위한 결정론적 웹 증거

Scavenge는 하나의 웹 페이지에서 하나의 필드를 검사하고 해당 필드가 나타나는 모든 위치, 각 표현이 말하는 내용, 그리고 각 값이 정확히 어디서 왔는지 보고합니다.

정확한 출처와 함께 필드 관찰 결과를 수집합니다. 어떤 관찰이 의미상 올바른지는 판단하지 않습니다. 그 판단은 페이지가 무엇을 의미하는지 알아야 하며, 엔진은 의도적으로 그 능력이 없습니다 — 왜 거기서 멈추는지를 참조하세요.

기능

$ 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 작업으로, 수동으로 수행되며, 대상당 한 번, 영원히 계속됩니다. 에이전트도 할 수 있지만, 재현 가능하지 않고 정확한 출처도 없습니다.

왜 거기서 멈추는지

원래 목표는 더 야심적이었습니다: 다른 표현에서 발견된 값이 동일한 실제 사물을 가리키는지 결정적으로 판단하고, 일치하거나 일치하지 않는 부분을 보고하는 것이었습니다.

실제 상점들이 그 가정을 깨뜨렸습니다. 비교 가능해 보이는 값들은 추천 캐러셀, 장바구니, 금융 테이블, 매장 찾기, 제품 변형, 그리고 동일 페이지의 두 번째 Product 블록에 속해 있었습니다. 12개 상점에 걸친 검증 실행에서 엔진이 보고한 모든 불일치가 그런 종류였습니다 — 값과 출처는 옳았지만, 비교가 틀렸습니다.

제대로 고치는 것은 엔터티 해결로 변합니다. 그래서 Scavenge는 한 단계 더 일찍 멈춥니다: 증거를 결정론적으로 수집하고 인간이나 에이전트가 해석하도록 맡깁니다. 이전 설계를 무효화한 결과를 포함한 전체 설명은 docs/research/에 있습니다.

지원되는 필드

price와 availability. 두 개, '임의'가 아닙니다.

지원되는 채널

RAW_DOM · STRUCTURED_DATA · EMBEDDED_STATE · RENDERED_DOM · NETWORK_JSON

균등하게 검증되지는 않았습니다. 12개 상점에 걸친 23페이지 검증에서 STRUCTURED_DATA는 46회 실행 중 28회에서 값을 생성했고, EMBEDDED_STATE는 6회에서만 생성했습니다.

MCP

하나의 도구, 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

하나의 엔진. 두 인터페이스 모두 호출합니다; 테스트는 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, loopback, 링크-로컬 및 사설 범위는 모든 요청 전에 거부됩니다 — 이는 인간이 보지 않고 에이전트가 URL을 제공하는 MCP에서 더 중요합니다. 본문은 512KB로 제한, JSON 응답은 40개로 제한, 대기 시간 제한, 로봇 가져오기 제한. robots.txt가 준수되며, 타임아웃 또는 접근 불가능한 robots.txt는 절대 허가로 간주되지 않습니다. 캡처된 요청이 재생되지 않으며, 인증된 요청이 재발행되지 않으며, 페이지에서 어떤 것도 실행되지 않습니다.

명시적으로 하지 않는 일

• 어떤 관찰이 올바른지 결정하지 않습니다. v0.1은 어떤 비교도 게시하지 않습니다.

• 엔터티 해결. 페이지의 제품을 두 번째 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. 로봇을 존중하는 접근은 많은 대형 소매업체를 완전히 배제합니다.

라이선스

Apache-2.0.

상태

실험적 v0.1. 생산용이 아닌 기술 피드백을 위해 게시되었습니다. API는 변경될 수 있습니다. 12개 상점의 23개 페이지와 결정론적 픽스처 스위트에서 검증되었습니다; 이는 작은 샘플이며 벤치마크가 아닙니다.

연구 기록 — 이 아이디어의 이전 버전을 무효화한 결과를 포함하여 — 는 docs/research/에 있습니다.