docs/computer-use-foundation-contract.md - maka - Git at Google

 # Maka Computer Use Foundation Contract

 状态：Accepted
 适用范围：Desktop foundation；CLI 仅实验性 opt-in；`@maka/headless` 暂不纳入
 目的：定义 stacked PR 不可破坏的合同与验证门。

 外部证据参考（不属于本仓库）：

 - `codex-computer-use-lab/docs/08-wrapper-policy-and-toctou.md`：canonical app approval、pre-await snapshot、approval 与 action freshness 分离；
 - `codex-computer-use-lab/docs/13-policy-error-state-machine.md`：policy → approval → fresh observation → action，以及 intervention/lock/blocked URL 状态；
 - `codex-computer-use-lab/docs/16-service-process-lifecycle-and-retention.md`：exact executable ownership、client/idle lifecycle、connection-loss cleanup；
 - `codex-computer-use-lab/docs/19-electron-presentation-and-mcp-event-contract.md`：presentation 与 native action transport 分离。

 上述文件位于独立逆向实验仓库。本文只记录由 Maka 测试锁定的合同，
 不把外部路径声明为本仓库内链接。

 ## Contract

 1. Observation authority
    - 每个可执行 observation 具有唯一 `frameId + epoch`、截图尺寸、`pid + windowId`、capture-local 坐标信息，以及适用时的 Electron page identity。
    - 坐标只能在产生它的截图/窗口 frame 内解释。dispatch 禁止重新选择当前全局坐标下的最高 z-order 窗口。
    - 新 observation、turn/session 结束、abort、user stop、service loss 和明确 intervention 使旧 action claim 与 keyboard ownership 失效。

 2. Action binding
    - mutation 在第一次异步边界前完成参数快照、规范化、fingerprint、claim，并绑定 active observation。
    - 有顺序依赖的动作按 Computer Use session 串行；不同 session 不全局串行。
    - stale、replay、unclaimed、malformed、targetless action 均 fail closed，不得回退到裸 pixel、foreground activation 或当前系统焦点。

 3. Exact target validation
    - coordinate action 在 dispatch 前验证同一 window identity、geometry、screenshot scale、page identity 和 occlusion。
    - semantic action 优先按稳定 token refetch；否则仅允许唯一且 identity-preserving 的匹配。缺失、歧义、越界、遮挡或 page 变化必须失败。
    - 无关 AX/DOM 内容变化不能合成 `user_intervened`。物理介入和 terminal host state 必须来自明确事件。
    - drag/zoom 两端必须属于同一个 bound window。

 4. Execution ownership
    - maka-cu 是唯一 native executor；window/page discovery、semantic preparation、input dispatch 和 effect readback 均留在该边界内。
    - agent 不得移动真实鼠标、抢前台焦点、临时 activate 窗口或执行 windowless desktop input。
    - keyboard ownership 绑定 `session + turn + generation + pid + windowId + page/frame`，并在失败、stale、新 observation、intervention、service generation 变化、turn/session 结束时撤销。
    - child process 在未知 action outcome 下退出时必须 re-observe，禁止自动重放。

 5. Postcondition
    - mutation 成功后旧 observation 被消费并返回 fresh full observation；可获得视觉状态时向模型返回新截图。
    - transport success 不等于 business success。`verified:true` 必须由 action-specific effect/readback 支撑。
    - `supported:true, ok:false` 为本次 terminal failure；仅 side-effect-free 的 `supported:false` 可进行一次显式允许的 fallback。
    - retry 基于 fresh observation 和新 claim，禁止重试旧 coordinate/fingerprint。

 6. Service lifecycle
    - executable、version、hash、role 和 generation 必须 runtime-observable；dead/mismatched child 不得复用。
    - startup、request、shutdown、restart 均有界；成功恢复后重置连续失败预算。
    - process exit 清理 pending request、observation、keyboard ownership、presentation 和受影响 session lease。
    - capability 反映实时 `healthy / degraded / unavailable`，不能只检查 binary path。

 7. Approval and privacy
    - approval 是 app capability gate，不是 active observation 或 action freshness 证明。
    - Maka 采用分级短 lease：metadata read、screenshot read、pointer mutation、keyboard mutation、semantic mutation 分离；目标、action class、observation 或 session generation 变化时重新授权。
    - approval 至少标明 action class 与目标 app/window；敏感应用、secure/password field 和不支持的目的地 fail closed。
    - screenshot、typed text、coordinate、raw AX label/value、window title、secret 和 raw page content 默认不进入持久 session log、telemetry 或 evaluation report。
    - 上传截图前验证 model vision capability，并满足对应用户/provider consent policy。

 8. Presentation isolation
    - cursor/PiP 位于 targeting 下游，不能选择、转换、授权或改变执行坐标。
    - `readyForInteraction` 只能通过有界 fail-open 策略影响 dispatch 时机；`finished` 不阻塞 native dispatch 或 postcondition。
    - completion 使用 executor-resolved point；失败、abort、teardown、supersede 或缺少 completion point 时必须 cancel。
    - acknowledgement 按 session + action identity 绑定，stale ack 必须忽略。

 ## Validation Matrix

 `PASS`：当前证据直接覆盖；`PARTIAL`：组件证据存在但 production 闭环不足；`FAIL`：当前实现违反合同；`UNKNOWN`：缺少足够证据。

 本矩阵记录 #857 拆分链建立时的基线状态，用于界定各 stacked PR 的验证责任。拆分链合入后，各领域当前状态以源码与合同测试为准。

 | Contract area | 状态 | 当前证据 | 拆分链需要的证据 |
 |---|---|---|---|
 | Frame/window binding、duplicate rejection | PASS | frame state、bound-action、stale/duplicate tests | 在 Runtime slice 保留 focused tests |
 | Capture-local coordinate authority | PASS | window-local transform、scale/geometry、Retina/negative-origin tests | decoy window 下的 cumulative Desktop E2E |
 | Page identity、driver-only executor | PARTIAL | PID-owned CDP/page resolution，无 direct executor bypass | document replacement test；填充 `documentFingerprint` |
 | Semantic identity refetch | PARTIAL | unique refetch、missing/ambiguous rejection | token mismatch 不得接受 replacement control |
 | Occlusion、no foreground/pixel fallback | PASS | coordinate/semantic occlusion 与 fail-closed tests | real-window safety sentinel |
 | Fresh postcondition、effect verification | PARTIAL | mutation 后要求 fresh observation，部分 readback | 所有 advertised mutation 的 cross-layer tests |
 | Per-session queue、generation lease | PARTIAL | session queue/frame claim；lease 修复尚在本地 | concurrent-session 与 intervention-before-dispatch tests |
 | Physical intervention、lock、stop | FAIL | 有状态机原型，无 Desktop production event producer | 真实 host wiring 与 transition tests |
 | Service recovery、unknown outcome | PARTIAL | 本地 service abstraction 与 unit tests | restart reset、attestation、child-crash、cleanup E2E |
 | Approval semantics | FAIL | 旧实现是整 turn scope | 分级 lease、脱敏 permission event、sensitive-target tests |
 | Privacy、telemetry | FAIL | 旧 observation/tool args 可含敏感内容 | persistence/redaction tests；allowlist report schema |
 | Presentation lifecycle | PARTIAL | 本地 candidate 存在；远端 #777 与 #699 相同 | 重建 presentation-only PR 与 cumulative E2E |
 | Provider/model compatibility | PARTIAL | Desktop 默认走统一 function harness | vision gate；每个准入 model 的 real-runtime evidence |
 | Binary provenance | PASS | source/archive/binary/license pinning | 独立 supply-chain verifier |
 | Signed packaged app | UNKNOWN | 无 `.app` signing/notarization/Gatekeeper 证据 | nested helper、TCC chain、cold-start package smoke |

 ## Split Gate

 每个 stacked PR 必须写清：负责的 contract 条款、non-goals、exported interface、focused verifier 和 cumulative verifier。重建从最终已验证 tree 按目标文件/hunk 提取，不机械重放旧 73-commit 历史。

 ## 两个执行器留下的教训

 Maka 在两个 native executor 上做过真机实测：cua-driver（trycua，Rust，MCP）和一个
 自有的 Swift executor（协议 `maka.cu/2`）。下面每一条都由真机实测得出，写在这里是
 因为它们是设计层面的，换执行器不会自动消失。

 ### 协议要封闭，而不是宽容

 cua-driver 的 MCP 面是开放字符串：dispatch tier 要从 path 字符串猜，猜错的每一次
 都落到 `coordinate-background`；错误消息可能带应用文本，于是宿主必须整体脱敏，
 结果是**模型永远只看到错误码**，看不到那句可操作的话。`maka.cu/2` 把这些收成闭
 集（§1.1 的双错误层、§1.2 的固定句子、§6.3 的 tier/path 配对），宿主才敢把执行器
 的句子直接给模型看。

 教训：能让模型自救的信息，往往正是"看起来可能不安全所以被丢掉"的那部分。解法是
 让它在协议层就不可能不安全，而不是在宿主层一刀切。

 ### 两端各写一份的东西，一定会分叉

 坐标动作 100% 不可用，藏了整个开发期。根因：快照侧 `hostWalkTree` 与校验侧
 `HostAXBindingProbe` 各自实现了同一份"摘要输入"字段表，根节点的 `ancestors` 一个
 读活链、一个硬编码空数组。65 个元素差 1 个，窗口摘要就不符，而窗口摘要是坐标动作
 **唯一**的锚。元素动作因为只校验自身，24/24 一直是绿的，完全遮住了它。

 修法不是让两份拷贝再对齐一次（那已经试过一次并且正是这次分叉的来源），而是收敛成
 一条代码路径、规则放在里面。

 教训：凡是"记录时算一遍、校验时再算一遍"的结构，必须共用一个函数。绿灯不覆盖的
 那条路，就是它会坏掉的地方。

 ### 缓存不是查询

 `NSWorkspace.shared.runningApplications` 和 `frontmostApplication` 在没有 AppKit
 run loop 的进程里**永不刷新**。执行器因此看不见任何在它之后启动的应用，而
 `foregroundTaken` 恒为启动时刻的那个值——一个抢了用户前台的启动会如实报告"没抢"。
 所有真机测试之所以一直是绿的，只是因为目标应用碰巧早就在跑。

 教训：在无 run loop 的进程里，AppKit 的任何"当前状态"访问器都要按缓存对待，改用
 `proc_listpids` / 窗口服务这类每次真查的接口。

 ### 上限要有时钟，截断要说出来

 `maxElements` 挡不住慢：由另一个进程托管的 open/save 面板走 1500 个元素花了 35 秒，
 撞穿宿主 20 秒死线被杀，而宿主报的是"执行器已退出"——把排查引向了错的一侧。而且
 截断只进了 trace，模型读到一棵残树会得出"这个控件不存在"。

 教训：任何遍历都要同时有数量上限和时间上限；任何截断都必须出现在**模型读得到的
 地方**，并且要说出它的含义（"可能存在但没列出"），而不只是一个 `truncated=true`。

 ### 不变量要请求，而不是假设

 `apps.launch` 的类型注释写着"启动的应用不得抢焦点"，而实现用的是
 `NSWorkspace.OpenConfiguration()` 默认值——`activates` 默认为 `true`，从来没有请求
 过后台启动。诚实上报那一半是对的（应用自激活时如实报 `foregroundTaken: true`），
 缺的是先去请求。

 教训：一条不变量如果只写在注释里、没有对应的一行代码去请求它，它就不是不变量。

 ### 剪枝要有回退路径才付得起

 Codex 剪得很狠（13 层深的通用容器全收），因为它有 `click{x,y}` 兜底：藏错了元素，
 模型还能按坐标点。Maka 的坐标路径默认关闭，藏掉的元素就是**够不到**的元素。跨 10
 个应用 9129 个元素实测，朴素的"无 label 就剪"会藏掉 3428 个，其中 1023 个
 （占全树 17%）是可操作的。

 教训：能不能剪，取决于剪错了有没有第二条路。没有回退的实现必须比有回退的保守。

 ### 省 token 的地方常常不在编码上

 JSON/YAML 不比"一元素一行 + 缩进"省：实测分别是它的 3.5 倍和 2.1 倍，因为后者把
 包含关系编码成缩进、把默认状态编码成"不写"。真正的浪费在别处——`list_apps` 无条件
 返回 133 个应用（12,933 字节，约 3,600 token，占一个三步回合的 85%），而其中 118
 个根本没有窗口、模型碰都碰不到。

 教训：先量一次真实回合的 token 分布再动手。最大的一笔开销往往不在你正在优化的那
 个字段上。

 ### 措辞补不上不存在的能力

 一条真实任务上的三轮迭代，每轮都把拒绝语句写得更准，模型的调用次数是 32 → 46 → 57。

 任务是「把窗口挪到左边」。移动窗口只能拖标题栏，拖标题栏只能用坐标动作，而坐标动作
 要求目标像素属于目标窗口——Computer Use 驱动的是用户没在看的窗口，后台启动的窗口
 必然压在 z-order 底部，于是必然被遮挡。**这个任务没有解**：协议里没有窗口管理动词，
 而「移动窗口」也不是任何控件的 AX 动作。

 把拒绝语句写清楚之后，模型确实读懂了「这条路不通」，于是去试别的路——而别的路也不
 通，所以试得更多。同一批改动对「导出 PDF」是有效的：那里存在一个正确答案（「做不
 到，因为菜单快捷键到不了后台应用」），模型说出这句话就停了。

 分界线：

 - 存在正确答案（包括「做不到」本身就是正确答案）→ 措辞能把模型引到那里，值得改。
 - 不存在正确答案 → 措辞只会让模型更快地把所有错路试一遍。要补的是能力，不是句子。

 判断方法：先问「一个熟练的人拿着同样这套动作面，能不能做成」。答不上来就先别改文案。
	# Maka Computer Use Foundation Contract

	状态：Accepted
	适用范围：Desktop foundation；CLI 仅实验性 opt-in；`@maka/headless` 暂不纳入
	目的：定义 stacked PR 不可破坏的合同与验证门。

	外部证据参考（不属于本仓库）：

	- `codex-computer-use-lab/docs/08-wrapper-policy-and-toctou.md`：canonical app approval、pre-await snapshot、approval 与 action freshness 分离；
	- `codex-computer-use-lab/docs/13-policy-error-state-machine.md`：policy → approval → fresh observation → action，以及 intervention/lock/blocked URL 状态；
	- `codex-computer-use-lab/docs/16-service-process-lifecycle-and-retention.md`：exact executable ownership、client/idle lifecycle、connection-loss cleanup；
	- `codex-computer-use-lab/docs/19-electron-presentation-and-mcp-event-contract.md`：presentation 与 native action transport 分离。

	上述文件位于独立逆向实验仓库。本文只记录由 Maka 测试锁定的合同，
	不把外部路径声明为本仓库内链接。

	## Contract

	1. Observation authority
	- 每个可执行 observation 具有唯一 `frameId + epoch`、截图尺寸、`pid + windowId`、capture-local 坐标信息，以及适用时的 Electron page identity。
	- 坐标只能在产生它的截图/窗口 frame 内解释。dispatch 禁止重新选择当前全局坐标下的最高 z-order 窗口。
	- 新 observation、turn/session 结束、abort、user stop、service loss 和明确 intervention 使旧 action claim 与 keyboard ownership 失效。

	2. Action binding
	- mutation 在第一次异步边界前完成参数快照、规范化、fingerprint、claim，并绑定 active observation。
	- 有顺序依赖的动作按 Computer Use session 串行；不同 session 不全局串行。
	- stale、replay、unclaimed、malformed、targetless action 均 fail closed，不得回退到裸 pixel、foreground activation 或当前系统焦点。

	3. Exact target validation
	- coordinate action 在 dispatch 前验证同一 window identity、geometry、screenshot scale、page identity 和 occlusion。
	- semantic action 优先按稳定 token refetch；否则仅允许唯一且 identity-preserving 的匹配。缺失、歧义、越界、遮挡或 page 变化必须失败。
	- 无关 AX/DOM 内容变化不能合成 `user_intervened`。物理介入和 terminal host state 必须来自明确事件。
	- drag/zoom 两端必须属于同一个 bound window。

	4. Execution ownership
	- maka-cu 是唯一 native executor；window/page discovery、semantic preparation、input dispatch 和 effect readback 均留在该边界内。
	- agent 不得移动真实鼠标、抢前台焦点、临时 activate 窗口或执行 windowless desktop input。
	- keyboard ownership 绑定 `session + turn + generation + pid + windowId + page/frame`，并在失败、stale、新 observation、intervention、service generation 变化、turn/session 结束时撤销。
	- child process 在未知 action outcome 下退出时必须 re-observe，禁止自动重放。

	5. Postcondition
	- mutation 成功后旧 observation 被消费并返回 fresh full observation；可获得视觉状态时向模型返回新截图。
	- transport success 不等于 business success。`verified:true` 必须由 action-specific effect/readback 支撑。
	- `supported:true, ok:false` 为本次 terminal failure；仅 side-effect-free 的 `supported:false` 可进行一次显式允许的 fallback。
	- retry 基于 fresh observation 和新 claim，禁止重试旧 coordinate/fingerprint。

	6. Service lifecycle
	- executable、version、hash、role 和 generation 必须 runtime-observable；dead/mismatched child 不得复用。
	- startup、request、shutdown、restart 均有界；成功恢复后重置连续失败预算。
	- process exit 清理 pending request、observation、keyboard ownership、presentation 和受影响 session lease。
	- capability 反映实时 `healthy / degraded / unavailable`，不能只检查 binary path。

	7. Approval and privacy
	- approval 是 app capability gate，不是 active observation 或 action freshness 证明。
	- Maka 采用分级短 lease：metadata read、screenshot read、pointer mutation、keyboard mutation、semantic mutation 分离；目标、action class、observation 或 session generation 变化时重新授权。
	- approval 至少标明 action class 与目标 app/window；敏感应用、secure/password field 和不支持的目的地 fail closed。
	- screenshot、typed text、coordinate、raw AX label/value、window title、secret 和 raw page content 默认不进入持久 session log、telemetry 或 evaluation report。
	- 上传截图前验证 model vision capability，并满足对应用户/provider consent policy。

	8. Presentation isolation
	- cursor/PiP 位于 targeting 下游，不能选择、转换、授权或改变执行坐标。
	- `readyForInteraction` 只能通过有界 fail-open 策略影响 dispatch 时机；`finished` 不阻塞 native dispatch 或 postcondition。
	- completion 使用 executor-resolved point；失败、abort、teardown、supersede 或缺少 completion point 时必须 cancel。
	- acknowledgement 按 session + action identity 绑定，stale ack 必须忽略。

	## Validation Matrix

	`PASS`：当前证据直接覆盖；`PARTIAL`：组件证据存在但 production 闭环不足；`FAIL`：当前实现违反合同；`UNKNOWN`：缺少足够证据。

	本矩阵记录 #857 拆分链建立时的基线状态，用于界定各 stacked PR 的验证责任。拆分链合入后，各领域当前状态以源码与合同测试为准。

	\| Contract area \| 状态 \| 当前证据 \| 拆分链需要的证据 \|
	\|---\|---\|---\|---\|
	\| Frame/window binding、duplicate rejection \| PASS \| frame state、bound-action、stale/duplicate tests \| 在 Runtime slice 保留 focused tests \|
	\| Capture-local coordinate authority \| PASS \| window-local transform、scale/geometry、Retina/negative-origin tests \| decoy window 下的 cumulative Desktop E2E \|
	\| Page identity、driver-only executor \| PARTIAL \| PID-owned CDP/page resolution，无 direct executor bypass \| document replacement test；填充 `documentFingerprint` \|
	\| Semantic identity refetch \| PARTIAL \| unique refetch、missing/ambiguous rejection \| token mismatch 不得接受 replacement control \|
	\| Occlusion、no foreground/pixel fallback \| PASS \| coordinate/semantic occlusion 与 fail-closed tests \| real-window safety sentinel \|
	\| Fresh postcondition、effect verification \| PARTIAL \| mutation 后要求 fresh observation，部分 readback \| 所有 advertised mutation 的 cross-layer tests \|
	\| Per-session queue、generation lease \| PARTIAL \| session queue/frame claim；lease 修复尚在本地 \| concurrent-session 与 intervention-before-dispatch tests \|
	\| Physical intervention、lock、stop \| FAIL \| 有状态机原型，无 Desktop production event producer \| 真实 host wiring 与 transition tests \|
	\| Service recovery、unknown outcome \| PARTIAL \| 本地 service abstraction 与 unit tests \| restart reset、attestation、child-crash、cleanup E2E \|
	\| Approval semantics \| FAIL \| 旧实现是整 turn scope \| 分级 lease、脱敏 permission event、sensitive-target tests \|
	\| Privacy、telemetry \| FAIL \| 旧 observation/tool args 可含敏感内容 \| persistence/redaction tests；allowlist report schema \|
	\| Presentation lifecycle \| PARTIAL \| 本地 candidate 存在；远端 #777 与 #699 相同 \| 重建 presentation-only PR 与 cumulative E2E \|
	\| Provider/model compatibility \| PARTIAL \| Desktop 默认走统一 function harness \| vision gate；每个准入 model 的 real-runtime evidence \|
	\| Binary provenance \| PASS \| source/archive/binary/license pinning \| 独立 supply-chain verifier \|
	\| Signed packaged app \| UNKNOWN \| 无 `.app` signing/notarization/Gatekeeper 证据 \| nested helper、TCC chain、cold-start package smoke \|

	## Split Gate

	每个 stacked PR 必须写清：负责的 contract 条款、non-goals、exported interface、focused verifier 和 cumulative verifier。重建从最终已验证 tree 按目标文件/hunk 提取，不机械重放旧 73-commit 历史。

	## 两个执行器留下的教训

	Maka 在两个 native executor 上做过真机实测：cua-driver（trycua，Rust，MCP）和一个
	自有的 Swift executor（协议 `maka.cu/2`）。下面每一条都由真机实测得出，写在这里是
	因为它们是设计层面的，换执行器不会自动消失。

	### 协议要封闭，而不是宽容

	cua-driver 的 MCP 面是开放字符串：dispatch tier 要从 path 字符串猜，猜错的每一次
	都落到 `coordinate-background`；错误消息可能带应用文本，于是宿主必须整体脱敏，
	结果是模型永远只看到错误码，看不到那句可操作的话。`maka.cu/2` 把这些收成闭
	集（§1.1 的双错误层、§1.2 的固定句子、§6.3 的 tier/path 配对），宿主才敢把执行器
	的句子直接给模型看。

	教训：能让模型自救的信息，往往正是"看起来可能不安全所以被丢掉"的那部分。解法是
	让它在协议层就不可能不安全，而不是在宿主层一刀切。

	### 两端各写一份的东西，一定会分叉

	坐标动作 100% 不可用，藏了整个开发期。根因：快照侧 `hostWalkTree` 与校验侧
	`HostAXBindingProbe` 各自实现了同一份"摘要输入"字段表，根节点的 `ancestors` 一个
	读活链、一个硬编码空数组。65 个元素差 1 个，窗口摘要就不符，而窗口摘要是坐标动作
	唯一的锚。元素动作因为只校验自身，24/24 一直是绿的，完全遮住了它。

	修法不是让两份拷贝再对齐一次（那已经试过一次并且正是这次分叉的来源），而是收敛成
	一条代码路径、规则放在里面。

	教训：凡是"记录时算一遍、校验时再算一遍"的结构，必须共用一个函数。绿灯不覆盖的
	那条路，就是它会坏掉的地方。

	### 缓存不是查询

	`NSWorkspace.shared.runningApplications` 和 `frontmostApplication` 在没有 AppKit
	run loop 的进程里永不刷新。执行器因此看不见任何在它之后启动的应用，而
	`foregroundTaken` 恒为启动时刻的那个值——一个抢了用户前台的启动会如实报告"没抢"。
	所有真机测试之所以一直是绿的，只是因为目标应用碰巧早就在跑。

	教训：在无 run loop 的进程里，AppKit 的任何"当前状态"访问器都要按缓存对待，改用
	`proc_listpids` / 窗口服务这类每次真查的接口。

	### 上限要有时钟，截断要说出来

	`maxElements` 挡不住慢：由另一个进程托管的 open/save 面板走 1500 个元素花了 35 秒，
	撞穿宿主 20 秒死线被杀，而宿主报的是"执行器已退出"——把排查引向了错的一侧。而且
	截断只进了 trace，模型读到一棵残树会得出"这个控件不存在"。

	教训：任何遍历都要同时有数量上限和时间上限；任何截断都必须出现在**模型读得到的
	地方**，并且要说出它的含义（"可能存在但没列出"），而不只是一个 `truncated=true`。

	### 不变量要请求，而不是假设

	`apps.launch` 的类型注释写着"启动的应用不得抢焦点"，而实现用的是
	`NSWorkspace.OpenConfiguration()` 默认值——`activates` 默认为 `true`，从来没有请求
	过后台启动。诚实上报那一半是对的（应用自激活时如实报 `foregroundTaken: true`），
	缺的是先去请求。

	教训：一条不变量如果只写在注释里、没有对应的一行代码去请求它，它就不是不变量。

	### 剪枝要有回退路径才付得起

	Codex 剪得很狠（13 层深的通用容器全收），因为它有 `click{x,y}` 兜底：藏错了元素，
	模型还能按坐标点。Maka 的坐标路径默认关闭，藏掉的元素就是够不到的元素。跨 10
	个应用 9129 个元素实测，朴素的"无 label 就剪"会藏掉 3428 个，其中 1023 个
	（占全树 17%）是可操作的。

	教训：能不能剪，取决于剪错了有没有第二条路。没有回退的实现必须比有回退的保守。

	### 省 token 的地方常常不在编码上

	JSON/YAML 不比"一元素一行 + 缩进"省：实测分别是它的 3.5 倍和 2.1 倍，因为后者把
	包含关系编码成缩进、把默认状态编码成"不写"。真正的浪费在别处——`list_apps` 无条件
	返回 133 个应用（12,933 字节，约 3,600 token，占一个三步回合的 85%），而其中 118
	个根本没有窗口、模型碰都碰不到。

	教训：先量一次真实回合的 token 分布再动手。最大的一笔开销往往不在你正在优化的那
	个字段上。

	### 措辞补不上不存在的能力

	一条真实任务上的三轮迭代，每轮都把拒绝语句写得更准，模型的调用次数是 32 → 46 → 57。

	任务是「把窗口挪到左边」。移动窗口只能拖标题栏，拖标题栏只能用坐标动作，而坐标动作
	要求目标像素属于目标窗口——Computer Use 驱动的是用户没在看的窗口，后台启动的窗口
	必然压在 z-order 底部，于是必然被遮挡。这个任务没有解：协议里没有窗口管理动词，
	而「移动窗口」也不是任何控件的 AX 动作。

	把拒绝语句写清楚之后，模型确实读懂了「这条路不通」，于是去试别的路——而别的路也不
	通，所以试得更多。同一批改动对「导出 PDF」是有效的：那里存在一个正确答案（「做不
	到，因为菜单快捷键到不了后台应用」），模型说出这句话就停了。

	分界线：

	- 存在正确答案（包括「做不到」本身就是正确答案）→ 措辞能把模型引到那里，值得改。
	- 不存在正确答案 → 措辞只会让模型更快地把所有错路试一遍。要补的是能力，不是句子。

	判断方法：先问「一个熟练的人拿着同样这套动作面，能不能做成」。答不上来就先别改文案。