PageEyes Agent 跨端 UI 自动化技术全景一、项目定位与能力地图自然语言如何变成 UI 操作1.1 两种感知模式不是同一条链1.2 固定源码中的功能矩阵二、Pydantic AI 架构与执行闭环规划、单步执行和失败终止2.1 PageEyes 包与 OmniParser 服务是两个边界2.2 真实执行顺序是“两层 Agent 工具循环”2.3 为什么强制一次只调用一个工具三、OmniParser 多源感知从截图到可点击元素图3.1 PageEyes 客户端给 LLM 的并不是完整检测结果3.2 OCR、图标与浮层的实际融合顺序3.3 缓存与并发的边界四、五端设备、Skills 与报告统一接口下面仍有平台差异4.1 设备抽象统一了调用方式没有抹平系统前置条件4.2 Skills 如何参与弹窗处理4.3 报告如何生成五、固定版本安装与第一次运行5.1 为什么不能只写 pip install page-eyes5.2 用 VLM 模式完成最小 Web 闭环5.3 切换到 LLM OmniParser六、安全、可靠性与版本边界6.1 UI Agent 拥有真实副作用6.2 截图、Prompt、缓存和报告的数据流6.3 OmniParser API 默认不适合公网裸露6.4 许可证与成熟度七、适用场景与总结参考资料传统 UI 自动化依赖 XPath、CSS Selector、Accessibility ID或坐标脚本页面一改就容易失效。PageEyes Agent 尝试把操作意图改写成自然语言任务再让 Agent 根据当前屏幕逐步感知、决策和调用工具。它适合探索性测试、UI 巡检和跨端流程验证但不是“输入一句话就能在任意设备上百分之百成功”的魔法层。PageEyes Agent 是基于 Pydantic AI 的自然语言 UI 自动化框架支持 Web、Android、HarmonyOS NEXT、iOS 和 Electron。它既可让 VLM 直接理解截图也可通过OmniParser 融合OCR、图标检测、Caption 与浮层检测后交给 LLM。本文基于固定源码拆解规划执行闭环、跨端工具、Skills、报告、部署与安全边界。GitHub仓库https://github.com/cmyk-labs/page-eyes-agent.git如果这个仓库对你有帮助欢迎在 GitHub 上点一个 Star ⭐ 支持一下。官方GitHub仓库https://github.com/tencentmusic/page-eyes-agent官方文档https://tencentmusic.github.io/page-eyes-agent/一、项目定位与能力地图自然语言如何变成 UI 操作1.1 两种感知模式不是同一条链PageEyes Agent 的上层任务编排相同但屏幕如何进入模型取决于AGENT_MODEL_TYPE模式屏幕输入定位方式外部依赖适合场景vlm当前截图以 Base64ImageUrl交给视觉语言模型模型输出 0999 归一化坐标再换算为设备像素一个支持视觉的模型端点快速体验、希望少部署一个感知服务llmOmniParser 返回元素 ID、文本和上下左右邻接关系LLM 选择元素 ID运行时根据完整 bbox 计算坐标文本 LLM OmniParser 服务希望用结构化元素降低图片 Token或使用小参数 LLM 做规划因此“项目不依赖 VLM”只适用于llm OmniParser路径固定版本同时实现了 VLM 路径。反过来OmniParser 也不是所有部署都必需vlm模式不会调用它。1.2 固定源码中的功能矩阵能力用户看到的结果固定源码结论自然语言任务输入一段或多步操作说明PlanningAgent先产生结构化步骤再逐步执行Web 自动化打开页面、点击、输入、下拉选择、滚动、上传Playwright 驱动本机 ChromeAndroid点击、输入、滑动、URL Scheme、启动应用ADB/adbutils可指定设备 serialHarmonyOS NEXT截图、点击、输入、滑动、启动 AbilityHDC/hdcutils不是复用 Android ADBiOS点击、输入、手势、Safari URL、启动应用WebDriverAgent facebook-wda需要 WDA 地址Electron接管窗口、点击、输入、多窗口切换Playwright 通过 CDP 接入已运行的 Electron 进程自然语言断言判断屏幕是否包含/不包含关键词LLM 模式基于解析元素文本不是像素差分或业务 API 断言Skills加载自定义技能和内置弹窗处理策略Pydantic AISkillsCapability属于行为指令不是权限沙箱步骤报告返回成功状态、步骤摘要和 HTML 路径每步记录动作、截图、元素与结果最后注入本地模板解析缓存相同/近似截图可复用元素结果可选 Milvus 图像向量不是知识库 RAG用户仓库固定提交中的早期技术文章素材包含下面的执行流程图可用于理解“感知—决策—动作—再感知”的思想但不能替代 1.3.9 的类级调用链。该用户仓库提交与上游官方提交一致本文后续仍以当前源码为准。二、Pydantic AI 架构与执行闭环规划、单步执行和失败终止2.1 PageEyes 包与 OmniParser 服务是两个边界根pyproject.toml声明 Python3.12固定依赖包括 Pydantic AI 1.73.0、Pydantic AI Skills、Playwright、ADB、HDC、WDA、iOS 设备和对象存储客户端。构建配置明确排除了OmniParser2说明page-eyesPython 包并不会把视觉服务一同安装到业务进程中。page-eyes-agent/ ├── src/page_eyes/ │ ├── agent.py # 规划、执行循环、五类 Agent 与报告 │ ├── config.py # 模型、模式、浏览器、Omni 与存储配置 │ ├── deps.py # 屏幕、步骤、上下文、工具参数/结果模型 │ ├── prompt.py # 规划与执行约束 │ ├── device.py # 五端设备连接与生命周期 │ ├── tools/ │ │ ├── _base.py # 工具包装、感知、断言、失败标记 │ │ ├── _mobile.py # 移动端公共动作 │ │ ├── web.py # Playwright Web 工具 │ │ ├── android.py # Android 适配 │ │ ├── harmony.py # HarmonyOS NEXT 适配 │ │ ├── ios.py # WDA 适配 │ │ └── electron.py # CDP 与窗口适配 │ ├── skills/gui-popup-handler/ # 内置弹窗处理 Skill │ └── report_template.html # 本地步骤报告模板 ├── OmniParser2/ │ ├── main.py # FastAPI 入口 │ ├── routers/omni/ # 上传、队列、缓存和解析 API │ ├── core/parse.py # 多源视觉解析主链 │ ├── core/handler.py # R-tree、空间排序与邻接关系 │ ├── model/ # 图标、Caption 与 Overlay 模型 │ └── Dockerfile # 独立视觉服务镜像 ├── tests/ # 五端和规划示例 └── docs/ # MkDocs 文档和技术文章这种拆分的好处是 Agent 进程保持相对轻量多个执行端可以共享一个视觉服务代价是网络延迟、截图传输、服务认证、模型版本和缓存隔离都要单独治理。2.2 真实执行顺序是“两层 Agent 工具循环”固定agent.py中可以定位到PlanningAgent和执行Agent没有一个独立的ReflectionAgent类。完整顺序如下用户任务 → PlanningAgent.run(prompt) → PlanningOutputType 校验 steps → 追加“结束任务” → 为当前步骤创建 StepInfo → executor Agent.iter(单个 planning.instruction) → 获取当前屏幕 → 模型选择工具和参数 → ToolHandler 记录动作并执行 → 工具结果返回模型必要时继续感知和调用 → 步骤无截图时自动补一张未解析截图 → 若当前步骤失败break直接汇总报告不再进入“结束任务” → 若前序步骤全部成功进入追加的“结束任务”并执行 tear_down → 汇总 is_success、steps、device_size → 生成本地 HTML 报告规划输出和执行模型都配置了重试执行时还设置请求次数上限。重试可以处理格式和偶发工具错误却不等于业务幂等第一次点击已经提交表单模型重试后再次点击可能产生重复副作用。失败分支还有一个资源生命周期边界tear_down只在循环真正走到“结束任务”时调用前序步骤失败后的break会跳过它。对 Web 端而言WebAgentTool.tear_down()还负责关闭浏览器上下文并停止 Playwright 客户端调用方应使用外层try/finally或显式清理兜底不能假设失败返回前已经自动释放资源。移动端的同名方法主要补最终截图Electron 则保留由外部管理的进程各端行为不能一概而论。2.3 为什么强制一次只调用一个工具tools/_base.py的装饰器会在工具前后更新StepInfo捕获异常并让模型重试。handle_graph_node()记录同一响应是否包含多个工具调用ToolHandler.pre_handle()检测到并行工具时抛出ModelRetry与 Prompt 中“一次仅使用一个工具”的规则形成双重限制。这不是为了降低吞吐而是为了保持因果顺序。UI 上“输入关键词”和“点击搜索”不能在同一时刻并行每次动作后重新读取屏幕也能避免使用已经过期的元素坐标。仍需注意两个源码边界当前run()没有持久化检查点、事务回滚或人工审批层AgentContext.steps在任务开始处也没有显式重置。稳妥做法是“一项任务创建一个 Agent 实例”有副作用的流程由调用方增加审批、幂等键和测试环境隔离。三、OmniParser 多源感知从截图到可点击元素图3.1 PageEyes 客户端给 LLM 的并不是完整检测结果LLM 模式中平台工具先截图get_screen()再向OMNI_BASE_URL/omni/parse/发送 multipart 请求。响应包含标注图 URL 和parsed_content_list完整元素会写入当前步骤上下文但给 LLM 的字段会被裁剪get_screen_info()主要保留id content left_elem_ids right_elem_ids top_elem_ids bottom_elem_ids点击工具收到element_id后才从上下文中的 bbox 计算真实坐标。这样可以减少 Prompt 中重复的坐标、类型和来源字段同时让模型用“文字 空间关系”理解界面。下面的用户仓库动图展示了元素信息形态图片同样固定到本文提交。3.2 OCR、图标与浮层的实际融合顺序FastAPI 启动时初始化 PaddleOCR、图标检测器、图标 Captioner 和 Overlay 检测器。请求进入OmniParser.parse()后严格按以下顺序执行RGB 截图 → PaddleOCR文字框、文字、置信度 → 图标 YOLO图标框、置信度 → 将坐标归一化 → R-tree 处理图标与 OCR 重叠 → 裁剪过滤后的图标区域 → Florence-2 LoRA 生成图标描述 → Overlay YOLO 检测加载中、弹窗、关闭按钮 → 合并文字、图标、浮层 → 空间排序并分配元素 ID → 计算上下左右邻接关系并绘制标注图 → 返回结构化元素后台写入可选缓存OCR 配置使用 PP-OCRv5 Server Detection 和 PP-OCRv4 Mobile Recognition。图标检测来源于 OmniParser V2 权重缺少文字的图标裁剪后交给 Florence-2 Caption。Overlay 模型则单独识别“页面加载中”“弹窗”和“弹窗关闭按钮”。BoxesHandler使用 R-tree 快速查询重叠候选OCR 在图标内部时可以把文字合并进图标描述图标落在大文字框中时也会按规则取舍。Overlay 不参加这一步去重而是在 Caption 之后直接加入最终集合。文章如果把浮层检测画成 OCR 之前的“前置哨兵”就与固定源码顺序不一致。3.3 缓存与并发的边界OmniParser 路由用队列槽位限制同时解析数默认配置是 4。启用 Milvus 后服务先用图像向量查询近期相似截图命中则复用元素和标注图未命中才执行模型链结果通过后台任务写回。这只是解析缓存不代表已证明四并发吞吐或多租户隔离。固定image_vector_storage.py会保存请求key但缓存查询条件并没有按key过滤不能把它当认证密钥或租户隔离键。多用户环境应按租户拆分存储或补充过滤和访问控制不需要缓存时显式设置MILVUS_ENABLEfalse。四、五端设备、Skills 与报告统一接口下面仍有平台差异4.1 设备抽象统一了调用方式没有抹平系统前置条件device.py将客户端和当前操作目标装进泛型Device五类*Agent.create()再组合对应 Device、Tool 和 AgentDeps平台连接方式主要动作真实限制WebPlaywright 启动本机 Chrome Persistent Context页面导航、坐标点击、输入、滚动、下拉、上传不是任意浏览器测试账号和 Profile 需要隔离AndroidADB/adbutils截图、点击、滑动、输入、URL、应用启动不传 serial 时选择首台设备设备必须开启调试HarmonyOS NEXTHDC/hdcutilssnapshot、uitest、输入、滑动、Ability 启动需要 HDC 连接键和对应开发环境iOSWDA/facebook-wdapymobiledevice3点击、输入、手势、Safari、应用启动wda_url必传WDA 需要 macOS、Xcode 和签名ElectronPlaywrightconnect_over_cdp复用 Web 工具、切换/关闭窗口应用必须开放 CDP不等于支持任意原生桌面程序Electron 截图使用scalecss消除 Retina DPR 导致的坐标偏移并在点击前切换到最新页面。Agent 只接管已有 Electron 进程不负责可靠地启动或关闭外部应用CDP 端口也应只绑定回环或可信网络。4.2 Skills 如何参与弹窗处理build_agent()默认扫描调用者的./skillspopup_closeTrue时还会附加包内技能目录。当前内置gui-popup-handler/SKILL.md会根据屏幕中的遮罩或“弹窗关闭按钮”指导模型处理广告、更新、登录、权限、Cookie 和新手引导。Overlay YOLO 负责“看见浮层类型”Skill 负责“决定如何处理”实际点击仍由平台 Tool 完成。这三层不要混为一个模型。Skill 也不是安全沙箱。例如策略可能接受 Cookie、关闭登录框或允许与任务相关的权限。敏感流程应只加载审阅过的技能必要时将popup_closeFalse并在上层禁止支付、删除、授权和隐私确认等动作自动执行。4.3 报告如何生成每次工具调用都会把 action、参数、截图 URL、元素和成功状态写入当前StepInfo。任务结束后create_report()将以下数据序列化为 JSON再替换本地report_template.html中的占位符{is_success:true,device_size:{width:0,height:0},steps:{}}返回值包含is_success、精简步骤列表和report_path。报告是本地 HTML 文件不是一个带权限体系的测试管理平台截图若上传 COS/MinIO则还要按对应对象存储策略控制访问。下图是用户仓库固定提交中较早的步骤报告示例当前模板样式可能已有变化但“按步骤回看动作和截图”的产品意图一致。五、固定版本安装与第一次运行5.1 为什么不能只写pip install page-eyes截至 2026-08-16PyPI 分发页的当前版本是1.4.0发布历史从1.3.8跳到1.4.0没有本文源码标识的1.3.9包。因此pip install page-eyes不能复现本文基线严格复现应固定完整提交gitclone https://github.com/cmyk-labs/page-eyes-agent.gitcdpage-eyes-agentgitcheckout b96ad114a146185b8d862b95a429a5d359c1d236 uvsync固定WebDevice使用channelchrome因此 Web 端需要 Google Chrome而不是 Playwright 默认 Chromium。可让 Playwright 安装 Chromeuv run playwrightinstallchrome固定 Git 树含有一个目录名以 ASCII 空格结尾原生 Windows 可能在 checkout 文档目录时失败。遇到该问题优先在 WSL/Linux 中克隆完整仓库如果只运行 Agent 包可用 Sparse Checkout 排除异常文档目录gitclone --no-checkout https://github.com/cmyk-labs/page-eyes-agent.gitcdpage-eyes-agentgitconfig core.protectNTFSfalsegitsparse-checkout init--conegitsparse-checkoutsetsrc testsgitcheckout b96ad114a146185b8d862b95a429a5d359c1d236 uvsynccore.protectNTFSfalse只写入这个测试仓库的本地配置Sparse 规则不会把异常文档路径落到磁盘。根目录文件会随 Cone 模式保留src已包含包内 Skill 和报告模板。本文已用这组命令在 Windows 对固定提交完成 checkout省略该配置时仍会因尾空格路径失败。这种 Sparse 方案只安装 Agent 客户端不包含OmniParser2视觉服务应在 WSL/Linux 或独立服务器部署。5.2 用 VLM 模式完成最小 Web 闭环VLM 模式不需要 OmniParser适合先确认 Agent、模型和浏览器是否能闭环。复制.env.example后只保留实际需要的配置例如OPENAI_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 OPENAI_API_KEYreplace-with-your-own-key AGENT_MODEL_TYPEvlm AGENT_MODELopenai:qwen3-vl-plus BROWSER_HEADLESSFalse创建demo.pyimportasynciofrompage_eyes.agentimportWebAgentasyncdefmain():agentawaitWebAgent.create(popup_closeFalse)resultawaitagent.run( - 打开 https://example.com - 检查页面中出现 Example Domain ,report_dir./report)print(result)if__name____main__:asyncio.run(main())uv run python demo.py成功判据不只是脚本没有异常还应检查返回的is_success、每一步的 action 和report_path再打开 HTML 报告核对截图。VLM 模式没有基于 OmniParser 文本元素的assert_screen_contains工具上例中的“检查”依赖 VLM 直接观察并在失败时标记任务因此必须人工核对报告不能把它当确定性关键词断言。模型名称和兼容端点只是固定 README 的配置示例本文没有替读者验证账号权限、计费和模型可用性。5.3 切换到 LLM OmniParser客户端配置应使用固定config.py实际读取的键OPENAI_BASE_URLhttps://api.deepseek.com/v1 OPENAI_API_KEYreplace-with-your-own-key AGENT_MODEL_TYPEllm AGENT_MODELopenai:deepseek-v4-flash OMNI_BASE_URLhttp://127.0.0.1:8000 BROWSER_HEADLESSFalse部分安装文档仍出现AGENT_OMNI_BASE_URL或AGENT_HEADLESS当前配置类真正读取的是OMNI_BASE_URL和BROWSER_HEADLESS。官方安装文档用lighthouseac/omniparser:latest快速启动视觉服务但latest是移动标签无法证明它对应本文提交。评估环境可以按官方方式体验并记录本地镜像摘要严格复现则应从固定提交审阅和构建OmniParser2同时处理模型版本与权重问题。源码构建前尤其要确认Overlay YOLO 和 LoRA Adapter 由OmniParser2/.gitattributes交给 Git LFS 管理普通 Git Blob 中看到的是指针文本不能把 132 字节的指针当模型文件。在 WSL/Linux 完整检出后先执行gitlfsinstallgitlfs pullgitlfs ls-filesls-lhOmniParser2/model/weights/overlay_detect/model.pt确认权重是 MB 级实体文件后再构建视觉服务。Dockerfile 下载 Hugging Face 基础模型时也没有把配置中声明的 revision 真正传入下载调用。权重未还原、模型提交未固定或未审阅trust_remote_codeTrue时不应把服务标记为可复现。视觉服务启动后先检查curlhttp://127.0.0.1:8000/health再运行同一个无敏感数据的 Web 用例对比 VLM 与结构化 LLM 路径的步骤、耗时、点击稳定性和模型 Token而不是只比较是否最终成功。六、安全、可靠性与版本边界6.1 UI Agent 拥有真实副作用PageEyes 的工具可以点击、输入、上传文件、启动应用和接受弹窗。模型误判不是一条错误日志那么简单可能导致提交表单、发送内容、授权权限甚至触发交易。建议只在专用测试账号、测试设备和测试数据上运行对删除、支付、发送、授权、上传和隐私同意增加上层人工确认给重复提交接口设置幂等键不依赖模型重试保持幂等任务开始前明确允许的域名、应用、页面和动作失败后检查实际 UI 状态不要仅根据模型输出决定重跑。自然语言断言同样有边界。LLM 模式的expect_screen_contains是在解析元素文本中查找关键词OCR 漏字、遮挡、同名文本和离屏元素都会影响结果。关键交易应结合业务 API、数据库或传统自动化断言交叉验证。6.2 截图、Prompt、缓存和报告的数据流数据可能流向主要风险任务文本、界面元素LLM 提供商业务内容、账号信息和 Prompt 留存完整截图VLM 提供商或 OmniParser密码、Token、聊天内容和个人信息泄露原图、标注图Base64、COS 或 MinIO访问控制、生命周期和链接泄露图像向量与元素Milvus多租户缓存串用与历史页面残留步骤与截图 URL本地 HTML 报告报告被转发后泄露操作过程对象存储应使用私有 Bucket、TLS、最小权限和生命周期规则报告分享前脱敏。VLM 模式会把截图交给模型提供商LLM OmniParser 模式也可能把结构化页面文字交给外部 LLM不能笼统写成“数据完全留在本地”。6.3 OmniParser API 默认不适合公网裸露固定OmniParser2/main.py默认关闭 OpenAPI URL却配置了allow_origins[*]的 CORS。/omni/parse/没有可见的身份认证逻辑请求中的key也不能当认证。生产部署应放在受控网络或反向代理之后补充 TLS、认证、来源限制、请求大小、速率限制、超时和审计。模型供应链也需要固定图标 YOLO、Florence-2、LoRA、Overlay YOLO、PaddleOCR 和trust_remote_code都会影响结果与代码执行边界。记录镜像摘要、模型仓库提交和文件哈希比只记录 PageEyes Git 提交更接近可复现运行。6.4 许可证与成熟度固定源码将主项目标为 MITpyproject.toml的成熟度分类为 Beta。LICENSE还包含随附第三方组件的许可证告知因此“主项目 MIT”不等于所有模型、依赖、驱动和设备工具都使用 MIT。分发 Docker 镜像、模型权重或企业产品前应分别核对 Microsoft OmniParser/Florence、PaddleOCR、YOLO、Pydantic AI 及平台工具的许可与使用条款。七、适用场景与总结PageEyes Agent 适合用自然语言快速覆盖 UI 主路径、跨端回归、探索性测试、内容巡检和弹窗干扰场景。它最有辨识度的设计不是单一模型而是三层组合Pydantic AI 负责规划与工具编排 OmniParser/VLM 负责屏幕感知 Playwright/ADB/HDC/WDA/CDP 负责真实执行llm OmniParser把截图转换为带空间关系的元素图让文本模型也能操作 GUIvlm路径则用更少的部署组件换取更强的模型和图片输入成本。五端 Agent 复用上层编排但驱动、权限、坐标、应用启动和调试环境仍需逐端维护。它不适合作为无人值守的高风险生产操作机器人也不能替代确定性强的 API 测试和业务校验。落地时建议从一个无敏感数据的 Web 流程开始固定模型和源码逐步增加失败样例、动作白名单、人工审批、传统断言与报告治理。做到这些PageEyes 才会成为可观察的测试工具而不只是一个会点击屏幕的演示 Agent。参考资料用户提供的 GitHub 仓库https://github.com/cmyk-labs/page-eyes-agent.gitPageEyes Agent 官方 GitHub 仓库https://github.com/tencentmusic/page-eyes-agentPageEyes Agent 官方文档https://tencentmusic.github.io/page-eyes-agent/PageEyes Agent 官方 PyPI 分发页https://pypi.org/project/page-eyes/