Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ccb.agent-aura.top/llms.txt

Use this file to discover all available pages before exploring further.

​
Computer Use — macOS / Windows / Linux 跨平台实施计划

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

​
1. 现状

参考项目的 Computer Use 仅支持 macOS——从入口到底层全部写死 darwin。我们的项目在 Phase 1-3 中已经完成了：
  • ✅ @ant/computer-use-mcp stub 替换为完整实现（12 文件）
  • ✅ @ant/computer-use-input 拆为 dispatcher + backends（darwin + win32）
  • ✅ @ant/computer-use-swift 拆为 dispatcher + backends（darwin + win32）
  • ✅ CHICAGO_MCP 编译开关已开
  • ✅ src/ 层 macOS 硬编码已移除（Phase 2 已完成）

​
2. 阻塞点全景

​
2.1 入口层

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

​
2.2 加载层

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

​
2.3 macOS 特有依赖

#文件:行号依赖macOS 实现需要替代方案
4executor.ts:72-96剪贴板pbcopy/pbpaste / PowerShell / xclipWin: PowerShell Get/Set-Clipboard；Linux: xclip/wl-copy
5drainRunLoop.tsCFRunLoop pumpcu._drainMainRunLoop()非 darwin：直接执行 fn()，不需要 pump
6escHotkey.tsESC 热键CGEventTap非 darwin：返回 false（已有 Ctrl+C fallback）
7hostAdapter.ts系统权限TCC accessibility + screenRecordingWin：直接 granted；Linux：检查 xdotool
8common.ts:55-58平台标识动态获取已改为 process.platform 分发
9executor.ts:232粘贴快捷键command/ctrl 分发已按平台分发粘贴快捷键

​
2.4 缺失的 Linux 后端

包macOSWindowsLinux
computer-use-input/backends/✅ darwin.ts✅ win32.ts❌ 需新建 linux.ts
computer-use-swift/backends/✅ darwin.ts✅ win32.ts❌ 需新建 linux.ts

​
3. 每个平台的能力依赖

​
3.1 computer-use-input（键鼠）

功能macOSWindowsLinux
鼠标移动CGEvent JXASetCursorPos P/Invokexdotool mousemove
鼠标点击CGEvent JXASendInput P/Invokexdotool click
鼠标滚轮CGEvent JXASendInput MOUSEEVENTF_WHEELxdotool scroll
键盘按键System Events osascriptkeybd_event P/Invokexdotool key
组合键System Events osascriptkeybd_event 组合xdotool key combo
文本输入System Events keystrokeSendKeys.SendWaitxdotool type
前台应用System Events osascriptGetForegroundWindow P/Invokexdotool getactivewindow + /proc
工具依赖osascript（内置）powershell（内置）xdotool（需安装）

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

功能macOSWindowsLinux
全屏截图screencaptureCopyFromScreengnome-screenshot / scrot / grim
区域截图screencapture -RCopyFromScreen(rect)gnome-screenshot -a / scrot -a / grim -g
显示器列表CGGetActiveDisplayList JXAScreen.AllScreensxrandr —query
运行中应用System Events JXAGet-Processwmctrl -l / ps
打开应用osascript activateStart-Processxdg-open / gtk-launch
隐藏/显示System Events visibilityShowWindow/SetForegroundWindowwmctrl -c / xdotool
工具依赖screencapture + osascriptpowershellxdotool + scrot/grim + wmctrl

​
3.3 executor 层

功能macOSWindowsLinux
drainRunLoopCFRunLoop pump不需要不需要
ESC 热键CGEventTap跳过（Ctrl+C fallback）跳过（Ctrl+C fallback）
剪贴板读pbpastepowershell Get-Clipboardxclip -o / wl-paste
剪贴板写pbcopypowershell Set-Clipboardxclip / wl-copy
粘贴快捷键command+vctrl+vctrl+v
终端检测__CFBundleIdentifierWT_SESSION / TERM_PROGRAMTERM_PROGRAM
系统权限TCC check直接 granted检查 xdotool 安装

​
4. 执行步骤

​
Phase 1：已完成 ✅

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

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

改动原则：macOS 代码路径不变，只在每处 darwin 守卫后加 win32/linux 分支。
步骤文件改动
2.1src/main.tsx:2366feature("CHICAGO_MCP") → 已为跨平台入口
2.2src/utils/computerUse/swiftLoader.ts已改为仅 darwin 加载，非 darwin 使用 platforms/
2.3src/utils/computerUse/executor.ts:302-309已改为 cross-platform dispatch（非 darwin → createCrossPlatformExecutor）
2.4src/utils/computerUse/executor.ts:72-96剪贴板已按平台分发：darwin→pbcopy/pbpaste，win32→PowerShell，linux→xclip
2.5src/utils/computerUse/executor.ts:232粘贴快捷键已按平台分发：darwin→command，其他→ctrl
2.6src/utils/computerUse/executor.ts:302-309非 darwin 已改为 createCrossPlatformExecutor()
2.7src/utils/computerUse/drainRunLoop.ts非 darwin 无需 pump（直接执行 fn）
2.8src/utils/computerUse/escHotkey.ts非 darwin 返回 false（已有 Ctrl+C fallback）
2.9src/utils/computerUse/hostAdapter.ts非 darwin 权限检查逻辑已实现
2.10src/utils/computerUse/common.ts:58已改为动态 process.platform 分发
2.11src/utils/computerUse/common.ts:55已改为 darwin→‘native’，其他→‘none’
2.12src/utils/computerUse/gates.ts:55已更新（需验证 enabled 默认值）
2.13src/utils/computerUse/gates.ts:39hasRequiredSubscription() 已更新

​
Phase 3：新增 Linux 后端

步骤文件内容
3.1packages/@ant/computer-use-input/src/backends/linux.tsxdotool 键鼠（mousemove/click/key/type/getactivewindow）
3.2packages/@ant/computer-use-swift/src/backends/linux.tsscrot/grim 截图 + xrandr 显示器 + wmctrl 窗口管理
3.3packages/@ant/computer-use-input/src/index.tsdispatcher 加 case 'linux'
3.4packages/@ant/computer-use-swift/src/index.tsdispatcher 加 case 'linux'

​
Phase 4：验证

测试项macOSWindowsLinux
build 成功✅验证验证
MCP 工具列表非空验证验证验证
鼠标移动验证✅ 已通过验证
截图验证✅ 已通过验证
键盘输入验证验证验证
前台窗口验证✅ 已通过验证
剪贴板验证验证验证

​
5. 文件改动总览

​
不动的文件（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 个）

文件改动量风险
main.tsx1 行低
swiftLoader.ts2 行低
executor.ts~40 行（剪贴板分发 + 平台守卫 + paste 快捷键）中
drainRunLoop.ts1 行低
escHotkey.ts3 行低
hostAdapter.ts5 行低
common.ts3 行低
gates.ts3 行低

​
新增文件（2 个）

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

​
6. Linux 依赖工具

工具用途安装命令（Ubuntu）
xdotool键鼠模拟 + 窗口管理sudo apt install xdotool
scrot 或 gnome-screenshot截图sudo apt install scrot
xrandr显示器信息通常已预装
xclip剪贴板sudo apt install xclip
wmctrl窗口列表/切换sudo apt install wmctrl
Wayland 环境需要替代工具：ydotool（替代 xdotool）、grim（替代 scrot）、wl-clipboard（替代 xclip）。初期可先只支持 X11，Wayland 标记为 todo。

​
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）
每个 Phase 可独立验证、独立提交。Phase 2 完成后 macOS + Windows 可用，Phase 3 完成后三平台全部可用。