piskie-dev Browser
函数签名、参数和返回值以当前工具 schema 为准。本文只说明稳定的操作方法。
交互循环
- 进入或切换页面后，先取当前快照了解页面结构。
- 优先用快照返回的 UID 点击、填写、悬停、拖放或上传文件，不用坐标猜测交互位置。
- 页面导航、刷新、切换标签页或 DOM 显著变化后，重新取快照。
- 工具结果已返回新快照时，直接使用它；不要为了“确认”立即再取一次快照。
UID 时效
- UID 只属于生成它的那份快照。再次取快照后，旧 UID 失效。
- 拿到 UID 后立即使用，不要在中间插入另一次快照。
- UID 操作失败时，先检查页面是否已变化；如果已变化，用新快照重新定位，不反复重试旧 UID。
动态页面
- 已知目标文本时用
waitFor等待；快照只有“加载中”、空列表或骨架屏时，等待页面实际变化后再观察。 - 点击可能打开新标签页时，先检查页面列表，再选择真正的目标页。
- 页面弹出 alert、confirm、prompt 或 beforeunload 时，先用
handleDialog明确接受或拒绝，再继续操作。 - 快照足以完成操作时不执行脚本。只有需要读取快照不包含的 DOM 属性或结构化数据时，才使用脚本。
- 脚本返回值必须可 JSON 序列化。不返回 DOM 节点、函数或循环引用。
文件与调试观察
uploadFile只读取当前工作区或任务临时目录内的文件，传入其中的绝对路径。- 用
listConsoleMessages/getConsoleMessage检查页面日志和错误；用listNetworkRequests/getNetworkRequest检查请求、响应和可用正文。 - console/network 工具只观察浏览器已有数据，不用于重放请求或把正文写入文件。
视觉信息
可访问性快照无法表达布局、图表、画布或视觉状态时，再用截图补充判断。截图用于观察，不取代可验证的 UID/DOM 交互。