vault backup: 2026-06-09 23:15:17

2026-06-09 23:15:17 +08:00
parent 31fd89aafe
commit e92c0327d9
111 changed files with 7276 additions and 8846 deletions
@@ -1,9 +1,21 @@
+---
+tags: [computer-use, 跨平台, macos, windows, linux, 屏幕操控]
+create time: 2026-06-09 22:30
+---
+
 # Computer Use — macOS / Windows / Linux 跨平台实施计划

-更新时间：2026-04-03
-参考项目：`E:\源码\claude-code-source-main\claude-code-source-main`
+## 概述

-## 1. 现状
+Computer Use 是 Claude Code 的屏幕操控能力，包括截图、键鼠模拟、应用管理。本文档记录从 macOS 单平台扩展到三平台（macOS + Windows + Linux）的完整实施计划、阻塞点分析和验证矩阵。
+
+> [!info]
+> 更新时间：2026-04-03
+> 参考项目：`E:\源码\claude-code-source-main\claude-code-source-main`
+
+## 正文
+
+### 1. 现状

 参考项目的 Computer Use **仅支持 macOS**——从入口到底层全部写死 darwin。我们的项目在 Phase 1-3 中已经完成了：

@@ -13,22 +25,22 @@
 - ✅ `CHICAGO_MCP` 编译开关已开
 - ✅ `src/` 层 macOS 硬编码已移除（Phase 2 已完成）

-## 2. 阻塞点全景
+### 2. 阻塞点全景

-### 2.1 入口层
+#### 2.1 入口层

 | # | 文件:行号 | 阻塞代码 | 影响 |
 |---|----------|---------|------|
 | 1 | `src/main.tsx:2366` | `feature("CHICAGO_MCP")` 门控 | CU 初始化入口 |

-### 2.2 加载层
+#### 2.2 加载层

 | # | 文件:行号 | 阻塞代码 | 影响 |
 |---|----------|---------|------|
 | 2 | `src/utils/computerUse/swiftLoader.ts` | macOS-only loader（已改为仅 darwin 加载） | 非 darwin 使用 platforms/ 替代 |
 | 3 | `src/utils/computerUse/executor.ts:302` | `process.platform !== 'darwin'` → cross-platform executor | 非 darwin 走跨平台路径 |

-### 2.3 macOS 特有依赖
+#### 2.3 macOS 特有依赖

 | # | 文件:行号 | 依赖 | macOS 实现 | 需要替代方案 |
 |---|----------|------|-----------|------------|
@@ -39,16 +51,16 @@
 | 8 | `common.ts:55-58` | 平台标识 | 动态获取 | 已改为 `process.platform` 分发 |
 | 9 | `executor.ts:232` | 粘贴快捷键 | `command`/`ctrl` 分发 | 已按平台分发粘贴快捷键 |

-### 2.4 缺失的 Linux 后端
+#### 2.4 缺失的 Linux 后端

 | 包 | macOS | Windows | Linux |
 |---|-------|---------|-------|
 | `computer-use-input/backends/` | ✅ darwin.ts | ✅ win32.ts | ❌ 需新建 linux.ts |
 | `computer-use-swift/backends/` | ✅ darwin.ts | ✅ win32.ts | ❌ 需新建 linux.ts |

-## 3. 每个平台的能力依赖
+### 3. 每个平台的能力依赖

-### 3.1 computer-use-input（键鼠）
+#### 3.1 computer-use-input（键鼠）

 | 功能 | macOS | Windows | Linux |
 |------|-------|---------|-------|
@@ -61,7 +73,7 @@
 | 前台应用 | System Events osascript | GetForegroundWindow P/Invoke | xdotool getactivewindow + /proc |
 | 工具依赖 | osascript（内置） | powershell（内置） | xdotool（需安装） |

-### 3.2 computer-use-swift（截图 + 应用管理）
+#### 3.2 computer-use-swift（截图 + 应用管理）

 | 功能 | macOS | Windows | Linux |
 |------|-------|---------|-------|
@@ -73,7 +85,7 @@
 | 隐藏/显示 | System Events visibility | ShowWindow/SetForegroundWindow | wmctrl -c / xdotool |
 | 工具依赖 | screencapture + osascript | powershell | xdotool + scrot/grim + wmctrl |

-### 3.3 executor 层
+#### 3.3 executor 层

 | 功能 | macOS | Windows | Linux |
 |------|-------|---------|-------|
@@ -85,18 +97,19 @@
 | 终端检测 | __CFBundleIdentifier | WT_SESSION / TERM_PROGRAM | TERM_PROGRAM |
 | 系统权限 | TCC check | 直接 granted | 检查 xdotool 安装 |

-## 4. 执行步骤
+### 4. 执行步骤

-### Phase 1：已完成 ✅
+#### Phase 1：已完成 ✅

 - [x] `@ant/computer-use-mcp` stub → 完整实现
 - [x] `@ant/computer-use-input` dispatcher + darwin/win32 backends
 - [x] `@ant/computer-use-swift` dispatcher + darwin/win32 backends
 - [x] `CHICAGO_MCP` 编译开关

-### Phase 2：移除 6 处 macOS 硬编码（解锁 macOS + Windows）
+#### Phase 2：移除 6 处 macOS 硬编码（解锁 macOS + Windows）

-**改动原则：macOS 代码路径不变，只在每处 darwin 守卫后加 win32/linux 分支。**
+> [!tip]
+> 改动原则：macOS 代码路径不变，只在每处 darwin 守卫后加 win32/linux 分支。

 | 步骤 | 文件 | 改动 |
 |------|------|------|
@@ -114,7 +127,7 @@
 | 2.12 | `src/utils/computerUse/gates.ts:55` | 已更新（需验证 enabled 默认值） |
 | 2.13 | `src/utils/computerUse/gates.ts:39` | `hasRequiredSubscription()` 已更新 |

-### Phase 3：新增 Linux 后端
+#### Phase 3：新增 Linux 后端

 | 步骤 | 文件 | 内容 |
 |------|------|------|
@@ -123,7 +136,7 @@
 | 3.3 | `packages/@ant/computer-use-input/src/index.ts` | dispatcher 加 `case 'linux'` |
 | 3.4 | `packages/@ant/computer-use-swift/src/index.ts` | dispatcher 加 `case 'linux'` |

-### Phase 4：验证
+#### Phase 4：验证

 | 测试项 | macOS | Windows | Linux |
 |--------|-------|---------|-------|
@@ -135,13 +148,13 @@
 | 前台窗口 | 验证 | ✅ 已通过 | 验证 |
 | 剪贴板 | 验证 | 验证 | 验证 |

-## 5. 文件改动总览
+### 5. 文件改动总览

-### 不动的文件（14 个）
+#### 不动的文件（14 个）

 `cleanup.ts`、`computerUseLock.ts`、`wrapper.tsx`、`toolRendering.tsx`、`mcpServer.ts`、`setup.ts`、`appNames.ts`、`inputLoader.ts`、`src/services/mcp/client.ts`、`@ant/computer-use-mcp/src/*`（Phase 1 已完成）、`backends/darwin.ts`（两个包都不动）

-### 改 src/ 的文件（8 个）
+#### 改 src/ 的文件（8 个）

 | 文件 | 改动量 | 风险 |
 |------|--------|------|
@@ -154,14 +167,14 @@
 | `common.ts` | 3 行 | 低 |
 | `gates.ts` | 3 行 | 低 |

-### 新增文件（2 个）
+#### 新增文件（2 个）

 | 文件 | 行数估算 |
 |------|---------|
 | `packages/@ant/computer-use-input/src/backends/linux.ts` | ~150 行 |
 | `packages/@ant/computer-use-swift/src/backends/linux.ts` | ~200 行 |

-## 6. Linux 依赖工具
+### 6. Linux 依赖工具

 | 工具 | 用途 | 安装命令（Ubuntu） |
 |------|------|-------------------|
@@ -171,27 +184,40 @@
 | `xclip` | 剪贴板 | `sudo apt install xclip` |
 | `wmctrl` | 窗口列表/切换 | `sudo apt install wmctrl` |

-Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替代 scrot）、`wl-clipboard`（替代 xclip）。初期可先只支持 X11，Wayland 标记为 todo。
+> [!warning]
+> Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替代 scrot）、`wl-clipboard`（替代 xclip）。初期可先只支持 X11，Wayland 标记为 todo。

-## 7. 执行顺序建议
+### 7. 执行顺序建议

-```
-Phase 2（解锁 macOS + Windows）
-  ├── 2.1-2.3  移除 3 处硬编码 throw/skip
-  ├── 2.4-2.5  剪贴板 + 粘贴快捷键平台分发
-  ├── 2.6      swiftLoader → 直接实例化
-  ├── 2.7-2.9  drainRunLoop / escHotkey / permissions 平台分支
-  ├── 2.10-2.11 common.ts 平台标识动态化
-  ├── 2.12-2.13 gates.ts 默认值
-  └── 验证 Windows
-
-Phase 3（Linux 后端）
-  ├── 3.1  input/backends/linux.ts
-  ├── 3.2  swift/backends/linux.ts
-  ├── 3.3-3.4  dispatcher 加 linux case
-  └── 验证 Linux
-
-Phase 4（集成验证 + PR）
+```mermaid
+graph TD
+    A["Phase 2: 解锁 macOS + Windows"] --> B["2.1-2.3: 移除3处硬编码"]
+    A --> C["2.4-2.5: 剪贴板+粘贴快捷键平台分发"]
+    A --> D["2.6: swiftLoader → 直接实例化"]
+    A --> E["2.7-2.9: drainRunLoop/escHotkey/permissions 平台分支"]
+    A --> F["2.10-2.11: common.ts 平台标识动态化"]
+    A --> G["2.12-2.13: gates.ts 默认值"]
+    A --> H["验证 Windows"]
+    B --> I["Phase 3: Linux 后端"]
+    C --> I
+    D --> I
+    E --> I
+    F --> I
+    G --> I
+    H --> I
+    I --> J["3.1: input/backends/linux.ts"]
+    I --> K["3.2: swift/backends/linux.ts"]
+    I --> L["3.3-3.4: dispatcher 加 linux case"]
+    J --> M["Phase 4: 集成验证 + PR"]
+    K --> M
+    L --> M
 ```

 每个 Phase 可独立验证、独立提交。Phase 2 完成后 macOS + Windows 可用，Phase 3 完成后三平台全部可用。
+
+## 关联笔记
+
+- [[computer-use-architecture-v2]]
+- [[computer-use-windows-enhancement]]
+- [[computer-use-tools-reference]]
+- [[computer-use-mcp-test-report]]