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-agent

Page Agent 是一个纯 JS 实现的 GUI Agent，它直接运行在网页内部，让你可以用自然语言指令操控 Web 应用——无需后端服务、无需 Python、无需浏览器插件。本文将以docs/README-zh.md为主线，结合仓库源码（packages/core、packages/llms、packages/page-controller、packages/page-agent等）深入讲解其集成方式、配置参数与底层工作原理，读完你就能在自己的产品里以「一行脚本」接入一个可对话、可操作的 AI 副驾驶。

什么是 Page Agent

Page Agent（即page-agentnpm 包）是一个客户端网页增强的 GUI Agent 框架：你只需要在页面中引入一段 JavaScript，页面就拥有了自己的 AI Agent，能够理解自然语言任务并像真人一样操作页面元素（点击、输入、滚动、下拉选择等）。

它的核心设计主张是：

• 纯页面内 JavaScript：不需要浏览器插件、Python 环境或无头浏览器，一切发生在你的网页里；
• 基于文本的 DOM 操作：不依赖截图，因此不需要多模态模型，也不需要特殊权限；
• 自备 LLM：支持大多数主流模型（包括本地部署模型），完全由你自己掌控；
• 可选的 Chrome 扩展与 MCP Server（Beta）：需要跨页面任务时再引入额外组件。

从仓库结构看，整个能力由若干分层包组合而成（见 packages）：

其中PageAgent类的构造逻辑（见 PageAgent.ts）清晰展示了这种组合关系：它同时创建了PageController（页面控制）与Panel（UI 面板），并继承PageAgentCore（核心主循环）。这意味着「看得见的面板」和「操作页面的引擎」可以独立工作。

应用场景

• SaaS AI Copilot：几行代码为你的产品加上 AI 副驾驶，无需重写后端。
• 智能表单填写：把 20 次点击变成一句话。ERP、CRM、管理后台的最佳拍档。
• 无障碍增强：用自然语言让任何网页无障碍。语音指令、屏幕阅读器，零门槛。
• 跨页面 Agent：通过可选的 Chrome 扩展 让你的 Web Agent 跨标签页工作。
• MCP 接入：通过 MCP 为现有 Agent 加入浏览器控制能力。

快速开始

方式一：一行脚本接入（体验 Demo）

最快的方式是使用官方免费的 Demo LLM，在你的页面 HTML 中直接引入：

<script src="https://registry.npmmirror.com/page-agent/1.12.3/files/dist/iife/page-agent.demo.js" crossorigin="anonymous" ></script>

⚠️ 仅用于技术评估。该 Demo CDN 使用了免费的测试 LLM API，使用即表示你同意其 条款。

加载后脚本会自动创建一个 Demo Agent，并在页面上展示控制面板。几个实用的 URL 参数（对应 demo.ts 中的解析逻辑）：

脚本加载成功后会将PageAgent挂载到window.PageAgent（同时清理可能存在的旧实例，避免重复注入），因此你可以在控制台或后续代码中随时手动创建 Agent。

方式二：NPM 安装（正式集成）

npm install page-agent

import { 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（是否成功）、data（Agent 的最终回答文本）以及完整的history（历史事件流，可供回放与调试）。当 Agent 判定任务完成时会调用内置的done工具，execute随即返回结果（见 PageAgentCore.ts）。

配置参数详解

PageAgent的配置类型是PageAgentConfig，它是AgentConfig & PageControllerConfig & Omit<PanelConfig, 'language'>的组合（见 PageAgent.ts）。核心配置定义在 types.ts 中，下面按用途分组说明。

LLM 相关（来自packages/llms）

parseLLMConfig（见 packages/llms/src/index.ts）会在运行时校验：缺少baseURL或model会直接抛出错误；而maxRetries、disableNamedToolChoice、customFetch等均提供了合理的默认兜底。

提示：如果模型不支持强制指定工具名（即tool_choice传对象），可以设置disableNamedToolChoice: true来绕过（见 OpenAIClient.ts）。

行为与任务控制

生命周期钩子（均标注为实验性）：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-act（Reason + Act）循环（见 PageAgentCore.ts 的注释说明）：

step ├─ observe （收集当前环境与上下文信息） ├─ think （调用 LLM） │ ├─ reflection（评估历史、生成记忆、做短期规划） │ └─ action （给出接近下一个目标的行为） └─ act （执行该行为） loop

每一步中，Agent 会依次：刷新页面浏览器状态（getBrowserState）→ 组装系统提示词与用户提示词 → 调用 LLM → 解析出「反思」与「动作」→ 执行对应工具 → 将步骤写回历史。

提示词中会注入结构化的<agent_state>（用户请求与步数信息）、<agent_history>（历史步骤、观察与用户接管记录）以及<browser_state>（页面头部、交互元素简化 HTML、页脚滚动提示），组装逻辑见#assembleUserPrompt（PageAgentCore.ts）。

反思先于行动（Reflection-before-action）

PageAgent 的每一步都要求 LLM 先输出三部分反思内容，再选择动作：

• evaluation_previous_goal：上一步动作达成了多少目标；
• memory：需要记住的关键信息；
• next_goal：下一步要完成什么。

这些字段会进入MacroTool的输入结构（见 types.ts）。#packMacroTool会把所有内置/自定义工具合并成一个「每步必调」的大工具（PageAgentCore.ts），强制模型每一步都进行反思并做出决策，从而保证行为可解释、可追踪。

内置工具集

工具定义在 packages/core/src/tools/index.ts 中：

这些工具通过PageController（见 PageController.ts）执行真实的 DOM 操作。PageController每次会从当前页面提取交互元素的简化 HTML 树并建立索引映射（对应browser-use中的eval_page与selector_map），LLM 只需引用元素索引即可操作，完全不需要截图。

事件系统与信息流

Agent 提供两类事件反馈（见 PageAgentCore.ts）：

1. History Events（historychange事件）：持久的步骤、观察、用户接管、错误记录，构成 Agent 的记忆，会跨步骤进入 LLM 上下文；
2. Activity Events（activity事件）：瞬时 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 Server（Beta）（packages/mcp）：通过 MCP 协议把浏览器控制能力暴露给外部 Agent 客户端，让现有 Agent 生态（如各类 LLM 客户端）也能驱动浏览器。

贡献与致谢

欢迎社区贡献！请参阅 CONTRIBUTING.md 了解安装与贡献指南；提交 issue 或 PR 之前，请先阅读作者声明与 行为准则。注意：仓库不接受未经实质性人类参与、完全由 Bot 或 Agent 自动生成的代码。

本项目基于browser-use的优秀工作构建。DOM 处理组件与提示词派生自 browser-use（MIT 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