昆
昆仑AI工具大全KUN.NET
提交工具

agent-desktop 上手：在无显示器的 Linux 上拉起无头桌面，用无障碍树操作计算器和编辑器，再写一个会自我核对的 Python 循环

按 Vercel Labs 官方 agent-desktop 文档整理（1.2.0 实测，无需 API Key）：用 npm 安装并按官方脚本在无显示器的 Linux 上拉起 Xvfb 无头桌面；用 snapshot、find 拿到引用，用 click、set-value 操作 GNOME 计算器和 Mousepad，用 wait 和窗口标题独立核对，处理关闭时的保存对话框；最后用 Python 写出按错误码重试、每步核对的循环，接上会话追踪，并用 skills 和 AGENTS.md 交给编程智能体。

入门3 课时70 分钟图文实操

免费学习无需登录

开始学习 查看课程目录
agent-desktop 上手：在无显示器的 Linux 上拉起无头桌面，用无障碍树操作计算器和编辑器，再写一个会自我核对的 Python 循环 课程封面

你将学会

  • 在无显示器的 Linux 上拉起无头桌面
  • 读懂快照、引用和快照 ID
  • 用 find 和 click 操作桌面控件
  • 用 wait 和 get 独立核对效果
  • 读懂 delivery 与 retry 字段
  • 用 snapshot --surface 处理对话框
  • 用 Python 写出每步核对的循环
  • 用会话和追踪记录一次运行
  • 用 skills 和 AGENTS.md 接入编程智能体

适合谁

  • 给编程智能体加桌面操作能力的开发者
  • 在 Linux 服务器上做桌面自动化的工程师
  • 关注 computer use 的研究者和学生

课前准备

  • 会用 Linux 终端和 apt、npm
  • Linux x86_64 或 ARM64（glibc 2.35+）
  • Node.js 18 或更高
  • 课时 3 需要基础 Python

课程目录

3 课时 · 70 分钟
  1. 01装好 agent-desktop，在无显示器的 Linux 上拉起无头桌面并读懂引用用 npm 安装 agent-desktop 1.2.0；看懂纯终端里 status 为什么是 denied，按官方 Docker 指南的 agent-desktop-run 脚本拉起 Xvfb、openbox 和会话总线；打开 GNOME 计算器，确认它登上无障碍总线；用骨架快照和整窗快照认识引用，并亲眼看到两块一模一样的区域为什么钻取会被拒。图文20 分钟开始本课
  2. 02观察、操作、验证：按计算器、写编辑器、处理保存对话框用 find 找到按钮引用，按出 6×7 并用 wait 等到 42；用 set-value 一次写入算式，弄清 delivered_verified 为什么也不等于程序已接受；往 Mousepad 写字后用窗口标题的星号做第二重核对并截图；关闭程序时遇到保存对话框，用 list-surfaces 和 snapshot --surface 找到 Don't Save 并核对程序已退出。图文25 分钟开始本课
  3. 03写一个会自我核对的 Python 循环，再接上会话追踪和编程智能体用 Python 标准库写一个计算器智能体，按官方规则只在 retry 为 safe 时重试；亲眼看到连按同一个键 6 次错 2 次，改成每按一个键就核对后 6 次全对；认识 INVALID_ARGS、WINDOW_NOT_FOUND 等错误码；用会话和追踪统计一次运行做了什么；最后用 skills get、AGENTS.md 和 npx skills add 交给编程智能体。图文25 分钟开始本课

课程说明

agent-desktop 是 Vercel Labs 开源的桌面「电脑操作」（computer use）命令行工具，Apache-2.0 许可，用 Rust 编写。它不截图、不做像素匹配，而是读取操作系统提供给读屏软件的无障碍树（macOS、Windows 的系统无障碍接口，Linux 上是 AT-SPI），把每个能点、能填的控件编成一个引用（ref），以 JSON 返回；AI 智能体对引用执行点击、填值等操作，再读一次界面核对结果。它本身不带大模型，默认无头运行，不移动鼠标、不抢焦点。Linux 版从 2026 年 10 月 28 日发布的 1.0.0 开始提供，测试时最新版本是 11 月 5 日发布的 1.2.0，GitHub 仓库约 2.2 万星，本周登上 GitHub Trending。同门的 agent-browser 管网页，agent-desktop 管桌面程序。

本课按 agent-desktop 官方文档（安装、Linux 平台说明、Docker 容器指南、快速上手、观察-操作-验证循环、错误与恢复、会话、技能）整理。2026-11-13（Asia/Shanghai）在一台没有显卡、也没有显示器的 Debian 13 x86_64 云主机上，用 npm 安装 agent-desktop 1.2.0，按官方脚本拉起 Xvfb 无头桌面，操作 GNOME 计算器 48 和 Mousepad 0.6.3。课里每一段命令和脚本都实跑过，「对照结果」都是这台机器的真实输出，只做了节选；快照 ID 每次运行都不同，耗时类数字会有小幅出入。课里也如实保留了出错的例子：骨架快照钻取被拒、set-value 写入后被清屏覆盖、连按同一个键在 6 次里丢了 2 次，并给出官方推荐的修法。全程不需要任何 API Key 或付费模型。没有实测的有：macOS、Windows 上的运行，--headed 物理输入，以及由 AI 智能体驱动的完整会话。

课时你会做完的事需要什么
1装好 1.2.0，在无显示器的 Linux 上拉起无头桌面，读懂快照和引用Linux（Ubuntu 24.04+ 或 Debian 13），Node.js 18+
2用观察、操作、验证循环按计算器、写编辑器、处理保存对话框同上，另需 jq
3写一个会自我核对的 Python 循环，学会错误码、会话追踪和技能接入同上，另需 Python 3

适合

  • 想给 Claude Code、Codex 等编程智能体加上「操作桌面软件」能力的开发者
  • 需要在 Linux 服务器或容器里做桌面程序自动化、回归测试的工程师
  • 想弄清无障碍树式 computer use 和截图式方案差别的研究者和学生

先修

  • 会用 Linux 终端，能用 apt 和 npm 装软件
  • 本机或云主机是 Linux x86_64 或 ARM64（glibc 2.35 以上）
  • 课时 3 需要能读懂简单的 Python 和 JSON

你会学到

  • 用官方 agent-desktop-run 脚本在没有显示器的 Linux 上拉起带无障碍总线的无头桌面
  • 用 snapshot、find 拿到带快照 ID 的引用，知道什么时候读整窗、什么时候用骨架加钻取
  • 用 click、set-value 操作控件，用 wait、get 和窗口标题独立核对效果
  • 读懂 delivered_verified、delivered_unverified 和 retry: safe/unsafe
  • 用 snapshot --surface 处理弹出的对话框
  • 用 Python 写出按错误码重试、每步核对的循环，用会话和追踪记录一次运行
  • 用 skills get 和 AGENTS.md 让编程智能体自己学会使用 agent-desktop

官方资料

绑定工具： agent-desktop（https://www.kun.net/tools/agent-desktop/ ）