page-agent 扩展API完全指南window.PAGE_AGENT_EXT 如何从网页触发多页任务【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agentpage-agent是一个用 JavaScript 编写的页面内 GUI Agent可以用自然语言操控网页界面。它的浏览器扩展版更进一步通过window.PAGE_AGENT_EXT扩展 API你的网页 JavaScript 可以直接触发跨多个标签页的浏览器自动化任务——填表单、点按钮、开新标签页、切换页面全部由一行execute()调用完成。本文带你从零理解这个 API 的授权机制、参数配置与多页任务原理。为什么需要扩展 APIpage-agent 有两种使用形态形态能力入口页面内库npm 包只能操控当前页面DOMPageAgent.ts浏览器扩展 API可跨标签页操控整个浏览器窗口window.PAGE_AGENT_EXT扩展 API 的核心价值当任务需要打开 A 页面查数据再到 B 页面填写时普通页面脚本无能为力而扩展 API 可以让 Agent 自由地开新标签页、切换标签页、关闭标签页。注入原理Token 校验与三层架构理解window.PAGE_AGENT_EXT从哪来先要知道扩展的三层隔离设计源码见 content.ts隔离世界Isolated World扩展的 Content Script 读取扩展侧的 token并与页面localStorage中的 token 比对。页面 JS 无法篡改扩展侧 token保证授权可信。主世界注入Main Worldtoken 匹配成功后扩展才注入 main-world.js在window上挂载PAGE_AGENT_EXT和PAGE_AGENT_EXT_VERSION。消息桥接execute()并不直接操作浏览器而是通过postMessage把任务发给 Content Script由其中的 MultiPageAgent 真正执行事件再逐层回传给你的回调函数。 这就是为什么页面脚本里要轮询等待window.PAGE_AGENT_EXT出现——注入发生在页面加载之后。授权三步走获取与配置 Token扩展拥有页面访问、导航、多标签控制等宽权限因此必须显式授权打开扩展的侧边栏面板Side Panel复制你的授权 token在信任该 Agent 的网页中把 token 写入localStoragelocalStorage.setItem(PageAgentExtUserAuthToken, 你的token)刷新页面控制台出现Auth tokens match日志API 即已注入。⚠️安全建议只把 token 配置在你信任的应用域名下避免被其他站点滥用。API 速览execute 与 stopwindow.PAGE_AGENT_EXT命名空间只有两个核心成员完整类型定义见 extension_api.mdexecute(task, config)— 执行一个任务const result await window.PAGE_AGENT_EXT.execute( 打开示例站点把搜索结果第一页的标题汇总, { baseURL: https://api.openai.com/v1, model: gpt-4o, apiKey: 你的API密钥, onActivity: (a) console.log(Agent 动作:, a), } )task自然语言任务描述字符串必填configLLM 配置 回调必填返回值PromiseExecutionResult包含success、data结果文本、history完整执行历史stop()— 中止当前任务window.PAGE_AGENT_EXT.stop()同时window.PAGE_AGENT_EXT_VERSION提供版本字符串可在调用主 API 前先做能力检测。配置项详解includeInitialTab 是灵魂参数参数类型默认说明baseURL/modelstring必填LLM 接口地址与模型名apiKeystring可选LLM 密钥systemInstructionstring可选全局系统级指令includeInitialTabbooleantrue是否把发起任务的当前标签页纳入任务experimentalIncludeAllTabsbooleanfalse实验特性控制窗口内所有未固定标签页onStatusChangecallback可选状态变化回调onActivitycallback可选每一步动作回调onHistoryUpdatecallback可选完整历史更新回调includeInitialTab的典型用法假设你的网页是一个任务发起台真正的操作对象是别的页面——此时设为falseAgent 会新开标签页干活不干扰当前页。多页任务如何工作三个标签页工具多页能力由 MultiPageAgent 编排底层是 TabsController。Agent 被注入了三个自定义工具tabTools.ts工具作用open_new_tab打开新标签页并设为当前页switch_to_tab切换到已有标签页继续操作close_tab关闭标签页每个步骤开始前Agent 会先同步最新的标签页状态并等待页面加载完成因此你随时手动开的标签页也能被 Agent 感知。任务结束后标签组会被自动清理。用回调实时跟踪进度onStatusChange: (status) { // status: idle | running | completed | error | stopped updateUI(status) }, onActivity: (activity) { // thinking / executing / executed / retrying / error appendLog(activity) }配合onHistoryUpdate你可以把 Agent 的每一步思考—动作—观察实时渲染成时间线 UI这正是许多产品用它做AI 操作可视化的原因。限制与常见问题仅限普通浏览器窗口扩展依赖 Tab Group API在弹出窗口和 PWA 应用窗口中不生效。同时只能跑一个任务Agent 正在运行时再次execute会直接返回错误提示需等待上一个任务结束。API 没出现按顺序检查token 是否一致 → 是否刷新过页面 → 控制台有无Auth tokens match日志。TypeScript 类型npm install page-agent/core即可获得ExecuteConfig、ExecutionResult等完整类型无需手写声明。小结window.PAGE_AGENT_EXT的本质是一条受 token 保护的消息通道你的网页负责发起任务和渲染进度扩展负责跨标签页的浏览器操作。三步授权、一个execute调用就能把多页浏览器操作变成一段可嵌入任何网页的 JavaScript——这就是 page-agent 扩展 API 的完整玩法。更多细节请查阅官方文档 packages/extension/docs/extension_api.md。【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考