突破前端反爬：Playwright 与 Markdown DOM 压缩算法

(第 61 篇：Agent 动力学之视觉感官)

当你要求 Agent 去检索网页资讯时，通用的实现是 requests.get(url)。但在如今满屏 React/Vue 单页面应用 (SPA)，且带着层层 Cloudflare 反爬盾的时代，原生的 HTTP GET 对于 Agent 来说就是瞎子。

要让 Agent 在当代互联网冲浪，必须赋予它操控无头浏览器 (Headless Browser) 的能力。在这一章中，我们将探讨如何利用 Playwright 结合 DOM 蒸馏算法，为智能体打造一双看透网页本质的眼睛。

1. 致命的 HTML Token 爆炸

当你使用 page.content() 拿到一个常见的电商网页时，里面充斥着大量不可见的 script 标签、冗长的 svg 定义，以及毫无语意的 Tailwind CSS 类名（如 class="flex mt-2 justify-center"）。

直接投喂 HTML 的后果：

1. Token 溢出：一个简单的首页 HTML 往往超过 100KB，直接塞爆模型的上下文窗口。
2. 噪声干扰：大模型会把由于排版需要的 CSS 类名误认为是代码逻辑，导致幻觉率飙升。
3. 解析成本：模型需要浪费大量的计算资源去“对齐”那些成对的 <div> 标签，而真正有价值的新闻标题只占不到 1%。

2. 核心架构：DOM 的“蒸馏”与 Markdown 化

工业级 Agent（如 Stagehand 或 Firecrawl）的核心逻辑：不在模型端解析 HTML，而在宿主机端完成信息蒸馏。

2.1 【核心源码】具备视觉感知的文本提取器

我们需要在 Playwright 运行环境中注入一段脚本，将 DOM 降维转换成语义清晰的 Markdown：

from bs4 import BeautifulSoup
import html2text

class BrowserEngine:
    """
    Agent 的“数字视网膜”：
    将杂乱无章的 HTML 像素世界转化为极简的语义 Markdown。
    """
    def __init__(self, page):
        self.page = page

    async def get_clean_snapshot(self) -> str:
        # 1. 物理移除所有的“交互噪音”
        await self.page.evaluate("""() => {
            const selectors = ['script', 'style', 'svg', 'noscript', 'nav', 'footer'];
            selectors.forEach(s => {
                document.querySelectorAll(s).forEach(el => el.remove());
            });
        }""")
        
        raw_html = await self.page.content()
        soup = BeautifulSoup(raw_html, 'html.parser')
        
        # 2. Markdown 转换：这是 LLM 最容易理解的“世界语”
        text_maker = html2text.HTML2Text()
        text_maker.ignore_links = False # 保留链接，这决定了 Agent 能否“顺着网线过去”
        text_maker.ignore_images = True
        
        # 将 DOM 深度降维
        clean_text = text_maker.handle(str(soup))
        return clean_text

    async def get_interactive_elements(self):
        """
        [极客加固]：给每一个可点击元素打上“电子标签”。
        这样大模型只需说“点击 [12] 号按钮”，而不是去写复杂的 CSS。
        """
        # ...利用 JS 遍历 DOM，给 button, a 标签加上 data-mcp-id 属性...
        pass

3. 面向意图的操控 (Semantic Locator)

传统自动化测试中，我们要写 page.locator('#order-btn-25').click()。这种强绑定的 ID 一旦网站前端改版（加个 div，改个 class），你的 Agent 当场就“吓死”在原地。

AI 时代的定位哲学： 你不再传确切的选择器。大模型只需下达意图：{"action": "click", "target": "确定下单按钮"}。 底层的 Playwright 控制器会利用 Embedding 语义搜索，在当前页面的“可交互列表”中找到最匹配的那一个元素执行物理点击。

4. 防爬与伪装：让 Agent 看起来像个人

Agent 在抓取网页时最怕遇到 403 Forbidden。

1. Stealth 模式：使用 playwright-stealth 模拟真实的显卡指纹、字体库、屏幕刷新率细节。
2. 行为轨迹随机化：禁止瞬间大跨度点击。通过代码模拟鼠标平滑滑过屏幕（Bezier Curve），模拟人类“犹豫”的输入速度。
3. Network 拦截：如果不需要图片，可以在路由层物理拦截 .png, .jpg 的加载。这不仅能极速提升 Agent 响应时间，还能节省 80% 的带宽成本。

5. Playwright 的工程打法：Locator 稳定性与可复盘调试

Playwright 的一条核心原则是：优先使用“面向用户”的定位方式（例如 role/text），让脚本对 DOM 结构变化更有韧性。 citeturn0search1

这对 Agent 来说同样重要： 你不希望“一个 class 名变化”就让整个任务崩溃。

建议把定位分成三层：

1. 第一层（最稳）：role/label/name 等可访问性信号（最接近用户意图）。
2. 第二层：文本近邻 + 结构锚点（例如某个标题下的第一个按钮）。
3. 第三层（兜底）：CSS/XPath（只在完全没办法时使用，并强制审计）。

调试方面： 不要只靠截图或视频猜问题。 Playwright 提供 trace viewer，用于复盘每一步操作、定位器、网络请求与耗时。 citeturn0search8

把 trace 作为“证据链”保存下来， 你才能复盘为什么 Agent 会点错、为什么被 403、为什么卡住。

6. DOM 蒸馏算法：从“全量 HTML”到“可推理 Markdown”要有明确步骤

蒸馏不是简单删标签。 一个可落地的 pipeline 至少包含：

1. 删除不可见与噪音节点（script/style/svg 等）。
2. 保留链接与结构（标题层级、列表、表格），否则模型无法导航。
3. 抽取交互元素清单（button/a/input），并给每个元素分配稳定 ID。
4. 输出双通道：
   • Markdown 快照（给模型推理）
   • 交互元素表（给执行器定位）

关键的工程约束： Markdown 快照必须有大小上限（字符数/节点数），超过就摘要或分块； 否则你只是把“HTML 爆炸”换成了“Markdown 爆炸”。

7. 工程风险：浏览器自动化是高权限工具，必须配最小权限与隔离

浏览器自动化不是“爬虫”，它是“远程操作能力”。 常见风险：

1. 信息泄露：页面中可能含有隐私信息，截图/trace 会把它落盘。
2. 提示词注入：网页内容可能诱导模型去执行危险操作（例如登录、支付、下载脚本）。
3. 资源耗尽：无头浏览器占用 CPU/内存很高，必须有超时与并发上限。

治理策略：

1. deny-by-default：默认只允许读取与截图，写入/提交操作需要 HITL。
2. sandbox：隔离浏览器 profile、下载目录与 cookie 存储。
3. 审计：保存 trace 与关键截图，但要做脱敏与访问控制。 citeturn0search8

8. 失败模式：为什么“能打开页面”不等于“能完成任务”

在 Agent 场景里，最常见的失败不是“打不开”，而是“卡在半路”：

1. 无法点击：覆盖层、cookie banner、动态按钮禁用。
2. 点击了但没效果：SPA 路由改变但 DOM 没刷新（或你监听错了）。
3. 等待条件错误：waitForSelector 等到永远，实际应该等网络 idle 或特定响应。
4. 被反爬拦截：403、验证码、指纹校验，导致页面内容与预期不一致。

治理策略的核心是“观察力”：

1. 每一步动作都记录：locator、目标元素快照、点击前后 URL/标题变化。
2. 遇到异常就收集证据：trace + 截图 + 关键网络响应。
3. 连续失败触发降级：转为只读抓取（不再点击），或者交给 HITL。

这就是为什么 trace viewer 比“肉眼看视频”更靠谱。 citeturn0search8

9. 最小可测：把“网页蒸馏”做成确定性组件

Agent 项目里最容易漂移的就是“网页蒸馏”： 同一个网页今天一个 DOM，明天一个 DOM。

建议至少做三类测试：

1. 固定 HTML fixture：确保你的“删除噪音 + Markdown 化”对固定输入是稳定输出。
2. 交互元素提取测试：确保按钮/链接的标号与文本抽取规则稳定。
3. 回归样本：对 5-10 个常见站点保留快照，定期跑对比（允许更新，但必须审计差异）。

注意：测试的目标不是“永远正确”，而是“漂移可见、失败可复盘”。

本章精粹

1. HTML 不是给模型读的：Markdown 才是。蒸馏数据是保证 Agent 理解准确性的唯一途径。
2. 语义定位优于硬编码：给 DOM 元素打上虚拟 ID，让模型通过 ID 操控，能有效规避前端改版带来的崩溃风险。
3. 视觉感知是闭环：不仅仅是读取文本。在关键步骤截图并利用 Vision 模型（如 Claude 3.5 Sonnet）进行审计，能极大提升 Agent 任务的成功率。

通过 Playwright，你的 Agent 真正走出了文件系统的文件夹，走向了浩瀚的互联网海洋。下一章，我们将讨论当网页点击已经不够用时，如何接管整台电脑的终极感官——【Computer Use 与屏幕解析：像人一样移动鼠标和识别截图的 VLM 架构】。

(本文完 - 深度解析系列 61 / 全文约 1600 字) (注：建议将网页蒸馏逻辑封装为单独的微服务，它将成为你 Agent 系统的“感知中继站”。)

参考与延伸（写作核验）

• Playwright Best Practices（定位器与稳定性建议）。 citeturn0search1
• Playwright Trace Viewer（可复盘证据链）。 citeturn0search8