给 AI Agent 使用 Puppeteer 之前，先定义浏览器边界

给 AI Agent 使用 Puppeteer 之前先定义浏览器边界Puppeteer 是非常适合 AI coding agent 使用的工具。它用 Node.js API 控制 Chrome 或 Firefox可以做浏览器自动化、截图、网页抓取、页面检查、网络请求观察和重复性 Web 任务。但这也是风险来源。一旦 Agent 能打开浏览器它就可能接触真实网页、登录状态、页面内容、下载文件、截图、表单提交和本地缓存。第一个问题不应该是“能不能让 Agent 用 Puppeteer”而应该是Agent 能不能在最小权限下完成一个可复核的浏览器任务下面是一套更适合首次接入前使用的检查框架。1. 先区分两个安装路径Puppeteer 常见有两个安装方式npm i puppeteer完整包通常包含浏览器下载行为npm i puppeteer-core更轻的核心库需要自己提供浏览器可执行文件。这个选择对 Agent 很重要。如果只是检查本地页面或 CI previewpuppeteer-core加明确的executablePath可能更可控。如果需要快速隔离 smoke test完整包更方便但它会增加安装、缓存、浏览器版本和网络下载方面的变量。不要让 Agent 随便决定。它至少应该先说明准备安装哪个包是否会下载浏览器临时目录和浏览器缓存放在哪里是否需要访问网络哪个命令能证明第一次任务成功。2. 第一次运行必须产出证据一个好的 Puppeteer 首次运行不应该只输出“看起来没问题”。它应该产出小而明确的证据。可以接受的证据包括本地测试页截图受控 URL 的 HTML 片段单个页面的网络请求列表console log 捕获包含 URL、状态码、标题、selector 结果、时间戳的 JSON 报告。不应该接受的证据包括“我检查过页面没问题”“这段自动化应该能跑”“Puppeteer 已经安装”但没有运行证据来自个人登录账号的截图基础验证前就要求生产密钥或真实账号。对 AI coding agent 来说可以定一个简单规则没有产物就还不能算验证完成。3. 把浏览器访问当成权限边界Doramagic 的 Puppeteer 边界卡建议从最小权限、临时目录、可回滚配置开始。这是合理默认值。Agent 运行 Puppeteer 前应该先明确允许访问哪些 URL 或域名是否允许使用登录状态是否允许截图是否允许下载是否允许提交表单浏览器数据和临时文件写到哪里什么情况下必须立刻停止。例如只允许 Puppeteer 访问 http://localhost:3000。 不要使用现有浏览器 profile。 不要提交表单。 把一张截图和一个 JSON 报告保存到 ./artifacts/browser-smoke/。 如果页面跳转到 localhost 之外立刻停止并报告。这样可以防止一个简单 UI 检查变成开放式网页操作。4. 真实踩坑不要被忽略Doramagic 的 Puppeteer 能力包里记录了一些 source-linked pitfall例如安装行为、浏览器版本、包安全提醒、flaky test、缓存行为、Firefox viewport、浏览器二进制文件位置等问题。这些信息不应该被夸大成“Puppeteer 不安全”或“Puppeteer 有问题”。更准确的用法是把它们变成检查问题当前 Node 版本是什么项目安装的是puppeteer还是puppeteer-coreChrome 是自动下载、跳过下载还是外部提供浏览器可执行文件是否真的存在cache 目录是否临时且可删除smoke test 是否在目标浏览器上真的跑通这在 CI、容器、远程开发机里尤其重要因为那里的浏览器依赖往往和本机不同。5. 用 GO / HOLD / NO-GO 控制首次运行我会用这个规则判断 Agent 是否可以继续GO使用受控 URL产出截图或报告不使用现有用户 profile并且可以重复运行HOLD浏览器能打开但安装路径、缓存路径、可执行文件路径或目标 URL 不清楚NO-GO基础 smoke test 前就需要生产登录状态、私人数据或外部表单提交。这不是让 Agent 变得保守而是让浏览器自动化可复核。6. 更安全的第一条指令不要一上来就对 Agent 说“帮我搭一套浏览器自动化”。更好的第一条指令是基于 Puppeteer 能力说明为这个仓库设计一个最小安全浏览器 smoke test。 只使用本地或明确批准的 URL。 不要使用现有浏览器 profile。 不要提交表单不要使用凭据。 运行前先返回计划命令、预期产物、停止条件和回滚路径。这能迫使 Agent 在打开浏览器之前先暴露边界。7. 适合什么场景这套方法适合希望让 AI 宿主使用 Puppeteer 做截图、网页抓取、浏览器检查或 UI 自动化的团队。它不能替代 Puppeteer 官方文档也不能证明生产环境已经安全更不代表 Puppeteer 官方对这个能力包背书。更准确的理解是Puppeteer 给了 Agent 一双浏览器里的手边界规则决定这双手能碰哪里、什么时候必须停下。参考资料Doramagic 整理的独立 Puppeteer 项目说明书https://doramagic.ai/en/projects/puppeteer/manual/上游项目https://github.com/puppeteer/puppeteer声明本文基于 Doramagic 对 Puppeteer 的独立能力包整理不代表 Puppeteer 或 Google 官方立场也不表示上游项目对该能力包背书。