用途
PageMap 旨在解决智能体浏览网页时的上下文窗口溢出问题。Playwright MCP 每页会输出 50-540KB 的可访问性快照，经过 2-3 次导航后就会撑爆上下文窗口；Firecrawl 和 Jina 虽能将 HTML 转为 markdown，但仅支持只读、无法交互。PageMap 将原始 HTML（10 万以上 token）转换为结构化、AI 可读的页面地图（2-5K token），实现约 97% 的 token 削减，让智能体以更少 token 读取并操作网页。
主要能力
- 13 个 MCP 工具：覆盖完整浏览工作流，包括 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 种页面类型自动检测：product_detail、listing、search_results、article、news、video、login、form、checkout、dashboard、help_faq、settings、error、documentation、landing、blocked，并针对每种类型应用优化提取。
- 电商深度覆盖：内置支持 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 同意和登录屏障检测。
- 障碍检测与提示：检测登录要求、机器人拦截、缺货、年龄验证、弹窗覆盖等问题，并添加 barrier 字段给出诊断和建议的下一步操作。
- Cookie 同意自动关闭：自动检测 7 家 CMP 提供商（Cookiebot、OneTrust、TrustArc、Didomi、Quantcast、Usercentrics 及通用回退），采用 5 级关闭级联：CMP JS API → Reject → Accept → Dismiss → Close symbol，默认遵循 GDPR 拒绝优先策略。
- 弹窗覆盖检测：基于 AX 树 role="dialog" 与 HTML 正则的两阶段检测，自动关闭促销弹窗（如 newsletter、exit-intent）。
- 机器人检测感知：识别 Cloudflare、Turnstile、reCAPTCHA、hCaptcha 和 Akamai，报告提供商并建议等待/重试策略。
- 过期引用恢复：当 DOM 变化导致引用失效时，返回明确指引以重新获取。
- 内容智能：支持 8 种 JSON-LD schema（Product、NewsArticle、VideoObject、FAQPage、Event、LocalBusiness、BreadcrumbList、ItemList）；从结构化数据和 DOM 回退中提取价格、评分、评论、描述、图片等元数据；两层缓存（缓存命中约 10ms、内容刷新约 500ms、完整重建约 1.5s），对未变更部分进行基于差异的更新；可选的 to_delta_packet() 序列化器输出摘要绑定的证据单元、声明候选、来源和权威标志，供下游记忆/审查系统使用，且不改变默认 MCP 输出。
- 本地化：从 URL 自动检测语言区域，针对 CJK 文字调整 token 预算。
使用方式
PageMap 可作为 MCP 服务器、Python SDK 和 CLI 使用。默认模式为本地 MCP 服务器，无需服务器设置。首次使用时自动安装 Chromium，无需手动执行 playwright install。
MCP 客户端配置：可添加到 Claude Code、Cursor、Windsurf 或 Claude Desktop。Claude Desktop（macOS）需使用 uvx 的绝对路径——运行 which uvx（例如 /opt/homebrew/bin/uvx）。VS Code（Copilot）在 .vscode/mcp.json 中使用 "servers" 而非 "mcpServers"。
Docker 镜像：Docker Hub 和 GitHub Container Registry 提供多架构镜像（amd64/arm64）。
离线处理（无浏览器）：暂未提供具体命令细节。
适用场景
- 智能体需要读取并操作网页（点击、填表、导航）的自动化任务。
- 电商价格、选项、评分、库存等结构化数据提取。
- 需要控制 token 消耗的网页浏览智能体。
- 需要处理 cookie 同意、弹窗、登录屏障等复杂页面场景。
限制
- 登录受限页面：PageMap 不管理会话或 cookie，认证需在外部处理。
- 强机器人检测（Cloudflare、Akamai）：可能阻止自动访问。PageMap 能检测提供商并建议策略，但无法绕过主动的机器人缓解措施。
- 私有网络访问：默认被阻止，需使用 --allow-local 标志或设置 PAGEMAP_ALLOW_LOCAL=1。
- iframe：由于浏览器安全策略，跨域 iframe 不可访问。
- 用户需自行遵守目标网站的服务条款和所有适用法律。
安全
PageMap 将所有网页内容视为不可信输入：SSRF 多层防御；提示注入防御（内容边界、角色前缀剥离、可疑内容标记）；符合 RFC 9309 的 robots.txt 合规（可用 --ignore-robots 退出）；资源守卫（DOM 节点限制、HTML 大小限制、响应大小限制）；会话隔离（每个会话有独立 cookie 和存储，自动清理）。
许可与定价
本地（STDIO）模式永久免费，自托管，基于 AGPL-3.0 开源。云 API 为托管多租户服务器，含认证、速率限制和基于积分的计费，需联系 retio1001@retio.ai 获取访问权限。商业许可选项同样联系该邮箱。
故障排除
- "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 手动安装。
