PageAgent 浏览器自动化系统提示词完全解析：从 Agent 循环设计到源码级实现

PageAgent 浏览器自动化系统提示词完全解析从 Agent 循环设计到源码级实现【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent本指南以 PageAgent 浏览器扩展中实际运行的系统提示词packages/extension/src/agent/system_prompt.md为主体逐段拆解这一份驱动自然语言操控浏览器的 Agent 操作手册它如何定义输入协议、浏览器状态、操作守则、任务终止条件与反思-行动循环并在每一步如何与 PageAgentCore 的主循环、工具系统和多页签控制器联动。读完本文你将能理解该提示词每一处设计的工程意图掌握其结构化标签协议与 JSON 输出格式并知道如何在扩展侧自定义系统指令来约束 Agent 行为。一、定位扩展侧浏览器 Agent 的操作系统手册在 PageAgent 的 Chrome 扩展中负责真正执行用户任务的不是简单的单页面脚本而是一个运行在**迭代循环iterative loop**中的 AI Agent。它的最高目标就是完成user_request中用户下达的任务。而这份系统提示词就是决定 Agent如何思考、如何观察、如何行动、何时终止的核心纲领。它与核心包packages/core/src/prompts/system_prompt.md中的提示词同源但不同版扩展版加入了多页签multi-tab能力——browser_state中会携带Open Tabs打开的页签列表与Current Tab当前页签配合扩展独有的页签管理工具而核心版则保留了capability单页限制声明You can only handle single page app. Do not jump out of current page.。在代码中这份提示词以 Vite 的?raw方式被直接引入并注入到 Agent 内核MultiPageAgent.ts 顶部import SYSTEM_PROMPT from ./system_prompt.md?raw构造器内通过customSystemPrompt: systemPrompt将其传给PageAgentCorePageAgentCore在每次调用 LLM 之前通过#getSystemPrompt()PageAgentCore.ts读取该提示词——若配置了customSystemPrompt则直接使用否则回退到核心包自带的提示词。也就是说这份文件是扩展场景下 Agent 行为的事实标准任何对 Agent 行为的约束都必须回到它的规则上来。二、提示词的整体架构XML 标签分区整份提示词由多个语义明确的标签块组成每一块负责 Agent 心智模型的一个侧面。下表为整体分区一览标签块职责intro声明 Agent 擅长任务清单复杂站点导航、表单自动化、信息收集、Agent 循环、多样化网页任务language_settings默认工作语言与回复语言规则input定义每步输入的三段式结构agent_history、agent_state、browser_stateagent_history历史事件流格式step_N与sys系统消息user_request用户最终目标优先级最高始终可见browser_state页签状态与可交互元素的索引协议browser_rules浏览器操作守则严格规则task_completion_rules何时必须调用done、如何设置success与textreasoning_rules反思-行动推理模式要求examples输出范式示例evaluation / memory / next_goaloutput每步必须输出的结构化 JSON 格式这种分区即协议的设计让 LLM 在任何一步都能快速定位自己该关注的信息也便于工程侧程序化地组装与解析每一步的上下文。三、输入协议每步喂给 LLM 的三段式输入提示词明确声明Agent 在每一步收到的输入都由三部分组成agent_history按时间顺序的事件流包含此前的动作及其结果agent_state当前的user_request与step_infobrowser_state页签、当前页签、当前 URL、带索引的可交互元素以及可见页面内容。这三段输入并不是提示词作者凭空规定的——它们在 PageAgentCore.ts 的#assembleUserPrompt()中被逐段程序化拼装agent_state中写入user_request即this.task、step_infoStep N of M max possible steps 与当前时间agent_history中按stepIndex递增生成step_N标签并回填每一步的Evaluation of Previous Step、Memory、Next Goal与Action Resultsobservation类型事件包装为sys消息browser_state由pageController.getBrowserState()采集加上browserState.header页签汇总表与pageContent简化后的页面内容必要时经transformPageContent清洗后再发给 LLM。关于历史事件流提示词给出了明确的格式约定step_{step_number}: Evaluation of Previous Step: Assessment of last action Memory: Your memory of this step Next Goal: Your goal for this step Action Results: Your actions and their results /step_{step_number}以及用sys标签包裹的系统消息。agent_history构成了 Agent 跨步骤的记忆在后续每一步都会被重新带入上下文。四、user_request最高优先级的目标提示词对user_request的定义只有一句话但分量极重This is your ultimate objective and always remains visible.这是你的终极目标并且始终可见。它同时给出了两条执行准则如果用户请求非常具体——仔细遵循每一步不跳过、不臆造dont skip or hallucinate steps如果任务是开放式的——自行规划实现路径。在代码侧execute(task)会把任务字符串写入this.task随后每一步的#assembleUserPrompt()都会把它放进agent_state。任务在整轮执行中保持可见这正是always remains visible的实现保证。五、browser_state可交互元素的索引协议browser_state是 Agent 感知网页的眼睛。提示词规定其结构为Open Tabs带 id 的所有已打开页签Current Tab当前正在查看的页签Current URL当前页面 URLInteractive Elements所有可交互元素格式为[index]typetext/type其中index是交互数字标识type是 HTML 元素类型button、input 等text是元素描述。官方示例[33]divUser form/div *[35]button aria-labelSubmit formSubmit/button三条关键语义只有带[]数字索引的元素才是可交互的缩进\t表示层级缩进元素是上方较低索引元素的HTML子元素*[标记新出现的可点击元素自上次步骤以来在 URL 未变化的前提下新出现在页面上的元素不带[]的纯文本元素不可交互。在扩展的多页签场景下这个browser_state的 header 部分会额外注入一张页签汇总 Markdown 表格。由 TabsController.ts 的summarizeTabs()生成格式为| Tab ID | URL | Title | Status | Current | |-----|-----|-----|-----|-----| | 123 | https://... | Page Title | complete | ✅ |其中✅标记当前页签最后一行可能是No tabs available. Open a tab if needed.无页签可用提示。RemotePageController.getBrowserState()会把这个表格拼接到 browserState 的 header 最前面再交给 LLM——这样 Agent 才能看到自己开了哪些页签、当前在哪个页签上。六、browser_rules浏览器操作守则这是提示词中最长也最硬核的部分全部为严格规则Strictly follow these rules逐条展开如下只操作带数字[index]的元素只用明确提供的索引页面变化后重新分析例如输入文本后出现候选列表应判断是否需要与新元素交互如从列表中选择正确选项视口机制默认只列出可见视口内的元素怀疑相关内容在屏幕外时使用滚动动作只有页面上下还有像素时才滚动按页滚动用num_pages参数控制如0.5表示半页、2.0表示两页容器滚动可滚动元素带data-scrollable属性并附各方向可滚动距离可用其索引滚动特定溢出区域验证码出现验证码时告知用户无法解决结束任务并请用户处理页面未加载完使用wait动作不要重复同一动作超过 3 次除非条件发生了变化输入中断若填表后动作序列被中断多半是出现了新变化如字段下弹出建议善用筛选当user_request含产品类型、评分、价格、地点等特定信息时尝试应用筛选提高效率优先级user_request是终极目标用户给出明确步骤时始终优先输入完成动作input_text后可能需要按回车、点击搜索按钮或从下拉框选择来收尾不必要不登录没有凭据就不要登录任务类型二分先判断属于哪类任务——非常具体的逐步指令严格按步骤执行不跳过还是开放式任务自行规划、创造性完成遇到登录/验证码卡住时可换思路如利用可访问部分或网络搜索获取信息。这些规则与底层工具一一对应。在 packages/core/src/tools/index.ts 中可以看到click_element_by_index、input_text、select_dropdown_option、scroll支持down、num_pages、pixels、index参数、scroll_horizontally、wait支持seconds范围 1–10 秒、done等工具的 schema 定义规则与工具参数严丝合缝。七、task_completion_rules与done动作终止协议提示词规定 Agent 必须在以下三种情况之一调用done完全完成了user_request到达最终允许步数max_steps即使任务未完成卡住无法继续、请求不清晰或含不当内容、绝对无法继续时。done的语义约束仅当user_request完整完成、无缺失组件时success才设为true任何缺失、不完整或不确定都设success: falsetext字段用于向用户传达发现并给出连贯回复done只能作为单独动作调用不能与其他动作同时调用若用户指定输出格式如返回如下结构的 JSON必须严格遵守done的 schema 可能被修改解题时须参考该 schema。在核心循环中PageAgentCore.ts 对done做了专门处理解析出actionName done后读取success默认false与text缺省为no text provided构造ExecutionResult写入lastResult将最终状态置为completed并跳出循环。若步数超过maxSteps默认 40见 PageAgentCore.ts则记录 Step count exceeded maximum limit 并以error状态终止——这就是提示词中到达最终允许步数也要调用 done的兜底保障。八、reasoning_rules反思-行动循环的推理模式提示词要求 Agent 展示以下推理模式以成功达成目标依据agent_history推理跟踪向user_request推进的进度与上下文分析最近的Next Goal与Action Result明确说明上一步想达成什么综合agent_history与browser_state理解当前状态显式判断上一步的成功/失败/不确定——不能因为动作看起来执行了就假设成功若预期变化缺失标记失败或不确定并规划恢复卡住检测当重复相同动作多次却毫无进展时判定为卡住考虑替代方案如滚动获取更多上下文或向用户求助遇到困难及时求助用户让用户保持在循环中看到与任务相关的信息时规划存入记忆始终对照user_request分析仔细核对具体步骤与所需信息特定筛选、表单字段、搜索信息并比较当前轨迹与用户请求是否一致。这套先反思、后行动的模型在工程上由一个名为AgentOutput的MacroTool宏工具强制执行。见 PageAgentCore.ts 的#packMacroTool()它将所有内部工具合并成一个 schema 为{ evaluation_previous_goal?, memory?, next_goal?, action: {...} }的单一工具每次 LLM 调用都强制走这个宏工具从而保证每步输出都携带反思字段。types.ts中的 AgentReflection 接口正是这一心智模型的类型化表达。九、输出协议结构化的 JSON 反射输出提示词末尾定义了每步的标准输出 JSON{ evaluation_previous_goal: Concise one-sentence analysis of your last action. Clearly state success, failure, or uncertain., memory: 1-3 concise sentences of specific memory of this step and overall progress. You should put here everything that will help you track progress in future steps. Like counting pages visited, items found, etc., next_goal: State the next immediate goal and action to achieve it, in one clear sentence., action:{ Action name: {// Action parameters} } }字段语义evaluation_previous_goal对上次动作的一句话分析明确 success / failure / uncertainmemory1–3 句本步记忆与整体进度用于未来步骤追踪如访问过的页面数、找到的条目数next_goal下一步的立即目标与动作一句话说清action本次要执行的工具名与参数。提示词还附带了输出范式参考examples例如evaluation 示例Successfully navigated to the product page and found the target information. Verdict: Success、Clicked the login button and user authentication form appeared. Verdict: Successmemory 示例记录主页面待分析报告数量、已处理 2 份季度销售数据、下一步进入库存分析与客户反馈报告next_goal 示例Click on the Add to Cart button to proceed with the purchase flow.值得注意的是PageAgentCore的宏工具 schema 中三个反思字段均标记为可选optional()且thinking字段被注释禁用工具执行时只把非空字段拼入反思文本避免空字段污染上下文PageAgentCore.ts。十、语言适配机制提示词中的动态替换提示词自带语言设置段language_settings - Default working language: **English** - Use the language that user is using. Return in users language. /language_settings扩展在注入前会对这段做运行时替换实现跟随用户语言的体验MultiPageAgent.ts 的detectLanguage()读取navigator.languagezh开头返回zh-CN否则返回en-US若配置了language则优先使用配置值用正则/Default working language: \*\*.*?\*\*/将**English**替换为**中文**或**English**MultiPageAgent.ts。语言偏好可通过扩展侧 UI 配置。useAgent.ts 的configure()会把language写入chrome.storage.localConfigPanel.tsx 提供语言下拉选项核心包#getSystemPrompt()中也有完全相同的替换逻辑PageAgentCore.ts。SupportedLanguage类型定义为en-US | zh-CNtypes.ts。十一、多页签扩展从单页到多页的操作闭环扩展版提示词与核心版最实质的差异在于browser_state携带Open Tabs并在工具集中新增了三个页签工具tabTools.tsopen_new_tab按 URL 打开新页签并设为当前页签后续所有页面操作都作用于它switch_to_tab按tab_id切换到已有页签只能切换到 browser_state 页签列表中出现的页签close_tab按tab_id关闭页签不能关闭初始页签Cannot close the initial tabTabsController.ts。这些工具经由customTools注入PageAgentCoreMultiPageAgent.ts并与提示词形成闭环TabsController.init()在任务开始时确认初始页签并以PageAgent(task)为标题、随机颜色创建页签组TabsController.ts每步开始前syncTabs()拉取窗口页签快照若出现新页签则自动聚焦到最新的一个像用户一样跟随页面TabsController.ts页签状态汇总表经由summarizeTabs()进入每一步的browser_state让 LLM 始终看得到页签全景受限于浏览器扩展隔离execute_javascript在扩展场景被显式禁用AbortSignal无法跨上下文页面上受限协议chrome://、about:、file://等会被isContentScriptAllowed()拦截RemotePageController.ts。由此一份提示词文档、一套索引协议、一组页面工具与页签工具共同构成了输入 → 反思 → 决策 → 执行 → 再观察的完整多页浏览器自动化闭环。十二、自定义与进阶如何改写这份操作系统手册提示词虽内置但 PageAgent 开放了多层定制能力让开发者可以按场景改写 Agent 行为自定义系统提示词AgentConfig.customSystemPrompt可完全覆盖默认提示词但types.ts明确警告错误提示词可能破坏 Agent 行为请谨慎使用types.ts系统级指令扩展的AdvancedConfig.systemInstructionuseAgent.ts会通过instructions.system传入由#getInstructions()组装为instructionssystem_instructions.../system_instructions/instructions块追加到每次的用户提示词之前PageAgentCore.ts——这是在不改动系统提示词的前提下注入行为约束的推荐方式页面级动态指令instructions.getPageInstructions(url)按 URL 动态返回指令实验性上下文experimentalLlmsTxt会从当前站点获取/llms.txt并作为llms_txt上下文注入步数上限maxSteps默认 40可在配置面板调整直接影响到达最终允许步数的终止时机内容脱敏transformPageContent可在页面内容发给 LLM 前清洗敏感数据如正则替换手机号与提示词对精确提取信息的要求配合使用。总结packages/extension/src/agent/system_prompt.md 表面上是一份写给 LLM 看的文本实质上是一份经过工程校验的人机协议契约browser_state定义了 Agent 如何看页面browser_rules约束了 Agent 如何动手task_completion_rules规定了 Agent 何时收手output的 JSON 结构则驱动着每一步先反思后行动的心智模型。它与 PageAgentCore.ts 的主循环、tools/index.ts 的宏工具、tabTools.ts 与 TabsController.ts 的多页签体系深度耦合共同支撑起用自然语言控制网页界面这一核心能力的每一次迭代执行。对于希望深入理解浏览器 Agent 工程化或计划自定义 PageAgent 行为规则的开发者这份文档是理解整个系统的最佳起点。【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考