🖥️ screen-use

browser-use，但面向整个桌面。

让任何 AI Agent 在 Windows 上拥有眼睛 👀 和双手 🖐️ —— 让 Claude、Kimi、Cursor 或你自己的 agent 看到屏幕、找到 UI 元素，并通过自然语言操作任何桌面应用。无需选择器。无需在 UI 变化时失效的脚本。

👆 跨应用自主：agent 从计算器读取结果，激活记事本并输入——每一步都由观看屏幕的 VLM 决定（见底部的实时思考流）。

单应用 agent 循环（VLM 自行计算 78 × 9）：

脚本化跨应用（计算器 → 记事本）：

单应用精确点击：

为什么

传统 RPA 记录选择器——一旦页面变化就会失效。browser-use（32k⭐）为浏览器解决了这个问题。screen-use 将同样的理念带到整个桌面：Excel、SAP 客户端、ERP 软件，甚至旧版 Win32 程序。

Related MCP server: WinPilot Computer Use MCP

工作原理

Your Agent (Claude / Kimi / Cursor / custom)   ← does the planning
        │  MCP or Python SDK
        ▼
┌─────────────────────────────────────────────┐
│ screen-use                                  │
│  Visual Loop ──► observe→think→act→verify   │
│  Introspection──► difficulty playbook        │
│  Meta-learning──► experience & vocab memory  │
│  Perception ──► UIA tree + screenshots (SoM)│
│  Locating   ──► strategy chain:             │
│                 ⓪ learned vocab mapping     │
│                 ① UIA text match (0 cost)   │
│                 ② Set-of-Mark + VLM         │
│  Action     ──► mouse / keyboard            │
└─────────────────────────────────────────────┘

VLM 是可选的，不是必需的。 定位策略链通过纯无障碍树文本匹配即可命中大多数目标——零模型调用，毫秒级延迟。视觉模型（云端或通过 Ollama 本地）仅在 UIA 盲区 UI 时介入。

快速开始

git clone https://github.com/tongriyaotxt/screen-use.git
cd screen-use
pip install -r requirements.txt

作为 Kimi CLI 插件（推荐）

一条命令——Kimi 立即获得全部 14 个桌面工具：

kimi mcp add --transport stdio screen-use -- <path-to-python.exe> -m screen_use.mcp_server
kimi mcp test screen-use   # verify the connection

可选安装捆绑的使用策略技能，该技能教 Kimi 最优的工具选择策略：

mkdir -p ~/.kimi/skills/screen-use && cp skills/screen-use/SKILL.md ~/.kimi/skills/screen-use/

然后只需告诉 Kimi："打开计算器并计算 123 × 456" 或 "读取我记事本中的内容"。

作为通用 MCP 服务器

添加到 claude_desktop_config.json（或任何兼容 MCP 的 agent 配置）：

{
  "mcpServers": {
    "screen-use": {
      "command": "python",
      "args": ["-m", "screen_use.mcp_server"],
      "cwd": "path/to/screen-use"
    }
  }
}

然后只需告诉你的 agent："打开计算器并计算 123 × 456。"

作为 Python SDK

from screen_use import ScreenUse

tools = ScreenUse()

tools.click_element("Save")            # locate + click, one call
tools.type_text("Hello, 你好")          # Unicode-safe (clipboard paste)
tools.hotkey("ctrl", "s")

# Atomic tools for vision-capable agents:
elements = tools.list_ui_elements()    # id, name, type, bbox — no model needed
shot = tools.screenshot(annotate=True) # Set-of-Mark annotated screenshot
tools.click(500, 300)

自主任务循环

一次调用，完全自主——agent 观察、决策、行动并自我纠正：

tools.run_task("打开计算器，算 25 乘以 4")   # observe → think → act → verify

Introspection (困难分类反思)：当循环卡住时，它会分类困难类型——无效果 / 重复循环 / 连续失败 / 元素缺失 / 意外弹窗——并通过针对性的提示策略进行反思，然后调整策略。

Meta-learning (元学习)：成功的运行会被记住。类似的历史任务会被作为经验提示召回，学到的词汇映射（例如“乘号” → Multiply by）成为策略链的新第一级。用得越多，它确实会变得越好。记忆存储在 ~/.screen_use/ 中。

工具（14）

原子工具（零模型依赖）：screenshot · list_ui_elements · click · double_click · right_click · click_element_id · type_text · hotkey · press · scroll

高级工具：find_element（策略链定位）· click_element（定位 + 点击）· read_screen（VLM 屏幕问答）· run_task（自主视觉循环）

视觉模型（可选）

仅当你的 agent 没有视觉且目标应用是 UIA 盲区时才需要。将 .env.example 复制为 .env：

未配置任何 VLM 时，原子工具和 UIA 匹配仍可完全工作。

安全

• 🚨 故障安全：将鼠标猛甩到左上角即可立即中止

• ✅ confirm_callback 钩子，用于批准每个操作（SDK）

• 🧪 ScreenUse(dry_run=True) 记录操作而不执行

可扩展性

screen-use 被设计为一组可替换的层——每一层都可以在不触及核心的情况下扩展：

安全钩子也是接口的一部分：confirm_callback 用于人在回路审批，dry_run 用于模拟，PyAutoGUI 故障安全用于紧急停止。

路线图

• UIA + SoM 定位策略链

• MCP 服务器（14 个工具）

• 本地 VLM 支持（Ollama）

• 自主视觉循环（run_task）

• 内省策略与元学习记忆

• wait_for_element / 自动验证原语

• 拖放

• VLM 原始坐标回退 + OpenCV 模板匹配（UIA 盲区应用）

• macOS（Accessibility API）和 Linux 支持

• PyPI 发布

欢迎贡献——请查看 issues 寻找适合新手的好任务。

开发

pytest tests -q                        # 61 unit tests, no desktop/VLM needed
python examples/demo_calculator.py     # end-to-end demo (real clicks!)
python examples/mcp_client_demo.py     # MCP handshake + tool list

许可证

MIT

screen-use = 桌面版 browser-use：让任何 AI Agent 获得看屏幕、操作桌面应用的能力。

• 不是传统 RPA：不录制 selector，通过无障碍树 + 视觉模型理解 UI，界面变了也不怕

• 跨一切桌面应用：Excel、SAP、ERP 客户端、老旧 Win32 程序

• 自然语言驱动：click_element("保存按钮") 一句话搞定

• VLM 可选：策略链第一级是纯 UIA 文本匹配（零模型、毫秒级），视觉模型只在盲区兜底，支持本地 Ollama 保护隐私

接入方式、工具列表、安全配置与上文英文版一致。