mirror of
https://github.com/NanmiCoder/cc-haha
synced 2026-08-01 16:43:37 +08:00
190 lines
7.1 KiB
Markdown
190 lines
7.1 KiB
Markdown
# Computer Use 使用指南
|
||
|
||
Computer Use 允许模型读取屏幕并操作鼠标、键盘、应用和剪贴板。它直接作用于当前电脑，启用前请先理解授权范围和平台差异。
|
||
|
||
## 支持平台
|
||
|
||
| 平台 | 状态 | 关键差异 |
|
||
|---|---|---|
|
||
| macOS Apple Silicon / Intel | 支持 | 需要“辅助功能”和“屏幕录制”权限；支持原生截图过滤 |
|
||
| Windows | 支持 | 使用 Windows Python 运行时；截图不会过滤未授权窗口 |
|
||
| Linux | 不支持 | 当前没有 Linux 执行器 |
|
||
|
||
打包桌面端不要求用户安装 Bun。Computer Use 需要可用的 Python 3，应用会在用户配置目录下创建隔离的虚拟环境并安装平台依赖。
|
||
|
||
## 快速开始
|
||
|
||
### 桌面端
|
||
|
||
1. 打开“设置 → Computer Use”。
|
||
2. 开启 Computer Use。
|
||
3. 检查 Python 状态；自动检测失败时，可选择 Python 可执行文件。
|
||
4. 执行安装或修复，让应用创建虚拟环境和安装依赖。
|
||
5. macOS 用户授予“辅助功能”和“屏幕录制”权限，然后重新检查。
|
||
6. 选择允许控制的应用，并按需要开启剪贴板和系统组合键权限。
|
||
7. 新建会话，用自然语言描述目标和允许操作的应用。
|
||
|
||
可以从简单、可撤销的任务开始：
|
||
|
||
```text
|
||
截取当前屏幕并告诉我你看到了什么。
|
||
打开 Notes，新建一条标题为“测试”的空白笔记。
|
||
在已授权的应用中，帮我找到设置入口，但不要修改任何内容。
|
||
```
|
||
|
||
### CLI
|
||
|
||
源码模式需要先安装项目依赖，并保证 Python 3 可用：
|
||
|
||
```bash
|
||
bun install
|
||
python3 --version
|
||
./bin/claude-haha
|
||
```
|
||
|
||
可以通过环境变量关闭动态 Computer Use MCP：
|
||
|
||
```bash
|
||
CLAUDE_COMPUTER_USE_ENABLED=0 ./bin/claude-haha
|
||
```
|
||
|
||
也可以在 `~/.claude/cc-haha/computer-use-config.json` 中设置：
|
||
|
||
```json
|
||
{
|
||
"enabled": false
|
||
}
|
||
```
|
||
|
||
桌面设置页修改的是同一份托管配置。优先使用设置页，不要手工覆盖其中未知字段。
|
||
|
||
## 工具与 Teach 能力
|
||
|
||
代码中定义了 27 个 Computer Use 工具：
|
||
|
||
| 类别 | 工具 |
|
||
|---|---|
|
||
| 授权 | `request_access`、`list_granted_applications` |
|
||
| 截图 | `screenshot`、`zoom` |
|
||
| 鼠标 | `left_click`、`right_click`、`middle_click`、`double_click`、`triple_click`、`left_click_drag`、`mouse_move`、`left_mouse_down`、`left_mouse_up`、`cursor_position`、`scroll` |
|
||
| 键盘 | `type`、`key`、`hold_key` |
|
||
| 应用 | `open_application`、`switch_display` |
|
||
| 剪贴板 | `read_clipboard`、`write_clipboard` |
|
||
| 控制流 | `wait`、`computer_batch` |
|
||
| Teach | `request_teach_access`、`teach_step`、`teach_batch` |
|
||
|
||
基础控制能力包含 24 个工具。Teach 的 3 个工具只在宿主启用 Teach capability 时公开；未启用时，当前会话只会看到基础工具。
|
||
|
||
Teach 用于“带着用户一步一步操作”的场景：
|
||
|
||
1. `request_teach_access` 请求教学所需的应用授权。
|
||
2. `teach_step` 展示一个带锚点的说明，并等待用户点击下一步。
|
||
3. `teach_batch` 把可以预判的多个教学步骤合并，减少模型往返。
|
||
|
||
Teach 授权与普通控制授权相互独立。教学步骤仍经过应用白名单和输入安全检查；用户退出教学后，模型不应继续调用 Teach 工具。
|
||
|
||
## 工作原理
|
||
|
||
Computer Use 使用“截图 → 分析 → 操作 → 再截图”的闭环：
|
||
|
||
```text
|
||
模型
|
||
→ 调用 Computer Use MCP 工具
|
||
→ TypeScript 调度与安全检查
|
||
→ Python Bridge
|
||
→ macOS / Windows 系统操作
|
||
→ 截图或操作结果返回模型
|
||
```
|
||
|
||
- 工具定义与授权逻辑位于 `src/vendor/computer-use-mcp/`。
|
||
- CLI 集成和 Python Bridge 位于 `src/utils/computerUse/`。
|
||
- 平台执行器位于 `runtime/mac_helper.py` 和 `runtime/win_helper.py`。
|
||
- 桌面安装、权限和预授权由 `src/server/api/computer-use.ts` 与 `desktop/src/pages/ComputerUseSettings.tsx` 管理。
|
||
|
||
## 授权模型
|
||
|
||
### 应用授权
|
||
|
||
模型必须先调用 `request_access`，说明需要哪些应用以及原因。用户可以批准或拒绝。设置页中的预授权应用是默认授权配置，不代表任意应用都可以被控制；运行中新增应用仍需要走相应授权流程。
|
||
|
||
应用按能力分为三个等级：
|
||
|
||
| 等级 | 能力 |
|
||
|---|---|
|
||
| `read` | 读取截图，不执行输入 |
|
||
| `click` | 点击、移动和滚动，不输入文字或执行高权限动作 |
|
||
| `full` | 在其他安全检查通过后允许键盘、拖拽等完整操作 |
|
||
|
||
### 剪贴板与系统组合键
|
||
|
||
剪贴板读取、剪贴板写入和系统级组合键是单独的授权标志。允许控制某个应用，不会自动获得这些权限。
|
||
|
||
### 并发
|
||
|
||
Computer Use 使用会话锁防止多个会话同时争夺鼠标和键盘。看到“正在被其他会话使用”时，应先停止或完成原会话，而不是删除锁文件。
|
||
|
||
## 平台安全边界
|
||
|
||
### macOS
|
||
|
||
- 需要“辅助功能”才能输入和操作应用。
|
||
- 需要“屏幕录制”才能截图。
|
||
- 截图支持原生窗口过滤，只保留授权应用和桌面。
|
||
|
||
### Windows
|
||
|
||
- 当前截图过滤能力为 `none`：截图中可能出现所有可见窗口。
|
||
- 应用白名单仍会阻止把输入动作发送给未授权的前台应用。
|
||
- 因为截图本身不做过滤，开始前应主动关闭或最小化包含敏感信息的窗口。
|
||
|
||
### 当前明确没有的保护
|
||
|
||
- **没有全局 Escape 中止热键。** 桌面端应使用当前任务的停止操作；CLI 运行可用终端中断。
|
||
- **不会在每次操作前自动隐藏未授权窗口。** 不要依赖自动隐藏来保护敏感内容。
|
||
- **像素陈旧验证默认关闭。** UI 变化后，模型应重新截图再点击。
|
||
|
||
这些限制是当前实现边界，不应在文档或 UI 中描述成已经可用。
|
||
|
||
## Python 运行时
|
||
|
||
首次安装或修复时，应用会：
|
||
|
||
1. 把当前平台的 helper 和 requirements 同步到用户配置目录。
|
||
2. 使用自动检测或用户选择的 Python 创建 venv。
|
||
3. 安装或升级 pip。
|
||
4. 按 requirements 内容哈希决定是否重新安装依赖。
|
||
5. 通过 JSON payload 调用平台 helper，并解析统一 JSON 结果。
|
||
|
||
macOS 主要依赖 `mss`、Pillow、PyAutoGUI 和 PyObjC；Windows 还使用 pywin32、psutil、pyperclip 与 screeninfo。准确版本约束以 `runtime/requirements*.txt` 为准。
|
||
|
||
## 故障排查
|
||
|
||
### macOS 仍提示缺少权限
|
||
|
||
- 确认授权的是实际启动 Claude Code Haha 的应用。
|
||
- 权限变更后完全退出并重新打开应用。
|
||
- 在设置页重新执行权限检查。
|
||
|
||
### Python 安装失败
|
||
|
||
- 在设置页选择明确的 Python 3 可执行文件。
|
||
- 确认该 Python 支持 `venv`。
|
||
- 使用“安装/修复”重新创建运行时。
|
||
- 查看“诊断”页中的 Computer Use 安装日志。
|
||
|
||
### 截图可以但点击失败
|
||
|
||
- 确认目标应用处于授权列表。
|
||
- 确认它是当前前台应用。
|
||
- 检查授权等级是否允许该动作。
|
||
- UI 已变化时重新截图，不要复用旧坐标。
|
||
|
||
### Windows 截图出现其他窗口
|
||
|
||
这是当前 Windows 截图能力的已知边界。输入白名单不会过滤截图内容；执行前请关闭或最小化敏感窗口。
|
||
|
||
## 深入阅读
|
||
|
||
- [Computer Use 架构](./computer-use-architecture.md)
|
||
- [桌面端架构](../desktop/02-architecture.md)
|