@mearl/client 2.0.0

package/dist/commands.js

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