wonder/cs-note
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
wonder
2026-06-09 23:15:17 +08:00
parent 31fd89aafe
commit e92c0327d9
111 changed files with 7276 additions and 8846 deletions
Download Patch File Download Diff File Expand all files Collapse all files
claude-code-best/docs/features/computer-use-windows-enhancement.md
+67 -130
View File
@@ -1,17 +1,27 @@
---
tags: [computer-use, windows, ui-automation, ocr, printwindow]
create time: 2026-06-09 22:30
---
# Computer Use Windows 增强实施计划
更新时间：2026-04-03
依赖文档：`docs/features/windows-ai-desktop-control.md`、`docs/features/computer-use.md`
## 概述
## 1. 目标
在已有的 PowerShell 子进程方案基础上，利用 Windows 原生 API 增强 Computer Use 的 Windows 实现，解决窗口绑定截图、UI 结构感知和性能三个核心问题。增强后 Windows 方案在 UI Automation 和 OCR 方面将超过 macOS 原始实现。
在已有的 PowerShell 子进程方案基础上，利用 Windows 原生 API 增强 Computer Use 的 Windows 实现，解决 3 个核心问题：
> [!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 能力
### 2. 已验证的 Windows API 能力
以下 API 全部通过 PowerShell P/Invoke 实测通过：
@@ -28,9 +38,9 @@
| 剪贴板直接操作 | `System.Windows.Forms.Clipboard` | ✅ 读/写/图片检测 |
| Shell 启动 | `ShellExecute` | ✅ 打开文件/URL/应用 |
## 3. 架构设计
### 3. 架构设计
### 3.1 文件结构
#### 3.1 文件结构
在现有 `backends/win32.ts` 基础上新增 Windows 专属模块：
@@ -58,30 +68,24 @@ src/utils/computerUse/
│ └── windowEnum.ts ← EnumWindows 窗口枚举
```
### 3.2 分层
#### 3.2 分层
```
┌──────────────────────────────────────────────┐
│ Computer Use MCP Tools │
│ screenshot / click / type / request_access │
│ + Windows 专属: ui_tree / ocr / window_cap │
├──────────────────────────────────────────────┤
│ src/utils/computerUse/ │
│ executor.ts → 按平台 dispatch │
│ win32/ → Windows 专属能力模块 │
├──────────────────────────────────────────────┤
│ packages/@ant/computer-use-{input,swift} │
│ backends/win32.ts → PowerShell + Win32 API │
├──────────────────────────────────────────────┤
│ Windows Native API │
│ PrintWindow / EnumWindows / UI Automation │
│ SendInput / Clipboard / OCR / ShellExecute │
└──────────────────────────────────────────────┘
```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. 实施计划
### 4. 实施计划
### Phase A：窗口绑定截图（解决核心问题）
#### Phase A：窗口绑定截图（解决核心问题）
**问题**：当前 `CopyFromScreen` 只能全屏截图，无法对指定窗口截图。
**方案**：用 `PrintWindow` + `FindWindow` 实现窗口级截图。
@@ -114,12 +118,9 @@ public class WinCap {
'@
```
**验证标准**：
- 能按窗口标题截图
- 被遮挡的窗口也能截图
- 返回 base64 + width + height
**验证标准**：能按窗口标题截图、被遮挡的窗口也能截图、返回 base64 + width + height。
### Phase B：UI Automation（Windows 专属新能力）
#### Phase B：UI Automation（Windows 专属新能力）
**问题**：macOS 有 Accessibility API 可以读取/操作 UI 元素，Windows 当前只能坐标点击。
**方案**：用 `System.Windows.Automation` 实现 UI 树读取和元素操作。
@@ -148,44 +149,9 @@ setValue(windowTitle: string, automationId: string, value: string): boolean
elementAtPoint(x: number, y: number): UIElement | null
```
**UIElement 类型**：
```typescript
interface UIElement {
name: string
controlType: string // Button, Edit, Text, List, etc.
automationId: string
boundingRect: { x: number, y: number, w: number, h: number }
isEnabled: boolean
value?: string // ValuePattern 可用时
children?: UIElement[]
}
```
**验证标准**：能读取记事本的 UI 树、能向文本框写入内容、能点击按钮、能识别坐标处的元素。
**PowerShell 脚本核心**：
```powershell
Add-Type -AssemblyName UIAutomationClient
Add-Type -AssemblyName UIAutomationTypes
# 读取 UI 树
$root = [AutomationElement]::RootElement
$window = $root.FindFirst([TreeScope]::Children,
[PropertyCondition]::new([AutomationElement]::NameProperty, $title))
$elements = $window.FindAll([TreeScope]::Descendants, [Condition]::TrueCondition)
# 写入文本
$element.GetCurrentPattern([ValuePattern]::Pattern).SetValue($text)
# 点击按钮
$element.GetCurrentPattern([InvokePattern]::Pattern).Invoke()
```
**验证标准**：
- 能读取记事本的 UI 树（按钮、文本框、菜单）
- 能向文本框写入内容
- 能点击按钮
- 能识别坐标处的元素
### Phase C：OCR 屏幕文字识别
#### Phase C：OCR 屏幕文字识别
**问题**：截图后 AI 只能看到图片，无法直接读取文字。
**方案**：用 `Windows.Media.Ocr` 对截图进行文字识别。
@@ -195,92 +161,56 @@ $element.GetCurrentPattern([InvokePattern]::Pattern).Invoke()
| C.1 | `src/utils/computerUse/win32/ocr.ts` | 新建：截图 + OCR 识别 |
| C.2 | `packages/@ant/computer-use-mcp/src/tools.ts` | 增加 `screen_ocr` 工具定义 |
**ocr.ts 导出函数**：
```typescript
// 对屏幕区域 OCR
ocrRegion(x: number, y: number, w: number, h: number, lang?: string): OcrResult
// 对指定窗口 OCR
ocrWindow(windowTitle: string, lang?: string): OcrResult
interface OcrResult {
text: string
lines: { text: string, bounds: {x,y,w,h} }[]
language: string
}
```
**已确认可用语言**：英语 (en-US) + 中文 (zh-Hans-CN)
**验证标准**：
- 能识别屏幕区域中的英文和中文
- 返回文字内容 + 每行的位置信息
### Phase D：高频操作性能优化
#### Phase D：高频操作性能优化
**问题**：每次 PowerShell 启动 273ms，鼠标移动等高频操作太慢。
**方案**：用 .NET `System.Windows.Forms.Clipboard` 等直接 API 替代 PowerShell 子进程。
| 步骤 | 文件 | 改动 |
|------|------|------|
| D.1 | `src/utils/computerUse/executor.ts` | 剪贴板操作用直接 API 替代 PowerShell |
| D.2 | 考虑驻留 PowerShell 进程 | 通过 stdin/stdout 交互，摊平启动成本 |
**剪贴板直接 API**（不需要 PowerShell 子进程）：
```powershell
# 读：50ms → <1ms
[System.Windows.Forms.Clipboard]::GetText()
# 写：50ms → <1ms
# 写：50ms → <1ms
[System.Windows.Forms.Clipboard]::SetText($text)
# 图片检测
[System.Windows.Forms.Clipboard]::ContainsImage()
```
### Phase E：`request_access` Windows 适配
#### Phase E：`request_access` Windows 适配
**问题**：`request_access` 依赖 macOS bundleId 识别应用，Windows 没有这个概念。
**方案**：在 Windows 上用 exe 路径 + 窗口标题替代 bundleId。
| 步骤 | 文件 | 改动 |
|------|------|------|
| E.1 | `packages/@ant/computer-use-mcp/src/toolCalls.ts` | `resolveRequestedApps` 在 Windows 上用 exe 路径匹配 |
| E.2 | `packages/@ant/computer-use-mcp/src/sentinelApps.ts` | 增加 Windows 危险应用列表（cmd.exe, powershell.exe 等） |
| E.3 | `packages/@ant/computer-use-mcp/src/deniedApps.ts` | 增加 Windows 浏览器/终端识别规则 |
| E.4 | `src/utils/computerUse/hostAdapter.ts` | `ensureOsPermissions` Windows 上检查 UAC 状态 |
**Windows 应用标识映射**：
```
macOS bundleId → Windows 等价
com.apple.Safari → C:\Program Files\...\msedge.exe（或窗口标题匹配）
com.google.Chrome → chrome.exe
com.apple.Terminal → WindowsTerminal.exe / cmd.exe
```
### Phase F：全局热键（ESC 拦截）
| 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)` 实现。
| 步骤 | 文件 | 改动 |
|------|------|------|
| F.1 | `src/utils/computerUse/escHotkey.ts` | Windows 分支：RegisterHotKey 注册 ESC |
> [!tip]
> 优先级低——当前 Ctrl+C fallback 可用，ESC 热键是体验优化。
**优先级低**——当前 Ctrl+C fallback 可用，ESC 热键是体验优化。
### 5. 执行优先级
## 5. 执行优先级
```
Phase A: 窗口绑定截图 ← P0 核心需求，解决"操作其他界面"
Phase B: UI Automation ← P0 核心能力，AI 理解 UI 结构
Phase C: OCR ← P1 增值能力，AI 读屏幕文字
Phase D: 性能优化 ← P1 体验优化，高频操作提速
Phase E: request_access 适配 ← P1 功能完整性，权限模型适配
Phase F: ESC 热键 ← P2 体验优化，可后做
```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 的改动量估算
### 6. 每个 Phase 的改动量估算
| Phase | 新增文件 | 修改文件 | 新增代码行 | 风险 |
|-------|---------|---------|-----------|------|
@@ -292,14 +222,14 @@ Phase F: ESC 热键 ← P2 体验优化，可后做
| F ESC 热键 | 0 | 1 | ~50 | 低 |
| **总计** | **4** | **9** | **~850** | — |
## 7. 不动的文件
### 7. 不动的文件
- `backends/darwin.ts`（两个包都不动）
- `backends/linux.ts`（两个包都不动）
- `src/utils/computerUse/` 中 macOS 相关代码路径不动
- `packages/@ant/computer-use-mcp/src/` 中已复制的参考项目代码不动（只追加 Windows 工具）
## 8. 与 macOS/Linux 方案的对比
### 8. 与 macOS/Linux 方案的对比
| 能力 | macOS | Windows (增强后) | Linux |
|------|-------|-----------------|-------|
@@ -312,4 +242,11 @@ Phase F: ESC 热键 ← P2 体验优化，可后做
| ESC 热键 | CGEventTap | RegisterHotKey | 无 |
| 应用标识 | bundleId | exe 路径 + 窗口标题 | /proc + wmctrl |
**Windows 增强后将在 UI Automation 和 OCR 方面超过 macOS 方案**——这两项 macOS 原始实现也没有（Anthropic 用的是截图 + Claude 视觉理解，没有结构化 UI 数据）。
> [!info]
> Windows 增强后将在 UI Automation 和 OCR 方面超过 macOS 方案——这两项 macOS 原始实现也没有（Anthropic 用的是截图 + Claude 视觉理解，没有结构化 UI 数据）。
## 关联笔记
- [[computer-use]]
- [[computer-use-architecture-v2]]
- [[computer-use-tools-reference]]