给 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 preview，puppeteer-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-core？
• Chrome 是自动下载、跳过下载，还是外部提供？
• 浏览器可执行文件是否真的存在？
• 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 官方立场，也不表示上游项目对该能力包背书。