AI导哈

视觉测试代理

一款AI驱动的视觉测试代理，能够像真实用户一样查看应用程序，执行自动化测试，速度比传统方法快15倍，无需直接操作屏幕。

  • by chriswu727
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 chriswu727/screen-agent

使用说明

屏幕代理

AI原生测试代理可以像真实用户一样查看您的应用程序——比Claude Code快15倍，无需触摸屏幕。

一 主控程序 用于自主视觉测试的服务器。AI用自然语言规划测试步骤，服务器执行这些步骤，而无需LLM往返。通过CDP（Chrome）或Accessibility API（本机应用程序）在后台工作。

快速演示

# The AI plans. The server executes. No LLM round-trips. Background. 3 seconds.
run_test(name="Login Flow", steps=[
    {"find": "Email",    "action": "click_and_type", "text": "user@test.com"},
    {"find": "Password", "action": "click_and_type", "text": "secret123"},
    {"find": "Log in",   "action": "click"},
    {"verify": "Dashboard"},
])
# → ✅ 4/4 passed in 800ms. Screenshot evidence attached.

为什么？

每个测试工具都让您做出选择： 快速但脆弱 （剧作家）或 聪明但缓慢 （克劳德代码计算机使用）。Screen Agent既是：

  • 自主执行 — run_test() 在服务器端执行所有步骤。没有LLM往返。150ms/步与克劳德代码的1-3s/步相比。 快15倍。
  • 愿景优先 --LLM看到屏幕并决定在哪里点击。不是DOM选择器。UI更改不会中断测试，因为LLM会重新解释屏幕。
  • act + eval_js — act 返回LLM的屏幕截图以进行可视化分析，然后在LLM提供的坐标处执行。 eval_js 通过CDP运行JavaScript进行断言。0.6秒内进行5次测试。
  • 背景测试 — window_scope +CDP允许您在任何macOS Space上测试Chrome应用程序，而无需触摸用户的屏幕。对于本机应用程序，在同一空间的其他窗口后进行测试。
  • 多后端输入链 -三种输入法（Accessibility API→ CGEvent→ pyautogui）具有自动回退功能。适用于本机应用程序、Electron应用程序和游戏引擎。
  • 输入监护人 --实时安全系统，当您触摸鼠标或键盘时暂停所有代理操作。没有其他工具提供此功能。
  • 跨应用程序工作流 --跨多个应用程序的测试流（电子邮件→ 浏览器→ 松弛）。没有其他工具可以做到这一点，因为它们都是单个应用程序。

建筑

┌──────────────────────────────────┐
│          MCP Layer               │  22 tools via Model Context Protocol
├──────────────────────────────────┤
│          Engine Layer            │  InputChain (fallback) + Guardian (safety)
│                                  │  + WindowSession (background testing)
├──────────────────────────────────┤
│        Platform Layer            │  Protocol-based backends
│  AX → CGEvent → pyautogui       │  macOS / Windows / Linux
└──────────────────────────────────┘

输入后端链

核心设计挑战： pyautogui 适用于约80%的应用程序，但适用于游戏引擎和许多Electron应用程序。Screen Agent通过 责任链 图案：

优先级 后端 方法 最适合
1 轴 AXPerformAction 原生macOS应用程序——语义化，无需坐标
2 CG事件 CGEventPost 游戏，电子——原生操作系统事件注入
3 PyAutoGUI Python包装器 跨平台回退

每个后端都实现了相同的功能 InputBackend 协议。如果一个失败，链会自动尝试下一个。所有尝试都会用遥测技术记录下来，以确保可观察性。

安装

pip install screen-agent

# Recommended: install macOS native backends
pip install screen-agent[macos]

快速开始

使用克劳德代码

claude mcp add screen -- screen-agent serve

使用Cursor/其他MCP客户端

添加到MCP配置中：

{
  "mcpServers": {
    "screen": {
      "command": "screen-agent",
      "args": ["serve"]
    }
  }
}

检查系统功能

screen-agent check

工具

感知

工具 说明
capture_screen 屏幕截图（完整或区域），返回图像进行视觉分析
list_windows 列出所有可见的窗口及其位置
get_active_window 当前聚焦窗口
get_cursor_position 当前鼠标位置

输入（全部支持 verify: true 用于动作后截图）

工具 说明
click 在坐标处单击（左/右/中，多次单击）
type_text 在光标处键入文本（macOS上通过剪贴板输入Unicode）
press_key 带修饰符的按键（例如Cmd+C）
scroll 滚轮位于可选位置
move_mouse 移动光标而不单击
drag 在两点之间单击并拖动
focus_window 通过部分标题匹配将窗口置于前面

OCR（自动检测中文、日文、韩文、英文）

工具 说明
ocr 提取所有带边界框的文本
find_text 查找文本并返回位置
click_text 查找文本并单击其中心

自主测试（差异化因素）

工具 说明
run_test 自主执行完整的测试计划——没有LLM往返。快15倍。
act 视觉优先：返回屏幕截图→ LLM外观→ 在坐标处执行
eval_js 通过CDP执行JavaScript。DOM断言、元素点击、状态检查
interact 基于OCR：通过文本查找元素+点击/键入一次调用

背景测试

工具 说明
window_scope 锁到窗户上。Chrome：自动CDP（任何空格）。原生：CGWindowList（同一空间）。
window_release 释放窗口范围，返回全屏模式

目视E2E测试

工具 说明
test_start 通过自动截图收集启动测试会话
test_step 开始测试步骤（自动捕获“之前”的屏幕截图）
test_verify 通过OCR文本检查或屏幕截图差异验证步骤
test_end 结束会话，生成带有证据的降价报告
test_status 当前会话状态

安全（输入监护人）

工具 说明
add_app 将应用添加到列表中——代理只能与列出的应用进行交互
remove_app 从列表中删除
set_region 仅限于像素区域
clear_scope 删除所有限制
get_agent_status 守护者状态、后端统计数据、范围信息

背景测试

Screen Agent可以测试应用程序 不占用屏幕.三种模式，自动选择：

模式1:CDP（Chrome/Electron——任何空间，完全不可见）

# Start Chrome with debugging port
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-test

# Connect — works even if Chrome is on a different desktop
window_scope(app="Chrome", url="localhost:3000")

# All operations go through Chrome's internal pipeline
interact(target="Submit", action="click")
interact(target="Email", action="click_and_type", text="test@example.com")

window_release()

CDP完全绕过macOS窗口服务器。截图来自Chrome的渲染器，点击通过Chrome的输入系统。 你的屏幕从未被触摸过。

模式2：窗口捕获（任何macOS应用程序-相同空间）

# Works with Figma, Xcode, Terminal, games — any app
window_scope(app="Figma", title="Design v2")
interact(target="Export", action="click")
window_release()

用途 CGWindowListCreateImage 即使在其他应用程序后面也能捕获窗口。需要相同的macOS空间。

模式3：全屏（原版）

没有 window_scope，与以前一样在全屏上运行。

回退优先级

window_scope called → try CDP (Chrome) → try CGWindowList (same Space) → error
no scope → full screen mode

输入监护人

Screen Agent独特的安全系统有两个保证：

  1. 用户优先级 --任何键盘/鼠标活动都会立即暂停代理。它仅在您空闲1.5秒后恢复（可配置）。
  2. 范围锁定 --将代理限制在特定的应用程序和/或屏幕区域。
# Agent can only interact with Chrome and Figma
add_app("Chrome")
add_app("Figma")

# Or restrict to a region
set_region(x=0, y=0, width=800, height=600)

配置

所有参数均可通过环境变量进行配置：

变量 默认值 描述
SCREEN_AGENT_COOLDOWN 1.5 守护者冷却秒数
SCREEN_AGENT_GUARDIAN_DISABLED 0 设置为“1”以禁用
SCREEN_AGENT_INPUT_BACKENDS ax、cgevent、pyautogui 后端优先级顺序
SCREEN_AGENT_MAX_DIMENSION 2560 最大屏幕截图尺寸
SCREEN_AGENT_LOG_LEVEL 信息 日志记录级别

平台支持

功能 macOS Windows Linux
屏幕截图 mss mss mss
AX输入 石英AX - -
CGEvent输入 Quartz - -
pyautogui输入 回退 回退 后退
窗口管理 AppleScript - wmctrl
OCR 视觉框架 - -
视网膜缩放 自动检测 - -
窗口捕获 CGWindowListCreateImage 打印窗口 xdotool+ImageMagick

发展

git clone https://github.com/chriswu727/screen-agent
cd screen-agent
pip install -e ".[dev,macos]"
pytest tests/unit/ -v
ruff check src/ tests/

看 DEVPATH.md 开发历史和架构决策。

许可证

麻省理工学院

相关 MCP