深扒 action 契约：爪爪 PawWork 的 ref+rev 快照世代与 8 大错误码

深扒 action 契约爪爪 PawWork 的 refrev 快照世代与 8 大错误码【免费下载链接】BrowserKittenPaw Work - selection-first web agent for Chrome: select on the live page, describe the outcome, take away an editable office file. BYOK, sandboxed, no server.项目地址: https://gitcode.com/gh_mirrors/pa/BrowserKitten爪爪 PawWorkBrowserKitten是一款面向 Chrome 的选择优先 web agent 扩展你在真实页面上选中元素、描述想要的结果它就能驱动页面并把结果做成可编辑的 office 文件。它的action工具是整套浏览器即可编程层的底座——本文深扒 PawWork 的 action 契约refrev快照世代如何防止 agent 误点错控件以及 8 大错误码各自的触发时机与解法帮你读懂这个 Chrome 浏览器自动化 agent 的核心机制。为什么 agent 操作网页需要快照世代让 AI 直接写 CSS 选择器去点击网页控件最典型的翻车方式是页面异步刷新了选择器指向的元素已经变了。PawWork 的做法很朴素但有效——先拍照再动手且只允许在同一代快照内动手。一次action回路固定为三步snapshot扩展扫描当前标签页所有 frame 的可交互控件上限 80 个返回一份带ref的控件清单和一个快照世代号revmutateclick/fill/select/press/scroll/wait/fill_form必须携带最近一次快照的refrev返回新快照每次 mutate 成功后宿主会自动重新 snapshot 并随结果返回新的rev和新controls为下一步操作刷新世代。官方契约就写在 src/agent/AGENTS.md 的「action契约」一节模型参数表、回路规则和错误码全集都在那里。ref rev两把防伪印章拆开看ref控件的不透明身份证。每个控件在所在 frame 内的本地编号是a1、a2……跨 frame 时宿主会加上 frame 前缀变成f0.a12这种形式。解析逻辑见 src/background.js 的parseActionReff{frameId}.a{N}拆开路由到对应 frame本地aN兜底主 frame。注意ref是不透明的——契约明确要求 agent 不要发明 CSS 选择器只能引用 snapshot 里发下来的编号。rev标签页级的快照世代计数器。它保存在 Service Worker 内存的pageActionRevByTab表里src/background.js每次合并 snapshot 后由 stampPageActionRev 递增产出t1、t2、t7这类编号。动手前的校验在 stalePageActionRev这个 tab 还没有任何快照 →STALE_REFsnapshot first传入的rev缺失或和当前值对不上→STALE_REF并附带你拿到的旧编号提示重新快照。换句话说只要 agent 用过期的rev或页面已经翻页导致世代前进写入就会被拒——这是防止AI 在旧世界地图上开新世界的车的第一道闸。顺带一提ref还带 frame 维度多 frame 页面里 prefixFrameRefs 把各 frame 的本地编号统一加前缀fill_form再按frameId拆包分发到对应 frameiframe 里的输入框也能被准确命中。8 大错误码速查表一次看懂 PawWork 的 action 报错完整定义见 src/agent/AGENTS.md覆盖工具层、Service Worker 层和 content script 层三处实现错误码触发时机大白话解读STALE_REF没带rev、rev与当前世代对不上、或控件已从 DOM 卸载快照过期了先snapshot再来AMBIGUOUSname回退命中了多个同名控件别用名字改用 snapshot 里的refFILE_INPUT目标是input[typefile]文件选择器脚本填不了需要用户自己选文件NEED_PAGE页面是chrome://、扩展页、Web Store 等受限页或 frame 消息发不出去当前页面不允许自动化NEED_EXPLICIT_TABaction调用没带本轮的tabIdPawWork 不再默默打 Chrome 焦点标签必须显式指定TAB_LEASED该 tab 正被另一个 session的 execution 占用SW 内存里的 tab 租约锁避免两个会话互踩同一页面NO_TARGET无名无 ref、名字零命中、wait等文本超时、下拉框没有匹配 option找不到目标BAD_INPUT缺op/fields/value/key等必填参数调用参数本身不合法其中TAB_LEASED值得单独说明对 tab 的副作用操作actionsnapshot/mutate、sys.eval、sys.tabs.navigate/reload/focus、sys.cdp等会先在 Service Worker 的tabLeases上 tryAcquire别的会话已占用就拒绝同账号多任务靠这把锁互斥回合结束、中止或关标签时释放规则见 src/AGENTS.md。错误码背后的设计取舍三个细节1. 宁可报错不可瞎猜。缺tabId时 PawWork 不再回退到当前焦点标签而是直接NEED_EXPLICIT_TABsrc/background.js。焦点随时可能被用户切换显式 tabId 是唯一可靠的坐标。2. 世代表活在内存重启即清零。rev存在 SW 内存里Service Worker 被 Chrome 杀掉扩展重载、浏览器重启后pageActionRevByTab整表丢失下一次 mutate 必报STALE_REF——这其实是特性宁可强制重新 snapshot也不让陈旧引用跨进程复活。3. 等待也要带快照回家。wait操作等文本出现或超时NO_TARGET后waitTextAnyFrame 会无条件再跑一次全 frame snapshot 并 attachFreshSnapshot 挂回结果保证 agent 醒来手里永远攥着最新的rev。想继续深挖关键源码地图想搞懂什么看哪里完整契约与错误码定义src/agent/AGENTS.mdrev递增 / 过期校验 / frame 扇出src/background.js各 op 的执行与错误码抛出src/content_script.js模型侧的action工具参数src/agent/vnext/sessionWorkspace/tools.jstab 租约锁TAB_LEASED来源src/agent/vnext/host/tabLease.js回归测试tab 租约、画布冲突等tests/tab-lease.test.mjs、tests/runtime-regression.test.mjs一句话总结PawWork 的 action 契约 不透明ref指到哪个控件 内存rev世代确认页面没变 8 个语义明确的错误码告诉 agent 下一步该干什么。理解了这套先快照、同代操作、失败必回退的纪律你就读懂了 PawWork 敢在真实登录态网页上动手的底气。【免费下载链接】BrowserKittenPaw Work - selection-first web agent for Chrome: select on the live page, describe the outcome, take away an editable office file. BYOK, sandboxed, no server.项目地址: https://gitcode.com/gh_mirrors/pa/BrowserKitten创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考