wonder/cs-note

Fork 0

Files

T

wonder e92c0327d9 vault backup: 2026-06-09 23:15:17

2026-06-09 23:15:17 +08:00

10 KiB

Raw Permalink Blame History

tags, create time

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. 目标

窗口绑定截图：当前 CopyFromScreen 只能全屏截图，无法对指定窗口截图（尤其是被遮挡/最小化窗口）
UI 结构感知：当前只能通过坐标点击，无法像 macOS Accessibility 那样理解 UI 元素树
性能：每次 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 分层

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 脚本核心：

# 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 导出函数：

// 获取窗口的 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 子进程）：

# 读：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. 执行优先级

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 数据）。

10 KiB Raw Permalink Blame History Unescape Escape