【PageEyes Agent 跨端 UI 自动化】开源Pydantic AI、OmniParser 多源感知的UI 自动化Agent

PageEyes Agent 跨端 UI 自动化技术全景

[一、项目定位与能力地图：自然语言如何变成 UI 操作](#一、项目定位与能力地图：自然语言如何变成 UI 操作)
- [1.1 两种感知模式不是同一条链](#1.1 两种感知模式不是同一条链)
- [1.2 固定源码中的功能矩阵](#1.2 固定源码中的功能矩阵)
[二、Pydantic AI 架构与执行闭环：规划、单步执行和失败终止](#二、Pydantic AI 架构与执行闭环：规划、单步执行和失败终止)
- [2.1 PageEyes 包与 OmniParser 服务是两个边界](#2.1 PageEyes 包与 OmniParser 服务是两个边界)
- [2.2 真实执行顺序是"两层 Agent + 工具循环"](#2.2 真实执行顺序是“两层 Agent + 工具循环”)
- [2.3 为什么强制一次只调用一个工具](#2.3 为什么强制一次只调用一个工具)
[三、OmniParser 多源感知：从截图到可点击元素图](#三、OmniParser 多源感知：从截图到可点击元素图)
- [3.1 PageEyes 客户端给 LLM 的并不是完整检测结果](#3.1 PageEyes 客户端给 LLM 的并不是完整检测结果)
- [3.2 OCR、图标与浮层的实际融合顺序](#3.2 OCR、图标与浮层的实际融合顺序)
- [3.3 缓存与并发的边界](#3.3 缓存与并发的边界)
[四、五端设备、Skills 与报告：统一接口下面仍有平台差异](#四、五端设备、Skills 与报告：统一接口下面仍有平台差异)
- [4.1 设备抽象统一了调用方式，没有抹平系统前置条件](#4.1 设备抽象统一了调用方式，没有抹平系统前置条件)
- [4.2 Skills 如何参与弹窗处理](#4.2 Skills 如何参与弹窗处理)
- [4.3 报告如何生成](#4.3 报告如何生成)
五、固定版本安装与第一次运行
- [5.1 为什么不能只写 `pip install page-eyes`](#5.1 为什么不能只写 pip install page-eyes)
- [5.2 用 VLM 模式完成最小 Web 闭环](#5.2 用 VLM 模式完成最小 Web 闭环)
- [5.3 切换到 LLM + OmniParser](#5.3 切换到 LLM + OmniParser)
六、安全、可靠性与版本边界
- [6.1 UI Agent 拥有真实副作用](#6.1 UI Agent 拥有真实副作用)
- [6.2 截图、Prompt、缓存和报告的数据流](#6.2 截图、Prompt、缓存和报告的数据流)
- [6.3 OmniParser API 默认不适合公网裸露](#6.3 OmniParser API 默认不适合公网裸露)
- [6.4 许可证与成熟度](#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`	当前截图以 Base64 `ImageUrl` 交给视觉语言模型	模型输出 0～999 归一化坐标，再换算为设备像素	一个支持视觉的模型端点	快速体验、希望少部署一个感知服务
`llm`	OmniParser 返回元素 ID、文本和上下左右邻接关系	LLM 选择元素 ID，运行时根据完整 bbox 计算坐标	文本 LLM + OmniParser 服务	希望用结构化元素降低图片 Token，或使用小参数 LLM 做规划

因此，"项目不依赖 VLM"只适用于 llm + OmniParser 路径；固定版本同时实现了 VLM 路径。反过来，OmniParser 也不是所有部署都必需，vlm 模式不会调用它。

1.2 固定源码中的功能矩阵

能力	用户看到的结果	固定源码结论
自然语言任务	输入一段或多步操作说明	`PlanningAgent` 先产生结构化步骤，再逐步执行
Web 自动化	打开页面、点击、输入、下拉选择、滚动、上传	Playwright 驱动本机 Chrome
Android	点击、输入、滑动、URL Scheme、启动应用	ADB/`adbutils`，可指定设备 serial
HarmonyOS NEXT	截图、点击、输入、滑动、启动 Ability	HDC/`hdcutils`，不是复用 Android ADB
iOS	点击、输入、手势、Safari URL、启动应用	WebDriverAgent + `facebook-wda`，需要 WDA 地址
Electron	接管窗口、点击、输入、多窗口切换	Playwright 通过 CDP 接入已运行的 Electron 进程
自然语言断言	判断屏幕是否包含/不包含关键词	LLM 模式基于解析元素文本，不是像素差分或业务 API 断言
Skills	加载自定义技能和内置弹窗处理策略	Pydantic AI `SkillsCapability`，属于行为指令，不是权限沙箱
步骤报告	返回成功状态、步骤摘要和 HTML 路径	每步记录动作、截图、元素与结果，最后注入本地模板
解析缓存	相同/近似截图可复用元素结果	可选 Milvus + 图像向量，不是知识库 RAG

用户仓库固定提交中的早期技术文章素材包含下面的执行流程图，可用于理解"感知---决策---动作---再感知"的思想，但不能替代 1.3.9 的类级调用链。该用户仓库提交与上游官方提交一致，本文后续仍以当前源码为准。

二、Pydantic AI 架构与执行闭环：规划、单步执行和失败终止

2.1 PageEyes 包与 OmniParser 服务是两个边界

根 pyproject.toml 声明 Python >=3.12，固定依赖包括 Pydantic AI 1.73.0、Pydantic AI Skills、Playwright、ADB、HDC、WDA、iOS 设备和对象存储客户端。构建配置明确排除了 OmniParser2，说明 page-eyes Python 包并不会把视觉服务一同安装到业务进程中。

text 复制代码

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 类。完整顺序如下：

text 复制代码

用户任务
  → 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() 主要保留：

text 复制代码

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() 后，严格按以下顺序执行：

text 复制代码

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_ENABLE=false。

四、五端设备、Skills 与报告：统一接口下面仍有平台差异

4.1 设备抽象统一了调用方式，没有抹平系统前置条件

device.py 将客户端和当前操作目标装进泛型 Device，五类 *Agent.create() 再组合对应 Device、Tool 和 AgentDeps：

平台	连接方式	主要动作	真实限制
Web	Playwright 启动本机 Chrome Persistent Context	页面导航、坐标点击、输入、滚动、下拉、上传	不是任意浏览器；测试账号和 Profile 需要隔离
Android	ADB/`adbutils`	截图、点击、滑动、输入、URL、应用启动	不传 serial 时选择首台设备；设备必须开启调试
HarmonyOS NEXT	HDC/`hdcutils`	snapshot、uitest、输入、滑动、Ability 启动	需要 HDC 连接键和对应开发环境
iOS	WDA/`facebook-wda` + `pymobiledevice3`	点击、输入、手势、Safari、应用启动	`wda_url` 必传；WDA 需要 macOS、Xcode 和签名
Electron	Playwright `connect_over_cdp`	复用 Web 工具、切换/关闭窗口	应用必须开放 CDP；不等于支持任意原生桌面程序

Electron 截图使用 scale="css" 消除 Retina DPR 导致的坐标偏移，并在点击前切换到最新页面。Agent 只接管已有 Electron 进程，不负责可靠地启动或关闭外部应用；CDP 端口也应只绑定回环或可信网络。

4.2 Skills 如何参与弹窗处理

build_agent() 默认扫描调用者的 ./skills；popup_close=True 时还会附加包内技能目录。当前内置 gui-popup-handler/SKILL.md 会根据屏幕中的遮罩或"弹窗关闭按钮"，指导模型处理广告、更新、登录、权限、Cookie 和新手引导。

Overlay YOLO 负责"看见浮层类型"，Skill 负责"决定如何处理"，实际点击仍由平台 Tool 完成。这三层不要混为一个模型。

Skill 也不是安全沙箱。例如策略可能接受 Cookie、关闭登录框或允许与任务相关的权限。敏感流程应只加载审阅过的技能，必要时将 popup_close=False，并在上层禁止支付、删除、授权和隐私确认等动作自动执行。

4.3 报告如何生成

每次工具调用都会把 action、参数、截图 URL、元素和成功状态写入当前 StepInfo。任务结束后，create_report() 将以下数据序列化为 JSON，再替换本地 report_template.html 中的占位符：

json 复制代码

{
  "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-16，PyPI 分发页的当前版本是 1.4.0，发布历史从 1.3.8 跳到 1.4.0，没有本文源码标识的 1.3.9 包。因此 pip install page-eyes 不能复现本文基线，严格复现应固定完整提交：

bash 复制代码

git clone https://github.com/cmyk-labs/page-eyes-agent.git
cd page-eyes-agent
git checkout b96ad114a146185b8d862b95a429a5d359c1d236
uv sync

固定 WebDevice 使用 channel="chrome"，因此 Web 端需要 Google Chrome，而不是 Playwright 默认 Chromium。可让 Playwright 安装 Chrome：

bash 复制代码

uv run playwright install chrome

固定 Git 树含有一个目录名以 ASCII 空格结尾，原生 Windows 可能在 checkout 文档目录时失败。遇到该问题，优先在 WSL/Linux 中克隆完整仓库；如果只运行 Agent 包，可用 Sparse Checkout 排除异常文档目录：

bash 复制代码

git clone --no-checkout https://github.com/cmyk-labs/page-eyes-agent.git
cd page-eyes-agent
git config core.protectNTFS false
git sparse-checkout init --cone
git sparse-checkout set src tests
git checkout b96ad114a146185b8d862b95a429a5d359c1d236
uv sync

core.protectNTFS=false 只写入这个测试仓库的本地配置；Sparse 规则不会把异常文档路径落到磁盘。根目录文件会随 Cone 模式保留，src 已包含包内 Skill 和报告模板。本文已用这组命令在 Windows 对固定提交完成 checkout；省略该配置时仍会因尾空格路径失败。这种 Sparse 方案只安装 Agent 客户端，不包含 OmniParser2，视觉服务应在 WSL/Linux 或独立服务器部署。

5.2 用 VLM 模式完成最小 Web 闭环

VLM 模式不需要 OmniParser，适合先确认 Agent、模型和浏览器是否能闭环。复制 .env.example 后只保留实际需要的配置，例如：

dotenv 复制代码

OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
OPENAI_API_KEY=replace-with-your-own-key
AGENT_MODEL_TYPE=vlm
AGENT_MODEL=openai:qwen3-vl-plus
BROWSER_HEADLESS=False

创建 demo.py：

python 复制代码

import asyncio

from page_eyes.agent import WebAgent


async def main():
    agent = await WebAgent.create(popup_close=False)
    result = await agent.run("""
    - 打开 https://example.com
    - 检查页面中出现 Example Domain
    """, report_dir="./report")
    print(result)


if __name__ == "__main__":
    asyncio.run(main())

bash 复制代码

uv run python demo.py

成功判据不只是脚本没有异常，还应检查返回的 is_success、每一步的 action 和 report_path，再打开 HTML 报告核对截图。VLM 模式没有基于 OmniParser 文本元素的 assert_screen_contains 工具，上例中的"检查"依赖 VLM 直接观察并在失败时标记任务，因此必须人工核对报告，不能把它当确定性关键词断言。模型名称和兼容端点只是固定 README 的配置示例，本文没有替读者验证账号权限、计费和模型可用性。

5.3 切换到 LLM + OmniParser

客户端配置应使用固定 config.py 实际读取的键：

dotenv 复制代码

OPENAI_BASE_URL=https://api.deepseek.com/v1
OPENAI_API_KEY=replace-with-your-own-key
AGENT_MODEL_TYPE=llm
AGENT_MODEL=openai:deepseek-v4-flash
OMNI_BASE_URL=http://127.0.0.1:8000
BROWSER_HEADLESS=False

部分安装文档仍出现 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 完整检出后先执行：

bash 复制代码

git lfs install
git lfs pull
git lfs ls-files
ls -lh OmniParser2/model/weights/overlay_detect/model.pt

确认权重是 MB 级实体文件后再构建视觉服务。Dockerfile 下载 Hugging Face 基础模型时也没有把配置中声明的 revision 真正传入下载调用。权重未还原、模型提交未固定或未审阅 trust_remote_code=True 时，不应把服务标记为可复现。

视觉服务启动后先检查：

bash 复制代码

curl http://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 许可证与成熟度

固定源码将主项目标为 MIT，pyproject.toml 的成熟度分类为 Beta。LICENSE 还包含随附第三方组件的许可证告知，因此"主项目 MIT"不等于所有模型、依赖、驱动和设备工具都使用 MIT。分发 Docker 镜像、模型权重或企业产品前，应分别核对 Microsoft OmniParser/Florence、PaddleOCR、YOLO、Pydantic AI 及平台工具的许可与使用条款。

七、适用场景与总结

PageEyes Agent 适合用自然语言快速覆盖 UI 主路径、跨端回归、探索性测试、内容巡检和弹窗干扰场景。它最有辨识度的设计不是单一模型，而是三层组合：

text 复制代码

Pydantic AI 负责规划与工具编排
  + OmniParser/VLM 负责屏幕感知
  + Playwright/ADB/HDC/WDA/CDP 负责真实执行

llm + OmniParser 把截图转换为带空间关系的元素图，让文本模型也能操作 GUI；vlm 路径则用更少的部署组件换取更强的模型和图片输入成本。五端 Agent 复用上层编排，但驱动、权限、坐标、应用启动和调试环境仍需逐端维护。

它不适合作为无人值守的高风险生产操作机器人，也不能替代确定性强的 API 测试和业务校验。落地时建议从一个无敏感数据的 Web 流程开始，固定模型和源码，逐步增加失败样例、动作白名单、人工审批、传统断言与报告治理。做到这些，PageEyes 才会成为可观察的测试工具，而不只是一个会点击屏幕的演示 Agent。

参考资料

用户提供的 GitHub 仓库：https://github.com/cmyk-labs/page-eyes-agent.git
PageEyes Agent 官方 GitHub 仓库：https://github.com/tencentmusic/page-eyes-agent
PageEyes Agent 官方文档：https://tencentmusic.github.io/page-eyes-agent/
PageEyes Agent 官方 PyPI 分发页：https://pypi.org/project/page-eyes/

【PageEyes Agent 跨端 UI 自动化】开源Pydantic AI、OmniParser 多源感知的UI 自动化Agent

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-eyes

5.2 用 VLM 模式完成最小 Web 闭环

5.3 切换到 LLM + OmniParser

六、安全、可靠性与版本边界

6.1 UI Agent 拥有真实副作用

6.2 截图、Prompt、缓存和报告的数据流

6.3 OmniParser API 默认不适合公网裸露

6.4 许可证与成熟度

七、适用场景与总结

参考资料

5.1 为什么不能只写 `pip install page-eyes`