@mearl/client 2.1.0 → 2.2.1

package/README.md

@@ -40,6 +40,9 @@ mearl get_requests --payload '{"count":5}'
 # 代理一个 HTTP 请求
 mearl send_request --payload '{"url":"https://api.example.com","method":"GET"}'
 
+# 以 multipart/form-data 上传本地文件
+mearl send_request --payload '{"url":"https://api.example.com/upload","method":"POST","formData":{"folder":"assets"},"files":[{"fieldName":"file","filePath":"/absolute/path/image.png"}]}'
+
 # 截图并保存
 mearl page_screenshot --output ./screenshot.png
 
@@ -88,7 +91,7 @@ mearl browser_release
 | TDBank      | `tdbank_account`                                                                                          |
 | 浏览器      | `browser_list` `browser_release` `browser_launch` `browser_close`                                         |
 
-页面交互动作（`page_click` / `page_type` / `page_hover` / `page_scroll` / `page_press` / `page_upload`）默认内置观察：同一次调用内执行动作并等待异步稳定，返回 `{ action, observation }`；传 `observe: false` 可关闭观察仅执行裸动作。观察结果不替代完整页面理解：`mode: "delta"` 只返回主文档中的 `effects.notifications`、`effects.interactives` 和 `effects.focus` 等高置信度信号，并明确携带 `scope: "main-document"`；可交互节点会尽量携带真实 backend `node.ref`，后续动作优先使用 ref，缺少 ref 时使用 `node.selector`。`mode: "navigation"` 且 `ready: true` 时，页面已通过网络静默、骨架状态或保守的内容稳定判定，可在新页面重建快照。通常仅在 `fullSnapshotRecommended` 为 true 时根据 `snapshotReasons` 回退；滚动后若下一步需要读取新视口内容，可按需获取 viewport 快照。`page_eval` 默认裸执行，只有显式传入 `observe` 对象时才启用观察。
+页面交互动作（`page_click` / `page_type` / `page_hover` / `page_scroll` / `page_press` / `page_upload`）默认内置观察：同一次调用内执行动作并等待异步稳定，返回 `{ action, observation }`；传 `observe: false` 可关闭观察仅执行裸动作。观察结果不替代完整页面理解：`mode: "delta"` 只返回主文档中的 `effects.notifications`、`effects.interactives` 和 `effects.focus` 等高置信度信号，并明确携带 `scope: "main-document"`；可交互节点会尽量携带真实 backend `node.ref`，后续动作优先使用 ref，缺少 ref 时使用 `node.selector`。`mode: "navigation"` 且 `ready: true` 时，页面已通过网络静默、骨架状态或保守的内容稳定判定，可在新页面重建快照。动作直接打开新标签页时，`observation.openedTabs` 返回新标签页的 `tabId`、URL、标题和加载状态，可直接把该 `tabId` 用于后续操作，不必调用 `tab_list`。通常仅在 `fullSnapshotRecommended` 为 true 时根据 `snapshotReasons` 回退；滚动后若下一步需要读取新视口内容，可按需获取 viewport 快照。`page_eval` 默认裸执行，只有显式传入 `observe` 对象时才启用观察。
 
 `page_snapshot` 默认返回完整 AX Tree；长列表可传 `mode: "viewport"`，只需要当前视口内的控件时传 `mode: "interactive"`，已知 CSS 区域时传 `rootSelector`，已有 ref 时传 `rootRef`（可用 `ancestorDepth` 向上补充上下文），只查找特定文案或角色时传 `query`。视口内缺少 AX 控件语义时，`interactive` 会自动回退到 viewport，并返回 `fallbackMode: "viewport"`。`maxNodes` / `maxChars` 截断会同时保留首尾内容。
 
@@ -96,7 +99,7 @@ mearl browser_release
 
 `browser_list` 统一列出普通浏览器和托管浏览器。`type` 区分 `regular` / `managed`，`status` 区分 `connected` / `running_disconnected` / `stopped`；只有 `connected` 的浏览器可作为操作目标。
 
-`browser_release` 释放当前目标浏览器的 debugger/CDP 控制和会话级临时状态，保留浏览器及全部标签页；后续浏览器操作可自动重新建立控制。
+`browser_release` 仅在用户明确要求结束调试、退出接管或清理会话资源时使用，不作为普通任务收尾。它会释放当前目标浏览器的 debugger/CDP 控制和会话级临时状态（包括设备/时区模拟），保留浏览器及全部标签页；后续浏览器操作可自动重新建立控制。
 
 托管浏览器使用独立 Profile 和动态 CDP 端口。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，新实例可以使用 `headless: true`（默认）完成测试账号登录。`copyCookieDomains` 可把控制浏览器指定域的 Cookie 复制到新实例，Cookie 值不会出现在命令结果或日志中；`userAgentMode: "desktop"` 可让实例使用匹配本机 Chrome 版本的桌面 UA。完整设计见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
 

package/dist/actionTimeouts.js

@@ -1,19 +1,12 @@
+import { PAGE_ACT_ACTIONS } from './generated-browser-action-protocol.js';
+const SEND_REQUEST_FILE_TRANSFER_TIMEOUT_MS = 120_000;
 function boundedNumber(value, fallback, minimum, maximum) {
     const numeric = Number(value);
     if (!Number.isFinite(numeric))
         return fallback;
     return Math.min(Math.max(numeric, minimum), maximum);
 }
-// 默认内置观察的页面交互动作。client 作为零依赖包本地维护，
-// 需与 browser-core/pageAct.ts 的 PAGE_ACT_ACTIONS 保持一致。
-const OBSERVED_PAGE_ACTIONS = new Set([
-    'page_click',
-    'page_type',
-    'page_hover',
-    'page_scroll',
-    'page_press',
-    'page_upload',
-]);
+const OBSERVED_PAGE_ACTIONS = new Set(PAGE_ACT_ACTIONS);
 export function resolveObservedActionTimeoutSec(data) {
     const observe = data.observe ?? {};
     const observationMs = boundedNumber(observe.timeoutMs, 3000, 500, 30000);
@@ -24,7 +17,10 @@ export function resolveObservedActionTimeoutSec(data) {
 }
 export function resolveActionTimeoutSec(action, data, fallback = 15) {
     if (action === 'send_request') {
-        return Math.max(fallback, Math.ceil(((data.timeout ?? 30000) + 5000) / 1000));
+        const transferTimeoutMs = Array.isArray(data.files) && data.files.length > 0
+            ? SEND_REQUEST_FILE_TRANSFER_TIMEOUT_MS
+            : 0;
+        return Math.max(fallback, Math.ceil(((data.timeout ?? 30000) + transferTimeoutMs + 5000) / 1000));
     }
     if (action === 'send_mtop_request') {
         return Math.max(fallback, Math.ceil(((data.timeout ?? 10000) + 5000) / 1000));
@@ -41,13 +37,23 @@ export function resolveActionTimeoutSec(action, data, fallback = 15) {
         return Math.max(fallback, 90);
     if (action === 'browser_close' || action === 'tdbank_account')
         return Math.max(fallback, 20);
+    if (action === 'run_actions') {
+        const actions = Array.isArray(data.actions) ? data.actions : [{}];
+        const timeoutSec = actions.reduce((total, step) => {
+            const stepAction = String(step?.action ?? '');
+            if (!stepAction || stepAction === 'run_actions')
+                return total + 15;
+            return total + resolveActionTimeoutSec(stepAction, step?.data ?? {}, 15);
+        }, 0);
+        return Math.max(fallback, timeoutSec);
+    }
     // 页面交互动作默认内置观察，超时需覆盖观察与导航窗口；observe:false 时是裸动作，用默认超时
-    if (OBSERVED_PAGE_ACTIONS.has(action) && data.observe !== false) {
+    const observedAction = OBSERVED_PAGE_ACTIONS.has(action);
+    const observationEnabled = action === 'page_eval'
+        ? data.observe !== null && typeof data.observe === 'object' && !Array.isArray(data.observe)
+        : data.observe !== false;
+    if (observedAction && observationEnabled) {
         return Math.max(fallback, resolveObservedActionTimeoutSec(data));
     }
-    if (action === 'run_actions') {
-        const steps = Array.isArray(data.actions) ? data.actions.length : 1;
-        return Math.max(fallback, steps * 15);
-    }
     return fallback;
 }