PageMap

PageMap

PageMap 可将原始 HTML（100K+ 个令牌）转换为结构化、便于 AI 读取的页面地图（2-5K 个令牌），减少 97% 的令牌用量。它可作为 MCP 服务、Python SDK 和 CLI 使用，支持 16 种页面类型和 30 多个电商网站。Agent 可以读取、点击、输入并浏览任意网页。

“让你的 Agent 在网上看得见、动得了。”

---

为什么选择 PageMap？

Playwright MCP 会为每个页面生成 50-540KB 的无障碍快照，浏览 2-3 个页面后就会撑满上下文窗口。Firecrawl 和 Jina 会将 HTML 转换为 Markdown，但只能读取，无法交互。

PageMap 为你的 Agent 提供任意网页的精简、可操作视图：

	PageMap	Playwright MCP	Firecrawl	Jina Reader
每页令牌数	2-5K	6-50K	10-50K	10-50K
交互方式	点击 / 输入 / 选择 / 悬停	原始树解析	只读	只读
多页会话	无限	浏览 2-3 页后失效	不适用	不适用
任务成功率（94 项任务）	84.7%	61.5%	64.5%	57.8%
每项任务平均令牌数	2,710	13,737	13,888	11,424
94 项任务的成本	$1.06	$4.09	$3.98	$2.26

在 11 个电商网站、94 项静态任务和 7 种条件下进行基准测试。8,100 多项测试通过。

---

快速开始

首次使用时会自动安装 Chromium，无需手动运行 playwright install。

安装

pip install retio-pagemap

MCP 客户端配置

添加到 Claude Code、Cursor、Windsurf 或 Claude Desktop：

{
  "mcpServers": {
    "pagemap": {
      "command": "uvx",
      "args": ["retio-pagemap"]
    }
  }
}

Claude Desktop（macOS）：使用 uvx 的绝对路径——运行 which uvx（例如 /opt/homebrew/bin/uvx）。

VS Code（Copilot）：在 .vscode/mcp.json 中使用 "servers"，而不是 "mcpServers"。

Docker

docker run -p 8000:8000 retio1001/pagemap --transport http

---

功能

13 个 MCP 工具——读取与交互

不只是读取——你的 Agent 还能点击按钮、填写表单、选择选项、管理标签页并跨页面浏览。13 个工具覆盖完整的浏览工作流：

get_page_map · execute_action · fill_form · scroll_page · wait_for · take_screenshot · get_page_state · navigate_back · batch_get_page_map · open_tab · switch_tab · list_tabs · close_tab

16 种自动检测的页面类型

PageMap 会自动对页面分类，并针对每种类型采用优化的提取方式：

product_detail · listing · search_results · article · news · video · login · form · checkout · dashboard · help_faq · settings · error · documentation · landing · blocked

全面覆盖电商网站

内置支持 4 个类别的 30 多个主要电商网站：

• 全球大型平台 — Amazon、eBay、AliExpress、SHEIN、Walmart、Rakuten
• 全球时尚品牌 — Zara、H&M、Nike、Uniqlo、ASOS、Zalando、SSENSE、Farfetch、COS
• 韩国 — Coupang、Naver Shopping、Musinsa、29CM、W Concept、SSG、11st
• 日本/中国 — ZOZO、Tmall、JD.com、Taobao

结构化提取价格、选项（尺码/颜色）、评分和库存情况，并自动处理 Cookie 同意提示及检测登录拦截。

智能恢复

PageMap 可检测问题，并告知 Agent 应采取的操作：

• 障碍检测 — 需要登录？被机器人拦截？缺货？需要年龄验证？弹窗覆盖层？PageMap 会添加一个 barrier 字段，其中包含诊断结果和建议的后续步骤
• 自动关闭 Cookie 同意提示 — 自动检测 7 个 CMP 提供商（Cookiebot、OneTrust、TrustArc、Didomi、Quantcast、Usercentrics，以及通用回退方案）。采用 5 层关闭流程：CMP JS API → 拒绝 → 接受 → 忽略 → 关闭符号。默认采用 GDPR 优先拒绝策略
• 弹窗覆盖层检测 — 通过 AX 树 role="dialog" 和 HTML 正则表达式进行两阶段检测。自动关闭促销弹窗（新闻通讯、退出意图）
• 机器人检测提示 — 可检测 Cloudflare、Turnstile、reCAPTCHA、hCaptcha 和 Akamai。报告提供商，并建议等待／重试策略
• 过期引用恢复 — 当 DOM 变化导致引用失效时，PageMap 会返回明确的重新获取指引

内容智能

• 8 种 JSON-LD schema — Product、NewsArticle、VideoObject、FAQPage、Event、LocalBusiness、BreadcrumbList 和 ItemList
• 元数据提取 — 从结构化数据和 DOM 回退方案中提取价格、评分、评论、描述和图片
• 两层缓存 — 命中缓存（约 10 ms）、刷新内容（约 500 ms）、完整重建（约 1.5 s）。对未变化的部分进行基于差异的更新
• 增量证据包输出 - 可选的 to_delta_packet() 序列化器会输出与摘要绑定的证据单元、声明候选项、来源信息和权威性标记，供下游记忆／审核系统使用，且不会改变默认 MCP 输出

支持 10 种语言

根据 URL 自动检测区域设置。针对 CJK 脚本调整令牌预算。

语言	区域设置	语言	区域设置
英语	en	中文	zh
韩语	ko	西班牙语	es
日语	ja	意大利语	it
法语	fr	葡萄牙语	pt
德语	de	荷兰语	nl

---

部署

本地（STDIO）

默认模式。作为本地 MCP 服务运行，无需设置服务。

retio-pagemap

Docker

docker run -p 8000:8000 retio1001/pagemap --transport http

可在 Docker Hub 和 GitHub Container Registry 获取多架构映像（amd64/arm64）。

---

Python API

import asyncio
from pagemap.browser_session import BrowserSession
from pagemap.delta_serializer import to_delta_packet
from pagemap.page_map_builder import build_page_map_live
from pagemap.serializer import to_agent_prompt, to_json

async def main():
    async with BrowserSession() as session:
        page_map = await build_page_map_live(session, "https://example.com/product/123")
        print(to_agent_prompt(page_map))   # Agent-optimized text format
        print(to_json(page_map))           # Structured JSON
        print(to_delta_packet(page_map))   # Digest-bound evidence packet
        print(page_map.page_type)          # "product_detail"
        print(page_map.interactables)      # [Interactable(ref=1, role="button", ...)]
        print(page_map.metadata)           # {"name": "...", "price": "..."}

asyncio.run(main())

用于离线处理（无需浏览器）：

from pagemap.page_map_builder import build_page_map_offline

page_map = build_page_map_offline(open("page.html").read(), url="https://example.com/product/123")

---

安全

PageMap 将所有网页内容视为不可信输入：

• SSRF 防护 — 采用多层防护，抵御服务端请求伪造
• 提示词注入防护 — 内容边界、角色前缀剥离、可疑内容标记
• 遵循 robots.txt — 符合 RFC 9309。可通过 --ignore-robots 标记选择不遵循
• 资源保护 — DOM 节点数限制、HTML 大小限制、响应大小限制
• 会话隔离 — 每个会话都使用独立的 Cookie 和存储，并自动清理

本地开发：默认阻止私有 IP。使用 --allow-local 或 PAGEMAP_ALLOW_LOCAL=1。

免责声明

使用 PageMap 时，用户有责任遵守目标网站的服务条款及所有适用法律。

---

故障排除

“spawn uvx ENOENT”（macOS 上的 Claude Desktop） — Claude Desktop 不会继承 shell 的 PATH。运行 which uvx，并在配置中使用绝对路径。

首次加载页面耗时较长 — 首次导航时，Chromium 冷启动需要约 10～30 秒。后续页面会在 1～3 秒内加载。

localhost 被阻止 — 使用 --allow-local 标记或设置 PAGEMAP_ALLOW_LOCAL=1。

未找到 Chromium — 运行 pip install retio-pagemap && playwright install chromium 手动安装。

---

要求

• Python 3.11+
• Chromium（首次使用时自动安装）

社区

有疑问或想法？欢迎加入 GitHub Discussions 参与讨论。

开发

git clone https://github.com/Retio-ai/Retio-pagemap.git
cd Retio-pagemap
uv sync --group dev
playwright install chromium
uv run pytest --tb=short -q

定价

本地（STDIO） — 永久免费。可自托管，基于 AGPL-3.0 开源。

云 API — 托管式多租户服务，提供身份验证、速率限制和基于额度的计费。如需使用权限，请联系 [email protected]。

许可证

AGPL-3.0-only — 完整文本请参见 LICENSE。

如需了解商业许可选项，请联系 [email protected]。

---

面向 Agent

本节面向使用 PageMap 作为 MCP 工具的 AI Agent。

工具

工具	使用时机
get_page_map	从这里开始。 导航到某个 URL，并获取包含编号引用的完整结构化页面地图。
execute_action	使用上次 get_page_map 返回的引用编号进行点击、输入、选择或悬停。
fill_form	一次调用填写多个表单字段。比依次调用 execute_action 更高效。
get_page_state	查看当前 URL 和标题，无需完整重建页面地图。适用于可能触发导航的操作之后。
scroll_page	滚动页面以显示延迟加载的内容，然后再次调用 get_page_map。
wait_for	等待动态内容出现（例如搜索或提交表单后）。
take_screenshot	当仅凭 PageMap 无法明确判断时，捕获页面的视觉状态。
navigate_back	返回浏览器历史记录中的上一步。
open_tab	打开新的浏览器标签页并导航到指定 URL。
switch_tab	按索引切换到其他已打开的标签页。
list_tabs	列出所有已打开标签页的 URL 和标题。
close_tab	按索引关闭标签页。
batch_get_page_map	并行获取多个 URL。适用于比较任务。

输出格式

URL: https://example.com/product/123
Title: Product Name
Type: product_detail          # auto-detected page type

## Actions
[1] button: Add to cart (click)
[2] select: Size (select) — options: S, M, L, XL
[3] link: See all reviews (click)
...

## Info
Price: $49.99
Rating: 4.5 / 5 (128 reviews)
Description: ...

## Images
  [1] https://cdn.example.com/product.jpg

## Meta
Tokens: ~1,800 | Interactables: 24 | Generation: 380ms

• ## Actions — 页面上的每个交互元素及其稳定的 ref 编号。
• ## Info — 从 HTML 中提取的页面关键信息：价格、标题、评分、描述。
• ## Images — 产品/内容图片 URL。
• ## Meta — Token 数量、可交互元素数量、生成时间。

障碍检测

当 PageMap 遇到页面级障碍时，会在响应中包含 barrier 字段：

State:
  barrier: login_required
  barrier_hint: "Login form detected with email + password fields. Use fill_form to authenticate."

可能的障碍：cookie_consent、login_required、bot_blocked、out_of_stock、empty_results、error_page、age_verification、region_restricted、popup_overlay。

遇到障碍时： 按照 barrier_hint 中的指引操作。对于 bot_blocked，请等待后重试。对于 login_required，请使用 fill_form 填写凭据。

Ref 生命周期

引用由 get_page_map 分配，并且在页面状态发生变化前保持有效。

以下情况会导致引用失效：

• 页面导航到新的 URL
• 发生 DOM 变化（打开模态框、SPA 导航、切换手风琴菜单）
• execute_action 导致页面级变化

遇到过期引用错误时： 再次调用 get_page_map 获取新的引用，然后重试。

Token 预算行为

当页面超出 Token 预算时，内容将按以下顺序删减：

1. 首先移除导航菜单、页脚和侧边栏
2. 缩减次要正文内容
3. 始终保留 ## Actions 和 ## Info

如果发现缺少关键信息，请尝试使用 scroll_page 加载延迟内容，然后再次调用 get_page_map。

推荐工作流

1. get_page_map(url)          → read Actions + Info, pick refs
2. execute_action(ref, ...)   → interact
3. get_page_state()           → confirm navigation occurred
4. get_page_map(new_url)      → get fresh refs for next step

对于包含动态内容的页面（搜索结果、筛选器）：

1. get_page_map(url)
2. execute_action(ref, "click")    → trigger search/filter
3. wait_for(text="results")        → wait for content
4. get_page_map(url)               → get updated map

已知限制

• 需要登录的页面 — PageMap 不管理会话或 Cookie。必须通过外部方式处理身份验证。
• 强力机器人检测（Cloudflare、Akamai）— 可能会阻止自动访问。PageMap 会检测提供方并建议应对策略，但无法绕过主动的机器人防护。
• 访问专用网络 — 默认禁止。需要使用 --allow-local 标志。
• iframe — 由于浏览器安全策略，无法访问跨源 iframe。

---

PageMap — 面向 Agent 时代的结构化 Web 智能。