如何安全重试？agent-desktop 的 Delivery Semantics 递送语义与 disposition 解析

GUI 自动化AI 应用桌面应用AI 技能【免费下载链接】agent-desktopAgent Desktop gives any agent reliable computer use on the desktop. Built with Rust, it sees any apps real UI structure through OS accessibility trees and operates it — refs stay stable and actions stay safe to retry, instead of guessing from pixels.项目地址https://gitcode.com/gh_mirrors/ag/agent-desktop点击查看免费下载agent-desktop是一个基于 Rust 的桌面计算机使用工具它通过操作系统无障碍树读取并操作任意应用的真实 UI为 AI agent 提供可靠的点击、输入和状态验证能力。这篇文章带你从新手视角理解它最关键的可靠性设计——Delivery Semantics递送语义也就是每个操作结果中携带的disposition字段它明确告诉调用方输入到底送达到没有从而决定能否安全重试避免重复点击、重复提交。为什么盲重试是危险的自动化操作中最经典的事故不是失败了而是失败了但输入其实已经到达——你再重试一次就会按钮被点击两次多提交一次订单文本被输入两遍toggle被触发两次把状态又切换回去传统脚本只能靠猜失败了就再试一次。agent-desktop 的做法是把是否送达变成每个结果里的一等公民字段让你从结果本身而不是错误码推断重试安全性。五个递送状态delivery 字段全解核心枚举定义在 delivery_semantics.rs共有 5 种状态状态JSON 值含义 未知unknown无法判断默认值例如非适配器错误 未送达not_delivered输入确认没有到达目标 送达不确定delivery_uncertain可能到达也可能没有 已送达未验证delivered_unverified输入已发出但效果未被确认✅ 已送达已验证delivered_verified输入到达且效果被观察到其中已送达未验证是一个容易被忽视的第三维度输入确实发出去了但应用的效果无法被读取确认例如安全输入框的隐藏值。安全重试规则retry 字段一锤定音与 delivery 平行的第二个字段是retry disposition定义在 retry_disposition.rs只有 3 种取值safe/unsafe/unknown。映射规则非常简单见 delivery_semantics.rs 的 retry 方法只有not_delivered是safe其余所有可能送达的状态一律unsafeunknown对应unknown。换句话说什么都没发生可以自由重试可能发生了绝不允许自动重放。这条规则在 CONCEPTS.md 的 Delivery Semantics 词条中有完整阐述。两个字段序列化为 JSON 对象并带有一致性校验——如果出现已送达却标记可安全重试这种矛盾组合反序列化会直接报错见 delivery_semantics_tests.rs 中的不可能组合测试{ delivery: not_delivered, retry: safe }在实际输出里如何读 disposition成功结果ActionResult自带disposition字段action_result.rs由执行步骤推导——有步骤成功送达但效果未验证时为delivered_unverified验证通过后升级为delivered_verified。错误结果错误载荷同样携带disposition和recovery字段output.rs。关键逻辑在 recovery_for_code只有retry safe时才会附带恢复策略RecoveryHint例如STALE_REF/SNAPSHOT_NOT_FOUND→refresh_snapshot_then_retry_original刷新快照后用新 ref 重试POLICY_DENIED→request_explicit_policy_then_retry_originalAPP_UNRESPONSIVE→inspect_state_then_retry_original并建议等待 250ms只要 retry 不是 safe就不会给出任何自动恢复建议——这是刻意设计调用方必须去检查现场而不是机械重试。这套字段通过 FFI 以稳定的 C 结构体AdDeliverySemanticsdelivery_semantics.rs暴露给 C 和其他语言绑定CLI、FFI 和未来消费者共享完全相同的语义。实战两类典型陷阱陷阱一macOS 右键菜单的假失败在 macOS 上语义化的AXShowMenu可能打开菜单后进入模态跟踪然后返回APP_UNRESPONSIVE此时 disposition 是delivery_uncertainretry: unsafe。菜单很可能已经打开了——正确做法是检查菜单表面而不是再点一次见 macos.md。陷阱二toggle / 状态类操作绝不盲目重复对toggle、check、expand等状态翻转操作未验证的送达尤其危险重复执行可能撤销第一次的改变。官方工作流建议明确写着mutation 超时后先取新快照 读取当前状态再决定下一步workflows.md。一张决策表收尾 你看到的disposition该怎么办retry: safe按recovery.strategy执行放心重试retry: unsafe停止重试读details.post_state/after_action按现场状态行动retry: unknown当作 unsafe 对待先观察再决定核心口诀失败不可怕可怕的是重复送达。agent-desktop 把送达与否的判定权交还给结构化数据让重试决策从猜变成查。延伸阅读概念定义CONCEPTS.md递送语义实现crates/core/src/delivery_semantics.rs错误输出与恢复策略crates/core/src/output.rs交互命令参考skills/agent-desktop/references/commands-interaction.md重试安全决策表skills/agent-desktop/SKILL.md赞分享GUI 自动化AI 应用桌面应用AI 技能【免费下载链接】agent-desktopAgent Desktop gives any agent reliable computer use on the desktop. Built with Rust, it sees any apps real UI structure through OS accessibility trees and operates it — refs stay stable and actions stay safe to retry, instead of guessing from pixels.项目地址https://gitcode.com/gh_mirrors/ag/agent-desktop点击查看免费下载相关推荐IronClaw 消息投递Delivery指南理解 builtin__outbound_deliver、投递证据与 Routine 语义IronClaw 消息投递Delivery指南理解 builtin__outbound_deliver 、投递证据与 Routine 语义 这篇技术指南以人工智能AI 应用交互助手AI AgentFlet Semantics 控件全解析为 Python 应用构建无障碍语义树Flet Semantics 控件全解析为 Python 应用构建无障碍语义树 Semantics 是 Flet 中负责为控件树附加语义注解Semantic前端跨平台桌面应用移动开发任天堂Switch模拟器yuzu从零到上手5步在PC上跑起Switch游戏任天堂Switch模拟器yuzu从零到上手5步在PC上跑起Switch游戏 想让 PC 玩 Switch 游戏yuzu 是目前最流行的开源任天堂 Switc虚拟化图形学逆向工程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考