Page-Agent 怎么让 AI 操作网页：嵌入式 GUI Agent、表单自动化与权限边界

Sun, 12 Jul 2026 12:14:00 +0800

Page-Agent 的思路与让 Agent 控制整台浏览器不同：它把 JavaScript 放进你的网页，让页面本身拥有一个 GUI Agent。官方说明它以文本化 DOM 操作为主，不依赖截图、多模态模型、Python 或 headless browser；多页任务可选 Chrome 扩展，另有 Beta MCP Server。项目 README

这很适合给 ERP、CRM、后台表单或内部工具增加“用一句话完成一串操作”的辅助能力，但不等于可以绕过产品权限。Agent 能做的动作必须仍受页面已有的鉴权、服务端校验和人工确认约束。

Page-Agent 和浏览器自动化怎么选

目标	更合适的方案
给自家 Web 产品内嵌自然语言助手	Page-Agent
回归测试、跨站抓取、确定性脚本	Playwright 或 Puppeteer
让 coding agent 查网络、控制台和性能	Chrome DevTools MCP
控制用户真实 Chrome 并保留人工会话	browser-harness 一类工具

站内已有 browser-harness、Playwright、Puppeteer 对比。Page-Agent 的区别在于：它不是替代测试框架，而是把操作能力作为产品内功能交给用户或外部 Agent。

从 NPM 配置一个最小实例

先安装包：

`1`	`npm install page-agent`

再在前端入口创建实例。模型地址、密钥和允许的操作范围应由你的服务端或安全配置管理，不要把生产密钥直接写进浏览器代码。

import { PageAgent } from 'page-agent'

const agent = new PageAgent({
  model: 'qwen3.5-plus',
  baseURL: 'https://your-compatible-api.example/v1',
  apiKey: 'USE_A_SCOPED_KEY',
  language: 'zh-CN',
})

await agent.execute('在当前页面找到“新建客户”按钮，但不要提交表单')

上例的目标是验证 DOM 识别和按钮定位。真实业务中，apiKey 应替换成短期、限额、可撤销的调用方式；不要把万能密钥、用户 token 或管理端凭据交给页面脚本。

推荐的接入顺序：先只读，再草稿，最后提交

实际接入时，先选一个权限低、字段少的页面，例如客户列表的筛选或工单的草稿填写。第一阶段只开放“定位页面元素、读取可见文本、生成操作建议”，并用测试数据验证 Agent 能区分同名记录和不同状态。此时不要开放点击保存、上传附件、跳转到外部域名等动作。

第二阶段才允许填写表单。把 Agent 的输入限制为结构化业务参数，例如客户 ID、折扣比例和有效期，而不要只给一句“给张三打折”。前端在执行前将它准备写入的字段列成预览；服务端根据当前用户角色再次校验字段是否可写、值是否在范围内。用户确认后，页面再调用现有业务接口，不能让 Agent 直接拥有绕过接口的后门。

第三阶段才考虑提交。提交动作应走与人工按钮相同的 API、审计日志和二次确认流程；提交成功后读取服务端返回的对象 ID、版本号和错误信息，再把结果展示给用户。这样即使模型误解了自然语言，也会在预览、权限或服务端校验中的某一层被拦下。

把任务拆成可审核的阶段

表单自动化最容易出错的地方不是点击，而是对象和副作用。建议把流程拆成：

查找：只读取当前页面的可见字段和候选记录。
填充草稿：只写入本地表单，不提交、不上传附件。
展示差异：将将要写入的字段和值交给用户确认。
提交：仅在用户点击确认、服务端权限校验通过后执行。

例如，“给客户 A 创建 20% 折扣”不能直接交给 Agent。更安全的实现是让它生成表单草稿、显示客户 ID、价格规则和有效期，再由有权限的人提交。

把页面能力收敛成动作白名单

不要把所有 DOM 元素都当成可调用工具。可以在产品侧定义业务动作，如 searchCustomer、fillDiscountDraft、previewDiscount、submitDiscount，并分别标注只读、可撤销或有副作用。Agent 先选择动作，前端再执行对应的页面交互；对于删除、退款、邀请成员、导出数据等高风险动作，直接不注册，或始终要求用户手动点击确认。

同时记录每次执行的用户、页面、动作、输入摘要、结果和失败原因。日志应脱敏，不保存完整密钥、cookie 或客户敏感字段。出现误操作时，这些记录能回答“Agent 看到了什么、提议了什么、最后由谁确认”，而不是只剩一段无法复现的聊天记录。

登录、多页和 MCP 的边界

Page-Agent 可以使用页面已有的登录态，但这不应成为扩大权限的理由。应避免：

让 Agent 从自然语言中提取并展示 cookie、密码或验证码；
让它把登录后的数据发送到未审核的模型端点；
用“自动化”跳过二次确认、支付确认或角色审批；
把跨页能力默认开放给所有用户。

官方的 Chrome 扩展与 MCP Server 用于多页或外部 Agent 控制时，尤其要建立域名白名单、动作白名单和审计日志。Beta 能力应先放在测试环境，而不是直接接入生产后台。

上线前用一组真实任务验收

选三到五条来自客服或运营的真实低风险任务，例如“筛选本周待跟进客户”“给指定工单补齐草稿字段”“从订单页跳到对应客户页”。每条任务都准备成功样本、歧义样本和无权限样本：成功样本应走完预览；歧义样本必须追问或停止；无权限样本必须被后端拒绝且不泄露额外数据。

验收时不要只看 Agent 是否点到了按钮，还要检查首次响应时间、失败是否可解释、刷新页面后草稿是否符合预期、断网或模型超时是否保留未提交数据。通过后再逐步扩大到更多页面，而不是一次性给整个后台加上自然语言入口。

排错清单

问题	处理方式
找不到按钮或字段	检查 DOM 是否动态渲染、元素是否在 iframe/遮罩层内，以及页面文案是否稳定
Agent 选择了错误记录	给任务加入唯一 ID、只读预览和结果回显，避免只靠名称匹配
模型调用失败	检查兼容 API、限额、CORS 与密钥注入位置，不要在前端日志输出密钥
表单已填但提交结果不对	将“填表”和“提交”拆开，提交后读取服务端返回值并显示给用户

小结

Page-Agent 的落地重点不是“让页面能听懂一句话”，而是把自然语言动作限制在可观察、可撤销、可审批的产品流程里。先在只读查询和草稿填充上验证，再逐步开放有副作用的操作。

Page-Agent on KnightLi的博客