@mearl/client 2.21.0 → 2.22.1

package/README.md

@@ -150,6 +150,10 @@ stdout 在管道或重定向时默认输出紧凑 JSON，在交互终端默认
 需要同时读取全文时显式传 `includeBody:true`。省略正文时不返回 `postData` / `responseBody` 字段；
 未指定字段时默认返回正文。
 
+`send_request` 默认携带所选浏览器中匹配完整目标 URL 的未分区 Cookie，保留不同路径下的同名 Cookie；不额外拼入父站点的 host-only Cookie，也不猜测页面的 Cookie 分区。需要页面分区、页面签名或完整页面身份时，使用目标页面中的 `page_eval` 请求。
+响应中的 `Set-Cookie` 会更新原浏览器，后续调用可以使用刷新后的登录态；`withCookies:false` 同时关闭自动携带与响应回写。扩展由 Chrome 处理响应 Cookie；CDP 的 Node 请求在返回前通过原页面的浏览器连接回写，支持 HttpOnly、默认路径、过期时间和删除。CDP 响应存在 `Set-Cookie` 时附带 `cookieSync: { updatedCount, rejectedCount, failedCount }`，不返回 Cookie 值；无法确定分区的 Partitioned 响应 Cookie 计入拒绝数。同步失败不撤销已完成的 HTTP 操作，应检查状态而非直接重发业务请求。MTop 普通请求及流式请求使用相同的响应刷新机制。
+扩展的临时凭据注入仅匹配原始完整请求 URL，重定向由 Chrome 按新 URL 选择 Cookie。CDP 的 Node 请求（含 MTop 流式请求）不自动跟随重定向，避免将原 URL 的 Cookie 或签名传到其他地址。
+
 Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通过 `browser_list` 返回的全局
 `browserId` 自动路由。以下覆盖参数仅在限定宿主或连接、传输排障时使用，因此不出现在默认 help：
 
@@ -211,6 +215,20 @@ Provider 与插件仍可独立安装、更新和卸载，帮助聚合不会启
 注册名优先使用显式名称，其次读取入口的 `name` metadata，最后回退到 skill 目录名；常规注册只传路径。
 setup 会补齐缺失或低于自身版本的 client、native-host；安装参数透传给 Ali Skills，并固定全局共享安装。
 
+`mearl-bbrowser` Skill 提供 `bbrowser` 插件，可直接加载 bb-browser 格式的社区及私有站点适配器，无需安装 bb-browser：
+
+```bash
+npx @mearl/setup plugin install trip/mearl --skill mearl-bbrowser --yes
+mearl bbrowser site list
+mearl bbrowser site fliggy-ebooking/whoami
+mearl bbrowser site ./fliggy-ebooking/ai-agent.js
+mearl bbrowser site zhihu/hot 10
+mearl bbrowser site zhihu/hot 10 --cdp
+```
+
+插件通过同一 `page_eval` 接口调用扩展或直连 CDP。适配器来源、私有目录、更新与结构化调用见
+[mearl-bbrowser Skill](../skills/mearl-bbrowser/SKILL.md)。插件默认输出 JSON。
+
 需要单独检查插件时运行 `mearl <name> --version`。命令会解析注册记录并加载入口，但不连接浏览器；
 退出码为 0 表示插件已注册且入口可加载，stdout 返回同目录 `SKILL.md` 的版本，缺少版本元数据时返回 `unknown`。
 未注册、入口丢失或加载失败会以退出码 2 和对应的 `PLUGIN_*` 错误结束。普通业务调用无需预先检查，直接处理同样的错误即可。
@@ -220,6 +238,7 @@ setup 会补齐缺失或低于自身版本的 client、native-host；安装参
 使用位置参数和业务选项，`--payload` 不能与前两种形式混用。JSON 保留业务字段类型；正文等文件输入按具体
 skill 的字段约定处理。`browser`、`timeout`、`output` 等宿主选项保留原有含义；同名业务字段以及数字、
 布尔值、对象和数组通过 `--payload` 传入。插件不使用上表中内置 action 的 `--payload-file` 入口。
+业务选项名称支持字母开头的字母、数字和下划线组合，下划线原样传递。
 
 注册后的插件也可从 SDK 调用；实例方法 `client.invokePlugin` 复用既有连接和默认浏览器：
 
@@ -235,7 +254,7 @@ const result = await invokePlugin(
 
 MCP Server 通过固定工具 `plugin_invoke` 接受同样的 `plugin`、`command` 和 `input`，不会把插件子命令动态扩展成 MCP 工具。SDK 与 MCP 不接受任意入口路径；调用尚未注册的 `buc`、`authx` 或 `tdbank` 时，会通过匹配当前 client 版本的 setup 自动安装并重试一次。其他未注册名称返回 `PLUGIN_NOT_REGISTERED`。
 
-长命令使用本机持久任务服务。服务按注册目录隔离并自动启动，CLI、SDK、MCP 与工具箱共享任务记录；调用方退出不取消执行。服务重启后将未完成任务标记为 `interrupted`，不自动重放。后台任务固定接受时的源码快照、工作目录与环境；静态第三方 JS 依赖需要预先打包进 Skill，状态文件放在源码目录之外。
+长命令使用本机持久任务服务。服务按注册目录隔离并自动启动，CLI、SDK、MCP 与工具箱共享任务记录；调用方退出不取消执行。服务重启后将未完成任务标记为 `interrupted`，不自动重放。后台任务固定接受时的源码快照、工作目录与环境；第三方 JS 依赖应预先打包进 Skill，状态文件放在源码目录之外。快照只固定源码和相对资源，不预解析 JS 依赖；缺失依赖和语法错误由执行器加载代码时报告。
 
 ```ts
 import { PluginTaskClient } from '@mearl/client';
@@ -255,6 +274,8 @@ try {
 
 `wait` 超时或其 signal 中止只结束等待；`cancel(taskId)` 才取消执行。浏览器任务需显式传 `browser`，名称会在接受前解析为固定 ID。`get/list` 返回任务快照与结果引用，`list` 返回有界分页及 `nextCursor`；`events` 返回游标、缺口标记和最新快照，`subscribe` 封装长轮询。`result(taskId)` 分块读取并校验完整业务结果，最大 64 MiB；终态记录和结果保留 7 天。
 
+插件宿主握手与 `tasks.status()` 返回 `version/buildId`，构建标识用于定位运行代码，兼容性由握手中的协议版本决定。协议相同时，即使版本、构建标识不同或旧宿主未提供标识，任务、模型、页面和状态请求仍可继续使用现有服务，不中断活动任务或页面实例。需要切换到新构建时，确认没有活动任务及页面操作后调用 `tasks.stopHost()`，下次业务调用将启动当前构建；重新注册插件不会重启宿主。本地修改客户端或宿主代码后执行根目录 `pnpm build`，同步生成指纹并构建双方产物；仅运行 `tsc --watch` 不会更新构建指纹。
+
 任务能力由 SDK `PluginTaskClient` 与工具箱 `host.task.*` 使用。对外命令由具体插件按业务需要提供，CLI 使用 `mearl <plugin> <command>`，MCP 使用 `plugin_invoke`。任务、模型、状态、页面实例和宿主诊断不单独暴露为全局 CLI/MCP 命令。仅注册工具箱内部命令的插件不会列入 CLI 插件列表；直接运行其名称会提示工具的打开位置。工具页可用 `window.mearl.waitTask(taskId)`、`readTaskResult(taskId)`、`listTasks()`，范围限定为所属插件的工具箱任务。
 
 `tasks.diagnose({ taskId?, plugin?, instanceId?, includeErrorMessages?, includeLocalPaths? })` 读取当前调用范围内的有界诊断报告。默认不包含业务输入、提示词、进度正文、检查点数据、结果正文、完整 URL、环境变量和凭证，也省略错误消息及本地路径；后两项可显式选择包含。报告的 coverage 和历史 gap 表示采集范围及保留历史限制。
@@ -269,7 +290,15 @@ try {
 
 插件可选导出 `toolbox`，注册后会出现在扩展 Popup 的工具箱中。页面资源放在 Skill 目录内，注册时由
 Mearl 将入口 HTML 引用的本地 CSS、JavaScript 和图片内联为不可变页面包，不需要启动 HTTP 服务，
-也不要求普通 HTML/CSS/JS 页面自行构建：
+也不要求普通 HTML/CSS/JS 页面自行构建。
+
+右键工具箱中的工具可单独禁用或启用对应 Skill；禁用状态显示在标题右侧，工具页面和命令仍可使用。禁用将该目录的
+`SKILL.md` 重命名为 `SKILL.md.mearl-disabled`，启用时恢复，作用于共享此目录的所有 Agent；
+软链接安装会作用于源目录。已有会话可能仍保留已载入的 Skill，需要重启 Agent 或新建会话。
+工具箱内更新和重新安装会保留禁用状态；外部安装器的更新不受此状态管理，若出现两份清单，需先处理冲突。
+独立复制安装的同名 Skill 需分别禁用。没有 Skill 清单的普通插件不显示此开关。
+
+工具箱元数据示例：
 
 ```javascript
 export const toolbox = {
@@ -347,6 +376,8 @@ Preact、Hooks 和 HTM 运行时。页面从 `window.mearl.ui` 读取 `html`、`
 `--mearl-accent` 等语义变量；主操作按钮使用 `--mearl-action-primary`、
 `--mearl-action-primary-hover` 和 `--mearl-action-primary-text`，以保持与扩展按钮一致。
 
+工具箱面向人，CLI 面向 Agent：复用业务操作、保持结果一致即可，不要求共享中间态。表单草稿、选择、预览等纯 UI 状态默认放浏览器内存；确需刷新或重新打开后恢复时再用浏览器存储。sandbox 页不能假定可直接访问 `localStorage`、IndexedDB 或 `chrome.storage`，应使用宿主提供的能力。只有业务记录、关闭页面后继续的任务、安全重试回执或受消息大小限制的资源传输才需要 Node 状态，并说明其生命周期及清理方式。
+
 需要 BUC 身份的内部 HTTP 接口通过官方 `buc` 插件调用。CLI 使用 `mearl buc request <url> [app]`，业务插件使用
 `app.invoke('buc', { command: 'request', input })`；当前身份和人员资料分别使用 `whoami` 与 `profile`
 子命令。BUC 插件按请求创建一次性凭据，只接受无 URL 凭据的 HTTPS 地址，过滤认证字段与 Cookie；
@@ -377,12 +408,14 @@ AuthX 对应 `mearl authx request <url> [audience]`，省略 `audience` 时同
 
 页面交互动作（`page_click` / `page_drag` / `page_type` / `page_hover` / `page_scroll` / `page_press` / `page_upload`）默认等待异步稳定并返回 `{ action, observation }`。参数、ref 或目标解析在派发前失败时返回 `action.stage: "precondition"`，省略无意义的 `observation` / `diagnostics`；浏览器可能已收到输入但确认超时时返回 `action.stage: "dispatch-uncertain"`，并保留 observation 供核验当前状态。能够在超时前确定的目标、命中、坐标、派发模式和输入序列状态保存在 `action.attempt`，它是诊断证据，不表示动作已经生效。失败时 CLI 退出码为 1。传 `observe: false` 可执行裸动作；需要同一动作期间的新增 error logs 和业务 requests 时传 `diagnostics: true`，埋点通过 `diagnostics.events` 按需开启。`page_eval` 默认裸执行，可按需开启观察或诊断。
 
-`tab_open active:true` 会激活目标 Tab、恢复最小化窗口，并通过 `activation` 返回实际标签页、窗口和 `visibilityState`；依赖可信触摸时先确认页面为 `visible`。页面动作的稳定观察会在有限预算内等待有限时长 CSS 动画。selector/ref 点击遇到嵌套滚动裁剪时会先滚动目标，仍不可见时才以明确的裁剪错误停止。
+`tab_open active:true` 请求激活目标页。扩展免打扰默认开启：HTTP(S) 页面在首次导航前启用后台焦点模拟，不切换标签页或窗口；关闭免打扰才会真实激活并恢复最小化窗口。`activation.mode` 区分 `background` / `foreground`，模拟后的 `visibilityState` 不代表窗口在前台。焦点模拟在交接、释放控制或扩展连接断开时关闭，`preserveEnvironment` 不保留它；交还后按需对同 URL 使用 `reuse:"require", active:true` 再次激活。不带会话时通过 `browser_release` 收尾。纯 CDP 和外部 Provider 遵循各自的激活能力。页面动作的稳定观察会在有限预算内等待有限时长 CSS 动画。selector/ref 点击遇到嵌套滚动裁剪时会先滚动目标，仍不可见时才以明确的裁剪错误停止。
 
 `page_click` 默认 `auto` 在隐藏页使用 DOM fallback，selector、文本、ref 和坐标定位都保持可用，并通过 `dispatchMode: "dom"`、`fallbackReason: "page-hidden"` 明确说明实际路径。普通后台任务不需要为了点击主动激活页面；只有站点明确拒绝非可信事件时才切换到可见页并强制 `mouse` / `touch`。
 
 `observation.effects.interactives` 会把内容未变化但 DOM 节点被框架重建的控件标记为 `recreated`，保留 selector/ref 与语义信息供后续定位，同时省略未变化的 value 和状态字段；值或状态确实变化时仍返回完整差异。
 
+`observation.effects.texts` 按需返回普通可见叶子文本的当前值 `{ selector, text }`，覆盖独立计数、金额等非控件文字。结果最多 8 项，每项 text 最多 160 字符；同一节点连续更新只保留最终值。非空文字的 Range 矩形必须完整处于视口和祖先滚动/裁剪框内，并通过命中检查；CSS 掩码文本不进入该通道。空文本使用元素框检查。结果不作为可交互控件或业务成功信号。复杂结构、不可读内容及预算溢出仍保留快照回退；该通道不改变导航等待策略。
+
 `page_press.pressMode` 支持 `auto` / `dom` / `keyboard`。默认 `auto` 在隐藏页使用 DOM 键盘事件，并通过返回的 `dispatchMode`、`fallbackReason` 和 `defaultAction` 说明实际派发及默认行为模拟结果；依赖浏览器原生编辑、选择或滚动行为时使用可见页面和 `keyboard`。
 
 `page_snapshot` 默认返回完整 AX Tree；长列表可传 `mode: "viewport"`，只需要当前视口内的控件时传 `mode: "interactive"`，AX 信息为空或过于稀疏时可显式传 `mode: "dom"`，返回实际渲染文本、原生控件、显式 role 和高置信 clickable 节点。DOM 模式同样返回可供后续动作使用的 `@ref`，但不会猜测任意容器的业务语义。已知 CSS 区域时传 `rootSelector`，已有 ref 时传 `rootRef`（可用 `ancestorDepth` 向上补充上下文），只查找特定文案或角色时传 `query`。`interactive` 在视口内缺少 AX 控件语义时仍只回退到 AX viewport，并返回 `fallbackMode: "viewport"`，不会自动切换数据来源。`maxNodes` / `maxChars` 截断会同时保留首尾内容。
@@ -418,6 +451,17 @@ debugger/CDP 控制和会话级临时状态，保留浏览器及全部标签页
 
 基础设施组件必须避免递归路由：`@mearl/cloud-connector` 使用 `@mearl/client/local` 子路径直连所在机器的 native-host。普通 Agent、CLI 与 MCP 集成均使用包根入口。
 
+插件代码按职责组织在 `src/plugins/`：
+
+| 目录 | 职责 |
+| --- | --- |
+| `sdk/` | 插件声明、命令接口及页面、模型、状态和恢复声明的校验 |
+| `clients/` | 插件服务连接及任务、模型、页面、状态的调用接口 |
+| `runtime/` | 服务组装、任务调度、存储、代码快照、执行器和进程清理 |
+| 插件目录根部 | 注册、资源打包、官方插件安装及调用端与服务端共享的通信协议 |
+
+测试位于各模块附近的 `__tests__/`。对外通过 `@mearl/client` 和 `@mearl/client/plugin` 导出；包根部的 `plugin.ts` 是插件公开入口。三个进程入口 `plugin-worker.ts`、`plugin-task-host.ts` 和 `pluginModelSessionWorker.ts` 保留在 `src/` 根部，`runtimePaths.ts` 统一定位包版本和进程入口，使逐文件编译与 Native Host 打包使用相同的入口布局。生成协议仍由 `browser-core` 同步到 `src/generated/`。
+
 ## 构建
 
 ```bash
@@ -432,7 +476,7 @@ ISC
 
 ### 插件页面实例
 
-`PluginPageClient` 通过本地插件服务管理 attach/get/list/send/detach/events/activation。插件导出独立 `pageRuntime` 声明并用 `app.page()` 调用。扩展与纯 CDP 共用实例、事件、激活和文档运行时；实例绑定 documentId，同插件同文档的所有入口共享初始化，导航后旧实例失效，启用的激活规则负责重建。`frame` 接受 `main`、`business` 或 `page_frames` 返回的 frame ID（扩展为数字，CDP 为字符串）。外部 Provider 仍须明确声明 `page_runtime` 能力。
+`PluginPageClient` 通过本地插件服务管理 attach/get/list/send/detach/events/activation。插件导出独立 `pageRuntime` 声明并用 `app.page()` 调用。宿主用 Node 内置编译器检查 code 的表达式语法，不执行代码；代码必须在网页中求值得到自包含函数，非函数或外部引用错误在页面运行时报告。扩展与纯 CDP 共用实例、事件、激活和文档运行时；实例绑定 documentId，同插件同文档的所有入口共享初始化，导航后旧实例失效，启用的激活规则负责重建。`frame` 接受 `main`、`business` 或 `page_frames` 返回的 frame ID（扩展为数字，CDP 为字符串）。外部 Provider 仍须明确声明 `page_runtime` 能力。
 
 显式手动 `attach` 复用自动激活的实例时，实例转为手动归属，初始化与在途任务继续复用；随后收窄自动激活范围不会清理该实例。
 
@@ -446,7 +490,7 @@ try {
 } finally { pages.disconnect(); }
 ```
 
-后台事件声明 schema 和串行、latest 合并或有限并发策略，处理器用 `app.runtimeCommand()` 注册并通过 `context.page` 访问固定文档。文档绑定任务可用 `app.page('activation')` 只读查询本插件激活规则，不允许设置或关闭规则。页面消息/结果各上限 24 MiB，宿主自动分块并校验；事件负载上限 32 KiB。工具箱使用 `host.page.*`，UI 订阅实例历史与后台执行独立。完整契约见 [插件宿主能力](../native-host/README.md#页面运行时和事件)。
+后台事件声明 schema 和串行、latest 合并或有限并发策略；schema 是格式元数据，事件处理器负责验证负载。处理器用 `app.runtimeCommand()` 注册并通过 `context.page` 访问固定文档。文档绑定任务可用 `app.page('activation')` 只读查询本插件激活规则，不允许设置或关闭规则。页面消息/结果各上限 24 MiB，宿主自动分块并校验；事件负载上限 32 KiB。工具箱使用 `host.page.*`，UI 订阅实例历史与后台执行独立。完整契约见 [插件宿主能力](../native-host/README.md#页面运行时和事件)。
 
 Python 入口同样导出 `pageRuntime` 字典，其中 `code` 仍是运行于网页中的 JavaScript 函数字符串；后台初始化与事件处理器通过 `app.runtimeCommand(...)` 或其装饰器注册。`app.page(operation, payload)`、`context.page.send(message)` 和 `context.page.get()` 都是同步调用，后两者仅在绑定页面实例的处理器中可用。JS 和 Python 的 `context.page.send(message, {timeoutSec: 120})` 可指定单次响应超时（大于 0 且最多 300 秒，Python 使用字典）；`app.page("send", {instanceId, message, timeoutSec})` 和 SDK `pages.send(plugin, instanceId, message, {timeoutSec})` 同样支持。该设置不改变其他请求，任务取消和文档解绑仍立即中断执行，传输失败也会取消对应网页请求。runtime-only 命令不出现在公开命令帮助中，也不能由 CLI 或工具箱直接执行；声明在页面事件中的普通 `app.command` 仍保留公开调用能力。
 
@@ -466,7 +510,7 @@ try {
 } finally { models.disconnect(); }
 ```
 
-`start` 返回持久 taskId；`run` 的 signal 取消模型执行并等待清理。`app.model(request, { onProgress })` / `context.model(request, { onProgress })` 可订阅当前这一次调用的 `model.delta`，并发调用的回调互相隔离；Python 使用 `context.model(request, on_progress=callback)`。增量 `data` 含 `delta/index/partial`，可用时带 `itemId/phase`；按消息隔离、跳过 commentary，序号缺失时回退到最终结果。增量只供临时展示，最终结果来自成功 turn 的完整消息并经过宿主 schema 校验；临时显示必须在失败时撤回，不能直接作为缓存或业务成功依据。模型目录与执行通过 `PluginModelClient` 或插件上下文使用。工具页使用 `host.model.capabilities/list/start` 和 `waitTask`。
+`start` 返回持久 taskId；`run` 的 signal 取消模型执行并等待清理。`app.model(request, { onProgress })` / `context.model(request, { onProgress })` 可订阅当前这一次调用的 `model.delta`，并发调用的回调互相隔离；Python 使用 `context.model(request, on_progress=callback)`。增量 `data` 含 `delta/index/partial`，可用时带 `itemId/phase`；按消息隔离、跳过 commentary，序号缺失时回退到最终结果。增量只供临时展示，最终结果来自成功 turn 的完整消息；outputSchema 透传模型 Provider，宿主解析 JSON，插件负责验证结果结构与业务约束；临时显示必须在失败时撤回，不能直接作为缓存或业务成功依据。模型目录与执行通过 `PluginModelClient` 或插件上下文使用。工具页使用 `host.model.capabilities/list/start` 和 `waitTask`。
 
 插件入口声明状态集合，然后从命令上下文访问：
 
@@ -482,11 +526,11 @@ export default app => app.command('save', async (input, context) => {
 });
 ```
 
-SDK `PluginStateClient.get/getMany/list/transact` 与工具箱 `host.state.*` 共享集合。每次写入需 CAS，冲突后重新读取、合并再重试；`schemaVersion` 升级用显式迁移事务。浏览器会话/实例可声明 `cache` 或 `memory`，页面身份由宿主验证。`memory` 只保存在插件执行宿主进程中，支持同样的 CAS、schema、TTL 与分块值限制；刷新文档时保留浏览器会话范围，浏览器会话变化后隔离，执行宿主重启时清空。内存状态全宿主合计最多 128 MiB / 512 个集合命名空间，按需占用；单集合 `maxBytes` 最大 128 MiB，实例结束释放其内存。容量、TTL 和完整契约见[插件宿主能力](../native-host/README.md#状态和激活)。二进制资产继续使用文件或资源通道。
+SDK `PluginStateClient.get/getMany/list/transact` 与工具箱 `host.state.*` 共享集合。schema 保留为格式描述和版本身份，写入与迁移的数据由插件自行验证；宿主检查 JSON、大小、版本和事务约束。每次写入需 CAS，冲突后重新读取、合并再重试；`schemaVersion` 升级用显式迁移事务。浏览器会话/实例可声明 `cache` 或 `memory`，页面身份由宿主验证。`memory` 只保存在插件执行宿主进程中，支持同样的 CAS、格式版本、TTL 与分块值限制；刷新文档时保留浏览器会话范围，浏览器会话变化后隔离，执行宿主重启时清空。内存状态全宿主合计最多 128 MiB / 512 个集合命名空间，按需占用；单集合 `maxBytes` 最大 128 MiB，实例结束释放其内存。容量、TTL 和完整契约见[插件宿主能力](../native-host/README.md#状态和激活)。二进制资产继续使用文件或资源通道。
 
 ### 显式任务恢复
 
-插件声明 `taskRecovery`（每个命令的 checkpointVersion/schema）并注册 `app.recoveryCommand(command, handler)`，命令通过 `context.checkpoint(data, expectedSequence)` 保存最多 64 KiB 的恢复依据。检查点数据、版本、宿主 schemaHash、序号和事件与任务记录原子写入；写入必须 CAS。
+插件声明 `taskRecovery`（每个命令的 checkpointVersion/schema）并注册 `app.recoveryCommand(command, handler)`，命令通过 `context.checkpoint(data, expectedSequence)` 保存最多 64 KiB 的恢复依据。检查点数据、版本、宿主 schemaHash、序号和事件与任务记录原子写入；写入必须 CAS。schema 用于声明身份和格式兼容比较，检查点及迁移数据的结构由插件验证。
 
 `tasks.checkpoint(taskId)` 读取检查点；`tasks.resume(taskId, { environment?, revision? })` 为终态根命令建立新 attempt，保持旧任务终态，固定原安装、源码快照、输入、目录和路由。默认提交调用进程的新环境，旧环境不持久化。恢复入口读取 `context.recovery`，先核对外部操作状态；宿主不重放原 handler，也不保证外部提交与检查点原子。
 

package/dist/actionTimeouts.js

@@ -1,4 +1,4 @@
-import { PAGE_ACT_ACTIONS } from './generated-browser-action-protocol.js';
+import { PAGE_ACT_ACTIONS } from './generated/browser-action-protocol.js';
 const SEND_REQUEST_FILE_TRANSFER_TIMEOUT_MS = 120_000;
 // Remote Providers may stage files before forwarding a page upload.
 const PAGE_UPLOAD_FILE_TRANSFER_TIMEOUT_MS = 180_000;

package/dist/artifacts.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserArtifact } from './generated-browser-action-protocol.js';
+import type { BrowserArtifact } from './generated/browser-action-protocol.js';
 import type { UnifiedInvokeOptions } from './unified.js';
 interface Invoker {
     invoke(action: string, data?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;

package/dist/browserRegistry.d.ts

@@ -8,7 +8,7 @@
  * registry directory and record shape; reading scans every *.json in the dir,
  * so it never needs to replicate daemon-core's filename hashing.
  */
-import type { BrowserCapabilities, BrowserDetails, BrowserPairingInfo, BrowserProviderIdentity, BrowserProviderOperation, BrowserReference, BrowserTransport } from './generated-browser-action-protocol.js';
+import type { BrowserCapabilities, BrowserDetails, BrowserPairingInfo, BrowserProviderIdentity, BrowserProviderOperation, BrowserReference, BrowserTransport } from './generated/browser-action-protocol.js';
 export interface LiveBrowser {
     pid: number;
     browserId: string;

package/dist/check.d.ts

@@ -1,6 +1,6 @@
 import type { CloudConnectorInfo } from '@mearl/cloud-types';
 import { type NativeHostDiagnostic } from './nativeHost.js';
-import type { BrowserCapabilities, BrowserProviderIdentity, BrowserProviderOperation } from './generated-browser-action-protocol.js';
+import type { BrowserCapabilities, BrowserProviderIdentity, BrowserProviderOperation } from './generated/browser-action-protocol.js';
 import { type UnifiedClientOptions, type UnifiedInvokeOptions } from './unified.js';
 export interface UnifiedCheckVersions {
     nativeHost?: string;

package/dist/cli.js

@@ -8,7 +8,7 @@ import { commandInput, findCommandSuggestions, formatCommandSuggestions, } from
 import { COMMANDS, COMMAND_MAP } from './commands.js';
 import { CLIENT_VERSION } from './socket.js';
 import { UnifiedClient } from './unified.js';
-import { findPluginEntry, findPluginRegistration, findOfficialPlugin, listPluginNames, listOfficialPluginNames, loadRegisteredPlugin, PluginError, } from './plugin.js';
+import { findPluginEntry, findPluginRegistration, findOfficialPlugin, listPluginNames, listOfficialPluginNames, loadRegisteredPlugin, PluginError, } from './plugins/sdk/plugin.js';
 import { getCloudServerConfigPath, loadCloudServerConfig } from './unifiedConfig.js';
 const TOP_LEVEL_COMMAND_NAME_WIDTH = 22;
 const CATEGORIES = [
@@ -90,6 +90,7 @@ const PLUGIN_HOST_OPTIONS = new Set([
     '--payload',
     '--payload-file',
     '--server',
+    '--session',
     '--timeout',
     '--verbose',
     '--version',
@@ -104,7 +105,7 @@ function findPluginInputOptionNames(args) {
         if (PLUGIN_HOST_OPTIONS.has(option))
             continue;
         const name = option.slice(2);
-        if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(name)) {
+        if (!/^[a-zA-Z][a-zA-Z0-9_]*$/.test(name)) {
             throw new Error(`无效的插件业务选项: ${option}`);
         }
         names.add(name);
@@ -473,7 +474,7 @@ export function parseClientArgs(args, plugin = false) {
         throw new Error('插件业务选项不能与 --payload 同时使用');
     }
     const json = options.json === true;
-    if (json && action !== 'check')
+    if (json && action !== 'check' && !plugin)
         throw new Error('--json 仅适用于 check');
     if (options.updates && action !== 'check')
         throw new Error('--updates 仅适用于 check');

package/dist/commands.d.ts

@@ -1,4 +1,4 @@
-import { type BrowserCommandAction } from './generated-browser-action-protocol.js';
+import { type BrowserCommandAction } from './generated/browser-action-protocol.js';
 export interface ParamDef {
     name: string;
     type: string;
@@ -297,7 +297,7 @@ export declare const COMMANDS: readonly [{
         readonly type: "string";
         readonly description: "规则说明";
     }];
-    readonly notes: readonly ["扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。"];
+    readonly notes: readonly ["扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。", "扩展模式会检查规则请求 URL 和显式来源域名的访问权限；缺失时仍保存规则，返回 warnings 和 missingOrigins，不自动弹窗。可在请求规则页面授权，或按提示调用 request_domain_permission。复杂 URL 表达式无法完整推断域名时会提示手动检查。"];
     readonly examples: ["set_rule --payload '{\"actionType\":\"block\",\"filter\":\"^https://example\\\\.com/ads/.*\"}'", "set_rule --payload '{\"ruleId\":42,\"enabled\":false}'"];
 }, {
     readonly name: "get_rules";
@@ -487,7 +487,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "active";
         readonly type: "boolean";
-        readonly description: "是否激活目标 Tab 并恢复最小化窗口，默认 false；响应返回 activation 验证结果";
+        readonly description: "是否激活目标 Tab，默认 false；扩展免打扰默认开启，使用后台焦点模拟，关闭后才切换前台；响应返回 activation";
     }, {
         readonly name: "openerTabId";
         readonly type: "number";
@@ -613,7 +613,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
     readonly notes: readonly ["selector / text / point 必须且只能提供一个。隐藏页 auto 使用 DOM；只有明确依赖真实用户手势时才激活页面。", "原生 select 可按 option 文本点击；checkbox/radio 返回 controlState.checkedBefore/checkedAfter。"];
     readonly examples: ["page_click --payload '{\"tabId\":12345,\"text\":\"提交\"}'", "page_click --payload '{\"tabId\":12345,\"text\":\"退款明细\",\"role\":\"button\"}'", "page_click --payload '{\"tabId\":12345,\"text\":\"确定\",\"scope\":\"@e12\"}'", "page_click --payload '{\"tabId\":12345,\"selector\":\"@e3\"}'", "page_click --payload '{\"tabId\":12345,\"selector\":\".submit-btn\"}'", "page_click --payload '{\"tabId\":12345,\"selector\":\".gesture-btn\",\"clickMode\":\"touch\"}'", "page_click --payload '{\"tabId\":12345,\"point\":{\"x\":336,\"y\":117}}'", "page_click --payload '{\"tabId\":12345,\"point\":{\"x\":196,\"y\":240},\"coordinateSpace\":\"active-frame\"}'"];
 }, {
@@ -643,7 +643,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
     readonly notes: readonly ["起点会自动滚入视口，终点必须同时位于当前视口；否则先滚动页面。隐藏页 auto 使用 DOM，不切换活动页。"];
     readonly examples: ["page_drag --payload '{\"tabId\":12345,\"from\":{\"x\":350,\"y\":80},\"to\":{\"x\":80,\"y\":80}}'", "page_drag --payload '{\"tabId\":12345,\"from\":\"@e3\",\"to\":\"#drop-zone\",\"dragMode\":\"mouse\"}'"];
 }, {
@@ -669,7 +669,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
     readonly examples: ["page_type --payload '{\"tabId\":12345,\"selector\":\"@e6\",\"text\":\"搜索关键词\"}'"];
 }, {
     readonly name: "page_hover";
@@ -685,7 +685,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
     readonly examples: ["page_hover --payload '{\"tabId\":12345,\"selector\":\".nav-menu\"}'"];
 }, {
     readonly name: "page_scroll";
@@ -713,7 +713,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。", "action.data 返回 moved、atTop/atBottom、scrollYBefore/After、maxScrollY、resolvedContainer 和 ancestorDistance；自动发现的内部容器提供可复用 containerSelector。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。", "action.data 返回 moved、atTop/atBottom、scrollYBefore/After、maxScrollY、resolvedContainer 和 ancestorDistance；自动发现的内部容器提供可复用 containerSelector。"];
     readonly examples: ["page_scroll --payload '{\"tabId\":12345,\"direction\":\"down\"}'", "page_scroll --payload '{\"tabId\":12345,\"direction\":\"bottom\"}'", "page_scroll --payload '{\"tabId\":12345,\"selector\":\".virtual-list\",\"direction\":\"down\",\"distance\":800}'", "page_scroll --payload '{\"tabId\":12345,\"selector\":\"@e8\",\"containerPolicy\":\"nearest\",\"direction\":\"bottom\"}'"];
 }, {
     readonly name: "page_runtime";
@@ -821,7 +821,7 @@ export declare const COMMANDS: readonly [{
         readonly description: "目标标签页 ID";
     }];
     readonly notes: readonly ["隐藏页 DOM 模式支持 Tab 焦点移动、原生控件 Enter/Space 激活和输入框 Enter 提交；编辑、选择、方向键和页面滚动等原生行为需可见页与 pressMode=keyboard。"];
-    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。", "action.data.dispatchMode / fallbackReason / defaultAction 说明实际输入路径。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。", "action.data.dispatchMode / fallbackReason / defaultAction 说明实际输入路径。"];
     readonly examples: ["page_press --payload '{\"tabId\":12345,\"key\":\"Enter\"}'"];
 }, {
     readonly name: "page_wait";
@@ -911,7 +911,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
     readonly notes: readonly ["直接写入 input[type=file]，不依赖 file chooser；隐藏的文件节点也可上传。外部 Provider 的文件中转能力查询 mearl <providerId>。"];
     readonly examples: ["page_upload --payload '{\"tabId\":12345,\"selector\":\"#file-input\",\"filePaths\":[\"/Users/me/photo.jpg\"]}'"];
 }, {
@@ -1093,7 +1093,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "mtopEnv";
         readonly type: "\"default\" | \"prod\" | \"pre\"";
-        readonly description: "可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。扩展模式全局生效，CDP 模式仅作用于目标 tab";
+        readonly description: "可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。仅作用于目标 tab";
     }, {
         readonly name: "emulation";
         readonly type: "object";
@@ -1211,7 +1211,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "需要授权的域名，如 example.com";
     }];
-    readonly notes: readonly ["domain 使用纯主机名，不传 URL。仅在非 BUC send_request 报域权限缺失时申请，BUC 不使用浏览器域权限。", "弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。"];
+    readonly notes: readonly ["domain 使用纯主机名，不传 URL。在非 BUC send_request 报域权限缺失，或 set_rule 提示缺少域名权限时申请；BUC 不使用浏览器域权限。", "弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。"];
     readonly result: readonly ["返回 granted、domain，授权成功时包含 origin。"];
     readonly examples: ["request_domain_permission --payload '{\"domain\":\"example.com\"}'"];
 }, {

package/dist/commands.js

@@ -1,4 +1,4 @@
-import { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, } from './generated-browser-action-protocol.js';
+import { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, } from './generated/browser-action-protocol.js';
 /** 容器档案名列表（拼进参数说明，新增档案无需改本文件） */
 const APP_PROFILE_NAME_LIST = APP_PROFILE_NAMES.join('/');
 const DEVICE_PRESET_TYPE = BROWSER_DEVICE_PRESET_NAMES.map(name => JSON.stringify(name)).join(' | ');
@@ -32,6 +32,7 @@ const PAGE_ACTION_RESULT = [
     'observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。',
     '包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。',
     'observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。',
+    'effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。',
     'fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。',
     '显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。',
 ];
@@ -297,6 +298,7 @@ export const COMMANDS = [
         ],
         notes: [
             '扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。',
+            '扩展模式会检查规则请求 URL 和显式来源域名的访问权限；缺失时仍保存规则，返回 warnings 和 missingOrigins，不自动弹窗。可在请求规则页面授权，或按提示调用 request_domain_permission。复杂 URL 表达式无法完整推断域名时会提示手动检查。',
         ],
         examples: [
             `set_rule --payload '{"actionType":"block","filter":"^https://example\\\\.com/ads/.*"}'`,
@@ -499,7 +501,7 @@ export const COMMANDS = [
             {
                 name: 'active',
                 type: 'boolean',
-                description: '是否激活目标 Tab 并恢复最小化窗口，默认 false；响应返回 activation 验证结果',
+                description: '是否激活目标 Tab，默认 false；扩展免打扰默认开启，使用后台焦点模拟，关闭后才切换前台；响应返回 activation',
             },
             {
                 name: 'openerTabId',
@@ -1199,7 +1201,7 @@ export const COMMANDS = [
             {
                 name: 'mtopEnv',
                 type: '"default" | "prod" | "pre"',
-                description: '可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。扩展模式全局生效，CDP 模式仅作用于目标 tab',
+                description: '可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。仅作用于目标 tab',
             },
             {
                 name: 'emulation',
@@ -1351,7 +1353,7 @@ export const COMMANDS = [
             },
         ],
         notes: [
-            'domain 使用纯主机名，不传 URL。仅在非 BUC send_request 报域权限缺失时申请，BUC 不使用浏览器域权限。',
+            'domain 使用纯主机名，不传 URL。在非 BUC send_request 报域权限缺失，或 set_rule 提示缺少域名权限时申请；BUC 不使用浏览器域权限。',
             '弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。',
         ],
         result: ['返回 granted、domain，授权成功时包含 origin。'],

package/dist/{generated-app-profile-definition.d.ts → generated/app-profile-definition.d.ts}

@@ -1,5 +1,5 @@
-import type { BrowserDevicePresetName, AppBridgeConfig } from './generated-browser-action-protocol.js';
-import type { AppBridgeSpec, AppImagePickerConfig, AppLayerUrlProxyConfig, AppMiniProgramConfig, AppNativeBackConfig, AppOverlayConfig, AppSchemeRule, AppTitleBarHostStyle, BridgeActionMap } from './generated-app-profile-runtime-types.js';
+import type { BrowserDevicePresetName, AppBridgeConfig } from './browser-action-protocol.js';
+import type { AppBridgeSpec, AppImagePickerConfig, AppLayerUrlProxyConfig, AppMiniProgramConfig, AppNativeBackConfig, AppOverlayConfig, AppSchemeRule, AppTitleBarHostStyle, BridgeActionMap } from './app-profile-runtime-types.js';
 export interface AppProfilePolicies {
     titleBar?: 'default' | 'taobao' | 'fliggy' | 'alipay' | 'wechat';
     navigatorLanguage?: boolean;

package/dist/{generated-app-profile-runtime-types.d.ts → generated/app-profile-runtime-types.d.ts}

@@ -1,5 +1,5 @@
-import type { AppProfileBinding, AppProfilePolicies, AppProfileSetting } from './generated-app-profile-definition.js';
-import type { BrowserDevicePresetName } from './generated-browser-action-protocol.js';
+import type { AppProfileBinding, AppProfilePolicies, AppProfileSetting } from './app-profile-definition.js';
+import type { BrowserDevicePresetName } from './browser-action-protocol.js';
 type DeviceCutout = 'none' | 'dynamic-island' | 'notch' | 'side-camera';
 /** 桥调用风格，与页面适配器使用的端内调用约定一一对应。 */
 export type AppBridgeStyle = 'windvane' | 'fliggy' | 'alipay' | 'callback' | 'btrip' | 'invoke' | 'callHandler' | 'amap' | 'didi' | 'easybikeNative' | 'mega' | 'wechat' | 'wechatMiniProgram';

package/dist/{generated-browser-action-protocol.d.ts → generated/browser-action-protocol.d.ts}

@@ -534,7 +534,7 @@ export interface SetAppProfileParams {
     bridgeConfig?: AppBridgeConfig;
     /**
      * 可选 MTop 接口环境。default 关闭环境改写；省略时保持当前设置。
-     * 扩展模式与插件设置页共享并全局生效；CDP 模式仅作用于目标 tab。
+     * 仅作用于目标 tab，扩展模式与该 tab 的快捷设置共享。
      */
     mtopEnv?: MtopEnvironment;
     /**

package/dist/{generated-plugin-diagnostics.d.ts → generated/plugin-diagnostics.d.ts}

@@ -1,7 +1,7 @@
-import type { PluginExecutionHost, PluginInvocationSource } from './generated-plugin-execution.js';
-import type { PluginTaskState, PluginTaskResultReference } from './generated-plugin-tasks.js';
-import type { PluginTaskCheckpointReference } from './generated-plugin-recovery.js';
-import type { PluginModelDiagnostic } from './generated-plugin-models.js';
+import type { PluginExecutionHost, PluginInvocationSource } from './plugin-execution.js';
+import type { PluginTaskState, PluginTaskResultReference } from './plugin-tasks.js';
+import type { PluginTaskCheckpointReference } from './plugin-recovery.js';
+import type { PluginModelDiagnostic } from './plugin-models.js';
 export interface PluginDiagnosticOptions {
     taskId?: string;
     plugin?: string;

package/dist/{generated-plugin-execution.d.ts → generated/plugin-execution.d.ts}

@@ -1,5 +1,5 @@
-import type { PluginPageBinding } from './generated-plugin-pages.js';
-import type { PluginTaskRecoveryContext } from './generated-plugin-recovery.js';
+import type { PluginPageBinding } from './plugin-pages.js';
+import type { PluginTaskRecoveryContext } from './plugin-recovery.js';
 /** Identifies an execution environment separately from a process incarnation. */
 export interface PluginExecutionHost {
     hostId: string;

package/dist/generated/plugin-host-build.d.ts

@@ -0,0 +1 @@
+export declare const PLUGIN_HOST_BUILD_ID = "1d85713299314f3ff82faecc749a025177411fdedd16949cee34e6712b93e1ef";

package/dist/generated/plugin-host-build.js

@@ -0,0 +1,2 @@
+// Generated by scripts/generate-plugin-host-build.mjs.
+export const PLUGIN_HOST_BUILD_ID = '1d85713299314f3ff82faecc749a025177411fdedd16949cee34e6712b93e1ef';

package/dist/{generated-plugin-pages.d.ts → generated/plugin-pages.d.ts}

@@ -1,4 +1,4 @@
-import type { PluginExecutionError, PluginExecutionHost } from './generated-plugin-execution.js';
+import type { PluginExecutionError, PluginExecutionHost } from './plugin-execution.js';
 export declare const PLUGIN_PAGE_LEASE_MS = 30000;
 /** Document or access-scope invalidation can cross transports that preserve only a message. */
 export declare function isPluginPageInvalidation(error: unknown): boolean;

package/dist/{generated-plugin-tasks.d.ts → generated/plugin-tasks.d.ts}

@@ -1,5 +1,5 @@
-import type { PluginExecutionError, PluginExecutionHost, PluginInvocationSource } from './generated-plugin-execution.js';
-import type { PluginTaskCheckpointReference } from './generated-plugin-recovery.js';
+import type { PluginExecutionError, PluginExecutionHost, PluginInvocationSource } from './plugin-execution.js';
+import type { PluginTaskCheckpointReference } from './plugin-recovery.js';
 export declare const PLUGIN_TASK_PROTOCOL_VERSION = 5;
 export type PluginTaskState = 'queued' | 'running' | 'cancelling' | 'success' | 'error' | 'cancelled' | 'interrupted';
 export interface PluginTaskResultReference {

package/dist/index.d.ts

@@ -1,21 +1,21 @@
-export { PluginHostConnection, type PluginHostConnectionOptions, type PluginHostClientOptions, } from './pluginHostConnection.js';
+export { PluginHostConnection, type PluginHostConnectionOptions, type PluginHostClientOptions, } from './plugins/clients/pluginHostConnection.js';
 /**
  * @mearl/client — unified Mearl browser client
  *
  * Discovers browser targets on this machine and every configured cloud connector,
  * then routes actions using the global browser ids returned by browser_list.
  */
-export { PluginTaskClient, type PluginTaskStartOptions, type PluginTaskWaitOptions, type PluginTaskClientOptions, type PluginTask, type PluginTaskEvents, type PluginTaskListResult, type PluginTaskStartResult, } from './pluginTasks.js';
-export { PluginPageClient } from './pluginPages.js';
-export type { PluginPageInstance, PluginPageEvents, PluginPageRuntime, PluginPageActivation, PluginPageTarget, PluginPageOperation, } from './pluginPages.js';
-export { executeRegisteredPlugin, type PluginExecutorOptions, type PluginExecutorDependencies, type PluginCommandContext, type PluginExecutionHost, type PluginInvocationIdentity, type PluginInvocationSource, } from './plugin.js';
+export { PluginTaskClient, type PluginTaskStartOptions, type PluginTaskWaitOptions, type PluginTaskClientOptions, type PluginTask, type PluginTaskEvents, type PluginTaskListResult, type PluginTaskStartResult, } from './plugins/clients/pluginTasks.js';
+export { PluginPageClient } from './plugins/clients/pluginPages.js';
+export type { PluginPageInstance, PluginPageEvents, PluginPageRuntime, PluginPageActivation, PluginPageTarget, PluginPageOperation, } from './plugins/clients/pluginPages.js';
+export { executeRegisteredPlugin, type PluginExecutorOptions, type PluginExecutorDependencies, type PluginCommandContext, type PluginExecutionHost, type PluginInvocationIdentity, type PluginInvocationSource, } from './plugins/sdk/plugin.js';
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, invokePlugin, listCloudConnectors, } from './unified.js';
 export type { UnifiedClientOptions, UnifiedInvokeOptions, UnifiedInvokeOptions as InvokeOptions, } from './unified.js';
-export type { PluginInvocation, PluginInvokeOptions, PluginProgress, StructuredPluginProgress, } from './plugin.js';
-export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_CAPABILITY_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
-export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserJsonValue, BrowserLaunchParams, BrowserProviderOperation, BrowserListResult, BrowserPairingInfo, BrowserReleaseFailure, BrowserReleaseResult, BrowserProviderDefinition, BrowserProviderIdentity, BrowserProviderInputSchema, BrowserProviderListResult, BrowserReference, BrowserDetails, BrowserSource, BrowserStatus, BrowserScreenshotKind, BrowserTransport, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageInspectFilter, PageInspectParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestBinaryBody, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, } from './generated-browser-action-protocol.js';
+export type { PluginInvocation, PluginInvokeOptions, PluginProgress, StructuredPluginProgress, } from './plugins/sdk/plugin.js';
+export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_CAPABILITY_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated/browser-action-protocol.js';
+export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserJsonValue, BrowserLaunchParams, BrowserProviderOperation, BrowserListResult, BrowserPairingInfo, BrowserReleaseFailure, BrowserReleaseResult, BrowserProviderDefinition, BrowserProviderIdentity, BrowserProviderInputSchema, BrowserProviderListResult, BrowserReference, BrowserDetails, BrowserSource, BrowserStatus, BrowserScreenshotKind, BrowserTransport, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageInspectFilter, PageInspectParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestBinaryBody, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, } from './generated/browser-action-protocol.js';
 import { type UnifiedInvokeOptions } from './unified.js';
-import type * as Protocol from './generated-browser-action-protocol.js';
+import type * as Protocol from './generated/browser-action-protocol.js';
 export declare function tabCheckpoint(params: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;
 /** Compatibility wrapper for tabCheckpoint. */
 export declare function captureCheckpoint(params: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;
@@ -66,9 +66,9 @@ export declare function saveArtifact(artifact: Protocol.BrowserArtifact & {
     outputPath: string;
     bytes: number;
 }>;
-export { PluginStateClient } from './pluginState.js';
-export { PluginModelClient } from './pluginModels.js';
-export type * from './generated-plugin-state.js';
-export type * from './generated-plugin-models.js';
-export type * from './generated-plugin-recovery.js';
-export type * from './generated-plugin-diagnostics.js';
+export { PluginStateClient } from './plugins/clients/pluginState.js';
+export { PluginModelClient } from './plugins/clients/pluginModels.js';
+export type * from './generated/plugin-state.js';
+export type * from './generated/plugin-models.js';
+export type * from './generated/plugin-recovery.js';
+export type * from './generated/plugin-diagnostics.js';