<div align="center">

# computer-copilot

**让 AI 像人一样操作 Windows 桌面的 MCP 服务器**

看得见的操控 · 管得住的权限 · 默认不截图

许可证: MIT · 仅支持 Windows 10/11 · Python 3.10+

</div>

---

## 这是什么

一个给 LLM 用的 **MCP（Model Context Protocol）服务器**，把 Windows 桌面变成 AI 可以操作的对象：
找窗口、点按钮、敲键盘、读界面文字、启动软件、截屏 —— 全部通过标准 MCP 工具暴露给
Claude / DeepSeek / Cursor / ZCode / DSH 等任意 MCP 客户端。

它不是一个「截图 → 识图 → 猜坐标」的玩具。**默认路径不截图**：

| 层级 | 手段 | 何时使用 | 典型耗时 |
|---|---|---|---|
| 1 | **UIA 控件接口**（`uiautomation`） | 标准 Windows 控件（按钮、菜单、编辑框、列表、树） | 毫秒级 |
| 2 | **OCR 文字定位**（Windows 内置 OCR） | 自绘界面（Quartus、CAD、游戏、绘图软件）无控件语义 | 数百毫秒 |
| 3 | **截图** | 只有用户明确要看画面、或需要留证据时 | 秒级 |
| 4 | **编号点击（Set-of-Mark）** | 把可点元素标成 ①②③，模型只回答"点 N 号"，由真值决定落点 | 中 |

> **设计原则：AI 平时不截图。**
> 截图很贵 —— 传输慢、token 多、还会泄露屏幕上无关的内容。所以默认走控件接口 / OCR；
> 只有当「用户要看」「需要作证」时才截图。截图范围可限定为只截当前目标窗口。

## 亮点

- **看得见的操控**：操控时在目标窗口画高亮边框 + AI 光标 + 操作流水，顶部有横幅提示。
- **管得住**：可随时通过 `panel` 工具暂停 / 切「仅观察」/ 一键叫停；用户一旦自己动鼠标键盘，AI 立刻让路。
- **隐私可控**：截图范围可限定为**只截当前操控的目标窗口**，不碰屏幕其它内容。
- **不弹黑窗**：启动 GUI 程序用 detached 方式，自动隐藏附带控制台窗口（ModelSim 这类程序也管得住）。
- **Windows 原生 OCR**：走 WinRT OCR 引擎，中英文都准，**不依赖任何外部模型或 API**。
- **遮挡也能读**：`PrintWindow` 截图可以在窗口被别的窗口压住时拿到完整内容。
- **编号点击**：截图里把可点元素标号，模型说"点 3 号"即可，落点由 UIA/OCR 真值决定，不靠模型心算坐标。
- **单一 MCP 服务**：其余全是标准工具，客户端可以随意替换。

## 演示

![computer-copilot 操控计算器](docs/images/demo.gif)

*AI 通过 MCP 操控计算器完成 `25 × 4 = 100`：青色光环是 AI 光标，扩散波纹是点击反馈，全程通过 UIA 语义调用完成。*

## 安装

```powershell
git clone https://github.com/Jasmineee007/computer-copilot.git
cd computer-copilot
pip install -e .
```

依赖：`mcp pillow pyautogui pyperclip uiautomation python-docx`（`pip install -e .` 会自动装）。
OCR 用 Windows 自带 WinRT，免安装；需系统有「中文(简体)」或英文 OCR 语言包（Win10 20H1+ 默认已带）。

## 接入 MCP 客户端

**方式一：直接指向命令**（装好后 `computer-copilot` 在 PATH 上）

```json
{
  "mcpServers": {
    "computer-copilot": {
      "command": "computer-copilot",
      "args": [],
      "env": { "SCREENSHOT_DIR": "C:/Users/you/screenshots" }
    }
  }
}
```

**方式二：用自带的启动器**（免改环境变量，脚本自定位包目录）——把 `mcp_launch.cmd` 的绝对路径给客户端：

```json
{
  "mcpServers": {
    "computer-copilot": {
      "command": "C:/path/to/computer_copilot/mcp_launch.cmd",
      "args": []
    }
  }
}
```

`SCREENSHOT_DIR` 决定截图落到哪个目录（建议给一个专门目录，方便清理）。
`COPILOT_IDLE_SECS` 调「用户动键鼠后 AI 让路」的阈值秒数（0 关闭仲裁）。

## 工具一览（54 个）

**窗口 / 进程**

| 工具 | 说明 |
|---|---|
| `list_windows` | 列出所有可见顶层窗口（标题 / 句柄 / PID / 尺寸） |
| `activate_window` / `set_target_window` | 激活 / 钉住目标窗口 |
| `wait_window` / `wait_window_gone` / `wait_file` | 等窗口出现 / 消失 / 文件就绪 |
| `resize_window` | 移动、缩放、最大化、最小化、隐藏 |
| `launch_app` / `run_process` | 启动程序（GUI 程序不弹黑窗、不被超时强杀） |
| `list_processes` / `kill_process` | 进程管理 |
| `wait_for` | **条件等待**：等控件出现/消失、等文本出现（比死等稳） |

**操控**

| 工具 | 说明 |
|---|---|
| `click` / `move_mouse` / `get_mouse_position` / `drag` / `scroll` | 鼠标（物理像素坐标） |
| `type_text` / `press_keys` | 输入文本（非 ASCII 自动走剪贴板，IME 免疫）/ 按键 |
| `click_ui_element` / `type_into_element` | 按控件名点击 / 往控件写文本（UIA，自带验证） |
| **`uia_action`** | 对控件执行 invoke / select / check / expand / focus / setvalue（推荐） |
| `find_ui_elements` | 列出窗口里的控件（名字、类型、矩形） |
| `invoke_menu` | 直接触发 Win32 菜单命令 |

**视觉 / 读**

| 工具 | 说明 |
|---|---|
| **`read_text`** | OCR 读窗口/区域文字，返回带坐标的词/行（可按 `contains`/`regex` 过滤） |
| `click_text` | 找到文字并直接点它（OCR → 点击一步到位） |
| **`screenshot_marked`** | 截图并给可点元素编号（融合 UIA 蓝框 + OCR 橙框） |
| **`click_mark`** | 按编号点击，落点由 UIA/OCR 真值决定 |
| `screenshot_window` / `screenshot_region` / `screenshot_full` / `screenshot_ui_element` | 截图（可带坐标网格、叠加层） |
| `snapshot` | 一次返回：截图 + 窗口清单 + UI 元素摘要（看全局最快） |

**实用工具**

| 工具 | 说明 |
|---|---|
| `clipboard_get` / `clipboard_set` / `clipboard_clear` | 剪贴板读写清 |
| `scrape` | 抓网页正文（标准库实现） |
| `fs_read` / `fs_write` / `fs_list` / `fs_search` | 文件读写、列目录、全文检索 |
| `registry_get` / `registry_set` | 读写注册表（仅 HKCU/HKLM，拒绝受保护键） |
| `notify` | Windows 系统通知（toast） |

**文档 / 控制**

| 工具 | 说明 |
|---|---|
| `doc_create/read/append/insert_text/insert_image/delete_block` | Word 文档读写、插图 |
| `overlay` | 开关 AI 操控叠加层（边框 / 光标 / 横幅） |
| `panel` | 状态 / 暂停 / 仅观察 / 隐私截图范围 / 清空记录 |
| `trust` | 信任 / 撤销某个程序（免确认直接操控） |

## 状态与安全（无独立面板，全走工具）

- `panel(action='status')` 查状态 / `set_pause` 暂停恢复 / `set_mode(mode='observe')` 仅观察 /
  `set_scope` 截图范围 / `clear` 清空记录。
- **仅观察模式**：键鼠/窗口操控全部拒绝（返回 OBSERVE_ONLY），截图与读取仍可用。
- **物理急停**：把鼠标快速甩到**屏幕左上角**即触发 pyautogui failsafe，立即中止自动化；或直接结束 MCP 进程。
- **用户优先**：检测到真实键鼠输入即让出控制权（`COPILOT_IDLE_SECS` 可调）。

## 快速上手

在 MCP 客户端里配置好本服务后，直接用自然语言下指令即可：

- 「打开计算器，算一下 25 × 4」
- 「在记事本里写下这段话并保存到桌面」
- 「读出当前窗口里所有按钮的名字」

也可以直接在终端以 stdio 方式启动服务，交给任意 MCP 客户端连接：

```powershell
computer-copilot
```

各工具的设计取舍见 [docs/architecture.md](docs/architecture.md)。

## 风险提示（请认真读）

这个项目**真的会操作你正在用的桌面**：能点按钮、敲键盘、发快捷键。

- 请**优先在虚拟机 / 测试环境**里跑，不要对着存有重要数据的生产机授权。
- 涉及删除、付款、发送等不可逆操作，请让 AI 先复述计划再执行。
- 用户一旦自己动鼠标或键盘，AI 会主动让路；也可随时 `panel(set_pause)` 或甩鼠标到左上角急停。
- 截图默认只取目标窗口，但请自行确认目标窗口里没有敏感信息。

## 目录结构

```
src/computer_copilot/     真正的实现
  server.py               MCP 工具定义（对外接口，54 个工具）
  element.py / element_marks.py  UIA 控件操作 / 元素编号点击
  vision.py / ocr.ps1     OCR 读文字（以文找位）
  capture.py              截图（窗口 / 区域 / 整屏 / 坐标网格）
  control.py              键鼠输入
  overlay.py              AI 操控叠加层（边框 / 光标 / 横幅）
  status_hub.py           进程内状态中枢（暂停 / 仅观察 / 截图范围门控）
  input_guard.py          用户优先：人一动，AI 让路
  extras.py               条件等待 / 剪贴板 / 网页 / 文件 / 注册表 / 通知
  sysops.py / docs.py     进程与命令 / Word 文档
tests/                    单元测试（坐标换算等纯函数）
docs/                     架构、隐私模型
```

## 致谢

- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [uiautomation](https://github.com/yinkaisheng/Python-UIAutomation-for-Windows)
- [Windows-MCP](https://github.com/CursorTouch/Windows-MCP) —— 叠加层渲染方案（UpdateLayeredWindow + 预乘 BGRA）、屏幕四边呼吸光晕、物理输入仲裁等思路借鉴自该项目
- Windows 内置 OCR（WinRT `Windows.Media.Ocr`）

## 许可证

MIT，见 [LICENSE](LICENSE)。