PageAgent 技术架构深度解析

核心机制深度解析

范式转换：从外部控制到内部增强

PageAgent 的核心创新在于运行位置的根本性改变。传统浏览器自动化工具（如 Browser-use、Playwright）从浏览器外部通过 WebDriver 协议或 DevTools Protocol 控制页面，而 PageAgent 直接嵌入到网页内部运行。

这种设计带来了三个根本性优势：

1. 零信任开销

传统方案：用户 → 自动化工具 → (需要信任/配置) → 浏览器 → 网页
PageAgent: 用户 → (内置于) → 网页 → 直接操作 DOM

PageAgent 不需要绕过反自动化检测，因为它本身就是页面的一部分。它不模拟用户行为，而是增强用户的操作能力。

2. 会话继承

由于运行在用户的真实浏览器会话中，PageAgent 天然继承：

• 所有 Cookie 和 LocalStorage 状态
• 已登录的用户身份
• 浏览器的扩展和自定义设置
• 网络请求的认证头

这消除了传统方案中最繁琐的凭证管理环节。

3. 实时 DOM 访问

PageAgent 通过 JavaScript 直接访问 DOM，无需序列化或远程调用：

• 实时读取页面状态
• 直接调用 DOM API（querySelector、dispatchEvent 等）
• 监听原生事件（click、input、submit）
• 修改样式和内容（style、innerHTML）

DOM 文本化索引机制

PageAgent 的核心技术突破是将 DOM 树转换为 LLM 可理解的文本化索引。这一机制使 LLM 无需视觉能力即可”看见”页面结构。

索引生成流程

flowchart TD
    A[原始 DOM 树] --> B[DOM 修剪]
    B --> C[可交互元素提取]
    C --> D[文本化编码]
    D --> E[索引映射表]
    E --> F[LLM 理解]
    F --> G[动作决策]
    G --> H[索引反查 DOM]
    H --> I[执行操作]

索引编码策略

PageAgent 使用智能的 DOM 压缩算法：

1. 元素筛选：只保留可交互元素（<button>、<input>、<a>、[role="button"] 等）
2. 层级扁平化：移除纯装饰性嵌套，保留语义结构
3. 文本摘要：对长文本进行智能截断（保留首尾关键信息）
4. 数字索引：为每个可操作元素分配唯一数字 ID

编码示例：

// 原始 HTML
<div class="nav">
  <button>Login</button>
  <a href="/signup">Sign Up</a>
  <input type="search" placeholder="Search..." />
</div>

// PageAgent 索引 (简化版)
[1] <button> Login </button>
[2] <a href="/signup"> Sign Up </a>
[3] <input type="search" placeholder="Search...">

这种编码方式将数千个 DOM 节点压缩为几十个可操作索引，大幅降低了 LLM 的 Token 消耗和理解难度。

LLM 集成与指令解析

支持的 LLM Provider

PageAgent 采用开放的 LLM 集成策略，支持多种模型：

提示词工程

PageAgent 的系统提示词包含以下关键部分：

你是一个专业的 UI 自动化助手。用户会给你自然语言指令，
你需要将其转换为具体的 DOM 操作。

## 可用动作：
- click[index]: 点击元素
- input[index, text]: 输入文本
- select[index, value]: 选择下拉选项
- scroll[index, direction]: 滚动页面
- extract[index]: 提取元素文本
- wait[condition]: 等待条件满足

## 输出格式：
必须返回 JSON 格式的动作列表，例如：
{"actions": [{"type": "click", "index": 1}, {"type": "input", "index": 3, "text": "hello"}]}

## 约束：
- 只能使用提供的索引编号
- 不要假设不存在的元素
- 如遇到歧义，先询问用户确认

指令解析流程

sequenceDiagram
    participant U as 用户
    participant P as PageAgent
    participant L as LLM
    participant D as DOM
    
    U->>P: "点击登录按钮"
    P->>D: 生成 DOM 索引
    D-->>P: 返回索引文本
    P->>L: 系统提示 + 索引 + 用户指令
    L-->>P: {"actions": [{"type": "click", "index": 1}]}
    P->>D: 执行动作 (index=1)
    D-->>P: 执行结果
    P->>U: 显示执行反馈

Action 执行管道

动作类型系统

PageAgent 定义了丰富的动作类型，覆盖常见的 UI 交互：

type ActionType = 
  | 'click'           // 点击元素
  | 'input'           // 文本输入
  | 'select'          // 下拉选择
  | 'checkbox'        // 复选框切换
  | 'radio'           // 单选按钮
  | 'hover'           // 悬停
  | 'scroll'          // 滚动
  | 'navigate'        // 页面跳转
  | 'extract'         // 数据提取
  | 'wait'            // 等待条件
  | 'assert'          // 断言验证
  | 'custom'          // 自定义动作

执行流程

flowchart LR
    A[动作队列] --> B{动作类型}
    B -->|click| C[定位元素]
    B -->|input| D[验证可输入]
    B -->|extract| E[读取文本]
    C --> F[dispatchEvent]
    D --> F
    E --> G[返回结果]
    F --> H[等待状态稳定]
    H --> I[更新索引]
    I --> J{还有动作？}
    J -->|Yes| A
    J -->|No| K[完成任务]

错误处理策略

PageAgent 采用多层错误处理机制：

1. 元素未找到：重新生成索引后重试（应对动态加载）
2. 动作执行失败：捕获异常，尝试替代方案（如 click() 失败则 dispatchEvent('click')）
3. LLM 返回无效：提示词约束 + 输出验证 + 自动重试
4. 超时处理：设置动作执行超时（默认 30 秒），超时后回滚状态

状态管理架构

会话状态机

PageAgent 内部维护一个状态机来跟踪任务执行：

stateDiagram-v2
    [*] --> Idle: 初始化完成
    Idle --> Listening: 用户输入指令
    Listening --> Analyzing: 提交指令
    Analyzing --> Executing: LLM 返回动作
    Executing --> Confirming: 需要确认？
    Confirming --> Executing: 用户确认
    Confirming --> Idle: 用户取消
    Executing --> Verifying: 动作完成
    Verifying --> Listening: 还有后续动作
    Verifying --> Idle: 任务完成
    Executing --> Error: 执行失败
    Error --> Idle: 错误处理完成

上下文管理

PageAgent 使用分层上下文管理：

interface AgentContext {
  // 会话级上下文
  sessionId: string;
  conversationHistory: Message[];  // 对话历史
  executedActions: ActionRecord[]; // 已执行动作日志
  
  // 页面级上下文
  currentPageUrl: string;
  domSnapshot: DOMSnapshot;
  indexMapping: Map<number, Element>;
  
  // 任务级上下文
  currentGoal: string;
  subGoals: string[];
  completedSteps: number;
}

这种设计支持：

• 多轮对话：记住之前的交互历史
• 断点恢复：意外中断后可从最近状态恢复
• 跨页任务：通过 Chrome 扩展实现多标签页状态同步

关键组件拆解

1. PageController（核心控制器）

职责：PageAgent 的主入口，协调各子系统

class PageAgent {
  private llm: LLMProvider;
  private domProcessor: DOMProcessor;
  private actionExecutor: ActionExecutor;
  private ui: AgentPanel;
  
  async execute(instruction: string): Promise<Result> {
    // 1. 生成 DOM 索引
    const index = await this.domProcessor.createIndex();
    
    // 2. 调用 LLM 解析指令
    const actions = await this.llm.parse(instruction, index);
    
    // 3. 显示确认面板（可选）
    if (this.ui.requiresConfirmation(actions)) {
      const confirmed = await this.ui.showConfirmation(actions);
      if (!confirmed) return { status: 'cancelled' };
    }
    
    // 4. 执行动作序列
    return await this.actionExecutor.execute(actions);
  }
}

2. DOMProcessor（DOM 处理器）

职责：DOM 树分析、索引生成、元素定位

核心算法：

• 可交互性判断：基于标签名、ARIA role、事件监听器
• 可见性检测：排除 display: none、visibility: hidden、超出视口元素
• 文本相似度计算：支持模糊匹配（如”登录按钮”匹配”Log In”、“Sign In”）

3. LLMProvider（LLM 适配器）

职责：统一不同 LLM API 的接口

关键设计：

• Provider 抽象层：统一的 chat() 接口，内部适配不同 API 格式
• Token 计数：实时跟踪 Token 消耗，支持预算控制
• 降级策略：主模型失败时自动切换到备用模型

4. ActionExecutor（动作执行器）

职责：将 LLM 返回的动作指令转换为真实 DOM 操作

技术要点：

• 事件模拟：支持 MouseEvent、KeyboardEvent、InputEvent 等多种事件类型
• 表单处理：智能识别表单验证规则，处理必填字段、格式校验
• 异步等待：自动检测网络请求、动画完成、DOM 更新

5. AgentPanel（UI 面板）

职责：提供人机协同界面

功能特性：

• 浮动面板：不遮挡页面内容的可拖动面板
• 动作预览：高亮显示即将操作的元素
• 执行日志：实时显示动作执行状态
• 人工介入：允许用户随时暂停、修改、跳过动作

设计理念解析

1. “In-Page First” 哲学

PageAgent 的设计哲学可以概括为：增强而非替代。

传统自动化试图完全替代人工操作，追求”无人值守”的自动化。而 PageAgent 选择了一条中间路线：

• 人类负责决策：用户设定目标，确认关键步骤
• AI 负责执行：处理重复性、机械性的操作细节
• 双向透明：用户知道 AI 在做什么，AI 理解用户的意图

这种设计避免了全自动化的不可靠性，同时大幅提升了效率。

2. “文本化 DOM” 的技术选型

为什么 PageAgent 选择文本化索引而非多模态视觉模型？

决策权衡：

PageAgent 团队认为，对于结构化的 Web 页面，DOM 树本身就是完美的”视觉表示”，无需额外的图像识别。

3. “渐进式增强” 的集成策略

PageAgent 设计了三种集成模式，适应不同场景：

graph TD
    A[集成模式] --> B[Script 标签]
    A --> C[NPM 包]
    A --> D[Chrome 扩展]
    
    B --> E["最简单<br/>单行代码<br/>适合快速试用"]
    C --> F["最灵活<br/>完整 API 控制<br/>适合深度集成"]
    D --> G["最强大<br/>跨标签页任务<br/>适合个人效率"]

这种设计确保：

• 低门槛：新手可以 1 分钟上手
• 高上限：专家可以深度定制
• 广覆盖：满足不同用户群体的需求

结论

PageAgent 的技术架构体现了对浏览器自动化问题的深刻思考。通过将 Agent 嵌入页面内部、采用文本化 DOM 索引、设计人机协同界面，PageAgent 在保持低复杂度的同时，实现了强大的自动化能力。

其核心创新点总结如下：

1. 位置创新：从”外部控制”转为”内部增强”
2. 索引创新：将 DOM 树压缩为 LLM 友好的文本索引
3. 交互创新：Human-in-the-loop 的协同设计
4. 工程创新：零基础设施、单行代码集成

这种架构使 PageAgent 成为当前浏览器自动化领域的一股清流，为后续技术发展提供了新的思路。

参考资料

• PageAgent Architecture Documentation
• PageAgent GitHub Source Code
• Browser-use: The Inspiration Behind PageAgent
• The Agent Living in Your Web Page - Medium