page-agent PageAgentCore源码逐行解读：execute()方法里的100个细节

page-agent PageAgentCore源码逐行解读：execute()方法里的100个细节

【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent

page-agent 是一个运行在网页内部的「GUI Agent」：给任意网页注入一段脚本，就能用自然语言控制按钮、表单与滚动条——不需要浏览器扩展、不需要截图、不需要多模态大模型。它的引擎是 packages/core 中的PageAgentCore类，而 execute() 方法（约160行）是贯穿整个智能体生命周期的心脏。本文逐行解读它的每一步，并从文件里100多处设计细节中，提炼出最精华的40条供你速查。

一、先看懂结构：PageAgentCore 是三层架构里的「大脑」

page-agent 按 monorepo 划分了职责，理解分工后再读源码会轻松很多：

层	包	职责
🧠 大脑	packages/core	PageAgentCore主循环：与 LLM 对话、调用工具、发出事件
🖱️ 手	packages/page-controller	PageController：读取 DOM 树、点击、输入、滚动
📦 外壳	packages/page-agent	面向业务方的PageAgent封装

PageAgentCore继承 Web 标准的EventTarget（L61），文件头的注释（L31-L60）已经把它的核心思想写清楚了：

• ReAct 循环：step = observe（观察）→ think（LLM 推理）→ act（执行动作），然后 loop；
• 事件系统：statuschange/historychange/activity/dispose四类事件；
• 两条信息流：history是持久记忆（进入 LLM 上下文），activity是瞬时 UI 反馈（不进上下文）。

这一句就是全文的钥匙：Agent 是一台事件驱动的循环机器。

二、execute() 全景图：一张图看懂 ReAct 主循环

进入细节前，先建立骨架（L210-L375）：

execute(task) │ ├─ 1. 预检：已销毁 / 正在运行 / 任务为空 → 直接抛错 ├─ 2. 状态重置：清空 history、新建 AbortController ├─ 3. status → running，发出 historychange ├─ 4. showMask 页面遮罩 + onBeforeTask 钩子 │ ├─ 5. while (true) 主循环： │ ├─ onBeforeStep 钩子 │ ├─ stepDelay 等待（第2步开始） │ ├─ 👀 observe：getBrowserState + 系统观察 │ ├─ 🧠 think：组装 prompt → LLM invoke → MacroTool │ ├─ 🚀 act：执行工具，step 写入 history │ ├─ done? → break │ ├─ onAfterStep 钩子 │ └─ step++ 超过 maxSteps? → break │ ├─ 6. onAfterTask 钩子 → return 结果 └─ 7. finally：清高亮 → 撤遮罩 → abort → setStatus

三个 break 出口 + 一个 finally，正是代码注释里所说的graceful exit（L247）。

三、逐行解读：入口的30行里藏着13个细节

3.1 三连预检与「错误边界」

if (this.disposed) throw new Error('PageAgent has been disposed. Create a new instance.') if (this.#status === 'running') throw new Error('A task is already running.') if (!task) throw new Error('Task is required')

（L212-L214）检查顺序是「是否还活着 → 是否并发 → 输入是否合法」。注意方法上方注释声明的错误边界（L206-L209）：外部错误（预检、配置、钩子）直接 throw；Agent 内部错误则被捕获并转成失败结果返回。这条边界贯穿整个方法，是读懂错误处理的前提。

3.2 状态重置与取消机制

this.history = [] this.#abortController = new AbortController()

这一段（L216-L226）有几个值得暂停的细节：

• 记忆按任务隔离：每次新任务清空history，Agent 的记忆是「每任务」的，不跨任务串味（L219）；
• 每个任务一个全新的AbortController（L222）：signal会贯穿 LLM 的 fetch、每个工具和异步回调，这是取消机制的唯一源头。注释特别强调 abort 时不带 reason，让signal.reason保持标准的AbortError（L85-L90）；
• #runningPromise（L225-226）：专门留给「当前 run 彻底落定后 resolve」，让stop()能等到任务真正结束——包括所有生命周期钩子；
• 按需裁掉工具（L232）：宿主没提供onAskUser回调时，动态delete('ask_user')。工具可用性随运行环境动态决定，是很实用的模式；
• stepDelay默认0.4 秒（L238），maxSteps默认40（构造函数 L111）；
• finalStatus初始值为'error'（L243）：先假设失败，任何漏网路径都会被记为失败而不是悄悄卡在 running；
• showMask包在suppress里（L245）：遮罩失败了也不让任务崩——对「锦上添花」功能的经典防御。

四、逐行解读：主循环的「观察 → 思考 → 行动」

4.1 👀 Observe：不只是读取 DOM

this.#states.browserState = await this.pageController.getBrowserState() await this.#handleObservations(step)

（L268-L269）getBrowserState()让「手」把当前页面抽取成纯文本 DOM（无截图、无多模态）。#handleObservations（L538-L577）则往 Agent 记忆里注入三类系统提醒，堪称「防翻车」设计：

提醒	触发条件	目的
⏱️ 等待警告	累计等待 ≥ 3 秒	防止模型无限「等待」拖延任务
🧭 导航提示	URL 发生变化	告知页面跳转，并额外等 0.5 秒让页面稳定
⚠️ 步数倒数	剩余 5 步 / 2 步	两档升级，提醒模型及时收尾

4.2 🧠 Think：MacroTool 是本文最精彩的一笔

const messages = [ { role: 'system', content: this.#getSystemPrompt() }, { role: 'user', content: await this.#assembleUserPrompt() }, ] const result = await this.#llm.invoke(messages, macroTool, signal, { toolChoiceName: 'AgentOutput', })

（L273-L288）三个亮点：

1. MacroTool：#packMacroTool()（L386-L470）把所有工具合并成一个大工具。它的输入要求模型先填写反思字段（evaluation_previous_goal/memory/next_goal，均可选）再给出action——即强制「reflection-before-action」心智模型（types.ts#L177-L185）。action是 zod union（L389-L393）：有且只能选一个工具；
2. 强制结构化输出：toolChoiceName: 'AgentOutput'让 LLM 每步必须调用这个工具，不许自由发挥（工具描述就是 "You MUST call this tool every step!"，L404）；
3. 容错归一：normalizeResponse处理模型偶发的不规范输出（L287）。

而#assembleUserPrompt（L579-L647）的组装结构非常工整：<instructions>（可选的自定义指令 / llms.txt）+<agent_state>（用户请求 + 步数 + 当前时间）+<agent_history>（每步反思与结果）+<browser_state>（文本化 DOM）。特别注意：error 事件会写入 history 供 UI 渲染，但不进 LLM 上下文（L625-L628 注释）——瞬时错误不应污染模型推理。

4.3 🚀 Act：done 工具其实「什么都不做」

LLM 返回后（L292-L325）：

• 从 MacroTool 结果里取出反思三字段与action，actionName = Object.keys(action)[0]（union 保证只有一个键）；
• 写一条完整step事件进 history（L307-L315），附带 token 用量与 LLM 原始请求/响应——这是事后复现问题的关键；
• 若actionName === 'done'（L317-L325）：done工具本身没有实际逻辑（见 tools/index.ts#L38-L52），由主循环直接接管退出——取success（缺省false）、取text（缺省'no text provided'），设置结果并 break。

4.4 工具执行里的隐藏细节（MacroTool.execute）

• 执行前后各有一次signal.throwIfAborted()（L408、L442）：即使工具无视 signal 正常返回，取消也不会被漏掉；
• 记录执行耗时duration，随executed活动事件发出（L438-L454）；
• 等待时间统计（L457-L461）：执行wait工具则累加，执行其它工具则清零——这让 4.1 里的「累计等待警告」精准可靠；
• 内置wait工具更聪明：从等待时长中扣除 LLM 调用耗时（tools/index.ts#L62-L67），模型「思考的时间」不算页面「等待的时间」。

五、逐行解读：错误处理与三层退出

5.1 步骤内错误：不抛出，转结果

} catch (error) { const isAbortError = (error as any)?.name === 'AbortError' taskResult = { success: false, data: message, history: this.history } finalStatus = isAbortError ? 'stopped' : 'error' break }

（L326-L337）要点：Agent 内部错误从不传播给调用方，而是写入 history 并返回失败的ExecutionResult。取消错误还与普通错误区分对待：不打console.error（避免噪音）、状态记stopped而非error。注释（L327）还解释了一个易错点：catch 块自身必须不再抛错，否则会被后续 finally 覆盖。

5.2 三个 break 出口

出口	条件	finalStatus
✅ done	模型调用 done 工具	completed
🛑 stop / dispose	AbortError	stopped
🚫 步数超限	step > maxSteps（默认 40）	error

步数检查放在 try之外（L348-L358）——递增与判断不属于「本步执行」，超限错误也会写入 history，UI 可见。

5.3 finally：逆序清理，一个不漏

} finally { await suppress(() => this.pageController.cleanUpHighlights()) await suppress(() => this.pageController.hideMask()) this.#abortController.abort() resolveRunning() this.#setStatus(finalStatus) }

（L368-L374）五件事各司其职：清元素高亮 → 撤页面遮罩 → 中止所有在途 signal → 唤醒stop()的等待者 → 落定最终状态。无论走哪条退出路径，页面一定被还原、状态一定不残留。

六、execute() 的两个搭档：stop() 与 dispose()

stop()只有 5 行（L200-L204）：

async stop(): Promise<void> { if (this.#status !== 'running') return this.#abortController.abort() await this.#running }

• 非运行状态直接 return，重复调用安全（幂等）；
• abort()触发主循环的 AbortError 分支，await this.#running则保证stop()返回时任务的onAfterStep/onAfterTask钩子都已跑完。

dispose()（L649-L660）是「销毁」：标记disposed、销毁 PageController、abort、发出dispose事件供 UI 清理。之后再调execute()会被第一条预检拦截——生命周期闭环。测试文件 PageAgentCore.test.ts 对并发拒绝、阻塞任务停止、销毁后拒绝三条路径都有专门用例，值得对照阅读。

七、「100个细节」速查表：值得抄进你项目的40条

全文600多行，细节多达上百处。下面按主题精选40条，行号均可直接跳转（均指向 PageAgentCore.ts）：

状态与事件

#	细节	位置
1	预检三连：disposed → running → 空任务	L212-L214
2	新任务清空 history，记忆按任务隔离	L219
3	每任务一个 AbortController，abort 不带 reason	L85-L91
4	#runningPromise 专门让 stop() 等完全落定	L95
5	finalStatus初始为 'error'：先假设失败	L243
6	先置 running，再发空 history 的 historychange	L228-L229
7	状态真正变化才发 statuschange（防抖守卫）	L179-L184
8	activity 是瞬时 UI 反馈，永不进 LLM 上下文	L44-L48
9	LLM 重试事件在构造函数里转成 retry 历史	L117-L132

工具与提示词

#	细节	位置
10	未设置 onAskUser 时动态删除 ask_user 工具	L232
11	customTools 传 null 即可移除内置工具	L134-L142
12	execute_javascript 默认关闭，实验开关才启用	L144-L146
13	所有工具合并成一个 MacroTool	L386-L393
14	反思三字段均可选，空则不拼	L397-L399
15	action 用 zod union：有且只有一个工具	L393
16	工具描述："You MUST call this tool every step!"	L404
17	反思文本只由非空字段拼装	L416-L423
18	toolChoiceName 强制每步结构化输出	L286
19	normalizeResponse 归一化 LLM 不规范输出	L287
20	系统提示词按语言配置动态替换	L475-L487
21	customSystemPrompt 可完整覆盖默认提示词	L476-L478
22	instructions 三来源：system / 页面回调 / llms.txt	L492-L531
23	transformPageContent 钩子：内容入模前可脱敏	L636-L638
24	error 事件进 history 供 UI 渲染，但不进 LLM 上下文	L625-L628

循环与边界

#	细节	位置
25	stepDelay 默认 0.4 秒	L238
26	maxSteps 默认 40 步	L111
27	while(true) + 多出口 break，而非 for 定步数	L251
28	stepDelay 放在「下一步开头」而非上一步末尾	L260
29	等待后 signal.throwIfAborted() 二次确认	L262
30	累计等待 ≥ 3 秒注入警告观察	L540-L545
31	URL 变化：注入导航观察 + 等 0.5 秒稳定	L548-L553
32	剩余 5 步 / 2 步两档倒计时警告	L556-L566
33	done 工具无实际逻辑，由主循环接管退出	L317-L325
34	done 的 success 缺省 false（宁严勿松）	L318
35	done 的 text 缺省 'no text provided'	L319
36	step 事件附带 token 用量与原始请求/响应	L307-L315
37	AbortError 不打 console.error，状态记 stopped	L329-L336
38	catch 块自身禁止再抛（注释说明原因）	L327
39	finally 先于 break 执行；钩子抛错则升级为外部错误	L338-L346
40	收尾五连：清高亮 → 撤遮罩 → abort → resolve → setStatus	L368-L374

（另有「wait 扣除 LLM 耗时」「工具执行前后双重 signal 检查」「stop() 幂等」等细节，已在第四、六节展开。）

八、接着往下读：配套文件导航

如果读完意犹未尽，建议按这个顺序继续：

1. 🛠️ packages/core/src/tools/index.ts — 全部内置工具定义（done / wait / click / input_text / scroll …）
2. 📜 packages/core/src/prompts/system_prompt.md — 写给模型的完整行为规则
3. 📐 packages/core/src/types.ts — 事件流、钩子、配置项的全部类型定义
4. 🧪 packages/core/src/PageAgentCore.test.ts — 主循环各路径的测试用例
5. 📦 packages/page-agent/src/PageAgent.ts — 业务外壳如何封装 Core
6. 🚀 docs/developer-guide.md — 本地开发与构建指南

一句话总结

execute()的精髓是八个字：入口设防、优雅退出——预检守住边界，循环里事件驱动、反思先行，任何时刻都能被干净地取消，退出路径上状态一个都不残留。这 600 多行代码是 ReAct 智能体的教科书级实现，也是理解整个 page-agent 项目的钥匙。

【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent