如何让 AI Agent 高效理解网页?Web Speed 用 MCP 把 HTML 噪声变成结构图谱
问题:AI Agent 面对 150KB 网页时的困境
如果你用 Claude Code 或 Cursor 让 AI Agent 分析一个网站首页,它大概率会收到一段超过 150,000 字符的原始 HTML——大量
、、SVG 图标代码、埋点脚本和无意义 div 层。Agent 需要消耗数百 Token 从这堆噪声中筛选出真实内容:导航栏写了什么、页面有哪些链接、有没有登录表单。
更糟糕的是,LLM 在处理原始 DOM 时经常编造元素 ID 和交互点——它看到 id="search-form" 就以为是合法的搜索表单路径,实际上这个 ID 可能已废弃。每次错误预测都是一轮额外的 API 调用,花钱又花时间。
这就是 Web Speed 想解决的问题:把面向人类的 HTML 噪声转化为 AI Agent 可确定性消费的结构化地图。
为什么这是真问题
一张典型网页的结构噪声比例惊人:
| 指标 | 典型值 |
|---|---|
| 原始 HTML 大小 | 150,000+ 字符 |
| 其中有意义的文本 | ~3,000-8,000 字符 |
| Token 浪费比例 | 90%-97% |
| 每页面多花费用 | $0.001-$0.01(视模型而定) |
传统方案是写 site-scraper——为每个网站写定制的选择器,但维护成本极高,网站改版就失效。或者用 Browser Use / Playwright 截图+视觉分析——但截图模式的 Token 成本是纯文本的 10-100 倍。
Web Speed 的方案:确定性结构映射
Web Speed 是一个纯 Python 的 MCP 工具,没有任何 LLM 依赖——它做的事情简单直接:获取 HTML,榨干所有非结构化噪声(脚本、样式、SVG、埋点),剩下的内容按确定的 JSON Schema 组织。
核心特点:
- 无 AI 内部:不依赖任何 LLM(OpenAI/Anthropic/Google 都不需要),纯规则驱动
- 97% Token 缩减:150KB HTML → ~4KB 结构化 JSON
- 确定性输出:同样的页面永远返回同样的 JSON 结构,不会幻觉
- MCP 原生:任何支持 MCP 协议的 AI 编码 Agent(Claude Code、Cursor、Codex)都能直接用
快速上手:安装与 MCP 配置
第一步:克隆仓库
git clone https://github.com/Dominic-Pi-Sunyer/web-speed-oss.git cd web-speed-oss/web-interpreter python3 -m venv venv source venv/bin/activate pip install -r requirements.txt
第二步:配置 MCP
将以下配置添加到 Claude Desktop 的配置文件:
{
"mcpServers": {
"web-speed": {
"command": "/absolute/path/to/web-interpreter/venv/bin/python",
"args": ["/absolute/path/to/web-interpreter/server.py"]
}
}
}
如果你使用 Cursor,在 Cursor MCP 设置中添加同样的配置即可。
核心功能实战
Web Speed 提供 6 个 MCP 工具,每个解决一个具体场景。
1. interpret_page — 全页面结构化分析
输入一个 URL,返回完整的结构地图:标题、导航栏、正文链接、表单字段、表格数据、文字段落。这是最常用的工具。
// 输出示例(简化和翻译后)
{
"url": "https://example.com/",
"page_type": "other",
"title": "Example Domain",
"headings": [
{ "level": 1, "text": "Example Domain" }
],
"navigation": [
{ "label": "首页", "url": "https://example.com/", "location": "header" }
],
"content_links": {
"total": 47,
"items": [
{ "label": "了解更多", "url": "https://iana.org/domains/example" }
]
},
"forms": [
{
"id": "search",
"method": "GET",
"fields": [
{ "name": "q", "type": "text", "label": "搜索", "required": false }
]
}
],
"tables": [],
"text_blocks": [
{ "tag": "p", "text": "本域名用于文档中的示例说明。" }
]
}
Agent 得到这段 JSON 后,可以立即知道:「这是一个页面,标题是 X,导航栏有 N 条链接,有一个搜索表单」。不需要从 150KB HTML 中自己翻找。
2. site_map — 一键抓取全站
如果你需要 Agent 了解一个网站的完整结构(比如分析竞品网站的产品目录),site_map 可以从根 URL 开始爬取所有页面,合并返回结构地图。
相比传统做法(逐页抓取 → 手动拼接 → 去重),site_map 一步到位。
3. page_type — 即时的页面分类
页面类型识别是 AI 浏览网页时的核心能力。Web Speed 通过结构特征推断页面类型:
| 页面特征 | 分类结果 |
|---|---|
| 包含密码输入框 | login |
| 大量列表项/卡片 | listing |
含 和多个段落 | article |
含 元素 | form |
| 几乎全是链接 | navigation |
// page_type("https://example.com/login")
{
"page_type": "login",
"title": "Sign In"
}
Agent 拿到 page_type: "login" 后就知道:「这是登录页,我不应该在这里抓取内容,直接跳转」。
4. submit_form — 表单提交
对于需要登录、搜索、筛选等交互操作的场景,submit_form 支持 GET/POST 方式提交表单,返回提交结果页的结构地图。
// Agent 先 interpret_page 获取表单字段
// 然后 submit_form 填写关键字段并提交
{
"url": "https://example.com/search",
"method": "GET",
"fields": { "q": "AI Agent" }
}
// 返回搜索结果的 interpret_page 格式
这在自动化测试、数据抓取场景中非常实用。
5. inspect_element — 深度探查
当需要了解某个特定元素的详细信息时(比如一个 CSS 选择器匹配的节点),inspect_element 返回该节点的完整结构数据,包括子元素、属性、文本内容。
缓存机制:全球加速的秘密武器
Web Speed 最巧妙的设计是共享 sitemap 缓存。当某个用户通过 Web Speed 访问一个网站后,该网站的 sitemap 会被发送到云端服务器。后续其他用户访问同一网站时,可以直接从缓存中获取,无需重新下载和解析 HTML。
目前缓存仅对付费 API 版本可用,但开源版本也支持本地文件缓存:
interpret_page("https://example.com/news")
适用场景总结
| 场景 | 推荐工具 | 理由 |
|---|---|---|
| 快速了解一个页面内容 | interpret_page | 一次调用获取全部关键信息 |
| 分析整个网站结构 | site_map | 全站爬取 → 结构索引 |
| 决定下一步操作 | page_type | 零成本分类,避免走错路径 |
| 与网站交互(搜索/登录) | submit_form | 带表单提交 + 结果返回 |
| 调试/反爬虫场景 | inspect_element | 深度探查特定元素 |
什么时候不需要 Web Speed? 如果你的 Agent 只需要访问 API 接口(JSON 数据),直接调用 API 比用 Web Speed 更高效。Web Speed 的场景是:Agent 必须以用户视角浏览网页,但又不希望被 HTML 噪声拖垮。
一句话总结:Web Speed 让 AI Agent 浏览网页时不再「读 HTML 源代码」,而是直接「查结构化地图」——就像人类不用读页面源码就能看新闻一样。
- GitHub(开源版):github.com/Dominic-Pi-Sunyer/web-speed-oss
- 官网/API 文档:getwebspeed.io