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 调用解释原因。您可以在两秒内看到这一点；引擎不会断言它。

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、环回地址、链路本地地址和私有地址范围在任何请求之前被拒绝——这在 MCP 下更为重要，因为代理提供的 URL 人类无法直接看到。请求体大小上限为 512 KB，JSON 响应上限为 40，有界等待，有界 robots 获取。遵守 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. 尊重 robots 的访问方式排除了许多大型零售商。

许可证

Apache-2.0。

状态

实验性 v0.1。 为技术反馈而发布，非生产用途。API 可能变更。已在 12 个商店页面的 23 页上经过验证，外加一套确定性测试套件；这是一个小样本，并非基准。

研究记录——包括导致早期版本想法失败的结果——位于 docs/research/。