# 真实之眼 Real Eye

给 AI 一双能看懂 Windows 界面的眼睛。

它把任意窗口读成**带坐标的文字**——控件的名字、角色、能不能点，加上画面上所有文字和它们的位置。于是：

- **看不见屏幕的模型也能操作电脑**：读出来的是文字，不是截图，纯文本模型（DeepSeek、Kimi、长上下文那些）同样能用
- **点击不用猜像素**：知道按钮叫什么、在哪，点哪儿是算出来的
- **被遮挡也能读**：抓的是窗口自己渲染的画面，窗口在后面、被别的窗口盖住都行

它是一个 **MCP 服务**，所以任何支持 MCP 的客户端都能用：Claude Code、Cursor、Cline、Windsurf……

**只读**：只看，不点、不打字、不抢焦点、不激活窗口。

---

## 装

需要 Windows 10/11 和 Python 3.9+。

```bash
git clone <这个仓库>
cd real-eye
pip install -r requirements.txt
```

默认用 Windows 自带 OCR，装完约 30MB。想要更准的中文识别，把 `requirements.txt` 里 `rapidocr_onnxruntime` 那行取消注释再装一次（多约 240MB）。

## 配

在 MCP 客户端里加一段（以 Claude Code 的 `~/.claude.json` 为例）：

```json
{
  "mcpServers": {
    "real-eye": {
      "command": "python",
      "args": ["C:\\路径\\到\\real-eye\\real_eye_server.py"]
    }
  }
}
```

Windows 上建议写 `python.exe` 的绝对路径。

重启客户端即可。模型就能调用下面这些工具了。

## 工具

| 工具 | 做什么 |
|---|---|
| `eye_windows` | 列出当前可见的窗口 |
| `eye_see` | 读一个窗口：控件清单（角色/名字/坐标/可点/启用状态）+ 画面上所有文字和坐标。不填目标就读当前前台窗口。`mark=true` 额外返回一张把每个元素编号画好的图，适合能看图的模型；同时给 `changed`，表示相比上次读取界面有没有变化 |
| `eye_find` | 按名字找东西在哪：优先查控件表（精确），没有再找 OCR 文字。返回屏幕坐标 |
| `eye_wait` | 等到某段文字出现（或超时）。用于等界面反应，比如等"发送"亮起来 |

`eye_see` / `eye_find` 有个 `accurate` 开关：默认快（Windows 自带 OCR，约 0.4 秒），设为 `true` 换 RapidOCR（约 4 秒，中文更准）。

## 快不快

本机实测（900×600 的窗口）：

| 操作 | 耗时 |
|---|---|
| 找控件（名字在控件表里） | 0.2 秒 |
| 读一次窗口（系统 OCR） | 0.4 秒 |
| 重复读同一画面（画面没变） | 0.1 秒 |
| 读一次窗口（`accurate=true`，RapidOCR） | 3–5 秒 |

## 已知限制

- **只读**。要点击/输入请配一个 Computer Use 类工具，用这里返回的坐标去点。
- 系统 OCR 会认错个别汉字（"询问"→"词问"）。要紧的文字加 `accurate=true`。
- 有些窗口既没有控件表、又不肯自己渲染（个别游戏、某些硬件加速界面），这时会明确报错，不会返回错的内容。
- 目标窗口最小化时拒绝读取。

## 许可

MIT，见 LICENSE。用到的第三方库各有自己的许可证（pywin32 PSF、mss MIT、Pillow MIT-CMU、numpy BSD、uiautomation Apache-2.0、winsdk MIT、rapidocr_onnxruntime Apache-2.0）。