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通过 责任链 图案：

每个后端都实现了相同的功能 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

工具

感知

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

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

自主测试（差异化因素）

背景测试

目视E2E测试

安全（输入监护人）

背景测试

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)

配置

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

平台支持

发展

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 开发历史和架构决策。

许可证

麻省理工学院