
前段时间我遇到一个很典型的需求:让 Agent 先去浏览器搜索资料,再把结果整理到本地编辑器,最后打开飞书准备一条消息,发送前停下来让我确认。
这句话对人来说没什么难度,但对很多 Coding Agent 来说,中间有一道明显的墙。它能读代码、改文件、执行 Shell,也能通过插件调用一些系统接口;可一旦任务进入 Finder、Excel、飞书这类图形界面,原来的工具链就接不上了。
Codex 的 Computer Use 已经把这条链路做进了桌面产品:模型能看见窗口、点击、输入,还能在 macOS 后台处理受限任务。相比之下,DSH Harness 目前更强的是开放的 Harness、工具调用、Skill 和 MCP 扩展,缺少同等开箱即用的本地桌面操作闭环。
这正是 agent-desktop 值得关注的地方。它没有再造一个 Agent,而是给现有 Agent 提供了一双可以复用的“眼睛和手”。
为什么 DSH 需要补一双“眼睛和手”
先把“会执行命令”和“会使用电脑”区分开。
当 DSH 执行 git diff、修改 TypeScript 文件或调用一个 MCP 接口时,输入输出都是结构化的。文件路径、命令结果、JSON 字段都很明确,模型容易判断下一步。
桌面软件不是这样。一个“导出”按钮可能藏在菜单里;点击后会弹出 Sheet;文件保存成功后窗口状态又会变化。Agent 不仅要知道点哪里,还要确认刚才的动作有没有生效,不能因为界面延迟就再点一次。
社区里并不缺“让 Agent 点鼠标”的方案,但成熟度差异很大。有的只支持浏览器,有的主要依赖截图和坐标,有的安装链路较长,还有一些项目对跨平台、失败恢复和权限边界说明得不够完整。评价这类工具,不能只看 Demo 是否点中了按钮,至少还要看六件事:
| 维度 | 真正需要确认的问题 |
|---|---|
| 安装复杂度 | 普通用户能否在现有 Agent 上直接接入 |
| 维护状态 | 是否持续适配操作系统和应用变化 |
| 定位机制 | 依赖像素坐标,还是能识别真实控件 |
| 跨平台 | macOS、Windows、Linux 分别支持到什么程度 |
| 失败恢复 | UI 变化、重复控件、动作超时后如何处理 |
| 安全边界 | 截图、剪贴板、敏感动作和系统权限如何控制 |
agent-desktop 的特点,是把这些问题当作执行层工程来处理,而不是只给模型一套鼠标坐标命令。
agent-desktop 不是新 Agent,而是桌面执行层
agent-desktop 是 Vercel Labs 开源的桌面操作工具。官方给出的定义很直接:让 AI Agent 通过操作系统的 Accessibility Tree 查看和操作 macOS、Windows、Linux 桌面应用。
它不负责理解你的业务目标,也不在内部运行一个大模型。DSH、Codex、Claude Code 或自研 Agent 负责规划,agent-desktop 负责把桌面界面转成结构化数据,再执行点击、输入、滚动等动作。
DSH / Codex / Claude Code / 自研 Agent
↓
agent-desktop
↓
Finder / 飞书 / Excel / 设置
这就是“跨 Agent”的具体含义:上层模型和 Harness 可以替换,底层桌面执行接口不必重新开发一遍。
“跨操作系统”也不是一句空话。它在 macOS 使用 AX API,在 Windows 使用 UI Automation,在 Linux 使用 AT-SPI。上层仍然调用 snapshot、click、type,平台差异由底层 Adapter 处理。当然,这不意味着同一条脚本在三个系统上百分之百通用——应用名称、界面结构和可访问性支持依然可能不同。
一次桌面操作到底怎么发生

理解 agent-desktop,记住五个词就够了:Accessibility Tree、Snapshot、ref、Action、Verify。
1. Accessibility Tree:先读真实控件
操作系统为了支持读屏器和辅助操作,会暴露窗口中的按钮、输入框、菜单、列表和状态。这些结构就是 Accessibility Tree。
相比“截图后猜按钮坐标”,它有两个优势:一是能直接知道某个元素是按钮还是输入框;二是窗口位置变化后,控件身份不必跟着像素坐标一起失效。
但它也有边界。如果应用没有正确暴露无障碍信息,Agent 看到的控件可能不完整,这时才需要截图或 --headed 物理输入作为补充。
2. Snapshot:把当前界面变成 JSON
例如读取 Finder:
agent-desktop snapshot --app Finder -i
命令会返回当前窗口结构,以及可以操作的元素。-i 表示优先保留交互节点,减少无关静态文本。
3. ref:不是随便记一个 @e8
每个可操作元素会得到类似 @s8f3k2p9:e8 的 qualified ref。前半部分属于 Snapshot,后半部分才是元素编号。
agent-desktop click '@s8f3k2p9:e8'
ref 与 Snapshot 绑定。如果 UI 已经变化,旧 ref 可能返回 STALE_REF;如果多个对象无法唯一确定,则可能返回 AMBIGUOUS_TARGET。正确做法不是盲目重试,而是重新读取界面,获得新的 ref。
4. Action:优先语义操作
click、type、select、toggle、scroll 等 ref 动作默认通过无障碍 API 执行,不移动真实鼠标,也尽量不抢焦点。拖拽、物理双击、坐标点击等动作才需要 --headed。
这种设计很关键。后台执行不是“把鼠标移得快一点”,而是尽量通过控件语义直接完成动作。
5. Verify:操作后必须再看一眼
可靠的 Computer Use 不是“命令执行成功就结束”,而是观察—动作—验证循环:
agent-desktop snapshot --app Finder -i
agent-desktop click '@s8f3k2p9:e8'
agent-desktop snapshot --app Finder -i
第二次 Snapshot 用来确认窗口是否真的变化。发送消息、提交表单这类动作尤其不能无脑重试;如果返回结果不能证明动作没有发生,应先观察当前状态。
它能做什么,又不能做什么
官方命令大致可以分成几组:
- 观察界面: Snapshot、查找控件、读取属性、截图、查看菜单或弹窗。
- 操作控件: 点击、输入、选择、勾选、展开、折叠、滚动。
- 键盘鼠标: 快捷键、悬停、拖拽、滚轮和物理点击。
- 应用窗口: 启动或关闭应用、列出窗口、切换焦点、移动和缩放窗口。
- 系统能力: 通知、剪贴板、等待、Session、Trace 和权限检查。
真实业务里,它比较适合三类任务。
第一类是只读检查,例如打开 Finder 查看下载目录、读取桌面应用状态、核对设置项。第二类是跨应用协作,例如浏览器找资料后放进文本编辑器,或下载 CSV 后交给 Excel。第三类是需要 GUI 才能完成的内部系统流程,例如没有开放 API 的旧 ERP 客户端。
它也不是万能的。无障碍树质量取决于目标应用;复杂视觉判断仍可能需要截图;验证码、系统安全授权和高风险确认不能交给 Agent 绕过。真正涉及账户、支付、权限、删除或对外沟通时,仍然需要人在关键动作前确认。
把 agent-desktop 接进 DSH Harness
如果已经安装 DSH Desktop,接入不需要部署服务器。最简单的方式是“本机 CLI + 通用 Agent Skill”。
第一步:检查 Node.js
agent-desktop 当前 npm 包要求 Node.js 18 或更高版本:
node --version
npm --version
第二步:安装 CLI
所有平台都可以使用 npm:
npm install -g agent-desktop
macOS 和 Linux 也可以使用 Homebrew:
brew install agent-desktop
然后检查状态:
agent-desktop version
agent-desktop status
截至 2026 年 11 月 19 日,npm 查询到的最新版是 1.3.1。我本机最初安装的是 1.1.0,因此没有最新 README 已列出的 MCP 子命令。这里也提醒大家:遇到“文档里有、命令里没有”的情况,先核对本机版本,不要立刻判断项目文档写错了。
第三步:安装通用 Skill
为了让 DSH 知道什么时候、怎样使用这套 CLI,可以把官方 Skill 安装到通用 Agent 目录:
npx skills add https://github.com/vercel-labs/agent-desktop \
-g \
--skill agent-desktop \
--agent universal \
--copy \
--yes
完成后新建一个 DSH 会话,让它重新加载 Skill。最新版 agent-desktop 也支持 MCP,但对已经安装 DSH 的普通用户来说,Skill + CLI 的链路更短,先跑通这条路径就够了。
第四步:配置权限
macOS 可以运行:
agent-desktop permissions --guide
然后在“系统设置 → 隐私与安全性”中,为 DSH Desktop 或实际执行命令的终端开启“辅助功能”和“屏幕录制”。Windows、Linux 的权限和前后台行为不同,应以 agent-desktop status 与对应平台文档为准。
第五步:先做只读验证
在新的 DSH 会话输入:
使用 agent-desktop 执行
agent-desktop status,告诉我平台和权限状态,不要操作任何应用。
再试一次:
使用 agent-desktop 查看当前运行的桌面应用,只返回应用名称,不要点击、关闭或切换窗口。
先证明“看得见”,再逐步开放点击和输入,比一上来就让 Agent 发消息安全得多。
和 Codex、Cursor、Playwright、DevTools、RPA 有什么区别

这些工具经常被放在一起讨论,但它们并不处在同一层。
| 工具 | 主要范围 | 观察与控制方式 | 最适合的任务 | 主要边界 |
|---|---|---|---|---|
agent-desktop | 原生桌面应用 | 系统无障碍树,必要时补充物理输入 | 给不同 Agent 增加本地跨应用操作 | 依赖目标应用无障碍支持和系统权限 |
| Codex Computer Use | ChatGPT/Codex 中的浏览器与桌面 | 产品内置 Computer Use | 开箱即用的 GUI 测试、跨应用工作流 | 主要绑定 ChatGPT/Codex 产品体验 |
| Cursor Browser / Computer Use | 安全 WebView 或自托管 Worker | MCP 扩展、Worker 桌面环境 | 开发流程内浏览器操作、自托管 Agent | 覆盖范围取决于本地/云端/Worker 模式 |
| Playwright | Web 浏览器 | DOM 和浏览器自动化接口 | E2E 测试、稳定定位、断言和回归 | 不负责普通原生桌面应用 |
| Chrome DevTools | Chrome 网页调试 | DevTools 与浏览器调试面板 | Network、Console、DOM、性能排查 | 核心不是跨应用自动化 |
| 传统 RPA | 固定浏览器或桌面流程 | 控件、脚本、流程编排或坐标 | 稳定、规则明确、需要审计的业务流程 | 动态目标通常需要预先编排更多分支 |
如果只记一个选择方法,可以按任务来:
- 验证 Web 产品完整流程,优先 Playwright。
- 排查接口、Console 或性能问题,优先 Chrome DevTools。
- 已经在 Codex 中工作,希望直接控制电脑,优先内置 Computer Use。
- 使用 DSH、Claude Code 或自研 Agent,需要操作本地原生应用,考虑
agent-desktop。 - 流程多年不变、要求强审计和确定性,传统 RPA 仍有价值。
Cursor 的情况稍微特殊。它已经有 Browser Tool,也为 Self-Hosted Cloud Agent 提供 Computer Use 和桌面共享,但这不等于“任意本地 Cursor 会话默认就能控制所有原生应用”。使用前仍要看具体运行模式。
DSH 的弱势,恰好也是开放 Harness 的机会
Codex Computer Use 的优势,不只是它能点鼠标,而是整个链路都在产品里:应用权限、审批、后台执行、浏览器、截图、人工接管和安全策略由同一个客户端协调。对普通用户来说,这种一体化体验明显更省事。
DSH 在这方面确实是弱势。至少在当前基础使用链路里,没有同等成熟的内置桌面 Computer Use 入口。社区插件也需要逐个判断,有些擅长浏览器,有些偏坐标自动化,有些还处在快速迭代阶段。
但换个角度,这也是 DSH 的机会。它没有把能力锁死在某个产品内部,而是允许我们通过 Skill、CLI、MCP 和插件补充执行层。agent-desktop 的价值,就是把操作系统差异、控件读取、ref 生命周期和失败恢复集中到一个开源组件里,让 Harness 继续负责它最擅长的规划和工具调度。
所以它不是 Playwright、DevTools 或 DSH 的替代品。更准确的关系是:
DSH 负责思考和编排
Playwright / DevTools 负责 Web 专项能力
agent-desktop 负责原生桌面执行
人在敏感动作前负责确认
本地运行,不等于信息不会离开电脑
“可本地安装”很容易被误解为“完全离线、数据绝不外传”。这两件事不是一回事。
agent-desktop 的执行层运行在本机,但如果 DSH 调用的是云端模型,界面文本、截图或工具结果仍可能进入模型上下文。Snapshot、剪贴板、截图、Trace 和调试文件也可能包含公司内部信息,不应该随手上传到公共日志或 Issue。
实际使用时,我建议遵循四条规则:
- 第一次只开放
status、list-apps等只读任务。 - 给 Agent 明确目标应用和操作范围,不要说“帮我处理一下电脑上的东西”。
- 发送消息、删除文件、提交表单、修改权限、付款等动作必须在执行前确认。
- 结构化接口可用时优先用 API、插件或 MCP,只有必须看 GUI 时才使用 Computer Use。
最后总结
agent-desktop 真正有价值的地方,不是让 Agent “看起来像人在点电脑”,而是把桌面操作变成一套可观察、可定位、可验证、可恢复的执行接口。对于 DSH Harness 来说,它补上的正是从代码和命令行跨到原生桌面应用的最后一段路。
如果你已经在使用 DSH,可以先完成 CLI 和 Skill 安装,跑通两条只读验证,再选一个低风险任务尝试跨应用流程。只做网页测试,就继续用 Playwright;需要网页诊断,就用 Chrome DevTools;要让 DSH 操作 Finder、飞书、Excel 或内部桌面客户端,再把 agent-desktop 加进来。工具不必互相取代,把它们放在正确的层级,才是更可靠的 Agent 工作流。
参考资料
- agent-desktop GitHub 仓库
- agent-desktop 官方文档
- ChatGPT / Codex Computer Use 官方文档
- Cursor Browser 官方文档
- Cursor Self-Hosted Computer Use 官方文档
- Playwright 官方文档
- Chrome DevTools Overview
参考资料
- https://github.com/vercel-labs/agent-desktop
- https://agent-browser.dev/desktop
- https://learn.chatgpt.com/docs/computer-use
- https://cursor.com/docs/agent/tools/browser
- https://cursor.com/docs/cloud-agent/self-hosted/computer-use
- https://playwright.dev/docs/intro
- https://developer.chrome.com/docs/devtools/overview