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

package/dist/commands.d.ts

@@ -23,6 +23,16 @@ export interface CommandDef {
     result?: readonly string[];
 }
 export declare const COMMANDS: readonly [{
+    readonly name: "get_capabilities";
+    readonly description: "只读查询当前目标浏览器的动作、设备和已安装 App 能力、限制与 Skill/帮助入口；不打开页面或启用模拟";
+    readonly params: [{
+        readonly name: "app";
+        readonly type: "string";
+        readonly description: "可选，使用目录中的完整 App ID 查询桥方法、可调设置和默认版本详情";
+    }];
+    readonly notes: readonly ["沿用 --browser / --session 路由；不传 app 返回摘要。apps.status=partial 表示目录未完整取得，unsupported 表示目标未提供目录；不能把两者当作未安装。", "available=false 的 App 当前不可启用；支持某个 action 不代表已有域名权限或真实设备授权。按需读取 usage.skills / usage.documentation，查询不会自动安装或加载 Skill。"];
+    readonly examples: ["get_capabilities", "get_capabilities --payload '{\"app\":\"example/app\"}'"];
+}, {
     readonly name: "browser_control";
     readonly description: "把控制会话交给用户；用户在 Mearl 浏览器管理页交还后重新观察页面";
     readonly params: [{
@@ -389,7 +399,7 @@ export declare const COMMANDS: readonly [{
         readonly type: "number";
         readonly description: "超时毫秒数，默认 10000";
     }];
-    readonly notes: readonly ["需要目标浏览器有对应登录态；Mearl 自动处理签名，不依赖页面脚本。api 以 mopen. 开头时使用 mopen 协议。", "env=prod 使用 h5api.m.taobao.com，pre 使用 h5api.wapa.taobao.com。"];
+    readonly notes: readonly ["需要目标浏览器有对应登录态；Mearl 自动处理签名，不依赖页面脚本。api 以 mopen. 开头时使用 mopen 协议。", "env=prod/pre 的网关由已安装的请求协议能力提供。"];
     readonly result: readonly ["返回 success、response、requestData；业务成功需检查 response.ret。"];
     readonly examples: ["send_mtop_request --payload '{\"api\":\"mtop.trade.order.detail\",\"data\":{\"orderId\":\"123\"}}'"];
 }, {
@@ -519,7 +529,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "appProfile";
         readonly type: "string";
-        readonly description: "按已安装档案应用 App 环境；内置基础档案只提供 UA/版本，完整桥由能力包提供。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true";
+        readonly description: "按已安装档案应用 App 环境，ID 与限制通过 get_capabilities 查询。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true";
     }, {
         readonly name: "os";
         readonly type: "\"ios\" | \"android\"";
@@ -531,7 +541,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://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 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\":\"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\":\"验证任务\"}'"];
 }, {
     readonly name: "tab_close";
     readonly description: "关闭指定标签页";
@@ -613,7 +623,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 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "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 与可用观察或最小快照核验，避免重复提交。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 独立。"];
     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 +653,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 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "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 与可用观察或最小快照核验，避免重复提交。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 独立。"];
     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 +679,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 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "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 与可用观察或最小快照核验，避免重复提交。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 独立。"];
     readonly examples: ["page_type --payload '{\"tabId\":12345,\"selector\":\"@e6\",\"text\":\"搜索关键词\"}'"];
 }, {
     readonly name: "page_hover";
@@ -685,7 +695,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 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "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 与可用观察或最小快照核验，避免重复提交。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 独立。"];
     readonly examples: ["page_hover --payload '{\"tabId\":12345,\"selector\":\".nav-menu\"}'"];
 }, {
     readonly name: "page_scroll";
@@ -713,7 +723,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 为空不表示失败。", "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 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 与可用观察或最小快照核验，避免重复提交。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 独立。", "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 +831,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 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "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 与可用观察或最小快照核验，避免重复提交。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 独立。", "action.data.dispatchMode / fallbackReason / defaultAction 说明实际输入路径。"];
     readonly examples: ["page_press --payload '{\"tabId\":12345,\"key\":\"Enter\"}'"];
 }, {
     readonly name: "page_wait";
@@ -911,7 +921,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 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "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 与可用观察或最小快照核验，避免重复提交。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 独立。"];
     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\"]}'"];
 }, {
@@ -1065,7 +1075,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "profile";
         readonly type: "string";
-        readonly description: `\u5BB9\u5668\u6863\u6848\u540D\uFF08enabled=true \u65F6\u5FC5\u586B\uFF09\uFF1B\u5185\u7F6E ${string}`;
+        readonly description: "已安装的容器档案 ID（enabled=true 时必填）；通过 get_capabilities 查询当前浏览器目录";
     }, {
         readonly name: "os";
         readonly type: "\"ios\" | \"android\"";
@@ -1110,7 +1120,7 @@ export declare const COMMANDS: readonly [{
     }];
     readonly notes: readonly ["只有用户明确要求 App/客户端/容器/JSBridge 模拟时启用。移动视口或普通 H5 调试使用 set_device_emulation。", "emulation={} 使用档案推荐设备；enabled=false 时省略 emulation 只清除 App 注入，传 {} 同时清除设备模拟。", "bridgeConfig.methods 按方法声明 behavior / response / noop 三选一，可传 silent；只支持受控行为、固定 JSON 回包或成功空实现，不执行配置脚本。"];
     readonly result: readonly ["返回 enabled、profile、label、userAgent、os、mtopEnv、reloaded；联动设备时额外返回实际 emulation。"];
-    readonly 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\":false}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":false,\"emulation\":{}}'"];
+    readonly examples: ["set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"reader\"}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":true,\"profile\":\"reader\",\"mtopEnv\":\"pre\"}'", "set_app_profile --payload '{\"tabId\":12345,\"enabled\":false,\"mtopEnv\":\"prod\"}'", "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\":{}}'"];
 }, {
     readonly name: "set_timezone";
     readonly description: "覆盖目标 tab 的时区，传空字符串恢复浏览器默认时区";
@@ -1153,7 +1163,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\":\"feature_channel\",\"domain\":\"example.com\"}'", "get_cookie --payload '{\"tabId\":12345,\"name\":\"tracknick\",\"url\":\"https://www.taobao.com/\",\"domain\":\"example.com\",\"path\":\"/\"}'"];
+    readonly examples: ["get_cookie --payload '{\"tabId\":12345,\"name\":\"feature_flag\"}'", "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\":\"account_name\",\"url\":\"https://www.shop.com/\",\"domain\":\"example.com\",\"path\":\"/\"}'"];
 }, {
     readonly name: "set_cookie";
     readonly description: "在目标浏览器设置一个指定非分区 session Cookie，可选刷新指定页面";
@@ -1190,7 +1200,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\":\"feature_channel\",\"value\":\"3.6.63\",\"domain\":\"example.com\",\"reload\":true}'"];
+    readonly examples: ["set_cookie --payload '{\"tabId\":12345,\"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}'"];
 }, {
     readonly name: "page_frames";
     readonly description: "获取页面主 frame 与所有 iframe 列表";

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 浏览器管理页交还后重新观察页面',
@@ -377,7 +382,7 @@ export const COMMANDS = [
         ],
         notes: [
             '需要目标浏览器有对应登录态；Mearl 自动处理签名，不依赖页面脚本。api 以 mopen. 开头时使用 mopen 协议。',
-            'env=prod 使用 h5api.m.taobao.com，pre 使用 h5api.wapa.taobao.com。',
+            'env=prod/pre 的网关由已安装的请求协议能力提供。',
         ],
         result: ['返回 success、response、requestData；业务成功需检查 response.ret。'],
         examples: [
@@ -541,7 +546,7 @@ export const COMMANDS = [
             {
                 name: 'appProfile',
                 type: 'string',
-                description: '按已安装档案应用 App 环境；内置基础档案只提供 UA/版本，完整桥由能力包提供。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true',
+                description: '按已安装档案应用 App 环境，ID 与限制通过 get_capabilities 查询。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true',
             },
             {
                 name: 'os',
@@ -567,9 +572,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":"验证任务"}'`,
         ],
     },
@@ -1174,7 +1179,7 @@ export const COMMANDS = [
             {
                 name: 'profile',
                 type: 'string',
-                description: `容器档案名（enabled=true 时必填）；内置 ${APP_PROFILE_NAME_LIST}`,
+                description: '已安装的容器档案 ID（enabled=true 时必填）；通过 get_capabilities 查询当前浏览器目录',
             },
             { name: 'os', type: '"ios" | "android"', description: '容器系统，默认 ios' },
             {
@@ -1220,12 +1225,12 @@ export const COMMANDS = [
             '返回 enabled、profile、label、userAgent、os、mtopEnv、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":true,"profile":"reader"}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"reader","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","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 +1285,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 +1332,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}'`,
         ],
     },

package/dist/index.d.ts

@@ -37,6 +37,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 +70,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

@@ -71,6 +71,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 +149,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/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 {

package/dist/plugins/runtime/pluginHostServer.js

@@ -1,3 +1,4 @@
+import { CLIENT_VERSION } from '../../runtimePaths.js';
 import { randomUUID } from 'node:crypto';
 import { createServer } from 'node:net';
 import { chmodSync, rmSync } from 'node:fs';
@@ -17,6 +18,7 @@ export async function startPluginHostServer(configuration = {}) {
     const owner = {
         pid: process.pid,
         protocolVersion: PLUGIN_TASK_PROTOCOL_VERSION,
+        version: CLIENT_VERSION,
         processIdentity: processIdentity(process.pid),
     };
     if (!claimRecord(paths.lease, owner))
@@ -103,6 +105,7 @@ export async function startPluginHostServer(configuration = {}) {
                 };
                 return {
                     protocolVersion: PLUGIN_TASK_PROTOCOL_VERSION,
+                    version: CLIENT_VERSION,
                     host: manager.host,
                     pid: process.pid,
                 };
@@ -112,6 +115,7 @@ export async function startPluginHostServer(configuration = {}) {
             if (method === 'status')
                 return {
                     protocolVersion: PLUGIN_TASK_PROTOCOL_VERSION,
+                    version: CLIENT_VERSION,
                     host: manager.host,
                     pid: process.pid,
                 };

package/dist/plugins/runtime/pluginPageManager.js

@@ -5,7 +5,6 @@ import { readFileSync, statSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 import { capturePluginRevision } from './pluginRevision.js';
 import { findPluginRegistration } from '../sdk/plugin.js';
-import { compilePluginPageSchema } from '../sdk/pluginPageDefinition.js';
 import { UnifiedClient, decodeBrowserTarget } from '../../unified.js';
 import { pluginHostPaths } from './pluginHostPaths.js';
 import { serializePluginExecutionError, pluginExecutionError } from './pluginExecutorProtocol.js';
@@ -726,9 +725,6 @@ export class PluginPageManager {
         const binding = record.runtime.events?.[name];
         if (!binding || Buffer.byteLength(JSON.stringify(input.payload ?? null)) > 32 * 1024)
             throw new Error('Page event is not declared or exceeds 32 KiB');
-        const validate = compilePluginPageSchema(binding.schema);
-        if (!validate(input.payload))
-            throw failure('PLUGIN_PAGE_EVENT_INVALID', 'Page event payload does not match its schema');
         const waiting = record.deliveries.filter(item => item.name === name && item.state === 'queued');
         if (binding.policy === 'latest') {
             for (const previous of waiting) {