mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-15 12:55:51 +00:00
c17edcb12e
三平台 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
497 lines
20 KiB
Markdown
497 lines
20 KiB
Markdown
# Computer Use 工具参考文档
|
||
|
||
## 概览
|
||
|
||
Computer Use 提供 37 个工具，分为三类：
|
||
|
||
| 分类 | 平台 | 工具数 | 说明 |
|
||
|------|------|--------|------|
|
||
| 通用工具 | 全平台 | 24 | 官方 Computer Use 标准能力 |
|
||
| Windows 专属工具 | Win32 | 10 | 绑定窗口模式下的增强能力 |
|
||
| 教学工具 | 全平台 | 3 | 分步引导模式（需 teachMode 开启） |
|
||
|
||
---
|
||
|
||
## 一、通用工具（24 个）
|
||
|
||
全平台可用。未绑定窗口时，操作对象是整个屏幕。
|
||
|
||
### 权限与会话
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `request_access` | `apps[]`, `reason`, `clipboardRead?`, `clipboardWrite?`, `systemKeyCombos?` | 请求操作应用的权限。所有其他工具的前置条件 |
|
||
| `list_granted_applications` | — | 列出当前会话已授权的应用 |
|
||
|
||
### 截图与显示
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `screenshot` | `save_to_disk?` | 截取当前屏幕。绑定窗口时截取绑定窗口（PrintWindow）。返回图片 + GUI 元素列表（Windows） |
|
||
| `zoom` | `region: [x1,y1,x2,y2]` | 截取指定区域的高分辨率图片。坐标基于最近一次全屏截图 |
|
||
| `switch_display` | `display` | 切换截图的目标显示器 |
|
||
|
||
### 鼠标操作
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `left_click` | `coordinate: [x,y]`, `text?` (修饰键) | 左键点击。`text` 可传 "shift"/"ctrl"/"alt" 实现组合点击 |
|
||
| `double_click` | `coordinate`, `text?` | 双击 |
|
||
| `triple_click` | `coordinate`, `text?` | 三击（选整行） |
|
||
| `right_click` | `coordinate`, `text?` | 右键点击 |
|
||
| `middle_click` | `coordinate`, `text?` | 中键点击 |
|
||
| `mouse_move` | `coordinate` | 移动鼠标（不点击） |
|
||
| `left_click_drag` | `coordinate` (终点), `start_coordinate?` (起点) | 拖拽 |
|
||
| `left_mouse_down` | — | 按下左键不松 |
|
||
| `left_mouse_up` | — | 松开左键 |
|
||
| `cursor_position` | — | 获取当前鼠标位置 |
|
||
|
||
### 键盘操作
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `type` | `text` | 输入文字 |
|
||
| `key` | `text` (如 "ctrl+s"), `repeat?` | 按键/组合键 |
|
||
| `hold_key` | `text`, `duration` (秒) | 按住键指定时长 |
|
||
|
||
### 滚动
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `scroll` | `coordinate`, `scroll_direction`, `scroll_amount` | 滚动。方向: up/down/left/right |
|
||
|
||
### 应用管理
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `open_application` | `app` | 打开应用。Windows 上自动绑定窗口 |
|
||
|
||
### 剪贴板
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `read_clipboard` | — | 读取剪贴板文字 |
|
||
| `write_clipboard` | `text` | 写入剪贴板 |
|
||
|
||
### 其他
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `wait` | `duration` (秒) | 等待 |
|
||
| `computer_batch` | `actions[]` | 批量执行多个动作（减少 API 往返） |
|
||
|
||
---
|
||
|
||
## 二、Windows 专属工具（10 个）
|
||
|
||
仅 Windows 平台可见。核心能力：**绑定窗口后的独立操作——不抢占用户鼠标键盘**。
|
||
|
||
### 工作模式
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────┐
|
||
│ 未绑定模式 │
|
||
│ 使用通用工具 (left_click/type/key/scroll) │
|
||
│ 操作对象：整个屏幕 │
|
||
│ 输入方式：全局 SendInput（会移动真实鼠标） │
|
||
└──────────────────────────────────────────────────┘
|
||
│
|
||
bind_window / open_application
|
||
▼
|
||
┌──────────────────────────────────────────────────┐
|
||
│ 绑定窗口模式 │
|
||
│ 使用 Win32 工具 (virtual_mouse/virtual_keyboard) │
|
||
│ 操作对象：绑定的窗口 │
|
||
│ 输入方式：SendMessageW（不动真实鼠标/键盘） │
|
||
│ 可视化：DWM 绿色边框 + 虚拟光标 + 状态指示器 │
|
||
└──────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 窗口绑定
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `bind_window` | `action`: list/bind/unbind/status | 窗口绑定管理 |
|
||
|
||
**动作详情：**
|
||
|
||
| action | 参数 | 说明 |
|
||
|--------|------|------|
|
||
| `list` | — | 列出所有可见窗口（hwnd、pid、title） |
|
||
| `bind` | `title?`, `hwnd?`, `pid?` | 绑定到指定窗口。设置 DWM 绿色边框 + 启动虚拟光标 + 启动状态指示器 + 短暂激活窗口确保可接收输入 |
|
||
| `unbind` | — | 解除绑定，恢复全屏模式 |
|
||
| `status` | — | 查看当前绑定状态（hwnd、title、pid、窗口矩形） |
|
||
|
||
### 窗口管理
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `window_management` | `action`, `x?`, `y?`, `width?`, `height?` | 窗口操作（Win32 API，不走全局快捷键） |
|
||
|
||
**动作详情：**
|
||
|
||
| action | 说明 |
|
||
|--------|------|
|
||
| `minimize` | ShowWindow(SW_MINIMIZE) |
|
||
| `maximize` | ShowWindow(SW_MAXIMIZE) |
|
||
| `restore` | ShowWindow(SW_RESTORE) — 恢复最小化/最大化 |
|
||
| `close` | SendMessage(WM_CLOSE) — 优雅关闭 |
|
||
| `focus` | SetForegroundWindow + BringWindowToTop — 激活窗口 |
|
||
| `move_offscreen` | SetWindowPos(-32000,-32000) — 移到屏幕外（仍可 SendMessage/PrintWindow） |
|
||
| `move_resize` | SetWindowPos — 移动/缩放到指定位置和大小 |
|
||
| `get_rect` | GetWindowRect — 获取当前位置和大小 |
|
||
|
||
### 虚拟鼠标
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `virtual_mouse` | `action`, `coordinate: [x,y]`, `start_coordinate?` | 在绑定窗口内操作虚拟鼠标 |
|
||
|
||
**动作详情：**
|
||
|
||
| action | 说明 |
|
||
|--------|------|
|
||
| `click` | 左键点击。虚拟光标移动到坐标 + 闪烁动画 |
|
||
| `double_click` | 双击 |
|
||
| `right_click` | 右键点击 |
|
||
| `move` | 移动虚拟光标（不点击） |
|
||
| `drag` | 按住 → 移动 → 松开。需 `start_coordinate` 指定起点 |
|
||
| `down` | 按下左键不松 |
|
||
| `up` | 松开左键 |
|
||
|
||
**与通用鼠标工具的区别：**
|
||
|
||
| | 通用 (`left_click` 等) | `virtual_mouse` |
|
||
|---|---|---|
|
||
| 输入方式 | SendInput（全局） | SendMessageW（窗口级） |
|
||
| 真实鼠标 | 会移动 | **不动** |
|
||
| 用户干扰 | 有 | **无** |
|
||
| 适用场景 | 未绑定时 | **绑定后** |
|
||
|
||
### 虚拟键盘
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `virtual_keyboard` | `action`, `text`, `duration?`, `repeat?` | 在绑定窗口内操作虚拟键盘 |
|
||
|
||
**动作详情：**
|
||
|
||
| action | text 含义 | 说明 |
|
||
|--------|----------|------|
|
||
| `type` | 要输入的文字 | SendMessageW(WM_CHAR)，支持 Unicode 中文/emoji |
|
||
| `combo` | 组合键 (如 "ctrl+s") | WM_KEYDOWN/UP 序列 |
|
||
| `press` | 单个键名 | 按下不松（配合 release 使用） |
|
||
| `release` | 单个键名 | 松开按键 |
|
||
| `hold` | 键名或组合 | 按住指定秒数后松开 |
|
||
|
||
**与通用键盘工具的区别：**
|
||
|
||
| | 通用 (`type`/`key`) | `virtual_keyboard` |
|
||
|---|---|---|
|
||
| 输入方式 | SendInput（全局） | SendMessageW（窗口级） |
|
||
| 物理键盘 | 会冲突 | **不冲突** |
|
||
| 适用场景 | 未绑定时 | **绑定后** |
|
||
|
||
**注意：** SendMessageW 对 Windows Terminal (ConPTY) 等现代应用无效。这些应用需要使用通用工具 + 窗口激活方式操作。
|
||
|
||
### 鼠标滚轮
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `mouse_wheel` | `coordinate: [x,y]`, `delta`, `direction?` | WM_MOUSEWHEEL 鼠标中键滚轮 |
|
||
|
||
**参数说明：**
|
||
- `delta`: 正值=向上，负值=向下。每 1 单位 ≈ 3 行
|
||
- `direction`: "vertical"（默认）或 "horizontal"
|
||
- `coordinate`: 滚轮作用点——决定哪个面板/区域接收滚动
|
||
|
||
**与通用 `scroll` 的区别：**
|
||
|
||
| | `scroll` | `mouse_wheel` |
|
||
|---|---|---|
|
||
| 原理 | WM_VSCROLL/WM_HSCROLL | **WM_MOUSEWHEEL** |
|
||
| Excel | ❌ | ✅ |
|
||
| 浏览器 | ❌ | ✅ |
|
||
| 代码编辑器 | ❌ | ✅ |
|
||
|
||
### 元素级操作
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `click_element` | `name?`, `role?`, `automationId?` | 按无障碍名称/角色点击 GUI 元素 |
|
||
| `type_into_element` | `name?`, `role?`, `automationId?`, `text` | 按名称向元素输入文字 |
|
||
|
||
**工作原理：**
|
||
1. 通过 UI Automation 在绑定窗口中查找匹配元素
|
||
2. `click_element`: 先尝试 InvokePattern（按钮/菜单），失败则 SendMessage 点击 BoundingRect 中心
|
||
3. `type_into_element`: 先尝试 ValuePattern 直接设值，失败则点击聚焦 + WM_CHAR 输入
|
||
|
||
**适用场景：**
|
||
- 截图中看到元素名称但坐标不精确时
|
||
- Accessibility Snapshot 列出了元素的 name/automationId 时
|
||
- 比坐标点击更可靠（不受窗口缩放/DPI 影响）
|
||
|
||
### 终端交互
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `prompt_respond` | `response_type`, `arrow_direction?`, `arrow_count?`, `text?` | 处理终端 Yes/No/选择提示 |
|
||
|
||
**response_type 详情：**
|
||
|
||
| response_type | 操作 | 场景 |
|
||
|---------------|------|------|
|
||
| `yes` | 发送 'y' + Enter | npm "Continue? (y/n)" |
|
||
| `no` | 发送 'n' + Enter | 拒绝确认 |
|
||
| `enter` | 发送 Enter | 接受默认选项 |
|
||
| `escape` | 发送 Escape | 取消操作 |
|
||
| `select` | ↑/↓ 箭头 × N + Enter | inquirer 选择菜单 |
|
||
| `type` | 输入文字 + Enter | 文本输入提示 |
|
||
|
||
### 状态指示器
|
||
|
||
| 工具 | 参数 | 说明 |
|
||
|------|------|------|
|
||
| `status_indicator` | `action`: show/hide/status, `message?` | 控制绑定窗口底部的浮动状态标签 |
|
||
|
||
---
|
||
|
||
## 三、教学工具（3 个）
|
||
|
||
需要 `teachMode` 开启。
|
||
|
||
| 工具 | 说明 |
|
||
|------|------|
|
||
| `request_teach_access` | 请求教学引导模式权限 |
|
||
| `teach_step` | 显示一步引导提示，等用户点 Next |
|
||
| `teach_batch` | 批量排队多步引导 |
|
||
|
||
---
|
||
|
||
## 操作流程
|
||
|
||
### 流程 1：全屏操作（未绑定）
|
||
|
||
```
|
||
request_access(apps=["Notepad"])
|
||
open_application(app="Notepad") ← 自动绑定窗口
|
||
screenshot ← PrintWindow 截图 + GUI 元素列表
|
||
left_click(coordinate=[500, 300]) ← 全局 SendInput
|
||
type(text="hello world") ← 全局 SendInput
|
||
key(text="ctrl+s") ← 全局 SendInput
|
||
```
|
||
|
||
### 流程 2：绑定窗口操作（推荐，不干扰用户）
|
||
|
||
```
|
||
request_access(apps=["Notepad"])
|
||
bind_window(action="list") ← 列出所有窗口
|
||
bind_window(action="bind", title="记事本") ← 绑定 + 绿色边框 + 虚拟光标
|
||
screenshot ← PrintWindow 截取绑定窗口
|
||
virtual_mouse(action="click", coordinate=[500, 300]) ← SendMessageW，不动真实鼠标
|
||
virtual_keyboard(action="type", text="hello world") ← SendMessageW，不动物理键盘
|
||
virtual_keyboard(action="combo", text="ctrl+s") ← 保存
|
||
mouse_wheel(coordinate=[500, 400], delta=-5) ← 向下滚动
|
||
bind_window(action="unbind") ← 解除绑定
|
||
```
|
||
|
||
### 流程 3：按元素名称操作
|
||
|
||
```
|
||
bind_window(action="bind", title="记事本")
|
||
screenshot ← 返回截图 + GUI elements 列表
|
||
click_element(name="保存", role="Button") ← UI Automation 查找并点击
|
||
type_into_element(role="Edit", text="new content")
|
||
```
|
||
|
||
### 流程 4：终端交互
|
||
|
||
```
|
||
bind_window(action="bind", title="PowerShell")
|
||
screenshot
|
||
prompt_respond(response_type="yes") ← 回答 y + Enter
|
||
prompt_respond(response_type="select", arrow_direction="down", arrow_count=2) ← 选第3项
|
||
```
|
||
|
||
### 流程 5：Excel/浏览器滚动
|
||
|
||
```
|
||
bind_window(action="bind", title="Excel")
|
||
screenshot
|
||
mouse_wheel(coordinate=[600, 400], delta=-10) ← 向下滚动 10 格
|
||
mouse_wheel(coordinate=[600, 400], delta=5, direction="horizontal") ← 向右滚动
|
||
```
|
||
|
||
---
|
||
|
||
## 应用兼容性
|
||
|
||
| 应用类型 | SendMessageW (virtual_*) | 元素操作 (click_element) | 注意 |
|
||
|---------|--------------------------|------------------------|------|
|
||
| 传统 Win32 (记事本/写字板) | ✅ | ✅ | 完美支持 |
|
||
| Office (Excel/Word) | ✅ (COM 自动化) | ✅ | 通过 COM API |
|
||
| WPF 应用 | ✅ | ✅ | 标准 UIA 支持 |
|
||
| Electron/Chrome | ⚠️ 部分 | ⚠️ 部分 | 内部渲染不走 Win32 消息 |
|
||
| UWP/WinUI (Windows Terminal) | ❌ | ❌ | ConPTY 不接受 SendMessageW |
|
||
| 浏览器网页内容 | ❌ | ❌ | 需要全局 SendInput |
|
||
|
||
**对于不支持 SendMessageW 的应用**，使用通用工具 (`left_click`/`type`/`key`) + `window_management(action="focus")` 先激活窗口。
|
||
|
||
---
|
||
|
||
## 绑定窗口时的可视化
|
||
|
||
绑定窗口后自动启动三层可视化：
|
||
|
||
1. **DWM 绿色边框** — 窗口自身的边框颜色变绿，零偏移
|
||
2. **虚拟鼠标光标** — 红色箭头图标，跟随 virtual_mouse 操作移动，点击时闪烁
|
||
3. **状态指示器** — 窗口底部浮动标签，显示当前操作（通过 status_indicator 控制）
|
||
|
||
---
|
||
|
||
## Accessibility Snapshot
|
||
|
||
每次 `screenshot` 时，如果窗口已绑定，会自动附带 GUI 元素列表：
|
||
|
||
```
|
||
GUI elements in this window:
|
||
[Button] "Save" (120,50 80x30) enabled
|
||
[Edit] "" (200,80 400x25) enabled value="hello" id=textBox1
|
||
[MenuItem] "File" (10,0 40x25) enabled
|
||
[MenuItem] "Edit" (50,0 40x25) enabled
|
||
[CheckBox] "Auto-save" (300,50 100x20) enabled id=chkAutoSave
|
||
```
|
||
|
||
模型同时收到 **截图图片 + 结构化元素列表**，可以选择：
|
||
- 用坐标操作：`virtual_mouse(action="click", coordinate=[120, 50])`
|
||
- 用名称操作：`click_element(name="Save")`
|
||
|
||
---
|
||
|
||
## UI Automation Control Patterns 参考
|
||
|
||
`click_element` / `type_into_element` 底层使用 UI Automation Control Patterns。当前已实现的和可扩展的：
|
||
|
||
| Pattern | 用途 | 当前状态 | 可用于 |
|
||
|---------|------|---------|--------|
|
||
| `InvokePattern` | 触发点击 | ✅ 已实现 (`click_element`) | 按钮、菜单项、链接 |
|
||
| `ValuePattern` | 读写文本值 | ✅ 已实现 (`type_into_element`) | 文本框、组合框 |
|
||
| `TogglePattern` | 切换状态 | ❌ 未实现 | 复选框、开关 |
|
||
| `SelectionPattern` | 选择项目 | ❌ 未实现 | 下拉菜单、列表 |
|
||
| `ScrollPattern` | 编程滚动 | ❌ 未实现（用 `mouse_wheel` 替代） | 列表、树、面板 |
|
||
| `ExpandCollapsePattern` | 展开/折叠 | ❌ 未实现 | 树节点、折叠面板 |
|
||
| `WindowPattern` | 窗口操作 | ❌ 未实现（用 `window_management` 替代） | 窗口最大化/关闭 |
|
||
| `TextPattern` | 读取文档文本 | ❌ 未实现 | 文档、富文本 |
|
||
| `GridPattern` | 表格操作 | ❌ 未实现 | Excel 单元格、数据网格 |
|
||
| `TablePattern` | 表格结构 | ❌ 未实现 | 表头、行列关系 |
|
||
| `RangeValuePattern` | 范围值操作 | ❌ 未实现 | 滑块、进度条 |
|
||
| `TransformPattern` | 移动/缩放 | ❌ 未实现 | 可拖拽元素 |
|
||
|
||
**扩展路线：** 优先实现 `TogglePattern`（复选框）和 `SelectionPattern`（下拉菜单），这两个在表单自动化中最常用。
|
||
|
||
---
|
||
|
||
## 屏幕截取技术方案对比
|
||
|
||
当前使用 Python Bridge (mss) 进行截图，底层是 GDI BitBlt。三种方案对比：
|
||
|
||
| 方案 | API | 当前状态 | 性能 | 优势 | 限制 |
|
||
|------|-----|---------|------|------|------|
|
||
| **GDI BitBlt** | `BitBlt` / `PrintWindow` | ✅ 当前使用 (mss/bridge.py) | ~300ms | 简单稳定，支持后台窗口 (PrintWindow) | 不支持硬件加速内容、DPI 处理复杂 |
|
||
| **DXGI Desktop Duplication** | `IDXGIOutputDuplication` | ❌ 未实现 | ~16ms (60fps) | 硬件加速，支持 HDR，GPU 直接读取 | 不支持单窗口截取，需 D3D11 |
|
||
| **Windows.Graphics.Capture** | `GraphicsCaptureItem` | ❌ 未实现 | ~16ms | 最新 API，支持单窗口/单显示器，系统级权限管理 | Win10 1903+，首次需用户确认 |
|
||
|
||
### 推荐升级路径
|
||
|
||
```
|
||
当前: GDI BitBlt (mss) ─── 全屏 ~300ms, 窗口 ~300ms (PrintWindow)
|
||
│
|
||
├─ 近期: DXGI Desktop Duplication ─── 全屏 ~16ms, 但不支持单窗口
|
||
│
|
||
└─ 远期: Windows.Graphics.Capture ─── 全屏 + 单窗口都 ~16ms
|
||
```
|
||
|
||
### DXGI Desktop Duplication 实现要点
|
||
|
||
```python
|
||
# bridge.py 中可添加 DXGI 截图（通过 d3dshot 或 dxcam 库）
|
||
import dxcam # pip install dxcam
|
||
|
||
camera = dxcam.create()
|
||
frame = camera.grab() # numpy array, ~5ms
|
||
# 转为 JPEG base64 发送
|
||
```
|
||
|
||
### Windows.Graphics.Capture 实现要点
|
||
|
||
```python
|
||
# 需要 WinRT Python 绑定
|
||
# pip install winrt-Windows.Graphics.Capture winrt-Windows.Graphics.DirectX
|
||
# 限制：首次调用需要用户在系统弹窗中确认权限
|
||
```
|
||
|
||
---
|
||
|
||
## 输入方式技术矩阵
|
||
|
||
不同应用类型需要不同的输入方式：
|
||
|
||
| 输入方式 | API | 优势 | 限制 | 适用应用 |
|
||
|---------|-----|------|------|---------|
|
||
| **SendMessageW** | `WM_CHAR` / `WM_KEYDOWN` | 不抢焦点，不动真实键鼠 | 现代应用不支持 | Win32 传统应用 (记事本/Office/WPF) |
|
||
| **SendInput** | `INPUT` 结构体 | 所有应用都支持 | **必须前台焦点**，会干扰用户 | 所有应用（通用后备） |
|
||
| **WriteConsoleInput** | 控制台 API | 直接写入控制台缓冲区 | 需要 AttachConsole（可能被拒绝） | cmd/PowerShell（非 Windows Terminal） |
|
||
| **UI Automation** | `InvokePattern` / `ValuePattern` | 语义级操作，最可靠 | 部分应用不暴露 UIA 接口 | 支持 UIA 的应用 |
|
||
| **COM Automation** | Excel/Word COM | 完全编程控制 | 仅 Office 应用 | Excel / Word |
|
||
| **剪贴板 + 粘贴** | `SetClipboardData` + `Ctrl+V` | 绕过输入限制 | 会覆盖用户剪贴板 | 通用后备 |
|
||
|
||
### 按应用类型的推荐输入策略
|
||
|
||
| 应用类型 | 首选 | 后备 | 说明 |
|
||
|---------|------|------|------|
|
||
| 传统 Win32 (记事本/写字板) | SendMessageW | UIA ValuePattern | 虚拟输入完美工作 |
|
||
| Office (Excel/Word) | COM Automation | SendMessageW | COM 提供结构化操作 |
|
||
| WPF 应用 | SendMessageW | UIA | 标准 Win32 消息循环 |
|
||
| Electron/Chrome 应用 | UIA | 剪贴板粘贴 | 内部渲染不走 Win32 |
|
||
| Windows Terminal (ConPTY) | SendInput (需前台) | 剪贴板粘贴 | ConPTY 不接受外部消息 |
|
||
| UWP/WinUI 应用 | SendInput (需前台) | UIA | XAML 渲染不走 Win32 消息 |
|
||
|
||
---
|
||
|
||
## 已知限制与待解决
|
||
|
||
| 限制 | 影响 | 计划 |
|
||
|------|------|------|
|
||
| Windows Terminal 不接受 SendMessageW | 虚拟键盘/鼠标对终端无效 | 自动检测应用类型，终端类切换到 SendInput + 短暂激活 |
|
||
| PrintWindow 截不到 alternate screen buffer | Ink REPL 画面截不到 | 切换到 Windows.Graphics.Capture |
|
||
| Accessibility Snapshot 对大应用慢 (>30s) | Excel 等复杂应用超时 | 限制遍历深度 + 超时保护 |
|
||
| DWM 边框对自定义标题栏应用可能无效 | 某些 Electron 应用看不到边框 | 检测并回退到叠加窗口方案 |
|
||
| 虚拟光标是 PowerShell WinForms 进程 | 启动慢 (~1s)，资源占用 | 考虑用 Win32 原生窗口替代 |
|
||
|
||
---
|
||
|
||
## 技术路线图
|
||
|
||
### Phase 1（当前）— 基础功能
|
||
- ✅ SendMessageW 虚拟输入
|
||
- ✅ PrintWindow/mss 截图
|
||
- ✅ UI Automation (InvokePattern + ValuePattern)
|
||
- ✅ Accessibility Snapshot
|
||
- ✅ DWM 边框指示
|
||
- ✅ Python Bridge
|
||
|
||
### Phase 2（近期）— 兼容性增强
|
||
- ⬜ 应用类型自动检测（Win32 vs Terminal vs UWP）
|
||
- ⬜ 终端类应用自动切换 SendInput + 短暂激活
|
||
- ⬜ TogglePattern / SelectionPattern 支持
|
||
- ⬜ DXGI Desktop Duplication 高速截图
|
||
- ⬜ Accessibility Snapshot 超时保护
|
||
|
||
### Phase 3（远期）— 高级能力
|
||
- ⬜ Windows.Graphics.Capture（单窗口实时截图）
|
||
- ⬜ 截图元素标注（在截图上标记 ID 数字）
|
||
- ⬜ 浏览器 DOM 提取（绑定浏览器时提取网页结构）
|
||
- ⬜ GridPattern / TablePattern（Excel 单元格级操作）
|
||
- ⬜ TextPattern（文档内容读取）
|
||
- ⬜ 多窗口协同操作
|