架构说明

本页面介绍 Mole 的技术架构。用户功能介绍请参阅使用技巧。

Agentic Loop 架构

Mole 的核心是一个极简的 Agentic Loop（代理循环），设计哲学是：

代码管机制和边界（保下限），模型管决策和策略（定上限）

核心循环

采样 -> 有工具调用 -> 执行 -> 回写 -> 继续采样
         无工具调用 -> 结束

代码负责（机制 + 边界）

• 采样 -> 执行 -> 回写循环
• 预算执行（轮数上限、调用数上限、上下文长度限制）
• 死循环检测（相同工具+参数重复 N 次自动终止）
• 空响应重试
• 上下文超长自动压缩
• 子任务递归入口

模型负责（决策 + 策略）

• 意图分类 / 工具选择 / 任务拆分
• 验证策略 / 何时停止 / 回复措辞

任务分级

Mole 按任务复杂度分为四个等级，由模型自主判断：

第一类：直接回答

问候、闲聊、知识问答等，直接用文字回答，不调用任何工具。

第二类：单步操作

一个明确的小目标（搜索、点击、截图、查询），调用最合适的工具，拿到结果后回复。

第三类：多步任务

需要 2 步以上才能完成的目标。每一步根据上一步的实际结果来决定下一步，不会在开头就把所有步骤都规划好。

第四类：复合任务

包含多个相对独立的子目标。使用 spawn_subtask 将每个独立子目标拆分为隔离任务执行，每个子任务有独立的上下文，避免信息混杂。

多标签页编排

Mole 可以在一次任务中跨多个浏览器标签页操作——比如在一个页面搜索信息，提取数据后在另一个页面填写表单。

工作原理

所有页面操作工具都支持可选的 tab_id 参数。AI 的操作流程：

1. 打开新标签页 — tab_navigate(action='open', url='...') 返回新 tab 的 tab_id
2. 操作目标标签页 — 将 tab_id 传给任意工具：page_snapshot(tab_id=123)、cdp_input(tab_id=123, ...)、extract_data(tab_id=123, ...)
3. 清理 — 完成后 tab_navigate(action='close', tab_id=123)

关键规则

• element_id 是标签页私有的 — 从 Tab A 获取的元素 ID 不能在 Tab B 上使用。必须先在目标标签页调用 page_snapshot
• 默认行为不变 — 省略 tab_id 时，工具在用户发起对话的标签页上操作
• 列出打开的标签页 — tab_navigate(action='list') 显示所有标签页及其 ID

CDP 深度控制

Mole 通过 Chrome DevTools Protocol（CDP）接入 10 个协议域，提供浏览器进程级别的深度控制能力，弥补 Content Script 的固有限制：

• 可信事件注入 — 发送 isTrusted=true 的鼠标/键盘事件，绕过反爬的事件来源检测
• 对话框处理 — 自动检测和处理 alert/confirm/prompt 对话框，不再阻断自动化流程
• iframe 穿透 — 跨域 iframe 中执行 JS、获取文本，解决验证码和支付表单等场景
• 网络可见性 — 完整的请求/响应数据（包括 body 和 headers），以及 Cookie 读写
• 请求拦截 — 拦截请求后修改参数放行、返回 Mock 响应、或模拟失败，支持注入认证 headers 和绕过 CORS
• DOM 深度操作 — 无视同源策略直接查询/修改 DOM，获取精确 box model 几何信息
• 页面存储 — 跨域读写 localStorage / sessionStorage，无需 content script
• CSS 样式 — 获取计算样式和匹配规则、修改内联样式、动态注入 CSS 规则
• 视觉高亮 — 高亮标注 DOM 元素或区域，AI 操作时让用户直观看到操作对象
• 设备模拟 — 模拟移动端视口、覆盖 User-Agent、伪造地理位置和时区
• 控制台捕获 — 自动收集 console 输出和未捕获异常，辅助诊断页面问题

所有 CDP 工具共享统一的会话管理器（cdp-session.ts），自动管理 debugger 的 attach/detach 生命周期和域事件监听。

上下文自动压缩

当对话上下文变得过长时，Mole 会自动压缩历史上下文，保留关键信息，确保在 LLM 的上下文窗口限制内持续工作。这使得长时间的多步任务不会因为上下文溢出而失败。

Vision 视觉理解

Mole 具有视觉理解能力。当调用 screenshot 工具时，截图图片会自动注入 LLM 多模态上下文，AI 可以直接"看"到页面内容并据此做出判断。

标注截图

使用 screenshot(annotate=true) 获取带编号标注的截图：

• 视口内的每个可交互元素会被标注编号（1, 2, 3...）和红色高亮边框
• 同时返回编号到 element_id 的映射表（包含 tag、text 信息）
• AI 可以通过视觉识别目标元素，然后用映射表中的 element_id 精确操作
• 遵循 Look → Act → Check 协议：先观察页面全貌，再精确操作，关键步骤验证结果

限制：

• 每次任务最多注入 15 张截图图片，控制上下文体积
• 上下文压缩时图片自动降级为文字占位
• 优先使用 page_snapshot / page_skeleton 获取结构化数据，视觉分析作为补充
• 截图时自动隐藏悬浮球，避免遮挡页面内容