Agent 工程DeepSeek发布于 2026/11/20作者 koala已人工审核9 分钟

agent-desktop 是什么:原理、功能、DSH Harness 接入与 Computer Use 工具对比

从 Accessibility Tree、Snapshot 与 ref 循环出发,讲清 agent-desktop 如何补足 DSH Harness 的桌面操作能力,并对比 Codex Computer Use、Cursor、Playwright、Chrome DevTools 与传统 RPA。

给 DSH Harness 装上桌面操作能力

前段时间我遇到一个很典型的需求:让 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 的观察、动作与验证循环

理解 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 用来确认窗口是否真的变化。发送消息、提交表单这类动作尤其不能无脑重试;如果返回结果不能证明动作没有发生,应先观察当前状态。

它能做什么,又不能做什么

官方命令大致可以分成几组:

真实业务里,它比较适合三类任务。

第一类是只读检查,例如打开 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 有什么区别

Computer Use 工具选择地图

这些工具经常被放在一起讨论,但它们并不处在同一层。

工具主要范围观察与控制方式最适合的任务主要边界
agent-desktop原生桌面应用系统无障碍树,必要时补充物理输入给不同 Agent 增加本地跨应用操作依赖目标应用无障碍支持和系统权限
Codex Computer UseChatGPT/Codex 中的浏览器与桌面产品内置 Computer Use开箱即用的 GUI 测试、跨应用工作流主要绑定 ChatGPT/Codex 产品体验
Cursor Browser / Computer Use安全 WebView 或自托管 WorkerMCP 扩展、Worker 桌面环境开发流程内浏览器操作、自托管 Agent覆盖范围取决于本地/云端/Worker 模式
PlaywrightWeb 浏览器DOM 和浏览器自动化接口E2E 测试、稳定定位、断言和回归不负责普通原生桌面应用
Chrome DevToolsChrome 网页调试DevTools 与浏览器调试面板Network、Console、DOM、性能排查核心不是跨应用自动化
传统 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。

实际使用时,我建议遵循四条规则:

  1. 第一次只开放 status、list-apps 等只读任务。
  2. 给 Agent 明确目标应用和操作范围,不要说“帮我处理一下电脑上的东西”。
  3. 发送消息、删除文件、提交表单、修改权限、付款等动作必须在执行前确认。
  4. 结构化接口可用时优先用 API、插件或 MCP,只有必须看 GUI 时才使用 Computer Use。

最后总结

agent-desktop 真正有价值的地方,不是让 Agent “看起来像人在点电脑”,而是把桌面操作变成一套可观察、可定位、可验证、可恢复的执行接口。对于 DSH Harness 来说,它补上的正是从代码和命令行跨到原生桌面应用的最后一段路。

如果你已经在使用 DSH,可以先完成 CLI 和 Skill 安装,跑通两条只读验证,再选一个低风险任务尝试跨应用流程。只做网页测试,就继续用 Playwright;需要网页诊断,就用 Chrome DevTools;要让 DSH 操作 Finder、飞书、Excel 或内部桌面客户端,再把 agent-desktop 加进来。工具不必互相取代,把它们放在正确的层级,才是更可靠的 Agent 工作流。

参考资料

参考资料

  1. https://github.com/vercel-labs/agent-desktop
  2. https://agent-browser.dev/desktop
  3. https://learn.chatgpt.com/docs/computer-use
  4. https://cursor.com/docs/agent/tools/browser
  5. https://cursor.com/docs/cloud-agent/self-hosted/computer-use
  6. https://playwright.dev/docs/intro
  7. https://developer.chrome.com/docs/devtools/overview

Continue Reading

相关推荐

继续阅读同一工具与主题下的实战内容。