@mearl/client 2.1.0 → 2.2.0

package/dist/commands.d.ts

@@ -1,3 +1,4 @@
+import type { BrowserCommandAction } from './generated-browser-action-protocol.js';
 export interface ParamDef {
     name: string;
     type: string;
@@ -5,7 +6,7 @@ export interface ParamDef {
     description: string;
 }
 export interface CommandDef {
-    name: string;
+    name: BrowserCommandAction;
     description: string;
     /** payload 字段说明 */
     params?: ParamDef[];
@@ -13,6 +14,891 @@ export interface CommandDef {
     outputFlag?: boolean;
     examples?: string[];
 }
-export declare const COMMANDS: CommandDef[];
-export type KnownAction = 'get_requests' | 'get_logs' | 'get_events' | 'get_api_schema' | 'set_mock' | 'get_mocks' | 'set_rule' | 'get_rules' | 'send_request' | 'send_mtop_request' | 'tab_open' | 'tab_close' | 'tab_list' | 'page_click' | 'page_type' | 'page_hover' | 'page_scroll' | 'page_eval' | 'page_press' | 'page_wait' | 'page_navigate' | 'page_upload' | 'page_snapshot' | 'page_screenshot' | 'page_selected_element' | 'page_frames' | 'set_device_emulation' | 'set_timezone' | 'get_cookie' | 'set_cookie' | 'record_start' | 'record_stop' | 'request_domain_permission' | 'get_user_info' | 'browser_list' | 'browser_release' | 'browser_launch' | 'browser_close' | 'run_actions';
-export declare const COMMAND_MAP: Map<string, CommandDef>;
+export declare const COMMANDS: readonly [{
+    readonly name: "get_requests";
+    readonly description: "获取最近的网络请求（mtop 或普通 xhr/fetch）";
+    readonly params: [{
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly description: "目标标签页 ID，从 tab_list 获取";
+    }, {
+        readonly name: "count";
+        readonly type: "number";
+        readonly description: "返回条数，默认 10";
+    }, {
+        readonly name: "source";
+        readonly type: "\"mtop\" | \"requests\"";
+        readonly description: "数据来源，不填时默认 mtop";
+    }, {
+        readonly name: "filter";
+        readonly type: "string";
+        readonly description: "按 URL 或 API 名称过滤，支持正则";
+    }, {
+        readonly name: "includeBody";
+        readonly type: "boolean";
+        readonly description: "是否包含请求/响应体，默认 true";
+    }];
+    readonly examples: ["get_requests --payload '{\"count\":5}'", "get_requests --payload '{\"source\":\"mtop\",\"filter\":\"cart\"}'"];
+}, {
+    readonly name: "get_logs";
+    readonly description: "获取浏览器控制台日志";
+    readonly params: [{
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly description: "目标标签页 ID，从 tab_list 获取";
+    }, {
+        readonly name: "limit";
+        readonly type: "number";
+        readonly description: "返回条数，默认 20";
+    }, {
+        readonly name: "level";
+        readonly type: "string";
+        readonly description: "按日志级别过滤：log/info/warn/error";
+    }, {
+        readonly name: "filter";
+        readonly type: "string";
+        readonly description: "按内容过滤，支持正则";
+    }];
+    readonly examples: ["get_logs --payload '{\"limit\":10,\"level\":\"error\"}'"];
+}, {
+    readonly name: "get_events";
+    readonly description: "获取 RUM/aplus/ARMS 埋点事件";
+    readonly params: [{
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly description: "目标标签页 ID，从 tab_list 获取";
+    }, {
+        readonly name: "source";
+        readonly type: "\"rum\" | \"aplus\" | \"arms\" | \"all\"";
+        readonly description: "数据来源，默认 all";
+    }, {
+        readonly name: "event_type";
+        readonly type: "string";
+        readonly description: "按事件类型过滤，支持正则，如 CLK/PV";
+    }, {
+        readonly name: "filter";
+        readonly type: "string";
+        readonly description: "按 name 或 url 过滤，支持正则";
+    }, {
+        readonly name: "since";
+        readonly type: "number";
+        readonly description: "只返回最近 N 秒内的事件";
+    }, {
+        readonly name: "limit";
+        readonly type: "number";
+        readonly description: "返回条数，默认 20";
+    }, {
+        readonly name: "includeRaw";
+        readonly type: "boolean";
+        readonly description: "返回完整 URL、_raw 和 _context；默认 false";
+    }];
+    readonly examples: ["get_events --payload '{\"source\":\"aplus\",\"event_type\":\"CLK\",\"limit\":10}'", "get_events --payload '{\"filter\":\"order\",\"includeRaw\":true,\"limit\":1}'", "get_events --payload '{\"tabId\":12345,\"source\":\"all\",\"limit\":20}'"];
+}, {
+    readonly name: "get_api_schema";
+    readonly description: "获取 API 接口 schema（出入参定义）";
+    readonly params: [{
+        readonly name: "api";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "API 名称";
+    }, {
+        readonly name: "fields";
+        readonly type: "(\"schema\" | \"hsf\")[]";
+        readonly description: "指定返回内容；不填时返回全部可用内容";
+    }];
+    readonly examples: ["get_api_schema --payload '{\"api\":\"mtop.trade.order.detail\"}'"];
+}, {
+    readonly name: "set_mock";
+    readonly description: "设置 API mock 数据";
+    readonly params: [{
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly description: "目标标签页 ID，从 tab_list 获取";
+    }, {
+        readonly name: "apiName";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "API 名称或正则表达式";
+    }, {
+        readonly name: "mockData";
+        readonly type: "object";
+        readonly description: "完整 mock 响应数据（与 fields 二选一）";
+    }, {
+        readonly name: "fields";
+        readonly type: "array";
+        readonly description: "按字段路径修改真实响应（与 mockData 二选一）";
+    }, {
+        readonly name: "enabled";
+        readonly type: "boolean";
+        readonly description: "是否启用，默认 true。false 时恢复真实数据";
+    }, {
+        readonly name: "duration";
+        readonly type: "number";
+        readonly description: "完整响应时长（毫秒）：mock 的总耗时，绕过真实服务器精确控制";
+    }, {
+        readonly name: "conditions";
+        readonly type: "object";
+        readonly description: "请求 query/body 字段子集匹配；$index 从 0 开始指定调用顺序";
+    }];
+    readonly examples: ["set_mock --payload '{\"apiName\":\"mtop.cart.query\",\"mockData\":{\"ret\":[\"SUCCESS::调用成功\"]}}'", "set_mock --payload-file ./mock-data.json"];
+}, {
+    readonly name: "get_mocks";
+    readonly description: "查看当前生效的 mock 列表";
+    readonly params: [{
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly description: "目标标签页 ID，从 tab_list 获取";
+    }, {
+        readonly name: "apiName";
+        readonly type: "string";
+        readonly description: "按 API 名称或正则表达式过滤";
+    }];
+    readonly examples: ["get_mocks"];
+}, {
+    readonly name: "set_rule";
+    readonly description: "添加 Chrome declarativeNetRequest 规则（重定向/修改请求头/拦截请求）";
+    readonly examples: ["set_rule --payload '{\"rule\":{...}}'"];
+}, {
+    readonly name: "get_rules";
+    readonly description: "查看当前存储的全部请求规则（含 Options 面板配置的）";
+    readonly examples: ["get_rules"];
+}, {
+    readonly name: "send_request";
+    readonly description: "发送 HTTP 请求，自动携带浏览器 Cookie";
+    readonly params: [{
+        readonly name: "url";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "完整目标 URL";
+    }, {
+        readonly name: "method";
+        readonly type: "string";
+        readonly description: "HTTP 方法，默认 GET";
+    }, {
+        readonly name: "headers";
+        readonly type: "object";
+        readonly description: "自定义请求头";
+    }, {
+        readonly name: "params";
+        readonly type: "object";
+        readonly description: "URL 查询参数";
+    }, {
+        readonly name: "body";
+        readonly type: "any";
+        readonly description: "请求体（传对象时自动 JSON 序列化）";
+    }, {
+        readonly name: "withCookies";
+        readonly type: "boolean";
+        readonly description: "是否附加浏览器 Cookie，默认 true";
+    }, {
+        readonly name: "cookieDomain";
+        readonly type: "string";
+        readonly description: "指定 Cookie 域名，不填时从 url 提取";
+    }, {
+        readonly name: "timeout";
+        readonly type: "number";
+        readonly description: "超时毫秒数，默认 30000";
+    }];
+    readonly examples: ["send_request --payload '{\"url\":\"https://api.example.com/data\",\"method\":\"GET\"}'"];
+}, {
+    readonly name: "send_mtop_request";
+    readonly description: "在页面上下文中发起 mtop 请求，自动处理签名和 token";
+    readonly params: [{
+        readonly name: "api";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "mtop API 名称";
+    }, {
+        readonly name: "data";
+        readonly type: "object";
+        readonly description: "请求数据";
+    }, {
+        readonly name: "version";
+        readonly type: "string";
+        readonly description: "API 版本，默认 1.0";
+    }, {
+        readonly name: "method";
+        readonly type: "string";
+        readonly description: "HTTP 方法，默认 GET";
+    }, {
+        readonly name: "env";
+        readonly type: "\"online\" | \"pre\"";
+        readonly description: "请求环境，默认 online";
+    }, {
+        readonly name: "timeout";
+        readonly type: "number";
+        readonly description: "超时毫秒数，默认 10000";
+    }];
+    readonly examples: ["send_mtop_request --payload '{\"api\":\"mtop.trade.order.detail\",\"data\":{\"orderId\":\"123\"}}'"];
+}, {
+    readonly name: "tdbank_account";
+    readonly description: "TDBank 账号操作：获取当前账号、账号列表、切换账号、快速借用并切换账号";
+    readonly params: [{
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly description: "CDP 模式下可指定用于读取 Cookie 的标签页 ID";
+    }, {
+        readonly name: "operation";
+        readonly type: "\"current\" | \"list\" | \"switch\" | \"borrow\"";
+        readonly description: "操作类型，默认 list";
+    }, {
+        readonly name: "refresh";
+        readonly type: "boolean";
+        readonly description: "list 时是否强制刷新账号列表";
+    }, {
+        readonly name: "accountId";
+        readonly type: "string | number";
+        readonly description: "switch 时使用账号列表中的 id";
+    }, {
+        readonly name: "havanaId";
+        readonly type: "string | number";
+        readonly description: "switch 时也可直接指定 havanaId";
+    }, {
+        readonly name: "site";
+        readonly type: "string | number";
+        readonly description: "直接指定 havanaId 时必填";
+    }, {
+        readonly name: "query";
+        readonly type: "string";
+        readonly description: "borrow 时输入要借用的账号 loginId/关键词";
+    }];
+    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: "列出所有浏览器及其连接状态、类型和托管实例信息";
+    readonly examples: ["browser_list"];
+}, {
+    readonly name: "browser_release";
+    readonly description: "按用户明确要求释放调试控制和会话级临时效果（含设备/时区模拟），保留浏览器和全部标签页；不用于普通任务收尾";
+    readonly examples: ["browser_release", "browser_release --browser chrome-a"];
+}, {
+    readonly name: "browser_launch";
+    readonly description: "启动独立 Chrome，可在新实例中通过 TDBank 登录指定账号";
+    readonly params: [{
+        readonly name: "name";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "实例名称，最多 64 个字符";
+    }, {
+        readonly name: "headless";
+        readonly type: "boolean";
+        readonly description: "是否无头运行，默认 true";
+    }, {
+        readonly name: "userAgentMode";
+        readonly type: "\"default\" | \"desktop\"";
+        readonly description: "UA 模式：default 使用 Chrome 默认 UA，desktop 使用匹配本机版本的桌面 UA";
+    }, {
+        readonly name: "persistent";
+        readonly type: "boolean";
+        readonly description: "关闭后是否保留独立 Profile，默认 false";
+    }, {
+        readonly name: "url";
+        readonly type: "string";
+        readonly description: "登录完成后打开的初始页面";
+    }, {
+        readonly name: "executablePath";
+        readonly type: "string";
+        readonly description: "自定义 Chrome 可执行文件路径";
+    }, {
+        readonly name: "accountId";
+        readonly type: "string | number";
+        readonly description: "登录账号列表中的 accountId";
+    }, {
+        readonly name: "havanaId";
+        readonly type: "string | number";
+        readonly description: "直接登录 havanaId；需要同时传 site";
+    }, {
+        readonly name: "site";
+        readonly type: "string | number";
+        readonly description: "havanaId 对应的站点";
+    }, {
+        readonly name: "query";
+        readonly type: "string";
+        readonly description: "搜索、借用并登录匹配的 TDBank 账号";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly description: "CDP 控制浏览器中用于读取 TDBank Cookie 的标签页";
+    }, {
+        readonly name: "copyCookieDomains";
+        readonly type: "string[]";
+        readonly description: "从控制浏览器复制到新实例的 Cookie 域名列表，可与 TDBank 登录组合";
+    }];
+    readonly examples: ["browser_launch --payload '{\"name\":\"account-a\",\"headless\":true,\"accountId\":12345}'", "browser_launch --payload '{\"name\":\"figma\",\"userAgentMode\":\"desktop\",\"copyCookieDomains\":[\"figma.com\"]}'", "browser_launch --payload '{\"name\":\"account-b\",\"query\":\"test_account\",\"url\":\"https://www.taobao.com\"}'", "browser_launch --payload '{\"name\":\"with-cookies\",\"copyCookieDomains\":[\"example.com\",\"sub.example.org\"]}'"];
+}, {
+    readonly name: "browser_close";
+    readonly description: "关闭指定托管浏览器并按策略清理独立 Profile";
+    readonly params: [{
+        readonly name: "browser";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "托管浏览器的 browserId 或名称";
+    }, {
+        readonly name: "deleteProfile";
+        readonly type: "boolean";
+        readonly description: "强制删除持久化 Profile，默认 false";
+    }];
+    readonly examples: ["browser_close --payload '{\"browser\":\"managed:account-a\"}'", "browser_close --payload '{\"browser\":\"account-b\",\"deleteProfile\":true}'"];
+}, {
+    readonly name: "tab_open";
+    readonly description: "打开或按 URL 规则复用 Tab，并等待新页面加载完成";
+    readonly params: [{
+        readonly name: "url";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "要打开的 URL";
+    }, {
+        readonly name: "active";
+        readonly type: "boolean";
+        readonly description: "是否激活新 Tab，默认 false";
+    }, {
+        readonly name: "closeExisting";
+        readonly type: "boolean";
+        readonly description: "打开前先关闭 Agent 受控的已有标签页，默认 false";
+    }, {
+        readonly name: "group";
+        readonly type: "string";
+        readonly description: "把新 Tab 加入指定标题的标签页分组（同名分组存在则加入，否则新建）。仅扩展模式支持";
+    }, {
+        readonly name: "reuse";
+        readonly type: "\"never\" | \"prefer\" | \"require\"";
+        readonly description: "never 始终新开；prefer 优先复用；require 只允许复用。默认 never";
+    }, {
+        readonly name: "match";
+        readonly type: "object";
+        readonly description: "复用匹配规则：urlPattern（支持 *）、ignoreSearch、ignoreHash、onMultiple（error/first）";
+    }, {
+        readonly name: "restoreFocusOnClose";
+        readonly type: "boolean";
+        readonly description: "关闭本次新开的 active Tab 后恢复原活动标签页，默认 false";
+    }, {
+        readonly name: "emulation";
+        readonly type: "object";
+        readonly description: "开 tab 即进入移动端模拟态（首屏即移动态、无需 reload）。字段同 set_device_emulation 去掉 enabled，如 {\"preset\":\"iphone-15-pro\"}";
+    }];
+    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 name: "tab_close";
+    readonly description: "关闭指定标签页";
+    readonly params: [{
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "要关闭的标签页 ID";
+    }];
+    readonly examples: ["tab_close --payload '{\"tabId\":123}'"];
+}, {
+    readonly name: "tab_list";
+    readonly description: "获取当前窗口所有标签页列表";
+    readonly examples: ["tab_list"];
+}, {
+    readonly name: "page_click";
+    readonly description: "点击页面元素，支持 selector / text / point 三种定位方式；auto 在可见页按设备模拟状态使用可信 mouse/touch，隐藏页使用 DOM fallback";
+    readonly params: [{
+        readonly name: "selector";
+        readonly type: "string";
+        readonly description: "原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 @eN ref（必须带 @ 前缀）。不支持 :has-text/:visible 等 Playwright 私有伪类";
+    }, {
+        readonly name: "text";
+        readonly type: "string";
+        readonly description: "按可见文本（accessibility name）定位。需要时配合 role/exact 消歧；多匹配会报错并列出候选";
+    }, {
+        readonly name: "point";
+        readonly type: "{ x: number; y: number }";
+        readonly description: "按视口坐标点击（CSS 像素）。selector/text 都不适用的兜底场景";
+    }, {
+        readonly name: "role";
+        readonly type: "string";
+        readonly description: "配合 text 使用，按 AX role 过滤（如 button、link、heading）";
+    }, {
+        readonly name: "exact";
+        readonly type: "boolean";
+        readonly description: "配合 text 使用，默认 true 精确匹配；false 时按子串匹配";
+    }, {
+        readonly name: "scope";
+        readonly type: "string";
+        readonly description: "配合 text 使用，把文本匹配限制在指定 CSS 元素或 @eN ref 子树内，适合消除重复文案歧义";
+    }, {
+        readonly name: "clickMode";
+        readonly type: "\"auto\" | \"dom\" | \"mouse\" | \"touch\"";
+        readonly description: "点击模式；auto 在可见页按设备模拟状态选择可信 mouse/touch、隐藏页走 DOM，checkbox/radio 校验状态；其他值强制指定派发方式";
+    }, {
+        readonly name: "observe";
+        readonly type: "object | false";
+        readonly description: "观察选项（quietMs/firstChangeTimeoutMs/timeoutMs/navigationGraceMs/navigationTimeoutMs/networkIdleMs/contentReadyAfterMs）；传 false 关闭内置观察，仅执行裸动作";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }];
+    readonly examples: ["page_click --payload '{\"text\":\"提交\"}'", "page_click --payload '{\"text\":\"退款明细\",\"role\":\"button\"}'", "page_click --payload '{\"text\":\"确定\",\"scope\":\"@e12\"}'", "page_click --payload '{\"selector\":\"@e3\"}'", "page_click --payload '{\"selector\":\".submit-btn\"}'", "page_click --payload '{\"selector\":\".gesture-btn\",\"clickMode\":\"touch\"}'", "page_click --payload '{\"point\":{\"x\":336,\"y\":117}}'"];
+}, {
+    readonly name: "page_type";
+    readonly description: "向输入框填写文本，兼容 React 受控组件；默认观察校验提示等异步变化";
+    readonly params: [{
+        readonly name: "selector";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 @eN ref（必须带 @ 前缀）";
+    }, {
+        readonly name: "text";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "要填写的文本";
+    }, {
+        readonly name: "clearFirst";
+        readonly type: "boolean";
+        readonly description: "是否先清空原有内容，默认 true";
+    }, {
+        readonly name: "observe";
+        readonly type: "object | false";
+        readonly description: "观察选项；传 false 关闭内置观察，仅执行裸动作";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }];
+    readonly examples: ["page_type --payload '{\"selector\":\"@e6\",\"text\":\"搜索关键词\"}'"];
+}, {
+    readonly name: "page_hover";
+    readonly description: "将鼠标悬停在元素上，默认观察下拉菜单、提示信息等 hover 后变化";
+    readonly params: [{
+        readonly name: "selector";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 @eN ref（必须带 @ 前缀）";
+    }, {
+        readonly name: "observe";
+        readonly type: "object | false";
+        readonly description: "观察选项；传 false 关闭内置观察，仅执行裸动作";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }];
+    readonly examples: ["page_hover --payload '{\"selector\":\".nav-menu\"}'"];
+}, {
+    readonly name: "page_scroll";
+    readonly description: "滚动页面或指定容器，默认观察懒加载等滚动后变化";
+    readonly params: [{
+        readonly name: "direction";
+        readonly type: "\"up\" | \"down\" | \"top\" | \"bottom\"";
+        readonly required: true;
+        readonly description: "滚动方向";
+    }, {
+        readonly name: "distance";
+        readonly type: "number";
+        readonly description: "滚动距离（px），默认 600";
+    }, {
+        readonly name: "selector";
+        readonly type: "string";
+        readonly description: "目标滚动容器的原生 CSS 选择器，或 page_snapshot 返回的 @eN ref；不传时滚动页面";
+    }, {
+        readonly name: "containerPolicy";
+        readonly type: "\"self\" | \"nearest\"";
+        readonly description: "默认 self，要求 selector 本身可滚动；nearest 会在其不可滚动时使用最近的可滚动祖先";
+    }, {
+        readonly name: "observe";
+        readonly type: "object | false";
+        readonly description: "观察选项；传 false 关闭内置观察，仅执行裸动作";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }];
+    readonly examples: ["page_scroll --payload '{\"direction\":\"down\"}'", "page_scroll --payload '{\"direction\":\"bottom\"}'", "page_scroll --payload '{\"selector\":\".virtual-list\",\"direction\":\"down\",\"distance\":800}'", "page_scroll --payload '{\"selector\":\"@e8\",\"containerPolicy\":\"nearest\",\"direction\":\"bottom\"}'"];
+}, {
+    readonly name: "page_eval";
+    readonly description: "在页面上下文中执行任意 JavaScript 表达式";
+    readonly params: [{
+        readonly name: "expression";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "要执行的 JS 表达式";
+    }, {
+        readonly name: "awaitPromise";
+        readonly type: "boolean";
+        readonly description: "表达式返回 Promise 时等待完成，默认 true";
+    }, {
+        readonly name: "observe";
+        readonly type: "object";
+        readonly description: "仅在表达式会修改页面且需要观察结果时显式传入；不传保持轻量裸执行";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }];
+    readonly examples: ["page_eval --payload '{\"expression\":\"document.title\"}'"];
+}, {
+    readonly name: "page_press";
+    readonly description: "在页面中按下键盘按键，默认观察提交、关闭弹窗等结果";
+    readonly params: [{
+        readonly name: "key";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "按键名称：Enter/Tab/Escape/Backspace 等";
+    }, {
+        readonly name: "modifiers";
+        readonly type: "string[]";
+        readonly description: "修饰键数组：ctrl/alt/shift/meta/cmd";
+    }, {
+        readonly name: "observe";
+        readonly type: "object | false";
+        readonly description: "观察选项；传 false 关闭内置观察，仅执行裸动作";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }];
+    readonly examples: ["page_press --payload '{\"key\":\"Enter\"}'"];
+}, {
+    readonly name: "page_wait";
+    readonly description: "等待指定时间、元素出现或页面条件成立";
+    readonly params: [{
+        readonly name: "time";
+        readonly type: "number";
+        readonly description: "等待毫秒数（与 selector 二选一）";
+    }, {
+        readonly name: "selector";
+        readonly type: "string";
+        readonly description: "等待元素出现的 CSS 选择器（与 time/condition 三选一）";
+    }, {
+        readonly name: "condition";
+        readonly type: "string";
+        readonly description: "在页面主上下文轮询的 JS 表达式，返回 truthy 时结束";
+    }, {
+        readonly name: "timeout";
+        readonly type: "number";
+        readonly description: "等待超时毫秒数，默认 10000";
+    }, {
+        readonly name: "interval";
+        readonly type: "number";
+        readonly description: "轮询间隔毫秒数，默认 200";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }];
+    readonly examples: ["page_wait --payload '{\"time\":1000}'", "page_wait --payload '{\"selector\":\".loaded\"}'", "page_wait --payload '{\"condition\":\"window.appReady === true\",\"timeout\":30000}'"];
+}, {
+    readonly name: "page_navigate";
+    readonly description: "在当前标签页内导航到 URL、刷新页面，或沿浏览历史后退/前进";
+    readonly params: [{
+        readonly name: "url";
+        readonly type: "string";
+        readonly description: "要导航到的 URL；与 refresh/history 互斥";
+    }, {
+        readonly name: "refresh";
+        readonly type: "boolean";
+        readonly description: "为 true 时直接重新加载当前页面；与 url/history 互斥";
+    }, {
+        readonly name: "history";
+        readonly type: "\"back\" | \"forward\"";
+        readonly description: "沿当前标签页浏览历史后退或前进；与 url/refresh 互斥";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }];
+    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";
+    readonly description: "向 <input type=\"file\"> 元素上传文件，默认观察上传状态变化";
+    readonly params: [{
+        readonly name: "selector";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 @eN ref（必须带 @ 前缀），必须指向 input[type=file]";
+    }, {
+        readonly name: "filePaths";
+        readonly type: "string[]";
+        readonly required: true;
+        readonly description: "本地文件路径数组";
+    }, {
+        readonly name: "observe";
+        readonly type: "object | false";
+        readonly description: "观察选项；传 false 关闭内置观察，仅执行裸动作";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }];
+    readonly examples: ["page_upload --payload '{\"selector\":\"#file-input\",\"filePaths\":[\"/Users/me/photo.jpg\"]}'"];
+}, {
+    readonly name: "page_snapshot";
+    readonly description: "获取页面无障碍树快照，支持完整、交互元素或当前视口范围（含 @ref）";
+    readonly params: [{
+        readonly name: "depth";
+        readonly type: "number";
+        readonly description: "树深度，默认 15，复杂页面可调大";
+    }, {
+        readonly name: "mode";
+        readonly type: "\"full\" | \"interactive\" | \"viewport\"";
+        readonly description: "输出范围，默认 full；interactive 只保留当前视口内的语义控件；长列表优先使用 viewport";
+    }, {
+        readonly name: "rootSelector";
+        readonly type: "string";
+        readonly description: "只获取指定 CSS 元素的 AX 子树，可与 mode 组合；与 rootRef 互斥";
+    }, {
+        readonly name: "rootRef";
+        readonly type: "string";
+        readonly description: "以已有 @eN ref 为根获取局部 AX 子树；与 rootSelector 互斥";
+    }, {
+        readonly name: "ancestorDepth";
+        readonly type: "number";
+        readonly description: "rootRef 向上扩展的 DOM 祖先层数，默认 0，最大 20";
+    }, {
+        readonly name: "query";
+        readonly type: "{ text?: string; role?: string; exact?: boolean }";
+        readonly description: "服务端过滤 AX 树，只保留按 accessibility name / role 命中的节点及祖先路径";
+    }, {
+        readonly name: "maxNodes";
+        readonly type: "number";
+        readonly description: "最多输出节点数，0 表示不限制";
+    }, {
+        readonly name: "maxChars";
+        readonly type: "number";
+        readonly description: "快照文本最大字符数，默认 60000，超出保留首尾；传 0 不限制";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }];
+    readonly examples: ["page_snapshot", "page_snapshot --payload '{\"tabId\":1,\"mode\":\"viewport\"}'", "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";
+    readonly description: "获取当前页面或指定元素截图";
+    readonly outputFlag: true;
+    readonly params: [{
+        readonly name: "selector";
+        readonly type: "string";
+        readonly description: "CSS 选择器，提供后只截取该元素区域";
+    }, {
+        readonly name: "format";
+        readonly type: "\"png\" | \"jpeg\"";
+        readonly description: "图片格式，默认 png";
+    }, {
+        readonly name: "quality";
+        readonly type: "number";
+        readonly description: "JPEG 压缩质量（0-100），默认 80";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }];
+    readonly examples: ["page_screenshot --output ./screenshot.png", "page_screenshot --payload '{\"selector\":\".product-card\"}' --output ./card.png"];
+}, {
+    readonly name: "page_selected_element";
+    readonly description: "获取 DevTools Elements 面板当前选中元素的详细信息";
+    readonly outputFlag: true;
+    readonly params: [{
+        readonly name: "includeOuterHTML";
+        readonly type: "boolean";
+        readonly description: "是否返回 outerHTML（最多 3000 字符），默认 true";
+    }, {
+        readonly name: "includeScreenshot";
+        readonly type: "boolean";
+        readonly description: "是否附带元素截图，默认 false；指定 --output 时自动开启";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }];
+    readonly examples: ["page_selected_element", "page_selected_element --output ./element.png"];
+}, {
+    readonly name: "get_user_info";
+    readonly description: "获取当前登录用户的信息";
+    readonly params: [{
+        readonly name: "detail";
+        readonly type: "boolean";
+        readonly description: "是否获取完整用户信息，默认 false（只返回工号）";
+    }];
+    readonly examples: ["get_user_info", "get_user_info --payload '{\"detail\":true}'"];
+}, {
+    readonly name: "record_start";
+    readonly description: "开始录制用户操作";
+    readonly params: [{
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly description: "目标标签页 ID，从 tab_list 获取";
+    }];
+    readonly examples: ["record_start"];
+}, {
+    readonly name: "record_stop";
+    readonly description: "停止录制并返回完整结果（操作 + 关联请求）；未在录制时不报错，返回 wasRecording: false";
+    readonly params: [{
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly description: "目标标签页 ID，从 tab_list 获取";
+    }];
+    readonly examples: ["record_stop"];
+}, {
+    readonly name: "set_device_emulation";
+    readonly description: "把目标 tab 切换为移动端模拟（视口/UA/触摸），等价 DevTools 设备工具栏，作用域 per-tab；需保持调试控制才持续生效";
+    readonly params: [{
+        readonly name: "enabled";
+        readonly type: "boolean";
+        readonly required: true;
+        readonly description: "true=启用，false=清除";
+    }, {
+        readonly name: "preset";
+        readonly type: "\"iphone-15-pro\" | \"iphone-se\" | \"pixel-8\" | \"ipad-mini\" | \"galaxy-s23\"";
+        readonly description: "内置设备预设，提供 width/height/DPR/UA 默认值";
+    }, {
+        readonly name: "width";
+        readonly type: "number";
+        readonly description: "视口宽度（覆盖 preset）";
+    }, {
+        readonly name: "height";
+        readonly type: "number";
+        readonly description: "视口高度（覆盖 preset）";
+    }, {
+        readonly name: "deviceScaleFactor";
+        readonly type: "number";
+        readonly description: "DPR（覆盖 preset）";
+    }, {
+        readonly name: "mobile";
+        readonly type: "boolean";
+        readonly description: "是否走移动渲染模式，默认从 preset 推断";
+    }, {
+        readonly name: "userAgent";
+        readonly type: "string";
+        readonly description: "自定义 UA（覆盖 preset）";
+    }, {
+        readonly name: "orientation";
+        readonly type: "\"portrait\" | \"landscape\"";
+        readonly description: "横竖屏，默认 portrait";
+    }, {
+        readonly name: "touch";
+        readonly type: "boolean";
+        readonly description: "是否启用触摸事件，默认 mobile 为真时启用";
+    }, {
+        readonly name: "reload";
+        readonly type: "boolean";
+        readonly description: "启用后是否重载页面，默认 true";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        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_timezone";
+    readonly description: "覆盖目标 tab 的时区，传空字符串恢复浏览器默认时区";
+    readonly params: [{
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }, {
+        readonly name: "timezone";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "IANA 时区标识（如 Asia/Shanghai）；空字符串表示清除覆盖";
+    }];
+    readonly examples: ["set_timezone --payload '{\"tabId\":12345,\"timezone\":\"America/New_York\"}'", "set_timezone --payload '{\"tabId\":12345,\"timezone\":\"\"}'"];
+}, {
+    readonly name: "get_cookie";
+    readonly description: "读取当前标签页的一个指定非分区 Cookie；拒绝返回 HttpOnly Cookie";
+    readonly params: [{
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }, {
+        readonly name: "name";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "要读取的 Cookie 名称；不支持列举全部 Cookie";
+    }, {
+        readonly name: "domain";
+        readonly type: "string";
+        readonly description: "可选精确域过滤，只允许当前 host 或其父域";
+    }, {
+        readonly name: "path";
+        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\"}'"];
+}, {
+    readonly name: "set_cookie";
+    readonly description: "设置当前标签页域下的一个指定非分区 session Cookie，可选刷新页面";
+    readonly params: [{
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }, {
+        readonly name: "name";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "Cookie 名称";
+    }, {
+        readonly name: "value";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "Cookie 值，可传空字符串；空字符串不会删除 Cookie";
+    }, {
+        readonly name: "domain";
+        readonly type: "string";
+        readonly description: "Cookie 域，默认当前 host；只允许当前 host 或其父域";
+    }, {
+        readonly name: "path";
+        readonly type: "string";
+        readonly description: "Cookie path，默认 /";
+    }, {
+        readonly name: "reload";
+        readonly type: "boolean";
+        readonly description: "设置后是否刷新页面，默认 false";
+    }];
+    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 name: "page_frames";
+    readonly description: "获取页面所有 iframe 列表";
+    readonly params: [{
+        readonly name: "tabId";
+        readonly type: "number";
+        readonly required: true;
+        readonly description: "目标标签页 ID";
+    }];
+    readonly examples: ["page_frames --payload '{\"tabId\":12345}'"];
+}, {
+    readonly name: "request_domain_permission";
+    readonly description: "申请访问指定域名的权限（弹窗让用户授权）";
+    readonly params: [{
+        readonly name: "domain";
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "需要授权的域名，如 example.com";
+    }];
+    readonly examples: ["request_domain_permission --payload '{\"domain\":\"example.com\"}'"];
+}, {
+    readonly name: "run_actions";
+    readonly description: "批量顺序执行多个 action，减少往返延迟。遇错即停，返回已完成步骤结果；步骤内的页面动作不带内置观察";
+    readonly params: [{
+        readonly name: "actions";
+        readonly type: "Array<{action: string, data?: object}>";
+        readonly required: true;
+        readonly description: "要依次执行的 action 列表";
+    }, {
+        readonly name: "tabId";
+        readonly type: "number";
+        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\"}]}'"];
+}];
+export declare const COMMAND_MAP: ReadonlyMap<string, CommandDef>;