253 lines
10 KiB
Markdown
253 lines
10 KiB
Markdown
---
|
||
tags: [computer-use, windows, ui-automation, ocr, printwindow]
|
||
create time: 2026-06-09 22:30
|
||
---
|
||
|
||
# Computer Use Windows 增强实施计划
|
||
|
||
## 概述
|
||
|
||
在已有的 PowerShell 子进程方案基础上，利用 Windows 原生 API 增强 Computer Use 的 Windows 实现，解决窗口绑定截图、UI 结构感知和性能三个核心问题。增强后 Windows 方案在 UI Automation 和 OCR 方面将超过 macOS 原始实现。
|
||
|
||
> [!info]
|
||
> 更新时间：2026-04-03
|
||
> 依赖文档：`docs/features/windows-ai-desktop-control.md`、`docs/features/computer-use.md`
|
||
|
||
## 正文
|
||
|
||
### 1. 目标
|
||
|
||
1. **窗口绑定截图**：当前 `CopyFromScreen` 只能全屏截图，无法对指定窗口截图（尤其是被遮挡/最小化窗口）
|
||
2. **UI 结构感知**：当前只能通过坐标点击，无法像 macOS Accessibility 那样理解 UI 元素树
|
||
3. **性能**：每次 PowerShell 启动约 273ms，剪贴板/窗口枚举等高频操作需要更快的方式
|
||
|
||
### 2. 已验证的 Windows API 能力
|
||
|
||
以下 API 全部通过 PowerShell P/Invoke 实测通过：
|
||
|
||
| 能力 | API | 验证结果 |
|
||
|------|-----|---------|
|
||
| 窗口绑定截图 | `PrintWindow(hwnd, hdc, PW_RENDERFULLCONTENT)` | ✅ VS Code 342KB, Chrome 273KB |
|
||
| 枚举窗口+HWND | `EnumWindows` + `GetWindowText` + `GetWindowThreadProcessId` | ✅ 38 个窗口，含 HWND/PID/标题 |
|
||
| UI 元素树 | `System.Windows.Automation.AutomationElement` | ✅ 记事本 39 个元素 |
|
||
| UI 写值 | `ValuePattern.SetValue()` | ✅ 成功写入记事本文本 |
|
||
| UI 点击 | `InvokePattern.Invoke()` | ✅ 按钮可程序化点击 |
|
||
| 坐标元素识别 | `AutomationElement.FromPoint(x, y)` | ✅ 返回元素类型+名称 |
|
||
| OCR | `Windows.Media.Ocr.OcrEngine` | ✅ 英语+中文引擎可用 |
|
||
| 全局热键 | `RegisterHotKey` | ✅ API 可调 |
|
||
| 剪贴板直接操作 | `System.Windows.Forms.Clipboard` | ✅ 读/写/图片检测 |
|
||
| Shell 启动 | `ShellExecute` | ✅ 打开文件/URL/应用 |
|
||
|
||
### 3. 架构设计
|
||
|
||
#### 3.1 文件结构
|
||
|
||
在现有 `backends/win32.ts` 基础上新增 Windows 专属模块：
|
||
|
||
```
|
||
packages/@ant/computer-use-input/src/
|
||
├── backends/
|
||
│ ├── darwin.ts ← 不动
|
||
│ ├── win32.ts ← 增强：直接 Win32 API 替代部分 PowerShell
|
||
│ └── linux.ts ← 不动
|
||
|
||
packages/@ant/computer-use-swift/src/
|
||
├── backends/
|
||
│ ├── darwin.ts ← 不动
|
||
│ ├── win32.ts ← 增强：PrintWindow 窗口截图 + EnumWindows
|
||
│ └── linux.ts ← 不动
|
||
|
||
packages/@ant/computer-use-mcp/src/
|
||
│ └── tools.ts ← 增加 Windows 专属工具定义（UI Automation、OCR）
|
||
|
||
src/utils/computerUse/
|
||
│ └── win32/ ← 新增目录：Windows 专属能力
|
||
│ ├── uiAutomation.ts ← UI 元素树、点击、写值
|
||
│ ├── ocr.ts ← 截图 + OCR 文字识别
|
||
│ ├── windowCapture.ts ← PrintWindow 窗口绑定截图
|
||
│ └── windowEnum.ts ← EnumWindows 窗口枚举
|
||
```
|
||
|
||
#### 3.2 分层
|
||
|
||
```mermaid
|
||
graph TB
|
||
A["Computer Use MCP Tools"] --> B["src/utils/computerUse/"]
|
||
B --> C["packages/@ant/computer-use-{input,swift}"]
|
||
C --> D["Windows Native API"]
|
||
A -->|"screenshot / click / type / request_access"| B
|
||
A -->|"Windows 专属: ui_tree / ocr / window_cap"| B
|
||
B -->|"executor.ts → 按平台 dispatch"| C
|
||
B -->|"win32/ → Windows 专属能力模块"| D
|
||
C -->|"backends/win32.ts → PowerShell + Win32 API"| D
|
||
D -->|"PrintWindow / EnumWindows / UI Automation / SendInput / Clipboard / OCR"| A
|
||
```
|
||
|
||
### 4. 实施计划
|
||
|
||
#### Phase A：窗口绑定截图（解决核心问题）
|
||
|
||
**问题**：当前 `CopyFromScreen` 只能全屏截图，无法对指定窗口截图。
|
||
**方案**：用 `PrintWindow` + `FindWindow` 实现窗口级截图。
|
||
|
||
| 步骤 | 文件 | 改动 |
|
||
|------|------|------|
|
||
| A.1 | `src/utils/computerUse/win32/windowCapture.ts` | 新建：`captureWindow(title)` 用 PrintWindow 截取指定窗口 |
|
||
| A.2 | `src/utils/computerUse/win32/windowEnum.ts` | 新建：`listWindows()` 用 EnumWindows 返回 {hwnd, pid, title}[] |
|
||
| A.3 | `packages/@ant/computer-use-swift/src/backends/win32.ts` | `screenshot.captureExcluding` 增加按窗口截图能力 |
|
||
| A.4 | `packages/@ant/computer-use-swift/src/backends/win32.ts` | `apps.listRunning` 用 EnumWindows 替代 Get-Process（返回 HWND） |
|
||
|
||
**PowerShell 脚本核心**：
|
||
|
||
```powershell
|
||
# PrintWindow 截取指定窗口
|
||
Add-Type -AssemblyName System.Drawing
|
||
Add-Type -ReferencedAssemblies System.Drawing @'
|
||
using System; using System.Runtime.InteropServices; using System.Drawing; using System.Drawing.Imaging;
|
||
public class WinCap {
|
||
[DllImport("user32.dll", CharSet=CharSet.Unicode)]
|
||
public static extern IntPtr FindWindow(string c, string t);
|
||
[DllImport("user32.dll")]
|
||
public static extern bool GetWindowRect(IntPtr h, out RECT r);
|
||
[DllImport("user32.dll")]
|
||
public static extern bool PrintWindow(IntPtr h, IntPtr hdc, uint f);
|
||
[StructLayout(LayoutKind.Sequential)]
|
||
public struct RECT { public int L, T, R, B; }
|
||
// ... CaptureByTitle(string title) → base64
|
||
}
|
||
'@
|
||
```
|
||
|
||
**验证标准**：能按窗口标题截图、被遮挡的窗口也能截图、返回 base64 + width + height。
|
||
|
||
#### Phase B：UI Automation（Windows 专属新能力）
|
||
|
||
**问题**：macOS 有 Accessibility API 可以读取/操作 UI 元素，Windows 当前只能坐标点击。
|
||
**方案**：用 `System.Windows.Automation` 实现 UI 树读取和元素操作。
|
||
|
||
| 步骤 | 文件 | 改动 |
|
||
|------|------|------|
|
||
| B.1 | `src/utils/computerUse/win32/uiAutomation.ts` | 新建：核心 UIA 操作封装 |
|
||
| B.2 | `packages/@ant/computer-use-mcp/src/tools.ts` | 增加 Windows 专属工具定义 |
|
||
|
||
**uiAutomation.ts 导出函数**：
|
||
|
||
```typescript
|
||
// 获取窗口的 UI 元素树
|
||
getUITree(windowTitle: string, depth: number): UIElement[]
|
||
|
||
// 按名称/类型/AutomationId 查找元素
|
||
findElement(windowTitle: string, query: {name?, controlType?, automationId?}): UIElement | null
|
||
|
||
// 点击元素（InvokePattern）
|
||
clickElement(windowTitle: string, automationId: string): boolean
|
||
|
||
// 设置元素值（ValuePattern）
|
||
setValue(windowTitle: string, automationId: string, value: string): boolean
|
||
|
||
// 获取坐标处的元素
|
||
elementAtPoint(x: number, y: number): UIElement | null
|
||
```
|
||
|
||
**验证标准**：能读取记事本的 UI 树、能向文本框写入内容、能点击按钮、能识别坐标处的元素。
|
||
|
||
#### Phase C：OCR 屏幕文字识别
|
||
|
||
**问题**：截图后 AI 只能看到图片，无法直接读取文字。
|
||
**方案**：用 `Windows.Media.Ocr` 对截图进行文字识别。
|
||
|
||
| 步骤 | 文件 | 改动 |
|
||
|------|------|------|
|
||
| C.1 | `src/utils/computerUse/win32/ocr.ts` | 新建：截图 + OCR 识别 |
|
||
| C.2 | `packages/@ant/computer-use-mcp/src/tools.ts` | 增加 `screen_ocr` 工具定义 |
|
||
|
||
**已确认可用语言**：英语 (en-US) + 中文 (zh-Hans-CN)
|
||
|
||
#### Phase D：高频操作性能优化
|
||
|
||
**问题**：每次 PowerShell 启动 273ms，鼠标移动等高频操作太慢。
|
||
**方案**：用 .NET `System.Windows.Forms.Clipboard` 等直接 API 替代 PowerShell 子进程。
|
||
|
||
**剪贴板直接 API**（不需要 PowerShell 子进程）：
|
||
|
||
```powershell
|
||
# 读：50ms → <1ms
|
||
[System.Windows.Forms.Clipboard]::GetText()
|
||
|
||
# 写：50ms → <1ms
|
||
[System.Windows.Forms.Clipboard]::SetText($text)
|
||
```
|
||
|
||
#### Phase E：`request_access` Windows 适配
|
||
|
||
**问题**：`request_access` 依赖 macOS bundleId 识别应用，Windows 没有这个概念。
|
||
**方案**：在 Windows 上用 exe 路径 + 窗口标题替代 bundleId。
|
||
|
||
**Windows 应用标识映射**：
|
||
|
||
| macOS bundleId | Windows 等价 |
|
||
|----------------|-------------|
|
||
| com.apple.Safari | msedge.exe（或窗口标题匹配） |
|
||
| com.google.Chrome | chrome.exe |
|
||
| com.apple.Terminal | WindowsTerminal.exe / cmd.exe |
|
||
|
||
#### Phase F：全局热键（ESC 拦截）
|
||
|
||
**问题**：当前非 darwin 直接跳过 ESC 热键，用 Ctrl+C 替代。
|
||
**方案**：用 `RegisterHotKey` 或 `SetWindowsHookEx(WH_KEYBOARD_LL)` 实现。
|
||
|
||
> [!tip]
|
||
> 优先级低——当前 Ctrl+C fallback 可用，ESC 热键是体验优化。
|
||
|
||
### 5. 执行优先级
|
||
|
||
```mermaid
|
||
graph LR
|
||
A["Phase A: 窗口绑定截图 P0"] --> B["Phase B: UI Automation P0"]
|
||
B --> C["Phase C: OCR P1"]
|
||
C --> D["Phase D: 性能优化 P1"]
|
||
D --> E["Phase E: request_access P1"]
|
||
E --> F["Phase F: ESC 热键 P2"]
|
||
```
|
||
|
||
### 6. 每个 Phase 的改动量估算
|
||
|
||
| Phase | 新增文件 | 修改文件 | 新增代码行 | 风险 |
|
||
|-------|---------|---------|-----------|------|
|
||
| A 窗口截图 | 2 | 1 | ~200 | 低 |
|
||
| B UI Automation | 1 | 1 | ~300 | 中 |
|
||
| C OCR | 1 | 1 | ~150 | 低 |
|
||
| D 性能优化 | 0 | 2 | ~50 | 低 |
|
||
| E request_access | 0 | 3 | ~100 | 中 |
|
||
| F ESC 热键 | 0 | 1 | ~50 | 低 |
|
||
| **总计** | **4** | **9** | **~850** | — |
|
||
|
||
### 7. 不动的文件
|
||
|
||
- `backends/darwin.ts`（两个包都不动）
|
||
- `backends/linux.ts`（两个包都不动）
|
||
- `src/utils/computerUse/` 中 macOS 相关代码路径不动
|
||
- `packages/@ant/computer-use-mcp/src/` 中已复制的参考项目代码不动（只追加 Windows 工具）
|
||
|
||
### 8. 与 macOS/Linux 方案的对比
|
||
|
||
| 能力 | macOS | Windows (增强后) | Linux |
|
||
|------|-------|-----------------|-------|
|
||
| 截图方式 | SCContentFilter (per-app) | **PrintWindow (per-window)** | scrot (全屏/区域) |
|
||
| UI 结构 | Accessibility API | **UI Automation** | 无 |
|
||
| OCR | 无内置 | **Windows.Media.Ocr** | 无内置 |
|
||
| 键鼠 | CGEvent + enigo | SendInput + keybd_event | xdotool |
|
||
| 窗口管理 | NSWorkspace | **EnumWindows + Win32** | wmctrl |
|
||
| 剪贴板 | pbcopy/pbpaste | **Clipboard 直接 API** | xclip |
|
||
| ESC 热键 | CGEventTap | RegisterHotKey | 无 |
|
||
| 应用标识 | bundleId | exe 路径 + 窗口标题 | /proc + wmctrl |
|
||
|
||
> [!info]
|
||
> Windows 增强后将在 UI Automation 和 OCR 方面超过 macOS 方案——这两项 macOS 原始实现也没有（Anthropic 用的是截图 + Claude 视觉理解，没有结构化 UI 数据）。
|
||
|
||
## 关联笔记
|
||
|
||
- [[computer-use]]
|
||
- [[computer-use-architecture-v2]]
|
||
- [[computer-use-tools-reference]]
|