@mearl/client 2.19.2 → 2.19.3

package/dist/commands.js

@@ -6,12 +6,35 @@ const PAGE_DIAGNOSTICS_PARAM = {
     name: 'diagnostics',
     type: 'object | boolean',
     description: '默认关闭；传 true 返回动作期间新增的 error logs/业务 requests，或传对象自定义通道与过滤',
+    details: [
+        'logs: boolean | { level, limit, filter }；true 默认采集 error 日志',
+        'requests: boolean | { count, filter, source, includeBody, includeHeaders, maxBodySize, fields, keysOnly }',
+        'events: boolean | { source, event_type, filter, limit, includeRaw }；埋点需显式开启',
+        '各通道过滤字段同 get_logs / get_requests / get_events；observe=false 时仍返回诊断增量，但不等待 DOM/导航稳定',
+    ],
 };
 const PAGE_OBSERVE_PARAM = {
     name: 'observe',
     type: 'object | false',
     description: '默认开启 DOM/导航观察；传 false 关闭，不影响显式请求的 diagnostics',
+    details: [
+        'quietMs: number，DOM 变化后的稳定窗口，默认 100ms',
+        'firstChangeTimeoutMs: number，无 DOM 变化时的观察窗口，默认 500ms',
+        'timeoutMs: number，DOM 观察阶段最大时间，默认 3000ms',
+        'navigationGraceMs: number，低信息量点击/按键的导航宽限，默认 1000ms；相关网络活动可延长宽限',
+        'navigationTimeoutMs: number，导航就绪最大等待时间，默认 15000ms',
+        'networkIdleMs: number，文档完成且相关请求归零后的静默时间，默认 500ms',
+        'contentReadyAfterMs: number，结构稳定兜底保护期，默认 min(5000, navigationTimeoutMs / 2)，并限制在导航超时前',
+    ],
 };
+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 结束。',
+    'observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。',
+    'fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。',
+    '显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。',
+];
 export const COMMANDS = [
     // ── API 调试 ──────────────────────────────────────────────────────────────
     {
@@ -56,6 +79,13 @@ export const COMMANDS = [
             { name: 'fields', type: 'string[]', description: '从响应体提取指定字段路径，最多 100 个' },
             { name: 'keysOnly', type: 'boolean', description: '只返回数据结构，不返回叶子值' },
         ],
+        notes: [
+            '流式请求开始后即进入缓冲区；页面及 App 桥代发的 MTop SSE 都归入 mtop。无法归属当前页面 target 的 Service Worker 请求不在采集范围内。',
+        ],
+        result: [
+            'nextCursor 用于同类查询续读，hasMore 表示还有数据，gap 表示缓冲区淘汰造成缺口；checkpoint cursor 可分别用于三类查询的初始边界。',
+            'isPending 标记未完成请求；SSE 的 responseBody 保存按序到达的 event/data/timestamp/duration 分片。敏感请求头返回脱敏值。',
+        ],
         examples: [
             `get_requests --payload '{"tabId":12345,"count":5}'`,
             `get_requests --payload '{"tabId":12345,"source":"mtop","filter":"cart"}'`,
@@ -81,6 +111,9 @@ export const COMMANDS = [
                 description: '只返回指定 tab checkpoint 或同类查询 cursor 之后的日志',
             },
         ],
+        result: [
+            'nextCursor 用于同类查询续读，hasMore 表示还有数据，gap 表示缓冲区淘汰造成缺口；checkpoint cursor 可分别用于三类查询的初始边界。',
+        ],
         examples: [`get_logs --payload '{"tabId":12345,"limit":10,"level":"error"}'`],
     },
     {
@@ -109,6 +142,13 @@ export const COMMANDS = [
                 description: '返回完整 URL、_raw 和 _context；默认 false',
             },
         ],
+        notes: [
+            'tab_open 新页从首屏采集；既有页面首次查询才启用采集，需要刷新或重新触发埋点。同批事件不会被 limit 拆开。',
+        ],
+        result: [
+            'nextCursor 用于同类查询续读，hasMore 表示还有数据，gap 表示缓冲区淘汰造成缺口；checkpoint cursor 可分别用于三类查询的初始边界。',
+            'captureStatus 为 armed/active/inactive；空结果附 hint 时按提示刷新或触发。默认去除 tracking URL query 与 _raw/_context，includeRaw=true 时保留。',
+        ],
         examples: [
             `get_events --payload '{"tabId":12345,"source":"aplus","event_type":"CLK","limit":10}'`,
             `get_events --payload '{"tabId":12345,"filter":"order","includeRaw":true,"limit":1}'`,
@@ -149,6 +189,11 @@ export const COMMANDS = [
                 description: '请求 query/body 字段子集匹配；$index 从 0 开始指定调用顺序',
             },
         ],
+        notes: [
+            '启用时至少提供 mockData 或非空 fields；非空 fields 优先。fields 每项 { path: string, value: any }，path 支持点号和数组索引。',
+            '相同 apiName 的多条无条件 Mock 会覆盖；conditions 子集匹配 query/body（含 data 内层），不同条件可共存；$index 从 0 起控制调用顺序，不参与字段匹配。',
+            '大字段可用顶层 @<绝对路径> 文件引用或 --payload-file；文件展开后仍受 Native Messaging 单条消息大小限制。',
+        ],
         examples: [
             `set_mock --payload '{"tabId":12345,"apiName":"mtop.cart.query","mockData":{"ret":["SUCCESS::调用成功"]}}'`,
             `set_mock --payload-file ./mock-data.json`,
@@ -185,17 +230,26 @@ export const COMMANDS = [
                 name: 'requestHeaders',
                 type: 'array',
                 description: 'modifyHeaders 动作的请求头修改列表',
+                details: [
+                    '每项 { header: string, operation: "set" | "append" | "remove", value?: string }；set/append 需 value',
+                ],
             },
             {
                 name: 'responseHeaders',
                 type: 'array',
                 description: 'modifyHeaders 动作的响应头修改列表',
+                details: [
+                    '每项 { header: string, operation: "set" | "append" | "remove", value?: string }；set/append 需 value',
+                ],
             },
             { name: 'initiatorDomains', type: 'string', description: '发起方域名过滤' },
             { name: 'resourceTypes', type: 'string[]', description: '资源类型过滤' },
             { name: 'priority', type: 'number', description: '规则优先级' },
             { name: 'description', type: 'string', description: '规则说明' },
         ],
+        notes: [
+            '扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。',
+        ],
         examples: [
             `set_rule --payload '{"actionType":"block","filter":"^https://example\\\\.com/ads/.*"}'`,
             `set_rule --payload '{"ruleId":42,"enabled":false}'`,
@@ -225,6 +279,11 @@ export const COMMANDS = [
                 name: 'files',
                 type: 'SendRequestFile[]',
                 description: 'multipart 文件，最多 20 个、总计不超过 40 MiB；Base64 文件总计不超过 7 MiB。每项传 fieldName 和绝对 filePath，或传 base64 + filename',
+                details: [
+                    'fieldName: string（必填）；filePath: string 与 base64: string 二选一',
+                    'filename: string，base64 时必填，filePath 时默认文件 basename',
+                    'contentType: string（可选），默认按文件名推断 MIME，否则 application/octet-stream',
+                ],
             },
             { name: 'withCookies', type: 'boolean', description: '是否附加浏览器 Cookie，默认 true' },
             {
@@ -234,6 +293,14 @@ export const COMMANDS = [
             },
             { name: 'timeout', type: 'number', description: '超时毫秒数，默认 30000' },
         ],
+        notes: [
+            '仅用于非 BUC 请求；BUC 接口使用 mearl buc，不手工传 Token、DPoP 或 Ticket。',
+            'body 不能与 formData/files 组合；multipart 不手工设置 Content-Type，由 Mearl 生成 boundary。',
+            'filePath 属于 native-host 所在机器；无法引用远端路径时用 base64。BUC 上传的路径属于插件执行宿主。',
+        ],
+        result: [
+            '返回 status、statusText、headers、body、bodyType、attachedCookieCount；bodyType 为 json/text/base64，二进制 body 需解码后保存。',
+        ],
         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"}]}'`,
@@ -251,6 +318,11 @@ export const COMMANDS = [
             { name: 'env', type: '"prod" | "pre"', description: '请求环境，默认 prod' },
             { name: 'timeout', type: 'number', description: '超时毫秒数，默认 10000' },
         ],
+        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"}}'`,
         ],
@@ -400,6 +472,15 @@ export const COMMANDS = [
                 description: '与 appProfile 配合；声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}',
             },
         ],
+        notes: [
+            'emulation / appProfile 只应用到新建 Tab；复用 Tab 要切换状态时用对应设置 action。',
+            'closeExisting 不能与复用或 openerTabId 组合；多匹配默认报错，match.onMultiple=first 可显式选择第一个。',
+        ],
+        result: [
+            '返回 tabId、url、title、opened/reused；reused=true 的既有页面应保留。',
+            'active=true 时 activation 包含 tabActive、windowFocused、windowState、visibilityState；emulation 返回实际生效配置。',
+            'capture.cursor 是导航前诊断边界，可分别用于 get_logs/get_requests/get_events 的 after。',
+        ],
         examples: [
             `tab_open --payload '{"url":"https://example.com"}'`,
             `tab_open --payload '{"url":"https://example.com/page","reuse":"prefer","match":{"ignoreSearch":true}}'`,
@@ -500,6 +581,11 @@ export const COMMANDS = [
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
+        result: PAGE_ACTION_RESULT,
+        notes: [
+            'selector / text / point 必须且只能提供一个。隐藏页 auto 使用 DOM；只有明确依赖真实用户手势时才激活页面。',
+            '原生 select 可按 option 文本点击；checkbox/radio 返回 controlState.checkedBefore/checkedAfter。',
+        ],
         examples: [
             `page_click --payload '{"tabId":12345,"text":"提交"}'`,
             `page_click --payload '{"tabId":12345,"text":"退款明细","role":"button"}'`,
@@ -541,6 +627,10 @@ export const COMMANDS = [
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
+        result: PAGE_ACTION_RESULT,
+        notes: [
+            '起点会自动滚入视口，终点必须同时位于当前视口；否则先滚动页面。隐藏页 auto 使用 DOM，不切换活动页。',
+        ],
         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"}'`,
@@ -562,6 +652,7 @@ export const COMMANDS = [
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
+        result: PAGE_ACTION_RESULT,
         examples: [`page_type --payload '{"tabId":12345,"selector":"@e6","text":"搜索关键词"}'`],
     },
     {
@@ -578,6 +669,7 @@ export const COMMANDS = [
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
+        result: PAGE_ACTION_RESULT,
         examples: [`page_hover --payload '{"tabId":12345,"selector":".nav-menu"}'`],
     },
     {
@@ -605,6 +697,10 @@ export const COMMANDS = [
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
+        result: [
+            ...PAGE_ACTION_RESULT,
+            'action.data 返回 moved、atTop/atBottom、scrollYBefore/After、maxScrollY、resolvedContainer 和 ancestorDistance；自动发现的内部容器提供可复用 containerSelector。',
+        ],
         examples: [
             `page_scroll --payload '{"tabId":12345,"direction":"down"}'`,
             `page_scroll --payload '{"tabId":12345,"direction":"bottom"}'`,
@@ -623,13 +719,22 @@ export const COMMANDS = [
                 description: '表达式返回 Promise 时等待完成，默认 true',
             },
             {
-                name: 'observe',
+                name: 'frameId',
+                type: 'string',
+                description: 'page_frames 返回的目标 frame ID，扩展/CDP 均支持；省略时容器/设备外壳使用当前业务 frame，普通页面使用主 frame',
+            },
+            {
+                ...PAGE_OBSERVE_PARAM,
                 type: 'object',
                 description: '仅在表达式会修改页面且需要观察结果时显式传入；不传保持轻量裸执行',
             },
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
+        notes: ['优先使用结构化 action；仅在其无法表达需求时执行最小范围脚本。'],
+        result: [
+            '默认返回 { result }；observe 对象启用观察并返回 { action, observation }；仅开启 diagnostics 时返回 { action, diagnostics }。diagnostics=false 不启用包装。失败阶段语义同 page_click。',
+        ],
         examples: [`page_eval --payload '{"tabId":12345,"expression":"document.title"}'`],
     },
     {
@@ -663,6 +768,10 @@ export const COMMANDS = [
             },
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
+        result: [
+            'matches[] 包含 boundingBox、computedStyle、hitTest、scroll 溢出量及可用的 scrollContainer。receivesPointerEvents=false 时读取 occludedBy。',
+            '$0 还返回 resolvedSelector、属性、XPath 和可用框架信息。',
+        ],
         examples: [
             `page_inspect --payload '{"tabId":12345,"selector":".form-field","styles":["display","width"]}'`,
             `page_inspect --payload '{"tabId":12345,"selector":"@e8"}'`,
@@ -691,6 +800,13 @@ export const COMMANDS = [
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
+        notes: [
+            '隐藏页 DOM 模式支持 Tab 焦点移动、原生控件 Enter/Space 激活和输入框 Enter 提交；编辑、选择、方向键和页面滚动等原生行为需可见页与 pressMode=keyboard。',
+        ],
+        result: [
+            ...PAGE_ACTION_RESULT,
+            'action.data.dispatchMode / fallbackReason / defaultAction 说明实际输入路径。',
+        ],
         examples: [`page_press --payload '{"tabId":12345,"key":"Enter"}'`],
     },
     {
@@ -723,6 +839,9 @@ export const COMMANDS = [
             { name: 'interval', type: 'number', description: '轮询间隔毫秒数，默认 200' },
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
+        notes: [
+            'time / selector / text / condition 必须且只能提供一个；time 范围 0–60000ms。页面交互已有内置观察，仅在需要独立等待条件时使用。',
+        ],
         examples: [
             `page_wait --payload '{"tabId":12345,"time":1000}'`,
             `page_wait --payload '{"tabId":12345,"selector":".dialog","state":"visible"}'`,
@@ -752,6 +871,7 @@ export const COMMANDS = [
             },
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
+        notes: ['url / refresh=true / history 必须且只能提供一个。'],
         examples: [
             `page_navigate --payload '{"tabId":12345,"url":"https://example.com/page2"}'`,
             `page_navigate --payload '{"tabId":12345,"refresh":true}'`,
@@ -773,6 +893,10 @@ export const COMMANDS = [
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
+        result: PAGE_ACTION_RESULT,
+        notes: [
+            '直接写入 input[type=file]，不依赖 file chooser；隐藏的文件节点也可上传。外部 Provider 的文件中转能力查询 mearl <providerId>。',
+        ],
         examples: [
             `page_upload --payload '{"tabId":12345,"selector":"#file-input","filePaths":["/Users/me/photo.jpg"]}'`,
         ],
@@ -816,6 +940,14 @@ export const COMMANDS = [
             },
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
+        notes: [
+            'query.text / query.role 至少提供一个；query.exact 默认 true。每次快照刷新有效 ref 集合。',
+            'interactive 无 AX 控件时回退到 viewport，不会自动改用 dom；Canvas 内容需截图。',
+        ],
+        result: [
+            '返回 snapshot、elementCount、outputNodeCount、mode；截断时 truncated=true。',
+            'query 返回 matches 与完整 matchCount，matches 最多 100 项，裁剪时 matchesTruncated=true。容器/iframe 的视口裁剪返回 outerViewport、contentViewport 和滚动位置。',
+        ],
         examples: [
             `page_snapshot --payload '{"tabId":12345}'`,
             `page_snapshot --payload '{"tabId":1,"mode":"viewport"}'`,
@@ -835,6 +967,12 @@ export const COMMANDS = [
             { name: 'quality', type: 'number', description: 'JPEG 压缩质量（0-100），默认 80' },
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
+        notes: [
+            '使用 --output <path> 保存图片；省略时 stdout 返回含 base64 data 的 JSON，避免直接将其加载为文本。',
+        ],
+        result: [
+            'meta 包含 format、width、height、size、url、title；宽高为物理像素（CSS 尺寸 × DPR）。',
+        ],
         examples: [
             `page_screenshot --payload '{"tabId":12345}' --output ./screenshot.png`,
             `page_screenshot --payload '{"tabId":12345,"selector":".product-card"}' --output ./card.png`,
@@ -885,6 +1023,13 @@ export const COMMANDS = [
             { name: 'reload', type: 'boolean', description: '启用后是否重载页面，默认 true' },
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
+        notes: [
+            '无 preset 时 width/height 必须成对提供且 userAgent 必填；mobile 默认 true，touch 跟随 mobile。',
+            'deviceShell 开启/移除时必须重载；splitScreen 仅在已启用 App 档案、deviceShell=true、横屏时生效。',
+        ],
+        result: [
+            '返回实际 viewport（width/height/deviceScaleFactor/scale）、UA、mobile、touch、orientation、deviceShell、splitScreen 和 reloaded；应以响应确认生效状态。',
+        ],
         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"}'`,
@@ -928,6 +1073,14 @@ export const COMMANDS = [
             { name: 'reload', type: 'boolean', description: '应用/清除后是否重载页面，默认 true' },
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
+        notes: [
+            '只有用户明确要求 App/客户端/容器/JSBridge 模拟时启用。移动视口或普通 H5 调试使用 set_device_emulation。',
+            'emulation={} 使用档案推荐设备；enabled=false 时省略 emulation 只清除 App 注入，传 {} 同时清除设备模拟。',
+            'bridgeConfig.methods 按方法声明 behavior / response / noop 三选一，可传 silent；只支持受控行为、固定 JSON 回包或成功空实现，不执行配置脚本。',
+        ],
+        result: [
+            '返回 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"}'`,
@@ -960,7 +1113,11 @@ export const COMMANDS = [
         name: 'get_cookie',
         description: '从目标浏览器读取一个指定非分区 Cookie；拒绝返回 HttpOnly Cookie',
         params: [
-            { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
+            {
+                name: 'tabId',
+                type: 'number',
+                description: '可选；指定标签页的 Cookie 存储区，省略时使用浏览器默认存储区',
+            },
             {
                 name: 'name',
                 type: 'string',
@@ -970,7 +1127,7 @@ export const COMMANDS = [
             {
                 name: 'url',
                 type: 'string',
-                description: '可选 Cookie 查询 URL；省略时使用当前标签页 URL',
+                description: 'Cookie 查询 URL；未传 tabId 时必填，省略时使用指定标签页 URL',
             },
             {
                 name: 'domain',
@@ -979,17 +1136,31 @@ export const COMMANDS = [
             },
             { name: 'path', type: 'string', description: '可选精确 path 过滤' },
         ],
+        notes: [
+            '只读取指定非分区 Cookie，不列举全部、不回退分区 Cookie，拒绝 HttpOnly；禁止读取认证 Token。指定 url 不导航，指定 tabId 仅选择存储区时不启动采集。',
+        ],
+        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 '{"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":"/"}'`,
         ],
     },
     {
         name: 'set_cookie',
-        description: '设置当前标签页域下的一个指定非分区 session Cookie，可选刷新页面',
+        description: '在目标浏览器设置一个指定非分区 session Cookie，可选刷新指定页面',
         params: [
-            { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
+            {
+                name: 'tabId',
+                type: 'number',
+                description: '可选；指定标签页的 Cookie 存储区，reload=true 时必填',
+            },
+            {
+                name: 'url',
+                type: 'string',
+                description: 'Cookie 目标 URL；未传 tabId 时必填，省略时使用指定标签页 URL',
+            },
             {
                 name: 'name',
                 type: 'string',
@@ -1005,13 +1176,20 @@ export const COMMANDS = [
             {
                 name: 'domain',
                 type: 'string',
-                description: 'Cookie 域，默认当前 host；只允许当前 host 或其父域',
+                description: 'Cookie 域，默认目标 URL 的 host；只允许目标 host 或其父域',
             },
             { name: 'path', type: 'string', description: 'Cookie path，默认 /' },
-            { name: 'reload', type: 'boolean', description: '设置后是否刷新页面，默认 false' },
+            {
+                name: 'reload',
+                type: 'boolean',
+                description: '设置后是否刷新指定 tabId，默认 false；true 时必须传 tabId',
+            },
         ],
+        notes: ['仅写非分区 session Cookie，不支持删除。reload=true 时校验目标域与刷新页域的授权。'],
+        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 '{"tabId":12345,"name":"edith_switch_br.rx-vehicle-search_home","value":"3.6.63","domain":"taobao.com","reload":true}'`,
         ],
     },
@@ -1020,6 +1198,9 @@ export const COMMANDS = [
         name: 'page_frames',
         description: '获取页面主 frame 与所有 iframe 列表',
         params: [{ name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' }],
+        result: [
+            'frames[] 包含 frameId、url、name 和 isMainFrame；frameId 可用于 page_eval 等支持 frame 定位的 action。',
+        ],
         examples: [`page_frames --payload '{"tabId":12345}'`],
     },
     {
@@ -1033,6 +1214,11 @@ export const COMMANDS = [
                 description: '需要授权的域名，如 example.com',
             },
         ],
+        notes: [
+            'domain 使用纯主机名，不传 URL。仅在非 BUC send_request 报域权限缺失时申请，BUC 不使用浏览器域权限。',
+            '弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。',
+        ],
+        result: ['返回 granted、domain，授权成功时包含 origin。'],
         examples: [`request_domain_permission --payload '{"domain":"example.com"}'`],
     },
     // ── 组合调用 ────────────────────────────────────────────────────────────────
@@ -1054,8 +1240,12 @@ export const COMMANDS = [
                 description: '所有步骤共享的 tabId，步骤自身指定的优先',
             },
         ],
+        notes: ['最多 50 步，不允许嵌套 run_actions；需要根据每步效果决策时逐步调用普通 action。'],
+        result: [
+            '返回 results、completedSteps、totalSteps；失败时包含 error/failedStep，后续步骤未执行。',
+        ],
         examples: [
-            `run_actions --payload '{"tabId":12345,"actions":[{"action":"page_scroll","data":{"direction":"down"}},{"action":"page_wait","data":{"time":500}},{"action":"page_screenshot"}]}'`,
+            `run_actions --payload '{"tabId":12345,"actions":[{"action":"page_hover","data":{"selector":"#menu"}},{"action":"page_click","data":{"selector":"#menu-item"}}]}'`,
         ],
     },
 ];

package/dist/generated-browser-action-protocol.d.ts

@@ -616,9 +616,10 @@ export interface SetTimezoneResult {
     timezone: string | null;
 }
 export interface GetCookieParams {
-    tabId: number;
+    /** Select the tab's cookie store; omitted for the browser's default store. */
+    tabId?: number;
     name: string;
-    /** Cookie lookup URL; defaults to the current tab URL. */
+    /** Cookie lookup URL; required without tabId, otherwise defaults to the tab URL. */
     url?: string;
     domain?: string;
     path?: string;
@@ -633,9 +634,12 @@ export interface GetCookieResult {
     path?: string;
 }
 export interface SetCookieParams {
-    tabId: number;
+    /** Select the tab's cookie store; required when reload is true. */
+    tabId?: number;
     name: string;
     value: string;
+    /** Cookie target URL; required when tabId is omitted. */
+    url?: string;
     domain?: string;
     path?: string;
     reload?: boolean;
@@ -832,7 +836,7 @@ export type BrowserActionRequest<A extends BrowserAction> = BrowserActionMap[A][
 export type BrowserActionResponse<A extends BrowserAction> = BrowserActionMap[A]['response'];
 export type BrowserCommandAction = Exclude<BrowserAction, 'browser_select_browser'>;
 export type ExtensionBrowserAction = Exclude<BrowserCommandAction, 'browser_list' | 'browser_launch' | 'browser_close'>;
-export declare const TAB_ID_REQUIRED_ACTIONS: readonly ["tab_checkpoint", "capture_checkpoint", "get_requests", "get_logs", "get_events", "set_mock", "get_mocks", "page_screenshot", "tab_close", "page_click", "page_drag", "page_type", "page_scroll", "page_hover", "page_eval", "page_inspect", "page_snapshot", "page_press", "page_wait", "page_navigate", "page_upload", "page_frames", "set_device_emulation", "set_app_profile", "set_timezone", "get_cookie", "set_cookie", "run_actions"];
+export declare const TAB_ID_REQUIRED_ACTIONS: readonly ["tab_checkpoint", "capture_checkpoint", "get_requests", "get_logs", "get_events", "set_mock", "get_mocks", "page_screenshot", "tab_close", "page_click", "page_drag", "page_type", "page_scroll", "page_hover", "page_eval", "page_inspect", "page_snapshot", "page_press", "page_wait", "page_navigate", "page_upload", "page_frames", "set_device_emulation", "set_app_profile", "set_timezone", "run_actions"];
 export type TabIdRequiredAction = (typeof TAB_ID_REQUIRED_ACTIONS)[number];
 export declare function actionRequiresTabId(action: unknown): action is TabIdRequiredAction;
 export declare function validateRequiredActionTabId(action: string, data: unknown): void;

package/dist/generated-browser-action-protocol.js

@@ -76,8 +76,6 @@ export const TAB_ID_REQUIRED_ACTIONS = [
     'set_device_emulation',
     'set_app_profile',
     'set_timezone',
-    'get_cookie',
-    'set_cookie',
     'run_actions',
 ];
 const TAB_ID_REQUIRED_ACTION_SET = new Set(TAB_ID_REQUIRED_ACTIONS);
@@ -85,11 +83,22 @@ export function actionRequiresTabId(action) {
     return typeof action === 'string' && TAB_ID_REQUIRED_ACTION_SET.has(action);
 }
 export function validateRequiredActionTabId(action, data) {
-    if (!actionRequiresTabId(action))
+    const cookieAction = action === 'get_cookie' || action === 'set_cookie';
+    if (!actionRequiresTabId(action) && !cookieAction)
         return;
-    const tabId = data && typeof data === 'object' && !Array.isArray(data)
-        ? data.tabId
+    const input = data && typeof data === 'object' && !Array.isArray(data)
+        ? data
         : undefined;
+    const tabId = input?.tabId;
+    if (cookieAction && tabId === undefined) {
+        if (action === 'set_cookie' && input?.reload === true) {
+            throw new Error('set_cookie: reload requires tabId');
+        }
+        if (typeof input?.url !== 'string' || !input.url.trim()) {
+            throw new Error(`${action}: specify url or tabId`);
+        }
+        return;
+    }
     if (typeof tabId !== 'number' || !Number.isSafeInteger(tabId) || tabId < 0) {
         throw new Error(`${action} requires a numeric tabId. Call tab_open or tab_list to obtain a tabId.`);
     }

package/dist/plugin.d.ts

@@ -1,5 +1,5 @@
 import { type OfficialPluginInstaller } from './officialPluginInstaller.js';
-import { type PluginToolboxContribution } from './pluginRegistry.js';
+import { type PluginToolboxContribution, type PluginRegistration } from './pluginRegistry.js';
 import type { UnifiedInvokeOptions } from './unified.js';
 export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, 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';
@@ -22,11 +22,14 @@ export interface PluginExecutionContext {
 }
 export interface PluginApp {
     readonly options: Readonly<PluginOptions>;
-    command(signature: string, handler: PluginHandler, description?: string): void;
+    /** Examples omit the `mearl <plugin>` prefix, which help adds when displayed. */
+    command(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>) => unknown | Promise<unknown>;
+/** 工具列表仅检查入口；页面资源只在打开对应工具时检查。 */
+export declare function refreshRegisteredPlugin(name: string, includePage?: boolean): Promise<PluginRegistration | undefined>;
 /** 注册和执行复用同一宿主能力边界；仅 handler 执行期间开放浏览器调用。 */
 export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invoke' | 'options' | 'progress'>, pluginName?: string): Promise<{
     name: string | undefined;