cs-note/claude-code-best/docs/features/computer-use-windows-enhancement.md

---
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]]