@mearl/client 2.21.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,7 +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，并固定全局共享安装。
+setup 会补齐缺失或低于自身版本的 client、native-host；安装参数由 setup 的 Skills 安装器处理，并固定全局共享安装。
 
 需要单独检查插件时运行 `mearl <name> --version`。命令会解析注册记录并加载入口，但不连接浏览器；
 退出码为 0 表示插件已注册且入口可加载，stdout 返回同目录 `SKILL.md` 的版本，缺少版本元数据时返回 `unknown`。
@@ -220,6 +218,7 @@ setup 会补齐缺失或低于自身版本的 client、native-host；安装参
 使用位置参数和业务选项，`--payload` 不能与前两种形式混用。JSON 保留业务字段类型；正文等文件输入按具体
 skill 的字段约定处理。`browser`、`timeout`、`output` 等宿主选项保留原有含义；同名业务字段以及数字、
 布尔值、对象和数组通过 `--payload` 传入。插件不使用上表中内置 action 的 `--payload-file` 入口。
+业务选项名称支持字母开头的字母、数字和下划线组合，下划线原样传递。
 
 注册后的插件也可从 SDK 调用；实例方法 `client.invokePlugin` 复用既有连接和默认浏览器：
 
@@ -227,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，状态文件放在源码目录之外。
 
@@ -260,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 = {
@@ -347,6 +354,8 @@ Preact、Hooks 和 HTM 运行时。页面从 `window.mearl.ui` 读取 `html`、`
 `--mearl-accent` 等语义变量；主操作按钮使用 `--mearl-action-primary`、
 `--mearl-action-primary-hover` 和 `--mearl-action-primary-text`，以保持与扩展按钮一致。
 
+工具箱面向人，CLI 面向 Agent：复用业务操作、保持结果一致即可，不要求共享中间态。表单草稿、选择、预览等纯 UI 状态默认放浏览器内存；确需刷新或重新打开后恢复时再用浏览器存储。sandbox 页不能假定可直接访问 `localStorage`、IndexedDB 或 `chrome.storage`，应使用宿主提供的能力。只有业务记录、关闭页面后继续的任务、安全重试回执或受消息大小限制的资源传输才需要 Node 状态，并说明其生命周期及清理方式。
+
 需要 BUC 身份的内部 HTTP 接口通过官方 `buc` 插件调用。CLI 使用 `mearl buc request <url> [app]`，业务插件使用
 `app.invoke('buc', { command: 'request', input })`；当前身份和人员资料分别使用 `whoami` 与 `profile`
 子命令。BUC 插件按请求创建一次性凭据，只接受无 URL 凭据的 HTTPS 地址，过滤认证字段与 Cookie；
@@ -377,12 +386,14 @@ AuthX 对应 `mearl authx request <url> [audience]`，省略 `audience` 时同
 
 页面交互动作（`page_click` / `page_drag` / `page_type` / `page_hover` / `page_scroll` / `page_press` / `page_upload`）默认等待异步稳定并返回 `{ action, observation }`。参数、ref 或目标解析在派发前失败时返回 `action.stage: "precondition"`，省略无意义的 `observation` / `diagnostics`；浏览器可能已收到输入但确认超时时返回 `action.stage: "dispatch-uncertain"`，并保留 observation 供核验当前状态。能够在超时前确定的目标、命中、坐标、派发模式和输入序列状态保存在 `action.attempt`，它是诊断证据，不表示动作已经生效。失败时 CLI 退出码为 1。传 `observe: false` 可执行裸动作；需要同一动作期间的新增 error logs 和业务 requests 时传 `diagnostics: true`，埋点通过 `diagnostics.events` 按需开启。`page_eval` 默认裸执行，可按需开启观察或诊断。
 
-`tab_open active:true` 会激活目标 Tab、恢复最小化窗口，并通过 `activation` 返回实际标签页、窗口和 `visibilityState`；依赖可信触摸时先确认页面为 `visible`。页面动作的稳定观察会在有限预算内等待有限时长 CSS 动画。selector/ref 点击遇到嵌套滚动裁剪时会先滚动目标，仍不可见时才以明确的裁剪错误停止。
+`tab_open active:true` 请求激活目标页。扩展免打扰默认开启：HTTP(S) 页面在首次导航前启用后台焦点模拟，不切换标签页或窗口；关闭免打扰才会真实激活并恢复最小化窗口。`activation.mode` 区分 `background` / `foreground`，模拟后的 `visibilityState` 不代表窗口在前台。焦点模拟在交接、释放控制或扩展连接断开时关闭，`preserveEnvironment` 不保留它；交还后按需对同 URL 使用 `reuse:"require", active:true` 再次激活。不带会话时通过 `browser_release` 收尾。纯 CDP 和外部 Provider 遵循各自的激活能力。页面动作的稳定观察会在有限预算内等待有限时长 CSS 动画。selector/ref 点击遇到嵌套滚动裁剪时会先滚动目标，仍不可见时才以明确的裁剪错误停止。
 
 `page_click` 默认 `auto` 在隐藏页使用 DOM fallback，selector、文本、ref 和坐标定位都保持可用，并通过 `dispatchMode: "dom"`、`fallbackReason: "page-hidden"` 明确说明实际路径。普通后台任务不需要为了点击主动激活页面；只有站点明确拒绝非可信事件时才切换到可见页并强制 `mouse` / `touch`。
 
 `observation.effects.interactives` 会把内容未变化但 DOM 节点被框架重建的控件标记为 `recreated`，保留 selector/ref 与语义信息供后续定位，同时省略未变化的 value 和状态字段；值或状态确实变化时仍返回完整差异。
 
+`observation.effects.texts` 按需返回普通可见叶子文本的当前值 `{ selector, text }`，覆盖独立计数、金额等非控件文字。结果最多 8 项，每项 text 最多 160 字符；同一节点连续更新只保留最终值。非空文字的 Range 矩形必须完整处于视口和祖先滚动/裁剪框内，并通过命中检查；CSS 掩码文本不进入该通道。空文本使用元素框检查。结果不作为可交互控件或业务成功信号。复杂结构、不可读内容及预算溢出仍保留快照回退；该通道不改变导航等待策略。
+
 `page_press.pressMode` 支持 `auto` / `dom` / `keyboard`。默认 `auto` 在隐藏页使用 DOM 键盘事件，并通过返回的 `dispatchMode`、`fallbackReason` 和 `defaultAction` 说明实际派发及默认行为模拟结果；依赖浏览器原生编辑、选择或滚动行为时使用可见页面和 `keyboard`。
 
 `page_snapshot` 默认返回完整 AX Tree；长列表可传 `mode: "viewport"`，只需要当前视口内的控件时传 `mode: "interactive"`，AX 信息为空或过于稀疏时可显式传 `mode: "dom"`，返回实际渲染文本、原生控件、显式 role 和高置信 clickable 节点。DOM 模式同样返回可供后续动作使用的 `@ref`，但不会猜测任意容器的业务语义。已知 CSS 区域时传 `rootSelector`，已有 ref 时传 `rootRef`（可用 `ancestorDepth` 向上补充上下文），只查找特定文案或角色时传 `query`。`interactive` 在视口内缺少 AX 控件语义时仍只回退到 AX viewport，并返回 `fallbackMode: "viewport"`，不会自动切换数据来源。`maxNodes` / `maxChars` 截断会同时保留首尾内容。
@@ -418,6 +429,17 @@ debugger/CDP 控制和会话级临时状态，保留浏览器及全部标签页
 
 基础设施组件必须避免递归路由：`@mearl/cloud-connector` 使用 `@mearl/client/local` 子路径直连所在机器的 native-host。普通 Agent、CLI 与 MCP 集成均使用包根入口。
 
+插件代码按职责组织在 `src/plugins/`：
+
+| 目录 | 职责 |
+| --- | --- |
+| `sdk/` | 插件声明、命令接口及页面、模型、状态和恢复声明的校验 |
+| `clients/` | 插件服务连接及任务、模型、页面、状态的调用接口 |
+| `runtime/` | 服务组装、任务调度、存储、代码快照、执行器和进程清理 |
+| 插件目录根部 | 注册、资源打包、官方插件安装及调用端与服务端共享的通信协议 |
+
+测试位于各模块附近的 `__tests__/`。对外通过 `@mearl/client` 和 `@mearl/client/plugin` 导出；包根部的 `plugin.ts` 是插件公开入口。三个进程入口 `plugin-worker.ts`、`plugin-task-host.ts` 和 `pluginModelSessionWorker.ts` 保留在 `src/` 根部，`runtimePaths.ts` 统一定位包版本和进程入口，使逐文件编译与 Native Host 打包使用相同的入口布局。生成协议仍由 `browser-core` 同步到 `src/generated/`。
+
 ## 构建
 
 ```bash
@@ -428,7 +450,7 @@ pnpm typecheck  # 仅类型检查
 
 ## License
 
-ISC
+Apache-2.0
 
 ### 插件页面实例
 
@@ -446,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` 仍保留公开调用能力。
 
@@ -482,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#状态和激活)。二进制资产继续使用文件或资源通道。
 
 ### 显式任务恢复
 
@@ -490,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` 拒绝循环或过深组合。进程树无法确认停止时保留失败记录并拒绝恢复。
 
@@ -502,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/cli.js

@@ -8,7 +8,7 @@ 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, findOfficialPlugin, listPluginNames, listOfficialPluginNames, loadRegisteredPlugin, PluginError, } from './plugin.js';
+import { findPluginEntry, findPluginRegistration, findOfficialPlugin, listPluginNames, listOfficialPluginNames, loadRegisteredPlugin, PluginError, } from './plugins/sdk/plugin.js';
 import { getCloudServerConfigPath, loadCloudServerConfig } from './unifiedConfig.js';
 const TOP_LEVEL_COMMAND_NAME_WIDTH = 22;
 const CATEGORIES = [
@@ -90,6 +90,7 @@ const PLUGIN_HOST_OPTIONS = new Set([
     '--payload',
     '--payload-file',
     '--server',
+    '--session',
     '--timeout',
     '--verbose',
     '--version',
@@ -104,7 +105,7 @@ function findPluginInputOptionNames(args) {
         if (PLUGIN_HOST_OPTIONS.has(option))
             continue;
         const name = option.slice(2);
-        if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(name)) {
+        if (!/^[a-zA-Z][a-zA-Z0-9_]*$/.test(name)) {
             throw new Error(`无效的插件业务选项: ${option}`);
         }
         names.add(name);
@@ -473,7 +474,7 @@ export function parseClientArgs(args, plugin = false) {
         throw new Error('插件业务选项不能与 --payload 同时使用');
     }
     const json = options.json === true;
-    if (json && action !== 'check')
+    if (json && action !== 'check' && !plugin)
         throw new Error('--json 仅适用于 check');
     if (options.updates && action !== 'check')
         throw new Error('--updates 仅适用于 check');