wonder/cs-note
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
cs-note/claude-code-best/docs/features/computer-use-tools-reference.md
T

16 KiB
Raw Permalink Blame History

tags, create time
tags create time
computer-use
windows
工具参考
virtual-mouse
virtual-keyboard
ui-automation
2026-06-09 22:30

Computer Use 工具参考文档

概述

Computer Use 提供 38 个工具，分为通用工具（24 个，全平台）、Windows 专属工具（12 个，绑定窗口模式增强）和教学工具（3 个）三类。本文档是完整的工具参数和使用说明参考。

正文

一、通用工具（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 专属工具（12 个）

仅 Windows 平台可见。核心能力：绑定窗口后的独立操作——不抢占用户鼠标键盘。

工作模式

graph TB
    A["未绑定模式"] -->|"使用通用工具 left_click/type/key/scroll"| B["操作对象: 整个屏幕"]
    A -->|"输入方式: 全局 SendInput（会移动真实鼠标）"| B
    A -->|"bind_window / open_application"| C["绑定窗口模式"]
    C -->|"使用 Win32 工具 virtual_mouse/virtual_keyboard"| D["操作对象: 绑定的窗口"]
    C -->|"输入方式: SendMessageW（不动真实鼠标/键盘）"| D
    C -->|"可视化: DWM 绿色边框 + 虚拟光标 + 状态指示器"| D

窗口绑定

工具 参数 说明
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)
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（窗口级）
物理键盘 会冲突 不冲突
适用场景 未绑定时 绑定后

Warning

SendMessageW 对 Windows Terminal (ConPTY) 等现代应用无效。这些应用需要使用通用工具 + 窗口激活方式操作。

鼠标滚轮

工具 参数 说明
mouse_wheel coordinate: [x,y], delta, direction? WM_MOUSEWHEEL 鼠标中键滚轮
  • delta: 正值=向上，负值=向下。每 1 单位 ≈ 3 行
  • direction: "vertical"（默认）或 "horizontal"

与通用 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 输入

终端交互

工具 参数 说明
open_terminal agent, command? 打开新终端窗口并启动 AI agent（claude/codex/gemini/custom）
activate_window click_x?, click_y? 激活绑定窗口
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")

应用兼容性

应用类型 SendMessageW (virtual_*) 元素操作 (click_element) 注意
传统 Win32 (记事本/写字板) ✅ ✅ 完美支持
Office (Excel/Word) ✅ (COM 自动化) ✅ 通过 COM API
WPF 应用 ✅ ✅ 标准 UIA 支持
Electron/Chrome ⚠️ 部分 ⚠️ 部分 内部渲染不走 Win32 消息
UWP/WinUI (Windows Terminal) ❌ ❌ ConPTY 不接受 SendMessageW
浏览器网页内容 ❌ ❌ 需要全局 SendInput

Tip

对于不支持 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

模型同时收到 截图图片 + 结构化元素列表，可以选择用坐标操作或用名称操作。

UI Automation Control Patterns 参考

click_element / type_into_element 底层使用 UI Automation Control Patterns：

Pattern 用途 当前状态 可用于
InvokePattern 触发点击 ✅ 已实现 按钮、菜单项、链接
ValuePattern 读写文本值 ✅ 已实现 文本框、组合框
TogglePattern 切换状态 ❌ 未实现 复选框、开关
SelectionPattern 选择项目 ❌ 未实现 下拉菜单、列表
ScrollPattern 编程滚动 ❌ 未实现 列表、树、面板
ExpandCollapsePattern 展开/折叠 ❌ 未实现 树节点、折叠面板
WindowPattern 窗口操作 ❌ 未实现 窗口最大化/关闭
TextPattern 读取文档文本 ❌ 未实现 文档、富文本
GridPattern 表格操作 ❌ 未实现 Excel 单元格、数据网格
TablePattern 表格结构 ❌ 未实现 表头、行列关系
RangeValuePattern 范围值操作 ❌ 未实现 滑块、进度条
TransformPattern 移动/缩放 ❌ 未实现 可拖拽元素

[!question] 扩展路线：优先实现 TogglePattern（复选框）和 SelectionPattern（下拉菜单），这两个在表单自动化中最常用。

屏幕截取技术方案对比

方案 API 当前状态 性能 优势 限制
GDI BitBlt BitBlt / PrintWindow ✅ 当前使用 (mss/bridge.py) ~300ms 简单稳定，支持后台窗口 不支持硬件加速内容
DXGI Desktop Duplication IDXGIOutputDuplication ❌ 未实现 ~16ms (60fps) 硬件加速，GPU 直接读取 不支持单窗口截取
Windows.Graphics.Capture GraphicsCaptureItem ❌ 未实现 ~16ms 最新 API，支持单窗口/单显示器 Win10 1903+

推荐升级路径

graph LR
    A["当前: GDI BitBlt mss 全屏~300ms"] --> B["近期: DXGI Desktop Duplication 全屏~16ms"]
    B --> C["远期: Windows.Graphics.Capture 全屏+单窗口~16ms"]

输入方式技术矩阵

输入方式 API 优势 限制 适用应用
SendMessageW WM_CHAR / WM_KEYDOWN 不抢焦点，不动真实键鼠 现代应用不支持 Win32 传统应用
SendInput INPUT 结构体 所有应用都支持 必须前台焦点 所有应用（通用后备）
WriteConsoleInput 控制台 API 直接写入控制台缓冲区 需要 AttachConsole cmd/PowerShell
UI Automation InvokePattern / ValuePattern 语义级操作，最可靠 部分应用不暴露 UIA 支持 UIA 的应用
COM Automation Excel/Word COM 完全编程控制 仅 Office 应用 Excel / Word
剪贴板 + 粘贴 SetClipboardData + Ctrl+V 绕过输入限制 会覆盖用户剪贴板 通用后备

已知限制与待解决

限制 影响 计划
Windows Terminal 不接受 SendMessageW 虚拟键盘/鼠标对终端无效 自动检测应用类型，终端类切换到 SendInput + 短暂激活
PrintWindow 截不到 alternate screen buffer Ink REPL 画面截不到 切换到 Windows.Graphics.Capture
Accessibility Snapshot 对大应用慢 (>30s) Excel 等复杂应用超时 限制遍历深度 + 超时保护
DWM 边框对自定义标题栏应用可能无效 某些 Electron 应用看不到边框 检测并回退到叠加窗口方案

技术路线图

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（文档内容读取）
  • ⬜ 多窗口协同操作

关联笔记

Reference in New Issue View Git Blame Copy Permalink