@mearl/client 2.14.0 → 2.15.1

package/README.md

@@ -63,15 +63,10 @@ npx @mearl/setup update --local
 # 查看某个 action 的帮助
 mearl <action> --help
 
-# 启动两个隔离的 headless Chrome，并分别登录不同 TDBank 账号
-mearl browser_launch --payload '{"name":"account-a","accountId":12345}'
-mearl browser_launch --payload '{"name":"account-b","query":"test_account"}'
+# 启动两个隔离的 headless Chrome
+mearl browser_launch --payload '{"name":"browser-a","url":"https://example.com"}'
+mearl browser_launch --payload '{"name":"browser-b","persistent":true}'
 mearl browser_launch --payload '{"name":"cookie-copy","copyCookieDomains":["example.com"]}'
-mearl browser_launch --payload '{"name":"cloud-login","provider":"agentbay","persistent":true,"userAgentMode":"desktop","copyCookieDomains":["example.com"],"url":"https://example.com/account"}'
-mearl browser_launch --browser '<控制浏览器 browserId>' --payload '{"name":"cloud-login","provider":"agentbay","reuse":"require","copyCookieDomains":["example.com"]}'
-mearl browser_launch --browser '<本地来源 browserId>' --payload '{"sessionId":"<其他设备创建的 AgentBay sessionId>","copyCookieDomains":["example.com"]}'
-mearl browser_launch --payload '{"name":"cloud-tools","provider":"agentbay","copyCookieDomains":"mearl-services"}'
-mearl browser_launch --payload '{"name":"cloud-tools-plus","provider":"agentbay","copyCookieDomains":{"presets":["mearl-services"],"domains":["figma.com"]}}'
 mearl browser_launch --payload '{"name":"figma","userAgentMode":"desktop","copyCookieDomains":["figma.com"]}'
 mearl browser_list
 mearl browser_release
@@ -79,16 +74,19 @@ mearl browser_release
 
 ### 外部浏览器 Provider
 
-Provider 浏览器与扩展、CDP 和 AgentBay 浏览器一起出现在 `browser_list` 中，并使用同一个
+Provider 浏览器与扩展、CDP 浏览器一起出现在 `browser_list` 中，并使用同一个
 全局 `browserId` 参与路由。Provider 的安装、更新和卸载由 `@mearl/setup` 管理：
 
 ```bash
 npx @mearl/setup provider install @ali/mearl-provider-brow
+npx @mearl/setup provider install @ali/mearl-provider-agentbay
 
-# 让 Brow 创建一个配对实例；debugId 可省略并自动生成
-mearl browser_launch --payload '{"provider":"brow","providerOptions":{"debugId":"my-device"}}'
+# 查看 Provider 当前版本的能力、参数与使用流程
+mearl brow
+mearl agentbay --help
 
-# 扫码后确认同一个实例已经连接
+# Provider 启动参数统一放在 providerOptions
+mearl browser_launch --payload '{"provider":"brow","providerOptions":{}}'
 mearl browser_list
 
 # 后续操作使用 browser_list 返回的全局 Browser ID
@@ -130,12 +128,13 @@ Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通
 `browser_list --help` 和 `browser_launch --help` 会按场景展示宿主选择参数；连接或传输排障运行
 `mearl check --help`。其中 `--json` 仅用于输出机器可读的检查结果。
 
-## Skill CLI 插件
+## Skill 插件
 
 安装 skill 并自动注册命令，或直接注册已有入口：
 
 ```bash
 npx @mearl/setup plugin install trip/mearl --skill yuque-doc-fetch --yes
+npx @mearl/setup plugin install trip/mearl --skill buc-request --yes
 npx @mearl/setup plugin yuque /absolute/path/to/yuque-doc-fetch
 npx @mearl/setup plugin uninstall yuque
 mearl yuque read "https://aliyuque.antfin.com/group/book/doc"
@@ -146,7 +145,7 @@ mearl yuque --version
 
 目录默认使用 `scripts/main.mjs`。入口默认导出 `register(app)`，可导出简短的 `description`
 显示在 `mearl` 插件列表中，并通过 `app.command(signature, handler, description?)`
-注册动作、`app.invoke(action, payload, options?)` 复用当前浏览器上下文，并用 `app.progress(message)` 报告可选进度。CLI 默认只输出最终结果，传入
+注册动作、`app.invoke(action, payload, options?)` 复用当前浏览器上下文，并用 `app.progress(message)` 报告可选进度。调用另一个插件时，payload 使用 `{ command, input }` envelope；嵌套调用继承宿主选项并拒绝循环依赖。CLI 默认只输出最终结果，传入
 `--verbose` 时才把进度写入 stderr。handler 返回文本或 JSON，宿主统一处理 `--output`、连接和错误。写命令在用户调用后直接执行，业务模块负责目标、状态、幂等和结果校验。
 自动注册默认以 skill 安装目录名作为命令名，也可在入口导出 `name` 指定短名称。
 setup 会补齐缺失或低于自身版本的 client、native-host；安装参数透传给 Ali Skills，并固定全局共享安装。
@@ -158,19 +157,38 @@ setup 会补齐缺失或低于自身版本的 client、native-host；安装参
 插件接受位置参数或包含 command/input 的 `--payload`，两种形式不能混用。JSON 保留业务字段类型；正文等文件输入
 按具体 skill 的字段约定处理。插件不使用上表中内置 action 的 `--payload-file` 入口。
 
+注册后的插件也可从 SDK 调用；实例方法 `client.invokePlugin` 复用既有连接和默认浏览器：
+
+```typescript
+import { invokePlugin } from '@mearl/client';
+
+const result = await invokePlugin(
+  'yuque',
+  { command: 'read', input: { url: 'https://aliyuque.antfin.com/group/book/doc' } },
+  { browser: 'work' },
+);
+```
+
+MCP Server 通过固定工具 `mearl_plugin` 接受同样的 `plugin`、`command` 和 `input`，不会把插件子命令动态扩展成 MCP 工具。SDK 与 MCP 不接受任意入口路径；调用官方目录中尚未注册的插件时，会通过匹配当前 client 版本的 setup 自动安装并重试一次。未知名称仍返回 `PLUGIN_NOT_REGISTERED`。
+
 注册记录在 `~/.mearl/plugins/<name>.json`，保存入口路径和可选的简短描述；skill 业务代码原地更新直接生效，换路径或更新描述后重新注册。
 `plugin uninstall <name>` 会对 `~/.agents/skills` 中的全局 Skill 调用 `ali-skills remove --global --yes`，
 成功后清除相关注册；即使入口目录已被手动删除，也会完成 Ali Skills 跟踪记录的清理。
 手工路径只解除注册并保留源码。
 `PLUGIN_NOT_REGISTERED` 表示插件尚未注册。`PLUGIN_ENTRY_MISSING` 会显示失效入口，并给出带有实际插件名的
 卸载清理命令。其他错误按实际原因处理。
-编写规范见 [Mearl Skill Creator 的 CLI 插件规范](../skills/mearl-skill-creator/references/cli-plugin.md)。
+编写规范见 [Mearl Skill Creator 的 Skill 插件规范](../skills/mearl-skill-creator/references/cli-plugin.md)。
+
+需要 BUC 身份的内部 HTTP 接口通过官方 `buc` 插件调用。CLI 使用 `mearl buc request`，业务插件使用
+`app.invoke('buc', { command: 'request', input })`；当前身份和人员资料分别使用 `whoami` 与 `profile`
+子命令。BUC 插件按请求创建一次性凭据，只允许访问 HTTPS `alibaba-inc.com` 域名，过滤认证字段与
+Cookie，并始终在运行 CLI、SDK 或 MCP Server 的机器上执行，不随浏览器或 connector 转发。
 
 ## 支持的操作
 
 | 分类          | Actions                                                                                                                              |
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| API 调试      | `tab_checkpoint` `get_requests` `get_logs` `get_events` `get_api_schema`                                                             |
+| API 调试      | `tab_checkpoint` `get_requests` `get_logs` `get_events`                                                                              |
 | Mock & 规则   | `set_mock` `get_mocks` `set_rule` `get_rules`                                                                                        |
 | 网络请求      | `send_request` `send_mtop_request` `request_domain_permission`                                                                       |
 | 标签页        | `tab_open` `tab_close` `tab_list`                                                                                                    |
@@ -178,9 +196,7 @@ setup 会补齐缺失或低于自身版本的 client、native-host；安装参
 | 组合调用      | `run_actions`                                                                                                                        |
 | 页面感知      | `page_snapshot` `page_screenshot` `page_selected_element` `page_frames`                                                              |
 | 环境与 Cookie | `set_device_emulation` `set_app_profile` `set_timezone` `get_cookie` `set_cookie`                                                     |
-| 用户信息      | `get_user_info`                                                                                                                      |
 | 录制          | `record_start` `record_stop`                                                                                                         |
-| TDBank        | `tdbank_account`                                                                                                                     |
 | 浏览器        | `browser_list` `browser_release` `browser_launch` `browser_close`                                                                    |
 
 页面交互动作（`page_click` / `page_drag` / `page_type` / `page_hover` / `page_scroll` / `page_press` / `page_upload`）默认等待异步稳定并返回 `{ action, observation }`。参数、ref 或目标解析在派发前失败时返回 `action.stage: "precondition"`，省略无意义的 `observation` / `diagnostics`，CLI 退出码为 1。传 `observe: false` 可执行裸动作；需要同一动作期间的新增 error logs 和业务 requests 时传 `diagnostics: true`，埋点通过 `diagnostics.events` 按需开启。`page_eval` 默认裸执行，可按需开启观察或诊断。
@@ -193,9 +209,11 @@ setup 会补齐缺失或低于自身版本的 client、native-host；安装参
 `regular` / `managed`，`status` 区分 `connected` / `pairing` / `running_disconnected` /
 `stopped`；只有 `connected` 的浏览器可作为常规操作目标。
 
-按 `sessionId` 接入的 AgentBay 浏览器用 `browser_release` 收尾：它会移除本机 attachment 并退出对应宿主，但不会关闭云端 Session。其他浏览器仅在用户明确要求结束调试、退出接管或清理会话资源时调用；它会释放 debugger/CDP 控制和会话级临时状态（包括设备/时区模拟），保留浏览器及全部标签页，后续浏览器操作可自动重新建立控制。
-
-托管浏览器使用独立 Profile。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，本地实例可以使用 `headless: true`（默认）完成测试账号登录。AgentBay 固定为非 headless，传 `headless: true` 会被拒绝；`imageId` 可指定镜像别名或具体镜像 ID，省略时使用已验证的 Linux Browser Use 内网镜像。`persistent: true` 会让本地实例保留 Profile，让 AgentBay 同名实例绑定稳定的云端 Browser Context；正常关闭时同步 Cookie、LocalStorage、IndexedDB 等状态，下次启动无需再次复制本地登录态。`deleteProfile: true` 会显式删除对应 Profile 或 Context。AgentBay 的 `reuse` 支持 `never`（默认）、`prefer` 和 `require`：`prefer` 存在运行实例时复用、否则创建，`require` 只复用且不会意外创建计费会话。另一台设备已知确切 Session 时，可传 `sessionId` 直接通过 AgentBay CDP 接入，不需要 cloud-server；当前设备需配置能访问该 Session 的 `AGENTBAY_KEY`。provider-local ID 为 `managed:agentbay:session:<sessionId>`，跨 CLI 调用使用启动响应中的全局 `browserId`，且本机只持有 attachment。`copyCookieDomains` 传数组时复制指定域，传 `"mearl-services"` 时同步 Mearl 依赖平台登录态；需要同时复制基础登录态和额外站点时传 `{ "presets": ["mearl-services"], "domains": [...] }`。Cookie 值不会经过 cloud-server，也不会出现在命令结果或日志中；`userAgentMode: "desktop"` 让本地实例使用匹配本机 Chrome 版本的桌面 UA，AgentBay 则复用当前控制浏览器的桌面 UA。`browser_list` 仅返回浏览器的稳定配置，不携带 AgentBay 串流入口或沙箱 noVNC 地址。需要时显式运行 `mearl check --browser <id|名称>`，由统一的浏览器访问入口能力实时返回 `browserAccess`；AgentBay、OpenSandbox 和 AONE Sandbox 地址都应按敏感信息处理。完整设计见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
+`browser_release` 仅在用户明确要求结束调试、退出接管或清理会话资源时调用；它会释放
+debugger/CDP 控制和会话级临时状态，保留浏览器及全部标签页。托管实例的启动、关闭、持久化、
+接入和登录态同步语义由各 Provider 声明；运行 `mearl <providerId>` 获取当前说明。访问入口不在
+`browser_list` 中，需要时显式运行 `mearl check --browser <id|名称>`，并把返回的
+`browserAccess.url` 按敏感信息处理。
 
 ## 架构
 

package/dist/actionTimeouts.js

@@ -1,8 +1,8 @@
 import { PAGE_ACT_ACTIONS } from './generated-browser-action-protocol.js';
 const SEND_REQUEST_FILE_TRANSFER_TIMEOUT_MS = 120_000;
-// AgentBay staging can spend up to 60s transferring bytes and then 120s syncing the session disk.
+// Remote Providers may stage files before forwarding a page upload.
 const PAGE_UPLOAD_FILE_TRANSFER_TIMEOUT_MS = 180_000;
-// AgentBay context sync can poll for about 12 minutes before session deletion waits up to 5 more.
+// Persistent Providers may need to synchronize remote state before closing an instance.
 const BROWSER_CLOSE_TIMEOUT_SEC = 18 * 60;
 function boundedNumber(value, fallback, minimum, maximum) {
     const numeric = Number(value);
@@ -41,8 +41,6 @@ export function resolveActionTimeoutSec(action, data, fallback = 15) {
         return Math.max(fallback, 90);
     if (action === 'browser_close')
         return Math.max(fallback, BROWSER_CLOSE_TIMEOUT_SEC);
-    if (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) => {

package/dist/check.d.ts

@@ -15,8 +15,6 @@ export interface ProviderVersionInfo {
     protocolVersion: number;
 }
 export type BrowserAccessCapability = {
-    kind: 'agentbay';
-} | {
     kind: 'sandbox-novnc';
     environment: 'opensandbox' | 'aone';
     port: number;

package/dist/check.js

@@ -3,8 +3,6 @@ function formatError(error) {
     return error instanceof Error ? error.message : String(error);
 }
 function browserAccessLabel(access) {
-    if (access.kind === 'agentbay')
-        return 'AgentBay, temporary';
     if (access.kind === 'sandbox-novnc' && 'environment' in access) {
         return access.environment === 'opensandbox' ? 'OpenSandbox noVNC' : 'AONE Sandbox noVNC';
     }

package/dist/cli.js

@@ -8,13 +8,13 @@ import { commandInput, findCommandSuggestions, formatCommandSuggestions, } from
 import { COMMANDS, COMMAND_MAP } from './commands.js';
 import { CLIENT_VERSION } from './socket.js';
 import { UnifiedClient } from './unified.js';
-import { findPluginEntry, findPluginRegistration, listPluginNames, loadPlugin, PluginError, } from './plugin.js';
+import { findPluginEntry, findPluginRegistration, findOfficialPlugin, listPluginNames, listOfficialPluginNames, loadRegisteredPlugin, PluginError, } from './plugin.js';
 import { getCloudServerConfigPath, loadCloudServerConfig } from './unifiedConfig.js';
 const TOP_LEVEL_COMMAND_NAME_WIDTH = 22;
 const CATEGORIES = [
     {
         title: 'API 调试',
-        names: ['tab_checkpoint', 'get_requests', 'get_logs', 'get_events', 'get_api_schema'],
+        names: ['tab_checkpoint', 'get_requests', 'get_logs', 'get_events'],
     },
     { title: 'Mock & 规则', names: ['set_mock', 'get_mocks', 'set_rule', 'get_rules'] },
     {
@@ -46,9 +46,7 @@ const CATEGORIES = [
         title: '环境与 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'] },
-    { title: 'TDBank', names: ['tdbank_account'] },
     {
         title: '浏览器',
         names: ['browser_list', 'browser_release', 'browser_launch', 'browser_close'],
@@ -61,7 +59,16 @@ const BUILTIN_COMMANDS = [
         examples: ['check'],
     },
 ];
-const SUGGESTABLE_COMMANDS = [...COMMANDS, ...BUILTIN_COMMANDS];
+const OFFICIAL_PLUGIN_COMMANDS = listOfficialPluginNames().map(name => ({
+    name,
+    description: findOfficialPlugin(name).description,
+    examples: [name],
+}));
+const SUGGESTABLE_COMMANDS = [
+    ...COMMANDS,
+    ...BUILTIN_COMMANDS,
+    ...OFFICIAL_PLUGIN_COMMANDS,
+];
 const ADVANCED_BUILTIN_COMMANDS = new Set(['connector_list']);
 function printUsage(commandName, version) {
     const lines = [
@@ -115,6 +122,14 @@ function printUsage(commandName, version) {
             });
             lines.push('', '已注册插件：', ...entries);
         }
+        const installed = new Set(plugins);
+        const available = listOfficialPluginNames().filter(name => !installed.has(name));
+        if (available.length) {
+            lines.push('', '官方插件（首次调用自动安装）：', ...available.map(name => {
+                const description = findOfficialPlugin(name).description;
+                return `  ${name.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}${description}`;
+            }));
+        }
     }
     catch (error) {
         lines.push('', error instanceof Error ? error.message : String(error));
@@ -126,6 +141,78 @@ function printUsage(commandName, version) {
     lines.push('', `运行 ${commandName} <action> --help 查看 action 参数。`);
     console.error(lines.join('\n'));
 }
+function providerSchemaLine(name, schema, required, indent = 2) {
+    const detail = [
+        required ? '必填' : '可选',
+        schema.type,
+        schema.type === 'string' && schema.secret ? '敏感' : undefined,
+        schema.title,
+        schema.description,
+        schema.default === undefined ? undefined : `默认 ${JSON.stringify(schema.default)}`,
+    ].filter(Boolean);
+    return `${' '.repeat(indent)}${name.padEnd(Math.max(1, 24 - indent))}${detail.join(' · ')}`;
+}
+function providerSchemaLines(name, schema, required, indent = 2) {
+    const lines = [providerSchemaLine(name, schema, required, indent)];
+    if (schema.type === 'object') {
+        const childRequired = new Set(schema.required ?? []);
+        for (const [childName, childSchema] of Object.entries(schema.properties)) {
+            lines.push(...providerSchemaLines(childName, childSchema, childRequired.has(childName), indent + 2));
+        }
+    }
+    else if (schema.type === 'array' && schema.items.type === 'object') {
+        const childRequired = new Set(schema.items.required ?? []);
+        for (const [childName, childSchema] of Object.entries(schema.items.properties)) {
+            lines.push(...providerSchemaLines(childName, childSchema, childRequired.has(childName), indent + 2));
+        }
+    }
+    return lines;
+}
+function printProviderHelp(commandName, provider) {
+    const browserType = provider.browserType;
+    const lines = [
+        `${provider.providerId} — ${provider.name} v${provider.version}`,
+        '',
+        ...(browserType.help ?? []).map(line => String(line)),
+    ];
+    if (browserType.help?.length)
+        lines.push('');
+    lines.push('创建：', `  ${commandName} browser_launch --payload '{"provider":"${provider.providerId}","providerOptions":{}}'`, '', '启动参数（providerOptions）：');
+    const required = new Set(browserType.inputSchema.required ?? []);
+    const properties = Object.entries(browserType.inputSchema.properties);
+    if (properties.length === 0)
+        lines.push('  （无）');
+    else {
+        for (const [name, schema] of properties) {
+            lines.push(...providerSchemaLines(name, schema, required.has(name)));
+        }
+    }
+    if (browserType.inputSchema.oneOf?.length) {
+        lines.push('', '可选模式：');
+        browserType.inputSchema.oneOf.forEach((schema, index) => {
+            const mode = schema.title || `模式 ${index + 1}`;
+            const requiredFields = schema.required?.length ? schema.required.join(', ') : '无必填字段';
+            lines.push(`  ${mode}（必填：${requiredFields}）`);
+        });
+    }
+    lines.push('', '发现与检查：', `  ${commandName} browser_list`, `  ${commandName} check --browser <browserId>`, '', '管理：', `  npx @mearl/setup provider update ${provider.providerId}`, `  npx @mearl/setup provider uninstall ${provider.providerId}`);
+    if (browserType.configuration) {
+        lines.push('', 'Provider 配置（在 Mearl 浏览器管理器中填写）：');
+        const configurationRequired = new Set(browserType.configuration.inputSchema.required ?? []);
+        for (const [name, schema] of Object.entries(browserType.configuration.inputSchema.properties)) {
+            lines.push(...providerSchemaLines(name, schema, configurationRequired.has(name)));
+        }
+    }
+    if (browserType.documentationUrl) {
+        lines.push('', `文档：${browserType.documentationUrl}`);
+    }
+    console.error(lines.join('\n'));
+}
+function installedProvider(name) {
+    if (!name)
+        return undefined;
+    return listInstalledProviders().find(provider => provider.providerId === name);
+}
 function printCheckHelp(commandName) {
     console.error([
         'check',
@@ -341,7 +428,7 @@ export function parseClientArgs(args, plugin = false) {
             : {}),
     };
 }
-async function runPluginCli(args, entry, commandName) {
+async function runPluginCli(args, commandName) {
     let parsed;
     try {
         parsed = parseClientArgs(args, true);
@@ -359,23 +446,23 @@ async function runPluginCli(args, entry, commandName) {
             ...(parsed.local ? { local: true } : {}),
             ...(parsed.forceCdp ? { transport: 'cdp' } : {}),
         };
-        const plugin = await loadPlugin(entry, {
-            options: invokeOptions,
-            progress(message) {
-                if (parsed.verbose) {
-                    process.stderr.write(message.endsWith('\n') ? message : `${message}\n`);
-                }
-            },
+        const plugin = await loadRegisteredPlugin(parsed.action, {
             async invoke(action, payload, options) {
                 client ??= new UnifiedClient({
                     ...(parsed.serverUrl ? { serverUrl: parsed.serverUrl } : {}),
                 });
-                const result = await client.invoke(action, payload, { ...invokeOptions, ...options });
-                if (result?.action?.success === false)
-                    throw new Error(result.action.error || `${action} failed`);
-                return result;
+                return client.invoke(action, payload, options);
             },
-        }, parsed.action);
+        }, {
+            ...invokeOptions,
+            ...(parsed.verbose
+                ? {
+                    onProgress(message) {
+                        process.stderr.write(message.endsWith('\n') ? message : `${message}\n`);
+                    },
+                }
+                : {}),
+        });
         if (parsed.version) {
             console.log(plugin.version ?? 'unknown');
             return 0;
@@ -435,6 +522,12 @@ export async function runMearlCli(args, options = {}) {
     const clientVersion = options.clientVersion ?? CLIENT_VERSION;
     if (args[0] === 'capture_checkpoint')
         args = ['tab_checkpoint', ...args.slice(1)];
+    const provider = installedProvider(args[0]);
+    if (provider &&
+        (args.length === 1 || args.slice(1).every(arg => arg === '--help' || arg === '-h'))) {
+        printProviderHelp(commandName, provider);
+        return 0;
+    }
     if (args[0] &&
         !args[0].startsWith('-') &&
         !args[0].startsWith('__') &&
@@ -443,8 +536,8 @@ export async function runMearlCli(args, options = {}) {
         !COMMAND_MAP.has(args[0])) {
         try {
             const entry = findPluginEntry(args[0]);
-            if (entry)
-                return await runPluginCli(args, entry, commandName);
+            if (entry || findOfficialPlugin(args[0]))
+                return await runPluginCli(args, commandName);
         }
         catch (error) {
             console.error(error instanceof Error ? error.message : String(error));

package/dist/commands.d.ts

@@ -142,24 +142,6 @@ export declare const COMMANDS: readonly [{
         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: "version";
-        readonly type: "string";
-        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 数据";
@@ -334,100 +316,43 @@ export declare const COMMANDS: readonly [{
         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: "login 首次不传；后续传上次响应的 tabId；无法恢复待扫码状态时会返回新的 tabId；其他操作在 CDP 模式下用于读取 Cookie";
-    }, {
-        readonly name: "operation";
-        readonly type: "\"current\" | \"list\" | \"login\" | \"switch\" | \"borrow\"";
-        readonly description: "操作类型，默认 current";
-    }, {
-        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";
-        readonly description: "switch 时使用账号列表中的 id";
-    }, {
-        readonly name: "havanaId";
-        readonly type: "string | number";
-        readonly description: "switch 时直接指定 havanaId；TDBank 方式需配合 site，免密方式需配合 ssoKey";
-    }, {
-        readonly name: "site";
-        readonly type: "string | number";
-        readonly description: "TDBank 方式直接指定 havanaId 时必填";
-    }, {
-        readonly name: "ssoKey";
-        readonly type: "string";
-        readonly description: "switch 免密方式的秘钥；必须同时传 havanaId，site 固定为 taobao";
-    }, {
-        readonly name: "query";
-        readonly type: "string";
-        readonly description: "borrow 时输入要借用的账号 loginId/关键词";
-    }, {
-        readonly name: "identityId";
-        readonly type: "string | number";
-        readonly description: "login 返回 identity_required 后，传用户明确选择的 identityId";
-    }];
-    readonly examples: ["tdbank_account --payload '{\"operation\":\"login\"}'", "tdbank_account --payload '{\"operation\":\"login\",\"tabId\":12345}'", "tdbank_account --payload '{\"operation\":\"login\",\"tabId\":12345,\"identityId\":\"10001\"}'", "tdbank_account --payload '{\"operation\":\"current\"}'", "tdbank_account --payload '{\"operation\":\"list\",\"refresh\":true}'", "tdbank_account --payload '{\"operation\":\"switch\",\"accountId\":12345}'", "tdbank_account --payload '{\"operation\":\"switch\",\"havanaId\":\"1234567890\",\"ssoKey\":\"<secret>\"}'", "tdbank_account --payload '{\"operation\":\"borrow\",\"query\":\"test_account\"}'"];
 }, {
     readonly name: "browser_list";
-    readonly description: "列出所有浏览器及其连接状态、类型和托管实例信息；AgentBay 可包含镜像与持久化 Context";
+    readonly description: "列出所有浏览器及其连接状态、类型和 Provider 托管实例信息";
     readonly summary: "列出本地及远端浏览器与连接状态";
     readonly examples: ["browser_list"];
 }, {
     readonly name: "browser_release";
-    readonly description: "sessionId 接入的 AgentBay 浏览器用它解除本机 attachment且不关闭云端 Session；其他浏览器仅按用户明确要求释放调试控制和会话级临时效果（含设备/时区模拟），不用于普通任务收尾";
-    readonly summary: "释放浏览器控制或解除 Session attachment";
+    readonly description: "释放当前浏览器的调试控制和会话级临时效果（含设备/时区模拟）；不用于普通任务收尾，Provider 实例的行为以 mearl <providerId> 为准";
+    readonly summary: "释放浏览器调试控制和会话级临时效果";
     readonly examples: ["browser_release", "browser_release --browser chrome-a"];
 }, {
     readonly name: "browser_launch";
-    readonly description: "启动本地 Chrome、创建/复用 AgentBay 云浏览器，或通过已注册 Provider 创建浏览器实例";
+    readonly description: "启动本地 Chrome，或通过已注册 Provider 创建浏览器实例";
     readonly params: [{
         readonly name: "name";
         readonly type: "string";
-        readonly description: "实例名称，创建浏览器时必填；按 sessionId 接入时可省略";
+        readonly description: "本地实例名称；使用 local Provider 时必填";
     }, {
         readonly name: "provider";
         readonly type: "string";
-        readonly description: "运行环境，默认 local；可传 agentbay 或 mearl --help 中展示的已注册 Provider ID";
+        readonly description: "运行环境，默认 local；可传 mearl --help 中展示的已注册 Provider ID";
     }, {
         readonly name: "providerOptions";
         readonly type: "Record<string, JSON value>";
         readonly description: "所选 Provider 声明的结构化启动参数；不能与顶层启动字段混用";
-    }, {
-        readonly name: "sessionId";
-        readonly type: "string";
-        readonly description: "显式接入现有 AgentBay Session；不会创建、初始化或取得其生命周期所有权";
-    }, {
-        readonly name: "reuse";
-        readonly type: "\"never\" | \"prefer\" | \"require\"";
-        readonly description: "AgentBay 运行实例复用策略：never 默认不复用；prefer 同名运行实例存在则复用、无记录则创建；require 只复用、不创建";
-    }, {
-        readonly name: "imageId";
-        readonly type: "string";
-        readonly description: "AgentBay 镜像别名或具体镜像 ID；默认使用已验证的 Linux Browser Use 内网镜像";
     }, {
         readonly name: "headless";
         readonly type: "boolean";
-        readonly description: "本地 provider 是否无头运行，默认 true；AgentBay 固定为 false，不支持 true";
+        readonly description: "本地 Provider 是否无头运行，默认 true";
     }, {
         readonly name: "userAgentMode";
         readonly type: "\"default\" | \"desktop\"";
-        readonly description: "UA 模式：default 使用 provider 默认 UA；desktop 本地使用匹配本机版本的 UA，AgentBay 复用控制浏览器的桌面 UA";
+        readonly description: "本地 UA 模式：default 使用默认 UA；desktop 使用匹配本机版本的 UA";
     }, {
         readonly name: "persistent";
         readonly type: "boolean";
-        readonly description: "关闭后是否保留浏览器状态，默认 false；本地保留 Profile，AgentBay 同名实例复用云端 Context";
+        readonly description: "本地实例关闭后是否保留 Profile，默认 false";
     }, {
         readonly name: "url";
         readonly type: "string";
@@ -436,35 +361,15 @@ export declare const COMMANDS: readonly [{
         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[] | \"mearl-services\" | { presets?: [\"mearl-services\"]; domains?: string[] }";
         readonly description: "从控制浏览器复制 Cookie：可传域名数组、Mearl 登录态预设，或组合预设与额外域名";
     }];
-    readonly examples: ["browser_launch --payload '{\"provider\":\"brow\",\"providerOptions\":{}}'", "browser_launch --payload '{\"name\":\"cloud-a\",\"provider\":\"agentbay\",\"userAgentMode\":\"desktop\",\"url\":\"https://example.com\"}'", "browser_launch --payload '{\"name\":\"cloud-public\",\"provider\":\"agentbay\",\"imageId\":\"browser_latest\",\"url\":\"https://example.com\"}'", "browser_launch --payload '{\"name\":\"cloud-login\",\"provider\":\"agentbay\",\"persistent\":true,\"copyCookieDomains\":[\"example.com\"],\"url\":\"https://example.com/account\"}'", "browser_launch --payload '{\"name\":\"cloud-login\",\"provider\":\"agentbay\",\"reuse\":\"require\",\"copyCookieDomains\":[\"example.com\"]}'", "browser_launch --browser '<本地浏览器 browserId>' --payload '{\"sessionId\":\"<AgentBay sessionId>\",\"copyCookieDomains\":[\"example.com\"]}'", "browser_launch --payload '{\"name\":\"cloud-tools\",\"provider\":\"agentbay\",\"copyCookieDomains\":\"mearl-services\"}'", "browser_launch --payload '{\"name\":\"cloud-tools\",\"provider\":\"agentbay\",\"copyCookieDomains\":{\"presets\":[\"mearl-services\"],\"domains\":[\"figma.com\"]}}'", "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 examples: ["browser_launch --payload '{\"provider\":\"brow\",\"providerOptions\":{}}'", "browser_launch --payload '{\"name\":\"figma\",\"userAgentMode\":\"desktop\",\"copyCookieDomains\":[\"figma.com\"]}'", "browser_launch --payload '{\"name\":\"with-cookies\",\"copyCookieDomains\":[\"example.com\",\"sub.example.org\"]}'"];
 }, {
     readonly name: "browser_close";
-    readonly description: "关闭指定托管浏览器并按策略保留或清理本地 Profile / AgentBay Context";
+    readonly description: "关闭指定托管浏览器，并按 Provider 策略保留或清理持久化数据";
     readonly params: [{
         readonly name: "browser";
         readonly type: "string";
@@ -473,9 +378,9 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "deleteProfile";
         readonly type: "boolean";
-        readonly description: "强制删除持久化本地 Profile 或 AgentBay Context，默认 false";
+        readonly description: "强制删除持久化数据，默认 false";
     }];
-    readonly examples: ["browser_close --payload '{\"browser\":\"managed:account-a\"}'", "browser_close --payload '{\"browser\":\"managed:agentbay:cloud-a\"}'", "browser_close --payload '{\"browser\":\"account-b\",\"deleteProfile\":true}'"];
+    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，并等待新页面加载完成";
@@ -885,15 +790,6 @@ export declare const COMMANDS: readonly [{
         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: "开始录制用户操作";
@@ -1034,7 +930,7 @@ export declare const COMMANDS: readonly [{
     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 description: "从目标浏览器读取一个指定非分区 Cookie；拒绝返回 HttpOnly Cookie";
     readonly params: [{
         readonly name: "tabId";
         readonly type: "number";
@@ -1045,16 +941,20 @@ export declare const COMMANDS: readonly [{
         readonly type: "string";
         readonly required: true;
         readonly description: "要读取的 Cookie 名称；不支持列举全部 Cookie";
+    }, {
+        readonly name: "url";
+        readonly type: "string";
+        readonly description: "可选 Cookie 查询 URL；省略时使用当前标签页 URL";
     }, {
         readonly name: "domain";
         readonly type: "string";
-        readonly description: "可选精确域过滤，只允许当前 host 或其父域";
+        readonly description: "可选精确域过滤，只允许 Cookie 查询 URL 的 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 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\"}'", "get_cookie --payload '{\"tabId\":12345,\"name\":\"tracknick\",\"url\":\"https://www.taobao.com/\",\"domain\":\"taobao.com\",\"path\":\"/\"}'"];
 }, {
     readonly name: "set_cookie";
     readonly description: "设置当前标签页域下的一个指定非分区 session Cookie，可选刷新页面";