page-agent核心概念一文读懂PageAgent、Core、PageController三大组件关系图【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agentpage-agent 是一个运行在网页内的 GUI AgentGUI 智能体让你用一句自然语言就能控制浏览器界面。很多新手第一次看它的 monorepo 源码时会困惑到底有多少个包PageAgent、PageAgentCore、PageController 三者的边界在哪里本文通过一张关系图加白话讲解带你一文读懂 page-agent 核心概念快速建立完整的架构认知 三大组件关系图一图看懂 page-agent 架构先用一张图建立整体印象来自 developer-guide.md 中的包结构说明┌────────────────────────────────────────────┐ │ PageAgent │ ← 开箱即用npm: page-agent │ 内置 UI 面板 Panel 自动组装下面两个组件 │ └───────┬────────────────────┬───────────────┘ │ 继承 │ 自动创建 ┌────────────▼──────────────┐ ┌───▼────────────────────────┐ │ PageAgentCore │ │ PageController │ │ npm: page-agent/core │ │npm: page-agent/ │ │ Agent 的大脑 │ │ page-controller │ │ ReAct 循环 LLM 推理 │ │ 眼睛 手 │ └───────────────────────────┘ └────────────────────────────┘一句话总结分工组件角色比喻负责什么源码位置PageAgent完整产品继承 Core、自动创建 PageController并挂载内置 UI 面板PageAgent.tsPageAgentCore大脑 ReAct 循环观察 → 思考 → 行动、LLM 调用、任务记忆PageAgentCore.tsPageController眼睛手 读取 DOM、生成页面状态、执行点击/输入等元素操作PageController.tsPageController网页的眼睛和手不依赖 LLMPageController 是三大组件中唯一完全不关心大模型的部分。它做两件事观察把当前页面的 DOM 树拍平提取出所有可交互元素按钮、输入框、链接等生成一份带索引编号的简化 HTML 文本也就是喂给大模型看的浏览器状态。核心逻辑见 getPageInfo.ts 和 dom_tree执行根据大模型给出的元素编号执行 actions.ts 中定义的点击、输入、滚动、选择等操作。源码注释里特别强调它Designed to be independent of LLM and can be tested in unit testsPageController.ts这意味着它可以在没有网络、没有模型的环境下独立开发和测试也是整个项目纯前端、零后端依赖设计的关键一环。PageAgentCoreAgent 的大脑ReAct 循环PageAgentCore 是不带任何 UI 的纯逻辑核心类。如果你打开 PageAgentCore.ts开头就有一份非常清楚的ReAct 循环注释Observe观察调用pageController.getBrowserState()获取当前页面状态Think思考拼装系统提示词 页面状态 历史记忆调用 LLM 做推理Act行动把模型选中的工具如 click、input真正执行到页面上Loop循环重复以上步骤直到模型调用done或达到最大步数。几个新手容易忽略的细节事件驱动Core 继承自EventTarget通过statuschange、historychange、activity事件向外广播状态PageAgentCore.ts这正是 UI 面板能实时显示Agent 在想什么的原因记忆机制每一步的评估结论、记忆和下一个目标reflection都会进入 history 数组成为后续轮次的上下文让多步任务不犯糊涂系统提示词默认提示词写在 system_prompt.md支持按语言自动替换。简单说Core 只负责想PageController 负责看和做两者通过构造函数注入的方式组合new PageAgentCore({ pageController })。PageAgent三者合体开箱即用PageAgent 是最外层、也是 90% 用户真正接触到的类。它的构造函数只有几行核心代码PageAgent.ts用你的配置new PageController(...)默认开启视觉遮罩操作时锁定页面防止误触把 PageController 传给自己super(...)完成 Core 的初始化new Panel(this, ...)创建内置 UI 面板。也就是说PageAgent PageAgentCore PageController UI Panel 的一键打包。面板源码在 Panel.ts它会直接消费 Core 发来的history历史事件流和activity实时活动流两个信息流把思考中…点击了按钮这些过程展示给用户。一次任务执行的完整链路以agent.execute(点击登录按钮)为例串起三大组件的协作步骤执行者发生了什么1PageAgent接收任务转发给 Core 的execute()2PageController展示遮罩、扫描 DOM产出带编号元素的页面状态文本3PageAgentCore把任务 页面状态 历史打包成 Prompt调用 LLM4PageAgentCore解析模型返回的工具调用如click(index7)5PageController按编号找到元素并点击返回执行结果6UI Panel通过事件实时渲染每一步的进度与结果若模型返回done循环结束并给出成功/失败结果若超出maxSteps默认 40 步则安全终止PageAgentCore.ts。我该用哪一个三大组件选型指南这是新手最常问的问题直接给结论用 PageAgent绝大多数场景一行npm install page-agent就能获得完整体验——自带面板、自动处理 DOM、支持 Agent 主动提问ask_user 工具用 PageAgentCore进阶场景需要自定义 UI 界面、无头自动化测试、嵌入其他 Agent 系统时自己监听事件并画界面即可单独用 PageController特殊场景只想做 DOM 提取或元素操作、不接大模型时例如自建爬虫辅助或自动化脚本想要跨标签页能力项目还提供了一个 Chrome 扩展包 packages/extension/其中的 MultiPageAgent 让 Agent 的能力扩展到多个浏览器标签页。相关文档与源码索引项目结构与各包职责说明docs/developer-guide.md中文项目说明docs/README-zh.md扩展 API 集成细节packages/extension/docs/extension_api.md内置工具定义click / input / done 等packages/core/src/tools/index.ts理清PageAgent 是壳、Core 是脑、PageController 是手脚这条主线后再深入任何一块源码都会事半功倍。如果你准备动手实践建议从 README.md 中的 NPM 安装示例开始先跑通一个new PageAgent(...)任务再带着具体现象回来看架构理解会更深一层 【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
