介绍
# Computer Use Skill
针对无头 Linux 服务器的完整桌面 GUI 控制。创建虚拟显示（Xvfb + XFCE），以便您在 VPS/云实例上无需物理显示器即可运行和控制桌面应用程序。
## 环境
- **显示**: `:99` - **分辨率**: 1024x768 (XGA, Anthropic 推荐) - **桌面**: XFCE4 (最小化 — 仅含 xfwm4 + 面板)
## 快速设置
运行安装脚本以安装所有内容（systemd 服务，无闪烁 VNC）：
```bash ./scripts/setup-vnc.sh ```
这将安装： - 位于 `:99` 的 Xvfb 虚拟显示 - 最小化 XFCE 桌面（xfwm4 + 面板，不含 xfdesktop） - 带稳定性参数的 x11vnc - 用于浏览器访问的 noVNC
所有服务在启动时自动启动，并在崩溃时自动重启。
## 操作参考
| 操作 | 脚本 | 参数 | 描述 | |--------|--------|-----------|-------------| | 截图 | `screenshot.sh` | — | 捕获屏幕 → base64 PNG | | 光标位置 | `cursor_position.sh` | — | 获取当前鼠标 X,Y | | 鼠标移动 | `mouse_move.sh` | x y | 移动鼠标至坐标 | | 左键单击 | `click.sh` | x y left | 在坐标处左键单击 | | 右键单击 | `click.sh` | x y right | 右键单击 | | 中键单击 | `click.sh` | x y middle | 中键单击 | | 双击 | `click.sh` | x y double | 双击 | | 三击 | `click.sh` | x y triple | 三击（选中行） | | 左键拖拽 | `drag.sh` | x1 y1 x2 y2 | 从起点拖拽至终点 | | 左键按下 | `mouse_down.sh` | — | 按下鼠标按钮 | | 左键松开 | `mouse_up.sh` | — | 松开鼠标按钮 | | 输入 | `type_text.sh` | "text" | 输入文本（50 字符分块，12ms 延迟）| | 按键 | `key.sh` | "combo" | 按下按键（Return, ctrl+c, alt+F4）| | 长按 | `hold_key.sh` | "key" secs | 按住按键持续指定时间 | | 滚动 | `scroll.sh` | dir amt [x y] | 向上/下/左/右滚动 | | 等待 | `wait.sh` | seconds | 等待然后截图 | | 缩放 | `zoom.sh` | x1 y1 x2 y2 | 裁剪区域截图 |
## 使用示例
```bash export DISPLAY=:99
# Take screenshot ./scripts/screenshot.sh
# Click at coordinates ./scripts/click.sh 512 384 left
# Type text ./scripts/type_text.sh "Hello world"
# Press key combo ./scripts/key.sh "ctrl+s"
# Scroll down ./scripts/scroll.sh down 5 ```
## 工作流模式
1. **截图** — 始终从查看屏幕开始 2. **分析** — 识别 UI 元素和坐标 3. **操作** — 单击、输入、滚动 4. **截图** — 验证结果 5. **重复**
## 提示
- 屏幕为 1024x768，原点 (0,0) 位于左上角 - 在文本字段中输入前先单击以获取焦点 - 使用 `ctrl+End` 在浏览器中跳转至页面底部 - 大多数操作在 2 秒延迟后会自动截图 - 长文本会分块（50 字符），并带有 12ms 的按键延迟
## 实时桌面查看 (VNC)
通过浏览器或 VNC 客户端实时查看桌面。
### 通过浏览器连接
```bash # SSH tunnel (run on your local machine) ssh -L 6080:localhost:6080 your-server
# Open in browser http://localhost:6080/vnc.html ```
### 通过 VNC 客户端连接
```bash # SSH tunnel ssh -L 5900:localhost:5900 your-server
# Connect VNC client to localhost:5900 ```
### SSH 配置（推荐）
添加到 `~/.ssh/config` 以实现自动隧道连接：
``` Host your-server HostName your.server.ip User your-user LocalForward 6080 127.0.0.1:6080 LocalForward 5900 127.0.0.1:5900 ```
然后只需 `ssh your-server`，VNC 即可连接。
## 系统服务
```bash # Check status systemctl status xvfb xfce-minimal x11vnc novnc
# Restart if needed sudo systemctl restart xvfb xfce-minimal x11vnc novnc ```
### 服务链
``` xvfb → xfce-minimal → x11vnc → novnc ```
- **xvfb**: 虚拟显示 :99 (1024x768x24) - **xfce-minimal**: 看门狗程序，运行 xfwm4+panel，终止 xfdesktop - **x11vnc**: 带有 `-noxdamage` 参数以保证稳定性的 VNC 服务器 - **novnc**: WebSocket 代理，带心跳机制以保持连接稳定
## 打开应用程序
```bash export DISPLAY=:99
# Chrome — only use --no-sandbox if the kernel lacks user namespace support. # Check: cat /proc/sys/kernel/unprivileged_userns_clone # 1 = sandbox works, do NOT use --no-sandbox # 0 = sandbox fails, --no-sandbox required as fallback # Using --no-sandbox when unnecessary causes instability and crashes. if [ "$(cat /proc/sys/kernel/unprivileged_userns_clone 2>/dev/null)" = "0" ]; then google-chrome --no-sandbox & else google-chrome & fi
xfce4-terminal & # Terminal thunar & # File manager ```
**注意**：Snap 浏览器（Firefox、Chromium）在无头服务器上存在沙箱问题。请改用 Chrome `.deb` 包：
```bash wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb sudo dpkg -i google-chrome-stable_current_amd64.deb sudo apt-get install -f ```
## 手动设置
如果您更喜欢手动设置而不是使用 `setup-vnc.sh`：
```bash # Install packages sudo apt install -y xvfb xfce4 xfce4-terminal xdotool scrot imagemagick dbus-x11 x11vnc novnc websockify
# Run the setup script (generates systemd services, masks xfdesktop, starts everything) ./scripts/setup-vnc.sh ```
如果您更喜欢完全手动设置，`setup-vnc.sh` 脚本会内联生成所有 systemd 服务文件 — 请阅读它以了解确切的服务定义。
## 故障排除
### VNC 显示黑屏 - 检查 xfwm4 是否正在运行：`pgrep xfwm4` - 重启桌面：`sudo systemctl restart xfce-minimal`
### VNC 闪烁/闪屏 - 确保 xfdesktop 已被屏蔽（检查 `/usr/bin/xfdesktop`） - xfdesktop 由于在 Xvfb 上的清除→绘制循环会导致闪烁
### VNC 频繁断开连接 - 检查 noVNC 是否带有 `--heartbeat 30` 参数 - 检查 x11vnc 是否带有 `-noxdamage` 参数
### x11vnc 崩溃 (SIGSEGV) - 添加 `-noxdamage -noxfixes` 参数 - DAMAGE 扩展会导致 Xvfb 崩溃
## 依赖项
由 `setup-vnc.sh` 安装： ```bash xvfb xfce4 xfce4-terminal xdotool scrot imagemagick dbus-x11 x11vnc novnc websockify ```