@mearl/client 2.14.0 → 2.15.0

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,7 +128,7 @@ Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通
 `browser_list --help` 和 `browser_launch --help` 会按场景展示宿主选择参数；连接或传输排障运行
 `mearl check --help`。其中 `--json` 仅用于输出机器可读的检查结果。
 
-## Skill CLI 插件
+## Skill 插件
 
 安装 skill 并自动注册命令，或直接注册已有入口：
 
@@ -158,19 +156,44 @@ 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 都只解析本机 registry 中已注册的名称，不接受任意入口路径。
+
 注册记录在 `~/.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)。
+
+插件通过 `app.buc.request({ app, auth, url, ... })` 调用需要 BUC 身份的内部 HTTP 接口。`auth` 支持
+`id-token`（默认）、`ticket-header` 和兼容旧服务的 `ticket-query`。Mearl 按请求创建一次性凭据并注入
+`Authorization` + `DPoP`、`SSO-TICKET` Header 或 `SSO_TICKET` Query，只允许访问 HTTPS
+`alibaba-inc.com` 域名；凭据不会返回给插件，也不会复用到下一次请求，调用方也不能自行传入这些认证字段。
+`app.buc.whoami()` 返回当前身份的
+`empId` 和姓名，并在 Agent 身份场景返回 `agentId`；仅在确实需要部门等详细字段时使用
+`app.buc.profile()`，它通过一次性 `alineiwai` Ticket
+建立内存会话、校验资料属于当前员工，并只返回白名单字段，Ticket 与 Cookie 均不暴露给插件。
+缺少 BUC CLI 时 Mearl 会从官方 CLI Hub 安装后重试。这些方法与 `app.invoke` 一样，只能在插件 handler
+执行期间调用。BUC 请求始终在运行 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 +201,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 +214,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/buc.d.ts

@@ -0,0 +1,65 @@
+interface ProgramResult {
+    stdout: string;
+    stderr: string;
+}
+export interface BucIdentity {
+    agentId?: string;
+    empId: string;
+    name?: string;
+}
+export interface BucProfile extends BucIdentity {
+    bucUserId?: string;
+    gid?: string;
+    empType?: string;
+    photoPath?: string;
+    displayName?: string;
+    nickName?: string;
+    deptId?: string;
+    admin?: boolean;
+    buName?: string;
+    buNo?: string;
+    deptDesc?: string;
+    lang?: string;
+    cid?: string;
+    jobDesc?: string;
+    loginWorkNo?: string;
+}
+export type BucRequestFormValue = string | number | boolean;
+export type BucRequestAuth = 'id-token' | 'ticket-header' | 'ticket-query';
+export interface BucRequestParams {
+    app: string;
+    url: string;
+    auth?: BucRequestAuth;
+    method?: string;
+    headers?: Record<string, string>;
+    params?: Record<string, string | number | boolean | null | undefined>;
+    body?: unknown;
+    formData?: Record<string, BucRequestFormValue>;
+    responseType?: 'json' | 'text' | 'auto';
+    timeoutMs?: number;
+}
+export interface BucRequestResult {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: unknown;
+}
+export interface BucApi {
+    request(params: BucRequestParams): Promise<BucRequestResult>;
+    whoami(): Promise<BucIdentity>;
+    profile(): Promise<BucProfile>;
+}
+export type BucCommandRunner = (args: string[]) => Promise<ProgramResult>;
+export interface BucDependencies {
+    fetch?: typeof fetch;
+    installBuc?: () => Promise<void>;
+    runBuc?: BucCommandRunner;
+}
+export declare const runBucCommand: BucCommandRunner;
+export declare function installBucCli(): Promise<void>;
+export declare function bucWhoami(dependencies?: BucDependencies): Promise<BucIdentity>;
+export declare function bucProfile(dependencies?: BucDependencies): Promise<BucProfile>;
+/** Executes one internal request with a fresh credential in the selected BUC authentication mode. */
+export declare function bucRequest(input: BucRequestParams, dependencies?: BucDependencies): Promise<BucRequestResult>;
+export declare const buc: BucApi;
+export {};