Skip to content

computer-use-foundation-contract.md

Latest commit

 

History

History
266 lines (203 loc) · 19.5 KB

computer-use-foundation-contract.md

File metadata and controls

266 lines (203 loc) · 19.5 KB
Raw

Maka Computer Use Foundation Contract

状态：Accepted 适用范围：Desktop foundation；CLI 仅实验性 opt-in；Eval subject 通过 Runtime Host 继承同一边界 目的：定义 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 分离。
  • codex-computer-use-lab/docs/22-native-ax-diff-refetch-and-instance-isolation.md：stable AX revision ids、ordered difference、no-change 与 full fallback。

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

Contract

  1. Observation authority

    • 每个可执行 observation 具有唯一 frameId + epoch、截图尺寸、pid + windowId、capture-local 坐标信息，以及适用时的 Electron page identity。
    • 同一窗口跨 revision 的模型 element id 可以稳定，但它只是 presentation identity；每次 dispatch 仍必须解析到 fresh snapshot 的 opaque token。
    • WebContent/renderer 元素同时绑定 host process generation 与 actual input-owner generation；唯一真实 WebContent 元素会遮蔽同框叶子 mirror，歧义 mirror 不删除。
    • 坐标只能在产生它的截图/窗口 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。
    • WebContent click 只有在 host/window 与 renderer generation 都验证后才能走 skylight_pid；失败不得退回 AX mirror 或 JavaScript click。

  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 authoritative observation；完整当前元素树保留在 observation 内，可获得视觉状态时向模型返回新截图。
    • immediate post-action model text 可以使用 executor 声明的 no-change/difference/full presentation；显式 observe 仍显示完整树，差分不得成为重建当前状态的唯一来源。
    • 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 必须忽略。

Renderer semantic source contract

Maka 自己的 Electron renderer 也是 Computer Use 的目标。它不能依赖截图或运行时注入 来弥补页面语义；角色、名称、状态和 landmark 必须由页面本身提供。

  • 一个可见窗口只暴露一个 main landmark。AppShell 已拥有主 landmark，聊天页、 Skills、MCP、定时任务和每日回顾必须作为有名称的 region 出现在其内部，不能再嵌套 第二个 main。
  • 每个可操作 AX node 必须有非空 accessible name。选中导航使用 aria-current，标签页 使用 aria-selected，展开态、禁用态、忙碌态和表单状态由原生元素或对应 ARIA 状态 暴露。
  • 同一层级的 region 不使用相同名称表示不同语义。例如新任务页面 region 与内部空态 hero 分别命名为“新任务对话”和“开始对话”。
  • Astryx 自带文案进入中文 accessibility tree 前必须经过 packages/ui/src/astryx-i18n.tsx。新增 Astryx surface 时，不能让英文 fallback 静默进入中文 Computer Use observation。
  • 不添加生产环境 DOM walker、MutationObserver、定时轮询或额外 a11y 依赖来修补以上 问题。语义随现有 JSX 渲染，运行时开销只限原生 DOM/ARIA 属性。

验证分四层：

  1. TypeScript 与 Storybook 构建保证语义属性、文案契约和非默认状态 fixture 能随产品 API 一起演进。不要重新引入基于正则的 JSX 源码扫描器；它无法可靠理解组件语义，主干已用 真实 AX 验证取代这类检查。
  2. scripts/ax-tree-audit.mjs 是 Storybook 与 Electron E2E 共用的测试侧 AX 规则源， 拒绝无名或同一语义作用域内歧义的可操作 node、多 main、无名 dialog，以及缺少 checked/selected/expanded/value 的状态控件。
  3. apps/desktop/e2e/accessibility-coverage.spec.ts 读取真实 Electron Chromium AX tree， 从运行时设置导航枚举所有设置页，并覆盖模块页、全局弹窗、会话页和 7 个工作栏面板。
  4. scripts/storybook-visual-smoke.mjs 对 Storybook 全目录读取 AX tree，执行 play 函数到最终态，并验证 modal 焦点、隐藏/惰性 surface 和关键 Computer Use story inventory；名字含 narrow 的故事必须在窄视口运行。独立 WebContentsView 由 apps/desktop/scripts/browser-observe-act-smoke.mjs 走真实 observe → semantic ref → act → effect 闭环，不能伪装成 renderer tree 的一部分。

完整页面、状态、动作与性能边界清单见 docs/computer-use-ui-coverage.md。

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
WebContent / renderer target PASS actual PID + start time、coalition readiness、mirror 去重；精确 pin 的 5 轮 OOP 全部 skylight_pid、isTrusted=true、单 down-up，30 个 sentinel span 零前台样本 扩到真实 Electron/Chromium app matrix
Semantic identity refetch PASS renderer frame-only reflow 仅允许同进程世代 unique replacement；missing/ambiguous fail closed；native frame change 继续拒绝；真机全部零误点 保留跨 toolkit 录制回归
Stable AX revision / post-action diff PASS DFS stable ID、跨 fresh token 继承、ordered changes、removed ranges、no-change/full fallback；host 显式 observe 保持 full 增加真实长树 token-saving trajectory 样本
Modal / multi-window routing PARTIAL app→sheet、exact secondary、button/scroll/close 功能矩阵 5/5；精确 pin 的高频 sentinel 捕获 1,738 个 target-frontmost 样本，后台安全未通过 修复原生 AX press 的瞬时前台抢占，再重跑同一聚合矩阵
Occlusion、no foreground/pixel fallback PASS coordinate/semantic occlusion 与 fail-closed tests real-window safety sentinel
Fresh postcondition、effect verification PARTIAL mutation 后 fresh observation；5 轮 primary oracle=1、slider 业务值/readback=42、scroll tree delta + oracle=76 继续补 secondary action 与跨窗口业务 oracle
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 / 窗口服务这类每次真查的接口。

WebContent 不是把事件 PID 改掉

WKWebView 的 AX 树和 XPC process 不是同时出现的。只按进程名找 WebContent 会撞到别的 应用，只把 CGEvent.postToPid 改投 renderer 又完全没有事件。当前闭环分三层：

  • XNU resource + jetsam coalition 只负责证明 host 到 WebContent 的唯一归属，并触发 一次 250ms bounded re-observe；
  • observation 只删除同框、同语义、唯一且为叶子的 host mirror；
  • event 仍绑定 host CGWindowID，通过单通道 private SkyLight 交给 WindowServer 做 renderer hop；actual PID/start time 是元素身份和 restart fence。

教训：OOP targeting 是 process identity、window identity 和 event routing 的联合 问题，不是一个 PID 字段。

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

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」是有效的：那里存在一个正确答案（「做不 到，因为菜单快捷键到不了后台应用」），模型说出这句话就停了。

分界线：

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

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