mirror of
https://github.com/NanmiCoder/cc-haha
synced 2026-07-18 13:23:33 +08:00
cf55c55d00
- Add Computer Use architecture deep dive documentation (CN/EN) with 4 generated diagrams (architecture, security gates, Python Bridge, patch environment comparison) - Move Computer Use section below Skills in sidebar and README - Fix 153 broken anchor links across 18 documentation files: - CN docs: add missing `、` after Chinese numeral prefixes - EN docs: add missing `_` prefix for number-starting heading IDs - Fix em-dash and special character encoding in anchor hrefs
608 lines
26 KiB
Markdown
608 lines
26 KiB
Markdown
# Computer Use 架构深度解析
|
||
|
||
> 深入解析 Computer Use 功能的底层实现：从 MCP 工具定义到 Python Bridge，从 9 层安全关卡到灰度控制绕过。
|
||
|
||
<p align="center">
|
||
<a href="#一、补丁环境总览">补丁环境</a> ·
|
||
<a href="#二、分层架构">分层架构</a> ·
|
||
<a href="#三、mcp-工具层">MCP 工具层</a> ·
|
||
<a href="#四、安全关卡体系">安全关卡</a> ·
|
||
<a href="#五、python-bridge-机制">Python Bridge</a> ·
|
||
<a href="#六、截图-分析-操作闭环">交互闭环</a> ·
|
||
<a href="#七、关键源文件索引">源文件索引</a>
|
||
</p>
|
||
|
||
|
||
|
||
---
|
||
|
||
## 一、补丁环境总览
|
||
|
||
Claude Code 原版的 Computer Use 功能（内部代号 **Chicago**）依赖三个不可公开获取的组件：
|
||
|
||
| 组件 | 作用 | 获取方式 |
|
||
|------|------|----------|
|
||
| `@ant/computer-use-swift` | 屏幕截图、显示器枚举 | Anthropic 私有 npm 包 |
|
||
| `@ant/computer-use-input` | 鼠标/键盘模拟 | Anthropic 私有 npm 包 |
|
||
| GrowthBook 远程配置 | 灰度控制、功能开关 | Anthropic 内部服务 |
|
||
|
||
我们的方案是：**保留原始 MCP 工具定义和安全机制不变，仅替换底层执行层和灰度控制**。
|
||
|
||
|
||
|
||
### 我们做了什么
|
||
|
||
```
|
||
原始 Claude Code Claude Code Haha (补丁版)
|
||
───────────────── ─────────────────────────
|
||
@ant/computer-use-swift ──替换为──→ Python Bridge (mac_helper.py)
|
||
@ant/computer-use-input ──替换为──→ pyautogui + pyobjc
|
||
GrowthBook 灰度控制 ──绕过──→ gates.ts 硬编码 return true
|
||
订阅检查 (Max/Pro) ──绕过──→ getChicagoEnabled() = true
|
||
编译宏 CHICAGO_MCP ──替换为──→ true
|
||
isDefaultDisabledBuiltin ──修改──→ 返回 false
|
||
```
|
||
|
||
### 我们没有改什么
|
||
|
||
- **MCP 工具定义**（24 个工具的 schema 和参数校验）
|
||
- **9 层安全关卡**（TCC 权限、应用白名单、权限等级、像素验证等）
|
||
- **应用分类系统**（191 个 bundle ID 的分类和权限映射）
|
||
- **会话上下文管理**（全局锁、截图缓存、状态同步）
|
||
- **键盘快捷键阻止列表**（系统级危险操作拦截）
|
||
|
||
### 灰度绕过细节
|
||
|
||
原始代码通过三层门控限制 Computer Use 的访问：
|
||
|
||
```typescript
|
||
// 原始代码（简化）
|
||
function getChicagoEnabled(): boolean {
|
||
// 层1：GrowthBook 远程配置
|
||
const config = getDynamicConfig('tengu_malort_pedway')
|
||
// 层2：订阅检查
|
||
const hasSubscription = hasRequiredSubscription() // Max/Pro
|
||
// 层3：编译时宏
|
||
return feature('CHICAGO_MCP') && config.enabled && hasSubscription
|
||
}
|
||
```
|
||
|
||
我们的处理：
|
||
|
||
```typescript
|
||
// gates.ts — 我们的修改
|
||
export function getChicagoEnabled(): boolean {
|
||
return true // ← 三层门控全部绕过
|
||
}
|
||
```
|
||
|
||
**注意**：子开关（pixelValidation、mouseAnimation 等）仍然保留原始逻辑，可通过配置控制。
|
||
|
||
---
|
||
|
||
## 二、分层架构
|
||
|
||
Computer Use 采用 **6 层架构**，每层职责清晰、边界明确：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Layer 1 — MCP 工具接口层 │
|
||
│ tools.ts: 24 个工具 schema + 参数校验 │
|
||
│ buildComputerUseTools() → MCP Tool Definition │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ Layer 2 — 工具调度与安全控制层 │
|
||
│ toolCalls.ts: handleToolCall() + 9 层安全关卡 │
|
||
│ deniedApps.ts: 191 个应用分类 + 权限等级 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ Layer 3 — MCP 服务器绑定层 │
|
||
│ mcpServer.ts: 会话上下文 + 全局锁 + 截图缓存 │
|
||
│ bindSessionContext() → per-call overrides │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ Layer 4 — CLI 集成层 │
|
||
│ wrapper.tsx: 权限对话框 + 状态读写 │
|
||
│ setup.ts: MCP 配置初始化 │
|
||
│ gates.ts: 灰度控制（已绕过） │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ Layer 5 — Python Bridge 进程通信层 [补丁] │
|
||
│ pythonBridge.ts: venv 管理 + JSON RPC + 错误处理 │
|
||
│ callPythonHelper<T>(command, payload) → T │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ Layer 6 — Python 运行时执行层 [补丁] │
|
||
│ mac_helper.py: pyautogui + mss + pyobjc │
|
||
│ 660 行 Python 实现所有系统交互 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**标 `[补丁]` 的层**是我们替换/新增的代码，**其余层完全保留**原始 Claude Code 的逻辑。
|
||
|
||
### 为什么这样分层？
|
||
|
||
| 层 | 来源 | 可复用性 |
|
||
|----|------|----------|
|
||
| Layer 1-2 | `vendor/computer-use-mcp/` | 平台无关，可用于 Electron、Web 等宿主 |
|
||
| Layer 3 | `vendor/computer-use-mcp/` | 平台无关，MCP 标准协议 |
|
||
| Layer 4 | `utils/computerUse/` | CLI 专用，绑定应用状态 |
|
||
| Layer 5-6 | `utils/computerUse/` + `runtime/` | macOS 专用，Python 实现 |
|
||
|
||
---
|
||
|
||
## 三、MCP 工具层
|
||
|
||
### 24 个工具一览
|
||
|
||
Computer Use 通过 MCP（Model Context Protocol）暴露 24 个工具给模型：
|
||
|
||
| 类别 | 工具 | 权限等级 |
|
||
|------|------|----------|
|
||
| **权限** | `request_access`, `list_granted_applications` | 无需权限 |
|
||
| **截屏** | `screenshot`, `zoom` | read |
|
||
| **鼠标点击** | `left_click`, `double_click`, `triple_click` | click |
|
||
| **鼠标高级** | `right_click`, `middle_click`, `left_click_drag` | full |
|
||
| **鼠标移动** | `mouse_move`, `cursor_position`, `scroll` | click |
|
||
| **鼠标底层** | `left_mouse_down`, `left_mouse_up` | full |
|
||
| **键盘** | `type`, `key`, `hold_key` | full |
|
||
| **应用** | `open_application`, `switch_display` | full |
|
||
| **剪贴板** | `read_clipboard`, `write_clipboard` | full |
|
||
| **批量** | `computer_batch` | 继承子操作 |
|
||
| **等待** | `wait` | 无需权限 |
|
||
|
||
### 坐标系统
|
||
|
||
模型通过两种坐标模式与屏幕交互：
|
||
|
||
```
|
||
pixels 模式（默认）：
|
||
模型看到截图尺寸 (1176 x 784)
|
||
模型输出坐标 [588, 392]
|
||
scaleCoord() 转换：
|
||
x_logical = (588 * displayWidth / 1176) + originX
|
||
y_logical = (392 * displayHeight / 784) + originY
|
||
|
||
normalized_0_100 模式：
|
||
模型输出坐标 [50, 50]（百分比）
|
||
scaleCoord() 转换：
|
||
x_logical = (50 / 100) * displayWidth + originX
|
||
y_logical = (50 / 100) * displayHeight + originY
|
||
```
|
||
|
||
截图尺寸经过 `imageResize.ts` 计算，确保：
|
||
- 长边 ≤ 1568 像素
|
||
- Token 预算 ≤ 1568（视觉编码器 28px/token）
|
||
- 保持宽高比
|
||
|
||
### 应用分类系统
|
||
|
||
`deniedApps.ts` 对 191 个应用进行精细分类：
|
||
|
||
**浏览器类**（55 个 bundle ID）→ 权限等级 `read`
|
||
```
|
||
Safari, Chrome, Firefox, Arc, Edge, Opera, Brave, Vivaldi...
|
||
理由：浏览器操作应使用 Chrome MCP，而非盲点击
|
||
```
|
||
|
||
**终端类**（102 个 bundle ID）→ 权限等级 `click`
|
||
```
|
||
Terminal, iTerm2, VS Code, Cursor, JetBrains 全家桶, Xcode...
|
||
理由：终端操作应使用 Bash Tool，限制为只能点击不能输入
|
||
```
|
||
|
||
**交易类**（34 个 bundle ID）→ 权限等级 `read`
|
||
```
|
||
Webull, Fidelity, Interactive Brokers, Binance, Kraken...
|
||
理由：金融操作风险极高，仅允许截图查看
|
||
```
|
||
|
||
**完全禁止**（策略拒绝名单）：
|
||
```
|
||
Netflix, Spotify, Apple Music, Kindle...
|
||
理由：版权合规，不进入权限对话框直接拒绝
|
||
```
|
||
|
||
---
|
||
|
||
## 四、安全关卡体系
|
||
|
||
每个输入操作（点击、键盘、拖拽）在执行前需通过 **9 层安全关卡**：
|
||
|
||
|
||
|
||
### 关卡详解
|
||
|
||
#### Gate 1：Kill Switch
|
||
```typescript
|
||
if (adapter.isDisabled()) return errorResult("Computer Use is disabled")
|
||
```
|
||
读取 `getChicagoEnabled()` — 在补丁版中永远返回 `true`。
|
||
|
||
#### Gate 2：TCC 权限检查
|
||
```typescript
|
||
await adapter.ensureOsPermissions()
|
||
// → Python: check_permissions
|
||
// → Accessibility: osascript "tell System Events..."
|
||
// → Screen Recording: CGDisplayCaptureDisplay()
|
||
```
|
||
如果缺少 macOS Accessibility 或 Screen Recording 权限，直接报错。
|
||
|
||
#### Gate 3：全局互斥锁
|
||
```typescript
|
||
await tryAcquireComputerUseLock(sessionId)
|
||
// 文件锁: ~/.claude/computer-use.lock
|
||
// JSON: { sessionId, pid, acquiredAt }
|
||
```
|
||
确保同一时间只有一个 Claude 会话可以控制电脑。支持 stale PID 恢复。
|
||
|
||
#### Gate 4：隐藏非白名单应用
|
||
```typescript
|
||
await executor.prepareForAction(allowlistBundleIds)
|
||
// 隐藏所有不在白名单中的应用窗口
|
||
// 确保截图中只出现授权应用
|
||
```
|
||
|
||
#### Gate 5：前台应用检查
|
||
```typescript
|
||
const frontmost = await executor.getFrontmostApp()
|
||
if (!allowlist.includes(frontmost.bundleId)) {
|
||
return errorResult("Application not authorized")
|
||
}
|
||
```
|
||
即使通过了白名单，还需确认当前前台应用是已授权的。
|
||
|
||
#### Gate 6：权限等级检查
|
||
|
||
三级权限模型：
|
||
|
||
| Tier | 允许的操作 | 禁止的操作 |
|
||
|------|-----------|-----------|
|
||
| `read` | 截图查看 | 任何输入操作 |
|
||
| `click` | 左键点击、滚动 | 右键、拖拽、键盘输入 |
|
||
| `full` | 全部操作 | 无限制 |
|
||
|
||
```typescript
|
||
function tierSatisfies(tier: CuAppPermTier, required: ActionKind): boolean {
|
||
const order = { read: 0, click: 1, full: 2 }
|
||
return order[tier] >= order[required]
|
||
}
|
||
```
|
||
|
||
**反绕过机制**：如果权限不足，响应中会附加 `TIER_ANTI_SUBVERSION` 提示，防止模型通过 AppleScript 或 System Events 绕过限制。
|
||
|
||
#### Gate 7：剪贴板防护
|
||
|
||
**威胁模型**：
|
||
```
|
||
1. Agent 调用 write_clipboard("rm -rf /")
|
||
2. 切换到 Terminal（click-tier 允许点击）
|
||
3. 模型点击 Terminal 的粘贴按钮
|
||
4. 恶意命令被执行
|
||
```
|
||
|
||
**防护机制**：
|
||
```
|
||
当 click-tier 应用成为前台时：
|
||
→ 保存当前剪贴板内容（stash）
|
||
→ 清空剪贴板
|
||
→ 每次操作后再次清空
|
||
|
||
当非 click-tier 应用成为前台时：
|
||
→ 恢复原始剪贴板内容
|
||
```
|
||
|
||
#### Gate 8：像素验证（Staleness Guard）
|
||
|
||
```
|
||
上次截图 当前实际屏幕
|
||
┌────────────┐ ┌────────────┐
|
||
│ 按钮A │ │ 对话框 │ ← UI 已变化
|
||
│ [756,342] │ │ 确认? │
|
||
└────────────┘ └────────────┘
|
||
|
||
像素验证：在 [756,342] 取 9×9 网格
|
||
→ 对比上次截图 vs 实时截图的像素
|
||
→ 不同 → 拒绝点击 + 提示重新截图
|
||
→ 相同 → 允许点击
|
||
```
|
||
|
||
**注意**：补丁版中 `pixelValidation` 默认关闭（`hostAdapter.cropRawPatch()` 返回 null）。
|
||
|
||
#### Gate 9：系统快捷键拦截
|
||
|
||
`keyBlocklist.ts` 阻止危险快捷键：
|
||
|
||
| 快捷键 | 危险操作 |
|
||
|--------|---------|
|
||
| `⌘Q` | 退出应用 |
|
||
| `⇧⌘Q` | 登出系统 |
|
||
| `⌥⌘⎋` | 强制退出对话框 |
|
||
| `⌘Tab` | 应用切换器 |
|
||
| `⌘Space` | Spotlight |
|
||
| `⌃⌘Q` | 锁屏 |
|
||
|
||
---
|
||
|
||
## 五、Python Bridge 机制
|
||
|
||
|
||
|
||
### 架构设计
|
||
|
||
原始 Claude Code 使用编译好的 Swift 原生模块（.node NAPI 插件）直接调用 macOS API。我们用 **Python 子进程 + JSON RPC** 替代了这一层：
|
||
|
||
```
|
||
TypeScript (Bun 运行时) Python (venv)
|
||
┌────────────────────┐ ┌────────────────────┐
|
||
│ executor.ts │ │ mac_helper.py │
|
||
│ │ execFile() │ │
|
||
│ callPythonHelper │ ──────────────→ │ main() │
|
||
│ ('click', │ command + │ ├─ 解析 argv │
|
||
│ {x:756,y:342}) │ --payload JSON │ ├─ dispatch() │
|
||
│ │ │ └─ click() │
|
||
│ ← JSON.parse ──── │ ←────────────── │ pyautogui │
|
||
│ {ok:true, │ stdout JSON │ │
|
||
│ result:true} │ │ json_output(...) │
|
||
└────────────────────┘ └────────────────────┘
|
||
```
|
||
|
||
### 启动引导流程
|
||
|
||
首次调用 `callPythonHelper()` 时自动完成环境初始化：
|
||
|
||
```
|
||
ensureBootstrapped()
|
||
│
|
||
├─ 检查 .runtime/venv/bin/python3 是否存在
|
||
│ └─ 不存在 → python3 -m venv .runtime/venv/
|
||
│
|
||
├─ 检查 pip 是否可用
|
||
│ └─ 不可用 → python3 -m ensurepip --upgrade
|
||
│
|
||
├─ 计算 runtime/requirements.txt 的 SHA256
|
||
│ └─ 与 .runtime/requirements.sha256 对比
|
||
│ └─ 不同 → pip install -r requirements.txt
|
||
│ 写入新的 SHA256 哈希
|
||
│ └─ 相同 → 跳过安装
|
||
│
|
||
└─ 就绪，返回 venv Python 路径
|
||
```
|
||
|
||
**依赖清单**（`runtime/requirements.txt`）：
|
||
|
||
| 库 | 用途 |
|
||
|----|------|
|
||
| `mss` | 高性能屏幕截图 |
|
||
| `Pillow` | JPEG 编码和图像处理 |
|
||
| `pyautogui` | 鼠标点击、键盘输入 |
|
||
| `pyobjc-core` | macOS Objective-C 桥接 |
|
||
| `pyobjc-framework-Cocoa` | NSWorkspace（应用管理）、NSPasteboard（剪贴板） |
|
||
| `pyobjc-framework-Quartz` | CGDisplay（显示器）、CGWindow（窗口列表） |
|
||
|
||
### 命令映射表
|
||
|
||
`mac_helper.py`（660 行）实现了以下命令：
|
||
|
||
| 命令 | Python 实现 | 返回值 |
|
||
|------|------------|--------|
|
||
| `screenshot` | `mss.grab()` + `PIL.Image` JPEG 编码 | `{base64, width, height, displayWidth, displayHeight}` |
|
||
| `zoom` | `mss.grab(region)` 区域截图 | `{base64, width, height}` |
|
||
| `click` | `pyautogui.moveTo()` + `pyautogui.click()` | `true` |
|
||
| `key` | `pyautogui.hotkey()` / `pyautogui.press()` | `true` |
|
||
| `type` | `pyautogui.write(interval=0.008)` | `true` |
|
||
| `drag` | `pyautogui.dragTo(duration=0.2)` | `true` |
|
||
| `scroll` | `pyautogui.scroll()` / `pyautogui.hscroll()` | `true` |
|
||
| `hold_key` | `pyautogui.keyDown()` + `sleep` + `pyautogui.keyUp()` | `true` |
|
||
| `frontmost_app` | `NSWorkspace.frontmostApplication()` | `{bundleId, displayName}` |
|
||
| `list_displays` | `CGGetActiveDisplayList()` + `CGDisplayBounds()` | `[DisplayGeometry...]` |
|
||
| `find_window_displays` | `CGWindowListCopyWindowInfo()` + 交集计算 | `[{bundleId, displayIds}...]` |
|
||
| `list_installed_apps` | 递归扫描 `/Applications` + `plistlib` | `[InstalledApp...]` |
|
||
| `list_running_apps` | `NSWorkspace.runningApplications()` | `[RunningApp...]` |
|
||
| `open_app` | `NSWorkspace.launchApplicationAtURL_options_` | `void` |
|
||
| `read_clipboard` | `NSPasteboard.stringForType_()` | `string` |
|
||
| `write_clipboard` | `NSPasteboard.setString_forType_()` | `void` |
|
||
| `check_permissions` | `osascript` + `CGDisplayCaptureDisplay` | `{accessibility, screenRecording}` |
|
||
|
||
### 错误处理
|
||
|
||
```python
|
||
# mac_helper.py 的统一错误处理
|
||
def main():
|
||
try:
|
||
result = dispatch(command, payload)
|
||
json_output({"ok": True, "result": result})
|
||
except Exception as e:
|
||
error_output({"ok": False, "error": {"message": str(e)}})
|
||
```
|
||
|
||
TypeScript 端：
|
||
```typescript
|
||
// pythonBridge.ts
|
||
const parsed = JSON.parse(stdout)
|
||
if (!parsed.ok) {
|
||
throw new Error(parsed.error.message) // → MCP tool error
|
||
}
|
||
return parsed.result
|
||
```
|
||
|
||
---
|
||
|
||
## 六、截图-分析-操作闭环
|
||
|
||
一个完整的 Computer Use 交互由多个 **截图-分析-操作** 循环组成：
|
||
|
||
### 典型交互流程
|
||
|
||
```
|
||
用户: "帮我打开网易云音乐，搜索一首歌"
|
||
|
||
┌─ 循环 1：发现并打开应用 ─────────────────────────────────┐
|
||
│ │
|
||
│ Step 1: request_access │
|
||
│ → 弹出权限对话框，用户授权允许操作的应用 │
|
||
│ → 设置 allowedApps, grantFlags │
|
||
│ │
|
||
│ Step 2: screenshot │
|
||
│ → 截取全屏 → JPEG 编码 → base64 │
|
||
│ → 缓存截图尺寸 (lastScreenshotDims) │
|
||
│ → 返回给模型 │
|
||
│ │
|
||
│ Step 3: 模型分析截图 │
|
||
│ → "桌面上没有网易云音乐，需要打开它" │
|
||
│ → 决定调用 open_application │
|
||
│ │
|
||
│ Step 4: open_application("com.netease.163music") │
|
||
│ → Gate 1-9 全部通过 │
|
||
│ → Python: NSWorkspace.launchApplicationAtURL_() │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────┘
|
||
|
||
┌─ 循环 2：定位搜索框 ────────────────────────────────────┐
|
||
│ │
|
||
│ Step 5: screenshot │
|
||
│ → 截取全屏（网易云已打开） │
|
||
│ → 更新 lastScreenshotDims │
|
||
│ │
|
||
│ Step 6: 模型分析截图 │
|
||
│ → 视觉识别搜索框位置 → (756, 342) │
|
||
│ → 决定点击搜索框 │
|
||
│ │
|
||
│ Step 7: left_click({coordinate: [756, 342]}) │
|
||
│ → Gate 4: 隐藏非白名单应用 │
|
||
│ → Gate 5: 前台是网易云 ✓ │
|
||
│ → Gate 6: tier=full ≥ click ✓ │
|
||
│ → Gate 7: 非 click-tier 应用，跳过 │
|
||
│ → scaleCoord(756, 342) 转换为屏幕坐标 │
|
||
│ → Python: pyautogui.click(x_logical, y_logical) │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────┘
|
||
|
||
┌─ 循环 3：输入搜索词 ────────────────────────────────────┐
|
||
│ │
|
||
│ Step 8: type({text: "喜欢你"}) │
|
||
│ → Gate 6: tier=full ≥ keyboard ✓ │
|
||
│ → Python: pyautogui.write("喜欢你", interval=0.008) │
|
||
│ │
|
||
│ Step 9: screenshot │
|
||
│ → 确认搜索结果已出现 │
|
||
│ → 模型分析："搜索结果列表中第一个就是目标歌曲" │
|
||
│ │
|
||
│ Step 10: left_click({coordinate: [...]}) │
|
||
│ → 点击目标歌曲 │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 坐标转换的关键
|
||
|
||
**模型看到的**和**屏幕实际的**是不同的坐标空间：
|
||
|
||
```
|
||
原始屏幕 (2560 x 1600, Retina 2x)
|
||
├─ 逻辑尺寸: 1280 x 800
|
||
└─ 物理像素: 2560 x 1600
|
||
|
||
imageResize 计算后：
|
||
├─ 缩放后尺寸: 1176 x 735 (≤1568px 预算)
|
||
└─ 这就是模型"看到"的截图尺寸
|
||
|
||
模型输出坐标: [588, 368]（图像空间的像素位置）
|
||
|
||
scaleCoord 转换:
|
||
x_logical = (588 / 1176) * 1280 + originX = 640 + 0 = 640
|
||
y_logical = (368 / 735) * 800 + originY = 400 + 0 = 400
|
||
|
||
Python 执行:
|
||
pyautogui.moveTo(640, 400) ← 逻辑坐标（macOS 自动处理 Retina）
|
||
```
|
||
|
||
### 截图缓存与状态同步
|
||
|
||
```
|
||
bindSessionContext 闭包
|
||
│
|
||
├─ lastScreenshot (内存)
|
||
│ ├─ base64: JPEG 数据（用于 pixel validation）
|
||
│ ├─ width/height: 模型看到的尺寸
|
||
│ └─ displayWidth/displayHeight/originX/originY: 显示器几何
|
||
│
|
||
└─ AppState.computerUseMcpState (持久化)
|
||
├─ allowedApps: AppGrant[] — 已授权应用列表
|
||
├─ grantFlags: {...} — 剪贴板/系统快捷键权限
|
||
├─ selectedDisplayId?: number — 选定的显示器
|
||
├─ lastScreenshotDims?: {...} — 截图几何（跨重启恢复）
|
||
└─ hiddenDuringTurn?: Set<string> — 本轮隐藏的应用
|
||
```
|
||
|
||
---
|
||
|
||
## 七、关键源文件索引
|
||
|
||
### vendor/computer-use-mcp/（原始代码层）
|
||
|
||
| 文件 | 行数 | 职责 |
|
||
|------|------|------|
|
||
| `types.ts` | 622 | 权限模型、会话上下文、全部类型定义 |
|
||
| `tools.ts` | 707 | 24 个 MCP 工具的 schema 和参数校验 |
|
||
| `toolCalls.ts` | 1600+ | **核心**：工具派发、9 层安全关卡、权限流程 |
|
||
| `deniedApps.ts` | 554 | 191 个应用的分类（browser/terminal/trading）和权限映射 |
|
||
| `sentinelApps.ts` | 44 | 敏感应用预警标签（shell/filesystem/system_settings） |
|
||
| `mcpServer.ts` | 314 | MCP 服务器工厂、会话上下文绑定、全局锁 |
|
||
| `pixelCompare.ts` | 172 | 点击目标像素验证（staleness guard） |
|
||
| `imageResize.ts` | 109 | 截图尺寸计算（API 图像转码算法） |
|
||
| `keyBlocklist.ts` | 154 | 系统快捷键拦截（⌘Q、⌘Tab 等） |
|
||
| `executor.ts` | 101 | ComputerExecutor 接口定义 |
|
||
| `subGates.ts` | 20 | 灰度子开关预设组合 |
|
||
|
||
### utils/computerUse/（CLI 适配层）
|
||
|
||
| 文件 | 行数 | 职责 | 补丁? |
|
||
|------|------|------|-------|
|
||
| `executor.ts` | 231 | ComputerExecutor 的 Python bridge 实现 | ✅ 重写 |
|
||
| `pythonBridge.ts` | 111 | Python 子进程管理、venv 引导、JSON RPC | ✅ 新增 |
|
||
| `hostAdapter.ts` | 54 | HostAdapter 实现（权限检查、灰度读取） | 部分修改 |
|
||
| `gates.ts` | 51 | GrowthBook 灰度控制（`getChicagoEnabled` 绕过） | ✅ 修改 |
|
||
| `wrapper.tsx` | 300+ | 会话上下文构建、权限对话框、锁管理 | 未修改 |
|
||
| `setup.ts` | 54 | MCP 配置初始化 | 未修改 |
|
||
| `computerUseLock.ts` | 216 | 全局文件锁（`~/.claude/computer-use.lock`） | 未修改 |
|
||
| `common.ts` | 62 | 常量定义（server name、bundle ID） | 未修改 |
|
||
| `cleanup.ts` | — | turn-end 清理（应用恢复、剪贴板恢复） | 未修改 |
|
||
| `toolRendering.tsx` | — | 工具结果 UI 渲染 | 未修改 |
|
||
|
||
### runtime/（Python 运行时）
|
||
|
||
| 文件 | 行数 | 职责 | 补丁? |
|
||
|------|------|------|-------|
|
||
| `mac_helper.py` | 660 | 所有系统交互的 Python 实现 | ✅ 新增 |
|
||
| `requirements.txt` | 6 | Python 依赖声明 | ✅ 新增 |
|
||
|
||
---
|
||
|
||
## 八、设计权衡
|
||
|
||
### 为什么选择 Python Bridge？
|
||
|
||
| 维度 | 原生 Swift (.node) | Python Bridge |
|
||
|------|-------------------|---------------|
|
||
| **性能** | ~0ms（进程内调用） | ~50-100ms（子进程启动） |
|
||
| **可读性** | 编译后不可读 | 660 行清晰的 Python |
|
||
| **可修改性** | 需要 Swift 编译环境 | 直接编辑 .py 文件 |
|
||
| **依赖** | 特定 Bun 版本的 NAPI | 任意 Python 3.8+ |
|
||
| **跨平台** | 仅 macOS | pyautogui/mss 天然跨平台 |
|
||
| **用户体验** | 无感知 | 无感知（模型思考时间秒级） |
|
||
|
||
**结论**：50-100ms 的额外延迟在 Computer Use 的场景下完全可以忽略——模型分析截图和决策的时间通常是 2-5 秒，用户不会注意到底层操作多了 100ms。
|
||
|
||
### 我们尝试过但放弃的方案
|
||
|
||
**方案一：提取原生 .node 模块**
|
||
- 从 Claude Code 二进制中成功提取了 `computer-use-swift.node`（ARM64 424KB）
|
||
- 同步方法正常工作，但 **Swift 异步方法的 continuation 永远不会 resume**
|
||
- 根因：.node 文件针对 Claude Code 内置 Bun 编译，与用户 Bun 版本不兼容
|
||
|
||
**方案二：空 Stub 包**
|
||
- 代码能编译但所有操作报错——没有实际执行能力
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [Computer Use 功能指南](./computer-use.md) — 使用方式、快速开始、环境变量
|
||
- [源码修复记录](/reference/fixes) — 其他修复和补丁的详细记录
|