computer-control

计算机控制技能

使用 Claude 的 Computer Use API，通过屏幕截图和鼠标／键盘操作查看并控制桌面环境。

适用场景

• 自动化缺少 CLI 替代方案的 GUI 工作流
• 通过视觉交互测试 Web 应用
• 填写表单、浏览菜单或与桌面应用交互
• 构建需要视觉验证的自动化流水线

不适用场景

• 可通过 CLI 或 API 完成的任务（无需 GUI）
• 使用 Playwright 或 CDP 更适合的浏览器自动化

为何默认选择不启用。 根据 docs/inclusive-defaults.md（TRUE-exception 类别 4），Computer Use 会截取屏幕截图并合成键盘／鼠标输入：这类跨进程副作用必须始终由用户显式调用，绝不能默认启用。

架构

计算机使用系统分为三层：

1. 显示工具包（phantom.display）- 通过 xdotool/scrot 在真实或虚拟显示器上执行操作系统级操作
2. Agent 循环（phantom.loop）- 管理 Claude API 与显示工具包之间的对话循环
3. CLI（phantom.cli）- 用于运行任务或检查环境是否就绪的命令行界面

User Task
    |
    v
Agent Loop  <---->  Claude API (beta)
    |                   |
    v                   v
Display Toolkit    tool_use responses
    |              (click, type, screenshot)
    v
OS Commands (xdotool, scrot)
    |
    v
Display (X11 / Xvfb / WSLg)

快速入门

检查环境

cd plugins/phantom
uv run python -m phantom.cli --check

运行任务

export ANTHROPIC_API_KEY="sk-ant-..."
uv run python -m phantom.cli "Open Firefox and search for Claude AI"

在 Python 中使用

from phantom.display import DisplayConfig, DisplayToolkit
from phantom.loop import LoopConfig, run_loop

result = run_loop(
    task="Take a screenshot of the desktop",
    api_key="sk-ant-...",
    loop_config=LoopConfig(
        model="claude-sonnet-5",
        max_iterations=10,
    ),
    display_config=DisplayConfig(width=1920, height=1080),
)

print(f"Done in {result.iterations} iterations")
print(result.final_text)

API 版本

模型	工具版本	Beta 标记
Opus 4.6、Sonnet 4.6、Opus 4.5	computer_20251124	computer-use-2025-11-24
Sonnet 4.5、Haiku 4.5、更早版本	computer_20250124	computer-use-2025-01-24

resolve_tool_version() 函数会根据模型名称自动处理此映射。

可用操作

所有版本：

• screenshot - 截取显示画面
• left_click - 在 [x, y] 处单击
• type - 输入文本字符串
• key - 按下组合键（例如 ctrl+s）
• mouse_move - 移动光标

增强版（20250124+）：

• scroll - 按指定方向和距离滚动
• left_click_drag - 在坐标之间拖动
• right_click、middle_click、double_click、triple_click
• hold_key - 按住按键一段时间
• wait - 在操作之间暂停

最新版本（20251124）：

• zoom - 以全分辨率查看屏幕区域

安全

使用计算机控制存在风险。请遵循以下指南：

1. 使用沙盒：在 Docker 或 VM 中运行，不要在主操作系统上运行
2. 限制访问权限：除非必要，否则不要提供登录凭据；绝不要提供银行或敏感服务的凭据
3. 设置迭代上限：始终使用 max_iterations，避免 API 费用失控
4. 人工审批：对于可能造成现实影响的操作，通过 on_action 添加确认回调
5. 关闭敏感应用：Claude 会通过屏幕截图看到整个屏幕；开始前关闭所有私人内容

环境要求

Linux（原生或使用 WSLg 的 WSL2）：

sudo apt install xdotool scrot xclip

无头环境（Docker/CI）：

# Install Xvfb for virtual display
sudo apt install xvfb xdotool scrot xclip
Xvfb :1 -screen 0 1920x1080x24 &
export DISPLAY=:1

提示词编写技巧

1. 明确说明任务的每个步骤
2. 加上“每完成一步后，截取屏幕截图并进行验证”，以便尽早发现错误
3. 当界面元素难以点击时，使用键盘快捷键
4. 为可重复的工作流提供示例屏幕截图
5. 设置包含特定领域指令的系统提示词

退出条件

• 启动任何任务前，uv run python -m phantom.cli --check 的退出码为 0；如果检查失败，则先安装所需的操作系统工具（xdotool、scrot、xclip）或启动 Xvfb，再继续
• 每次调用 run_loop() 都设置 max_iterations；启动任务时必须明确设置迭代上限，以避免 API 费用失控
• 最终结果包含 result.iterations 计数和确认任务结果的 result.final_text；final_text 为空时应视为失败，而非成功
• 任务开始前关闭敏感应用（密码管理器、银行应用、私人文件）；任务提示词中不得包含原始凭据