@mearl/client 2.21.0 → 2.22.0

package/README.md

@@ -211,6 +211,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 +234,7 @@ setup 会补齐缺失或低于自身版本的 client、native-host；安装参
 使用位置参数和业务选项，`--payload` 不能与前两种形式混用。JSON 保留业务字段类型；正文等文件输入按具体
 skill 的字段约定处理。`browser`、`timeout`、`output` 等宿主选项保留原有含义；同名业务字段以及数字、
 布尔值、对象和数组通过 `--payload` 传入。插件不使用上表中内置 action 的 `--payload-file` 入口。
+业务选项名称支持字母开头的字母、数字和下划线组合，下划线原样传递。
 
 注册后的插件也可从 SDK 调用；实例方法 `client.invokePlugin` 复用既有连接和默认浏览器：
 
@@ -347,6 +362,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 +394,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 +437,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

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;
@@ -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\"]}'"];
 }, {

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 独立。',
 ];
@@ -499,7 +500,7 @@ export const COMMANDS = [
             {
                 name: 'active',
                 type: 'boolean',
-                description: '是否激活目标 Tab 并恢复最小化窗口，默认 false；响应返回 activation 验证结果',
+                description: '是否激活目标 Tab，默认 false；扩展免打扰默认开启，使用后台焦点模拟，关闭后才切换前台；响应返回 activation',
             },
             {
                 name: 'openerTabId',

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-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-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';

package/dist/index.js

@@ -1,15 +1,15 @@
-export { PluginHostConnection, } from './pluginHostConnection.js';
+export { PluginHostConnection, } 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, } from './pluginTasks.js';
-export { PluginPageClient } from './pluginPages.js';
-export { executeRegisteredPlugin, } from './plugin.js';
+export { PluginTaskClient, } from './plugins/clients/pluginTasks.js';
+export { PluginPageClient } from './plugins/clients/pluginPages.js';
+export { executeRegisteredPlugin, } from './plugins/sdk/plugin.js';
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, invokePlugin, listCloudConnectors, } from './unified.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 { 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';
 import { invoke } from './unified.js';
 export function tabCheckpoint(params, options) {
     return invoke('tab_checkpoint', params, options);
@@ -144,5 +144,5 @@ export async function saveArtifact(artifact, outputPath, options = {}) {
     const { exportArtifact } = await import('./artifacts.js');
     return exportArtifact({ invoke }, artifact, outputPath, options);
 }
-export { PluginStateClient } from './pluginState.js';
-export { PluginModelClient } from './pluginModels.js';
+export { PluginStateClient } from './plugins/clients/pluginState.js';
+export { PluginModelClient } from './plugins/clients/pluginModels.js';

package/dist/pageEvalArguments.d.ts

@@ -1,3 +1,3 @@
-import { type PageEvalParams } from './generated-browser-action-protocol.js';
+import { type PageEvalParams } from './generated/browser-action-protocol.js';
 /** Serialize page_eval arguments within transport limits while retaining the caller's execution world. */
 export declare function invokePageEvalWithArgs(invoke: (payload: Record<string, unknown>, transfer?: boolean) => Promise<any>, params: PageEvalParams): Promise<any>;

package/dist/pageEvalArguments.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { validatePageUserScriptParams, resolvePageEvalExpression, } from './generated-browser-action-protocol.js';
+import { validatePageUserScriptParams, resolvePageEvalExpression, } from './generated/browser-action-protocol.js';
 const CHUNK_CHARACTERS = 48 * 1024;
 /** Serialize page_eval arguments within transport limits while retaining the caller's execution world. */
 export async function invokePageEvalWithArgs(invoke, params) {

package/dist/plugin-task-host.js

@@ -1,4 +1,4 @@
-import { startPluginHostServer } from './pluginHostServer.js';
+import { startPluginHostServer } from './plugins/runtime/pluginHostServer.js';
 try {
     const server = await startPluginHostServer();
     const close = () => {

package/dist/plugin-worker.js

@@ -1,9 +1,9 @@
-import { supervisePluginExecutor } from './pluginExecutorSupervisor.js';
+import { supervisePluginExecutor } from './plugins/runtime/pluginExecutorSupervisor.js';
 if (process.argv[2] === '--command') {
     let command;
     // Register IPC before loading command code so startup messages retain their order.
     process.on('message', (message) => {
-        void (command ??= import('./pluginCommandWorker.js'))
+        void (command ??= import('./plugins/runtime/pluginCommandWorker.js'))
             .then(worker => worker.handlePluginWorkerMessage(message))
             .catch(error => {
             process.stderr.write(String(error));

package/dist/plugin.d.ts

@@ -1,118 +1 @@
-import type { PluginTaskRecoveryDeclaration, PluginTaskCheckpoint, PluginCheckpointMigrationInput } from './generated-plugin-recovery.js';
-import type { PluginStateDeclaration } from './generated-plugin-state.js';
-import type { PluginModelRequest, PluginModelResult } from './generated-plugin-models.js';
-import type { PluginPageRuntime } from './generated-plugin-pages.js';
-import type { AppProfileContribution } from './generated-app-profile-definition.js';
-export type { AppProfileContribution, AppProfileDefinition, } from './generated-app-profile-definition.js';
-export { invokePageEvalWithArgs } from './pageEvalArguments.js';
-import { type OfficialPluginInstaller } from './officialPluginInstaller.js';
-import { type PluginToolboxContribution, type PluginRegistration } from './pluginRegistry.js';
-import { type PluginCommandContext, type PluginInvocationIdentity, type PluginInvocationSource } from './pluginExecution.js';
-import type { UnifiedInvokeOptions } from './unified.js';
-export type { PluginCommandContext, PluginExecutionHost, PluginInvocationIdentity, PluginInvocationSource, } from './pluginExecution.js';
-export { executeRegisteredPlugin, type PluginExecutorOptions, type PluginExecutorDependencies, } from './pluginExecutor.js';
-export { PluginTaskClient } from './pluginTasks.js';
-export { cleanupPluginRuntime } from './pluginRuntimeCleanup.js';
-export { PluginPageClient } from './pluginPages.js';
-export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, pluginDirectory, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, readPluginPageBundleChunk, type PluginRegistration, type PluginRegistrationOptions, type PluginToolboxAgentConfig, type PluginPageBundleRegistration, type PluginToolboxContribution, type PluginToolboxLocale, type PluginToolboxSandboxPage, } from './pluginRegistry.js';
-export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, type OfficialPluginDefinition, type OfficialPluginName, } from './officialPluginCatalog.js';
-export type PluginOptions = UnifiedInvokeOptions;
-export interface StructuredPluginProgress {
-    message: string;
-    data?: Record<string, unknown>;
-}
-export type PluginProgress = string | StructuredPluginProgress;
-export interface PluginInvocation {
-    command: string;
-    input: Record<string, any>;
-}
-export interface PluginInvokeOptions extends UnifiedInvokeOptions {
-    onProgress?: (progress: PluginProgress) => void;
-    signal?: AbortSignal;
-    /** Audit label supplied by the entry point, never an authorization decision. */
-    source?: PluginInvocationSource;
-}
-export interface PluginExecutionContext {
-    runModel?(plugin: string, request: PluginModelRequest, options: Pick<PluginInvokeOptions, 'signal' | 'onProgress'>): Promise<PluginModelResult>;
-    ensurePlugin?: OfficialPluginInstaller;
-    source?: PluginInvocationSource;
-    parentInvocation?: PluginInvocationIdentity;
-    invocation?: PluginInvocationIdentity;
-    resolveRegistration?: (name: string) => PluginRegistration | undefined;
-    invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions, onProgress?: PluginInvokeOptions['onProgress']): Promise<any>;
-}
-export interface PluginApp {
-    readonly options: Readonly<PluginOptions>;
-    /** Examples omit the `mearl <plugin>` prefix, which help adds when displayed. */
-    command(signature: string, handler: PluginHandler, description?: string, examples?: string[]): void;
-    /** Registers a page-only command, also declared in toolbox.page.commands. */
-    state(collection: string, operation: string, input?: Record<string, unknown>): Promise<any>;
-    model(request: PluginModelRequest, options?: Pick<PluginInvokeOptions, 'onProgress'>): Promise<PluginModelResult>;
-    runtimeCommand(signature: string, handler: PluginHandler, description?: string, examples?: string[]): void;
-    recoveryCommand(command: string, handler: PluginHandler): void;
-    checkpointMigration(command: string, handler: (input: PluginCheckpointMigrationInput, context: PluginCommandContext) => unknown | Promise<unknown>): void;
-    checkpoint(data: unknown, expectedSequence: number): Promise<PluginTaskCheckpoint>;
-    page(operation: string, input?: Record<string, unknown>): Promise<any>;
-    toolboxCommand(signature: string, handler: PluginHandler, description?: string, examples?: string[]): void;
-    invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
-    progress(progress: PluginProgress): void;
-}
-export type PluginHandler = (input: Record<string, any>, context: PluginCommandContext) => unknown | Promise<unknown>;
-/** 工具列表仅检查入口；页面资源只在打开对应工具时检查。 */
-export declare function refreshRegisteredPlugin(name: string, includePage?: boolean): Promise<PluginRegistration | undefined>;
-/** 注册和执行复用同一宿主能力边界；仅 handler 执行期间开放浏览器调用。 */
-export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'options' | 'progress'> & {
-    invoke: PluginExecutionContext['invoke'];
-    source?: PluginInvocationSource;
-    parentInvocation?: PluginInvocationIdentity;
-    invocation?: PluginInvocationIdentity;
-    signal?: AbortSignal;
-    runModel?: PluginExecutionContext['runModel'];
-    onInvocation?: (identity: PluginInvocationIdentity | undefined) => void;
-}, pluginName?: string): Promise<{
-    name: string | undefined;
-    description: string | undefined;
-    toolbox: PluginToolboxContribution | undefined;
-    pageRuntime: PluginPageRuntime | undefined;
-    stateStorage: PluginStateDeclaration | undefined;
-    taskRecovery: PluginTaskRecoveryDeclaration | undefined;
-    appProfiles: AppProfileContribution | undefined;
-    profileSources: Record<string, string> | undefined;
-    version: string | undefined;
-    commandHelp(namespace: string): string;
-    help(namespace: string, name?: string): string;
-    run(positionals: string[], payload?: unknown, namedInput?: Record<string, unknown>): Promise<unknown>;
-    runRuntime(invocation: PluginInvocation): Promise<unknown>;
-    runRecovery(invocation: PluginInvocation): Promise<unknown>;
-    runMigration(invocation: PluginInvocation): Promise<unknown>;
-    runToolbox(invocation: PluginInvocation): Promise<unknown>;
-}>;
-export declare function loadRegisteredPlugin(name: string, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<{
-    name: string | undefined;
-    description: string | undefined;
-    toolbox: PluginToolboxContribution | undefined;
-    pageRuntime: PluginPageRuntime | undefined;
-    stateStorage: PluginStateDeclaration | undefined;
-    taskRecovery: PluginTaskRecoveryDeclaration | undefined;
-    appProfiles: AppProfileContribution | undefined;
-    profileSources: Record<string, string> | undefined;
-    version: string | undefined;
-    commandHelp(namespace: string): string;
-    help(namespace: string, name?: string): string;
-    run(positionals: string[], payload?: unknown, namedInput?: Record<string, unknown>): Promise<unknown>;
-    runRuntime(invocation: PluginInvocation): Promise<unknown>;
-    runRecovery(invocation: PluginInvocation): Promise<unknown>;
-    runMigration(invocation: PluginInvocation): Promise<unknown>;
-    runToolbox(invocation: PluginInvocation): Promise<unknown>;
-}>;
-export declare function invokeRegisteredPlugin(name: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<unknown>;
-/** Entry point for the native toolbox service; nested plugin calls retain public-command access. */
-export declare function invokeRegisteredToolboxPlugin(name: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<unknown>;
-export declare function invokeRegisteredRuntimePlugin(name: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<unknown>;
-export declare function invokeRegisteredRecoveryPlugin(name: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<unknown>;
-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 * from './plugins/sdk/plugin.js';