substrate-browser

Substrate

别再浪费 48K 个 token 来读取网页了。Substrate 可将典型内容页面压缩到大约 1–4K 个 token，让你的大模型真正用得上——而原始 HTML 约有 48K 个 token。

Substrate 是一个 MCP 服务，可让你的 AI Agent 拥有浏览网页的眼睛和双手。它会提取任意网页的压缩语义图，其中包含按钮、输入框、链接、下拉菜单、复选框及其精确像素坐标，并通过空间坐标处理点击、输入和选择操作。无需 CSS 选择器。无需 xpath。不会产生幻觉。

为什么重要

其他所有浏览器自动化方案都会把 token 浪费在噪声上：

方案	Token 数	提取耗时	大模型得到的内容
原始 HTML（page.content()）	约 48,000	5ms	完整 DOM 树——脚本、样式、隐藏元素、广告标记。大模型会淹没在噪声中，还会幻觉出对不可见元素的点击操作。
视觉（截图 + OCR）	约 8,000	约 800ms	一团像素。大模型能“看到”页面，却无法精确定位目标。点击位置会偏差 20px，表单也会操作失败。
Substrate	约 1,000–4,000	约 10–30ms	结构化 JSON：每个元素是什么、位于何处、处于什么状态。大模型第一次尝试就能点击正确的目标。

**计算方式：**一个约有 110 个元素的内容页面（例如 Wikipedia）可压缩到大约 2,300 个 token——约占典型 128K 上下文窗口的 1.8%。大模型空间用尽之前，大约可以容纳 55 次页面提取。使用原始 HTML 时，只能容纳 2 次。

Token 数量级为粗略估算，基于代表性页面的实时测量结果（example.com 约 84 个 token、Wikipedia 约 3.5K 个 token、Hacker News 首页约 4.4K 个 token，提取耗时 8–58ms）。具体数值会随页面密度变化；提取器会将输出上限设为 MAX_ELEMENTS=400，因此内容非常密集的页面会被截断，而非完整输出。计算方式很简单：对于一个约有 2.3K 个 token 的页面，⌊128K/2.3K⌋ ≈ 55 次提取。

真正的优势——更短的操作循环：

Without Substrate:                          With Substrate:
navigate → screenshot                       navigate
→ "I see a button" → click (wrong)          → {btn id=3 "Submit" [640,400]}
→ screenshot → "ah, more right"             → click(3) → done.
→ click → "not that either"                 
→ screenshot → ...                          2 tool calls. Task complete.
8-12 tool calls. Task complete.

这可不是微不足道的改进。每项网页任务的 API 调用次数减少 5–6 倍，延迟降低 5–6 倍，成本降低 5–6 倍。

工作原理

Substrate 通过 Model Context Protocol (MCP) 以无头 Chromium 浏览器的形式运行。你的大模型 Agent 可通过 10 个简单工具与它交互：

工具	功能
navigate	加载 URL，并获取页面图（最多 400 个元素）
click	通过数字 ID 点击任意元素
type_text	在输入框中输入文本（会先自动清空）
select_option	按值选择下拉选项
press_key	按下键盘按键（Escape、Enter、Tab、方向键、修饰键）
scroll	按视口高度的 80% 向上或向下滚动
screenshot	获取视觉快照和页面图
go_back / go_forward	浏览器历史记录导航
get_current_url	检查当前位置

每个导航和交互工具都会返回相同的压缩图（get_current_url 仅返回 URL；screenshot 返回图像和页面图）。大模型读取页面图，选择一个元素 ID，然后调用下一个工具。无需解读图像。无需解析 HTML。只需 ID 和坐标。

安装与设置

Substrate 是一个独立的 Model Context Protocol (MCP) 服务。无需编写代码即可使用——只需将它接入你的 AI 助手。

选项 1：Claude Desktop（推荐）

1. 打开 Claude Desktop 配置文件：
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
2. 在 mcpServers 块中添加 substrate-browser 服务：

{
  "mcpServers": {
    "substrate-browser": {
      "command": "npx",
      "args": ["-y", "substrate-browser"]
    }
  }
}

3. 重启 Claude Desktop。现在，你会看到可用的 10 个浏览器工具（带有一个小锤子图标），然后就可以让 Claude“访问 example.com，告诉我你看到了什么”。

（注意：Playwright 会在首次运行时自动下载 Chromium 二进制文件。这要求你的系统已安装 Node.js 20+。）

选项 2：从源代码运行（面向开发者）

如果你想修改提取逻辑或添加自己的工具：

git clone https://github.com/manuelinuxkr/substrate-b.git
cd substrate-b
npm install
npx playwright install chromium
npm run build
npm start

许可证

MIT