@mearl/provider

@mearl/provider

@mearl/provider 是 Mearl 的统一浏览器 Provider 契约与运行时。内置 Local Chrome 和外部 Provider 使用相同的 BrowserProviderDefinition；区别只在于运行时位于 Native Host 进程内， 还是通过本地 Provider Socket 接入。

核心模型

Provider v2 分开表达实例状态与控制方式：

• status：实例处于 connected、pairing、running_disconnected 或 stopped。
• control：页面操作由 Provider 自己处理、由宿主的 Extension/CDP 处理，或当前没有控制通道。

实例还会声明 ownership、persistence、当前允许的资源 operations、稳定 references 和可公开展示的 details。因此 Provider identity 不再等同于控制传输，持久化实例 也不需要伪装成已连接浏览器。

外部 Provider 安装

外部 Provider 包将 @mearl/provider 声明为运行依赖：

pnpm add @mearl/provider

包的 package.json#mearl.provider 声明协议入口、浏览器类型和结构化启动参数：

{
  "name": "@example/mearl-provider-device",
  "version": "1.0.0",
  "type": "module",
  "mearl": {
    "provider": {
      "providerId": "example-device",
      "name": "Example device provider",
      "protocolVersion": 2,
      "entry": "./dist/runtime.js",
      "browserType": {
        "name": "Device",
        "help": ["Pair a device, then use its browserId with Mearl actions."],
        "inputSchema": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string",
              "title": "Pairing code",
              "placeholder": "Generated by default"
            }
          }
        }
      }
    }
  }
}

Schema 支持 string、number、boolean、array 和递归 object；Provider 配置也可通过 browserType.configuration.inputSchema 声明。browserType.help 由 mearl <providerId> 和 mearl <providerId> --help 展示，让 Provider 的操作说明随独立包版本演进。同名 Skill 插件已注册时， CLI 会在其后自动追加插件命令摘要，Provider 不需要在 browserType.help 中重复维护命令清单。 local 是内置保留 ID。

最小外部运行时

import { createProviderServer, type BrowserProviderDefinition } from '@mearl/provider';

const definition: BrowserProviderDefinition = {
  descriptor: {
    providerId: 'example-device',
    name: 'Example device provider',
    version: '1.0.0',
  },
  browserType: {
    name: 'Device',
    inputSchema: {
      type: 'object',
      properties: { code: { type: 'string', title: 'Pairing code' } },
    },
  },
  launch: async options => createDevice(String(options.code ?? '')),
  close: async ({ browserId }) => removeDevice(browserId),
  handleAction: async ({ browserId, action, data }) =>
    dispatchDeviceAction(browserId, action, data),
};

const server = createProviderServer({ definition });
await server.start();
server.updateBrowsers([
  {
    browserId: 'device-1',
    name: 'Example device',
    status: 'connected',
    control: {
      kind: 'provider',
      capabilities: {
        actions: ['tab_list', 'page_snapshot', 'page_click'],
        screenshot: 'none',
      },
    },
    ownership: 'owned',
    persistence: 'persistent',
    operations: ['close'],
  },
]);

配对中的设备使用 status: "pairing" 并提供 pairing；停止的持久化实例使用 status: "stopped" 和 control: { kind: "none" }。运行但尚未接通控制链路时使用 status: "running_disconnected"。 Runtime 会统一校验 schema、状态机、操作能力和页面 action capability，校验通过后才调用实现。 start、detach、getAccess、syncCookies 等可选实现必须与实例声明的 operation 对应； 这些是 Provider runtime 的内部能力，不会要求 Mearl 公共协议增加一一对应的 action。

公共 browser_launch 对所有 Provider 接收 { provider, providerOptions }，返回与 browser_list.browsers[] 相同的 ManagedBrowserInfo（对象形式的 Provider identity、状态、 持久化策略、操作和安全元数据）。管理器内部字段、控制连接和临时访问地址不进入该结果。 Local 的 CLI 顶层参数是便捷输入；外部 Provider 参数必须放在 providerOptions，两者不得混用。

内置浏览器保留本地启动交互；外部 Provider 根据 browserType.inputSchema 生成输入项。 两者提交同一结构的 providerOptions。 Schema 的顶层 oneOf 可声明多个完整对象约束， 例如创建与接管会话；每个分支用 title 命名，Runtime 要求输入恰好匹配一个分支， not 可排除不允许的字段组合。default 是表单初始值，不会隐式修改调用方参数。 对象字段 copyCookieDomains 约定使用 { presets?, domains? } Cookie 范围结构。 为这个字段声明 component: "cookie-sync" 后，Mearl 浏览器管理器会使用统一的 Cookie 范围选择组件，并在提交前申请所选站点权限；未声明组件时仍按普通 object 字段渲染。 Provider 可用 component: "switch" 渲染紧凑布尔开关；formHidden 隐藏仅供 CLI/API 使用的高级字段，formWidth 控制字段宽度，formDefault 设置不影响运行时默认值的表单初值， formHideOptional 只隐藏可选标识而不改变校验，formVisibleWhen 根据另一个字段是否为空控制显示与提交。 browserType.documentationUrl 声明 HTTP(S) 文档地址；configuration.inputSchema 声明配置参数， 配置只传给所选 Provider 的 configure，不存入页面本地存储。

details 中的通用键具有固定类型：headless 为布尔值，createdAt 为可解析时间字符串， cdpPort 为有效端口，account 包含 nickname 和可选的字符串 accountId/loginId， copiedCookies 包含字符串数组 domains 和非负整数 count。其余键允许非敏感 JSON，界面同样展示。 references 的 kind 表示资源类别，id 为不透明标识，label 为展示名； 通用类别包括 profile/session/image/context/context-name，也允许 Provider 自定义类别。

内置运行时

Native Host 使用 createProviderRuntime(definition) 直接运行内置 Local Provider，不需要创建 Socket 或注册安装记录。内置与外部实现共享同一份 schema 校验、状态机和生命周期派发逻辑；需要宿主服务的进程内调用可通过 ProviderContext.host 注入，Provider 合同本身不依赖 Extension、Native Messaging 或 具体浏览器服务 SDK。

外部 Provider 的安装、发现与启动仍由 @mearl/setup 管理：

npx @mearl/setup provider install <package>
npx @mearl/setup provider update <provider-id>
npx @mearl/setup provider uninstall <provider-id>