mcpField
A
agent-desktop

agent-desktop

github.com/lahfirAgent 工作流1.8k186 次安装1 天前更新
代码仓库

关于 agent-desktop

agent-desktop 是供 AI Agent 使用的命令行技能，通过操作系统的辅助功能树检查和操作桌面应用。它以结构化 JSON 返回命令结果，支持观察、操作和验证流程，默认使用无头语义操作。

主要功能

  1. 01通过辅助功能树检查应用
  2. 02按引用查找和操作界面元素
  3. 03用新快照验证界面变化
  4. 04命令结果采用 JSON 封装
  5. 05默认使用无头语义操作

适用场景

  1. 01通过 AI Agent 自动执行桌面流程
  2. 02操作前检查对话框内容
  3. 03界面操作结果不确定时安全恢复

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/lahfir/agent-desktop --skill agent-desktop

安装后在 Claude Code 中输入/agent-desktop确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
commands-interaction.md
commands-observation.md
commands-system.md
workflows.md

详细介绍

agent-desktop

agent-desktop 是一个 CLI，可让 AI Agent 通过 OS 辅助功能树观察和操作桌面应用。它是一个工具，而不是 Agent。每条命令都会输出一个 JSON 封套（ok、data 或 error）。观察、操作和验证的循环由你来执行。

Shell 语法

示例使用 POSIX shell。在 PowerShell 中，所有 ref 都要加引号（'@s8f3k2p9:e1'），因为裸写的 @token 是 splatting 运算符。使用 $env:NAME = 'value' 代替 export，并使用 | ConvertFrom-Json 代替 $(...) 和 jq。Windows 技能文档中提供了 PowerShell 格式的命令。

首次运行

  1. 运行 agent-desktop status。它会报告平台、权限和 supported_surfaces。
  2. 运行 agent-desktop skills get platform。它会加载二进制文件所运行系统（macOS、Windows 或 Linux）对应的技能。
  3. 如需查看标志和语法，运行 agent-desktop <command> --help。此技能文档不会重复列出标志。

操作循环

已知角色或确切名称时，使用 find。否则，先映射应用，再深入查看某个区域。

agent-desktop snapshot --skeleton --app "Notes" -i --compact   # shallow map, children_count on cut branches
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # drill into one region
agent-desktop click @s8f3k2p9:e12                              # act on a qualified ref
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # verify: re-read the same region
  • 小型应用无需建立骨架。执行完整的 snapshot -i。
  • 切勿为某个表面建立骨架（--surface menu、sheet、alert）。表面已经处于焦点状态。
  • 打开菜单、工作表或警报的操作会在 data.surfaces 中列出该表面。接下来应以该覆盖层为目标。
  • 异步步骤之后，使用 wait（参见 commands-system.md）。固定等待时间可能导致竞态。

Refs

  • 输出的 ref 带有快照限定：@<snapshot_id>:e<N>，例如 @s8f3k2p9:e1。后续命令中直接传入即可。
  • ref 仅在单个快照中有效。任何 UI 发生变化后，都要重新查看受影响区域，或创建新快照。
  • 只有可寻址的元素才会获得 ref。静态文本和不可交互的容器不会获得 ref。
  • STALE_REF：该 ref 已不再对应当前 UI。创建新快照并使用新的 ref。
  • AMBIGUOUS_TARGET：有多个当前元素匹配。使用 find --role --name --exact 或 --root 缩小目标范围，然后使用新的 ref。
  • SNAPSHOT_NOT_FOUND：快照 ID 已过期。重新创建快照。

交付和重试

操作结果包含 data.disposition，错误包含 error.disposition，二者都带有 delivery 和 retry。观察命令（例如 snapshot）成功时不会包含这些字段；此类命令的错误以及所有 INVALID_ARGS 拒绝都会带有 not_delivered 和 retry: safe。

  • 仅当 disposition.retry 为 safe 时，才重试或替换操作。只有 not_delivered 是安全的。
  • 其他任何 delivery 值都表示操作可能已经执行。重复操作可能会再次点击、输入或提交，而 toggle 可能会撤销自身的效果。
  • 对于不安全的结果，读取当前状态（使用 get、is 或新快照），再据此决定。若存在 details.post_state，可借助它判断。
  • 根据 error.code 和 error.disposition 分支处理。消息和建议文本可能会变化。
  • details.retryable: false 表示等待不会改变结果。请尝试其他方法。

无头和有头模式

Ref 操作默认以无头模式运行。它们使用语义辅助功能调用，不会获取焦点、移动光标、合成按键或使用剪贴板。如果不存在语义路径，操作会安全失败。只有在用户明确允许物理输入（例如双击、悬停、拖动或聚焦）时，才使用全局 --headed 标志。切勿为了从无头模式的失败中恢复而切换到有头模式。原始坐标（--xy）不会隐式获取焦点。不同操作是否需要 --headed 因 OS 而异：请阅读对应平台的技能文档。

参考资料

仅在需要时加载：agent-desktop skills get desktop <reference>。

参考资料何时打开
commands-observation需要了解 snapshot、find、get、is、screenshot、list-surfaces 的语义、部分树或 --root 规则时
commands-interaction在 click、type、set-value、select、toggle、scroll、press 和 mouse 命令之间进行选择，或排查操作错误时
commands-system启动或关闭应用、管理窗口、使用剪贴板、wait、batch、会话、多 Agent 光标、跟踪或加载技能时
workflows需要参考表单、菜单、对话框、等待新窗口、scroll-find、拖动等操作模式及反模式列表时

评论

支持 Markdown