# macOS Ghost Control MCP (`computer-control-mcp`)

面向 macOS 的高性能、无感视觉闭环与 **自愈式 SOP（Standard Operating Procedure）** 桌面控制 MCP 服务端。支持 **Claude Desktop**、**Cursor**、**Google Antigravity**、**Windsurf** 等所有兼容 Model Context Protocol (MCP) 的 AI Agent 客户端。

---

## 核心特性

1. **1x 逻辑分辨率防遮挡截图与网格对齐（Zero Retina Offset）**
   - 底层基于 `screencapture -x -o -l <wid>` 与 `Quartz` 窗口帧缓冲，自动将 Retina 2x 物理像素归一化为 **1x 逻辑坐标空间**，并叠加 `100px` 辅助网格，彻底解决 macOS 多屏与高分屏点击偏移问题。
2. **Codex 风格常驻平滑虚拟光标 + 自动渐隐（Visual Collaborator Cursor）**
   - 执行过程中提供带状态胶囊徽章（`● AI` / `● CLICK` / `● TYPE` / `● SCROLL` / `● KEY`）的 `NSPanel` 点击穿透虚拟指针，以三阶缓动（Cubic Ease-Out）平滑滑行展示 AI 操作轨迹，**任务序列结束时自动 0.18s 渐隐消失**。
3. **零物理鼠标争抢（Zero Mouse Contention）**
   - 支持纯后台 `PID` 注入与极速 `teleport` 硬件注入双模式；**用户鼠标空闲守卫**：区分本驱动合成事件与用户真实事件，用户正在移动/按住鼠标时绝不 warp（等待或抛 `UserBusyError`）；点击后仅在用户未动鼠标时复位。
   - 虚拟光标采用**会话心跳**：任务期间常驻（长时间 OCR 等待也不闪隐），任务结束立即渐隐；MCP 进程崩溃 2.5s 内自动隐藏；守护进程带协议版本号，升级后自动替换。
4. **混合感知通用泛化（AX + OCR + 弹层）**
   - `perception.py`：`AXUIElement` 控件树（Electron 自动开启 `AXManualAccessibility`，可 `AXPress` 零鼠标点击）+ RapidOCR（小区域 Retina 物理像素识别）+ `kCGWindowLayer>0` 弹层窗口感知，统一为窗口相对坐标的 `UIElement`。
   - **通用定位打分**替代应用专属像素硬编码：分组锚点（`section`）、规避分组（网络搜索/聊天记录）、查询回显联想簇识别、排除输入框自身；**fail-safe**：最佳候选可疑时拒绝而非误选。
   - **`select_item` 列表选择**：`keyboard` 策略用方向键 + 高亮行帧差分定位，高亮落在目标行才回车（不动鼠标）；`click` / `ax` / `enter` 策略可选。
   - **`expect` 后置条件**：`text` / `absent_text` / `popup` / `window_size_unchanged`，每步证明"生效了"。
5. **闭环自愈 SOP 引擎（`sop_engine.py`）**
   - 快速路径 `expect` 失败 → `recover` 重放前置步骤 → `alternatives` → 其它选择策略 / `target` 语义重定位 / `heal_region` → 整个 SOP 跑通后**自动写回模板**（保留 `{{参数}}`、版本 +1、`changelog` + 每步 `heal_history`、旧版归档 `sops/.history/`、统计写 `sops/.state/`）。
   - 不可逆步骤（`"idempotent": false`，如"回车发送"）绝不自动重试；`vacuous` 检测防止"动作前条件已成立"造成的假阳性。

---

## 目录结构

```text
computer-control-mcp/
├── src/computer_control_mcp/
│   ├── core.py                 # MCP 工具注册入口
│   ├── macos_ghost_driver.py   # Quartz/AppKit 输入注入、截图、鼠标空闲守卫、虚拟光标守护进程
│   ├── perception.py           # AX + OCR + 弹层混合感知、通用定位打分、高亮行检测
│   ├── interaction.py          # 语义动作、expect 后置校验、自愈 run_step
│   ├── sop_engine.py           # SOP 渲染 / 执行 / 自动写回 / 归档 / 统计
│   ├── sop_cli.py              # computer-control-sop 命令行
│   ├── server.py               # MCP 标准 stdio 服务启动入口
│   └── cli.py                  # CLI 命令行入口
├── sops/                       # 可自愈、可热更新的声明式 SOP 剧本库
│   ├── wechat_send_message.json
│   ├── youtube_search_and_play.json
│   └── activity_monitor_top_processes.json
├── skills/macos-computer-use/  # 通用视觉泛化与 SOP 自愈 Agent Skill (适配 Antigravity / Claude)
│   └── SKILL.md
├── .cursor/rules/              # Cursor 专属自动加载规则
│   └── macos-computer-use.mdc
└── scripts/
    └── install_macos.sh        # macOS 一键环境构建与配置脚本
```

---

## 快速开始（macOS 一键安装）

```bash
git clone <your-repo-url> computer-control-mcp
cd computer-control-mcp
chmod +x scripts/install_macos.sh
./scripts/install_macos.sh
```

安装脚本会自动创建 `.venv`、安装全部依赖、挂载全局 Skill，并在终端输出可直接粘贴到 `~/.cursor/mcp.json` 或 `claude_desktop_config.json` 的配置片段。

### 系统权限要求
请在 `系统设置 -> 隐私与安全性` 中为运行客户端（如 Cursor、Terminal、Antigravity 或 Claude）开启：
- **辅助功能（Accessibility）**：用于发送 Quartz 键鼠事件。
- **屏幕录制（Screen & System Audio Recording）**：用于无遮挡窗口截图与本地 RapidOCR 识别。

---

## 核心 MCP 工具一览

| 工具名称 | 用途说明 |
| :--- | :--- |
| `macos_run_sop` | **闭环自愈执行 SOP**：每步 `expect` 校验，失效自动回退通用能力，跑通后自动写回修复 SOP；失败返回逐次尝试诊断与 `healing_hint`。支持 `dry_run`。 |
| `macos_inspect_ui` | 结构化感知（无需看图）：AX + OCR 元素、弹层窗口，用于构造语义 `target` / `expect`。 |
| `macos_ghost_execute` | **批量执行器**：原子动作 + 语义动作（`click_text`、`select_item`、`assert_text`…），每个动作可带 `expect` / `target` / `alternatives` / `recover` / `idempotent`。 |
| `macos_capture_window` | 按应用名/标题模糊匹配窗口，返回 1x 逻辑分辨率截图（含可选 `100px` 坐标网格）及窗口边界信息。 |
| `macos_capture_display` | 截取指定显示器（`display_index`）的 1x 逻辑分辨率全屏图像。 |
| `macos_list_sops` | 列出 `sops/` 注册表中所有可用的标准作业流程（SOP）及其版本号。 |
| `macos_get_sop` | 按 `sop_id` 获取指定 SOP 的完整声明式模板、前置条件、断言与已知界面陷阱。 |
| `macos_save_sop` | **SOP 自愈热更新**：当发现 SOP 过时并通过通用视觉推理跑通后，原位保存更新后的 SOP，自动递增版本号并追加 `changelog`。 |
| `macos_desensitize_image` | 对截图指定矩形区域执行像素化马赛克 + 高斯模糊隐私脱敏。 |

### SOP 命令行

```bash
computer-control-sop list
computer-control-sop run wechat_send_message -p target_contact=文件传输助手 -p message_text=你好
computer-control-sop run wechat_send_message --dry-run -p ...      # 只渲染不执行
computer-control-sop inspect 微信 --region 0 0 420 600            # 打印 AX/OCR 元素
```

### 测试

```bash
.venv/bin/python -m pytest tests/test_self_healing.py -q   # 离线：定位打分 / 高亮差分 / SOP 写回
```

---

## License

MIT License