@mearl/client 2.22.0 → 3.0.0-beta.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,5 +1,7 @@
 # @mearl/client
 
+本仓库仍在迁移完整宿主。此包已可独立构建和测试，setup/native-host/extension 的公开发行接入尚未完成；下列产品命令描述其现有合同，不代表已发布 3.0。
+
 统一浏览器 SDK 与 CLI。它会发现当前机器及已配置 cloud-server 下所有 connector 的浏览器，并根据 `browser_list` 返回的全局 `browserId` 自动选择本地 Socket 或云端 WebSocket 链路。
 
 提供两种用法：类型安全的具名方法（`getRequests`、`sendRequest` 等），以及灵活的底层 `invoke(action, payload)`。
@@ -103,15 +105,13 @@ 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
+npx @mearl/setup provider install @example/mearl-provider-device
 
 # 查看 Provider 当前版本的能力、参数与使用流程
-mearl brow
-mearl agentbay --help
+mearl example-device --help
 
 # Provider 启动参数统一放在 providerOptions
-mearl browser_launch --payload '{"provider":"brow","providerOptions":{}}'
+mearl browser_launch --payload '{"provider":"example-device","providerOptions":{}}'
 mearl browser_list
 
 # 后续操作使用 browser_list 返回的全局 Browser ID
@@ -190,15 +190,13 @@ client、native-host、cloud-server 和 MCP server 的已安装版本。发现
 安装 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 install trip/mearl --skill authx-request --yes
-npx @mearl/setup plugin /absolute/path/to/yuque-doc-fetch
-npx @mearl/setup plugin uninstall yuque
-mearl yuque read "https://aliyuque.antfin.com/group/book/doc"
-mearl yuque --payload '{"command":"read","input":{"url":"https://aliyuque.antfin.com/group/book/doc"}}'
-mearl yuque --help
-mearl yuque --version
+npx @mearl/setup plugin install https://github.com/F-loat/mearl --skill browser-tab-manager --yes
+npx @mearl/setup plugin /absolute/path/to/browser-tab-manager
+npx @mearl/setup plugin uninstall tabs
+mearl tabs summary
+mearl tabs --payload '{"command":"summary","input":{}}'
+mearl tabs --help
+mearl tabs --version
 ```
 
 当已注册插件与 Provider 使用同一名称时，`mearl <name> --help` 会先显示 Provider 的启动和生命周期说明，
@@ -209,21 +207,7 @@ Provider 与插件仍可独立安装、更新和卸载，帮助聚合不会启
 注册动作、`app.invoke(action, payload, options?)` 复用当前浏览器上下文，并用 `app.progress(message)` 报告可选进度。JavaScript 插件还可传入 `{ message, data }`，让工具页通过可 JSON 序列化的 `data` 获取稳定的阶段、对象 ID 等机器信息；CLI 仍只显示 `message`。Python 的 `app.invoke` 是同步调用，handler 可以是普通函数或 `async def`。Python 插件要求 `python3 >= 3.9`，可用 `MEARL_PYTHON` 指定解释器路径；Mearl 不安装 Python 或执行 `pip install`。调用另一个插件时，payload 使用 `{ command, input }` envelope；嵌套调用继承宿主选项并拒绝循环依赖。CLI 默认只输出最终结果，传入
 `--verbose` 时才把进度写入 stderr。handler 返回文本或 JSON，宿主统一处理 `--output`、连接和错误。写命令在用户调用后直接执行，业务模块负责目标、状态、幂等和结果校验。
 注册名优先使用显式名称，其次读取入口的 `name` metadata，最后回退到 skill 目录名；常规注册只传路径。
-setup 会补齐缺失或低于自身版本的 client、native-host；安装参数透传给 Ali Skills，并固定全局共享安装。
-
-`mearl-bbrowser` Skill 提供 `bbrowser` 插件，可直接加载 bb-browser 格式的社区及私有站点适配器，无需安装 bb-browser：
-
-```bash
-npx @mearl/setup plugin install trip/mearl --skill mearl-bbrowser --yes
-mearl bbrowser site list
-mearl bbrowser site fliggy-ebooking/whoami
-mearl bbrowser site ./fliggy-ebooking/ai-agent.js
-mearl bbrowser site zhihu/hot 10
-mearl bbrowser site zhihu/hot 10 --cdp
-```
-
-插件通过同一 `page_eval` 接口调用扩展或直连 CDP。适配器来源、私有目录、更新与结构化调用见
-[mearl-bbrowser Skill](../skills/mearl-bbrowser/SKILL.md)。插件默认输出 JSON。
+setup 会补齐缺失或低于自身版本的 client、native-host；安装参数由 setup 的 Skills 安装器处理，并固定全局共享安装。
 
 需要单独检查插件时运行 `mearl <name> --version`。命令会解析注册记录并加载入口，但不连接浏览器；
 退出码为 0 表示插件已注册且入口可加载，stdout 返回同目录 `SKILL.md` 的版本，缺少版本元数据时返回 `unknown`。
@@ -242,13 +226,13 @@ skill 的字段约定处理。`browser`、`timeout`、`output` 等宿主选项
 import { invokePlugin } from '@mearl/client';
 
 const result = await invokePlugin(
-  'yuque',
-  { command: 'read', input: { url: 'https://aliyuque.antfin.com/group/book/doc' } },
+  'tabs',
+  { command: 'summary', input: {} },
   { browser: 'work' },
 );
 ```
 
-MCP Server 通过固定工具 `plugin_invoke` 接受同样的 `plugin`、`command` 和 `input`，不会把插件子命令动态扩展成 MCP 工具。SDK 与 MCP 不接受任意入口路径；调用尚未注册的 `buc`、`authx` 或 `tdbank` 时，会通过匹配当前 client 版本的 setup 自动安装并重试一次。其他未注册名称返回 `PLUGIN_NOT_REGISTERED`。
+MCP Server 通过固定工具 `plugin_invoke` 接受同样的 `plugin`、`command` 和 `input`，不会把插件子命令动态扩展成 MCP 工具。SDK 与 MCP 不接受任意入口路径；本地受管理目录中的插件未注册时，会通过匹配当前 client 版本的 setup 自动安装并重试一次。目录由安装宿主显式保存，核心没有组织专属名单；其他未注册名称返回 `PLUGIN_NOT_REGISTERED`。
 
 长命令使用本机持久任务服务。服务按注册目录隔离并自动启动，CLI、SDK、MCP 与工具箱共享任务记录；调用方退出不取消执行。服务重启后将未完成任务标记为 `interrupted`，不自动重放。后台任务固定接受时的源码快照、工作目录与环境；静态第三方 JS 依赖需要预先打包进 Skill，状态文件放在源码目录之外。
 
@@ -275,16 +259,24 @@ try {
 `tasks.diagnose({ taskId?, plugin?, instanceId?, includeErrorMessages?, includeLocalPaths? })` 读取当前调用范围内的有界诊断报告。默认不包含业务输入、提示词、进度正文、检查点数据、结果正文、完整 URL、环境变量和凭证，也省略错误消息及本地路径；后两项可显式选择包含。报告的 coverage 和历史 gap 表示采集范围及保留历史限制。
 
 注册记录在 `~/.mearl/plugins/<name>.json`，保存入口路径和可选的简短描述；skill 业务代码原地更新直接生效，换路径或更新描述后重新注册。
-`plugin uninstall <name>` 会对 `~/.agents/skills` 中的全局 Skill 调用 `ali-skills remove --global --yes`，
-成功后清除相关注册；即使入口目录已被手动删除，也会完成 Ali Skills 跟踪记录的清理。
+`plugin uninstall <name>` 会对 `~/.agents/skills` 中的全局 Skill 调用 Skills 安装器执行全局卸载，
+成功后清除相关注册；即使入口目录已被手动删除，也会完成 Skills 跟踪记录的清理。
 手工路径只解除注册并保留源码。
 `PLUGIN_NOT_REGISTERED` 表示插件尚未注册。`PLUGIN_ENTRY_MISSING` 会显示失效入口，并给出带有实际插件名的
 卸载清理命令。其他错误按实际原因处理。
-编写规范见 [Mearl Skill Creator 的 Skill 插件规范](../skills/mearl-skill-creator/references/cli-plugin.md)。
+下文描述插件工具箱、页面、状态与任务的通用合同。
 
 插件可选导出 `toolbox`，注册后会出现在扩展 Popup 的工具箱中。页面资源放在 Skill 目录内，注册时由
 Mearl 将入口 HTML 引用的本地 CSS、JavaScript 和图片内联为不可变页面包，不需要启动 HTTP 服务，
-也不要求普通 HTML/CSS/JS 页面自行构建：
+也不要求普通 HTML/CSS/JS 页面自行构建。
+
+右键工具箱中的工具可单独禁用或启用对应 Skill；禁用状态显示在标题右侧，工具页面和命令仍可使用。禁用将该目录的
+`SKILL.md` 重命名为 `SKILL.md.mearl-disabled`，启用时恢复，作用于共享此目录的所有 Agent；
+软链接安装会作用于源目录。已有会话可能仍保留已载入的 Skill，需要重启 Agent 或新建会话。
+工具箱内更新和重新安装会保留禁用状态；外部安装器的更新不受此状态管理，若出现两份清单，需先处理冲突。
+独立复制安装的同名 Skill 需分别禁用。没有 Skill 清单的普通插件不显示此开关。
+
+工具箱元数据示例：
 
 ```javascript
 export const toolbox = {
@@ -458,7 +450,7 @@ pnpm typecheck  # 仅类型检查
 
 ## License
 
-ISC
+Apache-2.0
 
 ### 插件页面实例
 
@@ -476,7 +468,7 @@ try {
 } finally { pages.disconnect(); }
 ```
 
-后台事件声明 schema 和串行、latest 合并或有限并发策略，处理器用 `app.runtimeCommand()` 注册并通过 `context.page` 访问固定文档。文档绑定任务可用 `app.page('activation')` 只读查询本插件激活规则，不允许设置或关闭规则。页面消息/结果各上限 24 MiB，宿主自动分块并校验；事件负载上限 32 KiB。工具箱使用 `host.page.*`，UI 订阅实例历史与后台执行独立。完整契约见 [插件宿主能力](../native-host/README.md#页面运行时和事件)。
+后台事件声明 schema 和串行、latest 合并或有限并发策略，处理器用 `app.runtimeCommand()` 注册并通过 `context.page` 访问固定文档。文档绑定任务可用 `app.page('activation')` 只读查询本插件激活规则，不允许设置或关闭规则。页面消息/结果各上限 24 MiB，宿主自动分块并校验；事件负载上限 32 KiB。工具箱使用 `host.page.*`，UI 订阅实例历史与后台执行独立。完整契约见 [插件宿主能力](../../docs/plugin-runtime.md#页面运行时和事件)。
 
 Python 入口同样导出 `pageRuntime` 字典，其中 `code` 仍是运行于网页中的 JavaScript 函数字符串；后台初始化与事件处理器通过 `app.runtimeCommand(...)` 或其装饰器注册。`app.page(operation, payload)`、`context.page.send(message)` 和 `context.page.get()` 都是同步调用，后两者仅在绑定页面实例的处理器中可用。JS 和 Python 的 `context.page.send(message, {timeoutSec: 120})` 可指定单次响应超时（大于 0 且最多 300 秒，Python 使用字典）；`app.page("send", {instanceId, message, timeoutSec})` 和 SDK `pages.send(plugin, instanceId, message, {timeoutSec})` 同样支持。该设置不改变其他请求，任务取消和文档解绑仍立即中断执行，传输失败也会取消对应网页请求。runtime-only 命令不出现在公开命令帮助中，也不能由 CLI 或工具箱直接执行；声明在页面事件中的普通 `app.command` 仍保留公开调用能力。
 
@@ -512,7 +504,7 @@ export default app => app.command('save', async (input, context) => {
 });
 ```
 
-SDK `PluginStateClient.get/getMany/list/transact` 与工具箱 `host.state.*` 共享集合。每次写入需 CAS，冲突后重新读取、合并再重试；`schemaVersion` 升级用显式迁移事务。浏览器会话/实例可声明 `cache` 或 `memory`，页面身份由宿主验证。`memory` 只保存在插件执行宿主进程中，支持同样的 CAS、schema、TTL 与分块值限制；刷新文档时保留浏览器会话范围，浏览器会话变化后隔离，执行宿主重启时清空。内存状态全宿主合计最多 128 MiB / 512 个集合命名空间，按需占用；单集合 `maxBytes` 最大 128 MiB，实例结束释放其内存。容量、TTL 和完整契约见[插件宿主能力](../native-host/README.md#状态和激活)。二进制资产继续使用文件或资源通道。
+SDK `PluginStateClient.get/getMany/list/transact` 与工具箱 `host.state.*` 共享集合。每次写入需 CAS，冲突后重新读取、合并再重试；`schemaVersion` 升级用显式迁移事务。浏览器会话/实例可声明 `cache` 或 `memory`，页面身份由宿主验证。`memory` 只保存在插件执行宿主进程中，支持同样的 CAS、schema、TTL 与分块值限制；刷新文档时保留浏览器会话范围，浏览器会话变化后隔离，执行宿主重启时清空。内存状态全宿主合计最多 128 MiB / 512 个集合命名空间，按需占用；单集合 `maxBytes` 最大 128 MiB，实例结束释放其内存。容量、TTL 和完整契约见[插件宿主能力](../../docs/plugin-runtime.md#状态和激活)。二进制资产继续使用文件或资源通道。
 
 ### 显式任务恢复
 
@@ -520,7 +512,7 @@ SDK `PluginStateClient.get/getMany/list/transact` 与工具箱 `host.state.*`
 
 `tasks.checkpoint(taskId)` 读取检查点；`tasks.resume(taskId, { environment?, revision? })` 为终态根命令建立新 attempt，保持旧任务终态，固定原安装、源码快照、输入、目录和路由。默认提交调用进程的新环境，旧环境不持久化。恢复入口读取 `context.recovery`，先核对外部操作状态；宿主不重放原 handler，也不保证外部提交与检查点原子。
 
-SDK 使用 `tasks.checkpoint(taskId)` / `tasks.resume(taskId)`。当前仅支持 public/service 根命令，拒绝模型、子任务、页面绑定和 caller 路由恢复，且必须确认原执行树已经停止。默认固定原代码；显式 `revision: 'current'` 选择请求进入时的当前快照。同格式版本需 schema 相同，跨格式版本需目标 `taskRecovery` 声明 `migrateFrom: [{ version, schema }]` 并注册隐藏 `app.checkpointMigration(command, handler)`，返回目标检查点数据。宿主先核验历史 schemaHash，禁止转换中的宿主及嵌套插件 API，以 10 秒期限管理进程；转换必须可重试、无副作用，可信代码不构成 OS 沙箱。并发恢复合并为一个转换与后继任务，旧任务和数据保持不变。完整资格与故障域见[检查点与显式恢复](../native-host/README.md#检查点与显式恢复)。
+SDK 使用 `tasks.checkpoint(taskId)` / `tasks.resume(taskId)`。当前仅支持 public/service 根命令，拒绝模型、子任务、页面绑定和 caller 路由恢复，且必须确认原执行树已经停止。默认固定原代码；显式 `revision: 'current'` 选择请求进入时的当前快照。同格式版本需 schema 相同，跨格式版本需目标 `taskRecovery` 声明 `migrateFrom: [{ version, schema }]` 并注册隐藏 `app.checkpointMigration(command, handler)`，返回目标检查点数据。宿主先核验历史 schemaHash，禁止转换中的宿主及嵌套插件 API，以 10 秒期限管理进程；转换必须可重试、无副作用，可信代码不构成 OS 沙箱。并发恢复合并为一个转换与后继任务，旧任务和数据保持不变。完整资格与故障域见[检查点与显式恢复](../../docs/plugin-runtime.md#检查点与显式恢复)。
 
 插件 CLI 调用失败以非零退出码和 stderr JSON `{ "error": { "code", "message" } }` 返回，保留 SDK/MCP 的 code，不输出任意异常附加字段。`PLUGIN_TASK_WAIT_TIMEOUT` 仅停止等待；`PLUGIN_EXECUTION_CANCELLED` / `PLUGIN_EXECUTION_DEADLINE` 表示执行取消或到期；`PLUGIN_PAGE_TARGET_CHANGED` / `PLUGIN_PAGE_INVALIDATED` 要求重新获取页面实例；`PLUGIN_STATE_CONFLICT` 需重新读取 CAS 版本；`PLUGIN_MODEL_CAPABILITY_UNSUPPORTED` 表示声明能力不支持；`PLUGIN_INVOCATION_CYCLE` / `PLUGIN_INVOCATION_DEPTH` 拒绝循环或过深组合。进程树无法确认停止时保留失败记录并拒绝恢复。
 
@@ -532,3 +524,11 @@ SDK 使用 `tasks.checkpoint(taskId)` / `tasks.resume(taskId)`。当前仅支持
 插件宿主由 `PluginHost` 组装任务、状态、页面与模型目录服务，统一关闭和诊断。`PluginTaskManager` 接收明确的服务依赖并管理执行树；页面和状态服务不反向修改调度器。SDK 的连接、服务发现、握手、重连和调用桥接由 `PluginHostConnection` 管理。需要共享连接时，在 Task/Model/State 客户端构造选项中传入 `connection`，Page 客户端通过第二个构造参数传入；注入连接由创建者关闭，各客户端的 `disconnect()` 只关闭自己创建的连接。连接始终绑定单个调用范围，不能跨插件、交互渠道或来源复用。
 
 后台连续模型调用可以显式传 `conversation`（1–80 个字母、数字或 `:_-`）。同名会话仅在当前页面实例或宿主管理的当前命令执行内复用；插件、版本、模型、指令、环境和调用归属分别隔离。未指定时每次调用独立。页面解除绑定或命令结束会释放会话；取消、失败和超时会销毁当前会话，空闲 5 分钟释放，每 32 轮重新建立临时会话以限制历史增长。会话仅驻留内存，不新增顶层 CLI/MCP 命令。
+
+## 受管理插件目录
+
+安装宿主可通过 client/plugin 的 replaceOfficialPluginCatalog(revision, plugins) 保存已选 preset 的插件目录。revision 为确切清单摘要，每项声明 description、skill 和安装器参数 installArgs，可选 setup 分组。目录以原子文件替换保存于当前插件注册目录的 .official-catalog.json；默认不存在任何预装组织项。安装源码与 preset 的信任校验由安装宿主负责，目录本身不触发安装。
+
+findOfficialPlugin/listOfficialPluginNames 每次读取当前目录，继续复用同一 setup 入口完成缺失插件安装。readOfficialPluginCatalog 向安装状态页报告损坏；普通插件和浏览器命令忽略损坏的可选目录，不影响已注册能力。OFFICIAL_PLUGINS 兼容导出反映本进程最近读取的目录。
+
+扩展版本检查默认读取 GitHub 最新正式发行物中的 config.json；发行宿主可用 MEARL_EXTENSION_CONFIG_URL 提供返回 version 或 latestVersion 的配置端点。尚未上传扩展发行元数据时，更新信息显示不可用，核心源码版本不作为已发布扩展版本；检查失败仅影响更新提示。

package/dist/actionTimeouts.js

@@ -1,4 +1,4 @@
-import { PAGE_ACT_ACTIONS } from './generated/browser-action-protocol.js';
+import { PAGE_ACT_ACTIONS } from '@mearl/browser-core';
 const SEND_REQUEST_FILE_TRANSFER_TIMEOUT_MS = 120_000;
 // Remote Providers may stage files before forwarding a page upload.
 const PAGE_UPLOAD_FILE_TRANSFER_TIMEOUT_MS = 180_000;

package/dist/artifacts.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserArtifact } from './generated/browser-action-protocol.js';
+import type { BrowserArtifact } from '@mearl/browser-core';
 import type { UnifiedInvokeOptions } from './unified.js';
 interface Invoker {
     invoke(action: string, data?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;

package/dist/autoUpdate.js

@@ -226,8 +226,7 @@ export function setupUpdateCommand(version, packageRoot, profiles, updateClient)
             `@mearl/setup@${version}`,
             'update',
             '--yes',
-            '--target-line',
-            `${major}.${minor}.x`,
+            ...(version.includes('-beta.') ? [] : ['--target-line', `${major}.${minor}.x`]),
             '--skip-skill',
         ],
         env,

package/dist/browserRegistry.d.ts

@@ -8,7 +8,7 @@
  * registry directory and record shape; reading scans every *.json in the dir,
  * so it never needs to replicate daemon-core's filename hashing.
  */
-import type { BrowserCapabilities, BrowserDetails, BrowserPairingInfo, BrowserProviderIdentity, BrowserProviderOperation, BrowserReference, BrowserTransport } from './generated/browser-action-protocol.js';
+import type { BrowserCapabilities, BrowserDetails, BrowserPairingInfo, BrowserProviderIdentity, BrowserProviderOperation, BrowserReference, BrowserTransport } from '@mearl/browser-core';
 export interface LiveBrowser {
     pid: number;
     browserId: string;

package/dist/check.d.ts

@@ -1,6 +1,6 @@
 import type { CloudConnectorInfo } from '@mearl/cloud-types';
 import { type NativeHostDiagnostic } from './nativeHost.js';
-import type { BrowserCapabilities, BrowserProviderIdentity, BrowserProviderOperation } from './generated/browser-action-protocol.js';
+import type { BrowserCapabilities, BrowserProviderIdentity, BrowserProviderOperation } from '@mearl/browser-core';
 import { type UnifiedClientOptions, type UnifiedInvokeOptions } from './unified.js';
 export interface UnifiedCheckVersions {
     nativeHost?: string;

package/dist/check.js

@@ -4,7 +4,7 @@ const UPDATE_SOURCES = {
     client: 'https://registry.npmjs.org/@mearl%2Fclient/latest',
     'native-host': 'https://registry.npmjs.org/@mearl%2Fnative-host/latest',
     'cloud-connector': 'https://registry.npmjs.org/@mearl%2Fcloud-connector/latest',
-    extension: 'https://mearl.alibaba-inc.com/config.json',
+    extension: 'https://github.com/F-loat/mearl/releases/latest/download/config.json',
 };
 export function parseReleaseVersion(value) {
     if (typeof value !== 'string')
@@ -30,13 +30,14 @@ export function isNewerRelease(latest, installed) {
     return false;
 }
 async function fetchLatestVersion(component) {
-    const response = await fetch(UPDATE_SOURCES[component], {
+    const source = component === 'extension' ? process.env.MEARL_EXTENSION_CONFIG_URL || UPDATE_SOURCES.extension : UPDATE_SOURCES[component];
+    const response = await fetch(source, {
         signal: AbortSignal.timeout(1500),
     });
     if (!response.ok)
         throw new Error(`HTTP ${response.status}`);
     const payload = (await response.json());
-    const version = component === 'extension' ? payload.latestVersion : payload.version;
+    const version = component === 'extension' ? (payload.latestVersion ?? payload.version) : payload.version;
     if (!parseReleaseVersion(version))
         throw new Error('Invalid release version');
     return version;

package/dist/commands.d.ts

@@ -1,4 +1,4 @@
-import { type BrowserCommandAction } from './generated/browser-action-protocol.js';
+import { type BrowserCommandAction } from '@mearl/browser-core';
 export interface ParamDef {
     name: string;
     type: string;
@@ -297,7 +297,7 @@ export declare const COMMANDS: readonly [{
         readonly type: "string";
         readonly description: "规则说明";
     }];
-    readonly notes: readonly ["扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。"];
+    readonly notes: readonly ["扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。", "扩展模式会检查规则请求 URL 和显式来源域名的访问权限；缺失时仍保存规则，返回 warnings 和 missingOrigins，不自动弹窗。可在请求规则页面授权，或按提示调用 request_domain_permission。复杂 URL 表达式无法完整推断域名时会提示手动检查。"];
     readonly examples: ["set_rule --payload '{\"actionType\":\"block\",\"filter\":\"^https://example\\\\.com/ads/.*\"}'", "set_rule --payload '{\"ruleId\":42,\"enabled\":false}'"];
 }, {
     readonly name: "get_rules";
@@ -353,7 +353,7 @@ export declare const COMMANDS: readonly [{
         readonly type: "number";
         readonly description: "超时毫秒数，默认 30000";
     }];
-    readonly notes: readonly ["仅用于非 BUC 请求；BUC 接口使用 mearl buc，不手工传 Token、DPoP 或 Ticket。", "body 不能与 formData/files 组合；bodyFile 以原始字节发送，不包 multipart boundary，不能用于 GET/HEAD。", "bodyFile.filePath 属于 native-host，最大 40 MiB；base64 解码后最大 7 MiB。multipart 不手工设置 Content-Type，由 Mearl 生成 boundary。", "filePath 属于 native-host 所在机器；无法引用远端路径时用 base64。BUC 上传的路径属于插件执行宿主。"];
+    readonly notes: readonly ["需要托管认证的接口使用相应能力插件；不要手工传入其管理的凭据。", "body 不能与 formData/files 组合；bodyFile 以原始字节发送，不包 multipart boundary，不能用于 GET/HEAD。", "bodyFile.filePath 属于 native-host，最大 40 MiB；base64 解码后最大 7 MiB。multipart 不手工设置 Content-Type，由 Mearl 生成 boundary。", "filePath 属于请求执行宿主；无法引用远端路径时用 base64。"];
     readonly result: readonly ["返回 status、statusText、headers、body、bodyType、attachedCookieCount；bodyType 为 json/text/base64，二进制 body 需解码后保存。"];
     readonly examples: ["send_request --payload '{\"url\":\"https://api.example.com/data\",\"method\":\"GET\"}'", "send_request --payload '{\"url\":\"https://api.example.com/upload\",\"method\":\"POST\",\"formData\":{\"folder\":\"assets\"},\"files\":[{\"fieldName\":\"file\",\"filePath\":\"/absolute/path/image.png\"}]}'", "send_request --payload '{\"url\":\"https://api.example.com/upload\",\"method\":\"POST\",\"bodyFile\":{\"filePath\":\"/absolute/path/image.png\",\"contentType\":\"image/png\"}}'"];
 }, {
@@ -457,8 +457,8 @@ export declare const COMMANDS: readonly [{
         readonly description: "自定义 Chrome 可执行文件路径";
     }, {
         readonly name: "copyCookieDomains";
-        readonly type: "string[] | \"mearl-services\" | { presets?: [\"mearl-services\"]; domains?: string[] }";
-        readonly description: "从控制浏览器复制 Cookie：可传域名数组、Mearl 登录态预设，或组合预设与额外域名";
+        readonly type: "string[] | string | { presets?: string[]; domains?: string[] }";
+        readonly description: "从控制浏览器复制 Cookie：可传域名数组、已安装能力提供的范围名，或组合范围与额外域名";
     }];
     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\"]}'"];
 }, {
@@ -519,7 +519,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "appProfile";
         readonly type: "string";
-        readonly description: "开 tab 即注入 App 客户端环境与 JSBridge；档案名同 set_app_profile，如 \"fliggy\"。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true";
+        readonly description: "按已安装档案应用 App 环境；内置基础档案只提供 UA/版本，完整桥由能力包提供。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true";
     }, {
         readonly name: "os";
         readonly type: "\"ios\" | \"android\"";
@@ -531,7 +531,7 @@ export declare const COMMANDS: readonly [{
     }];
     readonly notes: readonly ["emulation / appProfile 只应用到新建 Tab；复用 Tab 要切换状态时用对应设置 action。", "closeExisting 不能与复用或 openerTabId 组合；多匹配默认报错，match.onMultiple=first 可显式选择第一个。"];
     readonly result: readonly ["返回 tabId、url、title、opened/reused；reused=true 的既有页面应保留。", "active=true 时 activation 包含 tabActive、windowFocused、windowState、visibilityState；emulation 返回实际生效配置。", "capture.cursor 是导航前诊断边界，可分别用于 get_logs/get_requests/get_events 的 after。"];
-    readonly examples: ["tab_open --payload '{\"url\":\"https://example.com\"}'", "tab_open --payload '{\"url\":\"https://example.com/page\",\"reuse\":\"prefer\",\"match\":{\"ignoreSearch\":true}}'", "tab_open --payload '{\"url\":\"https://m.example.com\",\"emulation\":{\"preset\":\"iphone-17-pro\"}}'", "tab_open --payload '{\"url\":\"https://market.m.taobao.com/app/trip/rx-home/pages/home\",\"appProfile\":\"fliggy\"}'", "tab_open --payload '{\"url\":\"https://market.m.taobao.com/app/trip/rx-home/pages/home\",\"appProfile\":\"fliggy\",\"emulation\":{\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}}'", "tab_open --payload '{\"url\":\"https://example.com\",\"appProfile\":\"fliggy\",\"os\":\"android\"}'", "tab_open --payload '{\"url\":\"https://example.com\",\"group\":\"验证任务\"}'"];
+    readonly examples: ["tab_open --payload '{\"url\":\"https://example.com\"}'", "tab_open --payload '{\"url\":\"https://example.com/page\",\"reuse\":\"prefer\",\"match\":{\"ignoreSearch\":true}}'", "tab_open --payload '{\"url\":\"https://m.example.com\",\"emulation\":{\"preset\":\"iphone-17-pro\"}}'", "tab_open --payload '{\"url\":\"https://example.com/app/home\",\"appProfile\":\"fliggy\"}'", "tab_open --payload '{\"url\":\"https://example.com/app/home\",\"appProfile\":\"fliggy\",\"emulation\":{\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}}'", "tab_open --payload '{\"url\":\"https://example.com\",\"appProfile\":\"fliggy\",\"os\":\"android\"}'", "tab_open --payload '{\"url\":\"https://example.com\",\"group\":\"验证任务\"}'"];
 }, {
     readonly name: "tab_close";
     readonly description: "关闭指定标签页";
@@ -1055,7 +1055,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["set_device_emulation --payload '{\"tabId\":12345,\"enabled\":true,\"preset\":\"iphone-17-pro\"}'", "set_device_emulation --payload '{\"tabId\":12345,\"enabled\":true,\"preset\":\"pixel-11\",\"orientation\":\"landscape\"}'", "set_device_emulation --payload '{\"tabId\":12345,\"enabled\":true,\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}'", "set_device_emulation --payload '{\"tabId\":12345,\"enabled\":false}'"];
 }, {
     readonly name: "set_app_profile";
-    readonly description: "设置 App 客户端环境与 JSBridge；可同时设置 MTop 页面接口环境，传 emulation 时联动设备模拟";
+    readonly description: "设置已安装的 App 档案；完整 JSBridge 由能力包提供。可同时设置 MTop 页面接口环境，传 emulation 时联动设备模拟";
     readonly summary: "设置或清除目标标签页的 App 容器模拟";
     readonly params: [{
         readonly name: "enabled";
@@ -1093,7 +1093,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "mtopEnv";
         readonly type: "\"default\" | \"prod\" | \"pre\"";
-        readonly description: "可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。扩展模式全局生效，CDP 模式仅作用于目标 tab";
+        readonly description: "可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。仅作用于目标 tab";
     }, {
         readonly name: "emulation";
         readonly type: "object";
@@ -1153,7 +1153,7 @@ export declare const COMMANDS: readonly [{
     }];
     readonly notes: readonly ["只读取指定非分区 Cookie，不列举全部、不回退分区 Cookie，拒绝 HttpOnly；禁止读取认证 Token。指定 url 不导航，指定 tabId 仅选择存储区时不启动采集。"];
     readonly result: readonly ["找到时 found=true 并返回 value/domain/path；不存在时 found=false。"];
-    readonly examples: ["get_cookie --payload '{\"tabId\":12345,\"name\":\"feature_flag\"}'", "get_cookie --payload '{\"url\":\"https://www.taobao.com/\",\"name\":\"tracknick\"}'", "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 examples: ["get_cookie --payload '{\"tabId\":12345,\"name\":\"feature_flag\"}'", "get_cookie --payload '{\"url\":\"https://www.taobao.com/\",\"name\":\"tracknick\"}'", "get_cookie --payload '{\"tabId\":12345,\"name\":\"feature_channel\",\"domain\":\"example.com\"}'", "get_cookie --payload '{\"tabId\":12345,\"name\":\"tracknick\",\"url\":\"https://www.taobao.com/\",\"domain\":\"example.com\",\"path\":\"/\"}'"];
 }, {
     readonly name: "set_cookie";
     readonly description: "在目标浏览器设置一个指定非分区 session Cookie，可选刷新指定页面";
@@ -1190,7 +1190,7 @@ export declare const COMMANDS: readonly [{
     }];
     readonly notes: readonly ["仅写非分区 session Cookie，不支持删除。reload=true 时校验目标域与刷新页域的授权。"];
     readonly result: readonly ["返回 url/name/domain/path/reloaded，指定标签页时包含 tabId；不回显 Cookie 值。"];
-    readonly examples: ["set_cookie --payload '{\"tabId\":12345,\"name\":\"feature_flag\",\"value\":\"enabled\"}'", "set_cookie --payload '{\"url\":\"https://www.taobao.com/\",\"name\":\"feature_flag\",\"value\":\"enabled\"}'", "set_cookie --payload '{\"tabId\":12345,\"name\":\"edith_switch_br.rx-vehicle-search_home\",\"value\":\"3.6.63\",\"domain\":\"taobao.com\",\"reload\":true}'"];
+    readonly examples: ["set_cookie --payload '{\"tabId\":12345,\"name\":\"feature_flag\",\"value\":\"enabled\"}'", "set_cookie --payload '{\"url\":\"https://www.taobao.com/\",\"name\":\"feature_flag\",\"value\":\"enabled\"}'", "set_cookie --payload '{\"tabId\":12345,\"name\":\"feature_channel\",\"value\":\"3.6.63\",\"domain\":\"example.com\",\"reload\":true}'"];
 }, {
     readonly name: "page_frames";
     readonly description: "获取页面主 frame 与所有 iframe 列表";
@@ -1211,7 +1211,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "需要授权的域名，如 example.com";
     }];
-    readonly notes: readonly ["domain 使用纯主机名，不传 URL。仅在非 BUC send_request 报域权限缺失时申请，BUC 不使用浏览器域权限。", "弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。"];
+    readonly notes: readonly ["domain 使用纯主机名，不传 URL。在 send_request 或 set_rule 提示缺少浏览器域名权限时申请。", "弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。"];
     readonly result: readonly ["返回 granted、domain，授权成功时包含 origin。"];
     readonly examples: ["request_domain_permission --payload '{\"domain\":\"example.com\"}'"];
 }, {