爪爪 PawWork live-page action 完全实操手册：3 个核心 op 驱动真实网页-平芜编程栈

爪爪 PawWork live-page action 完全实操手册：3 个核心 op 驱动真实网页

【免费下载链接】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

爪爪 PawWork 是一款开源 Chrome 扩展，用 live-page action 工具直接驱动真实网页：先snapshot给页面控件拍快照，再用fill_form批量填表、click精准点按，让 AI 代理在你已登录的浏览器上替你操作，BYOK、沙箱化、无服务器。

一、live-page action 是什么：先拍快照，再动控件 🐾

普通网页自动化脚本靠 CSS 选择器硬编码，页面一改就崩。爪爪 PawWork 的action工具换了一条路：基于快照的引用（ref）机制。

ref（控件引用）：形如f0.a12——f0是 frame 编号，a12是该 frame 内的控件序号，对模型是不透明 ID，不需要你写选择器。
rev（快照世代）：形如t7，标记这份快照的"代"。页面每次变动后引用就会过期。
回路固定：snapshot拿快照 → 用同一代ref + rev执行fill_form/click等变更 → 每次变更的返回里都会带一份新快照（新rev+ 新controls），继续下一轮操作。

快照采集时，每个 frame 最多收80 个可交互控件（可见优先、隐藏排后），覆盖input、select、textarea、button、a[href]、contenteditable等；密码框的值会被打码为***，避免泄露到模型上下文。实现见 content_script.js。

二、三步加载爪爪：从 clone 到第一次 action 🚀

拿到源码（无package.json、无构建步骤）：git clone https://gitcode.com/gh_mirrors/pa/BrowserKitten
加载扩展：打开chrome://extensions→ 开启右上角开发者模式→加载已解压的扩展程序→ 选择仓库根目录（manifest.json 就在根上，要求 Chrome 135+）。
填入 API Key：打开侧栏粘贴一个 OpenAI 兼容接口的 Key（BYOK，只存在本地chrome.storage.local），然后在任意http(s)页面上直接发任务。

两个顺手的小快捷键（定义在 manifest.json）：

快捷键	作用
`Alt+Shift+S`	开启/关闭"伸爪"页面点选，把选区作为上下文交给代理
`Alt+Shift+C`	区域截图 → 剪贴板 + 对话附件

改过源码后在扩展卡片点重新加载即可。

三、op 详解：snapshot / fill_form / click 怎么用 🔍

模型可用的 op 共 8 个：snapshot/fill_form/click/fill/select/press/scroll/wait（完整 schema 见 tools.js）。你最常用的是前三个：

1. snapshot：给页面"拍张清单照"

不带参数调用action op=snapshot，返回当前 tab 所有 frame 的合并控件清单。清单里每个控件带 role（textbox / button / combobox…）、无障碍名（label、aria-label 或 placeholder）、当前值，以及ref。

使用原则：先 snapshot，再用这份快照的 ref + rev 去变更，不要凭空猜 CSS 选择器。

2. fill_form：一次填好整张表单 ✍️

fill_form的fields支持两种写法：

[{ ref: "f0.a12", value: "…" }]—— 精确引用
[{ name: "搜索框", value: "…" }]—— 用无障碍名回退，命中两个控件会返回AMBIGUOUS

多字段表单按frameId自动拆包分发到对应 frame，一次调用填完所有输入框。之后需要提交时再显式click提交按钮——代理默认不会替你提交表单，除非你明确要求。

3. click：精准点一下 🖱️

click带上最近快照的ref和rev即可。配套动作还有：

fill/select：单字段填值 / 下拉选择
press：按键（Enter、Tab、Escape、方向键、Space…），不指定目标时打给主 frame 的当前焦点元素
scroll：滚动页面
wait：等待某段text出现（上限 5000ms），或纯睡一小段时间（默认 300ms）

作用域与限制（30 秒读完）

action只作用于本轮消息打开的那个 tab（显式tabId），不会偷偷切到 Chrome 焦点标签；缺 tabId 会报NEED_EXPLICIT_TAB。
tab 租约：同一个 tab 正被另一个会话的 execution 占用时返回TAB_LEASED，防止两个会话同时改一个页面。
限制页（chrome://、扩展页、Web Store 等）会返回NEED_PAGE。
chrome://extensions重新加载扩展后，快照世代rev会重置，需要重新snapshot。

四、常见错误码速查：出错了先看这里 🛠️

错误码	含义	怎么办
`STALE_REF`	`rev`对不上或控件已卸载	重新`snapshot`，用新`ref`+`rev`
`AMBIGUOUS`	`name`命中多个控件	改用`ref`精确引用
`NO_TARGET`	无名无 ref / 零命中 / wait 超时	核对快照清单里的名称
`FILE_INPUT`	遇到文件上传控件	脚本填不了，需手动上传
`NEED_PAGE`	限制页 / 无 host	换到普通`http(s)`页面
`NEED_EXPLICIT_TAB`	本轮消息没带 tabId	先打开目标页再发任务
`TAB_LEASED`	tab 被另一会话占用	等另一个会话结束
`BAD_INPUT`	缺`op`/`fields`/`value`等	补齐参数重试

完整契约（参数表 + 错误码）写在 agent/AGENTS.md，跨 frame 扇出与租约的宿主侧逻辑见 src/AGENTS.md。

五、相关文件速览 📂

内容	路径
`action`工具 schema 与执行入口	src/agent/vnext/sessionWorkspace/tools.js
快照采集与 80 控件上限	src/content_script.js
消息总线与跨 frame 运输	src/background.js
产品架构与进程分层	AGENTS.md
安装与测试说明	README.md

一句话总结：snapshot 看、fill_form 填、click 点，三步回路配合rev世代防过期，就能让爪爪 PawWork 在你真实登录态的网页上稳定完成表单填写与点击任务——无需服务器、数据不出本机。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考