@mearl/client 2.7.3 → 2.8.1

package/dist/cli.js

@@ -13,12 +13,16 @@ const CATEGORIES = [
         names: ['tab_checkpoint', 'get_requests', 'get_logs', 'get_events', 'get_api_schema'],
     },
     { title: 'Mock & 规则', names: ['set_mock', 'get_mocks', 'set_rule', 'get_rules'] },
-    { title: '网络代理', names: ['send_request', 'send_mtop_request'] },
+    {
+        title: '网络代理',
+        names: ['send_request', 'send_mtop_request', 'request_domain_permission'],
+    },
     { title: '标签页', names: ['tab_open', 'tab_close', 'tab_list'] },
     {
         title: '页面操作',
         names: [
             'page_click',
+            'page_drag',
             'page_type',
             'page_hover',
             'page_scroll',
@@ -36,7 +40,7 @@ const CATEGORIES = [
     },
     {
         title: '环境与 Cookie',
-        names: ['set_device_emulation', 'set_timezone', 'get_cookie', 'set_cookie'],
+        names: ['set_device_emulation', 'set_app_profile', 'set_timezone', 'get_cookie', 'set_cookie'],
     },
     { title: '用户信息', names: ['get_user_info'] },
     { title: '录制', names: ['record_start', 'record_stop'] },
@@ -289,8 +293,10 @@ export async function runMearlCli(args, options = {}) {
         return 0;
     }
     if (args[0] !== 'check' && args[0] !== 'connector_list' && !COMMAND_MAP.has(args[0])) {
-        printUnknownCommand(commandName, args);
-        return 2;
+        if (!args[0].startsWith('__')) {
+            printUnknownCommand(commandName, args);
+            return 2;
+        }
     }
     let parsed;
     try {

package/dist/commands.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserCommandAction } from './generated-browser-action-protocol.js';
+import { type BrowserCommandAction } from './generated-browser-action-protocol.js';
 export interface ParamDef {
     name: string;
     type: string;
@@ -56,6 +56,22 @@ export declare const COMMANDS: readonly [{
         readonly name: "includeBody";
         readonly type: "boolean";
         readonly description: "是否包含请求/响应体，默认 true";
+    }, {
+        readonly name: "includeHeaders";
+        readonly type: "boolean";
+        readonly description: "是否包含请求/响应头，默认 false";
+    }, {
+        readonly name: "maxBodySize";
+        readonly type: "number";
+        readonly description: "单个请求/响应体最大字符数，默认 50000";
+    }, {
+        readonly name: "fields";
+        readonly type: "string[]";
+        readonly description: "从响应体提取指定字段路径，最多 100 个";
+    }, {
+        readonly name: "keysOnly";
+        readonly type: "boolean";
+        readonly description: "只返回数据结构，不返回叶子值";
     }];
     readonly examples: ["get_requests --payload '{\"count\":5}'", "get_requests --payload '{\"source\":\"mtop\",\"filter\":\"cart\"}'"];
 }, {
@@ -72,7 +88,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "level";
         readonly type: "string";
-        readonly description: "按日志级别过滤：log/info/warn/error";
+        readonly description: "按日志级别过滤：log/info/warn/error/all";
     }, {
         readonly name: "filter";
         readonly type: "string";
@@ -132,6 +148,10 @@ export declare const COMMANDS: readonly [{
         readonly type: "string";
         readonly required: true;
         readonly description: "API 名称";
+    }, {
+        readonly name: "version";
+        readonly type: "string";
+        readonly description: "API 版本，用于精确匹配接口定义";
     }, {
         readonly name: "fields";
         readonly type: "(\"schema\" | \"hsf\")[]";
@@ -188,7 +208,46 @@ export declare const COMMANDS: readonly [{
 }, {
     readonly name: "set_rule";
     readonly description: "添加 Chrome declarativeNetRequest 规则（重定向/修改请求头/拦截请求）";
-    readonly examples: ["set_rule --payload '{\"rule\":{...}}'"];
+    readonly params: [{
+        readonly name: "actionType";
+        readonly type: "\"redirect\" | \"block\" | \"allow\" | \"upgradeScheme\" | \"modifyHeaders\"";
+        readonly required: true;
+        readonly description: "规则动作";
+    }, {
+        readonly name: "filter";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "URL 过滤表达式";
+    }, {
+        readonly name: "redirectUrl";
+        readonly type: "string";
+        readonly description: "redirect 动作的目标 URL";
+    }, {
+        readonly name: "requestHeaders";
+        readonly type: "array";
+        readonly description: "modifyHeaders 动作的请求头修改列表";
+    }, {
+        readonly name: "responseHeaders";
+        readonly type: "array";
+        readonly description: "modifyHeaders 动作的响应头修改列表";
+    }, {
+        readonly name: "initiatorDomains";
+        readonly type: "string";
+        readonly description: "发起方域名过滤";
+    }, {
+        readonly name: "resourceTypes";
+        readonly type: "string[]";
+        readonly description: "资源类型过滤";
+    }, {
+        readonly name: "priority";
+        readonly type: "number";
+        readonly description: "规则优先级";
+    }, {
+        readonly name: "description";
+        readonly type: "string";
+        readonly description: "规则说明";
+    }];
+    readonly examples: ["set_rule --payload '{\"actionType\":\"block\",\"filter\":\"^https://example\\\\.com/ads/.*\"}'"];
 }, {
     readonly name: "get_rules";
     readonly description: "查看当前存储的全部请求规则（含 Options 面板配置的）";
@@ -229,6 +288,10 @@ export declare const COMMANDS: readonly [{
         readonly name: "withCookies";
         readonly type: "boolean";
         readonly description: "是否附加浏览器 Cookie，默认 true";
+    }, {
+        readonly name: "responseType";
+        readonly type: "\"json\" | \"text\" | \"auto\"";
+        readonly description: "响应解析方式，默认 auto";
     }, {
         readonly name: "timeout";
         readonly type: "number";
@@ -237,7 +300,7 @@ export declare const COMMANDS: readonly [{
     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";
-    readonly description: "在页面上下文中发起 mtop 请求，自动处理签名和 token";
+    readonly description: "使用目标浏览器 Cookie 发起 mtop 请求，自动处理签名和 token";
     readonly params: [{
         readonly name: "api";
         readonly type: "string";
@@ -255,6 +318,10 @@ export declare const COMMANDS: readonly [{
         readonly name: "method";
         readonly type: "string";
         readonly description: "HTTP 方法，默认 GET";
+    }, {
+        readonly name: "appKey";
+        readonly type: "string";
+        readonly description: "签名使用的 appKey，默认 12574478";
     }, {
         readonly name: "env";
         readonly type: "\"online\" | \"pre\"";
@@ -280,6 +347,10 @@ export declare const COMMANDS: readonly [{
         readonly name: "refresh";
         readonly type: "boolean";
         readonly description: "list 时是否强制刷新账号列表";
+    }, {
+        readonly name: "pageIndex";
+        readonly type: "number";
+        readonly description: "list 时的页码，默认 1";
     }, {
         readonly name: "accountId";
         readonly type: "string | number";
@@ -300,7 +371,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["tdbank_account --payload '{\"operation\":\"current\"}'", "tdbank_account --payload '{\"operation\":\"list\",\"refresh\":true}'", "tdbank_account --payload '{\"operation\":\"switch\",\"accountId\":12345}'", "tdbank_account --payload '{\"operation\":\"borrow\",\"query\":\"test_account\"}'"];
 }, {
     readonly name: "browser_list";
-    readonly description: "列出所有浏览器及其连接状态、类型和托管实例信息；AgentBay 可包含镜像、持久化 Context 和串流地址";
+    readonly description: "列出所有浏览器及其连接状态、类型和托管实例信息；AgentBay 可包含镜像与持久化 Context";
     readonly examples: ["browser_list"];
 }, {
     readonly name: "browser_release";
@@ -427,8 +498,12 @@ export declare const COMMANDS: readonly [{
         readonly name: "emulation";
         readonly type: "object";
         readonly description: "开 tab 即进入移动端模拟态（首屏即移动态、无需 reload）。字段同 set_device_emulation 去掉 enabled，如 {\"preset\":\"iphone-15-pro\"}";
+    }, {
+        readonly name: "appProfile";
+        readonly type: "string";
+        readonly description: "开 tab 即进入 App 容器模拟态（客户端 UA + JSBridge 托管 + iframe 容器栈 + 自适应系统标题栏，首屏即容器态）。系统栏由 iframe 外层统一渲染，并根据页面协议与桥调用切换普通、沉浸或隐藏状态；档案名同 set_app_profile，如 \"fliggy\"";
     }];
-    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-15-pro\"}}'", "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-15-pro\"}}'", "tab_open --payload '{\"url\":\"https://market.m.taobao.com/app/trip/rx-home/pages/home\",\"appProfile\":\"fliggy\"}'", "tab_open --payload '{\"url\":\"https://example.com\",\"group\":\"验证任务\"}'"];
 }, {
     readonly name: "tab_close";
     readonly description: "关闭指定标签页";
@@ -853,6 +928,45 @@ export declare const COMMANDS: readonly [{
         readonly description: "目标标签页 ID";
     }];
     readonly examples: ["set_device_emulation --payload '{\"enabled\":true,\"preset\":\"iphone-15-pro\"}'", "set_device_emulation --payload '{\"enabled\":true,\"preset\":\"pixel-8\",\"orientation\":\"landscape\"}'", "set_device_emulation --payload '{\"enabled\":false}'"];
+}, {
+    readonly name: "set_app_profile";
+    readonly description: "把目标 tab 切换为 App 容器模拟态（客户端 UA + JSBridge 托管 + 页面跳转 iframe 容器栈 + scheme 唤端映射 + 自适应系统标题栏），系统栏由 iframe 外层统一渲染，并根据页面协议与桥调用切换普通、沉浸或隐藏状态；用于桌面浏览器近似实机验证 App 内 H5，需保持调试控制才持续生效";
+    readonly params: [{
+        readonly name: "enabled";
+        readonly type: "boolean";
+        readonly required: true;
+        readonly description: "true=启用，false=清除";
+    }, {
+        readonly name: "profile";
+        readonly type: "string";
+        readonly description: `\u5BB9\u5668\u6863\u6848\u540D\uFF08enabled=true \u65F6\u5FC5\u586B\uFF09\uFF1A${string}`;
+    }, {
+        readonly name: "os";
+        readonly type: "\"ios\" | \"android\"";
+        readonly description: "容器系统，默认 ios";
+    }, {
+        readonly name: "appVersion";
+        readonly type: "string";
+        readonly description: "覆盖档案默认 App 版本号";
+    }, {
+        readonly name: "deviceModel";
+        readonly type: "string";
+        readonly description: "Android 机型名（拼入 UA 与 __DEVICE_MODEL__）";
+    }, {
+        readonly name: "emulation";
+        readonly type: "object";
+        readonly description: "覆盖档案推荐的设备模拟参数，字段同 set_device_emulation 去掉 enabled";
+    }, {
+        readonly name: "reload";
+        readonly type: "boolean";
+        readonly description: "应用/清除后是否重载页面，默认 true";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }];
+    readonly examples: ["set_app_profile --payload '{\"enabled\":true,\"profile\":\"fliggy\"}'", "set_app_profile --payload '{\"enabled\":true,\"profile\":\"alipay\",\"os\":\"android\",\"deviceModel\":\"Pixel 8 Pro\"}'", "set_app_profile --payload '{\"enabled\":false}'"];
 }, {
     readonly name: "set_timezone";
     readonly description: "覆盖目标 tab 的时区，传空字符串恢复浏览器默认时区";
@@ -957,6 +1071,6 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "所有步骤共享的 tabId，步骤自身指定的优先";
     }];
-    readonly examples: ["run_actions --payload '{\"actions\":[{\"action\":\"page_scroll\",\"data\":{\"direction\":\"down\"}},{\"action\":\"page_wait\",\"data\":{\"time\":500}},{\"action\":\"page_screenshot\"}]}'"];
+    readonly examples: ["run_actions --payload '{\"tabId\":12345,\"actions\":[{\"action\":\"page_scroll\",\"data\":{\"direction\":\"down\"}},{\"action\":\"page_wait\",\"data\":{\"time\":500}},{\"action\":\"page_screenshot\"}]}'"];
 }];
 export declare const COMMAND_MAP: ReadonlyMap<string, CommandDef>;

package/dist/commands.js

@@ -1,3 +1,6 @@
+import { APP_PROFILE_NAMES, } from './generated-browser-action-protocol.js';
+/** 容器档案名列表（拼进参数说明，新增档案无需改本文件） */
+const APP_PROFILE_NAME_LIST = APP_PROFILE_NAMES.join('/');
 const PAGE_DIAGNOSTICS_PARAM = {
     name: 'diagnostics',
     type: 'object | boolean',
@@ -35,6 +38,10 @@ export const COMMANDS = [
                 description: '只返回指定 tab checkpoint 或同类查询 cursor 之后的请求',
             },
             { name: 'includeBody', type: 'boolean', description: '是否包含请求/响应体，默认 true' },
+            { name: 'includeHeaders', type: 'boolean', description: '是否包含请求/响应头，默认 false' },
+            { name: 'maxBodySize', type: 'number', description: '单个请求/响应体最大字符数，默认 50000' },
+            { name: 'fields', type: 'string[]', description: '从响应体提取指定字段路径，最多 100 个' },
+            { name: 'keysOnly', type: 'boolean', description: '只返回数据结构，不返回叶子值' },
         ],
         examples: [
             `get_requests --payload '{"count":5}'`,
@@ -47,7 +54,7 @@ export const COMMANDS = [
         params: [
             { name: 'tabId', type: 'number', description: '目标标签页 ID，从 tab_list 获取' },
             { name: 'limit', type: 'number', description: '返回最新 N 条，默认 100' },
-            { name: 'level', type: 'string', description: '按日志级别过滤：log/info/warn/error' },
+            { name: 'level', type: 'string', description: '按日志级别过滤：log/info/warn/error/all' },
             { name: 'filter', type: 'string', description: '按内容过滤，支持正则' },
             { name: 'since', type: 'number', description: '只返回最近 N 秒内的日志' },
             {
@@ -90,6 +97,7 @@ export const COMMANDS = [
         description: '获取 API 接口 schema（出入参定义）',
         params: [
             { name: 'api', type: 'string', required: true, description: 'API 名称' },
+            { name: 'version', type: 'string', description: 'API 版本，用于精确匹配接口定义' },
             {
                 name: 'fields',
                 type: '("schema" | "hsf")[]',
@@ -144,7 +152,33 @@ export const COMMANDS = [
     {
         name: 'set_rule',
         description: '添加 Chrome declarativeNetRequest 规则（重定向/修改请求头/拦截请求）',
-        examples: [`set_rule --payload '{"rule":{...}}'`],
+        params: [
+            {
+                name: 'actionType',
+                type: '"redirect" | "block" | "allow" | "upgradeScheme" | "modifyHeaders"',
+                required: true,
+                description: '规则动作',
+            },
+            { name: 'filter', type: 'string', required: true, description: 'URL 过滤表达式' },
+            { name: 'redirectUrl', type: 'string', description: 'redirect 动作的目标 URL' },
+            {
+                name: 'requestHeaders',
+                type: 'array',
+                description: 'modifyHeaders 动作的请求头修改列表',
+            },
+            {
+                name: 'responseHeaders',
+                type: 'array',
+                description: 'modifyHeaders 动作的响应头修改列表',
+            },
+            { name: 'initiatorDomains', type: 'string', description: '发起方域名过滤' },
+            { name: 'resourceTypes', type: 'string[]', description: '资源类型过滤' },
+            { name: 'priority', type: 'number', description: '规则优先级' },
+            { name: 'description', type: 'string', description: '规则说明' },
+        ],
+        examples: [
+            `set_rule --payload '{"actionType":"block","filter":"^https://example\\\\.com/ads/.*"}'`,
+        ],
     },
     {
         name: 'get_rules',
@@ -172,6 +206,11 @@ export const COMMANDS = [
                 description: 'multipart 文件，最多 20 个、总计不超过 40 MiB；Base64 文件总计不超过 7 MiB。每项传 fieldName 和绝对 filePath，或传 base64 + filename',
             },
             { name: 'withCookies', type: 'boolean', description: '是否附加浏览器 Cookie，默认 true' },
+            {
+                name: 'responseType',
+                type: '"json" | "text" | "auto"',
+                description: '响应解析方式，默认 auto',
+            },
             { name: 'timeout', type: 'number', description: '超时毫秒数，默认 30000' },
         ],
         examples: [
@@ -181,12 +220,13 @@ export const COMMANDS = [
     },
     {
         name: 'send_mtop_request',
-        description: '在页面上下文中发起 mtop 请求，自动处理签名和 token',
+        description: '使用目标浏览器 Cookie 发起 mtop 请求，自动处理签名和 token',
         params: [
             { name: 'api', type: 'string', required: true, description: 'mtop API 名称' },
             { name: 'data', type: 'object', description: '请求数据' },
             { name: 'version', type: 'string', description: 'API 版本，默认 1.0' },
             { name: 'method', type: 'string', description: 'HTTP 方法，默认 GET' },
+            { name: 'appKey', type: 'string', description: '签名使用的 appKey，默认 12574478' },
             { name: 'env', type: '"online" | "pre"', description: '请求环境，默认 online' },
             { name: 'timeout', type: 'number', description: '超时毫秒数，默认 10000' },
         ],
@@ -209,6 +249,7 @@ export const COMMANDS = [
                 description: '操作类型，默认 list',
             },
             { name: 'refresh', type: 'boolean', description: 'list 时是否强制刷新账号列表' },
+            { name: 'pageIndex', type: 'number', description: 'list 时的页码，默认 1' },
             { name: 'accountId', type: 'string | number', description: 'switch 时使用账号列表中的 id' },
             { name: 'havanaId', type: 'string | number', description: 'switch 时也可直接指定 havanaId' },
             { name: 'site', type: 'string | number', description: '直接指定 havanaId 时必填' },
@@ -224,7 +265,7 @@ export const COMMANDS = [
     // ── 浏览器 ────────────────────────────────────────────────────────────────
     {
         name: 'browser_list',
-        description: '列出所有浏览器及其连接状态、类型和托管实例信息；AgentBay 可包含镜像、持久化 Context 和串流地址',
+        description: '列出所有浏览器及其连接状态、类型和托管实例信息；AgentBay 可包含镜像与持久化 Context',
         examples: ['browser_list'],
     },
     {
@@ -364,11 +405,17 @@ export const COMMANDS = [
                 type: 'object',
                 description: '开 tab 即进入移动端模拟态（首屏即移动态、无需 reload）。字段同 set_device_emulation 去掉 enabled，如 {"preset":"iphone-15-pro"}',
             },
+            {
+                name: 'appProfile',
+                type: 'string',
+                description: '开 tab 即进入 App 容器模拟态（客户端 UA + JSBridge 托管 + iframe 容器栈 + 自适应系统标题栏，首屏即容器态）。系统栏由 iframe 外层统一渲染，并根据页面协议与桥调用切换普通、沉浸或隐藏状态；档案名同 set_app_profile，如 "fliggy"',
+            },
         ],
         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-15-pro"}}'`,
+            `tab_open --payload '{"url":"https://market.m.taobao.com/app/trip/rx-home/pages/home","appProfile":"fliggy"}'`,
             `tab_open --payload '{"url":"https://example.com","group":"验证任务"}'`,
         ],
     },
@@ -785,6 +832,37 @@ export const COMMANDS = [
             `set_device_emulation --payload '{"enabled":false}'`,
         ],
     },
+    {
+        name: 'set_app_profile',
+        description: '把目标 tab 切换为 App 容器模拟态（客户端 UA + JSBridge 托管 + 页面跳转 iframe 容器栈 + scheme 唤端映射 + 自适应系统标题栏），系统栏由 iframe 外层统一渲染，并根据页面协议与桥调用切换普通、沉浸或隐藏状态；用于桌面浏览器近似实机验证 App 内 H5，需保持调试控制才持续生效',
+        params: [
+            { name: 'enabled', type: 'boolean', required: true, description: 'true=启用，false=清除' },
+            {
+                name: 'profile',
+                type: 'string',
+                description: `容器档案名（enabled=true 时必填）：${APP_PROFILE_NAME_LIST}`,
+            },
+            { name: 'os', type: '"ios" | "android"', description: '容器系统，默认 ios' },
+            { name: 'appVersion', type: 'string', description: '覆盖档案默认 App 版本号' },
+            {
+                name: 'deviceModel',
+                type: 'string',
+                description: 'Android 机型名（拼入 UA 与 __DEVICE_MODEL__）',
+            },
+            {
+                name: 'emulation',
+                type: 'object',
+                description: '覆盖档案推荐的设备模拟参数，字段同 set_device_emulation 去掉 enabled',
+            },
+            { name: 'reload', type: 'boolean', description: '应用/清除后是否重载页面，默认 true' },
+            { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
+        ],
+        examples: [
+            `set_app_profile --payload '{"enabled":true,"profile":"fliggy"}'`,
+            `set_app_profile --payload '{"enabled":true,"profile":"alipay","os":"android","deviceModel":"Pixel 8 Pro"}'`,
+            `set_app_profile --payload '{"enabled":false}'`,
+        ],
+    },
     {
         name: 'set_timezone',
         description: '覆盖目标 tab 的时区，传空字符串恢复浏览器默认时区',
@@ -894,7 +972,7 @@ export const COMMANDS = [
             },
         ],
         examples: [
-            `run_actions --payload '{"actions":[{"action":"page_scroll","data":{"direction":"down"}},{"action":"page_wait","data":{"time":500}},{"action":"page_screenshot"}]}'`,
+            `run_actions --payload '{"tabId":12345,"actions":[{"action":"page_scroll","data":{"direction":"down"}},{"action":"page_wait","data":{"time":500}},{"action":"page_screenshot"}]}'`,
         ],
     },
 ];

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

@@ -108,6 +108,8 @@ export interface SendMtopRequestParams {
     appKey?: string;
     env?: string;
     timeout?: number;
+    headers?: Record<string, string>;
+    ttid?: string;
 }
 export interface TdbankAccountParams {
     operation?: 'current' | 'list' | 'switch' | 'borrow';
@@ -285,6 +287,36 @@ export interface TabOpenParams {
     restoreFocusOnClose?: boolean;
     emulation?: BrowserEmulationOptions;
     group?: string;
+    /**
+     * 客户端容器模拟档案名（如 'fliggy'）。打开后即按该 App 的 WebView 环境渲染：
+     * 移动视口 + 容器 UA + JSBridge 托管 + 自适应系统标题栏。系统栏由 iframe 外层统一渲染，
+     * 并根据页面协议与桥调用切换普通、沉浸或隐藏状态。可用档案见 APP_PROFILE_NAMES。
+     */
+    appProfile?: AppProfileName;
+}
+/**
+ * 客户端容器模拟可用档案名。
+ *
+ * 档案数据（UA / 桥对象 / 方法映射）在 @mearl/app-profiles 维护，但名单属于协议：
+ * 它是 set_app_profile.profile 与 tab_open.appProfile 的取值域，CLI 帮助与 MCP 工具
+ * schema 的 enum 也由它生成。app-profiles 反向引用本清单约束自己的档案表，
+ * 因此新增档案时只需改两处（名单 + 档案数据），且漏改会在类型检查时暴露。
+ */
+export declare const APP_PROFILE_NAMES: readonly ["fliggy", "taobao", "wechat", "tmall", "alipay", "koubei", "taobao-tj", "taobao-live", "xianyu", "etao", "eleme", "damai", "btrip", "amap", "qianwen", "lingyou", "didi", "easybike"];
+export type AppProfileName = (typeof APP_PROFILE_NAMES)[number];
+export interface SetAppProfileParams {
+    tabId?: number;
+    /** false 时清除该 tab 的容器模拟并刷新 */
+    enabled: boolean;
+    /** 容器档案名（enabled=true 时必填） */
+    profile?: AppProfileName;
+    os?: 'ios' | 'android';
+    appVersion?: string;
+    deviceModel?: string;
+    /** 覆盖档案推荐的设备模拟参数（视口/UA 默认取档案值） */
+    emulation?: BrowserEmulationOptions;
+    /** 默认 true：应用/清除后刷新页面使注入生效 */
+    reload?: boolean;
 }
 export interface TabCloseParams {
     tabId: number;
@@ -619,6 +651,10 @@ export interface BrowserActionMap {
         request: SetDeviceEmulationParams;
         response: unknown;
     };
+    set_app_profile: {
+        request: SetAppProfileParams;
+        response: unknown;
+    };
     set_timezone: {
         request: SetTimezoneParams;
         response: SetTimezoneResult;
@@ -696,6 +732,7 @@ export declare const BROWSER_ACTIONS: {
     readonly page_upload: true;
     readonly page_frames: true;
     readonly set_device_emulation: true;
+    readonly set_app_profile: true;
     readonly set_timezone: true;
     readonly get_cookie: true;
     readonly set_cookie: true;
@@ -741,6 +778,7 @@ export declare const BROWSER_COMMAND_ACTIONS: {
     readonly page_upload: true;
     readonly page_frames: true;
     readonly set_device_emulation: true;
+    readonly set_app_profile: true;
     readonly set_timezone: true;
     readonly get_cookie: true;
     readonly set_cookie: true;
@@ -783,6 +821,7 @@ export declare const EXTENSION_BROWSER_ACTIONS: {
     readonly page_upload: true;
     readonly page_frames: true;
     readonly set_device_emulation: true;
+    readonly set_app_profile: true;
     readonly set_timezone: true;
     readonly get_cookie: true;
     readonly set_cookie: true;

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

@@ -6,6 +6,34 @@ export const SEND_REQUEST_MAX_TOTAL_FILE_BYTES = 40 * 1024 * 1024;
 // Base64 expands by 4/3; 7 MiB leaves roughly 680 KiB for JSON framing under
 // the 10 MiB cloud message limit.
 export const SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES = 7 * 1024 * 1024;
+/**
+ * 客户端容器模拟可用档案名。
+ *
+ * 档案数据（UA / 桥对象 / 方法映射）在 @mearl/app-profiles 维护，但名单属于协议：
+ * 它是 set_app_profile.profile 与 tab_open.appProfile 的取值域，CLI 帮助与 MCP 工具
+ * schema 的 enum 也由它生成。app-profiles 反向引用本清单约束自己的档案表，
+ * 因此新增档案时只需改两处（名单 + 档案数据），且漏改会在类型检查时暴露。
+ */
+export const APP_PROFILE_NAMES = [
+    'fliggy',
+    'taobao',
+    'wechat',
+    'tmall',
+    'alipay',
+    'koubei',
+    'taobao-tj',
+    'taobao-live',
+    'xianyu',
+    'etao',
+    'eleme',
+    'damai',
+    'btrip',
+    'amap',
+    'qianwen',
+    'lingyou',
+    'didi',
+    'easybike',
+];
 export const PAGE_ACT_ACTIONS = [
     'page_click',
     'page_drag',
@@ -53,6 +81,7 @@ export const BROWSER_ACTIONS = {
     page_upload: true,
     page_frames: true,
     set_device_emulation: true,
+    set_app_profile: true,
     set_timezone: true,
     get_cookie: true,
     set_cookie: true,
@@ -98,6 +127,7 @@ export const BROWSER_COMMAND_ACTIONS = {
     page_upload: true,
     page_frames: true,
     set_device_emulation: true,
+    set_app_profile: true,
     set_timezone: true,
     get_cookie: true,
     set_cookie: true,
@@ -140,6 +170,7 @@ export const EXTENSION_BROWSER_ACTIONS = {
     page_upload: true,
     page_frames: true,
     set_device_emulation: true,
+    set_app_profile: true,
     set_timezone: true,
     get_cookie: true,
     set_cookie: true,

package/dist/index.d.ts

@@ -6,8 +6,8 @@
  */
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, listCloudConnectors, } from './unified.js';
 export type { UnifiedClientOptions, UnifiedInvokeOptions, UnifiedInvokeOptions as InvokeOptions, } from './unified.js';
-export { BROWSER_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
-export type { ActionStep, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserLaunchParams, BrowserListResult, BrowserReleaseFailure, BrowserReleaseResult, BrowserSource, BrowserStatus, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetApiSchemaParams, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, GetUserInfoParams, ManagedBrowserAccount, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSelectedElementParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RecordParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, TdbankAccountParams, } from './generated-browser-action-protocol.js';
+export { APP_PROFILE_NAMES, BROWSER_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
+export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserLaunchParams, BrowserListResult, BrowserReleaseFailure, BrowserReleaseResult, BrowserSource, BrowserStatus, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetApiSchemaParams, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, GetUserInfoParams, ManagedBrowserAccount, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSelectedElementParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RecordParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, TdbankAccountParams, } from './generated-browser-action-protocol.js';
 import { type UnifiedInvokeOptions } from './unified.js';
 import type * as Protocol from './generated-browser-action-protocol.js';
 export declare function tabCheckpoint(params?: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;
@@ -47,6 +47,7 @@ export declare function pageNavigate(params: Protocol.PageNavigateParams, option
 export declare function pageUpload(params: Protocol.PageUploadParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_upload'>>;
 export declare function pageFrames(params: Protocol.PageFramesParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'page_frames'>>;
 export declare function setDeviceEmulation(params: Protocol.SetDeviceEmulationParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'set_device_emulation'>>;
+export declare function setAppProfile(params: Protocol.SetAppProfileParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'set_app_profile'>>;
 export declare function setTimezone(params: Protocol.SetTimezoneParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'set_timezone'>>;
 export declare function getCookie(params: Protocol.GetCookieParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'get_cookie'>>;
 export declare function setCookie(params: Protocol.SetCookieParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'set_cookie'>>;

package/dist/index.js

@@ -5,7 +5,7 @@
  * then routes actions using the global browser ids returned by browser_list.
  */
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, listCloudConnectors, } from './unified.js';
-export { BROWSER_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
+export { APP_PROFILE_NAMES, BROWSER_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
 import { invoke } from './unified.js';
 export function tabCheckpoint(params = {}, options) {
     return invoke('tab_checkpoint', params, options);
@@ -116,6 +116,9 @@ export function pageFrames(params, options) {
 export function setDeviceEmulation(params, options) {
     return invoke('set_device_emulation', params, options);
 }
+export function setAppProfile(params, options) {
+    return invoke('set_app_profile', params, options);
+}
 export function setTimezone(params, options) {
     return invoke('set_timezone', params, options);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.7.3",
+  "version": "2.8.1",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -51,7 +51,7 @@
   "dependencies": {
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.7.3"
+    "@mearl/cloud-types": "2.8.1"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",