@mearl/client 2.19.2 → 2.19.3

package/README.md

@@ -123,7 +123,7 @@ Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通
 | ------------------------ | ------------------------------------- |
 | `--connector <id\|名称>` | 限制到一台远端机器                    |
 | `--local`                | 只使用当前机器                        |
-| `--cdp`                  | 当前机器强制使用 CDP，并隐含 `--local` |
+| `--cdp`                  | 当前机器强制使用 CDP；清单只列 CDP 浏览器，并隐含 `--local` |
 | `--server <url>`         | 覆盖自动读取的 cloud-server 地址      |
 
 `browser_list --help` 和 `browser_launch --help` 会按场景展示宿主选择参数；连接或传输排障运行
@@ -268,13 +268,18 @@ Preact、Hooks 和 HTM 运行时。页面从 `window.mearl.ui` 读取 `html`、`
 `--mearl-accent` 等语义变量；主操作按钮使用 `--mearl-action-primary`、
 `--mearl-action-primary-hover` 和 `--mearl-action-primary-text`，以保持与扩展按钮一致。
 
-需要 BUC 身份的内部 HTTP 接口通过官方 `buc` 插件调用。CLI 使用 `mearl buc request`，业务插件使用
+需要 BUC 身份的内部 HTTP 接口通过官方 `buc` 插件调用。CLI 使用 `mearl buc request <url> [app]`，业务插件使用
 `app.invoke('buc', { command: 'request', input })`；当前身份和人员资料分别使用 `whoami` 与 `profile`
 子命令。BUC 插件按请求创建一次性凭据，只接受无 URL 凭据的 HTTPS 地址，过滤认证字段与 Cookie；
 调用方须按已验证的业务契约确认目标服务可信。请求始终在运行 CLI、SDK 或 MCP Server 的机器上执行，
 不随浏览器或 connector 转发。
 `buc request` 支持与 `send_request` 同结构的 `formData` 和 `files`；`files[].filePath` 从该插件执行
 宿主读取，而不是浏览器 native-host，无法引用宿主路径时使用 Base64 内容与 `filename`。
+省略 `app` 时从内置 URL 映射选择；Mearl 正式与预发的 `/api` 地址均映射到 `Mearl`。未登记的地址
+必须显式传入服务登记的 `app`，显式值优先；SDK、MCP 与插件调用的 `input.app` 遵循相同规则。
+AuthX 对应 `mearl authx request <url> [audience]`，省略 `audience` 时同样使用已登记的 URL 映射。
+两者的 `--help` 和 `request --help` 均包含完整 `--payload '{"command":"request","input":{...}}'`
+示例，涵盖 JSON 请求与文件上传。
 
 ## 支持的操作
 
@@ -308,7 +313,11 @@ Preact、Hooks 和 HTM 运行时。页面从 `window.mearl.ui` 读取 `html`、`
 
 `browser_list` 统一列出普通浏览器、Provider 浏览器和托管浏览器。`type` 区分
 `regular` / `managed`，`status` 区分 `connected` / `pairing` / `running_disconnected` /
-`stopped`；只有 `connected` 的浏览器可作为常规操作目标。
+`stopped`；只有 `connected` 的浏览器可作为常规操作目标。本机没有已连接的插件浏览器时，
+`browser_list` 会自动探测默认 CDP 端点，即使已有 Provider 配对记录也无需传 `--cdp`。
+`browser_list --cdp` 在没有已注册的普通 CDP 浏览器时会主动探测该端点，并只返回 CDP 浏览器；
+插件浏览器已连接也不影响这次探测。设置 `MEARL_SOCKET_PATH` 时，清单请求沿用该实例 Socket。
+`check --cdp` 也只检查这些 CDP 浏览器。
 
 `browser_release` 仅在用户明确要求结束调试、退出接管或清理会话资源时调用；它会释放
 debugger/CDP 控制和会话级临时状态，保留浏览器及全部标签页。托管实例的启动、关闭、持久化、

package/dist/check.js

@@ -174,7 +174,11 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                 environment.push({
                     status: 'error',
                     label: `Cloud server or connector discovery failed${source}`,
-                    details: [formatError(error), redactServerUrl(options.serverUrl)],
+                    details: [
+                        formatError(error),
+                        redactServerUrl(options.serverUrl),
+                        'On the Agent machine, run `mearl-cloud-server status` to verify the server and current connection command. Use `mearl check --local` to isolate this machine.',
+                    ],
                 });
             }
         }
@@ -215,7 +219,8 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                 details: [formatError(error)],
             });
         }
-        const connected = (browserList?.browsers ?? []).filter(browser => browser.status === 'connected');
+        const connected = (browserList?.browsers ?? []).filter(browser => browser.status === 'connected' &&
+            (options.transport !== 'cdp' || browser.transport === 'cdp'));
         let targets = connected;
         if (options.browser) {
             const matches = findBrowsers(connected, options.browser);
@@ -242,9 +247,16 @@ export async function runUnifiedCheck(options, dependencies = {}) {
         if (!options.browser && connected.length === 0 && browserList) {
             environment.push({
                 status: 'error',
-                label: 'No connected browser',
+                label: options.transport === 'cdp' ? 'No connected CDP browser' : 'No connected browser',
                 details: [
-                    'Open Chrome with the Mearl extension, start a managed browser, or connect a browser host.',
+                    options.transport === 'cdp'
+                        ? 'Enable a local CDP endpoint (see `mearl-native-host --help`) and run `mearl browser_list --cdp` to inspect discovery.'
+                        : 'Open Chrome with the Mearl extension, start a managed browser, or connect a browser host.',
+                    ...(!options.local && connectors.length > 0
+                        ? [
+                            'Connectors are connected but expose no ready browser. On the browser machine, run `mearl check --local`; use `mearl connector_list` for versions and heartbeat details.',
+                        ]
+                        : []),
                 ],
             });
         }

package/dist/cli.js

@@ -270,6 +270,9 @@ function printCheckHelp(commandName) {
         '  --json                输出机器可读 JSON',
         '  --updates            查询已安装组件的发布版本',
         '  -h, --help            查看帮助',
+        '',
+        '检查本机及远端控制链路；发现错误时退出码为 1。',
+        'Server 地址优先级：--server > MEARL_SERVER_URL > ~/.mearl/cloud-server.json。',
     ].join('\n'));
 }
 function printAdvancedCommandHelp(commandName, action) {
@@ -281,6 +284,7 @@ function printAdvancedCommandHelp(commandName, action) {
         '',
         '用法：',
         `  ${commandName} connector_list [--server <url>] [--timeout <seconds>]`,
+        '结果包含 count 与 connectors；每项包含 ID、名称、可选版本、连接时间和最后心跳。',
     ].join('\n'));
 }
 function printCommandHelp(commandName, command) {
@@ -298,6 +302,8 @@ function printCommandHelp(commandName, command) {
         for (const parameter of command.params) {
             const required = parameter.required ? '必填' : '可选';
             lines.push(`  ${parameter.name.padEnd(22)}${required.padEnd(6)}${parameter.type.padEnd(28)}  ${parameter.description}`);
+            for (const detail of parameter.details ?? [])
+                lines.push(`    ${detail}`);
         }
         lines.push('');
     }
@@ -307,6 +313,12 @@ function printCommandHelp(commandName, command) {
     else if (command.name === 'browser_launch') {
         lines.push('宿主选择（本机与远端同时可用时）：', '  --local               在当前机器启动', '  --connector <id|名称> 在指定远端 connector 启动', '  --browser <id|名称>   在控制浏览器所在宿主启动，并可作为 Cookie/UA 来源', '');
     }
+    if (command.notes?.length) {
+        lines.push('约束与行为：', ...command.notes.map(note => `  ${note}`), '');
+    }
+    if (command.result?.length) {
+        lines.push('结果：', ...command.result.map(line => `  ${line}`), '');
+    }
     if (command.examples?.length) {
         lines.push('示例：');
         for (const example of command.examples)
@@ -685,7 +697,14 @@ export async function runMearlCli(args, options = {}) {
         return actionInvocationFailed(parsed.action, result) ? 1 : 0;
     }
     catch (error) {
-        console.error(error instanceof Error ? error.message : String(error));
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        if (/connection timeout/i.test(message)) {
+            console.error('连接未就绪，请运行 mearl check 定位控制链路故障。');
+        }
+        else if (/请求超时|(?:request|command) timeout|timed out/i.test(message)) {
+            console.error('超时不代表动作未执行。点击、提交或写入后先读取当前状态确认结果；只读查询可缩小范围或增加 --timeout（秒）后重试。');
+        }
         return 1;
     }
     finally {

package/dist/commands.d.ts

@@ -4,6 +4,8 @@ export interface ParamDef {
     type: string;
     required?: boolean;
     description: string;
+    /** 复杂字段的结构与组合约束，仅在 action help 展示。 */
+    details?: readonly string[];
 }
 export interface CommandDef {
     name: BrowserCommandAction;
@@ -17,6 +19,8 @@ export interface CommandDef {
     /** 是否支持 --output */
     outputFlag?: boolean;
     examples?: string[];
+    notes?: readonly string[];
+    result?: readonly string[];
 }
 export declare const COMMANDS: readonly [{
     readonly name: "tab_checkpoint";
@@ -77,6 +81,8 @@ export declare const COMMANDS: readonly [{
         readonly type: "boolean";
         readonly description: "只返回数据结构，不返回叶子值";
     }];
+    readonly notes: readonly ["流式请求开始后即进入缓冲区；页面及 App 桥代发的 MTop SSE 都归入 mtop。无法归属当前页面 target 的 Service Worker 请求不在采集范围内。"];
+    readonly result: readonly ["nextCursor 用于同类查询续读，hasMore 表示还有数据，gap 表示缓冲区淘汰造成缺口；checkpoint cursor 可分别用于三类查询的初始边界。", "isPending 标记未完成请求；SSE 的 responseBody 保存按序到达的 event/data/timestamp/duration 分片。敏感请求头返回脱敏值。"];
     readonly examples: ["get_requests --payload '{\"tabId\":12345,\"count\":5}'", "get_requests --payload '{\"tabId\":12345,\"source\":\"mtop\",\"filter\":\"cart\"}'"];
 }, {
     readonly name: "get_logs";
@@ -107,6 +113,7 @@ export declare const COMMANDS: readonly [{
         readonly type: "string";
         readonly description: "只返回指定 tab checkpoint 或同类查询 cursor 之后的日志";
     }];
+    readonly result: readonly ["nextCursor 用于同类查询续读，hasMore 表示还有数据，gap 表示缓冲区淘汰造成缺口；checkpoint cursor 可分别用于三类查询的初始边界。"];
     readonly examples: ["get_logs --payload '{\"tabId\":12345,\"limit\":10,\"level\":\"error\"}'"];
 }, {
     readonly name: "get_events";
@@ -145,6 +152,8 @@ export declare const COMMANDS: readonly [{
         readonly type: "boolean";
         readonly description: "返回完整 URL、_raw 和 _context；默认 false";
     }];
+    readonly notes: readonly ["tab_open 新页从首屏采集；既有页面首次查询才启用采集，需要刷新或重新触发埋点。同批事件不会被 limit 拆开。"];
+    readonly result: readonly ["nextCursor 用于同类查询续读，hasMore 表示还有数据，gap 表示缓冲区淘汰造成缺口；checkpoint cursor 可分别用于三类查询的初始边界。", "captureStatus 为 armed/active/inactive；空结果附 hint 时按提示刷新或触发。默认去除 tracking URL query 与 _raw/_context，includeRaw=true 时保留。"];
     readonly examples: ["get_events --payload '{\"tabId\":12345,\"source\":\"aplus\",\"event_type\":\"CLK\",\"limit\":10}'", "get_events --payload '{\"tabId\":12345,\"filter\":\"order\",\"includeRaw\":true,\"limit\":1}'", "get_events --payload '{\"tabId\":12345,\"source\":\"all\",\"limit\":20}'"];
 }, {
     readonly name: "set_mock";
@@ -180,6 +189,7 @@ export declare const COMMANDS: readonly [{
         readonly type: "object";
         readonly description: "请求 query/body 字段子集匹配；$index 从 0 开始指定调用顺序";
     }];
+    readonly notes: readonly ["启用时至少提供 mockData 或非空 fields；非空 fields 优先。fields 每项 { path: string, value: any }，path 支持点号和数组索引。", "相同 apiName 的多条无条件 Mock 会覆盖；conditions 子集匹配 query/body（含 data 内层），不同条件可共存；$index 从 0 起控制调用顺序，不参与字段匹配。", "大字段可用顶层 @<绝对路径> 文件引用或 --payload-file；文件展开后仍受 Native Messaging 单条消息大小限制。"];
     readonly examples: ["set_mock --payload '{\"tabId\":12345,\"apiName\":\"mtop.cart.query\",\"mockData\":{\"ret\":[\"SUCCESS::调用成功\"]}}'", "set_mock --payload-file ./mock-data.json"];
 }, {
     readonly name: "get_mocks";
@@ -222,10 +232,12 @@ export declare const COMMANDS: readonly [{
         readonly name: "requestHeaders";
         readonly type: "array";
         readonly description: "modifyHeaders 动作的请求头修改列表";
+        readonly details: readonly ["每项 { header: string, operation: \"set\" | \"append\" | \"remove\", value?: string }；set/append 需 value"];
     }, {
         readonly name: "responseHeaders";
         readonly type: "array";
         readonly description: "modifyHeaders 动作的响应头修改列表";
+        readonly details: readonly ["每项 { header: string, operation: \"set\" | \"append\" | \"remove\", value?: string }；set/append 需 value"];
     }, {
         readonly name: "initiatorDomains";
         readonly type: "string";
@@ -243,6 +255,7 @@ export declare const COMMANDS: readonly [{
         readonly type: "string";
         readonly description: "规则说明";
     }];
+    readonly notes: readonly ["扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。"];
     readonly examples: ["set_rule --payload '{\"actionType\":\"block\",\"filter\":\"^https://example\\\\.com/ads/.*\"}'", "set_rule --payload '{\"ruleId\":42,\"enabled\":false}'"];
 }, {
     readonly name: "get_rules";
@@ -280,6 +293,7 @@ export declare const COMMANDS: readonly [{
         readonly name: "files";
         readonly type: "SendRequestFile[]";
         readonly description: "multipart 文件，最多 20 个、总计不超过 40 MiB；Base64 文件总计不超过 7 MiB。每项传 fieldName 和绝对 filePath，或传 base64 + filename";
+        readonly details: readonly ["fieldName: string（必填）；filePath: string 与 base64: string 二选一", "filename: string，base64 时必填，filePath 时默认文件 basename", "contentType: string（可选），默认按文件名推断 MIME，否则 application/octet-stream"];
     }, {
         readonly name: "withCookies";
         readonly type: "boolean";
@@ -293,6 +307,8 @@ export declare const COMMANDS: readonly [{
         readonly type: "number";
         readonly description: "超时毫秒数，默认 30000";
     }];
+    readonly notes: readonly ["仅用于非 BUC 请求；BUC 接口使用 mearl buc，不手工传 Token、DPoP 或 Ticket。", "body 不能与 formData/files 组合；multipart 不手工设置 Content-Type，由 Mearl 生成 boundary。", "filePath 属于 native-host 所在机器；无法引用远端路径时用 base64。BUC 上传的路径属于插件执行宿主。"];
+    readonly result: readonly ["返回 status、statusText、headers、body、bodyType、attachedCookieCount；bodyType 为 json/text/base64，二进制 body 需解码后保存。"];
     readonly examples: ["send_request --payload '{\"url\":\"https://api.example.com/data\",\"method\":\"GET\"}'", "send_request --payload '{\"url\":\"https://api.example.com/upload\",\"method\":\"POST\",\"formData\":{\"folder\":\"assets\"},\"files\":[{\"fieldName\":\"file\",\"filePath\":\"/absolute/path/image.png\"}]}'"];
 }, {
     readonly name: "send_mtop_request";
@@ -327,6 +343,8 @@ 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 result: readonly ["返回 success、response、requestData；业务成功需检查 response.ret。"];
     readonly examples: ["send_mtop_request --payload '{\"api\":\"mtop.trade.order.detail\",\"data\":{\"orderId\":\"123\"}}'"];
 }, {
     readonly name: "browser_list";
@@ -447,6 +465,8 @@ export declare const COMMANDS: readonly [{
         readonly type: "object";
         readonly description: "与 appProfile 配合；声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}";
     }];
+    readonly notes: readonly ["emulation / appProfile 只应用到新建 Tab；复用 Tab 要切换状态时用对应设置 action。", "closeExisting 不能与复用或 openerTabId 组合；多匹配默认报错，match.onMultiple=first 可显式选择第一个。"];
+    readonly result: readonly ["返回 tabId、url、title、opened/reused；reused=true 的既有页面应保留。", "active=true 时 activation 包含 tabActive、windowFocused、windowState、visibilityState；emulation 返回实际生效配置。", "capture.cursor 是导航前诊断边界，可分别用于 get_logs/get_requests/get_events 的 after。"];
     readonly examples: ["tab_open --payload '{\"url\":\"https://example.com\"}'", "tab_open --payload '{\"url\":\"https://example.com/page\",\"reuse\":\"prefer\",\"match\":{\"ignoreSearch\":true}}'", "tab_open --payload '{\"url\":\"https://m.example.com\",\"emulation\":{\"preset\":\"iphone-17-pro\"}}'", "tab_open --payload '{\"url\":\"https://market.m.taobao.com/app/trip/rx-home/pages/home\",\"appProfile\":\"fliggy\"}'", "tab_open --payload '{\"url\":\"https://market.m.taobao.com/app/trip/rx-home/pages/home\",\"appProfile\":\"fliggy\",\"emulation\":{\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}}'", "tab_open --payload '{\"url\":\"https://example.com\",\"appProfile\":\"fliggy\",\"os\":\"android\"}'", "tab_open --payload '{\"url\":\"https://example.com\",\"group\":\"验证任务\"}'"];
 }, {
     readonly name: "tab_close";
@@ -529,6 +549,8 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly 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\"}'"];
 }, {
     readonly name: "page_drag";
@@ -557,6 +579,8 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly 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\"}'"];
 }, {
     readonly name: "page_type";
@@ -581,6 +605,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
     readonly examples: ["page_type --payload '{\"tabId\":12345,\"selector\":\"@e6\",\"text\":\"搜索关键词\"}'"];
 }, {
     readonly name: "page_hover";
@@ -596,6 +621,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
     readonly examples: ["page_hover --payload '{\"tabId\":12345,\"selector\":\".nav-menu\"}'"];
 }, {
     readonly name: "page_scroll";
@@ -623,6 +649,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。", "action.data 返回 moved、atTop/atBottom、scrollYBefore/After、maxScrollY、resolvedContainer 和 ancestorDistance；自动发现的内部容器提供可复用 containerSelector。"];
     readonly 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_eval";
@@ -637,15 +664,23 @@ export declare const COMMANDS: readonly [{
         readonly type: "boolean";
         readonly description: "表达式返回 Promise 时等待完成，默认 true";
     }, {
-        readonly name: "observe";
+        readonly name: "frameId";
+        readonly type: "string";
+        readonly description: "page_frames 返回的目标 frame ID，扩展/CDP 均支持；省略时容器/设备外壳使用当前业务 frame，普通页面使用主 frame";
+    }, {
         readonly type: "object";
         readonly description: "仅在表达式会修改页面且需要观察结果时显式传入；不传保持轻量裸执行";
+        readonly name: string;
+        readonly required?: boolean;
+        readonly details?: readonly string[];
     }, ParamDef, {
         readonly name: "tabId";
         readonly type: "number";
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
+    readonly notes: readonly ["优先使用结构化 action；仅在其无法表达需求时执行最小范围脚本。"];
+    readonly result: readonly ["默认返回 { result }；observe 对象启用观察并返回 { action, observation }；仅开启 diagnostics 时返回 { action, diagnostics }。diagnostics=false 不启用包装。失败阶段语义同 page_click。"];
     readonly examples: ["page_eval --payload '{\"tabId\":12345,\"expression\":\"document.title\"}'"];
 }, {
     readonly name: "page_inspect";
@@ -676,6 +711,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
+    readonly result: readonly ["matches[] 包含 boundingBox、computedStyle、hitTest、scroll 溢出量及可用的 scrollContainer。receivesPointerEvents=false 时读取 occludedBy。", "$0 还返回 resolvedSelector、属性、XPath 和可用框架信息。"];
     readonly examples: ["page_inspect --payload '{\"tabId\":12345,\"selector\":\".form-field\",\"styles\":[\"display\",\"width\"]}'", "page_inspect --payload '{\"tabId\":12345,\"selector\":\"@e8\"}'", "page_inspect --payload '{\"tabId\":12345,\"selector\":\"$0\"}'", "page_inspect --payload '{\"tabId\":12345,\"filter\":\"horizontal-overflow\"}'", "page_inspect --payload '{\"tabId\":12345,\"filter\":\"scrollable\"}'"];
 }, {
     readonly name: "page_press";
@@ -699,6 +735,8 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
+    readonly notes: readonly ["隐藏页 DOM 模式支持 Tab 焦点移动、原生控件 Enter/Space 激活和输入框 Enter 提交；编辑、选择、方向键和页面滚动等原生行为需可见页与 pressMode=keyboard。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。", "action.data.dispatchMode / fallbackReason / defaultAction 说明实际输入路径。"];
     readonly examples: ["page_press --payload '{\"tabId\":12345,\"key\":\"Enter\"}'"];
 }, {
     readonly name: "page_wait";
@@ -741,6 +779,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
+    readonly notes: readonly ["time / selector / text / condition 必须且只能提供一个；time 范围 0–60000ms。页面交互已有内置观察，仅在需要独立等待条件时使用。"];
     readonly examples: ["page_wait --payload '{\"tabId\":12345,\"time\":1000}'", "page_wait --payload '{\"tabId\":12345,\"selector\":\".dialog\",\"state\":\"visible\"}'", "page_wait --payload '{\"tabId\":12345,\"selector\":\".loading\",\"state\":\"hidden\"}'", "page_wait --payload '{\"tabId\":12345,\"text\":\"提交成功\"}'", "page_wait --payload '{\"tabId\":12345,\"condition\":\"window.appReady === true\",\"timeout\":30000}'"];
 }, {
     readonly name: "page_navigate";
@@ -763,6 +802,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
+    readonly notes: readonly ["url / refresh=true / history 必须且只能提供一个。"];
     readonly examples: ["page_navigate --payload '{\"tabId\":12345,\"url\":\"https://example.com/page2\"}'", "page_navigate --payload '{\"tabId\":12345,\"refresh\":true}'", "page_navigate --payload '{\"tabId\":12345,\"history\":\"back\"}'"];
 }, {
     readonly name: "page_upload";
@@ -783,6 +823,8 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly 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\"]}'"];
 }, {
     readonly name: "page_snapshot";
@@ -825,6 +867,8 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
+    readonly notes: readonly ["query.text / query.role 至少提供一个；query.exact 默认 true。每次快照刷新有效 ref 集合。", "interactive 无 AX 控件时回退到 viewport，不会自动改用 dom；Canvas 内容需截图。"];
+    readonly result: readonly ["返回 snapshot、elementCount、outputNodeCount、mode；截断时 truncated=true。", "query 返回 matches 与完整 matchCount，matches 最多 100 项，裁剪时 matchesTruncated=true。容器/iframe 的视口裁剪返回 outerViewport、contentViewport 和滚动位置。"];
     readonly examples: ["page_snapshot --payload '{\"tabId\":12345}'", "page_snapshot --payload '{\"tabId\":1,\"mode\":\"viewport\"}'", "page_snapshot --payload '{\"tabId\":1,\"mode\":\"dom\"}'", "page_snapshot --payload '{\"tabId\":1,\"rootSelector\":\"[role=dialog]\"}'", "page_snapshot --payload '{\"tabId\":1,\"rootRef\":\"@e8\",\"ancestorDepth\":1}'", "page_snapshot --payload '{\"tabId\":1,\"query\":{\"text\":\"保存\",\"role\":\"button\"}}'"];
 }, {
     readonly name: "page_screenshot";
@@ -848,6 +892,8 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
+    readonly notes: readonly ["使用 --output <path> 保存图片；省略时 stdout 返回含 base64 data 的 JSON，避免直接将其加载为文本。"];
+    readonly result: readonly ["meta 包含 format、width、height、size、url、title；宽高为物理像素（CSS 尺寸 × DPR）。"];
     readonly examples: ["page_screenshot --payload '{\"tabId\":12345}' --output ./screenshot.png", "page_screenshot --payload '{\"tabId\":12345,\"selector\":\".product-card\"}' --output ./card.png"];
 }, {
     readonly name: "set_device_emulation";
@@ -912,6 +958,8 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
+    readonly notes: readonly ["无 preset 时 width/height 必须成对提供且 userAgent 必填；mobile 默认 true，touch 跟随 mobile。", "deviceShell 开启/移除时必须重载；splitScreen 仅在已启用 App 档案、deviceShell=true、横屏时生效。"];
+    readonly result: readonly ["返回实际 viewport（width/height/deviceScaleFactor/scale）、UA、mobile、touch、orientation、deviceShell、splitScreen 和 reloaded；应以响应确认生效状态。"];
     readonly examples: ["set_device_emulation --payload '{\"tabId\":12345,\"enabled\":true,\"preset\":\"iphone-17-pro\"}'", "set_device_emulation --payload '{\"tabId\":12345,\"enabled\":true,\"preset\":\"pixel-11\",\"orientation\":\"landscape\"}'", "set_device_emulation --payload '{\"tabId\":12345,\"enabled\":true,\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}'", "set_device_emulation --payload '{\"tabId\":12345,\"enabled\":false}'"];
 }, {
     readonly name: "set_app_profile";
@@ -960,6 +1008,8 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
+    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 name: "set_timezone";
@@ -982,8 +1032,7 @@ export declare const COMMANDS: readonly [{
     readonly params: [{
         readonly name: "tabId";
         readonly type: "number";
-        readonly required: true;
-        readonly description: "目标标签页 ID";
+        readonly description: "可选；指定标签页的 Cookie 存储区，省略时使用浏览器默认存储区";
     }, {
         readonly name: "name";
         readonly type: "string";
@@ -992,7 +1041,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "url";
         readonly type: "string";
-        readonly description: "可选 Cookie 查询 URL；省略时使用当前标签页 URL";
+        readonly description: "Cookie 查询 URL；未传 tabId 时必填，省略时使用指定标签页 URL";
     }, {
         readonly name: "domain";
         readonly type: "string";
@@ -1002,15 +1051,20 @@ export declare const COMMANDS: readonly [{
         readonly type: "string";
         readonly description: "可选精确 path 过滤";
     }];
-    readonly examples: ["get_cookie --payload '{\"tabId\":12345,\"name\":\"feature_flag\"}'", "get_cookie --payload '{\"tabId\":12345,\"name\":\"edith_switch_br.rx-vehicle-search_home\",\"domain\":\"taobao.com\"}'", "get_cookie --payload '{\"tabId\":12345,\"name\":\"tracknick\",\"url\":\"https://www.taobao.com/\",\"domain\":\"taobao.com\",\"path\":\"/\"}'"];
+    readonly notes: readonly ["只读取指定非分区 Cookie，不列举全部、不回退分区 Cookie，拒绝 HttpOnly；禁止读取认证 Token。指定 url 不导航，指定 tabId 仅选择存储区时不启动采集。"];
+    readonly result: readonly ["找到时 found=true 并返回 value/domain/path；不存在时 found=false。"];
+    readonly examples: ["get_cookie --payload '{\"tabId\":12345,\"name\":\"feature_flag\"}'", "get_cookie --payload '{\"url\":\"https://www.taobao.com/\",\"name\":\"tracknick\"}'", "get_cookie --payload '{\"tabId\":12345,\"name\":\"edith_switch_br.rx-vehicle-search_home\",\"domain\":\"taobao.com\"}'", "get_cookie --payload '{\"tabId\":12345,\"name\":\"tracknick\",\"url\":\"https://www.taobao.com/\",\"domain\":\"taobao.com\",\"path\":\"/\"}'"];
 }, {
     readonly name: "set_cookie";
-    readonly description: "设置当前标签页域下的一个指定非分区 session Cookie，可选刷新页面";
+    readonly description: "在目标浏览器设置一个指定非分区 session Cookie，可选刷新指定页面";
     readonly params: [{
         readonly name: "tabId";
         readonly type: "number";
-        readonly required: true;
-        readonly description: "目标标签页 ID";
+        readonly description: "可选；指定标签页的 Cookie 存储区，reload=true 时必填";
+    }, {
+        readonly name: "url";
+        readonly type: "string";
+        readonly description: "Cookie 目标 URL；未传 tabId 时必填，省略时使用指定标签页 URL";
     }, {
         readonly name: "name";
         readonly type: "string";
@@ -1024,7 +1078,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "domain";
         readonly type: "string";
-        readonly description: "Cookie 域，默认当前 host；只允许当前 host 或其父域";
+        readonly description: "Cookie 域，默认目标 URL 的 host；只允许目标 host 或其父域";
     }, {
         readonly name: "path";
         readonly type: "string";
@@ -1032,9 +1086,11 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "reload";
         readonly type: "boolean";
-        readonly description: "设置后是否刷新页面，默认 false";
+        readonly description: "设置后是否刷新指定 tabId，默认 false；true 时必须传 tabId";
     }];
-    readonly examples: ["set_cookie --payload '{\"tabId\":12345,\"name\":\"feature_flag\",\"value\":\"enabled\"}'", "set_cookie --payload '{\"tabId\":12345,\"name\":\"edith_switch_br.rx-vehicle-search_home\",\"value\":\"3.6.63\",\"domain\":\"taobao.com\",\"reload\":true}'"];
+    readonly notes: readonly ["仅写非分区 session Cookie，不支持删除。reload=true 时校验目标域与刷新页域的授权。"];
+    readonly result: readonly ["返回 url/name/domain/path/reloaded，指定标签页时包含 tabId；不回显 Cookie 值。"];
+    readonly examples: ["set_cookie --payload '{\"tabId\":12345,\"name\":\"feature_flag\",\"value\":\"enabled\"}'", "set_cookie --payload '{\"url\":\"https://www.taobao.com/\",\"name\":\"feature_flag\",\"value\":\"enabled\"}'", "set_cookie --payload '{\"tabId\":12345,\"name\":\"edith_switch_br.rx-vehicle-search_home\",\"value\":\"3.6.63\",\"domain\":\"taobao.com\",\"reload\":true}'"];
 }, {
     readonly name: "page_frames";
     readonly description: "获取页面主 frame 与所有 iframe 列表";
@@ -1044,6 +1100,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
+    readonly result: readonly ["frames[] 包含 frameId、url、name 和 isMainFrame；frameId 可用于 page_eval 等支持 frame 定位的 action。"];
     readonly examples: ["page_frames --payload '{\"tabId\":12345}'"];
 }, {
     readonly name: "request_domain_permission";
@@ -1054,6 +1111,8 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "需要授权的域名，如 example.com";
     }];
+    readonly notes: readonly ["domain 使用纯主机名，不传 URL。仅在非 BUC send_request 报域权限缺失时申请，BUC 不使用浏览器域权限。", "弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。"];
+    readonly result: readonly ["返回 granted、domain，授权成功时包含 origin。"];
     readonly examples: ["request_domain_permission --payload '{\"domain\":\"example.com\"}'"];
 }, {
     readonly name: "run_actions";
@@ -1070,6 +1129,8 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "所有步骤共享的 tabId，步骤自身指定的优先";
     }];
-    readonly examples: ["run_actions --payload '{\"tabId\":12345,\"actions\":[{\"action\":\"page_scroll\",\"data\":{\"direction\":\"down\"}},{\"action\":\"page_wait\",\"data\":{\"time\":500}},{\"action\":\"page_screenshot\"}]}'"];
+    readonly notes: readonly ["最多 50 步，不允许嵌套 run_actions；需要根据每步效果决策时逐步调用普通 action。"];
+    readonly result: readonly ["返回 results、completedSteps、totalSteps；失败时包含 error/failedStep，后续步骤未执行。"];
+    readonly examples: ["run_actions --payload '{\"tabId\":12345,\"actions\":[{\"action\":\"page_hover\",\"data\":{\"selector\":\"#menu\"}},{\"action\":\"page_click\",\"data\":{\"selector\":\"#menu-item\"}}]}'"];
 }];
 export declare const COMMAND_MAP: ReadonlyMap<string, CommandDef>;