diff --git a/README.md b/README.md index dc92cdb5f..993a1bc27 100644 --- 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 分支将会封存为历史版本 diff --git a/docs/features/computer-use.md b/docs/features/computer-use.md index feb417b0c..2cfd54d8c 100644 --- 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** 即可立即中止。 diff --git a/src/utils/computerUse/hostAdapter.ts b/src/utils/computerUse/hostAdapter.ts index a361e1bcc..6b494ec64 100644 --- 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()