mirror of
https://github.com/NanmiCoder/cc-haha
synced 2026-07-15 12:53:31 +08:00
1cd90dc66a
Computer Use is useful when explicitly needed, but exposing its MCP tools by default creates unnecessary desktop-control surface for users who want coding-only sessions. This adds a shared disable path for CLI flags, environment, and desktop settings while keeping preauthorized app state in one config file. The same change also preserves Windows and WSL shell startup behavior by applying the MSYS argument-conversion guard only on WSL-bound launches. Constraint: Computer Use MCP must not be exposed to the Coding Agent when disabled Constraint: Desktop settings and CLI sessions need to read the same persisted Computer Use config Rejected: Environment-only disable switch | desktop users need a persistent Settings control Rejected: Remove Computer Use setup entirely | enabled sessions still need the existing built-in MCP path Confidence: high Scope-risk: moderate Directive: Keep every new Computer Use entrypoint wired through loadStoredComputerUseConfig or the CLI disable flag before adding MCP tools Tested: bun test src/utils/computerUse/gates.test.ts src/utils/computerUse/preauthorizedConfig.test.ts src/server/__tests__/computer-use-api.test.ts src/utils/shell/wslInterop.test.ts desktop/src/pages/ComputerUseSettings.test.tsx Tested: bun run check:server; bun run check:desktop; bun run check:docs; bun run check:policy; bun run check:native; git diff --check Tested: SKIP_INSTALL=1 ./desktop/scripts/build-macos-arm64.sh; codesign verify; hdiutil verify; built CLI Computer Use E2E exposure and disable checks Not-tested: Full screenshot/control action after granting macOS Screen Recording permission on this machine
342 lines
14 KiB
Markdown
342 lines
14 KiB
Markdown
# Computer Use 功能指南
|
||
|
||
|
||
> **魔改说明**：本功能是基于 Claude Code 泄露源码中的 Computer Use（内部代号 "Chicago"）进行的**深度改造版本**。官方实现依赖 Anthropic 内部私有原生模块（`@ant/computer-use-swift`、`@ant/computer-use-input`），无法公开获取。我们**替换了整个底层操作层**，使用 Python bridge 实现所有系统交互——macOS 使用 `pyautogui` + `mss` + `pyobjc`，Windows 使用 `pyautogui` + `mss` + `win32gui` + `psutil`，使得任何人都可以在 macOS 和 Windows 上运行 Computer Use 功能。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [功能简介](#功能简介)
|
||
- [支持的设备与平台](#支持的设备与平台)
|
||
- [工作原理](#工作原理)
|
||
- [快速开始](#快速开始)
|
||
- [使用方式](#使用方式)
|
||
- [安全机制](#安全机制)
|
||
- [环境变量](#环境变量)
|
||
- [技术架构详解](#技术架构详解)
|
||
- [我们尝试过的方案](#我们尝试过的方案)
|
||
- [已知限制](#已知限制)
|
||
- [参考项目与致谢](#参考项目与致谢)
|
||
|
||
---
|
||
|
||
## 功能简介
|
||
|
||
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](https://bun.sh) >= 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 依赖
|
||
```
|
||
|
||
### 灰度控制绕过
|
||
|
||
官方 Claude Code 中 Computer Use 通过三层门控限制访问：
|
||
|
||
| 层级 | 原始机制 | 我们的处理 |
|
||
|------|----------|-----------|
|
||
| 编译时 | `feature('CHICAGO_MCP')` (Bun 编译宏) | 替换为 `true` |
|
||
| 订阅检查 | `hasRequiredSubscription()` (Max/Pro) | `getChicagoEnabled()` 直接返回 `true` |
|
||
| 远程配置 | GrowthBook `tengu_malort_pedway` | 同上，不再依赖远程配置 |
|
||
| 默认禁用 | `isDefaultDisabledBuiltin('computer-use')` | `isDefaultDisabledBuiltin()` 返回 `false` |
|
||
|
||
### 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 }
|
||
}
|
||
```
|
||
|
||
首次运行自动完成：
|
||
1. 创建 Python 虚拟环境 (`.runtime/venv/`)
|
||
2. 安装 pip
|
||
3. 按平台安装依赖：
|
||
- **macOS**: `mss`, `Pillow`, `pyautogui`, `pyobjc-*`（`requirements.txt`）
|
||
- **Windows**: `mss`, `Pillow`, `pyautogui`, `win32gui`, `psutil`, `pyperclip`, `screeninfo`（`requirements-win.txt`）
|
||
4. SHA256 哈希验证（仅 requirements 变更时重新安装）
|
||
|
||
---
|
||
|
||
## 我们尝试过的方案
|
||
|
||
### 方案一：从 Claude Code 二进制提取原生 .node 模块 ❌
|
||
|
||
**思路**：从已安装的 Claude Code 二进制 (`~/.local/share/claude/versions/2.1.91`，189MB Mach-O) 中定位并提取嵌入的原生 NAPI 模块。
|
||
|
||
**实施**：
|
||
- 成功从 Bun `$bunfs` 虚拟文件系统中提取了 `computer-use-swift.node` (ARM64 424KB + x64 430KB) 和 `computer-use-input.node` (ARM64 836KB + x64 821KB)
|
||
- 同步方法（TCC 权限检查、显示枚举）正常工作
|
||
- 创建了 npm 包装包并通过 workspace 注册
|
||
|
||
**失败原因**：
|
||
- Swift 异步方法（`screenshot.captureExcluding`）的 continuation 永远不会 resume
|
||
- 根因：提取的 .node 文件是针对 Claude Code 内置的 Bun 运行时编译的，与用户系统的 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](https://github.com/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](https://github.com/wimi321/macos-computer-use-skill) | MIT | Python bridge 架构、`mac_helper.py` 运行时、`executor.ts` 适配方案。该项目从 Claude Code 工作流中提取了可复用的 TypeScript 逻辑，并用完全公开的 Python 库替代了私有原生模块 |
|
||
| [domdomegg/computer-use-mcp](https://github.com/domdomegg/computer-use-mcp) | MIT | 独立的 Computer Use MCP 服务器实现（基于 nut.js），跨平台可用。在方案调研阶段提供了参考 |
|
||
| [paoloanzn/free-code](https://github.com/paoloanzn/free-code) | - | Feature flag 系统分析和构建系统参考 |
|
||
| [oboard/claude-code-rev](https://github.com/oboard/claude-code-rev) | - | 泄露源码的早期恢复工作，提供了 stub 包的参考实现 |
|
||
|
||
### 底层依赖
|
||
|
||
| 库 | 平台 | 用途 |
|
||
|----|------|------|
|
||
| [pyautogui](https://github.com/asweigart/pyautogui) | 跨平台 | 鼠标和键盘控制 |
|
||
| [mss](https://github.com/BoboTiG/python-mss) | 跨平台 | 屏幕截图 |
|
||
| [Pillow](https://github.com/python-pillow/Pillow) | 跨平台 | 图像处理和压缩 |
|
||
| [pyobjc](https://github.com/ronaldoussoren/pyobjc) | macOS | Cocoa/Quartz 框架绑定（应用管理、显示枚举） |
|
||
| [pywin32](https://github.com/mhammond/pywin32) | Windows | Win32 API 绑定（窗口管理） |
|
||
| [psutil](https://github.com/giampaolo/psutil) | Windows | 进程管理（应用列表、进程操作） |
|
||
| [pyperclip](https://github.com/asweigart/pyperclip) | Windows | 剪贴板操作 |
|
||
| [screeninfo](https://github.com/rr-/screeninfo) | Windows | 显示器信息（多屏支持） |
|