过去一年，Computer use 从演示视频里的“魔法”逐渐变成了工程团队手里的普通工具。要把这件事落地，绕不开一个很实际的问题：怎么让大模型稳定地看见屏幕、移动鼠标、敲键盘，还能在失败后重试？agent-desktop 就是为这个场景准备的 Computer use CLI。它不是一个庞大的 SDK，而是一套命令行接口，把屏幕截图、坐标点击、键盘输入、无障碍树读取这些原子动作暴露出来，让 Agent 通过 shell 调用即可完成桌面操作。这篇文章围绕它的工作方式、安装配置、可运行代码和常见坑展开，尽量把能直接抄走的部分写清楚。
Computer use CLI 到底解决什么问题
传统做法是让模型直接输出一段 PyAutoGUI 脚本，然后本地执行。听起来简单，实际很脆弱：模型不知道当前屏幕分辨率，不知道弹窗位置，也不清楚上一步点击是否生效。agent-desktop 的思路是把“感知”和“动作”拆成两条独立的命令通道。感知侧提供截图和无障碍树（accessibility tree）导出，动作侧提供点击、拖拽、输入、滚动等命令，每次调用都返回结构化结果，包括成功状态和当前屏幕摘要。这样 Agent 的循环就变成“截图 → 推理 → 执行单步动作 → 再截图验证”，而不是一次性生成整段脚本。CLI 形态还有个隐性好处：它天然适配任何能执行 shell 的 Agent 框架，不需要为 LangChain、AutoGPT 或者自研 runtime 各写一套适配层。你只要保证子进程能跑起来，剩下的就是拼命令。
安装与首次运行验证
agent-desktop 通常以单文件二进制或 Python 包形式分发，依赖系统级的截图与输入权限。在 Linux 上需要 X11 或 Wayland 的 input 注入权限，macOS 需要在“辅助功能”和“屏幕录制”里授权终端，Windows 则一般开箱可用。安装完成后第一件事不是急着点击，而是跑一次环境自检，确认截图能拿到、坐标能映射。
# 安装（以 pip 分发为例）
pip install agent-desktop
# 环境自检：输出屏幕尺寸、DPI 缩放、可用后端
agent-desktop doctor
# 抓一张全屏截图，保存到当前目录
agent-desktop screenshot –output ./screen.png
# 导出无障碍树，便于按元素定位而非硬编码坐标
agent-desktop tree –format json –depth 6 > ./a11y.json
# 单步动作：在 (640, 360) 处左键单击，并返回执行后的屏幕摘要
agent-desktop click –x 640 –y 360 –button left –verify
doctor 的输出值得细看，尤其是 DPI 缩放比例。很多“点了但没点中”的问题都来自缩放：截图是 1920×1080，实际逻辑坐标却是 1536×864，坐标直接传进去就会偏移。–verify 参数会让命令在动作后重新截图并返回差异摘要，方便 Agent 判断这一步是否产生了预期变化，而不是盲目进入下一步。
用 C 语言封装一个最小 Agent 循环
真正把 CLI 用起来，通常需要一个调度层。下面这段 C 代码演示了最小闭环：调用 agent-desktop 截图，读取文件大小作为“画面是否变化”的粗略信号，然后执行一次点击。实际项目里你会把中间那步换成模型推理，但进程调用和错误处理的结构是一样的。
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/stat.h>
static long file_size(const char *path) {
struct stat st;
if (stat(path, &st) != 0) return –1;
return (long)st.st_size;
}
static int run(const char *cmd) {
int rc = system(cmd);
if (rc != 0) {
fprintf(stderr, "[warn] command failed (%d): %s\\n", rc, cmd);
}
return rc;
}
int main(void) {
const char *shot = "/tmp/ad_step.png";
long prev = –1;
for (int step = 0; step < 5; step++) {
char buf[512];
/* 1. 感知：抓取当前屏幕 */
snprintf(buf, sizeof(buf),
"agent-desktop screenshot –output %s –quiet", shot);
if (run(buf) != 0) return 1;
long now = file_size(shot);
printf("step=%d screenshot_bytes=%ld\\n", step, now);
/* 2. 画面几乎没变化，说明上一步可能没生效，先停手 */
if (prev > 0 && labs(now – prev) < 1024) {
printf("screen unchanged, abort to avoid blind clicking\\n");
break;
}
prev = now;
/* 3. 动作：这里用固定坐标演示，真实场景应由模型给出 */
snprintf(buf, sizeof(buf),
"agent-desktop click –x 640 –y 360 –button left –verify");
run(buf);
}
return 0;
}
编译用 gcc agent.c -o agent 即可。这段代码刻意保持粗糙，因为它的价值在于展示边界：每一步都要检查返回值，动作之后要重新感知，检测到画面停滞就主动退出。Agent 系统里最贵的成本不是推理费用，而是错误动作引发的连锁反应，一个失控的拖拽可能把整个窗口布局搞乱，后面所有坐标全部失效。
坐标定位与无障碍树的选择
用坐标还是用元素，是 Computer use 里最常被讨论的取舍。纯坐标方案实现简单，但对分辨率、主题、语言敏感；无障碍树方案更稳，能按 role 和 name 定位，可惜并非所有应用都暴露完整语义，Electron 应用和部分自绘 UI 的树往往很浅。agent-desktop 允许两者混用：先用 tree 拿到候选元素及其包围盒，再退化成坐标点击。
# 按无障碍名称查找按钮，输出其中心坐标
agent-desktop find –role button –name "保存" –format coord
# 若找到，输出形如 812,446；直接喂给 click
COORD=$(agent-desktop find –role button –name "保存" –format coord)
if [ -n "$COORD" ]; then
agent-desktop click –coord "$COORD" –verify
else
echo "element not found, fallback to vision model" >&2
fi
# 键盘输入与组合键，注意先聚焦目标控件
agent-desktop type –text "hello world"
agent-desktop key –combo "ctrl+s"
实践中的推荐顺序是：优先 find 按语义定位，失败则用截图交给视觉模型估算坐标，最后才用固定坐标兜底。这个降级链条要写进 Agent 的提示词里，否则模型容易在第一次失败后就反复重试同一个错误坐标。另外 type 之前务必确认焦点，很多“输入丢失”其实是焦点还在上一个窗口。
稳定性、权限与常见报错
部署阶段最容易踩的坑集中在权限和并发。macOS 上如果终端没有辅助功能权限，点击命令会静默失败或返回权限错误码；Linux 无头服务器需要先起 Xvfb 并设置 DISPLAY；Wayland 下部分合成器限制输入注入，需要改用 portal 接口。并发方面，同一时刻只应有一个 Agent 操作桌面，多个进程同时移动鼠标会互相打断，建议用文件锁或单例守护进程串行化。日志也要留够：把每次命令的 stdout、返回码、截图路径都记下来，出问题时能回放整条动作序列。最后提醒一句，涉及删除、支付、发送消息这类不可逆操作，一定要在 CLI 外层加人工确认或白名单，别把判断权完全交给模型。
把 agent-desktop 当成一把螺丝刀而不是整套机器人，心态会轻松很多。它负责把桌面变成可编程接口，真正的智能仍然来自你如何设计感知频率、降级策略和失败恢复。先让单步动作稳定可验证，再谈多步规划，这条路走得慢但不容易翻车。
如果这篇对你有用，请扫码关注。
