@mearl/client 3.0.0-beta.1 → 3.0.0-beta.10

package/dist/guides/api-page-automation.md

@@ -0,0 +1,140 @@
+# Mearl 场景：常规网页自动化
+
+普通操作遵循 [核心工作流](./core.md)。本文件用于复杂控件、派发差异、文件操作或增量结果不足以决策的情况。布局、iframe、脚本与视觉验证见[页面排障](./api-page-debugging.md)，设备/App 联动见[环境准备](./api-page-environment.md)。
+
+## 打开与复用页面
+
+`tabId` 标识当前浏览器与传输中的页面，取得后持续复用；控制会话通过 `--session` 固定目标与控制归属，页面动作仍传 `tabId`。`opened` / `reused` 区分新页与既有页，复用页应保留。移动态或 App 态首屏需在新建时设置；这些配置不应用于复用页，已有页使用对应设置 action。
+
+需要激活已有页面时，对同 URL 使用 `reuse: "require", active: true`，避免另外新开页面。激活方式与临时状态恢复见[浏览器控制与人工交接](./api-browser-setup.md#control-sessions)。
+
+## 快照范围与非语义控件
+
+优先 viewport、局部根节点或 query，避免长页面完整输出；每次快照后只使用本次返回的新 ref。
+
+快照文本中的 @eN 可直接用于后续操作，内部节点映射只保存在运行时；无名称、无 ref 且无状态的分组会折叠，控件状态与文本内容保留。
+
+AX 空或稀疏时显式使用 dom；interactive 无 AX 控件时只回退到 AX viewport，不会自动切换来源。后台弹层仍在过渡时，等待明确可见条件，或用 full + query 核验结构。
+
+自定义复选框、单选框或开关没有原生/ARIA 语义时，AX 可能只返回相邻文案。以文案 ref 为根，用 dom 和 ancestorDepth 1–3 获取局部容器，从其中浏览器标记的 clickable ref 定位控件，不直接点击静态文案或猜 CSS。用观察、局部快照或 inspect 验证状态。
+
+<a id="observe"></a>
+
+## 动作结果判读
+
+交互 action 默认返回动作与增量观察。`page_eval` 默认裸执行，`run_actions` 的步骤不带内置观察。
+
+`observe: false` 且未开启 diagnostics 时返回裸动作结果，没有 `action` 或 `observation`；开启 diagnostics 时返回 `{ action, diagnostics }`。按实际返回结构判断，不将缺少 `action.success` 当作失败。
+
+- **未派发**：`action.stage: "precondition"` 时按 error 修正输入；过期 ref 重建最小快照。此时没有 observation/diagnostics。
+- **确认不确定**：`dispatch-uncertain` 时先看 attempt 中的请求目标、解析目标、命中、坐标、派发模式和输入序列确认状态，再用 observation 或最小快照判断是否已生效，确认未生效后才重试。attempt 本身不证明效果。
+- **目标差异**：`resolvedTarget`、`dispatchTarget`、`hitTarget` 只在目标存在有效差异时展开；兼容字段 tag/text 或 strategy/distance 的省略不表示缺少派发。无法确定可点击祖先时，actionableAncestorCandidates 仅供检查，不会自动改点。
+- **通知**：effects.notifications 是高置信度通知；transient 表示已出现后消失，只读取文案，不继续点击。
+- **控件与焦点**：effects.interactives 和 effects.focus 的 node.ref/selector 可继续操作。recreated 是同一语义控件被框架重建，不是新业务入口；状态未变时不会重复返回 value/checked。
+- **普通文本**：effects.texts 按需返回短小可见文本的 selector 和当前 text，例如独立计数或金额；不推断业务含义，也不代表可点击。最多 8 项、每项 160 字符；隐藏、遮挡、复杂结构或超限时仍按快照建议核验。
+- **快照建议**：按 fullSnapshotRecommended 和 snapshotReasons 补最小范围内容。已有通知/控件仍可能遗漏未分类结构；changed=true 而 effects 为空只说明没有高置信度信号，不能直接判失败。
+- **导航**：mode=navigation 中 loaded 只表示文档完成，ready 才表示可继续。network-idle 表示相关请求静默；content-stable 是长连接情况下按内容与 skeleton/busy 状态判断的就绪兜底。
+- **上下文重建**：mode=unavailable 时重新建立快照。delta 的 URL/标题未变化时可省略；同页请求用 network.ready/settledBy/pendingRequests 判断。
+- **新页面**：openedTabs 只报告当前目标 Tab 直接打开的页面。ready=true 时直接对其 tabId 建立快照，无需 tab_list。
+- **观察稳定**：quiet 已有限等待仍运行的动画；无限动画不阻塞。no-change 不自动要求快照；timeout 结合 snapshotReasons 回退。
+
+DOM 增量覆盖主文档（scope=main-document）；iframe、Shadow DOM、Canvas 或纯视觉变化可能不在覆盖范围。按目标补局部快照，跨域 iframe 或视觉任务用截图。
+
+## page_click
+
+文本多匹配时按候选 role/name 缩小范围或取 ref；原生 select 可按 option 文本点击，无需脚本改值。
+
+auto/dom 对原生 option 执行选择并触发 input/change，返回 `selectionState.valueBefore/valueAfter/selectedAfter`。这是事件派发后的即时状态；`selectedAfter` 为 false 表示选项未保持选中（例如页面处理器恢复了旧值），先检查页面再决定下一步。后续异步变化仍需按业务状态核验。禁用的 select、option、optgroup 不会被强行选择。自定义 ARIA option 仍走普通点击。
+
+selector/ref 目标被嵌套容器裁剪时会先滚入可见区；仍裁剪或被弹层覆盖则返回前置条件错误。用 page_inspect 的 hitTest.occludedBy 确认遮挡。派发前的命中检查允许目标自己的祖先/后代。
+
+auto 在可见页按设备使用可信 mouse/touch，在隐藏页回退 DOM；响应的 dispatchMode、pointerType、fallbackReason 说明实际路径。显式 touch 要求可见，显式 mouse 会强制尝试可信输入；只有任务明确依赖真实用户手势时才激活。
+
+## page_drag
+
+起点自动滚入视口，但终点需同时可见；否则先滚动。坐标适合 Canvas 或组件内手势，ref 适合可见元素拖放。DOM 回退属于不可信事件；页面拒绝不可信事件时再接管为可见页可信输入。
+
+## page_type
+
+填写表单后根据 observation 检查目标值及联动控件；不要仅以输入成功判断表单已提交。
+
+## page_hover
+
+hover 展开菜单后需根据内容选择下一步时逐步执行；目标已确定且紧接点击时可用 run_actions。
+
+## page_press
+
+先确认焦点；隐藏页 DOM 输入只实现部分默认行为，依赖编辑、选择、方向键或页面滚动时用可见页 keyboard。用 defaultAction 判断是否模拟了所需语义。
+
+原生 alert/confirm/prompt/beforeunload 会阻塞页面 JS。内置扩展与 CDP 路径通过 `page_snapshot` 返回 `dialog.id/type/message/defaultPrompt`，不运行 DOM 快照；中断回执中的弹窗文本有长度上限，完整读取时按需提高快照 `maxChars`。确认含义后用现有按键接口显式处理：
+
+```bash
+mearl page_press --payload '{"tabId":12345,"dialogId":"<dialog.id>","key":"Escape"}'
+mearl page_press --payload '{"tabId":12345,"dialogId":"<dialog.id>","key":"Enter","promptText":"仅用于 prompt"}'
+```
+
+普通 Enter 不处理原生弹窗；过期 ID 会拒绝，不自动接受或重试。该分支返回裸按键结果 `dispatchMode:"native-dialog"`，不进入 DOM 观察。处理后重新读页面：页面中已派发的 JS 可能继续执行，工具不会回放旧动作。动作已确认成功、仅后续观察被弹窗打断时，保留 `action.success:true` 并附带 `dialog`；没有确认回执时按 `dispatch-uncertain` 核验业务状态。
+
+只能读取监测连接收到的弹窗事件。首次附加前已打开、由其他调试连接持有的弹窗可能阻塞 Chrome 的 Page.enable；此时有界超时并提示人工关闭后重试，不猜测弹窗内容或盲目接受。弹窗文本存储上限 65536 字符，超出时返回 `truncated:true`。
+
+接受 prompt 时省略 `promptText` 会保留预填默认值，显式传 `""` 才清空；默认值超出存储上限时必须显式指定 `promptText`，避免提交被截断的值。
+
+## page_scroll
+
+用 moved、atTop/atBottom 判断是否移动或到达边界；自动发现内部容器时复用 containerSelector。ref 指向子节点时可使用 nearest 找可滚动祖先。需要读取滚动后的新视口时补 viewport 快照。
+
+## page_wait
+
+没有前置动作，或 observation 表明仍需等待且已有明确条件时再调用；以 selector/text/condition 表达业务就绪，固定时间只用于任务本身要求经过一段时间的情况。
+
+服务端渲染页面的节点出现不等于客户端已可交互；需要时等待已确认的业务就绪信号（例如倒计时开始更新），避免输入被后续初始化覆盖。
+
+等待结束后需要立即点击已确认目标时，在同一次 `mearl run` 中 await 等待并紧接点击，不把两个动作拆到不同模型轮次：
+
+```bash
+mearl run --session '<sessionId>' --timeout 240 <<'JS'
+const tabId = 12345;
+const ready = await mearl.pageWait({
+  tabId,
+  condition: '!!document.querySelector("form button[type=submit]:not(:disabled)")',
+  timeout: 200000,
+  interval: 100,
+});
+if (!ready.waited) throw new Error('Target did not become ready');
+console.log(await mearl.pageClick({ tabId, selector: 'form button[type=submit]:not(:disabled)' }));
+JS
+```
+
+整体 `--timeout` 要覆盖等待时限及后续动作；条件等待最多 300000ms。这会省去模型往返，但两次动作仍有传输与派发延迟，不保证原子执行。点击后检查动作结果与业务确认状态；失败或派发不确定时不要自动重放整段脚本。
+
+## page_navigate
+
+在同一 tabId 中导航、刷新或前进/后退，完成后建立新快照。
+
+<a id="file-operations"></a>
+
+## page_upload
+
+找到 input[type=file] 后直接上传，隐藏节点也可用。文件来源按以下方式指定：
+
+- 调用方文件：`files:[{filePath:"/absolute/path"}]`，自动中转到浏览器宿主。
+- 浏览器产物：`files:[{artifactId}]`，使用 `page_download` 返回的产物；会话产物继续使用所属会话。
+- 浏览器或 Provider 宿主文件：`filePaths:["/absolute/path"]`，路径属于执行上传的宿主；外部平台的文件中转按 Provider 帮助执行。
+
+`files` 与 `filePaths` 互斥。确认页面显示附件或上传成功的业务状态；外部 Provider 的文件能力按其当前帮助执行。
+
+## page_download
+
+先监听下载，再执行 `trigger` 点击并等待下载完成。`trigger` 使用不含 `tabId` 的 `page_click` 参数；目标页面由顶层 `tabId` 指定。
+
+`--output <绝对路径>` 将文件保存到调用方；省略时返回 `download.artifactId`，文件保留在浏览器宿主，可用于后续 `page_upload`。扩展无法通过 referrer 确认下载来源时，传入已知 `url`。下载超时或归属不确定时，先检查浏览器下载状态，再决定后续操作，避免重复点击。
+
+## 文件产物与传输
+
+文件中转的单文件上限为 256 MiB。Extension/CDP 支持上传与下载；外部 Provider 按 `capabilities.actions` 声明的 `page_upload`、`page_download` 使用对应能力。无会话产物空闲一小时回收，会话产物默认随 `browser_release --session <sessionId>` 清理，需要保留时传 `keepArtifactIds`。宿主退出清理暂存文件，保存到调用方的结果文件保留。
+
+## run_actions
+
+仅批量执行无需中间判断的紧密序列。失败时只检查已完成步骤与 failedStep；后续步骤未执行，不能将部分成功当作整个任务完成。
+
+连续填写等已知步骤可在同一次 `mearl run` 中使用 `observe:false`，最后检查提交前的表单状态或结果页；需要根据中间结果选目标时保留逐步观察。快照 `query` 必须是对象，例如 `{"query":{"text":"提交","exact":false}}`；切换标签用 `tab_open` 的 `reuse:"require",active:true`，刷新用 `page_navigate` 的 `refresh:true`，原生选项用 `page_click` 的 `role:"option"`。

package/dist/guides/api-page-debugging.md

@@ -0,0 +1,39 @@
+# Mearl 场景：页面排障与视觉验证
+
+需要检查布局、遮挡或 iframe，读取结构化 action 无法取得的状态，或核验视觉效果时读取本文件。常规交互见[网页自动化](./api-page-automation.md)。
+
+## 浏览器扩展页面
+
+调试 Mearl 自身扩展页面时，复用已连接的日常浏览器，用 `tab_open` 打开已知的 `chrome-extension://` 页面入口，持续使用返回的 `tabId` 执行快照、交互和截图，无需另起浏览器。浏览器内部页与扩展页不申请网站域名授权，由 Chrome 检查实际调试权限；读取其他扩展或内部页面失败时，按实际错误处理。将 popup 或侧边栏入口作为普通标签页打开，验证的是页面内容，真实宿主上下文和浏览器外壳交互需要另行验证。
+
+## 布局、遮挡与滚动容器
+
+优先 `page_inspect`，无需先写 page_eval 脚本。CSS、ref 和 DevTools 当前选区 `$0` 都可检查。文本/role 查找先用 page_snapshot.query，取得 matches/ref 后 inspect。
+
+`matches[].state` 返回原生或 ARIA 声明的 checked/selected/pressed/expanded/disabled/readonly，值带 `source`，支持 mixed；缺失字段表示没有可靠语义来源。
+
+- 命中数量与尺寸：读取 count、boundingBox、computedStyle；scanTruncated 时 count 不是完整扫描结果。
+- 点不到：hitTest.receivesPointerEvents=false 时检查 occludedBy；不要反复点击或直接合成事件。
+- 页面横向溢出：用 horizontal-overflow 找节点，再查看样式与横纵溢出量。
+- 页面不滚：用 scrollable 找容器，或检查 scrollContainer 后以 selector/ref 滚动。
+- 用户提到 Elements 当前选中节点：用 `$0`，可取得 resolvedSelector、属性、XPath 和框架信息，再进行结构化操作或元素截图。
+
+## iframe 定位
+
+用 `page_frames` 获取 frameId 与 URL/name，不猜 frame ID。扩展/CDP 的 page_eval.frameId 都在指定 frame 的页面默认上下文执行；省略时容器/设备外壳使用当前业务 frame，普通页面使用主 frame。需要读取外层容器时显式传主 frame ID。
+
+扩展后端在目标 frame 内取得的坐标用于点击时，同时传该 frameId 与 coordinateSpace=active-frame，避免误用外层视口或另一个业务 frame 的坐标。CDP 点击尚不支持显式 frameId/active-frame 坐标，不将 page_eval 的 frame 支持推断到其他 action。
+
+跨域 iframe 或快照不足以反映的视觉内容使用截图。容器中的默认业务 frame 与显式 frame 的输入派发范围，以 action help 的后端支持说明为准。
+
+## 最小范围脚本
+
+结构化快照、inspect 或滚动无法表达需求时，使用只读 page_eval 读取必要状态。默认裸执行，只返回 result；需要变更信号或诊断时才显式启用 observe/diagnostics。
+
+获取 selector 后回到结构化 action；直接 DOM 改写或合成点击可能绕过页面真实逻辑，不能仅用表达式执行成功证明业务成功。
+
+## 视觉验证
+
+用 `page_screenshot --output <绝对路径>` 保存后交给图像查看能力；避免将 base64 stdout 放进文本上下文。支持当前视口和指定元素截图，元素截图可能滚动目标到可见区。
+
+Canvas、纯视觉变化、跨域 iframe 或用户明确要求的 UI 核验才需要截图，不作为每个动作后的固定步骤。图片宽高是物理像素，按 CSS 尺寸 × DPR 解释。

package/dist/guides/api-page-environment.md

@@ -0,0 +1,37 @@
+# Mearl 场景：页面测试环境准备
+
+需要联动设备/App、折叠屏/分屏、时区或 Cookie 时读取本文件。设备预设与 App 档案以当前 CLI 为准，不从静态文档推断当前列表。远端/Provider 选择见[浏览器管理](./api-browser-setup.md)。
+
+设备模拟直接可用。App 模拟入口由已安装的能力包提供，档案可声明 UA、JSBridge 和容器行为。先查看 `mearl set_app_profile --help` 展示的目标浏览器动态目录；需要机器可读的桥方法、可调设置与默认版本时用 SDK `mearl.getCapabilities({ app: '目录中的完整 ID' })` 或 MCP `browser_get_capabilities`。按需读取 `usage.skills` / `usage.documentation`，再执行对应动作。
+
+## 设备模拟与设备外壳
+
+移动视口、UA、触摸或机型布局用 set_device_emulation；新建页在 tab_open.emulation 中传入，首屏直接生效。已有页用设置 action，保持 tabId。默认纯设备模拟，不创建 iframe；deviceShell=true 会在根 iframe WebView 内加载业务页并显示系统栏。
+
+scale 只改变视觉比例，不改变页面读取的视口或 DPR。预设的真实生效方向、尺寸、UA 和触摸能力以设置响应为准；折叠设备可能按自然方向归一化，不自行按 ID 推断方向。旧预设仍保留原尺寸与 UA。
+
+设备外壳开启/移除需要重载。任务会话用 `browser_release --session <sessionId>` 收尾，默认保留设备与 App 模拟；明确需要清理时传 `preserveEnvironment=false`。不带会话的浏览器级 release 会清理依赖调试连接的模拟，关闭 Tab 后该 Tab 的配置失效。任务只要求切换配置时，成功响应足够；要求查看页面效果时再做快照/截图。
+
+## App 与设备联动
+
+只有用户明确要求 App、客户端、容器、JSBridge 或容器栈模拟时启用 set_app_profile / tab_open.appProfile；普通 H5、唤端链接、客户端分支或操作失败不是启用理由。
+
+- 只注入桥：省略 emulation，保留设备状态；App 注入本身不创建根 iframe 或系统栏。
+- 完整端模拟：同一个 set_app_profile 调用传 emulation；空对象采用档案推荐设备，设备外壳默认开启。
+- 左右分屏：App 档案与 deviceShell=true、orientation=landscape、splitScreen=true 必须同时满足。新建页需要首屏分屏时，在 tab_open 同时传 appProfile 与该 emulation 组合。
+- 桥方法覆盖：bridgeConfig 只声明受控行为、固定 JSON 回包或成功空实现，不执行配置脚本。
+- 恢复：enabled=false 且省略 emulation 只清除 App；传 emulation={} 同时清除设备模拟。
+
+页面网络环境通过已安装预设声明的 networkControl 切换，传入其 id 和 value；省略保留当前设置，null 清除。可用控制项与取值以当前能力目录和预设文档为准。仅作用于目标 Tab，扩展模式与该 Tab 的快捷设置共享；关闭 Tab 或重启浏览器后清除。单次协议请求的参数不等于修改页面网络环境。
+
+## 时区
+
+用 set_timezone 覆盖目标 Tab 的 Date/Intl 时区，无需刷新；空字符串清除覆盖。按成功响应确认 enabled/timezone，不为单纯状态切换追加页面验证。
+
+## Cookie 与页面状态
+
+用已知 Cookie 名核验功能分支、实验或账号标识，不列举全部 Cookie、不读取认证 Token；HttpOnly 读取会被拒绝。
+
+只操作 Cookie 时可传 url，不为获取 tabId 额外打开页面；显式 tabId 用于选择该页的存储区（含无痕）。get_cookie 不回退同名分区 Cookie。
+
+set_cookie 只写非分区 session Cookie，空值不删除。需要页面重新读取 Cookie 时显式 reload=true 并提供 tabId；响应不回显写入值。按响应或页面业务状态验证，托管身份鉴权使用已安装的身份插件。

package/dist/guides/api-request-debugging.md

@@ -0,0 +1,54 @@
+# Mearl 场景：接口与埋点调试
+
+需要跨动作诊断、复现浏览器 HTTP/Protocol、处理域权限或设置 Mock/规则时读取本文件。
+
+## 选择诊断通道与输出范围
+
+- get_requests 默认查询全部请求；source=requests 只查普通 HTTP，source=protocol 只查协议插件采集的请求。大响应先用 includeBody=false、keysOnly 或 fields 控制输出；指定非空 fields 时默认省略正文，同时需要全文才传 includeBody=true。省略正文时不返回 postData / responseBody 字段。
+- get_logs 按级别/内容过滤，错误排查优先 error。
+- get_events 查询 RUM/aplus/ARMS，默认只保留解析字段；排查原始上报才用 includeRaw。既有页首次查询才开启采集，无历史时按 hint 刷新或重新触发。
+
+流式请求开始后即进入缓冲区；isPending 表示仍未完成。SSE 分片按顺序累积，协议归类由已安装的请求插件提供。不能把尚未结束的流误判为无响应；无法归属当前 Tab 的 Service Worker 请求不在采集范围内。
+
+## 单次动作与跨动作边界
+
+单次动作显式传 diagnostics，由执行器在派发前建立边界、在观察后返回新增内容；不要为每个动作额外 checkpoint。diagnostics=true 默认包含 error logs 与业务 requests，埋点用 events 显式开启。observe=false 仍返回诊断，但不等待 DOM/导航稳定。
+
+跨多个动作时建立一次 tab_checkpoint，再用 after 查询本次操作新增的记录：
+
+```bash
+mearl tab_checkpoint --payload '{"tabId":12345}'
+# 执行要排查的操作后，使用上一步返回的 cursor
+mearl get_logs --payload '{"tabId":12345,"after":"<cursor>","level":"error"}'
+mearl get_requests --payload '{"tabId":12345,"after":"<cursor>","source":"all","includeBody":false}'
+```
+
+同一 checkpoint cursor 可分别作为 logs/requests/events 的初始边界；查询返回的 nextCursor 带通道作用域，只用于同类续读。hasMore 表示仍有记录，gap 表示缓冲区淘汰，不应把缺口视为没有事件。tab_open 的 capture.cursor 是导航前边界，可直接读取首屏诊断。
+
+日志时间用 timestampMs（epoch 毫秒）；同一次埋点上报保持完整批次分页。缺少历史且 captureStatus=armed 时重新触发；inactive 时按 hint 排查采集链路。
+
+## 选择请求能力与执行宿主
+
+浏览器 HTTP 用 send_request；已安装插件提供的请求使用对应插件命令，其参数、认证和业务结果结构以插件帮助为准。不能只看 HTTP 成功判断业务成功。
+
+需要托管身份的接口使用已安装的专用能力插件，不手工传入其管理的凭据。协议与任务匹配见[相关 Skill 路由](./related-skills.md)。
+
+multipart 文件路径属于 native-host 所在机器；调用方不能引用远端文件时用 base64。`send_request` 还支持 `bodyFile: {filePath, contentType}` 或 `{base64, contentType}` 直接发送原始二进制（不封装 multipart）；与 body、formData、files 互斥，不支持 GET/HEAD。本地文件上限 40 MiB，Base64 解码上限 7 MiB。身份插件的文件路径属于插件执行宿主，两者不能混用。扩展模式 send_request 的 Cookie 不离开扩展；二进制响应按 bodyType=base64 解码保存，不作为大段文本载入。
+
+## 域权限失败
+
+send_request 报 Cookie access not authorized / Permission denied / Host permission missing 时，按错误中给出的纯主机名调用 request_permission。用户在弹窗决定，只有 granted=true 才重试原请求；拒绝/关闭/超时则停止该次重试并说明缺少域授权。独立身份插件遵循自身权限流程。
+
+## 请求规则的作用域
+
+用 set_rule 添加规则，get_rules 回查；删除时使用 enabled=false 和 ruleId。扩展规则持久化，CDP 请求头规则属于当前会话；CDP 只支持 modifyHeaders 的请求头 set。按当前后端和 Provider 能力选择，不假定所有模式支持重定向、屏蔽或响应头改写。
+
+## Mock 场景与回查
+
+完整 mockData 适合替换响应，fields 适合基于真实响应微调。需要同一接口多种情况时用 conditions 子集匹配，按业务入参隔离；无条件规则会覆盖。$index 从 0 起描述同一场景调用顺序，不作为业务请求字段匹配。
+
+用 get_mocks 回查目标 tabId 的配置，然后触发页面业务请求验证效果。设置成功不等于页面已收到 Mock。`browser_release --session <sessionId>` 默认保留 Mock；不带 `--session` 的浏览器级释放会清理依赖调试连接的 Mock，保持 Mock 终态时保留环境。禁用目标 Mock 用 enabled=false。
+
+## 大 payload 与文件引用
+
+整包参数用 --payload-file；某个大字段用顶层字符串 "@<绝对路径>"，客户端优先解析文件为 JSON，失败时用原文本。只展开顶层，不递归；读不到文件时保留字符串。文件展开仍走原传输通道，不绕过消息大小限制。

package/dist/guides/browser-tool-cooperation.md

@@ -0,0 +1,23 @@
+# 与其他浏览器工具协作
+
+Mearl 单独使用时沿用主 Skill 的页面操作流程。任务已有 Ego、agent-browser 等工具时保留其任务归属，按需使用 Mearl 的环境和调试能力。安装状态不代表当前页面已经连通或获准执行。
+
+## EgoLite
+
+需要设备/App 模拟、接口或日志调试时，优先使用已安装的 `mearl-ego` Skill。该 Skill 通过 Ego 原生 API 管理 Space 与交接，通过已连接的 Mearl 扩展操作同一页面，无需额外 Provider 或插件注册。
+
+未安装协作 Skill 时遵循以下边界：
+
+- 先读取 `ego-browser skill`，沿用当前 Space；创建、关联、人工交接与 `finish({ keep })` 均按 Ego 当前指南执行。
+- Ego 浏览器需安装并连接 Mearl 扩展。用 `browser_list` 选择 `transport: "extension"` 的连接，记录完整 `browserId`。
+- 在 Ego Page 读取 `page.cdp("Page.getFrameTree")` 的主 frame ID，再用扩展 `tab_list` 与 `page_frames` 核对。只有 `isMainFrame: true` 的 `frameId` 唯一匹配时，才使用该扩展 `browserId + tabId`；URL、标题和其他工具的页面标识不能代替核验。
+- 每轮转入扩展写操作前，按 Ego 指南确认同一 Space 仍由 Agent 控制；用户接管、Space 失活或归属变化时两套工具均停止写入。扩展不会自动继承 Ego 的控制阻断，未知结果先观察，不换工具重放。
+- 设备或 App 模拟开启期间，导航、交互、快照与截图使用扩展 action；Ego 鼠标输入可能与触摸模拟冲突，原生导航或截图可能改变设备参数。撤销并确认模拟清除后，再恢复 Ego 原生页面交互。
+- App 档案须已安装并取得实际站点权限，以当前目标的帮助为准。桥对象存在不证明真实原生授权或支付能力；跨域 iframe 的原生 screen/DPR、媒体查询与 CSS 安全区也不保证与真机一致。
+- 普通打开后设置模拟并重载，不等于业务页首次访问即处于模拟环境。需要首屏模拟时先确认当前工具支持的准备流程。
+- 成功收尾遵守 Ego 的页面保留规则；保留结果页时保留用户需要的模拟状态。需要恢复时在结束前通过扩展显式恢复原配置；Mearl 会话释放不替代 Ego 收尾，也不保证清除模拟。
+
+## agent-browser 等其他工具
+
+目前没有通用第三方 tab ID/ref 转换入口，也没有其专用 Provider。保留原工具的交互能力；只有已通过受支持连接确认到同一物理页面时才调用 Mearl 增强。
+尚不能确认映射或后端未声明所需动作时，明确说明当前限制，不按 URL 猜页或把整个任务切换到另一浏览器。

package/dist/guides/core.md

@@ -0,0 +1,60 @@
+# Mearl 核心工作流
+
+本指南说明通用操作流程。参数、返回字段以当前 CLI 的 `mearl <action> --help`、SDK `mearl.help()` 或 MCP 工具 schema 为准；MCP 使用实际提供的工具名，不猜命令映射。仅能使用 MCP、无法执行 CLI 时，直接使用当前 MCP 工具说明与 schema。组织发行版附带的安装、认证及业务指引继续有效，公共指南不替代这些说明。
+
+## 进入任务
+
+已有目标和明确动作时直接操作，不先做环境巡检。命令不可用或连接失败时再用 `mearl check`；本机连接按需恢复，不手工启动或保活 native host。安装和排障见[连接排查](./troubleshooting.md)。
+
+```bash
+mearl tab_open --payload '{"url":"https://example.com","reuse":"prefer"}'
+# 使用打开结果中的 tabId，观察后再选择本次快照提供的 ref。
+mearl page_snapshot --payload '{"tabId":12345,"mode":"viewport"}'
+mearl page_click --payload '{"tabId":12345,"selector":"@e3"}'
+```
+
+## 目标与控制归属
+
+页面动作持续复用同一浏览器与传输返回的 `tabId`。无可用页时才打开；已知 URL 优先 `reuse:"prefer"`，绑定开发页时沿用其 `openerTabId`。默认后台操作；确需可见输入时激活同一页。
+
+默认使用统一发现，不主动指定 `--local`、`--connector`、`--server` 或 `--cdp`。需要选择目标时用 `browser_list`，沿用返回的完整实例名或 `browserId`，不要另扫进程、端口。远端连接与 Provider 选择见[浏览器管理](./api-browser-setup.md)。
+
+需要任务归属、并行协作或人工交接时，首次 `tab_open` / `page_snapshot` / `page_screenshot` 传 `--session new`，后续复用完整 `session.sessionId` 与 `tabId`。会话固定目标，但 Cookie/存储仍共享。目标声明由外部工具控制时（例如 Ego 任务），沿用其交接与收尾，不传 Mearl `--session`；跨工具先核验同一实例和物理页面，不能仅凭 URL/标题或直接复用 ref、label、tab ID。详见[工具协作](./browser-tool-cooperation.md)。
+
+## 观察、操作与判读
+
+1. 需要理解页面或选择目标时取一次 `page_snapshot`；只要求截图时直接截图。优先 viewport、局部根节点或 query，确需全貌才取 full；AX 不足时再用 dom。只使用本次快照的 ref。
+2. 优先结构化点击、输入、滚动等动作。已知目标的紧密步骤可组合执行；有条件、循环或等待后立即点击时用 `mearl run`，见[代码组合](./scripting.md)。未知页面先输出最小观察，再由模型决定下一步，不预写未知 ref。
+3. 默认交互检查 `action.success`；`precondition` 表示未派发，可修正输入；`dispatch-uncertain` 表示可能生效，先看 attempt、observation 或必要快照，不直接重试。关闭观察且没有诊断时可能返回裸结果，按实际结构判读。
+4. 使用 effects、导航和 openedTabs 判断效果。新页已有 tabId 时直接使用。动作已内置观察，不固定追加等待、快照或截图；ref 过期、增量不足或 `fullSnapshotRecommended` 时再补观察。`changed:true` 且 effects 为空不表示失败。
+5. 用 URL、页面内容或实际配置核验用户要求的终态；动作成功或中间页不单独证明任务完成。视觉、Canvas、跨域 iframe 用截图；只要求切换设备/时区等状态时，以设置响应结束。
+
+复杂控件、文件、弹窗、派发差异见[网页自动化](./api-page-automation.md)；遮挡、布局与视觉验证见[页面排障](./api-page-debugging.md)。布局问题先用 `page_inspect`，必要时做最小只读 `page_eval`，取得目标后回到结构化动作。
+
+## 环境与诊断按需启用
+
+移动视口、UA、触摸使用 `set_device_emulation`，首屏生效用 `tab_open.emulation`。仅在用户明确要求客户端、JSBridge 或容器时启用 App 模拟；普通 H5、唤端链接或操作失败不构成启用理由。
+
+App 可用性以当前目标的 `set_app_profile --help` 或 `get_capabilities` 为准，沿用当前 browser/session。`partial`、`unsupported` 不等于空目录，`available:false` 不可启用。按需读能力包的 usage 指引，不自动安装；方法存在不证明真实授权、支付等业务能力可用。环境准备见[设备与 App](./api-page-environment.md)。
+
+已注册插件通过当前 `mearl --help` 或 SDK `mearl.help()` 发现，具体调用看插件帮助；本指南的专用 Skill 列表不代表全部已安装扩展。插件与 Provider 自己提供业务用法，核心入口不枚举它们的参数。
+
+只在任务需要日志、请求或埋点时开启 diagnostics；跨动作使用一次 checkpoint，再按 cursor 查询。输出范围、协议插件、域权限和 Mock 见[接口与埋点调试](./api-request-debugging.md)。不要为每次动作重复查询能力目录；接入、所需能力改变或连接失效时再核验。
+
+## 人工交接与收尾
+
+扫码、验证码或系统交互需要用户时，用 `browser_control` 的 handoff 交接，说明原因。用户接管或 `CONTROL_SESSION_PAUSED` 后停止派发；交回后重新观察，不重放未完成批次。无扩展 UI 时，须在用户明确确认交还后再 resume。
+
+会话任务用 `browser_release --session <id>` 释放归属，默认保留页面、Mock 和模拟环境。保留用户原有页和结果页，只有确认不需要的过程页才关闭。不带 session 的浏览器级释放仅用于用户要求结束调试或清理环境；外部工具按其自身约定收尾。具体归属与保留参数见[控制会话](./api-browser-setup.md#control-sessions)。
+
+## 按需深入
+
+- [代码组合](./scripting.md)：SDK、脚本上下文、超时和不确定结果。
+- [网页自动化](./api-page-automation.md)：控件、文件、弹窗与动作结果。
+- [页面排障](./api-page-debugging.md)：布局、遮挡、iframe、脚本及视觉。
+- [环境准备](./api-page-environment.md)：设备、App、时区、Cookie。
+- [接口与埋点调试](./api-request-debugging.md)：请求、日志、权限、Mock。
+- [浏览器管理](./api-browser-setup.md)：目标、会话、远端与 Provider。
+- [工具协作](./browser-tool-cooperation.md)：与 Ego、agent-browser 配合。
+- [专用 Skill 使用与安装](./related-skills.md)：如何选用和按需安装本地微信小程序等专用能力，以及在哪里查找扩展开发指引。
+- [连接排查](./troubleshooting.md)：连接失败与环境管理。

package/dist/guides/related-skills.md

@@ -0,0 +1,51 @@
+# 专用 Skill 使用与安装
+
+站点或业务对象与任务意图都匹配时，优先使用已安装的专用 Skill。通用网页操作继续使用 Mearl；不要仅因关键词相同就改用其他能力。专用站点的路由说明由对应 Skill 提供。
+
+| 意图 | Skill |
+| --- | --- |
+| 运行或验证本地微信小程序，包括 uni-app / Taro 的微信产物 | wechat-miniprogram |
+| 时间戳、Base64、图片编码、URL 编解码 | format-converter |
+| 记录或检索笔记与跨会话记忆 | notes-memory |
+| 管理已有浏览器标签分组、关闭受控标签页 | browser-tab-manager |
+| 用户明确要求使用 TinyPNG 压缩图片 | tinypng-compress |
+| 把设计稿叠加到网页并做像素差异对比 | design-overlay |
+| 为网页提供持续双语阅读 | immersive-translate |
+| 运行 bb-browser 站点适配器 | mearl-bbrowser |
+| Ego / EgoLite 任务中配合扩展进行端模拟、接口与日志调试 | mearl-ego |
+| 开发或审查外部浏览器、真机 Provider | mearl-provider-creator |
+| 把网站操作沉淀为可复用 Skill、CLI 或工具箱 GUI | mearl-skill-creator |
+
+有脚本入口的 Skill 可安装并自动注册插件：
+
+```bash
+{{setup}} plugin install https://github.com/mearlhq/mearl --skill <skill-name> --yes
+```
+
+已可用的专用 Skill 按其说明执行。用户明确要求使用表中某项专用能力、且执行任务需要该插件时，可在缺失时按需安装并继续。普通网页操作使用通用流程。
+
+## 运行本地微信小程序
+
+任务要运行小程序工程或已编译的微信产物时，先用 `mearl --help` 检查已注册插件中是否有 `wxa`。缺失时，从已包含此 Skill 且当前可访问的官方来源补装：
+
+```bash
+{{setup}} plugin install https://github.com/mearlhq/mearl --skill wechat-miniprogram --yes
+```
+
+官方来源暂不可用且本机已有包含此 Skill 的源码时，可直接注册：
+
+```bash
+{{setup}} plugin "/path/to/mearl/skills/wechat-miniprogram"
+```
+
+两种方式都会准备运行依赖并注册 `wxa`。读取对应目录中的 `wechat-miniprogram` Skill，查看 `mearl wxa start --help` 后用 `mearl wxa start <项目路径>` 启动。框架项目先构建微信产物。若安装失败，报告具体阻塞。用户只要求普通微信 H5 / WebView 模拟时，查询目标浏览器的微信 App 档案即可。
+
+## 开发与协作指引
+
+`mearl-ego`、`mearl-skill-creator` 与 `mearl-provider-creator` 是指引型 Skill，没有可注册的脚本入口；直接用标准 Skills 工具安装，不运行 `setup plugin`：
+
+```bash
+npx skills add https://github.com/mearlhq/mearl --skill mearl-skill-creator --global
+```
+
+已有源码时也可将 Git 来源替换为实际 Skill 目录。安装前核对所选分支或标签确实包含目标 Skill；普通任务不主动安装开发指引。

package/dist/guides/scripting.md

@@ -0,0 +1,21 @@
+# Mearl 场景：代码组合
+
+目标和后续动作已确定时，优先用 `mearl run` 合并连续调用，尤其是等待就绪后立即点击，避免模型往返错过短暂可操作窗口。需要条件、循环、过滤或组合已注册 Skill 命令时也用此入口。运行时已注入 `mearl` SDK，无需安装依赖：
+
+```bash
+mearl run --session '<sessionId>' <<'JS'
+const result = await mearl.invoke('get_requests', { tabId: 12345, count: 20 });
+console.log(result);
+// Skill 的 command/input 以其帮助为准：
+// const data = await mearl.invokePlugin('插件名', { command: '命令名', input: {} });
+JS
+```
+
+等待后立即操作的示例及超时设置见[常规网页自动化](./api-page-automation.md#page_wait)。等待条件和点击目标须已从页面确认；等待失败就停止，不继续点击。
+
+- 浏览器 API 可用 `mearl.pageClick({ tabId, selector })` 等 SDK 方法，或沿用 action 名称的 `mearl.invoke(action, payload, options?)`；Skill 命令用 `mearl.invokePlugin(name, { command, input }, options?)`。参数和返回值与普通调用一致，仍检查 `action.success`、派发状态与业务效果。
+- 方法、参数或结果不明确时，输出 `console.log(await mearl.help('pageClick'))`；它与 `mearl page_click --help` 共用帮助，`help()` 列出方法和已注册插件。插件用 `help({ plugin: '插件名', command: '命令名' })`。动态结果可输出 `mearl.structure(result)` 查看字段与类型；它只检查已取得的值，默认取有限深度、字段和数组样本，标注截断与循环引用，不代表完整契约。无需为理解结构重跑业务命令。
+- `--browser` / `--session` 等路由参数由所有调用继承。`--session new` 时先 await 建立会话的浏览器调用，再执行插件或并发调用；随后自动复用返回的 ID，可读 `mearl.session`。每轮新建 Node 进程，JS 变量不保留，后续继续传同一 `sessionId` 和 `tabId`。
+- 脚本拥有当前宿主的 Node 权限，继承工作目录和环境；使用 `await import()` 加载模块。DOM 代码放入 `mearl.pageEval`，浏览器动作优先使用结构化 API。stdout 只打印必要结果；未知页面需要模型理解时，输出最小观察后在下一轮决策，不预写未知 ref。
+- `--file <path>` 可读取脚本文件，内容同样支持顶层 await 和动态 import。`--timeout <seconds>` 是整个脚本时限，默认 60 秒；源码最多 1 MiB，输出最多 256 KiB。await 所有 SDK 调用，失败不自动重试。超时或取消后查看 `pendingActions` / `mayHaveLateEffects`，先核验已派发操作；不要重放整段脚本。
+- MCP 使用对应的 `browser_run_code` 工具。脚本适合代码可判断的流程，`run_actions` 保留给无需中间判断的紧密序列；需要模型理解或视觉判断时逐步操作。

package/dist/guides/troubleshooting.md

@@ -0,0 +1,170 @@
+# Mearl 环境安装与连接排查
+
+## 目录
+
+- [环境安装、更新与卸载](#environment-management)
+- [本机控制](#local)
+  - [浏览器扩展安装](#local-extension)
+  - [命令不可用或连接失败](#local-check)
+  - [EACCES](#eacces)
+  - [ENOENT](#enoent)
+  - [ECONNREFUSED / 连接关闭](#econnrefused)
+- [远程控制](#cloud)
+  - [Agent（控制端）](#cloud-agent)
+  - [浏览器端](#cloud-browser)
+  - [远程控制常见问题](#cloud-issues)
+- [通用问题](#common)
+  - [请求超时](#timeout)
+
+按 Agent 与浏览器所在机器选择排障流程；命令参数读取对应 CLI 的 `--help`，失败时优先按错误或 `check` 输出的提示处理。
+
+- **本机控制**：Agent 与浏览器在同一台机器，`@mearl/client` 通过 native host socket 通信。
+- **远程控制**：Agent 与浏览器不在同一台机器，`@mearl/client` 通过 cloud-server + cloud-connector 中转。
+
+<a id="environment-management"></a>
+
+## 环境安装、更新与卸载
+
+CLI、Native Host、MCP 和云端核心运行包要求 Node.js >= 20.18.0。安装前用 `node --version` 确认版本；
+不满足时先升级 Node。环境安装使用 `{{setup}} --yes`，沿用所展示入口的包名、版本或标签及 registry。
+出现 `Unknown operation: plugin` 时，用 `{{setup}} --version` 核对安装器版本；
+未指定版本时，npm 可能因 Node 不兼容而选择历史版本。
+
+环境管理使用 `{{setup}} <install|update|uninstall>`，具体选项按子命令 `--help` 查询。Agent 执行 install/uninstall 时附加 `--yes` 或 `--non-interactive`，避免等待交互；人工终端可保留交互选择。
+
+主动安装或更新本机环境时，setup 优先使用显式 `--preset <清单 URL 或路径>`，否则保留本机已选 preset；本机未选择时，在运行时初始化后、安装任何 Skill 前检查已连接扩展的受信 preset 并补齐本机组件。首次连接最多等待约一分钟。多个浏览器选择不同、来源不受信或状态不可读时会停止并提示显式选择，不猜测。浏览器未连接时仅安装基础环境，连接后重跑 setup 即可；普通连接和后台自动更新不触发首次本机 preset 安装。
+
+卸载只在用户明确要求一并移除全部 CLI 插件和浏览器 Provider 时传 `--full`；该选项不删除 Chrome 扩展。正常浏览器任务不主动安装或重新初始化，下方排障只在连接失败后使用。
+
+---
+
+<a id="local"></a>
+
+## 本机控制
+
+<a id="local-extension"></a>
+
+### 浏览器扩展安装
+
+优先安装 [Chrome 商店版](https://chromewebstore.google.com/detail/mearl/aoehhjnofngknnjefamjbplchbolghkm)，由 Chrome 管理更新。商店不可用或用户明确要求 setup 托管时，执行：
+
+```bash
+{{setup}} extension --full --yes
+```
+
+该命令同时准备本地环境。人工在终端执行时可省略 `--yes`。
+
+<a id="local-check"></a>
+
+### 命令不可用或连接失败
+
+`mearl` 或 `mearl-native-host` 命令不存在时，在浏览器所在机器安装：
+
+```bash
+{{setup}} --local --yes
+```
+
+命令存在但连接失败时，先检查当前链路：
+
+```bash
+mearl check
+```
+
+只需隔离检查当前机器时使用 `mearl check --local`；路由参数与配置优先级见 `mearl check --help`。只有检查结果表明本地组件缺失、过期或初始化不完整时，才更新并重新初始化：
+
+```bash
+{{setup}} update --local --yes
+```
+
+<a id="eacces"></a>
+
+### EACCES（权限不足）
+
+仅当 native host 初始化写入系统目录时权限不足，才在浏览器所在机器执行：
+
+```bash
+sudo mearl-native-host --init
+```
+
+Socket 访问被 Agent 沙箱拒绝时，按错误提示配置访问权限，不通过 sudo 或改写 Socket 权限绕过。
+
+<a id="enoent"></a>
+
+### ENOENT（找不到 Socket）
+
+client 会自动拉起 native host 并重试。自动恢复失败时按错误提示检查本机链路；手工启动或开发版扩展初始化的参数见 `mearl-native-host --help`，不要用 `nohup` 手工保活 daemon。
+
+如果重试后仍然失败，可按以下步骤排查：
+
+**使用浏览器插件模式：**
+
+确认 Chrome 已打开并等待扩展建联；仍失败时打开 DevTools 的 Mearl 面板触发连接。开发版扩展使用其实际扩展 ID 初始化 native host，再重新执行命令。
+
+**使用 CDP 模式：**
+
+按 `mearl-native-host --help` 或连接错误提示在 Chrome 开启调试并允许授权，确认有普通网页已打开后重试。默认在 Extension 不可用时回退 CDP；需要单独验证 CDP 链路时使用 `mearl check --cdp`。
+
+<a id="econnrefused"></a>
+
+### ECONNREFUSED / 连接关闭
+
+client 会处理当前用户的 stale socket 并尝试恢复 native host；恢复失败时运行 `mearl check --local`，按诊断处理，避免盲目删除 Socket 或重复初始化。
+
+---
+
+<a id="cloud"></a>
+
+## 远程控制
+
+远程控制需要在 **Agent（控制端）** 和 **浏览器端** 两端分别准备。
+
+<a id="cloud-agent"></a>
+
+### Agent（控制端）
+
+1. 安装 cloud-server、统一 client 与当前 Agent 的全局 mearl skill：
+
+   ```bash
+   {{setup}} --cloud --yes
+   ```
+
+   setup 会启动 cloud-server 并输出连接命令。把输出的完整命令交给用户在浏览器所在机器执行，不自行拼接地址或 token。
+
+2. 再次获取连接命令使用 `mearl-cloud-server status`；管理与日志命令见 `mearl-cloud-server --help`。
+
+3. client 自动读取连接配置。用户完成本地连接后，在 Agent 侧验证：
+
+   ```bash
+   mearl check
+   ```
+
+   按诊断定位故障所在机器，再在对应机器修复。默认不逐次传 Server 地址；覆盖参数、配置优先级和检查范围见 `mearl check --help`。连接 URL 可能包含 token，不写入日志或转发给无关方。
+
+<a id="cloud-browser"></a>
+
+### 浏览器端
+
+1. 执行 Agent 侧输出的完整连接命令，把浏览器接入远程控制链路。
+
+2. 浏览器端仍需满足 [本机控制](#local) 的前置条件（native host 已初始化、浏览器插件或 CDP 已建联），否则 connector 无法连到本地 socket。相关报错（EACCES / ENOENT / ECONNREFUSED）参考上文本机排查步骤。
+
+<a id="cloud-issues"></a>
+
+### 远程控制常见问题
+
+- **Agent 侧无法连接 Server**：运行 `mearl check`，按失败项的提示处理。
+- **需要确认动作会落到哪台机器**：运行 `mearl browser_list`，首次操作传返回的全局 `--browser <browserId>`；控制会话建立后由 `--session <sessionId>` 固定目标，无会话时继续传选定的 `--browser`。需要限制到某台远端机器时，从 `source` 获取 ID 或名称并传 `--connector <id|name>`。
+- **connector 连不上或一直重连**：在浏览器端运行 `mearl-cloud-connector status`，按状态和错误提示处理。
+- **connector 已接入但浏览器不可用或请求无响应**：在浏览器端运行 `mearl check --local`；需要检查 connector 版本与心跳时，Agent 端使用 `mearl connector_list`，字段见该命令 `--help`。
+
+### 可选云连接协议
+
+Qoder Cloud Agent 需要在浏览器机器先安装 `@mearl/plugin-qoder` 能力，再按该包 README 和 `docs/cloud-pairing.md` 生成配对信息、配置自定义工具。普通远端 Agent 使用上述 WebSocket 模式。核心未安装对应协议时会报告能力缺失，不会自动安装或读取该协议的凭据。
+
+### 请求超时
+
+超时可能发生在连接、动作执行或结果回传阶段，不能据此判断动作未执行。
+
+- 连接超时：使用 `mearl check` 定位链路故障。
+- 点击、提交、上传或写入超时：先读取当前页面或业务状态确认结果，再决定是否重试，避免重复副作用。
+- 只读查询超时：按 CLI 提示缩小查询范围、裁剪结果或增加 `--timeout`；默认时间按 action 推导，不统一设为 30 秒。