Computer Use 功能指南

实现说明：EchoFlow Code 通过 Python Bridge 提供本地 Computer Use 能力。macOS 使用 pyautogui + mss + pyobjc，Windows 使用 pyautogui + mss + win32gui + psutil，将截图、鼠标、键盘和应用管理统一封装为可审计的本地 MCP 工具。

功能简介

Computer Use 让 AI 模型能够直接控制你的电脑——截屏、移动鼠标、点击按钮、输入文字、管理应用窗口。

支持的操作（共 24 个 MCP 工具）：

类别	工具
截屏	`screenshot`、`zoom`
鼠标	`left_click`、`right_click`、`middle_click`、`double_click`、`triple_click`、`left_click_drag`、`mouse_move`、`left_mouse_down`、`left_mouse_up`、`cursor_position`、`scroll`
键盘	`type`、`key`、`hold_key`
应用	`open_application`、`switch_display`
权限	`request_access`、`list_granted_applications`
剪贴板	`read_clipboard`、`write_clipboard`
其他	`wait`、`computer_batch`

支持的设备与平台

平台	芯片	状态	说明
macOS	Apple Silicon (M1/M2/M3/M4)	✅ 完整支持	推荐平台
macOS	Intel x86_64	✅ 完整支持
Windows	x64	✅ 完整支持	使用 `win32gui` + `psutil` + `pyperclip` + `screeninfo` 替代 macOS 专有 API
Linux	任意	⚠️ 理论可行	需替换平台专有部分为 `wmctrl` + `xdotool`，当前未适配

运行环境要求

Bun >= 1.1.0
Python >= 3.8（首次运行自动创建 venv 并安装依赖）
macOS：系统权限 Accessibility（辅助功能）+ Screen Recording（屏幕录制）
Windows：无需额外权限配置

工作原理

Computer Use 的核心是一个截图-分析-操作的闭环：

┌──────────────────────────────────────────────┐
│  AI 模型（Claude / 其他 Anthropic 协议模型）     │
│                                               │
│  1. 收到用户请求 "打开网易云搜索喜欢你"            │
│  2. 调用 screenshot 工具 → 收到屏幕截图           │
│  3. 模型分析截图像素，识别 UI 元素位置              │
│     → "搜索框在 (756, 342)"                     │
│  4. 调用 left_click { coordinate: [756, 342] }  │
│  5. 调用 type { text: "喜欢你" }                 │
│  6. 再次 screenshot → 确认结果 → 下一步...        │
└──────────────┬───────────────────────────────┘
               │ MCP Tool Call
               ▼
┌──────────────────────────────────────────────┐
│  TypeScript 工具层                              │
│  (vendor/computer-use-mcp)                     │
│                                               │
│  - 安全检查（应用白名单、TCC 权限）               │
│  - 坐标模式转换（pixels / normalized）           │
│  - 工具分发 → executor                          │
└──────────────┬───────────────────────────────┘
               │ callPythonHelper()
               ▼
┌──────────────────────────────────────────────┐
│  Python Bridge                                │
│  macOS: runtime/mac_helper.py                 │
│  Windows: runtime/win_helper.py               │
│                                               │
│  pyautogui.click(756, 342)  ← 鼠标控制         │
│  mss.grab(monitor)          ← 截图             │
│  macOS: NSWorkspace.open()  ← 应用管理          │
│  Windows: win32gui / psutil ← 应用管理          │
└──────────────────────────────────────────────┘

关键：坐标分析完全由模型的视觉能力完成——模型"看"截图就像人看屏幕一样，直接从像素中识别按钮、输入框等 UI 元素的位置。

快速开始

1. 安装依赖

bash

bun install

2. 确保 Python 3 可用

bash

python3 --version  # 需要 >= 3.8

Python 依赖会在首次使用 Computer Use 时自动安装到 .runtime/venv/，无需手动操作。

3. 授予 macOS 权限

Accessibility（辅助功能）

bash

open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"

将你的终端应用（如 iTerm、Terminal、Ghostty 等）添加到允许列表。

Screen Recording（屏幕录制）

bash

open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"

同样添加你的终端应用。授权后可能需要重启终端。

4. 启动

bash

./bin/claude-haha

5. 使用

在对话中用自然语言请求即可：

> 帮我打开网易云音乐，搜索一首歌
> 截个屏看看当前桌面
> 帮我在 VS Code 里打开终端

使用方式

首次使用 Computer Use 时，系统会弹出应用授权对话框，你需要选择允许 Claude 操作的应用。

模型会先调用 request_access 请求权限
你在终端中确认允许哪些应用
之后模型就可以截图、点击、输入了

禁用 Computer Use

如果你只想使用普通 Coding Agent，不希望暴露 computer-use MCP 工具，可以使用任一方式禁用：

bash

claude-haha --no-computer-use
CLAUDE_COMPUTER_USE_ENABLED=0 claude-haha

也可以写入全局配置文件 ~/.claude/cc-haha/computer-use-config.json：

json

{
  "enabled": false
}

桌面端的 Settings > Computer Use 开关写入同一个配置。关闭后，新会话不会注入 computer-use 动态 MCP，也不会把桌面控制工具加入 allowedTools。

安全机制

机制	说明
应用白名单	每次会话需要明确授权允许操作的应用
并发保护	同一时间只有一个 Claude 会话可使用 Computer Use（文件锁机制）
剪贴板保护	通过剪贴板输入文本时会自动保存和恢复原始剪贴板内容
操作确认	敏感操作（如系统快捷键）需要额外授权

注意：由于底层使用 Python Bridge，全局 Escape 快捷键中止和操作前自动隐藏应用功能暂不可用。可使用 Ctrl+C 中止。

环境变量

变量	默认值	说明
`CLAUDE_COMPUTER_USE_ENABLED`	`1`	设为 `0` 可禁用 Computer Use
`CLAUDE_COMPUTER_USE_COORDINATE_MODE`	`pixels`	坐标模式：`pixels` 或 `normalized_0_100`
`CLAUDE_COMPUTER_USE_CLIPBOARD_PASTE`	`1`	是否启用剪贴板粘贴输入
`CLAUDE_COMPUTER_USE_MOUSE_ANIMATION`	`1`	是否启用鼠标动画
`CLAUDE_COMPUTER_USE_HIDE_BEFORE_ACTION`	`0`	操作前是否隐藏其他窗口
`CLAUDE_COMPUTER_USE_DEBUG`	`0`	调试模式

技术架构详解

整体分层

src/
├── vendor/computer-use-mcp/     ← MCP 工具定义与分发（12 个文件）
│   ├── tools.ts                 ← 24 个工具的 schema 定义
│   ├── toolCalls.ts             ← 安全检查 + 工具分发
│   ├── mcpServer.ts             ← MCP 服务器创建
│   ├── types.ts                 ← 全部类型定义
│   └── ...
├── utils/computerUse/
│   ├── executor.ts              ← 执行器（调用 Python bridge）
│   ├── pythonBridge.ts          ← Python 子进程管理
│   ├── hostAdapter.ts           ← 权限检查适配器
│   ├── gates.ts                 ← 功能启用策略
│   ├── wrapper.tsx              ← MCP 工具覆写层
│   ├── setup.ts                 ← MCP 配置初始化
│   └── ...
└── runtime/
    ├── mac_helper.py            ← macOS Python 实现
    ├── win_helper.py            ← Windows Python 实现
    ├── requirements.txt         ← macOS Python 依赖
    └── requirements-win.txt     ← Windows Python 依赖

功能启用策略

EchoFlow Code 的 Computer Use 由本地配置和启动参数控制，不依赖远程 feature flag。相关开关集中在 gates.ts 和配置文件中，便于在 CLI、桌面端和测试环境中保持一致。

层级	当前策略
构建配置	Computer Use 工具按需注入
本地配置	`CLAUDE_COMPUTER_USE_ENABLED` 和 `computer-use-config.json` 控制启停
远程配置	不依赖远程 feature flag
会话安全	仍保留应用白名单、TCC 权限和敏感操作检查

Python Bridge 工作机制

typescript

// pythonBridge.ts
async function callPythonHelper<T>(command: string, payload: object): Promise<T> {
  await ensureBootstrapped()  // 首次调用自动创建 venv + pip install
  
  // 调用: python3 runtime/mac_helper.py <command> --payload '{...}'
  const result = execFile(pythonBin, ['mac_helper.py', command, '--payload', JSON.stringify(payload)])
  
  return JSON.parse(result.stdout)  // { ok: true, result: T }
}

首次运行自动完成：

创建 Python 虚拟环境 (.runtime/venv/)
安装 pip
按平台安装依赖：
- macOS: mss, Pillow, pyautogui, pyobjc-*（requirements.txt）
- Windows: mss, Pillow, pyautogui, win32gui, psutil, pyperclip, screeninfo（requirements-win.txt）
SHA256 哈希验证（仅 requirements 变更时重新安装）

我们尝试过的方案

方案一：复用原生 .node 模块 ❌

思路：调研原生 NAPI 模块在本地运行时中的复用可行性。

实施：

原生模块的同步方法（TCC 权限检查、显示枚举）在早期调研中可工作
创建了 npm 包装包并通过 workspace 注册

失败原因：

Swift 异步方法（screenshot.captureExcluding）的 continuation 永远不会 resume
根因：原生模块与用户系统的 Bun 版本存在 N-API 异步实现兼容性问题
错误信息：SWIFT TASK CONTINUATION MISUSE: captureScreenWithExclusion leaked its continuation without resuming it

方案二：创建空 Stub 包 ❌

思路：为 @ant/computer-use-mcp、@ant/computer-use-input、@ant/computer-use-swift 创建最小化的 stub 包，使代码能编译加载。

失败原因：代码能编译但 MCP 服务器注册后无法执行任何实际操作——截图、点击等全部报错。

方案三：Python Bridge 替代原生模块 ✅（当前方案）

思路：参考 wimi321/macos-computer-use-skill，用 Python 子进程替代所有原生模块调用。

优势：

零二进制依赖，不依赖特定 Bun/Node 版本
纯 Python 实现，首次运行自动安装
截图、鼠标、键盘、应用管理全部可用
macOS ARM64 + x86_64 均支持

已知限制

限制	说明
不支持 Linux	需要适配平台专有 API 部分
无全局 Escape 中止	原生方案用 CGEventTap 实现，Python 版暂不支持，用 `Ctrl+C` 代替
操作前不自动隐藏窗口	原生方案的 `prepareDisplay` 依赖 Swift，Python 版未实现
性能略低	Python 进程启动 ~100ms 开销，但模型思考时间通常是秒级，用户感知不到
像素验证关闭	`pixelValidation` 默认关闭

参考项目与致谢

本功能的实现参考了以下开源项目，在此致以感谢：

项目	许可证	贡献
wimi321/macos-computer-use-skill	MIT	Python bridge 架构、`mac_helper.py` 运行时、`executor.ts` 适配方案。该项目整理了可复用的 Computer Use TypeScript 逻辑，并用公开 Python 库实现本地桌面交互
domdomegg/computer-use-mcp	MIT	独立的 Computer Use MCP 服务器实现（基于 nut.js），跨平台可用。在方案调研阶段提供了参考
paoloanzn/free-code	-	Feature flag 系统分析和构建系统参考
oboard/claude-code-rev	-	早期兼容性研究，提供了 stub 包的参考实现

底层依赖

库	平台	用途
pyautogui	跨平台	鼠标和键盘控制
mss	跨平台	屏幕截图
Pillow	跨平台	图像处理和压缩
pyobjc	macOS	Cocoa/Quartz 框架绑定（应用管理、显示枚举）
pywin32	Windows	Win32 API 绑定（窗口管理）
psutil	Windows	进程管理（应用列表、进程操作）
pyperclip	Windows	剪贴板操作
screeninfo	Windows	显示器信息（多屏支持）

Computer Use 功能指南 ​

目录 ​

功能简介 ​

支持的设备与平台 ​

运行环境要求 ​

工作原理 ​

快速开始 ​

1. 安装依赖 ​

2. 确保 Python 3 可用 ​

3. 授予 macOS 权限 ​

Accessibility（辅助功能） ​

Screen Recording（屏幕录制） ​

4. 启动 ​

5. 使用 ​

使用方式 ​

禁用 Computer Use ​

安全机制 ​

环境变量 ​

技术架构详解 ​

整体分层 ​

功能启用策略 ​

Python Bridge 工作机制 ​

我们尝试过的方案 ​

方案一：复用原生 .node 模块 ❌ ​

方案二：创建空 Stub 包 ❌ ​

方案三：Python Bridge 替代原生模块 ✅（当前方案） ​

已知限制 ​

参考项目与致谢 ​

底层依赖 ​

Computer Use 功能指南

目录

功能简介

支持的设备与平台

运行环境要求

工作原理

快速开始

1. 安装依赖

2. 确保 Python 3 可用

3. 授予 macOS 权限

Accessibility（辅助功能）

Screen Recording（屏幕录制）

4. 启动

5. 使用

使用方式

禁用 Computer Use

安全机制

环境变量

技术架构详解

整体分层

功能启用策略

Python Bridge 工作机制

我们尝试过的方案

方案一：复用原生 .node 模块 ❌

方案二：创建空 Stub 包 ❌

方案三：Python Bridge 替代原生模块 ✅（当前方案）

已知限制

参考项目与致谢

底层依赖