@mearl/client 3.0.0-beta.4 → 3.0.0-beta.7

package/dist/commands.js

@@ -1,6 +1,4 @@
-import { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, } from '@mearl/browser-core';
-/** 容器档案名列表（拼进参数说明，新增档案无需改本文件） */
-const APP_PROFILE_NAME_LIST = APP_PROFILE_NAMES.join('/');
+import { BROWSER_DEVICE_PRESET_NAMES, } from '@mearl/browser-core';
 const DEVICE_PRESET_TYPE = BROWSER_DEVICE_PRESET_NAMES.map(name => JSON.stringify(name)).join(' | ');
 const PAGE_DIAGNOSTICS_PARAM = {
     name: 'diagnostics',
@@ -30,13 +28,20 @@ const PAGE_OBSERVE_PARAM = {
 const PAGE_ACTION_RESULT = [
     '默认返回 { 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 结束。',
+    '包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。CLI 单次调用失败以退出码 1 结束；脚本需检查 action.success。',
     'observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。',
     'effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。',
     'fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。',
     '显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。',
 ];
 export const COMMANDS = [
+    {
+        name: 'get_capabilities',
+        description: '只读查询当前目标浏览器的动作、设备和已安装 App 能力、限制与 Skill/帮助入口；不打开页面或启用模拟',
+        params: [{ name: 'app', type: 'string', description: '可选，使用目录中的完整 App ID 查询桥方法、可调设置和默认版本详情' }],
+        notes: ['沿用 --browser / --session 路由；不传 app 返回摘要。apps.status=partial 表示目录未完整取得，unsupported 表示目标未提供目录；不能把两者当作未安装。', 'available=false 的 App 当前不可启用；支持某个 action 不代表已有域名权限或真实设备授权。按需读取 usage.skills / usage.documentation，查询不会自动安装或加载 Skill。'],
+        examples: ['get_capabilities', `get_capabilities --payload '{"app":"example/app"}'`],
+    },
     {
         name: 'browser_control',
         description: '把控制会话交给用户；用户在 Mearl 浏览器管理页交还后重新观察页面',
@@ -96,7 +101,7 @@ export const COMMANDS = [
     },
     {
         name: 'get_requests',
-        description: '获取最近的网络请求（mtop 或普通 xhr/fetch）',
+        description: '获取最近的网络请求（协议请求或普通 xhr/fetch）',
         params: [
             {
                 name: 'tabId',
@@ -107,8 +112,8 @@ export const COMMANDS = [
             { name: 'count', type: 'number', description: '返回条数，默认 10' },
             {
                 name: 'source',
-                type: '"mtop" | "requests" | "all"',
-                description: '数据来源，不填时默认 mtop；all 返回全部业务请求',
+                type: '"protocol" | "requests" | "all"',
+                description: '数据来源，不填时默认 all；all 返回全部业务请求',
             },
             { name: 'filter', type: 'string', description: '按 URL 或 API 名称过滤，支持正则' },
             { name: 'since', type: 'number', description: '只返回最近 N 秒内的请求' },
@@ -128,7 +133,7 @@ export const COMMANDS = [
             { name: 'keysOnly', type: 'boolean', description: '只返回数据结构，不返回叶子值' },
         ],
         notes: [
-            '流式请求开始后即进入缓冲区；页面及 App 桥代发的 MTop SSE 都归入 mtop。无法归属当前页面 target 的 Service Worker 请求不在采集范围内。',
+            '流式请求开始后即进入缓冲区；页面及 App 桥代发的 协议 SSE 都归入 protocol。无法归属当前页面 target 的 Service Worker 请求不在采集范围内。',
         ],
         result: [
             'nextCursor 用于同类查询续读，hasMore 表示还有数据，gap 表示缓冲区淘汰造成缺口；checkpoint cursor 可分别用于三类查询的初始边界。',
@@ -137,7 +142,7 @@ export const COMMANDS = [
         ],
         examples: [
             `get_requests --payload '{"tabId":12345,"count":5}'`,
-            `get_requests --payload '{"tabId":12345,"source":"mtop","filter":"cart"}'`,
+            `get_requests --payload '{"tabId":12345,"source":"protocol","filter":"cart"}'`,
         ],
     },
     {
@@ -244,7 +249,7 @@ export const COMMANDS = [
             '大字段可用顶层 @<绝对路径> 文件引用或 --payload-file；文件展开后仍受 Native Messaging 单条消息大小限制。',
         ],
         examples: [
-            `set_mock --payload '{"tabId":12345,"apiName":"mtop.cart.query","mockData":{"ret":["SUCCESS::调用成功"]}}'`,
+            `set_mock --payload '{"tabId":12345,"apiName":"cart.query","mockData":{"ret":["SUCCESS::调用成功"]}}'`,
             `set_mock --payload-file ./mock-data.json`,
         ],
     },
@@ -298,7 +303,7 @@ export const COMMANDS = [
         ],
         notes: [
             '扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。',
-            '扩展模式会检查规则请求 URL 和显式来源域名的访问权限；缺失时仍保存规则，返回 warnings 和 missingOrigins，不自动弹窗。可在请求规则页面授权，或按提示调用 request_domain_permission。复杂 URL 表达式无法完整推断域名时会提示手动检查。',
+            '扩展模式会检查规则请求 URL 和显式来源域名的访问权限；缺失时仍保存规则，返回 warnings 和 missingOrigins，不自动弹窗。可在请求规则页面授权，或按提示调用 request_permission。复杂 URL 表达式无法完整推断域名时会提示手动检查。',
         ],
         examples: [
             `set_rule --payload '{"actionType":"block","filter":"^https://example\\\\.com/ads/.*"}'`,
@@ -364,32 +369,28 @@ export const COMMANDS = [
         ],
     },
     {
-        name: 'send_mtop_request',
-        description: '使用目标浏览器 Cookie 发起 mtop 请求，自动处理签名和 token',
+        name: 'send_protocol_request',
+        description: '通过已安装的请求协议能力，使用目标浏览器 Cookie 发送请求',
         params: [
-            { name: 'api', type: 'string', required: true, description: 'mtop API 名称' },
-            { name: 'data', type: 'object', description: '请求数据' },
-            { name: 'version', type: 'string', description: 'API 版本，默认 1.0' },
-            { name: 'method', type: 'string', description: 'HTTP 方法，默认 GET' },
-            { name: 'appKey', type: 'string', description: '签名使用的 appKey，默认 12574478' },
-            { name: 'env', type: '"prod" | "pre"', description: '请求环境，默认 prod' },
-            { name: 'timeout', type: 'number', description: '超时毫秒数，默认 10000' },
+            { name: 'timeout', type: 'number', description: '宿主超时毫秒数；协议能力负责校验具体参数' },
         ],
         notes: [
-            '需要目标浏览器有对应登录态；Mearl 自动处理签名，不依赖页面脚本。api 以 mopen. 开头时使用 mopen 协议。',
-            'env=prod 使用 h5api.m.taobao.com，pre 使用 h5api.wapa.taobao.com。',
-        ],
-        result: ['返回 success、response、requestData；业务成功需检查 response.ret。'],
-        examples: [
-            `send_mtop_request --payload '{"api":"mtop.trade.order.detail","data":{"orderId":"123"}}'`,
+            '需要安装提供 request.protocol 的能力包；参数、签名、网关与响应协议由能力包定义。',
+            '使用 --payload 传递协议文档声明的参数；核心不设置业务参数默认值。',
         ],
+        result: ['返回 success、response、requestData；业务结果由协议定义。'],
+        examples: [`send_protocol_request --payload '{"operation":"example","data":{}}'`],
     },
     // ── 浏览器 ────────────────────────────────────────────────────────────────
     {
         name: 'browser_list',
         description: '列出所有浏览器及其连接状态、类型和 Provider 托管实例信息',
         summary: '列出本地及远端浏览器与连接状态',
-        examples: ['browser_list'],
+        params: [
+            { name: 'provider', type: 'string', description: '配合 launchForm，仅查询一个本机已安装 Provider 的启动候选；需 --local' },
+            { name: 'launchForm', type: 'object', description: '现有动态启动表单请求：{variant?,values:{}}，不创建或接入实例' },
+        ],
+        examples: ['browser_list', 'browser_list --local'],
     },
     {
         name: 'browser_release',
@@ -496,6 +497,9 @@ export const COMMANDS = [
         name: 'tab_open',
         description: '打开或按 URL 规则复用 Tab，并等待新页面加载完成',
         aliases: ['tab_new', 'new_tab', 'tab_create', 'create_tab'],
+        aliasExamples: {
+            tab_activate: `tab_open --payload '{"url":"https://example.com","reuse":"require","active":true}'`,
+        },
         params: [
             { name: 'url', type: 'string', required: true, description: '要打开的 URL' },
             {
@@ -541,7 +545,7 @@ export const COMMANDS = [
             {
                 name: 'appProfile',
                 type: 'string',
-                description: '按已安装档案应用 App 环境；内置基础档案只提供 UA/版本，完整桥由能力包提供。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true',
+                description: '按已安装档案应用 App 环境，ID 与限制见当前动态帮助。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true',
             },
             {
                 name: 'os',
@@ -567,9 +571,9 @@ 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://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/app/home","appProfile":"reader"}'`,
+            `tab_open --payload '{"url":"https://example.com/app/home","appProfile":"reader","emulation":{"preset":"ipad-mini-a17-pro","orientation":"landscape","deviceShell":true,"splitScreen":true}}'`,
+            `tab_open --payload '{"url":"https://example.com","appProfile":"reader","os":"android"}'`,
             `tab_open --payload '{"url":"https://example.com","group":"验证任务"}'`,
         ],
     },
@@ -613,6 +617,9 @@ export const COMMANDS = [
     {
         name: 'page_click',
         description: '点击页面元素，支持 CSS/@ref、可见文本或视口坐标定位',
+        aliasExamples: {
+            page_select: `page_click --payload '{"tabId":12345,"text":"选项文案","role":"option"}'`,
+        },
         params: [
             {
                 name: 'selector',
@@ -666,7 +673,8 @@ export const COMMANDS = [
         result: PAGE_ACTION_RESULT,
         notes: [
             'selector / text / point 必须且只能提供一个。隐藏页 auto 使用 DOM；只有明确依赖真实用户手势时才激活页面。',
-            '原生 select 可按 option 文本点击；checkbox/radio 返回 controlState.checkedBefore/checkedAfter。',
+            'auto 对原生 option、checkbox/radio 使用状态感知的 DOM 路径；显式 mouse/touch 保留可信输入。',
+            '原生 select 可按 option 文本点击；auto/dom 返回 selectionState.valueBefore/valueAfter/selectedAfter，检查选中状态是否保持。checkbox/radio 返回 controlState.checkedBefore/checkedAfter。',
         ],
         examples: [
             `page_click --payload '{"tabId":12345,"text":"提交"}'`,
@@ -721,6 +729,9 @@ export const COMMANDS = [
     {
         name: 'page_type',
         description: '向输入框填写文本，兼容 React 受控组件',
+        aliasExamples: {
+            page_fill: `page_type --payload '{"tabId":12345,"selector":"@e6","text":"填写内容","clearFirst":true}'`,
+        },
         params: [
             {
                 name: 'selector',
@@ -906,6 +917,8 @@ export const COMMANDS = [
                 description: '按键名称：Enter/Tab/Escape/Backspace 等',
             },
             { name: 'modifiers', type: 'string[]', description: '修饰键数组：ctrl/alt/shift/meta/cmd' },
+            { name: 'dialogId', type: 'string', description: '原生弹窗回执或 page_snapshot 中的 dialog.id；仅配合 Enter 接受或 Escape 取消' },
+            { name: 'promptText', type: 'string', description: '仅用于 dialogId + Enter 接受原生 prompt 时填写文本' },
             {
                 name: 'pressMode',
                 type: '"auto" | "dom" | "keyboard"',
@@ -917,6 +930,7 @@ export const COMMANDS = [
         ],
         notes: [
             '隐藏页 DOM 模式支持 Tab 焦点移动、原生控件 Enter/Space 激活和输入框 Enter 提交；编辑、选择、方向键和页面滚动等原生行为需可见页与 pressMode=keyboard。',
+            '原生 alert/confirm/prompt/beforeunload 弹窗需显式传 dialogId；普通 Enter 不处理弹窗。弹窗处理绕过 DOM 观察，不自动重放被中断的动作；处理后重新读取页面。',
         ],
         result: [
             ...PAGE_ACTION_RESULT,
@@ -956,6 +970,7 @@ export const COMMANDS = [
         ],
         notes: [
             'time / selector / text / condition 必须且只能提供一个；time 范围 0–60000ms。页面交互已有内置观察，仅在需要独立等待条件时使用。',
+            '等待后须立即执行已知动作时，用 mearl run 在同一脚本中 await pageWait 后紧接 pageClick，避免模型往返。整体 --timeout 须覆盖等待及后续动作；等待失败不继续点击。',
         ],
         examples: [
             `page_wait --payload '{"tabId":12345,"time":1000}'`,
@@ -968,6 +983,9 @@ export const COMMANDS = [
     {
         name: 'page_navigate',
         description: '在当前标签页内导航到 URL、刷新页面，或沿浏览历史后退/前进',
+        aliasExamples: {
+            page_reload: `page_navigate --payload '{"tabId":12345,"refresh":true}'`,
+        },
         params: [
             {
                 name: 'url',
@@ -1167,14 +1185,14 @@ export const COMMANDS = [
     },
     {
         name: 'set_app_profile',
-        description: '设置已安装的 App 档案；完整 JSBridge 由能力包提供。可同时设置 MTop 页面接口环境，传 emulation 时联动设备模拟',
+        description: '设置已安装的 App 档案；完整 JSBridge 由能力包提供。可同时设置已安装的网络控件，传 emulation 时联动设备模拟',
         summary: '设置或清除目标标签页的 App 容器模拟',
         params: [
             { name: 'enabled', type: 'boolean', required: true, description: 'true=启用，false=清除' },
             {
                 name: 'profile',
                 type: 'string',
-                description: `容器档案名（enabled=true 时必填）；内置 ${APP_PROFILE_NAME_LIST}`,
+                description: '已安装的容器档案 ID（enabled=true 时必填）；当前动态帮助直接展示目标浏览器目录',
             },
             { name: 'os', type: '"ios" | "android"', description: '容器系统，默认 ios' },
             {
@@ -1199,9 +1217,9 @@ export const COMMANDS = [
                 description: '声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}；不执行配置脚本',
             },
             {
-                name: 'mtopEnv',
-                type: '"default" | "prod" | "pre"',
-                description: '可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。仅作用于目标 tab',
+                name: 'networkControl',
+                type: 'object | null',
+                description: '可选已安装网络控件 {id,value}；null 清除，省略时保持当前设置。仅作用于目标 tab',
             },
             {
                 name: 'emulation',
@@ -1217,15 +1235,15 @@ export const COMMANDS = [
             'bridgeConfig.methods 按方法声明 behavior / response / noop 三选一，可传 silent；只支持受控行为、固定 JSON 回包或成功空实现，不执行配置脚本。',
         ],
         result: [
-            '返回 enabled、profile、label、userAgent、os、mtopEnv、reloaded；联动设备时额外返回实际 emulation。',
+            '返回 enabled、profile、label、userAgent、os、networkControl、reloaded；联动设备时额外返回实际 emulation。',
         ],
         examples: [
-            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"fliggy"}'`,
-            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"fliggy","mtopEnv":"pre"}'`,
-            `set_app_profile --payload '{"tabId":12345,"enabled":false,"mtopEnv":"prod"}'`,
-            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"fliggy","emulation":{}}'`,
-            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"alipay","emulation":{"preset":"pixel-11","deviceShell":true}}'`,
-            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"fliggy","emulation":{"preset":"ipad-mini-a17-pro","orientation":"landscape","deviceShell":true,"splitScreen":true}}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"reader"}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"reader","networkControl":{"id":"environment","value":"pre"}}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":false,"networkControl":null}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"reader","emulation":{}}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"wallet","emulation":{"preset":"pixel-11","deviceShell":true}}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"reader","emulation":{"preset":"ipad-mini-a17-pro","orientation":"landscape","deviceShell":true,"splitScreen":true}}'`,
             `set_app_profile --payload '{"tabId":12345,"enabled":false}'`,
             `set_app_profile --payload '{"tabId":12345,"enabled":false,"emulation":{}}'`,
         ],
@@ -1280,9 +1298,9 @@ export const COMMANDS = [
         result: ['找到时 found=true 并返回 value/domain/path；不存在时 found=false。'],
         examples: [
             `get_cookie --payload '{"tabId":12345,"name":"feature_flag"}'`,
-            `get_cookie --payload '{"url":"https://www.taobao.com/","name":"tracknick"}'`,
+            `get_cookie --payload '{"url":"https://www.shop.com/","name":"account_name"}'`,
             `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":"/"}'`,
+            `get_cookie --payload '{"tabId":12345,"name":"account_name","url":"https://www.shop.com/","domain":"example.com","path":"/"}'`,
         ],
     },
     {
@@ -1327,7 +1345,7 @@ export const COMMANDS = [
         result: ['返回 url/name/domain/path/reloaded，指定标签页时包含 tabId；不回显 Cookie 值。'],
         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 '{"url":"https://www.shop.com/","name":"feature_flag","value":"enabled"}'`,
             `set_cookie --payload '{"tabId":12345,"name":"feature_channel","value":"3.6.63","domain":"example.com","reload":true}'`,
         ],
     },
@@ -1342,7 +1360,7 @@ export const COMMANDS = [
         examples: [`page_frames --payload '{"tabId":12345}'`],
     },
     {
-        name: 'request_domain_permission',
+        name: 'request_permission',
         description: '申请访问指定域名的权限（必要时弹窗让用户授权）',
         params: [
             {
@@ -1357,7 +1375,7 @@ export const COMMANDS = [
             '弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。',
         ],
         result: ['返回 granted、domain，授权成功时包含 origin。'],
-        examples: [`request_domain_permission --payload '{"domain":"example.com"}'`],
+        examples: [`request_permission --payload '{"domain":"example.com"}'`],
     },
     // ── 组合调用 ────────────────────────────────────────────────────────────────
     {

package/dist/index.d.ts

@@ -13,7 +13,7 @@ export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invok
 export type { UnifiedClientOptions, UnifiedInvokeOptions, UnifiedInvokeOptions as InvokeOptions, } from './unified.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';
+export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserJsonValue, BrowserLaunchParams, BrowserProviderOperation, BrowserListResult, BrowserListParams, 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, RequestPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestBinaryBody, SendRequestFormValue, SendProtocolRequestParams, 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 '@mearl/browser-core';
 export declare function tabCheckpoint(params: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;
@@ -25,8 +25,9 @@ export declare function getEvents(params: Protocol.GetEventsParams, options?: Un
 export declare function setMock(params: Protocol.SetMockParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'set_mock'>>;
 export declare function getMocks(params: Protocol.GetMocksParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'get_mocks'>>;
 export declare function sendRequest(params: Protocol.SendRequestParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'send_request'>>;
-export declare function sendMtopRequest(params: Protocol.SendMtopRequestParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'send_mtop_request'>>;
+export declare function sendProtocolRequest(params: Protocol.SendProtocolRequestParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'send_protocol_request'>>;
 export declare function browserList(options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_list'>>;
+export declare function browserList(params: Protocol.BrowserListParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_list'>>;
 export declare function selectBrowser(params?: Protocol.SelectBrowserParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_select_browser'>>;
 export declare function browserRelease(options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_release'>>;
 export declare function browserRelease(params: Protocol.BrowserReleaseParams, options: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'browser_release'>>;
@@ -37,6 +38,7 @@ export declare function getRules(options?: UnifiedInvokeOptions): Promise<Protoc
 export declare function pageScreenshot(params: Protocol.PageScreenshotParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_screenshot'>>;
 export declare function tabOpen(params: Protocol.TabOpenParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_open'>>;
 export declare function tabClose(params: Protocol.TabCloseParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_close'>>;
+export declare function getCapabilities(params?: Protocol.GetCapabilitiesParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'get_capabilities'>>;
 export declare function tabList(options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_list'>>;
 export declare function tabGroup(params: Protocol.TabGroupParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_group'>>;
 export declare function pageClick(params: Protocol.PageClickParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_click'>>;
@@ -69,3 +71,5 @@ export declare function saveArtifact(artifact: Protocol.BrowserArtifact & {
 export { PluginStateClient } from './plugins/clients/pluginState.js';
 export { PluginModelClient } from './plugins/clients/pluginModels.js';
 export type * from '@mearl/browser-core';
+export { getStructure as structure, type StructureOptions } from '@mearl/browser-core';
+export type { GetCapabilitiesParams, BrowserCapabilityCatalog, AppCapability, AppProfileUsage } from '@mearl/browser-core';

package/dist/index.js

@@ -36,11 +36,13 @@ export function getMocks(params, options) {
 export function sendRequest(params, options) {
     return invoke('send_request', params, options);
 }
-export function sendMtopRequest(params, options) {
-    return invoke('send_mtop_request', params, options);
+export function sendProtocolRequest(params, options) {
+    return invoke('send_protocol_request', params, options);
 }
-export function browserList(options) {
-    return invoke('browser_list', {}, options);
+export function browserList(paramsOrOptions = {}, options) {
+    return 'provider' in paramsOrOptions || 'launchForm' in paramsOrOptions
+        ? invoke('browser_list', paramsOrOptions, options)
+        : invoke('browser_list', {}, paramsOrOptions);
 }
 export function selectBrowser(params = {}, options) {
     return invoke('browser_select_browser', params, options);
@@ -71,6 +73,9 @@ export function tabOpen(params, options) {
 export function tabClose(params, options) {
     return invoke('tab_close', params, options);
 }
+export function getCapabilities(params = {}, options) {
+    return invoke('get_capabilities', params, options);
+}
 export function tabList(options) {
     return invoke('tab_list', {}, options);
 }
@@ -146,3 +151,4 @@ export async function saveArtifact(artifact, outputPath, options = {}) {
 }
 export { PluginStateClient } from './plugins/clients/pluginState.js';
 export { PluginModelClient } from './plugins/clients/pluginModels.js';
+export { getStructure as structure } from '@mearl/browser-core';

package/dist/nativeHost.js

@@ -96,7 +96,7 @@ export function inspectNativeHostInstallation(options = {}) {
                 details: [
                     ...details,
                     `Registration: ${manifestPath}`,
-                    'Run `mearl-native-host init` with a working Node.js, then reopen the extension. If the runtime package is missing, run `npx --@mearl:registry=https://registry.npmjs.org @mearl/setup update --local`.',
+                    'Run `mearl-native-host init` with a working Node.js, then reopen the extension. If the runtime package is missing, run `npx @mearl/setup update --local`.',
                 ],
             });
         }

package/dist/plugins/clients/pluginHostConnection.d.ts

@@ -16,6 +16,8 @@ export interface PluginHostClientOptions extends PluginHostConnectionOptions {
 }
 export interface HostStatus {
     protocolVersion: number;
+    version?: string;
+    buildId?: string;
     host: PluginExecutionHost;
     pid: number;
 }

package/dist/plugins/clients/pluginHostConnection.js

@@ -243,7 +243,9 @@ export class PluginHostConnection {
                     this.connection = undefined;
             });
         }
-        return (await this.connection).request(method, input, timeoutMs);
+        const connection = await this.connection;
+        // The handshake protocol defines compatibility; build identity is diagnostic metadata.
+        return connection.request(method, input, timeoutMs);
     }
     disconnect() {
         this.generation++;

package/dist/plugins/officialPluginInstaller.js

@@ -2,6 +2,7 @@ import { closeSync, mkdirSync, openSync, rmSync, statSync, writeFileSync } from
 import { CLIENT_VERSION } from '../runtimePaths.js';
 import { join } from 'node:path';
 import { spawn } from 'node:child_process';
+import { npmExecEnvironment } from '@mearl/daemon-core';
 import { findOfficialPlugin, readOfficialPluginCatalog } from './officialPluginCatalog.js';
 import { findPluginRegistration, pluginDirectory } from './pluginRegistry.js';
 const INSTALL_TIMEOUT_MS = 180_000;
@@ -60,7 +61,7 @@ function appendOutput(current, chunk) {
 function installWithSetup(name) {
     return new Promise((resolve, reject) => {
         const command = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-        const child = spawn(command, ['-y', '--@mearl:registry=https://registry.npmjs.org', `@mearl/setup@${CLIENT_VERSION}`, 'plugin', 'ensure', name], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+        const child = spawn(command, ['-y', '--@mearl:registry=https://registry.npmjs.org', `@mearl/setup@${CLIENT_VERSION}`, 'plugin', 'ensure', name], { env: npmExecEnvironment(), stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
         let stdout = '';
         let stderr = '';
         let settled = false;

package/dist/plugins/pluginRegistry.d.ts

@@ -1,7 +1,7 @@
 import { type AppProfileContribution } from '@mearl/browser-core';
 export declare class PluginError extends Error {
     readonly code: string;
-    constructor(code: string, message: string);
+    constructor(code: string, message: string, options?: ErrorOptions);
 }
 export interface PluginToolboxSandboxPage {
     type: 'sandbox';

package/dist/plugins/pluginRegistry.js

@@ -9,6 +9,7 @@ import { buildPluginPageBundle, PLUGIN_PAGE_CHUNK_BYTES, PLUGIN_PAGE_RUNTIME_HAS
 import { pluginFileVersion } from './pluginSource.js';
 const RESERVED_NAMES = new Set([
     'check',
+    'run',
     'help',
     'connector_list',
     'capture_checkpoint',
@@ -17,8 +18,8 @@ const RESERVED_NAMES = new Set([
 ]);
 export class PluginError extends Error {
     code;
-    constructor(code, message) {
-        super(`${code}: ${message}`);
+    constructor(code, message, options) {
+        super(`${code}: ${message}`, options);
         this.code = code;
     }
 }
@@ -405,8 +406,15 @@ export function findPluginRegistration(name) {
             ...(source ? { source } : {}),
         };
     }
-    catch {
-        throw new PluginError('PLUGIN_REGISTRY_INVALID', `无效的插件记录: ${file}`);
+    catch (cause) {
+        const reason = cause instanceof SyntaxError
+            ? 'JSON 格式错误'
+            : cause instanceof Error
+                ? cause.message
+                : '未知校验错误';
+        throw new PluginError('PLUGIN_REGISTRY_INVALID', `无效的插件记录: ${file} (${reason})`, {
+            cause,
+        });
     }
 }
 export function readPluginPageBundleChunk(name, hash, index) {

package/dist/plugins/runtime/pluginCommandWorker.js

@@ -31,7 +31,7 @@ async function run(message) {
                 : message.access === 'toolbox'
                     ? invokeRegisteredToolboxPlugin
                     : invokeRegisteredPlugin;
-        const declaration = message.describe
+        const declaration = message.describe || message.help
             ? await loadPlugin(message.entry, {
                 options: {},
                 progress: () => { },
@@ -63,11 +63,13 @@ async function run(message) {
         const value = migration
             ? await migration.runMigration(message.invocation)
             : declaration
-                ? {
-                    pageRuntime: declaration.pageRuntime,
-                    stateStorage: declaration.stateStorage,
-                    taskRecovery: declaration.taskRecovery,
-                }
+                ? message.help
+                    ? declaration.help(message.help.namespace, message.help.command)
+                    : {
+                        pageRuntime: declaration.pageRuntime,
+                        stateStorage: declaration.stateStorage,
+                        taskRecovery: declaration.taskRecovery,
+                    }
                 : message.model
                     ? await (await import('@mearl/agent-runtime/codex')).runCodexModel(message.model, {
                         signal: controller.signal,

package/dist/plugins/runtime/pluginExecutor.d.ts

@@ -6,6 +6,11 @@ export interface PluginExecutorDependencies {
     registration?: PluginRegistration;
 }
 export interface PluginExecutorOptions extends PluginInvokeOptions {
+    help?: {
+        namespace: string;
+        command?: string;
+    };
+    onOutput?: (stream: 'stdout' | 'stderr', chunk: Buffer) => void;
     describe?: boolean;
     model?: PluginModelRequest;
     recovery?: boolean;

package/dist/plugins/runtime/pluginExecutor.js

@@ -8,7 +8,7 @@ import { stopPluginProcessTree } from './pluginProcessTree.js';
 import { processIdentity } from '@mearl/daemon-core';
 /** Executes registered trusted code in a process whose lifetime belongs to this invocation. */
 export async function executeRegisteredPlugin(plugin, invocation, context, options = {}, dependencies = {}) {
-    const { signal, onProgress, source, access = 'public', executionTimeoutMs, cancellationGraceMs = 1000, workerPath, cwd, environment, describe, model, recovery, migration, expectedRecovery, onExecutorStarted, onExecutorStopped, onDiagnostic, ...invokeOptions } = options;
+    const { signal, onProgress, source, access = 'public', executionTimeoutMs, cancellationGraceMs = 1000, workerPath, cwd, environment, describe, help, onOutput, model, recovery, migration, expectedRecovery, onExecutorStarted, onExecutorStopped, onDiagnostic, ...invokeOptions } = options;
     for (const [name, value] of [
         ['executionTimeoutMs', executionTimeoutMs],
         ['cancellationGraceMs', cancellationGraceMs],
@@ -25,7 +25,7 @@ export async function executeRegisteredPlugin(plugin, invocation, context, optio
     const entryVersion = pluginFileVersion(registration.entry);
     return new Promise((resolve, reject) => {
         const child = fork(workerPath ?? PLUGIN_WORKER_PATH, [], {
-            stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+            stdio: ['ignore', onOutput ? 'pipe' : 'ignore', 'pipe', 'ipc'],
             serialization: 'advanced',
             execArgv: [],
             detached: process.platform !== 'win32',
@@ -46,6 +46,18 @@ export async function executeRegisteredPlugin(plugin, invocation, context, optio
         child.stderr?.on('data', chunk => {
             stderr = `${stderr}${chunk}`.slice(-65536);
         });
+        if (onOutput) {
+            for (const stream of ['stdout', 'stderr']) {
+                child[stream]?.on('data', chunk => {
+                    try {
+                        onOutput(stream, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                    }
+                    catch (error) {
+                        stop(error instanceof Error ? error : new Error(String(error)));
+                    }
+                });
+            }
+        }
         const send = (message) => {
             if (!child.connected || exited)
                 return;
@@ -209,6 +221,7 @@ export async function executeRegisteredPlugin(plugin, invocation, context, optio
                 entryVersion,
                 access,
                 describe,
+                help,
                 model,
                 recovery,
                 migration,

package/dist/plugins/runtime/pluginExecutorProtocol.d.ts

@@ -13,6 +13,10 @@ export type PluginWorkerRequest = {
     access: 'public' | 'toolbox' | 'runtime';
     registration?: PluginRegistration;
     describe?: boolean;
+    help?: {
+        namespace: string;
+        command?: string;
+    };
     model?: PluginModelRequest;
     recovery?: boolean;
     migration?: boolean;

package/dist/plugins/runtime/pluginExecutorSupervisor.js

@@ -3,13 +3,14 @@ import { fileURLToPath } from 'node:url';
 /** Ownership monitoring runs outside the event loop that executes plugin code. */
 export function supervisePluginExecutor(workerUrl) {
     const child = fork(fileURLToPath(workerUrl), ['--command'], {
-        stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+        stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
         serialization: 'advanced',
         execArgv: [],
     });
     let ending = false;
     let forwarded = Promise.resolve();
     child.stderr?.on('data', chunk => process.stderr.write(chunk));
+    child.stdout?.on('data', chunk => process.stdout.write(chunk));
     const terminate = () => {
         if (process.platform === 'win32') {
             try {