agent-desktop 的每条命令只打印一个 JSON 信封，然后退出。没有分隔日志、没有进度条、
没有需要正则去掉的前缀——一次调用对应一个可以 JSON.parse 的对象。
成功
{
"version": "2.6",
"ok": true,
"command": "snapshot",
"data": {
"app": "Finder",
"window": { "id": "w-204749", "title": "Downloads" },
"snapshot_id": "s8f3k2p9",
"ref_count": 59,
"complete": true
}
}| 字段 | 含义 |
|---|---|
version |
信封格式的版本，不是二进制的版本。解析逻辑应该跟着它走。 |
ok |
这次调用是否成功。判断成败看它，不要看输出里有没有 error 字样。 |
command |
被执行的命令名。 |
data |
这条命令自己的载荷，结构由命令决定。 |
ok: true 只表示命令返回了成功结果，不表示界面效果已经被验证。动作类命令会在
data.disposition 里说明交付情况，详见下面的 disposition。
失败
{
"version": "2.6",
"ok": false,
"command": "click",
"error": {
"code": "STALE_REF",
"message": "@s8f3k2p9:e7 not found in current RefMap",
"suggestion": "Re-run a snapshot to obtain fresh refs, then retry with the new ref",
"recovery": {
"strategy": "refresh_snapshot_then_retry_original",
"retryable": true,
"requires_fresh_snapshot": true
},
"disposition": {
"delivery": "not_delivered",
"retry": "safe"
}
}
}| 字段 | 含义 |
|---|---|
code |
机器可读的错误码，见错误与恢复。 |
message |
给人读的一句话。不要拿它做分支判断。 |
disposition |
这次失败的处置方式，包含 delivery 与 retry。总是存在。 |
suggestion |
可选。写成可以直接照做的下一步。 |
recovery |
可选。只在 disposition.retry 为 safe 时出现，给出结构化的恢复策略。 |
details |
可选。错误相关的结构化细节，例如 ref 身份失败的 details.kind。 |
error.code、error.message 和 error.disposition 总是存在；suggestion、recovery、
platform_detail 和 details 为空时省略。recovery.retry_after_ms 只在 TIMEOUT 和
APP_UNRESPONSIVE 时出现。
disposition 怎么读
disposition.delivery 说明动作有没有送达，disposition.retry 说明能不能重试：
delivery: "not_delivered"—— 确定没有送达，对应retry: "safe"。delivery: "delivered_unverified"/"delivered_verified"/"delivery_uncertain"—— 可能已经送达或已经送达，对应retry: "unsafe"。delivery: "unknown"—— 这次调用没有建立任何交付证据，retry也是unknown。 不要自动重试。
retry 不是独立判断出来的：not_delivered 对应 safe，其他非 unknown 取值对应
unsafe。只读命令的失败、参数错误和 APP_NOT_FOUND 这类在发送前就失败的查找，都会是
not_delivered。
退出码
退出码用于让 shell 脚本粗筛，细判断仍然要读信封：
| 退出码 | 含义 |
|---|---|
0 |
成功。 |
1 |
结构化错误。JSON 信封仍然打印在 stdout。 |
2 |
命令行解析错误。信封仍然打印，error.code 为 INVALID_ARGS。 |
ok: false 对应退出码 1，不会以 0 退出。需要区分错误类型时读 error.code；
需要决定要不要重试时读 error.disposition.retry。