Mearl 技能

🚀 快速开始

正常任务直接调用，本地与云端命令一致：

mearl get_requests --payload '{"count": 5}'
mearl get_logs --payload '{"limit": 10}'
mearl page_snapshot --payload '{"tabId": 12345}'
mearl page_click --payload '{"tabId":12345,"selector":"#submit"}'

只有命令不可用或连接失败时才执行 mearl check 并读取 连接故障排查，其中包含本地、CDP 直连和云端建联方式；正常任务不要主动探测、重复安装或初始化。

页面操作参数契约

• page_snapshot.query 必须是对象，例如 "query":{"text":"保存","role":"button"}，不能直接传字符串。
• page_click 必须且只能使用 selector / text / point 之一。selector 接受 CSS 或最新快照的 @ref；scope 只用于配合 text，也只接受 CSS 或 @ref，不能传可见标题。clickMode 默认 auto：可见桌面页使用可信 mouse、移动模拟页使用可信 touch，隐藏页使用 DOM fallback，且不切换标签或还原窗口；响应返回 dispatchMode / pointerType / fallbackReason。仅在需要覆盖自动策略时使用 dom / mouse / touch。
• page_scroll 的距离字段是 distance。页面本身不动时，选择目标区域内的 CSS / @ref，并传 containerPolicy: "nearest" 定位最近的可滚动祖先。
• 每次 page_snapshot 都会刷新 @ref。重复目标位于带标题的结构化区域时，先用 query 定位标题，再把返回的 ref 作为 rootRef 并配合 ancestorDepth 获取局部上下文，最后点击目标的新 ref。

其他参数不确定时先运行 mearl <action> --help 或读取 API 参数说明，不要猜测字段名或类型。

浏览器控制默认工作流

1. 确认环境：在首次快照前判断页面形态。用户明确要求移动端/H5，或目标明确是触屏专用页面但当前仍为桌面视口时，先进入移动模拟：新建页面在 tab_open 中传 emulation；已打开页面调用 set_device_emulation，默认 reload 后再建立快照。不要仅凭响应式布局或单一 URL 特征切换模拟。
2. 建立基线：首次进入页面或导航完成后调用一次 page_snapshot。长列表优先 mode: "viewport"；已知区域时用 rootSelector / rootRef；只找单个文案或角色时用 query；只有需要全貌时才用 full。interactive 只保留当前视口内的 AX 语义控件；视口内缺少控件语义时会回退到 viewport，并返回 fallbackMode。
3. 执行并判断：直接调用带内置观察的页面动作。先检查 action.success，再用 requestedTarget / resolvedTarget 判断实际目标，并结合 observation.changed 或 navigation 判断业务效果。delta 观察读取 effects；navigation 检查 ready / settledBy 后用新 URL 重建快照。
4. 按需补充观察：仅当 fullSnapshotRecommended 为 true 时，根据 snapshotReasons 获取最小范围快照，优先顺序为 rootRef、rootSelector、query、viewport、full。page_scroll 的 moved 只证明位置变化；下一步需要读取新视口内容时，即使没有推荐回退，也按需获取 viewport 快照。视觉任务、Canvas、跨域 iframe 或纯视觉变化使用 page_screenshot。changed: true 但 effects 为空不代表失败。
5. 验证终态：对照用户要求检查当前 URL、标题和必要范围的快照；视觉终态使用截图。动作成功、发生导航或到达中间页面都不能单独证明任务完成。

不要在每次动作后固定执行 page_wait、page_snapshot 或 page_screenshot。无需观察结果或排障时可传 observe: false 只执行裸动作；无前置动作的独立等待继续使用 page_wait。详细参数和响应见 API 参数说明。

🎯 意图识别与支持的操作

根据用户的描述，选择对应的操作和参数：

API 调试

Mock & 请求规则

网络请求代理

浏览器操作

组合调用

环境模拟

页面感知

托管浏览器与多账号

💡 实用技巧（易踩的坑）

• 大体积 payload：正文注入、base64 图片等大参数不要拼在命令行里——用 --payload-file <path> 从文件读取整个 payload；或把 payload 里某个字段写成 "@<绝对路径>"，该字段值会从文件读取（先按 JSON 解析、失败按原始文本）。
• 级联菜单 / 悬浮面板（如多级下拉选择）：逐条发 page_click 时命令间隔会让面板收起。用 run_actions 把 hover/click/wait 序列放进一次调用顺序执行；悬浮展开用 page_hover。
• <select> 下拉：用 page_click 点选项文本——命中 <option> 时会自动改写父 <select> 的值并派发 input/change（兼容 React 受控组件），不需要手写 page_eval。
• page_eval 支持 Promise：表达式的值若是 Promise 会自动等待并返回 resolve 结果，fetch(...).then(r=>r.json()) 可以直接作为表达式，不需要写全局变量轮询。
• 结构化能力不足时：用单次只读 page_eval 集中返回最小必要的候选和状态，取得 selector 后立即回到 page_click / page_scroll；直接点击、滚动或修改 DOM 仅作最后手段，需要判断后续变化时传 observe: {}。
• tab_list 同时返回 id 和 tabId，两者值相同；传给其他 action 时使用 tabId。
• 复用标签页：已知目标 URL 时优先调用一次 tab_open 并传 reuse: "prefer"，无需先 tab_list 再自行筛选。多个标签页匹配时默认报错，可缩小 match.urlPattern 或显式传 match.onMultiple: "first"。
• 自定义上传组件：page_upload 直接把文件写入 input[type=file] 节点（DOM.setFileInputFiles），隐藏 input、点击不弹 file chooser 的组件也能上传。

📚 参考文档

• 使用示例（各操作的完整 CLI 调用示例）
• API 参数详细说明（page_click / page_snapshot / set_mock / send_request / get_requests 等完整参数表及响应结构）
• 连接故障排查