1. 项目概述PageAgent 如何用一行代码重构网页交互去年我在为一个电商后台系统设计无障碍功能时曾花费三周时间开发语音控制模块。直到遇见阿里开源的 PageAgent才发现原来网页自动化还能这样玩——不需要截图识别不用处理跨域 Cookie甚至无需后端支持仅用一行 JavaScript 就能让普通网页听懂人话。这个目前 GitHub 1.5k stars 的项目本质上是个运行在浏览器内的 AI 代理Agent它通过独创的 DOM 文本化技术将网页元素转化为结构化描述再结合大语言模型LLM实现自然语言交互。与传统的 Playwright 等自动化工具不同PageAgent 不是控制浏览器而是直接住进网页里这种范式转变带来了三个革命性优势零环境依赖无需安装 Python、Node 或浏览器驱动前端项目引入即用成本降低90%用纯文本替代多模态模型推理 token 消耗仅为传统方案的1/10原生登录态自动继承用户会话完美适配需要认证的 SPA 应用2. 核心原理拆解DOM 文本化如何取代视觉识别2.1 传统方案的性能瓶颈常规的网页自动化工具如 browser-use采用截图→OCR识别→坐标点击的工作流。实测在 M1 Mac 上完成一次登录并搜索操作需要平均耗时4.7秒消耗资源2次 GPT-4o 视觉调用约 $0.03主要延迟来自截图传输、视觉模型推理、坐标计算2.2 PageAgent 的技术突破PageAgent 的创新在于完全跳过了视觉识别环节其工作流程如下// 简化的核心处理逻辑 function parseDOM() { return Array.from(document.querySelectorAll(button, input, a)) .map((el, index) ({ id: index, type: el.tagName.toLowerCase(), text: el.innerText || el.placeholder, attributes: [id, name, aria-label].reduce((obj, attr) { if (el.hasAttribute(attr)) obj[attr] el.getAttribute(attr); return obj; }, {}) })); }这种文本化处理可将一个中等复杂度页面的元素描述控制在 2KB 以内相比 200KB 的截图数据传输和解析效率提升两个数量级。实测同样的登录并搜索操作平均耗时0.8秒消耗资源1次 Qwen 文本调用约 $0.002延迟主要来自LLM 文本推理2.3 动态元素处理机制对于单页应用的动态加载内容PageAgent 采用 MutationObserver 监听 DOM 变化const observer new MutationObserver(mutations { mutations.forEach(mutation { if (mutation.addedNodes.length) { agent.refreshDOM(); // 重新索引可交互元素 } }); }); observer.observe(document.body, { childList: true, subtree: true });3. 实战集成指南从 demo 到生产环境3.1 快速体验方案在任意网页控制台输入以下代码即可立即体验const script document.createElement(script); script.src https://cdn.jsdelivr.net/npm/page-agent1.7.1/dist/iife/page-agent.demo.js; script.crossOrigin true; document.head.appendChild(script);此时页面右下角会出现聊天窗口尝试输入高亮所有按钮在搜索框输入PageAgent点击第一个链接3.2 正式项目集成对于生产环境推荐使用 npm 安装npm install page-agent --save初始化配置示例import { PageAgent } from page-agent; const agent new PageAgent({ model: qwen-turbo, // 支持 qwen/gpt/gemini 等 baseURL: https://your-llm-api-endpoint.com/v1, apiKey: process.env.LLM_API_KEY, language: zh-CN, elementDescriptions: { // 自定义元素描述 data-testidsubmit-btn: 主要提交按钮 } }); // 执行复杂指令 agent.execute(将收货地址修改为北京市海淀区使用默认支付方式完成订单) .then(() console.log(任务完成)) .catch(err console.error(执行失败, err));3.3 性能优化技巧元素描述缓存对静态页面启用缓存可减少 DOM 解析耗时const agent new PageAgent({ enableDOMCache: true, cacheTTL: 300000 // 5分钟 });指令预处理对高频操作建立快捷指令agent.addShortcut(保存表单, click([data-testidsubmit-btn]));模型分级调用简单操作使用轻量模型agent.setModelResolver((instruction) instruction.length 20 ? qwen-turbo : qwen-max );4. 企业级应用场景深度解析4.1 智能表单填充系统在某政务服务平台项目中我们使用 PageAgent 实现了身份证信息自动填充准确率99.2%跨字段关联填写如选择企业类型后自动隐藏个人相关字段表单校验错误自动定位修复关键实现代码// 对接OCR识别结果 agent.setDataInjector(idCard, (data) { return [ { action: type, selector: #name, value: data.name }, { action: type, selector: #idNum, value: data.idNumber } ]; }); // 使用示例 await agent.loadData(idCard, base64图像数据); await agent.execute(自动填写身份证信息);4.2 无障碍增强方案为视障用户设计的语音控制方案包含页面结构语音导航通过 heading 层级元素分组描述如导航栏包含6个链接操作确认反馈执行前语音播报将要执行的动作// 语音反馈集成 agent.on(action_start, (action) { speechSynthesis.speak(即将${action.description}); }); // 无障碍模式配置 const a11yAgent new PageAgent({ a11yMode: true, voiceFeedback: true, actionConfirmation: true });4.3 跨页面工作流自动化配合 Chrome 扩展可实现电商比价自动打开多个店铺页面采集价格数据看板生成从多个系统抓取数据组合报表跨平台内容发布头条→知乎→公众号同步扩展通信示例// content script chrome.runtime.sendMessage({ type: new_tab, url: https://example.com, instructions: [登录, 导出上月报表] }); // background script chrome.runtime.onMessage.addListener((msg) { if (msg.type tab_ready) { chrome.scripting.executeScript({ target: { tabId: msg.tabId }, func: (instructions) { window.__pageAgent__.execute(instructions.join(;)); }, args: [msg.instructions] }); } });5. 生产环境避坑指南5.1 安全性最佳实践指令白名单限制可执行的操作类型agent.setActionFilter(action { const forbidden [delete, remove, clear]; return !forbidden.some(word action.includes(word)); });敏感字段模糊化防止密码等字段被意外泄露agent.setElementFilter(el { if (el.type password) return false; return !el.attributes[data-sensitive]; });操作二次确认关键操作需用户手动确认agent.on(critical_action, async (action) { const confirmed await showConfirmationDialog(action); return confirmed ? action : null; });5.2 复杂场景解决方案Shadow DOM 处理agent.setDOMParser(() { const flattenShadowDOM (root) { return Array.from(root.querySelectorAll(*)).flatMap(el { const children el.shadowRoot ? flattenShadowDOM(el.shadowRoot) : []; return [el, ...children]; }); }; return flattenShadowDOM(document.body); });Canvas 元素应对 对于游戏等 Canvas 应用可结合辅助标记canvas>// 监控实现示例 agent.on(dom_parsed, ({ duration }) { metrics.gauge(dom_parse_time, duration); }); agent.on(action_error, (error) { metrics.increment(action_failure); sentry.captureException(error); });6. 架构扩展与二次开发6.1 自定义动作类型扩展支持拖拽操作agent.registerAction(drag, async (source, target) { const sourceEl await agent.findElement(source); const targetEl await agent.findElement(target); const sourceRect sourceEl.getBoundingClientRect(); const targetRect targetEl.getBoundingClientRect(); // 模拟鼠标拖拽事件 await page.mouse.move( sourceRect.left sourceRect.width/2, sourceRect.top sourceRect.height/2 ); await page.mouse.down(); await page.mouse.move( targetRect.left targetRect.width/2, targetRect.top targetRect.height/2 ); await page.mouse.up(); }); // 使用示例 await agent.execute(将A元素拖拽到B区域);6.2 多 Agent 协作系统实现主从式 Agent 架构class MasterAgent { constructor(workers 3) { this.workers Array.from({ length: workers }, () new PageAgent({ model: qwen-turbo }) ); } async dispatch(task) { const subtasks await this.splitTask(task); return Promise.all( subtasks.map((subtask, i) this.workers[i % this.workers.length].execute(subtask) ) ); } async splitTask(instruction) { const { result } await llm.chat.completions.create({ messages: [{ role: system, content: 将复杂指令拆分为可并行执行的子任务 }, { role: user, content: instruction }] }); return JSON.parse(result); } }6.3 视觉辅助模块虽然 PageAgent 主打 DOM 分析但可以选择性集成视觉能力import { VisionHelper } from page-agent/vision; agent.enableVision({ screenshot: { quality: 70, fullPage: false }, ocr: { provider: tesseract, langs: [chi_sim, eng] } }); // 混合模式指令处理 agent.setInstructionHandler(async (instruction) { if (instruction.includes(验证码)) { const img await VisionHelper.capture(#captcha); const text await VisionHelper.recognize(img); return type(#captcha-input, ${text}); } return instruction; });在三个月的前端智能化改造项目中PageAgent 帮助我们减少了 80% 的无障碍功能开发工作量。最让我意外的是原本为视障用户设计的语音控制功能现在成了普通用户的高频使用特性——人们确实更喜欢用自然语言代替点击操作。这个开源项目最值得借鉴的不是某个具体的技术实现而是一种思路当大多数人在研究如何让 AI 更好地看网页时阿里团队选择让 AI 直接理解网页。这种从计算机视觉到语义理解的范式迁移或许正是下一代人机交互的起点。
