SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场agent-desktop-windows

agent-desktop-windows

智能体与模型

查看项目

更新于 10-21 05:15

技能介绍

agent-desktop-windows 是 agent-desktop CLI 的 Windows 平台指南。文档说明 observe-act 循环、ref 系统、JSON 信封、会话与跟踪在各平台行为一致，本文件只描述 Windows 上的差异。

用途

面向需要在 Windows 上驱动桌面应用自动化的使用者，说明哪些命令组在 Windows 上可用、哪些会被拒绝，以及首次接触时的常见陷阱。

运行环境与限制

要求 Windows 10 1809+ / Windows Server 2019+（x64 或 ARM64），需在已登录用户的交互式桌面会话中运行。Session 0（服务与 SYSTEM 任务）、Server Core、安全桌面（UAC 提示、登录屏）、锁屏桌面及他人会话不受支持：在这些环境中观测、操作与截图会失败或返回空结果。

主要能力（按命令组）

  • 观测：snapshot、find、get、is、screenshot 可用；界面类型包括 window、focused、以 sheet 表示的 Chromium 模态框，以及以 menu 表示的已打开应用菜单。
  • 界面枚举：list-surfaces 可用，可按进程列出 window、focused 和 sheet 界面，并在菜单打开时提供带 item_count 的 menu 界面。
  • Shell 界面：open-system-surface 可用，可唤起开始菜单、任务栏、系统托盘、托盘溢出区或操作中心，并返回快照所需的窗口标识；quick-settings 返回 PLATFORM_NOT_SUPPORTED 并指向 action-center。
  • ref 交互：click、right-click、type、set-value、clear、select、toggle、check、uncheck、expand、collapse、scroll、scroll-to 可用；无头与 --headed 模式下均为语义投递，但 right-click 是物理点击，未加 --headed 时返回 POLICY_DENIED；type 需要焦点权限，严格无头下返回 POLICY_DENIED。
  • 多击与焦点：double-click、triple-click、focus 需全局 --headed；focus 强制要求 headed。
  • 键盘与鼠标：press、hover、drag、mouse-click、mouse-move、mouse-wheel 可用；移动光标的输入需 --headed；press --app 在验证后写入前台队列（无头下若不在最前则失败关闭；非交互调用方报告 delivered_unverified）。
  • 按住输入：key-down、key-up、mouse-down、mouse-up 在所有平台均以 ACTION_NOT_SUPPORTED 失败关闭，直到由守护进程接管按住输入的生存期。
  • 应用与窗口：launch、close-app、list-windows、list-apps、focus-window、resize-window、move-window、minimize、maximize、restore 可用；launch 解析 System32 或 Windows 目录下的绝对路径或裸名称（带或不带 .exe），不接受显示名称。
  • 显示器：list-displays 可用。
  • 剪贴板：clipboard-get、clipboard-set、clipboard-clear 可用，支持文本与图像内容。
  • 等待：wait 支持 ms、--element、--window、--text、--menu、--menu-closed、--event 和 --notification 谓词。
  • 通知：list-notifications、dismiss-notification、dismiss-all-notifications、notification-action 通过操作中心工作；唤起 Shell 界面的命令会占据前台，操作中心关闭时需加 --headed。
  • 光标叠加：cursor-overlay 可用；enable 渲染点击穿透叠加层，data.rendered 是渲染器自身的管道确认而非仅进程已派生；disable 不带 rendered 字段。
  • 系统：status、permissions、version、batch、skills、session、trace 可用。

使用方式与首次接触要点

  • 在 PowerShell 中引用每个 ref：PowerShell 会把裸 @token 当作 splatting 运算符并删除该参数，因此需写成 set-value '@s8f3k2p9:e1' hi；cmd.exe 与 bash 无需引号。
  • 被其他窗口遮挡的窗口可操作，最小化的窗口不行：其元素均报告 offscreen，ref 操作失败，应先 restore --app <image> 再重新 snapshot；不要习惯性使用 focus-window，它会抢占用户前台。
  • 不存在权限弹窗，permissions 将 automation 报告为 not_required；提权边界是唯一访问控制。
  • Chromium 与 Electron 应用在稳定前读取结果较薄，可给 snapshot 传 --timeout-ms 而不是判定树为空。
  • 默认无头，ref 操作保持语义；只有 --headed 命令会验证精确窗口焦点并合成物理输入。alt+f4、win+l、win+d、alt+tab、win+r、win+x、win+e、ctrl+shift+esc 及修饰键超集在未加 --force 时被拒绝。
  • type 需要焦点权限，是物理按键合成，严格无头下返回 POLICY_DENIED；当字段无可读 Text 选区时以 delivered_unverified 结束（verification_scope: "unavailable"），可用新的 get 确认。
  • press --app 写入前台队列、无按进程定向；无头下对非最前应用失败关闭；非交互调用方（服务、计划任务、CI 任务）得到 delivered_unverified。
  • launch 需要绝对路径或 System32/Windows 目录下的裸名称（如 notepad 或 notepad.exe），不接受显示名称；可用 list-apps 查找正在运行的应用。
  • 通知：操作中心关闭时 list-notifications 需 --headed；单条 dismiss-notification 与 notification-action 需 --headed 并提供 INDEX 条目的 --expected-app 或 --expected-title。
  • 界面：打开或上下文菜单即 menu 界面；Windows 不提供 menubar 界面。
  • 有状态操作执行一次后通过重读验证。delivered_verified 表示回读匹配；ACTION_FAILED 且 details.kind 为 "post_action_verification" 表示操作已落地但回读不同，应读取 details.post_state 而非重试；被应用重新格式化的 set-value 会读作失败。
  • 未签名二进制警告属预期现象。

Windows 差异要点

ref 操作是语义 UI Automation 调用（无头与 --headed 皆然），但 right-click、double-click、triple-click、type、focus 属物理或抢占焦点操作，需 --headed；通知通过操作中心工作且需 --headed；launch 接受绝对路径或 System32/Windows 目录下的裸名称；按住输入命令在所有平台失败关闭；光标叠加只为无头语义操作渲染；组合键中 cmd 与 meta 指 Windows 键，meta+c 是 Shell 快捷键，复制需写 ctrl+c；无头 type 被 POLICY_DENIED 拒绝，应使用 set-value 或加 --headed 通过 SendInput 输入，focus 也需 --headed。

参考文档

references/shell-and-overlay.md（open-system-surface、托盘与任务栏界面、通知、光标叠加、宿主 UWP 窗口标识与菜单检测覆盖）、references/permissions-and-elevation.md（完整性级别、UIPI、被阻止组合、受保护进程、跨进程交互租约）、references/chromium-and-electron.md（稳定时序、遮挡窗口风险、WPF 错误提供程序陷阱、未命名 Web 内容）、references/troubleshooting.md（症状到原因映射、操作验证结果、无头保存文档、安装警告）。可通过 agent-desktop skills get agent-desktop-windows references/troubleshooting.md 从二进制读取任意文件。