computer-use

计算机使用技能

为无头 Linux 服务器提供完整的桌面 GUI 控制。创建虚拟显示器（Xvfb + XFCE），让你无需物理显示器，即可在 VPS/云实例上运行和控制桌面应用程序。

环境

• 显示器：:99
• 分辨率：1024x768（XGA，Anthropic 推荐）
• 桌面环境：XFCE4（精简配置 — 仅 xfwm4 + 面板）

快速设置

运行设置脚本安装所有组件（systemd 服务、无闪烁 VNC）：

./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	截取指定区域

使用示例

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. 分析 — 识别界面元素和坐标
3. 操作 — 单击、输入、滚动
4. 截屏 — 验证结果
5. 重复

提示

• 屏幕分辨率为 1024x768，原点 (0,0) 位于左上角
• 在文本框中输入前，先单击使其获得焦点
• 在浏览器中使用 ctrl+End 跳转到页面底部
• 大多数操作会在延迟 2 秒后自动截屏
• 长文本会分段输入（每段 50 个字符），按键间隔为 12ms

实时桌面查看（VNC）

通过浏览器或 VNC 客户端实时查看桌面。

通过浏览器连接

# SSH tunnel (run on your local machine)
ssh -L 6080:localhost:6080 your-server

# Open in browser
http://localhost:6080/vnc.html

通过 VNC 客户端连接

# 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。

系统服务

# 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+面板，并终止 xfdesktop
• x11vnc：使用 -noxdamage 以提高稳定性的 VNC 服务
• novnc：带有心跳机制的 WebSocket 代理，可提升连接稳定性

打开应用程序

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：

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：

# 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 安装：

xvfb xfce4 xfce4-terminal xdotool scrot imagemagick dbus-x11 x11vnc novnc websockify