Page Agent 中文指南用纯 JavaScript 为网页接入自然语言 GUI Agent【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agentPage Agent 是一个纯 JS 实现的 GUI Agent它直接运行在网页内部让你可以用自然语言指令操控 Web 应用——无需后端服务、无需 Python、无需浏览器插件。本文将以docs/README-zh.md为主线结合仓库源码packages/core、packages/llms、packages/page-controller、packages/page-agent等深入讲解其集成方式、配置参数与底层工作原理读完你就能在自己的产品里以「一行脚本」接入一个可对话、可操作的 AI 副驾驶。什么是 Page AgentPage Agent即page-agentnpm 包是一个客户端网页增强的 GUI Agent 框架你只需要在页面中引入一段 JavaScript页面就拥有了自己的 AI Agent能够理解自然语言任务并像真人一样操作页面元素点击、输入、滚动、下拉选择等。它的核心设计主张是纯页面内 JavaScript不需要浏览器插件、Python 环境或无头浏览器一切发生在你的网页里基于文本的 DOM 操作不依赖截图因此不需要多模态模型也不需要特殊权限自备 LLM支持大多数主流模型包括本地部署模型完全由你自己掌控可选的 Chrome 扩展与 MCP ServerBeta需要跨页面任务时再引入额外组件。从仓库结构看整个能力由若干分层包组合而成见 packages包职责packages/page-agent对外入口组合核心、页面控制器与 UI 面板packages/coreAgent 主循环、工具系统、事件系统、提示词组装packages/llmsLLM 客户端封装OpenAI 兼容协议与重试机制packages/page-controllerDOM 树提取、元素交互、遮罩层等页面控制packages/uiAgent 控制面板历史记录、活动反馈、输入框其中PageAgent类的构造逻辑见 PageAgent.ts清晰展示了这种组合关系它同时创建了PageController页面控制与PanelUI 面板并继承PageAgentCore核心主循环。这意味着「看得见的面板」和「操作页面的引擎」可以独立工作。应用场景SaaS AI Copilot几行代码为你的产品加上 AI 副驾驶无需重写后端。智能表单填写把 20 次点击变成一句话。ERP、CRM、管理后台的最佳拍档。无障碍增强用自然语言让任何网页无障碍。语音指令、屏幕阅读器零门槛。跨页面 Agent通过可选的 Chrome 扩展 让你的 Web Agent 跨标签页工作。MCP 接入通过 MCP 为现有 Agent 加入浏览器控制能力。快速开始方式一一行脚本接入体验 Demo最快的方式是使用官方免费的 Demo LLM在你的页面 HTML 中直接引入script srchttps://registry.npmmirror.com/page-agent/1.12.3/files/dist/iife/page-agent.demo.js crossoriginanonymous /script⚠️ 仅用于技术评估。该 Demo CDN 使用了免费的测试 LLM API使用即表示你同意其 条款。加载后脚本会自动创建一个 Demo Agent并在页面上展示控制面板。几个实用的 URL 参数对应 demo.ts 中的解析逻辑参数说明默认值autoInitfalse只加载脚本不自动创建 Demo Agent之后可用new window.PageAgent(...)手动初始化并使用自定义 LLM自动初始化model指定模型名qwen3.5-plusbaseURL指定模型 API 地址Demo 测试 APIapiKey指定 API KeyDemo Keylang界面语言zh-CN或en-USzh-CNshowPanel是否显示控制面板true/falsetrue脚本加载成功后会将PageAgent挂载到window.PageAgent同时清理可能存在的旧实例避免重复注入因此你可以在控制台或后续代码中随时手动创建 Agent。方式二NPM 安装正式集成npm install page-agentimport { PageAgent } from page-agent const agent new PageAgent({ model: qwen3.5-plus, baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1, apiKey: YOUR_API_KEY, language: zh-CN, }) await agent.execute(点击登录按钮)agent.execute(task)会返回一个ExecutionResult其中包含success是否成功、dataAgent 的最终回答文本以及完整的history历史事件流可供回放与调试。当 Agent 判定任务完成时会调用内置的done工具execute随即返回结果见 PageAgentCore.ts。配置参数详解PageAgent的配置类型是PageAgentConfig它是AgentConfig PageControllerConfig OmitPanelConfig, language的组合见 PageAgent.ts。核心配置定义在 types.ts 中下面按用途分组说明。LLM 相关来自packages/llms参数说明默认值model模型名称必填无baseURLOpenAI 兼容的 API 地址必填无apiKeyAPI 密钥空maxRetriesLLM 调用失败时的最大重试次数2temperature温度参数已废弃不再是标准参数许多新模型会直接拒绝请改用transformRequestBody为已验证的模型单独设置不发送transformRequestBody在请求发出前改写请求体用于实现供应商特有的参数如缓存提示原样返回disableNamedToolChoice移除请求中的tool_choice字段用于修复部分 LLM 的Invalid tool_choice type: object报错falsecustomFetch自定义 fetch 函数用于定制请求头、凭据、代理等全局fetchparseLLMConfig见 packages/llms/src/index.ts会在运行时校验缺少baseURL或model会直接抛出错误而maxRetries、disableNamedToolChoice、customFetch等均提供了合理的默认兜底。提示如果模型不支持强制指定工具名即tool_choice传对象可以设置disableNamedToolChoice: true来绕过见 OpenAIClient.ts。行为与任务控制参数说明默认值maxSteps单次任务允许的最大步数40stepDelay每步之间的等待间隔秒用于给页面留出响应时间0.4languageAgent 工作语言与界面语言zh-CN或en-US—onAskUser当 Agent 需要向用户提问时的回调未设置则禁用ask_user工具无customTools自定义/覆盖/移除内置工具值为tool(...)或null移除无instructions.system全局系统级指令作用于所有任务无instructions.getPageInstructions每步执行前根据当前 URL 动态返回页面级指令无transformPageContent在把页面内容发送给 LLM 之前做转换如敏感数据脱敏无customSystemPrompt完全覆盖默认系统提示词实验性慎用无experimentalScriptExecutionTool是否启用可在页面上执行生成 JS 代码的实验性工具falseexperimentalLlmsTxt是否从当前站点抓取/llms.txt作为上下文实验性false生命周期钩子均标注为实验性onBeforeTask、onAfterTask、onBeforeStep、onAfterStep、onDispose。它们接收 agent 实例以及步数/历史/结果作为参数可在主循环的对应时机注入自定义逻辑见 types.ts。一个实用的脱敏示例——屏蔽页面内容中的手机号来自 types.ts 的文档注释const agent new PageAgent({ model: qwen3.5-plus, baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1, apiKey: YOUR_API_KEY, transformPageContent: async (content) { return content.replace(/1[3-9]\d{9}/g, ***********) }, })底层工作原理Re-act Agent 主循环PageAgentCore实现了经典的 Re-actReason Act循环见 PageAgentCore.ts 的注释说明step ├─ observe 收集当前环境与上下文信息 ├─ think 调用 LLM │ ├─ reflection评估历史、生成记忆、做短期规划 │ └─ action 给出接近下一个目标的行为 └─ act 执行该行为 loop每一步中Agent 会依次刷新页面浏览器状态getBrowserState→ 组装系统提示词与用户提示词 → 调用 LLM → 解析出「反思」与「动作」→ 执行对应工具 → 将步骤写回历史。提示词中会注入结构化的agent_state用户请求与步数信息、agent_history历史步骤、观察与用户接管记录以及browser_state页面头部、交互元素简化 HTML、页脚滚动提示组装逻辑见#assembleUserPromptPageAgentCore.ts。反思先于行动Reflection-before-actionPageAgent 的每一步都要求 LLM 先输出三部分反思内容再选择动作evaluation_previous_goal上一步动作达成了多少目标memory需要记住的关键信息next_goal下一步要完成什么。这些字段会进入MacroTool的输入结构见 types.ts。#packMacroTool会把所有内置/自定义工具合并成一个「每步必调」的大工具PageAgentCore.ts强制模型每一步都进行反思并做出决策从而保证行为可解释、可追踪。内置工具集工具定义在 packages/core/src/tools/index.ts 中工具作用done完成任务附上对用户的最终回复与成功标志wait等待若干秒自动扣除 LLM 调用耗时等待页面或数据加载完成ask_user向用户提问并等待回答需要配置onAskUserclick_element_by_index按索引点击元素input_text点击并输入文本select_dropdown_option按选项文本选择下拉项scroll垂直滚动页面或指定容器scroll_horizontally水平滚动execute_javascript在页面执行 JS实验性需显式开启且必须配合AbortSignal这些工具通过PageController见 PageController.ts执行真实的 DOM 操作。PageController每次会从当前页面提取交互元素的简化 HTML 树并建立索引映射对应browser-use中的eval_page与selector_mapLLM 只需引用元素索引即可操作完全不需要截图。事件系统与信息流Agent 提供两类事件反馈见 PageAgentCore.tsHistory Eventshistorychange事件持久的步骤、观察、用户接管、错误记录构成 Agent 的记忆会跨步骤进入 LLM 上下文Activity Eventsactivity事件瞬时 UI 反馈thinking / executing / executed / retrying / error只用于界面展示不进入 LLM 上下文。状态机则通过statuschange事件对外暴露取值为idle → running → completed / error / stopped。内置控制面板packages/ui中的Panel会渲染一个可折叠的控制面板头部区域展示实时活动状态历史区域直接渲染agent.history。这种「历史即单一事实来源、活动只反映当下」的架构保证了数据一致性见 Panel.ts。面板还负责把用户的回答回传给 Agent 的ask_user工具。进阶跨页面与外部 Agent 接入当单页面内 Agent 无法满足需求时仓库还提供了两个可选组件Chrome 扩展packages/extension为页面内 Agent 提供跨标签页、跨页面任务能力可控制多个页面同时执行MCP ServerBetapackages/mcp通过 MCP 协议把浏览器控制能力暴露给外部 Agent 客户端让现有 Agent 生态如各类 LLM 客户端也能驱动浏览器。贡献与致谢欢迎社区贡献请参阅 CONTRIBUTING.md 了解安装与贡献指南提交 issue 或 PR 之前请先阅读作者声明与 行为准则。注意仓库不接受未经实质性人类参与、完全由 Bot 或 Agent 自动生成的代码。本项目基于browser-use的优秀工作构建。DOM 处理组件与提示词派生自 browser-useMIT License。PageAgent专为客户端网页增强设计不是服务端自动化工具。项目以 MIT License 开源。相关本地开发与文档可继续阅读 docs/developer-guide.md 与 docs/CHANGELOG.md。【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Page Agent 中文指南：用纯 JavaScript 为网页接入自然语言 GUI Agent
Page Agent 中文指南用纯 JavaScript 为网页接入自然语言 GUI Agent【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agentPage Agent 是一个纯 JS 实现的 GUI Agent它直接运行在网页内部让你可以用自然语言指令操控 Web 应用——无需后端服务、无需 Python、无需浏览器插件。本文将以docs/README-zh.md为主线结合仓库源码packages/core、packages/llms、packages/page-controller、packages/page-agent等深入讲解其集成方式、配置参数与底层工作原理读完你就能在自己的产品里以「一行脚本」接入一个可对话、可操作的 AI 副驾驶。什么是 Page AgentPage Agent即page-agentnpm 包是一个客户端网页增强的 GUI Agent 框架你只需要在页面中引入一段 JavaScript页面就拥有了自己的 AI Agent能够理解自然语言任务并像真人一样操作页面元素点击、输入、滚动、下拉选择等。它的核心设计主张是纯页面内 JavaScript不需要浏览器插件、Python 环境或无头浏览器一切发生在你的网页里基于文本的 DOM 操作不依赖截图因此不需要多模态模型也不需要特殊权限自备 LLM支持大多数主流模型包括本地部署模型完全由你自己掌控可选的 Chrome 扩展与 MCP ServerBeta需要跨页面任务时再引入额外组件。从仓库结构看整个能力由若干分层包组合而成见 packages包职责packages/page-agent对外入口组合核心、页面控制器与 UI 面板packages/coreAgent 主循环、工具系统、事件系统、提示词组装packages/llmsLLM 客户端封装OpenAI 兼容协议与重试机制packages/page-controllerDOM 树提取、元素交互、遮罩层等页面控制packages/uiAgent 控制面板历史记录、活动反馈、输入框其中PageAgent类的构造逻辑见 PageAgent.ts清晰展示了这种组合关系它同时创建了PageController页面控制与PanelUI 面板并继承PageAgentCore核心主循环。这意味着「看得见的面板」和「操作页面的引擎」可以独立工作。应用场景SaaS AI Copilot几行代码为你的产品加上 AI 副驾驶无需重写后端。智能表单填写把 20 次点击变成一句话。ERP、CRM、管理后台的最佳拍档。无障碍增强用自然语言让任何网页无障碍。语音指令、屏幕阅读器零门槛。跨页面 Agent通过可选的 Chrome 扩展 让你的 Web Agent 跨标签页工作。MCP 接入通过 MCP 为现有 Agent 加入浏览器控制能力。快速开始方式一一行脚本接入体验 Demo最快的方式是使用官方免费的 Demo LLM在你的页面 HTML 中直接引入script srchttps://registry.npmmirror.com/page-agent/1.12.3/files/dist/iife/page-agent.demo.js crossoriginanonymous /script⚠️ 仅用于技术评估。该 Demo CDN 使用了免费的测试 LLM API使用即表示你同意其 条款。加载后脚本会自动创建一个 Demo Agent并在页面上展示控制面板。几个实用的 URL 参数对应 demo.ts 中的解析逻辑参数说明默认值autoInitfalse只加载脚本不自动创建 Demo Agent之后可用new window.PageAgent(...)手动初始化并使用自定义 LLM自动初始化model指定模型名qwen3.5-plusbaseURL指定模型 API 地址Demo 测试 APIapiKey指定 API KeyDemo Keylang界面语言zh-CN或en-USzh-CNshowPanel是否显示控制面板true/falsetrue脚本加载成功后会将PageAgent挂载到window.PageAgent同时清理可能存在的旧实例避免重复注入因此你可以在控制台或后续代码中随时手动创建 Agent。方式二NPM 安装正式集成npm install page-agentimport { PageAgent } from page-agent const agent new PageAgent({ model: qwen3.5-plus, baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1, apiKey: YOUR_API_KEY, language: zh-CN, }) await agent.execute(点击登录按钮)agent.execute(task)会返回一个ExecutionResult其中包含success是否成功、dataAgent 的最终回答文本以及完整的history历史事件流可供回放与调试。当 Agent 判定任务完成时会调用内置的done工具execute随即返回结果见 PageAgentCore.ts。配置参数详解PageAgent的配置类型是PageAgentConfig它是AgentConfig PageControllerConfig OmitPanelConfig, language的组合见 PageAgent.ts。核心配置定义在 types.ts 中下面按用途分组说明。LLM 相关来自packages/llms参数说明默认值model模型名称必填无baseURLOpenAI 兼容的 API 地址必填无apiKeyAPI 密钥空maxRetriesLLM 调用失败时的最大重试次数2temperature温度参数已废弃不再是标准参数许多新模型会直接拒绝请改用transformRequestBody为已验证的模型单独设置不发送transformRequestBody在请求发出前改写请求体用于实现供应商特有的参数如缓存提示原样返回disableNamedToolChoice移除请求中的tool_choice字段用于修复部分 LLM 的Invalid tool_choice type: object报错falsecustomFetch自定义 fetch 函数用于定制请求头、凭据、代理等全局fetchparseLLMConfig见 packages/llms/src/index.ts会在运行时校验缺少baseURL或model会直接抛出错误而maxRetries、disableNamedToolChoice、customFetch等均提供了合理的默认兜底。提示如果模型不支持强制指定工具名即tool_choice传对象可以设置disableNamedToolChoice: true来绕过见 OpenAIClient.ts。行为与任务控制参数说明默认值maxSteps单次任务允许的最大步数40stepDelay每步之间的等待间隔秒用于给页面留出响应时间0.4languageAgent 工作语言与界面语言zh-CN或en-US—onAskUser当 Agent 需要向用户提问时的回调未设置则禁用ask_user工具无customTools自定义/覆盖/移除内置工具值为tool(...)或null移除无instructions.system全局系统级指令作用于所有任务无instructions.getPageInstructions每步执行前根据当前 URL 动态返回页面级指令无transformPageContent在把页面内容发送给 LLM 之前做转换如敏感数据脱敏无customSystemPrompt完全覆盖默认系统提示词实验性慎用无experimentalScriptExecutionTool是否启用可在页面上执行生成 JS 代码的实验性工具falseexperimentalLlmsTxt是否从当前站点抓取/llms.txt作为上下文实验性false生命周期钩子均标注为实验性onBeforeTask、onAfterTask、onBeforeStep、onAfterStep、onDispose。它们接收 agent 实例以及步数/历史/结果作为参数可在主循环的对应时机注入自定义逻辑见 types.ts。一个实用的脱敏示例——屏蔽页面内容中的手机号来自 types.ts 的文档注释const agent new PageAgent({ model: qwen3.5-plus, baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1, apiKey: YOUR_API_KEY, transformPageContent: async (content) { return content.replace(/1[3-9]\d{9}/g, ***********) }, })底层工作原理Re-act Agent 主循环PageAgentCore实现了经典的 Re-actReason Act循环见 PageAgentCore.ts 的注释说明step ├─ observe 收集当前环境与上下文信息 ├─ think 调用 LLM │ ├─ reflection评估历史、生成记忆、做短期规划 │ └─ action 给出接近下一个目标的行为 └─ act 执行该行为 loop每一步中Agent 会依次刷新页面浏览器状态getBrowserState→ 组装系统提示词与用户提示词 → 调用 LLM → 解析出「反思」与「动作」→ 执行对应工具 → 将步骤写回历史。提示词中会注入结构化的agent_state用户请求与步数信息、agent_history历史步骤、观察与用户接管记录以及browser_state页面头部、交互元素简化 HTML、页脚滚动提示组装逻辑见#assembleUserPromptPageAgentCore.ts。反思先于行动Reflection-before-actionPageAgent 的每一步都要求 LLM 先输出三部分反思内容再选择动作evaluation_previous_goal上一步动作达成了多少目标memory需要记住的关键信息next_goal下一步要完成什么。这些字段会进入MacroTool的输入结构见 types.ts。#packMacroTool会把所有内置/自定义工具合并成一个「每步必调」的大工具PageAgentCore.ts强制模型每一步都进行反思并做出决策从而保证行为可解释、可追踪。内置工具集工具定义在 packages/core/src/tools/index.ts 中工具作用done完成任务附上对用户的最终回复与成功标志wait等待若干秒自动扣除 LLM 调用耗时等待页面或数据加载完成ask_user向用户提问并等待回答需要配置onAskUserclick_element_by_index按索引点击元素input_text点击并输入文本select_dropdown_option按选项文本选择下拉项scroll垂直滚动页面或指定容器scroll_horizontally水平滚动execute_javascript在页面执行 JS实验性需显式开启且必须配合AbortSignal这些工具通过PageController见 PageController.ts执行真实的 DOM 操作。PageController每次会从当前页面提取交互元素的简化 HTML 树并建立索引映射对应browser-use中的eval_page与selector_mapLLM 只需引用元素索引即可操作完全不需要截图。事件系统与信息流Agent 提供两类事件反馈见 PageAgentCore.tsHistory Eventshistorychange事件持久的步骤、观察、用户接管、错误记录构成 Agent 的记忆会跨步骤进入 LLM 上下文Activity Eventsactivity事件瞬时 UI 反馈thinking / executing / executed / retrying / error只用于界面展示不进入 LLM 上下文。状态机则通过statuschange事件对外暴露取值为idle → running → completed / error / stopped。内置控制面板packages/ui中的Panel会渲染一个可折叠的控制面板头部区域展示实时活动状态历史区域直接渲染agent.history。这种「历史即单一事实来源、活动只反映当下」的架构保证了数据一致性见 Panel.ts。面板还负责把用户的回答回传给 Agent 的ask_user工具。进阶跨页面与外部 Agent 接入当单页面内 Agent 无法满足需求时仓库还提供了两个可选组件Chrome 扩展packages/extension为页面内 Agent 提供跨标签页、跨页面任务能力可控制多个页面同时执行MCP ServerBetapackages/mcp通过 MCP 协议把浏览器控制能力暴露给外部 Agent 客户端让现有 Agent 生态如各类 LLM 客户端也能驱动浏览器。贡献与致谢欢迎社区贡献请参阅 CONTRIBUTING.md 了解安装与贡献指南提交 issue 或 PR 之前请先阅读作者声明与 行为准则。注意仓库不接受未经实质性人类参与、完全由 Bot 或 Agent 自动生成的代码。本项目基于browser-use的优秀工作构建。DOM 处理组件与提示词派生自 browser-useMIT License。PageAgent专为客户端网页增强设计不是服务端自动化工具。项目以 MIT License 开源。相关本地开发与文档可继续阅读 docs/developer-guide.md 与 docs/CHANGELOG.md。【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考