feat: Computer Use — Windows 跨平台支持 + GUI 无障碍增强 + Python Bridge

三平台 Computer Use (macOS + Windows + Linux)，Windows 专项增强。 - MCP server: toolCalls/tools/executor/mcpServer 等 12 文件完整实现 - 平台抽象层: platforms/{win32,darwin,linux}.ts - 跨平台 executor: executorCrossPlatform.ts - CHICAGO_MCP + VOICE_MODE feature flags 启用 - windowMessage.ts: SendMessageW (WM_CHAR Unicode + 剪贴板粘贴) - windowBorder.ts: 4 叠加窗口边框 (30fps 跟踪) - uiAutomation.ts: UI Automation 元素树/点击/写值 - accessibilitySnapshot.ts: 无障碍快照 → 模型感知 GUI - bridge.py + bridgeClient.ts: Python 长驻进程 (替代 per-call PS) - window_management: min/max/restore/close/focus (Win32 API) - click_element / type_into_element: 按名称操作 (无需坐标) - 截图自动附带 Accessibility Snapshot - 17 种方法, stdin/stdout JSON 通信 - 窗口枚举 1.5ms vs PS 500ms, 截图 360ms vs PS 800ms - 依赖: mss + Pillow + pywinauto
2026-06-15 12:55:51 +00:00 · 2026-04-05 15:27:50 +08:00
parent 7a2ade0a02
commit c17edcb12e
36 changed files with 8297 additions and 351 deletions
--- a/docs/features/computer-use.md
+++ b/docs/features/computer-use.md
@@ -1,136 +1,197 @@
-# Computer Use 用户指南
+# Computer Use — macOS / Windows / Linux 跨平台实施计划

-Computer Use 让 Claude 直接操控你的电脑——移动鼠标、点击、输入文字、截图，就像一个远程助手坐在你面前操作一样。
+更新时间：2026-04-03
+参考项目：`E:\源码\claude-code-source-main\claude-code-source-main`

-## 支持平台
+## 1. 现状

-| 平台 | 状态 | 额外配置 |
-|------|------|---------|
-| macOS | 可用 | 需授予辅助功能 + 屏幕录制权限 |
-| Windows | 可用 | 无需额外配置 |
-| Linux | 不可用 | 后端待开发 |
+参考项目的 Computer Use **仅支持 macOS**——从入口到底层全部写死 darwin。我们的项目在 Phase 1-3 中已经完成了：

-## 快速开始
+- ✅ `@ant/computer-use-mcp` stub 替换为完整实现（12 文件）
+- ✅ `@ant/computer-use-input` 拆为 dispatcher + backends（darwin + win32）
+- ✅ `@ant/computer-use-swift` 拆为 dispatcher + backends（darwin + win32）
+- ✅ `CHICAGO_MCP` 编译开关已开
+- ❌ `src/` 层有 6 处 macOS 硬编码阻塞

-1. 启动 Claude Code：
+## 2. 阻塞点全景

-   ```bash
-   bun run dev
-   ```
+### 2.1 入口层

-   Computer Use 默认已开启，无需额外参数。
+| # | 文件:行号 | 阻塞代码 | 影响 |
+|---|----------|---------|------|
+| 1 | `src/main.tsx:1605` | `getPlatform() === 'macos'` | 整个 CU 初始化被跳过 |

-2. 在对话中告诉 Claude 你想做什么，例如：
-   - "帮我打开系统设置"
-   - "截个屏看看当前桌面"
-   - "在 Finder 里点击那个文件"
+### 2.2 加载层

-3. 首次操控某个应用时，会弹出权限对话框让你确认。
+| # | 文件:行号 | 阻塞代码 | 影响 |
+|---|----------|---------|------|
+| 2 | `src/utils/computerUse/swiftLoader.ts:16` | `process.platform !== 'darwin'` → throw | 截图、应用管理全部不可用 |
+| 3 | `src/utils/computerUse/executor.ts:263` | `process.platform !== 'darwin'` → throw | 整个 executor 工厂函数不可用 |

-4. 操作过程中随时按 **Esc**（macOS）或 **Ctrl+C**（Windows）中止。
+### 2.3 macOS 特有依赖

-## 权限说明
+| # | 文件:行号 | 依赖 | macOS 实现 | 需要替代方案 |
+|---|----------|------|-----------|------------|
+| 4 | `executor.ts:70-88` | 剪贴板 | `pbcopy`/`pbpaste` | Win: PowerShell `Get/Set-Clipboard`；Linux: `xclip`/`wl-copy` |
+| 5 | `drainRunLoop.ts:21` | CFRunLoop pump | `cu._drainMainRunLoop()` | 非 darwin：直接执行 fn()，不需要 pump |
+| 6 | `escHotkey.ts:28` | ESC 热键 | CGEventTap | 非 darwin：返回 false（已有 Ctrl+C fallback） |
+| 7 | `hostAdapter.ts:48-54` | 系统权限 | TCC accessibility + screenRecording | Win：直接 granted；Linux：检查 xdotool |
+| 8 | `common.ts:56` | 平台标识 | `platform: 'darwin'` 硬编码 | 动态获取 |
+| 9 | `executor.ts:180` | 粘贴快捷键 | `command+v` | Win/Linux：`ctrl+v` |

-Computer Use 采用分级权限模型，保护你的安全：
+### 2.4 缺失的 Linux 后端

-| 级别 | 能力 | 适用场景 |
-|------|------|---------|
-| **full** | 所有操作：鼠标点击（左/右/中键）、拖拽、键盘输入、组合键 | 系统设置、Finder 等系统应用 |
-| **click** | 仅左键点击和滚轮滚动 | IDE（VS Code、Cursor）、终端 |
-| 未授权 | 所有操作被拒绝 | 需要通过 `request_access` 申请 |
+| 包 | macOS | Windows | Linux |
+|---|-------|---------|-------|
+| `computer-use-input/backends/` | ✅ darwin.ts | ✅ win32.ts | ❌ 需新建 linux.ts |
+| `computer-use-swift/backends/` | ✅ darwin.ts | ✅ win32.ts | ❌ 需新建 linux.ts |

-IDE 类应用默认只有 click 权限，这是安全设计——防止 AI 在你的终端或编辑器中执行危险操作。如需完整控制，可以在权限对话框中手动提升。
+## 3. 每个平台的能力依赖

-## 可用操作
+### 3.1 computer-use-input（键鼠）

-### 鼠标
+| 功能 | macOS | Windows | Linux |
+|------|-------|---------|-------|
+| 鼠标移动 | CGEvent JXA | SetCursorPos P/Invoke | xdotool mousemove |
+| 鼠标点击 | CGEvent JXA | SendInput P/Invoke | xdotool click |
+| 鼠标滚轮 | CGEvent JXA | SendInput MOUSEEVENTF_WHEEL | xdotool scroll |
+| 键盘按键 | System Events osascript | keybd_event P/Invoke | xdotool key |
+| 组合键 | System Events osascript | keybd_event 组合 | xdotool key combo |
+| 文本输入 | System Events keystroke | SendKeys.SendWait | xdotool type |
+| 前台应用 | System Events osascript | GetForegroundWindow P/Invoke | xdotool getactivewindow + /proc |
+| 工具依赖 | osascript（内置） | powershell（内置） | xdotool（需安装） |

-| 操作 | 说明 |
-|------|------|
-| 移动鼠标 | 移动到指定坐标 |
-| 左键点击 | 单击、双击、三击 |
-| 右键点击 | 需要 full 权限 |
-| 中键点击 | 需要 full 权限 |
-| 拖拽 | 从 A 点拖到 B 点，需要 full 权限 |
-| 滚轮 | 向上或向下滚动 |
+### 3.2 computer-use-swift（截图 + 应用管理）

-### 键盘
+| 功能 | macOS | Windows | Linux |
+|------|-------|---------|-------|
+| 全屏截图 | screencapture | CopyFromScreen | gnome-screenshot / scrot / grim |
+| 区域截图 | screencapture -R | CopyFromScreen(rect) | gnome-screenshot -a / scrot -a / grim -g |
+| 显示器列表 | CGGetActiveDisplayList JXA | Screen.AllScreens | xrandr --query |
+| 运行中应用 | System Events JXA | Get-Process | wmctrl -l / ps |
+| 打开应用 | osascript activate | Start-Process | xdg-open / gtk-launch |
+| 隐藏/显示 | System Events visibility | ShowWindow/SetForegroundWindow | wmctrl -c / xdotool |
+| 工具依赖 | screencapture + osascript | powershell | xdotool + scrot/grim + wmctrl |

-| 操作 | 说明 |
-|------|------|
-| 按键 | 单个按键或组合键（如 Ctrl+C） |
-| 输入文字 | 逐字符输入文本，需要 full 权限 |
-| 长按 | 按住某个键一段时间，需要 full 权限 |
+### 3.3 executor 层

-### 屏幕
+| 功能 | macOS | Windows | Linux |
+|------|-------|---------|-------|
+| drainRunLoop | CFRunLoop pump | 不需要 | 不需要 |
+| ESC 热键 | CGEventTap | 跳过（Ctrl+C fallback） | 跳过（Ctrl+C fallback） |
+| 剪贴板读 | pbpaste | `powershell Get-Clipboard` | xclip -o / wl-paste |
+| 剪贴板写 | pbcopy | `powershell Set-Clipboard` | xclip / wl-copy |
+| 粘贴快捷键 | command+v | ctrl+v | ctrl+v |
+| 终端检测 | __CFBundleIdentifier | WT_SESSION / TERM_PROGRAM | TERM_PROGRAM |
+| 系统权限 | TCC check | 直接 granted | 检查 xdotool 安装 |

-| 操作 | 说明 |
-|------|------|
-| 截图 | 截取当前屏幕 |
-| 切换显示器 | 多显示器环境下切换目标屏幕 |
-| 缩放 | 放大屏幕某个区域 |
+## 4. 执行步骤

-### 其他
+### Phase 1：已完成 ✅

-| 操作 | 说明 |
-|------|------|
-| 获取鼠标位置 | 查询当前鼠标坐标 |
-| 批量操作 | 一次执行多个操作，减少等待 |
-| 等待 | 暂停指定秒数（最长 100 秒） |
+- [x] `@ant/computer-use-mcp` stub → 完整实现
+- [x] `@ant/computer-use-input` dispatcher + darwin/win32 backends
+- [x] `@ant/computer-use-swift` dispatcher + darwin/win32 backends
+- [x] `CHICAGO_MCP` 编译开关

-## macOS 权限配置
+### Phase 2：移除 6 处 macOS 硬编码（解锁 macOS + Windows）

-首次使用前，需要授予两项系统权限。缺少任一项都会导致功能异常（见下方说明）。
+**改动原则：macOS 代码路径不变，只在每处 darwin 守卫后加 win32/linux 分支。**

-### 辅助功能（Accessibility）
+| 步骤 | 文件 | 改动 |
+|------|------|------|
+| 2.1 | `src/main.tsx:1605` | `getPlatform() === 'macos'` → 去掉平台限制，或改为 `!== 'unknown'` |
+| 2.2 | `src/utils/computerUse/swiftLoader.ts:16-18` | 移除 `process.platform !== 'darwin'` throw。`@ant/computer-use-swift/index.ts` 已有跨平台 dispatch |
+| 2.3 | `src/utils/computerUse/executor.ts:263-267` | 移除 `process.platform !== 'darwin'` throw。改为检查 input/swift isSupported |
+| 2.4 | `src/utils/computerUse/executor.ts:70-88` | 剪贴板函数按平台分发：darwin→pbcopy/pbpaste，win32→PowerShell Get/Set-Clipboard，linux→xclip |
+| 2.5 | `src/utils/computerUse/executor.ts:180` | `typeViaClipboard` 中 `command+v` → 非 darwin 时用 `ctrl+v` |
+| 2.6 | `src/utils/computerUse/executor.ts:273` | `const cu = requireComputerUseSwift()` → 改为 `new ComputerUseAPI()`（从 package 直接实例化，不走 swiftLoader throw） |
+| 2.7 | `src/utils/computerUse/drainRunLoop.ts` | 开头加 `if (process.platform !== 'darwin') return fn()` |
+| 2.8 | `src/utils/computerUse/escHotkey.ts` | `registerEscHotkey` 非 darwin 返回 false（已有 Ctrl+C fallback） |
+| 2.9 | `src/utils/computerUse/hostAdapter.ts:48-54` | `ensureOsPermissions` 非 darwin 返回 `{ granted: true }` |
+| 2.10 | `src/utils/computerUse/common.ts:56` | `platform: 'darwin'` → `platform: process.platform === 'win32' ? 'windows' : process.platform === 'linux' ? 'linux' : 'darwin'` |
+| 2.11 | `src/utils/computerUse/common.ts:55` | `screenshotFiltering: 'native'` → 非 darwin 时 `'none'`（Windows/Linux 截图不支持 per-app 过滤） |
+| 2.12 | `src/utils/computerUse/gates.ts:13` | `enabled: false` → `enabled: true`（无 GrowthBook 时默认可用） |
+| 2.13 | `src/utils/computerUse/gates.ts:39-43` | `hasRequiredSubscription()` → 直接返回 `true` |

-允许 Claude 控制鼠标和键盘。
+### Phase 3：新增 Linux 后端

-1. 打开 **系统设置 → 隐私与安全性 → 辅助功能**
-2. 点击左下角锁图标解锁（需要管理员密码）
-3. 将运行 Claude Code 的应用添加到允许列表：
-   - Terminal → `Terminal.app`
-   - iTerm → `iTerm.app`
-   - Cursor → `Cursor.app`
-   - VS Code 终端 → `Electron` 或 `Visual Studio Code.app`
-4. 确保应用旁边的开关已打开
+| 步骤 | 文件 | 内容 |
+|------|------|------|
+| 3.1 | `packages/@ant/computer-use-input/src/backends/linux.ts` | xdotool 键鼠（mousemove/click/key/type/getactivewindow） |
+| 3.2 | `packages/@ant/computer-use-swift/src/backends/linux.ts` | scrot/grim 截图 + xrandr 显示器 + wmctrl 窗口管理 |
+| 3.3 | `packages/@ant/computer-use-input/src/index.ts` | dispatcher 加 `case 'linux'` |
+| 3.4 | `packages/@ant/computer-use-swift/src/index.ts` | dispatcher 加 `case 'linux'` |

-**未授予时的现象**：鼠标移动、点击、键盘输入均无反应，工具执行成功但屏幕没有任何变化。
+### Phase 4：验证

-### 屏幕录制（Screen Recording）
+| 测试项 | macOS | Windows | Linux |
+|--------|-------|---------|-------|
+| build 成功 | ✅ | 验证 | 验证 |
+| MCP 工具列表非空 | 验证 | 验证 | 验证 |
+| 鼠标移动 | 验证 | ✅ 已通过 | 验证 |
+| 截图 | 验证 | ✅ 已通过 | 验证 |
+| 键盘输入 | 验证 | 验证 | 验证 |
+| 前台窗口 | 验证 | ✅ 已通过 | 验证 |
+| 剪贴板 | 验证 | 验证 | 验证 |

-允许 Claude 截取屏幕内容。
+## 5. 文件改动总览

-1. 打开 **系统设置 → 隐私与安全性 → 屏幕录制**
-2. 将同一个应用添加到允许列表并开启开关
-3. **需要重启该应用**才能生效（系统会提示 "xxx 需要重新打开"）
+### 不动的文件（14 个）

-**未授予时的现象**：截图工具执行成功但返回空白图片，Claude 无法看到你的屏幕，所有点击操作变成"盲点"。
+`cleanup.ts`、`computerUseLock.ts`、`wrapper.tsx`、`toolRendering.tsx`、`mcpServer.ts`、`setup.ts`、`appNames.ts`、`inputLoader.ts`、`src/services/mcp/client.ts`、`@ant/computer-use-mcp/src/*`（Phase 1 已完成）、`backends/darwin.ts`（两个包都不动）

-### 验证权限
+### 改 src/ 的文件（8 个）

-授予两项权限后，重启 Claude Code，在对话中让 Claude 截一张图即可验证是否配置成功。如果截图内容正常显示，说明权限配置完成。
+| 文件 | 改动量 | 风险 |
+|------|--------|------|
+| `main.tsx` | 1 行 | 低 |
+| `swiftLoader.ts` | 2 行 | 低 |
+| `executor.ts` | ~40 行（剪贴板分发 + 平台守卫 + paste 快捷键） | **中** |
+| `drainRunLoop.ts` | 1 行 | 低 |
+| `escHotkey.ts` | 3 行 | 低 |
+| `hostAdapter.ts` | 5 行 | 低 |
+| `common.ts` | 3 行 | 低 |
+| `gates.ts` | 3 行 | 低 |

-## Linux 依赖（暂不可用）
+### 新增文件（2 个）

-Linux 后端尚未开发。完成后需要安装以下工具：
+| 文件 | 行数估算 |
+|------|---------|
+| `packages/@ant/computer-use-input/src/backends/linux.ts` | ~150 行 |
+| `packages/@ant/computer-use-swift/src/backends/linux.ts` | ~200 行 |

-```bash
-sudo apt install xdotool scrot xclip wmctrl
+## 6. Linux 依赖工具
+
+| 工具 | 用途 | 安装命令（Ubuntu） |
+|------|------|-------------------|
+| `xdotool` | 键鼠模拟 + 窗口管理 | `sudo apt install xdotool` |
+| `scrot` 或 `gnome-screenshot` | 截图 | `sudo apt install scrot` |
+| `xrandr` | 显示器信息 | 通常已预装 |
+| `xclip` | 剪贴板 | `sudo apt install xclip` |
+| `wmctrl` | 窗口列表/切换 | `sudo apt install wmctrl` |
+
+Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替代 scrot）、`wl-clipboard`（替代 xclip）。初期可先只支持 X11，Wayland 标记为 todo。
+
+## 7. 执行顺序建议
+
+```
+Phase 2（解锁 macOS + Windows）
+  ├── 2.1-2.3  移除 3 处硬编码 throw/skip
+  ├── 2.4-2.5  剪贴板 + 粘贴快捷键平台分发
+  ├── 2.6      swiftLoader → 直接实例化
+  ├── 2.7-2.9  drainRunLoop / escHotkey / permissions 平台分支
+  ├── 2.10-2.11 common.ts 平台标识动态化
+  ├── 2.12-2.13 gates.ts 默认值
+  └── 验证 Windows
+
+Phase 3（Linux 后端）
+  ├── 3.1  input/backends/linux.ts
+  ├── 3.2  swift/backends/linux.ts
+  ├── 3.3-3.4  dispatcher 加 linux case
+  └── 验证 Linux
+
+Phase 4（集成验证 + PR）
 ```

-仅支持 X11，Wayland 不支持。
-
-## 常见问题
-
-### 截图成功但看不到图片
-
-检查 **系统设置 → 隐私与安全性 → 屏幕录制** 是否已授权。未授权时截图工具会执行成功但返回空白内容。
-
-### IDE 中无法输入文字或右键
-
-这是正常行为。IDE 类应用只有 click 权限，无法执行键盘输入、右键、拖拽等操作。如需完整控制，请在系统应用（如 Finder）中操作。
-
-### 操作中途想停止
-
-按 **Esc**（macOS）或 **Ctrl+C** 即可立即中止。
+每个 Phase 可独立验证、独立提交。Phase 2 完成后 macOS + Windows 可用，Phase 3 完成后三平台全部可用。