XuLan ScreenPilot

XuLan ScreenPilot

将真实的 Windows 屏幕转换为结构化元素表，供 AI Agent 操作。

English | 简体中文

XuLan ScreenPilot 解决 AI Agent 图形界面自动化的两个经典痛点——看不到元素和点不中：它向 Agent 提供带编号的元素表，而不是让 Agent 根据截图猜测坐标。Agent 扫描一次，读取表格，再通过元素 ID（click / type）操作屏幕，形成闭环。

完全使用本地 CPU。无需云端模型、GPU 或 API 密钥。

v1.0.0 亮点

• 默认开启紧凑扫描模式——编号前会过滤空的非交互式容器和重复标签：典型扫描可减少约 23% 的元素和提示词令牌，同时保留所有交互控件（compact=false 可恢复原始表格；meta.compact_removed 会报告过滤数量）。
• 默认开启隐私优先的元素簿——敏感窗口（记事本、聊天应用、登录对话框）的扫描会照常识别，但不会写入持久化元素簿（meta.privacy_skip）；显式设置 book=true 可覆盖此行为。
• 防卡死的 UIA 调用——目标窗口停止响应时，会在约 2 秒内（通过消息泵探测）返回结构化错误，而不是阻塞 30 秒以上；UIA 调用支持可配置超时，COM 故障会分类并计入 meta.errors.uia_stats。
• 明确的 expect 语义——业务等待超时不再一概变成 ok=false：action_executed 可区分“已发送点击，但未出现证据”和“操作本身失败”，避免盲目重试有风险的按钮。
• 按需获取最新截图裁剪——crop_screen / crop_xy 支持 force_refresh，绕过 60 秒的截图缓存，以便在操作后立即验证屏幕。

工作原理

三个引擎并行运行，并融合为一张元素表（优先级为 UIA > OCR > visual）：

引擎	来源	覆盖范围
uia	Windows UIA 辅助功能树	原生应用、浏览器（包括网页辅助功能树）——精准且快速
ocr	RapidOCR（onnxruntime，CPU）	没有控件树的游戏和自绘 UI；全屏文本回退
visual	OpenCV 连通组件 + 形状检测器	图标候选项；复选框／单选圆点／滑块／关闭按钮专用通道

融合过程会按中心包含关系或 IoU ≥ 0.3 去重，按从上到下、从左到右的顺序为元素编号，并生成：

• elements.json — 元素表缓存（按 id 查询以执行点击／输入）
• annotated_scan.png — 带注释的屏幕截图（红色 = UIA，蓝色 = OCR，绿色 = visual，每个框上都印有 id）

在此元素表基础上：

• 帧间 id 稳定性 — 重新扫描时，同一元素会保留相同 id；新元素会获得新 id（meta.tracker 会报告保留／新增／丢失的元素）。
• 后台捕获 — 通过 PrintWindow 获取被遮挡窗口的真实像素（无需将窗口置于前台）。
• 带漂移的点击 — 物理点击会加入高斯抖动和移动轨迹，让自动化操作看起来不那么机械；precise=True 可恢复像素级精度。
• 窗口堆叠感知 — 每次按坐标点击都会报告实际命中的顶层窗口（hit_window），并可拒绝点击被遮挡的目标（top_must）。
• 两级视觉 + 文本通道 — 以原生分辨率裁剪任意元素，以读取精细文本／图标；SigLIP 向量库支持按名称或图像查找 UI 元素，无需重新扫描。
• 时间维度 — 连续监视以捕获 Toast／瞬时反馈；输入后显示并验证；通过 ESC 探测卡顿；并在多帧之间区分静态与动态内容（UI 基础层与移动实体）。
• 业务级等待 — expect {find, mode: appear|disappear} 仅在屏幕上出现业务证据时，才将点击视为“成功”。
• 会话清理 — 每个会话的台账都会追踪 Agent 启动的窗口；cleanup_windows 会在任务结束时关闭这些窗口（仅使用 WM_CLOSE，采用六道安全检查，不使用 taskkill）；会话崩溃后会留下残留报告，下一会话会自动显示该报告。

安装

要求：Windows 10/11、Python 3.11+，仅需 CPU。

git clone <repo-url> screenpilot && cd screenpilot
pip install uiautomation rapidocr-onnxruntime onnxruntime opencv-python numpy pillow pyperclip pyautogui mcp
python screenpilot.py scan                       :: full-screen scan, prints the element table

已在 Python 3.13 上测试。可选的元素库向量通道和基准测试匹配器还需要 tokenizers，以及位于 SCREENPILOT_MODELS_DIR 下的 SigLIP int8 ONNX 权重。

可选：语义匹配器和元素库向量通道使用 SigLIP int8 ONNX 模型。将 SCREENPILOT_MODELS_DIR 设为存放模型目录的本地文件夹（参见 README.zh-CN.md §两级视觉与文本通道）。公开基准测试的数据集应放在 SCREENPILOT_DATASETS_DIR 下。

快速入门：Agent 闭环

# MCP tools (stdio server) or the CLI expose the same verbs:
scan_screen(window="记事本")        # 1. scan -> numbered element table
click_element(element_id=7)        # 2. act by id (UIA control-level when possible)
type_text(element_id=3, text="hi") # 3. type into an edit field
click_safe(element_id=12, expect={"find": "设置", "mode": "appear"})   # 4. act only when evidence shows
watch_burst(window="记事本", seconds=3)   # 5. catch transient feedback frames

MCP 配置（例如 Claude Desktop / ZCode）：

{"mcpServers": {"screenpilot": {
  "command": "python",
  "args": ["<path>/screenpilot/mcp_server.py"],
  "env": {"PYTHONIOENCODING": "utf-8"}
}}}

基准测试

公开的 GUI 定位基准测试、冻结的匹配器、官方评分。在配备 GTX 1070 Ti 的台式机上纯 CPU 运行（未使用 GPU）：

基准测试	范围	acc	oracle*	延迟
ScreenSpot-v2	全部 1,272 个问题	49.61%	88.36%	每个问题 1.94 秒
ScreenSpot-Pro	Windows，分层抽取的 200 个问题（以 4K 为主）	18.00%	78.5%	每个问题 3.87 秒

* oracle = GT 目标在元素表中有可识别的候选项时的指标——假设匹配器完美时的上限。它将识别引擎与匹配器的表现分开：在 ScreenSpot-Pro 上，差距几乎完全来自匹配器一侧（match_error 占未命中的 88%），这正是路线图所关注的方向。acc 数值采用冻结的启发式匹配器代替 Agent；实际使用时，Agent 会自行读取元素表，因此实际体验更接近 oracle 线，而非 acc。两项指标均会报告，不挑选有利结果。

复现：python bench/public_sspot.py --dataset v2 / --dataset pro（不包含数据集；两个 HF 来源见文档字符串）。

MCP 服务

通过 stdio 提供 20 个工具（scan_screen、scan_image、click_element、click_safe、click_xy、type_text、press_key、scroll_screen、snap_screen、crop_screen、crop_xy、book_find、watch_burst、verify_typing、probe_hang、split_static_dynamic、window_stack、activate_window、register_window、cleanup_windows）。scan_image 会在静态文件上离线运行相同的引擎；book_find 会查询持久化的元素簿（两级：文本匹配 + SigLIP 向量搜索），因此无需完整重新扫描即可找到反复出现的 UI。

会话清理（先注册后清理，sp/cleanup.py）：服务启动时会打开会话台账；register_window 会记录 Agent 自行启动的窗口，六个会更改状态的工具会自动记录操作新打开的窗口（仅供参考）。任务结束时，cleanup_windows 会温和地关闭台账中的窗口——仅使用 WM_CLOSE，绝不调用 taskkill——并遵循六道安全关卡：重新核验身份（hwnd+pid）、永久白名单（explorer / task manager / 自身进程）、仅清理本会话台账中的窗口、其他会话的窗口仅报告不处理、保护含未保存内容的窗口（绝不关闭未保存的工作），以及重新检查仍未关闭的窗口并报告，不升级处理。如果会话意外终止，系统会生成残留报告，并在下一会话首次调用工具时自动显示。

文档

完整文档（中文，包含内部机制、已知限制和测试套件索引）：README.zh-CN.md。

状态与路线图

系统已投入工作室日常使用，作为屏幕通道。已知问题均有记录，并未隐藏：深色主题专业应用（深色背景上的小字）会降低 OCR 召回率；4K 工具栏图标会给匹配器带来压力；Pro 基准分数受冻结的匹配器限制——请参阅 README.zh-CN.md §已知限制与坑。

许可证

开放核心：本仓库中的核心引擎依据 Apache License 2.0 发布。商业增值集成（闭源）不属于本仓库。

致谢

基于 RapidOCR、uiautomation、OpenCV 和 onnxruntime 构建。