feat: 更新 Computer Use 用户指南，添加 macOS 和 Windows 支持文档链接

2026-06-15 12:55:51 +00:00 · 2026-04-04 12:24:11 +08:00
parent ad1f90a00e
commit 765569b3cf
3 changed files with 128 additions and 128 deletions
--- a/README.md
+++ b/README.md
@@ -34,12 +34,13 @@
  - [x] 关闭自动更新;
  - [x] 添加自定义 sentry 错误上报支持 [文档](https://ccb.agent-aura.top/docs/internals/sentry-setup)
  - [x] 添加自定义 GrowthBook 支持 (GB 也是开源的, 现在你可以配置一个自定义的遥控平台) [文档](https://ccb.agent-aura.top/docs/internals/growthbook-adapter)
-  - [x] 自定义 login 模式, 大家可以用这个配置 Claude 的模型!
+  - [x] 自定义 login 模式, 大家可以用这个配置 Claude 的模型! [文档](https://ccb.agent-aura.top/docs/features/custom-platform-login)
+  - [x] Remote Control / Bridge Mode 支持 [文档](https://ccb.agent-aura.top/docs/features/bridge-mode)
  - [x] 修复搜索工具的 rg 缺失问题(需要重新 bun i)
-  - [x] OpenAI 接口兼容! /login 然后配置 OpenAI 平台即可!
-  - [x] Chrome use 支持(暂时浏览器插件要订阅权限,万恶的牢 A) 感谢 @amDosion
-  - [x] Computer use 支持 感谢 @amDosion
-  - [x] /voice 支持 @amDosion
+  - [x] OpenAI 接口兼容! /login 然后配置 OpenAI 平台即可! [文档](https://ccb.agent-aura.top/docs/plans/openai-compatibility)
+  - [x] Chrome use 支持(暂时浏览器插件要订阅权限,万恶的牢 A) 感谢 @amDosion [文档](https://ccb.agent-aura.top/docs/features/claude-in-chrome-mcp)
+  - [x] Computer use 支持 感谢 @amDosion [文档](https://ccb.agent-aura.top/docs/features/computer-use)
+  - [x] /voice 支持 @amDosion [文档](https://ccb.agent-aura.top/docs/features/voice-mode)
 - [ ] V6 大规模重构石山代码, 全面模块分包
  - [ ] V6 将会为全新分支, 届时 main 分支将会封存为历史版本

--- a/docs/features/computer-use.md
+++ b/docs/features/computer-use.md
@@ -1,142 +1,136 @@
-# Computer Use — macOS / Windows / Linux 跨平台实施计划
+# Computer Use 用户指南

-更新时间：2026-04-04
-参考项目：https://github.com/JrCx7scC/claude-code-source
+Computer Use 让 Claude 直接操控你的电脑——移动鼠标、点击、输入文字、截图，就像一个远程助手坐在你面前操作一样。

-## 1. 现状
+## 支持平台

-参考项目的 Computer Use **仅支持 macOS**——从入口到底层全部写死 darwin。我们的项目在 Phase 1-3 中已经完成了：
+| 平台 | 状态 | 额外配置 |
+|------|------|---------|
+| macOS | 可用 | 需授予辅助功能 + 屏幕录制权限 |
+| Windows | 可用 | 无需额外配置 |
+| Linux | 不可用 | 后端待开发 |

- ✅ `@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 硬编码全部移除，已支持 darwin / win32 / linux 三平台
+## 快速开始

-## 2. 用户使用方式
+1. 启动 Claude Code：

-Computer Use 由 `CHICAGO_MCP` feature flag 控制，无需额外 CLI 参数。
+   ```bash
+   bun run dev
+   ```

-> **订阅要求**：需要 Claude Pro、Max 或 Team 订阅，Computer Use 功能不向免费用户开放。
+   Computer Use 默认已开启，无需额外参数。

-### Dev 模式（默认已开启）
+2. 在对话中告诉 Claude 你想做什么，例如：
+   - "帮我打开系统设置"
+   - "截个屏看看当前桌面"
+   - "在 Finder 里点击那个文件"
+
+3. 首次操控某个应用时，会弹出权限对话框让你确认。
+
+4. 操作过程中随时按 **Esc**（macOS）或 **Ctrl+C**（Windows）中止。
+
+## 权限说明
+
+Computer Use 采用分级权限模型，保护你的安全：
+
+| 级别 | 能力 | 适用场景 |
+|------|------|---------|
+| **full** | 所有操作：鼠标点击（左/右/中键）、拖拽、键盘输入、组合键 | 系统设置、Finder 等系统应用 |
+| **click** | 仅左键点击和滚轮滚动 | IDE（VS Code、Cursor）、终端 |
+| 未授权 | 所有操作被拒绝 | 需要通过 `request_access` 申请 |
+
+IDE 类应用默认只有 click 权限，这是安全设计——防止 AI 在你的终端或编辑器中执行危险操作。如需完整控制，可以在权限对话框中手动提升。
+
+## 可用操作
+
+### 鼠标
+
+| 操作 | 说明 |
+|------|------|
+| 移动鼠标 | 移动到指定坐标 |
+| 左键点击 | 单击、双击、三击 |
+| 右键点击 | 需要 full 权限 |
+| 中键点击 | 需要 full 权限 |
+| 拖拽 | 从 A 点拖到 B 点，需要 full 权限 |
+| 滚轮 | 向上或向下滚动 |
+
+### 键盘
+
+| 操作 | 说明 |
+|------|------|
+| 按键 | 单个按键或组合键（如 Ctrl+C） |
+| 输入文字 | 逐字符输入文本，需要 full 权限 |
+| 长按 | 按住某个键一段时间，需要 full 权限 |
+
+### 屏幕
+
+| 操作 | 说明 |
+|------|------|
+| 截图 | 截取当前屏幕 |
+| 切换显示器 | 多显示器环境下切换目标屏幕 |
+| 缩放 | 放大屏幕某个区域 |
+
+### 其他
+
+| 操作 | 说明 |
+|------|------|
+| 获取鼠标位置 | 查询当前鼠标坐标 |
+| 批量操作 | 一次执行多个操作，减少等待 |
+| 等待 | 暂停指定秒数（最长 100 秒） |
+
+## macOS 权限配置
+
+首次使用前，需要授予两项系统权限。缺少任一项都会导致功能异常（见下方说明）。
+
+### 辅助功能（Accessibility）
+
+允许 Claude 控制鼠标和键盘。
+
+1. 打开 **系统设置 → 隐私与安全性 → 辅助功能**
+2. 点击左下角锁图标解锁（需要管理员密码）
+3. 将运行 Claude Code 的应用添加到允许列表：
+   - Terminal → `Terminal.app`
+   - iTerm → `iTerm.app`
+   - Cursor → `Cursor.app`
+   - VS Code 终端 → `Electron` 或 `Visual Studio Code.app`
+4. 确保应用旁边的开关已打开
+
+**未授予时的现象**：鼠标移动、点击、键盘输入均无反应，工具执行成功但屏幕没有任何变化。
+
+### 屏幕录制（Screen Recording）
+
+允许 Claude 截取屏幕内容。
+
+1. 打开 **系统设置 → 隐私与安全性 → 屏幕录制**
+2. 将同一个应用添加到允许列表并开启开关
+3. **需要重启该应用**才能生效（系统会提示 "xxx 需要重新打开"）
+
+**未授予时的现象**：截图工具执行成功但返回空白图片，Claude 无法看到你的屏幕，所有点击操作变成"盲点"。
+
+### 验证权限
+
+授予两项权限后，重启 Claude Code，在对话中让 Claude 截一张图即可验证是否配置成功。如果截图内容正常显示，说明权限配置完成。
+
+## Linux 依赖（暂不可用）
+
+Linux 后端尚未开发。完成后需要安装以下工具：

 ```bash
-bun run dev
+sudo apt install xdotool scrot xclip wmctrl
 ```

-`scripts/dev.ts` 的默认 feature 列表已包含 `CHICAGO_MCP`，启动后自动注册 Computer Use MCP 工具。
+仅支持 X11，Wayland 不支持。

-### 构建产物
+## 常见问题

-```bash
-FEATURE_CHICAGO_MCP=1 node dist/cli.js
-```
+### 截图成功但看不到图片

-### 使用流程
+检查 **系统设置 → 隐私与安全性 → 屏幕录制** 是否已授权。未授权时截图工具会执行成功但返回空白内容。

-1. **启动 CLI** — `bun run dev`（或构建产物 + 环境变量）
-2. **正常对话** — 在 REPL 中与 Claude 对话，当你让 Claude 操作电脑时（如"帮我打开浏览器并访问 xxx"），Claude 会调用 Computer Use 工具
-3. **首次审批** — Claude 首次尝试操控某个 App 时，会弹出权限对话框，你需要确认允许哪些 App 被操控（可勾选"本次会话不再询问"）
-4. **操作中** — 系统会发送通知"Claude is using your computer"，macOS 按 Esc、其他平台按 Ctrl+C 可中止
-5. **操作结束** — Claude 完成操作后自动释放，被隐藏的窗口会自动恢复
+### IDE 中无法输入文字或右键

-### 可用的操作
+这是正常行为。IDE 类应用只有 click 权限，无法执行键盘输入、右键、拖拽等操作。如需完整控制，请在系统应用（如 Finder）中操作。

- 截图（全屏 / 区域缩放）
- 鼠标移动、点击、拖拽、滚轮
- 键盘输入、组合键、长按
- 通过剪贴板粘贴多行文本
- 应用管理（列出、打开、隐藏/恢复）
- 多显示器支持（自动选择或手动指定）
+### 操作中途想停止

-### 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。
-
-### macOS 权限
-
-macOS 首次使用需要授予「辅助功能」和「屏幕录制」权限（系统会提示）。
-
-### Windows
-
-无需额外权限，开箱即用。
-
-## 3. 实施细节
-
-### 3.1 功能开关（gates.ts）
-
- `enabled` 默认为 `true`，无需订阅检查
- `hasRequiredSubscription()` 直接返回 `true`
- 子开关（鼠标动画、隐藏窗口、剪贴板守卫等）均通过 GrowthBook 远程配置或使用默认值
-
-### 3.2 平台分发
-
-所有平台相关逻辑已通过 `process.platform` 判断分发：
-
-| 文件 | 处理方式 |
-|------|---------|
-| `executor.ts` | 剪贴板：darwin→pbcopy/pbpaste，win32→PowerShell，linux→xclip；粘贴键：darwin→command+v，其他→ctrl+v |
-| `drainRunLoop.ts` | 非 darwin 直接执行 fn()，不需要 CFRunLoop pump |
-| `escHotkey.ts` | 非 darwin 返回 false（已有 Ctrl+C fallback） |
-| `hostAdapter.ts` | 非 darwin 直接返回 `{ granted: true }`，macOS 检查 TCC 权限 |
-| `common.ts` | 动态获取 platform 标识，截图过滤按平台选择 |
-| `swiftLoader.ts` | 自动检测包导出类型，跨平台实例化 `ComputerUseAPI` |
-| `main.tsx` | 仅检查 `feature('CHICAGO_MCP')` + 交互模式，无平台限制 |
-
-### 3.3 每个平台的能力依赖
-
-#### computer-use-input（键鼠）
-
-| 功能 | macOS | Windows | Linux |
-|------|-------|---------|-------|
-| 鼠标移动 | CGEvent JXA | SetCursorPos P/Invoke | xdotool mousemove |
-| 鼠标点击 | CGEvent JXA | SendInput P/Invoke | xdotool click |
-| 鼠标滚轮 | CGEvent JXA | SendInput MOUSEEVENTF_WHEEL | xdotool scroll |
-| 键盘按键 | System Events osascript | keybd_event P/Invoke | xdotool key |
-| 组合键 | System Events osascript | keybd_event 组合 | xdotool key combo |
-| 文本输入 | System Events keystroke | SendKeys.SendWait | xdotool type |
-| 前台应用 | System Events osascript | GetForegroundWindow P/Invoke | xdotool getactivewindow + /proc |
-| 工具依赖 | osascript（内置） | powershell（内置） | xdotool（需安装） |
-
-#### computer-use-swift（截图 + 应用管理）
-
-| 功能 | macOS | Windows | Linux |
-|------|-------|---------|-------|
-| 全屏截图 | screencapture | CopyFromScreen | gnome-screenshot / scrot / grim |
-| 区域截图 | screencapture -R | CopyFromScreen(rect) | gnome-screenshot -a / scrot -a / grim -g |
-| 显示器列表 | CGGetActiveDisplayList JXA | Screen.AllScreens | xrandr --query |
-| 运行中应用 | System Events JXA | Get-Process | wmctrl -l / ps |
-| 打开应用 | osascript activate | Start-Process | xdg-open / gtk-launch |
-| 隐藏/显示 | System Events visibility | ShowWindow/SetForegroundWindow | wmctrl -c / xdotool |
-| 工具依赖 | screencapture + osascript | powershell | xdotool + scrot/grim + wmctrl |
-
-#### executor 层
-
-| 功能 | macOS | Windows | Linux |
-|------|-------|---------|-------|
-| drainRunLoop | CFRunLoop pump | 不需要 | 不需要 |
-| ESC 热键 | CGEventTap | 跳过（Ctrl+C fallback） | 跳过（Ctrl+C fallback） |
-| 剪贴板读 | pbpaste | `powershell Get-Clipboard` | xclip -o / wl-paste |
-| 剪贴板写 | pbcopy | `powershell Set-Clipboard` | xclip / wl-copy |
-| 粘贴快捷键 | command+v | ctrl+v | ctrl+v |
-| 终端检测 | __CFBundleIdentifier | WT_SESSION / TERM_PROGRAM | TERM_PROGRAM |
-| 系统权限 | TCC check | 直接 granted | 检查 xdotool 安装 |
-
-## 4. 完成状态
-
-| Phase | 内容 | 状态 |
-|-------|------|------|
-| Phase 1 | MCP 实现 + Windows 后端 | ✅ 已完成 |
-| Phase 2 | 移除 macOS 硬编码 | ✅ 已完成 |
-| Phase 3 | Linux 后端（待新建 linux.ts） | ❌ 未完成 |
-
-Phase 1-2 完成后 macOS + Windows 可用。Phase 3（Linux 后端）需要新建 `packages/@ant/computer-use-input/src/backends/linux.ts`（~150 行）和 `packages/@ant/computer-use-swift/src/backends/linux.ts`（~200 行），并在对应 dispatcher 中加 `case 'linux'`。
+按 **Esc**（macOS）或 **Ctrl+C** 即可立即中止。
--- a/src/utils/computerUse/hostAdapter.ts
+++ b/src/utils/computerUse/hostAdapter.ts
@@ -48,6 +48,11 @@ export function getComputerUseHostAdapter(): ComputerUseHostAdapter {
      if (process.platform !== 'darwin') return { granted: true }
      const cu = requireComputerUseSwift() as any
      // Native .node module exposes tcc; cross-platform JS backend does not.
+      // When tcc is absent (JS backend on macOS), we cannot programmatically
+      // check TCC status — returning granted:false would create a deadlock
+      // (recheck also fails, user can never pass).  The JS backend uses
+      // osascript/screencapture which trigger OS-level permission prompts
+      // themselves, so the OS provides the safety net instead.
      if (!cu.tcc) return { granted: true }
      const accessibility = cu.tcc.checkAccessibility()
      const screenRecording = cu.tcc.checkScreenRecording()