@mearl/client 2.0.2 → 2.2.0

package/README.md

@@ -58,6 +58,7 @@ mearl browser_launch --payload '{"name":"account-b","query":"test_account"}'
 mearl browser_launch --payload '{"name":"cookie-copy","copyCookieDomains":["example.com"]}'
 mearl browser_launch --payload '{"name":"figma","userAgentMode":"desktop","copyCookieDomains":["figma.com"]}'
 mearl browser_list
+mearl browser_release
 ```
 
 **通用选项：**
@@ -69,6 +70,7 @@ mearl browser_list
 | `--timeout <seconds>`   | 请求超时时间             |
 | `--compact`             | 紧凑输出                 |
 | `--output <path>`       | 将结果写入文件（如截图） |
+| `--browser <id\|名称>`  | 指定目标浏览器           |
 
 ## 支持的操作
 
@@ -80,11 +82,11 @@ mearl browser_list
 | 标签页      | `tab_open` `tab_close` `tab_list`                                                                         |
 | 页面操作    | `page_click` `page_type` `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`                                                                     |
+| 环境与状态  | `set_device_emulation` `set_timezone` `get_cookie` `set_cookie`                                           |
 | 用户信息    | `get_user_info`                                                                                           |
 | 录制        | `record_start` `record_stop`                                                                              |
 | TDBank      | `tdbank_account`                                                                                          |
-| 浏览器      | `browser_list` `browser_launch` `browser_close`                                                           |
+| 浏览器      | `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` 对象时才启用观察。
 
@@ -94,6 +96,8 @@ mearl browser_list
 
 `browser_list` 统一列出普通浏览器和托管浏览器。`type` 区分 `regular` / `managed`，`status` 区分 `connected` / `running_disconnected` / `stopped`；只有 `connected` 的浏览器可作为操作目标。
 
+`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,11 @@
+import { PAGE_ACT_ACTIONS } from './generated-browser-action-protocol.js';
 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);
@@ -35,12 +27,18 @@ export function resolveActionTimeoutSec(action, data, fallback = 15) {
     }
     if (action === 'tab_open')
         return Math.max(fallback, 40);
+    if (action === 'set_cookie' && data.reload === true)
+        return Math.max(fallback, 40);
     if (action === 'browser_launch')
         return Math.max(fallback, 90);
     if (action === 'browser_close' || action === 'tdbank_account')
         return Math.max(fallback, 20);
     // 页面交互动作默认内置观察，超时需覆盖观察与导航窗口；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') {

package/dist/cli.js

@@ -41,13 +41,16 @@ const CATEGORIES = [
         title: '页面感知',
         names: ['page_snapshot', 'page_screenshot', 'page_selected_element', 'page_frames'],
     },
-    { title: '环境模拟', names: ['set_device_emulation', 'set_timezone'] },
+    {
+        title: '环境与 Cookie',
+        names: ['set_device_emulation', 'set_timezone', 'get_cookie', 'set_cookie'],
+    },
     { title: '用户信息', names: ['get_user_info'] },
     { title: '录制', names: ['record_start', 'record_stop'] },
     { title: 'TDBank', names: ['tdbank_account'] },
     {
         title: '浏览器',
-        names: ['browser_list', 'browser_launch', 'browser_close'],
+        names: ['browser_list', 'browser_release', 'browser_launch', 'browser_close'],
     },
 ];
 function printUsage() {