agent-desktop-windows

agent-desktop-windows

观察-操作循环、引用系统、JSON 封装、会话和追踪在所有平台上都相同。本文档仅介绍 Windows 上的差异。

需要 Windows 10 1809+ / Windows Server 2019+（x64 或 ARM64）。请在已登录用户的交互式桌面会话中运行。服务和 SYSTEM 任务所在的会话 0、Server Core、安全桌面（UAC 提示、登录屏幕）、锁定的桌面以及其他用户的会话均不受支持：这些环境中的观察、操作和捕获会失败或不返回任何内容。

功能表

组	命令	Windows 上的状态
观察	snapshot、find、get、is、screenshot	可用。界面包括 window、focused、作为 sheet 的 Chromium 模态窗口，以及打开的应用程序菜单 menu
界面	list-surfaces	可用。按进程列出 window、focused 和 sheet；菜单打开时还会列出带有 item_count 的 menu
Shell 界面	open-system-surface	可用于 start-menu、taskbar、system-tray、system-tray-overflow 和 action-center，并返回 snapshot --surface <kind> 读取的窗口。quick-settings 会返回 PLATFORM_NOT_SUPPORTED，并指出 action-center
引用交互	click、right-click、type、set-value、clear、select、toggle、check、uncheck、expand、collapse、scroll、scroll-to	可用；在无头和 --headed 模式下均支持语义操作。right-click 和 type 需要 --headed，在无头模式下会返回 POLICY_DENIED
多次点击和焦点	double-click、triple-click、focus	仅在全局启用 --headed 时可用
键盘和鼠标	press、hover、drag、mouse-click、mouse-move、mouse-wheel	可用。需要移动光标的输入操作必须使用 --headed。First Contact 介绍 press --app
按住输入	key-down、key-up、mouse-down、mouse-up	所有平台均会安全失败并返回 ACTION_NOT_SUPPORTED。无头模式下的 mouse-down 或 mouse-up 会先返回 POLICY_DENIED
应用和窗口	launch、close-app、list-windows、list-apps、focus-window、resize-window、move-window、minimize、maximize、restore	可用。First Contact 介绍 launch 接受的名称
显示器	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	可通过操作中心使用。操作中心关闭时请传入 --headed
光标叠加层	cursor-overlay	可用。只有渲染器通过管道确认后，enable 才会返回 data.rendered: true。参见 references/shell-and-overlay.md
系统	status、permissions、version、batch、skills、session、trace	可用

初次使用

• 在 PowerShell 中，所有 ref 都要加引号。 PowerShell 会将未加引号的 @token 视为展开运算符，并在二进制文件接收参数前将其删除，因此 set-value @s8f3k2p9:e1 hi 会报错 INVALID_ARGS。应写作 set-value '@s8f3k2p9:e1' hi。cmd.exe 和 bash 无需加引号。
• 被其他窗口挡住的窗口仍可操作，最小化的窗口则不行。 最小化窗口的所有元素都会报告 offscreen，对 ref 执行操作也会失败。运行 restore --app <image> 并重新获取快照。不要不加思考地使用 focus-window：它会抢占用户的前台窗口。
• 不存在权限对话框。 permissions 会将 automation 报告为 not_required。访问控制仅由权限提升边界决定。
• Chromium 和 Electron 应用在稳定下来之前，读取到的界面内容可能不完整。 为 snapshot 传入更长的 --timeout-ms，不要就此断定界面树为空。
• 受限快捷键。 alt+f4、win+l、win+d、alt+tab、win+r、win+x、win+e、ctrl+shift+esc 及其包含更多修饰键的组合，若不带 --force 都会被拒绝。在组合键中，cmd 和 meta 都表示 Windows 键，因此 meta+c 是 shell 快捷键。复制请使用 ctrl+c。
• type 需要 --headed。 它通过 SendInput 合成击键，因此严格无头模式下的 type 会返回 POLICY_DENIED。请使用 set-value，或传入 --headed。如果字段没有可读取的 Text selection，操作会以 delivered_unverified 结束（verification_scope: "unavailable"）；如果有可读取的 Text selection，则可以验证：使用新的 get 确认。
• press --app 会写入前台队列，不会针对特定进程。无头模式下，若目标应用并非最前方的窗口，操作会安全失败。非交互式调用方（服务、计划任务、CI 作业）会收到 delivered_unverified。
• launch 接受绝对路径，或 System32 或 Windows 目录下的裸名称；名称可带或不带 .exe（notepad 或 notepad.exe），但不能是显示名称。使用 list-apps 查找正在运行的应用。
• **通知：**关闭操作中心时，list-notifications 需要 --headed。对 INDEX 处的条目执行单项 dismiss-notification 和 notification-action，需要 --headed 以及 --expected-app 或 --expected-title。
• **界面：**打开的菜单或上下文菜单属于 menu 界面。Windows 不会提供 menubar 界面。
• 会显示 shell 界面的命令会占据前台。 严格无头模式会在显示任何内容前拒绝此类命令，并返回 POLICY_DENIED。
• 有状态的操作只运行一次，然后通过重新读取进行验证。 delivered_verified 表示回读结果匹配。若出现 ACTION_FAILED 且 details.kind: "post_action_verification"，则表示操作已生效，但回读结果不同：读取 details.post_state，不要重试。如果应用会重新格式化内容，set-value 会被判定为失败。参见 references/troubleshooting.md。
• 未签名二进制文件的警告属于预期情况。 参见 references/troubleshooting.md。

Windows 上的差异

• 无头模式和 --headed 模式下，ref 操作都是语义化的 UI Automation 调用；但 right-click、double-click、triple-click、type 和 focus 除外，它们需要实体输入或会切换焦点，因此需要 --headed。
• 光标叠加层只会在无头语义化操作期间播放每次操作的移动动画。--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。