@mearl/client 2.21.0 → 3.0.0-beta.0

package/dist/commands.d.ts

@@ -1,4 +1,4 @@
-import { type BrowserCommandAction } from './generated-browser-action-protocol.js';
+import { type BrowserCommandAction } from '@mearl/browser-core';
 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";
@@ -353,7 +353,7 @@ export declare const COMMANDS: readonly [{
         readonly type: "number";
         readonly description: "超时毫秒数，默认 30000";
     }];
-    readonly notes: readonly ["仅用于非 BUC 请求；BUC 接口使用 mearl buc，不手工传 Token、DPoP 或 Ticket。", "body 不能与 formData/files 组合；bodyFile 以原始字节发送，不包 multipart boundary，不能用于 GET/HEAD。", "bodyFile.filePath 属于 native-host，最大 40 MiB；base64 解码后最大 7 MiB。multipart 不手工设置 Content-Type，由 Mearl 生成 boundary。", "filePath 属于 native-host 所在机器；无法引用远端路径时用 base64。BUC 上传的路径属于插件执行宿主。"];
+    readonly notes: readonly ["需要托管认证的接口使用相应能力插件；不要手工传入其管理的凭据。", "body 不能与 formData/files 组合；bodyFile 以原始字节发送，不包 multipart boundary，不能用于 GET/HEAD。", "bodyFile.filePath 属于 native-host，最大 40 MiB；base64 解码后最大 7 MiB。multipart 不手工设置 Content-Type，由 Mearl 生成 boundary。", "filePath 属于请求执行宿主；无法引用远端路径时用 base64。"];
     readonly result: readonly ["返回 status、statusText、headers、body、bodyType、attachedCookieCount；bodyType 为 json/text/base64，二进制 body 需解码后保存。"];
     readonly examples: ["send_request --payload '{\"url\":\"https://api.example.com/data\",\"method\":\"GET\"}'", "send_request --payload '{\"url\":\"https://api.example.com/upload\",\"method\":\"POST\",\"formData\":{\"folder\":\"assets\"},\"files\":[{\"fieldName\":\"file\",\"filePath\":\"/absolute/path/image.png\"}]}'", "send_request --payload '{\"url\":\"https://api.example.com/upload\",\"method\":\"POST\",\"bodyFile\":{\"filePath\":\"/absolute/path/image.png\",\"contentType\":\"image/png\"}}'"];
 }, {
@@ -457,8 +457,8 @@ export declare const COMMANDS: readonly [{
         readonly description: "自定义 Chrome 可执行文件路径";
     }, {
         readonly name: "copyCookieDomains";
-        readonly type: "string[] | \"mearl-services\" | { presets?: [\"mearl-services\"]; domains?: string[] }";
-        readonly description: "从控制浏览器复制 Cookie：可传域名数组、Mearl 登录态预设，或组合预设与额外域名";
+        readonly type: "string[] | string | { presets?: string[]; domains?: string[] }";
+        readonly description: "从控制浏览器复制 Cookie：可传域名数组、已安装能力提供的范围名，或组合范围与额外域名";
     }];
     readonly examples: ["browser_launch --payload '{\"provider\":\"brow\",\"providerOptions\":{}}'", "browser_launch --payload '{\"name\":\"figma\",\"userAgentMode\":\"desktop\",\"copyCookieDomains\":[\"figma.com\"]}'", "browser_launch --payload '{\"name\":\"with-cookies\",\"copyCookieDomains\":[\"example.com\",\"sub.example.org\"]}'"];
 }, {
@@ -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";
@@ -519,7 +519,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "appProfile";
         readonly type: "string";
-        readonly description: "开 tab 即注入 App 客户端环境与 JSBridge；档案名同 set_app_profile，如 \"fliggy\"。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true";
+        readonly description: "按已安装档案应用 App 环境；内置基础档案只提供 UA/版本，完整桥由能力包提供。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true";
     }, {
         readonly name: "os";
         readonly type: "\"ios\" | \"android\"";
@@ -531,7 +531,7 @@ export declare const COMMANDS: readonly [{
     }];
     readonly notes: readonly ["emulation / appProfile 只应用到新建 Tab；复用 Tab 要切换状态时用对应设置 action。", "closeExisting 不能与复用或 openerTabId 组合；多匹配默认报错，match.onMultiple=first 可显式选择第一个。"];
     readonly result: readonly ["返回 tabId、url、title、opened/reused；reused=true 的既有页面应保留。", "active=true 时 activation 包含 tabActive、windowFocused、windowState、visibilityState；emulation 返回实际生效配置。", "capture.cursor 是导航前诊断边界，可分别用于 get_logs/get_requests/get_events 的 after。"];
-    readonly examples: ["tab_open --payload '{\"url\":\"https://example.com\"}'", "tab_open --payload '{\"url\":\"https://example.com/page\",\"reuse\":\"prefer\",\"match\":{\"ignoreSearch\":true}}'", "tab_open --payload '{\"url\":\"https://m.example.com\",\"emulation\":{\"preset\":\"iphone-17-pro\"}}'", "tab_open --payload '{\"url\":\"https://market.m.taobao.com/app/trip/rx-home/pages/home\",\"appProfile\":\"fliggy\"}'", "tab_open --payload '{\"url\":\"https://market.m.taobao.com/app/trip/rx-home/pages/home\",\"appProfile\":\"fliggy\",\"emulation\":{\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}}'", "tab_open --payload '{\"url\":\"https://example.com\",\"appProfile\":\"fliggy\",\"os\":\"android\"}'", "tab_open --payload '{\"url\":\"https://example.com\",\"group\":\"验证任务\"}'"];
+    readonly examples: ["tab_open --payload '{\"url\":\"https://example.com\"}'", "tab_open --payload '{\"url\":\"https://example.com/page\",\"reuse\":\"prefer\",\"match\":{\"ignoreSearch\":true}}'", "tab_open --payload '{\"url\":\"https://m.example.com\",\"emulation\":{\"preset\":\"iphone-17-pro\"}}'", "tab_open --payload '{\"url\":\"https://example.com/app/home\",\"appProfile\":\"fliggy\"}'", "tab_open --payload '{\"url\":\"https://example.com/app/home\",\"appProfile\":\"fliggy\",\"emulation\":{\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}}'", "tab_open --payload '{\"url\":\"https://example.com\",\"appProfile\":\"fliggy\",\"os\":\"android\"}'", "tab_open --payload '{\"url\":\"https://example.com\",\"group\":\"验证任务\"}'"];
 }, {
     readonly name: "tab_close";
     readonly description: "关闭指定标签页";
@@ -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\"]}'"];
 }, {
@@ -1055,7 +1055,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["set_device_emulation --payload '{\"tabId\":12345,\"enabled\":true,\"preset\":\"iphone-17-pro\"}'", "set_device_emulation --payload '{\"tabId\":12345,\"enabled\":true,\"preset\":\"pixel-11\",\"orientation\":\"landscape\"}'", "set_device_emulation --payload '{\"tabId\":12345,\"enabled\":true,\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}'", "set_device_emulation --payload '{\"tabId\":12345,\"enabled\":false}'"];
 }, {
     readonly name: "set_app_profile";
-    readonly description: "设置 App 客户端环境与 JSBridge；可同时设置 MTop 页面接口环境，传 emulation 时联动设备模拟";
+    readonly description: "设置已安装的 App 档案；完整 JSBridge 由能力包提供。可同时设置 MTop 页面接口环境，传 emulation 时联动设备模拟";
     readonly summary: "设置或清除目标标签页的 App 容器模拟";
     readonly params: [{
         readonly name: "enabled";
@@ -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";
@@ -1153,7 +1153,7 @@ export declare const COMMANDS: readonly [{
     }];
     readonly notes: readonly ["只读取指定非分区 Cookie，不列举全部、不回退分区 Cookie，拒绝 HttpOnly；禁止读取认证 Token。指定 url 不导航，指定 tabId 仅选择存储区时不启动采集。"];
     readonly result: readonly ["找到时 found=true 并返回 value/domain/path；不存在时 found=false。"];
-    readonly examples: ["get_cookie --payload '{\"tabId\":12345,\"name\":\"feature_flag\"}'", "get_cookie --payload '{\"url\":\"https://www.taobao.com/\",\"name\":\"tracknick\"}'", "get_cookie --payload '{\"tabId\":12345,\"name\":\"edith_switch_br.rx-vehicle-search_home\",\"domain\":\"taobao.com\"}'", "get_cookie --payload '{\"tabId\":12345,\"name\":\"tracknick\",\"url\":\"https://www.taobao.com/\",\"domain\":\"taobao.com\",\"path\":\"/\"}'"];
+    readonly examples: ["get_cookie --payload '{\"tabId\":12345,\"name\":\"feature_flag\"}'", "get_cookie --payload '{\"url\":\"https://www.taobao.com/\",\"name\":\"tracknick\"}'", "get_cookie --payload '{\"tabId\":12345,\"name\":\"feature_channel\",\"domain\":\"example.com\"}'", "get_cookie --payload '{\"tabId\":12345,\"name\":\"tracknick\",\"url\":\"https://www.taobao.com/\",\"domain\":\"example.com\",\"path\":\"/\"}'"];
 }, {
     readonly name: "set_cookie";
     readonly description: "在目标浏览器设置一个指定非分区 session Cookie，可选刷新指定页面";
@@ -1190,7 +1190,7 @@ export declare const COMMANDS: readonly [{
     }];
     readonly notes: readonly ["仅写非分区 session Cookie，不支持删除。reload=true 时校验目标域与刷新页域的授权。"];
     readonly result: readonly ["返回 url/name/domain/path/reloaded，指定标签页时包含 tabId；不回显 Cookie 值。"];
-    readonly examples: ["set_cookie --payload '{\"tabId\":12345,\"name\":\"feature_flag\",\"value\":\"enabled\"}'", "set_cookie --payload '{\"url\":\"https://www.taobao.com/\",\"name\":\"feature_flag\",\"value\":\"enabled\"}'", "set_cookie --payload '{\"tabId\":12345,\"name\":\"edith_switch_br.rx-vehicle-search_home\",\"value\":\"3.6.63\",\"domain\":\"taobao.com\",\"reload\":true}'"];
+    readonly examples: ["set_cookie --payload '{\"tabId\":12345,\"name\":\"feature_flag\",\"value\":\"enabled\"}'", "set_cookie --payload '{\"url\":\"https://www.taobao.com/\",\"name\":\"feature_flag\",\"value\":\"enabled\"}'", "set_cookie --payload '{\"tabId\":12345,\"name\":\"feature_channel\",\"value\":\"3.6.63\",\"domain\":\"example.com\",\"reload\":true}'"];
 }, {
     readonly name: "page_frames";
     readonly description: "获取页面主 frame 与所有 iframe 列表";
@@ -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。在 send_request 或 set_rule 提示缺少浏览器域名权限时申请。", "弹窗等待用户选择，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 '@mearl/browser-core';
 /** 容器档案名列表（拼进参数说明，新增档案无需改本文件） */
 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/.*"}'`,
@@ -347,10 +349,10 @@ export const COMMANDS = [
             { name: 'timeout', type: 'number', description: '超时毫秒数，默认 30000' },
         ],
         notes: [
-            '仅用于非 BUC 请求；BUC 接口使用 mearl buc，不手工传 Token、DPoP 或 Ticket。',
+            '需要托管认证的接口使用相应能力插件；不要手工传入其管理的凭据。',
             'body 不能与 formData/files 组合；bodyFile 以原始字节发送，不包 multipart boundary，不能用于 GET/HEAD。',
             'bodyFile.filePath 属于 native-host，最大 40 MiB；base64 解码后最大 7 MiB。multipart 不手工设置 Content-Type，由 Mearl 生成 boundary。',
-            'filePath 属于 native-host 所在机器；无法引用远端路径时用 base64。BUC 上传的路径属于插件执行宿主。',
+            'filePath 属于请求执行宿主；无法引用远端路径时用 base64。',
         ],
         result: [
             '返回 status、statusText、headers、body、bodyType、attachedCookieCount；bodyType 为 json/text/base64，二进制 body 需解码后保存。',
@@ -458,8 +460,8 @@ export const COMMANDS = [
             { name: 'executablePath', type: 'string', description: '自定义 Chrome 可执行文件路径' },
             {
                 name: 'copyCookieDomains',
-                type: 'string[] | "mearl-services" | { presets?: ["mearl-services"]; domains?: string[] }',
-                description: '从控制浏览器复制 Cookie：可传域名数组、Mearl 登录态预设，或组合预设与额外域名',
+                type: 'string[] | string | { presets?: string[]; domains?: string[] }',
+                description: '从控制浏览器复制 Cookie：可传域名数组、已安装能力提供的范围名，或组合范围与额外域名',
             },
         ],
         examples: [
@@ -499,7 +501,7 @@ export const COMMANDS = [
             {
                 name: 'active',
                 type: 'boolean',
-                description: '是否激活目标 Tab 并恢复最小化窗口，默认 false；响应返回 activation 验证结果',
+                description: '是否激活目标 Tab，默认 false；扩展免打扰默认开启，使用后台焦点模拟，关闭后才切换前台；响应返回 activation',
             },
             {
                 name: 'openerTabId',
@@ -539,7 +541,7 @@ export const COMMANDS = [
             {
                 name: 'appProfile',
                 type: 'string',
-                description: '开 tab 即注入 App 客户端环境与 JSBridge；档案名同 set_app_profile，如 "fliggy"。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true',
+                description: '按已安装档案应用 App 环境；内置基础档案只提供 UA/版本，完整桥由能力包提供。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true',
             },
             {
                 name: 'os',
@@ -565,8 +567,8 @@ export const COMMANDS = [
             `tab_open --payload '{"url":"https://example.com"}'`,
             `tab_open --payload '{"url":"https://example.com/page","reuse":"prefer","match":{"ignoreSearch":true}}'`,
             `tab_open --payload '{"url":"https://m.example.com","emulation":{"preset":"iphone-17-pro"}}'`,
-            `tab_open --payload '{"url":"https://market.m.taobao.com/app/trip/rx-home/pages/home","appProfile":"fliggy"}'`,
-            `tab_open --payload '{"url":"https://market.m.taobao.com/app/trip/rx-home/pages/home","appProfile":"fliggy","emulation":{"preset":"ipad-mini-a17-pro","orientation":"landscape","deviceShell":true,"splitScreen":true}}'`,
+            `tab_open --payload '{"url":"https://example.com/app/home","appProfile":"fliggy"}'`,
+            `tab_open --payload '{"url":"https://example.com/app/home","appProfile":"fliggy","emulation":{"preset":"ipad-mini-a17-pro","orientation":"landscape","deviceShell":true,"splitScreen":true}}'`,
             `tab_open --payload '{"url":"https://example.com","appProfile":"fliggy","os":"android"}'`,
             `tab_open --payload '{"url":"https://example.com","group":"验证任务"}'`,
         ],
@@ -1165,7 +1167,7 @@ export const COMMANDS = [
     },
     {
         name: 'set_app_profile',
-        description: '设置 App 客户端环境与 JSBridge；可同时设置 MTop 页面接口环境，传 emulation 时联动设备模拟',
+        description: '设置已安装的 App 档案；完整 JSBridge 由能力包提供。可同时设置 MTop 页面接口环境，传 emulation 时联动设备模拟',
         summary: '设置或清除目标标签页的 App 容器模拟',
         params: [
             { name: 'enabled', type: 'boolean', required: true, description: 'true=启用，false=清除' },
@@ -1199,7 +1201,7 @@ export const COMMANDS = [
             {
                 name: 'mtopEnv',
                 type: '"default" | "prod" | "pre"',
-                description: '可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。扩展模式全局生效，CDP 模式仅作用于目标 tab',
+                description: '可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。仅作用于目标 tab',
             },
             {
                 name: 'emulation',
@@ -1279,8 +1281,8 @@ export const COMMANDS = [
         examples: [
             `get_cookie --payload '{"tabId":12345,"name":"feature_flag"}'`,
             `get_cookie --payload '{"url":"https://www.taobao.com/","name":"tracknick"}'`,
-            `get_cookie --payload '{"tabId":12345,"name":"edith_switch_br.rx-vehicle-search_home","domain":"taobao.com"}'`,
-            `get_cookie --payload '{"tabId":12345,"name":"tracknick","url":"https://www.taobao.com/","domain":"taobao.com","path":"/"}'`,
+            `get_cookie --payload '{"tabId":12345,"name":"feature_channel","domain":"example.com"}'`,
+            `get_cookie --payload '{"tabId":12345,"name":"tracknick","url":"https://www.taobao.com/","domain":"example.com","path":"/"}'`,
         ],
     },
     {
@@ -1326,7 +1328,7 @@ export const COMMANDS = [
         examples: [
             `set_cookie --payload '{"tabId":12345,"name":"feature_flag","value":"enabled"}'`,
             `set_cookie --payload '{"url":"https://www.taobao.com/","name":"feature_flag","value":"enabled"}'`,
-            `set_cookie --payload '{"tabId":12345,"name":"edith_switch_br.rx-vehicle-search_home","value":"3.6.63","domain":"taobao.com","reload":true}'`,
+            `set_cookie --payload '{"tabId":12345,"name":"feature_channel","value":"3.6.63","domain":"example.com","reload":true}'`,
         ],
     },
     // ── 其他 ──────────────────────────────────────────────────────────────────
@@ -1351,7 +1353,7 @@ export const COMMANDS = [
             },
         ],
         notes: [
-            'domain 使用纯主机名，不传 URL。仅在非 BUC send_request 报域权限缺失时申请，BUC 不使用浏览器域权限。',
+            'domain 使用纯主机名，不传 URL。在 send_request 或 set_rule 提示缺少浏览器域名权限时申请。',
             '弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。',
         ],
         result: ['返回 granted、domain，授权成功时包含 origin。'],

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 '@mearl/browser-core';
+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 '@mearl/browser-core';
 import { type UnifiedInvokeOptions } from './unified.js';
-import type * as Protocol from './generated-browser-action-protocol.js';
+import type * as Protocol from '@mearl/browser-core';
 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,6 @@ 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 '@mearl/browser-core';

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 '@mearl/browser-core';
 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/local.d.ts

@@ -3,5 +3,7 @@
  * User-facing integrations should import from `@mearl/client` so browser routing
  * remains consistent across local and remote sources.
  */
-export { CLIENT_VERSION, SOCKET_PATH, decorateBrowserListResult, getDefaultBrowser, invoke, setDefaultBrowser, } from './socket.js';
+export { CLIENT_VERSION, SOCKET_PATH, decorateBrowserListResult, getDefaultBrowser, invoke, invokeLocalHost, setDefaultBrowser, } from './socket.js';
 export type { InvokeOptions } from './socket.js';
+export { listLiveBrowsers } from './browserRegistry.js';
+export type { LiveBrowser } from './browserRegistry.js';

package/dist/local.js

@@ -3,4 +3,5 @@
  * User-facing integrations should import from `@mearl/client` so browser routing
  * remains consistent across local and remote sources.
  */
-export { CLIENT_VERSION, SOCKET_PATH, decorateBrowserListResult, getDefaultBrowser, invoke, setDefaultBrowser, } from './socket.js';
+export { CLIENT_VERSION, SOCKET_PATH, decorateBrowserListResult, getDefaultBrowser, invoke, invokeLocalHost, setDefaultBrowser, } from './socket.js';
+export { listLiveBrowsers } from './browserRegistry.js';

package/dist/pageEvalArguments.d.ts

@@ -1,3 +1,3 @@
-import { type PageEvalParams } from './generated-browser-action-protocol.js';
+import { type PageEvalParams } from '@mearl/browser-core';
 /** 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 '@mearl/browser-core';
 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,2 @@
-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';
+export * from './plugins/skillManifest.js';