@mearl/setup 2.22.0 → 3.0.0-beta.1

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,22 +1,24 @@
 # @mearl/setup
 
+3.0 当前以 beta 发行。使用 `@beta` 入口安装同版本的 setup、运行包和扩展；正式版 `latest` 保留 2.22。组织能力由独立 preset 分发。
+
 Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全局安装 setup：
 
 ```bash
-npx @mearl/setup [install] [--local] [--cloud|--qoder-cloud] [--mcp]
-npx @mearl/setup update [--local] [--cloud|--qoder-cloud] [--mcp]
-npx @mearl/setup uninstall [--local] [--cloud|--qoder-cloud] [--mcp] [--full]
-npx @mearl/setup extension [--full] [--force]
-npx @mearl/setup plugin [name] <path>
-npx @mearl/setup plugin install <ali-skills add 参数...>
-npx @mearl/setup plugin uninstall <name>
-npx @mearl/setup provider <install|update|uninstall> <package|id>
+npx @mearl/setup@beta [install] [--local] [--cloud|--qoder-cloud] [--mcp]
+npx @mearl/setup@beta update [--local] [--cloud|--qoder-cloud] [--mcp]
+npx @mearl/setup@beta uninstall [--local] [--cloud|--qoder-cloud] [--mcp] [--full]
+npx @mearl/setup@beta extension [--full] [--force]
+npx @mearl/setup@beta plugin [name] <path>
+npx @mearl/setup@beta plugin install <skills add 参数...>
+npx @mearl/setup@beta plugin uninstall <name>
+npx @mearl/setup@beta provider <install|update|uninstall> <package|id>
 ```
 
 浏览器 Provider 独立安装和演进。安装后运行 `mearl <providerId>` 查看该版本声明的能力、
 配置和启动参数。
 
-在 Qoder Cloud Agent 环境中，使用 `npx @mearl/setup --qoder-cloud --yes` 选择 Qoder
+在 Qoder Cloud Agent 环境中，使用 `npx @mearl/setup@beta --qoder-cloud --yes` 选择 Qoder
 配对模式。它与 `--cloud` 安装同一套 cloud-server、client 和 Skill，只把 cloud-server
 模式记录为 Qoder；`mearl-cloud-server` 的命令交互保持不变，`start` 和 `restart` 输出新的
 配对指令后退出，不监听端口或保留守护进程。配对 URL 不包含 Qoder PAT。
@@ -26,34 +28,25 @@ npx @mearl/setup provider <install|update|uninstall> <package|id>
 一个命令安装 skill 并注册它的 CLI、SDK 和 MCP 能力：
 
 ```bash
-npx @mearl/setup plugin install trip/mearl --skill yuque-doc-fetch --yes
-mearl yuque read "https://aliyuque.antfin.com/group/book/doc"
+npx @mearl/setup@beta plugin install https://github.com/F-loat/mearl/tree/v3.0.0-beta.1 --skill browser-tab-manager --yes
+mearl tabs summary
 ```
 
-安装参数透传给 `npx -y ali-skills add`，统一使用全局 symlink 安装；不接受会截断后置选项的 `--` 参数分隔符，
-确保 skill 存放在 `~/.agents/skills` 并共享给所选 agent。安装日志实时显示，保留交互；
-setup 从 `Installed … skill(s)` 成功区块提取路径，仅注册本次安装且包含 `scripts/main.mjs` 或 `scripts/main.py` 的 skill；两者同时存在时使用 JavaScript 入口。
-普通 skill 正常安装。输出格式无法识别时提示手动注册，不扫描其他 skill 或猜测安装结果。
+安装参数传给固定版本的公共 Skills CLI（当前 skills@1.5.0，兼容项目的 Node 最低版本），使用全局共享目录。公共 CLI 的默认 symlink 和复制模式都可注册；复制模式通过 list --global --json 确认本次成功结果对应的 canonical path，不猜测目录，也不扫描其他 Skills。自定义 CLI 可通过 MEARL_SKILLS_PATH 指定。参数不接受截断后置选项的 -- 分隔符。
 
-默认 `install` 和 `update` 会用最多 5 秒的 `npm ping` 检查阿里内网 registry。
-registry 可访问时通过 Ali Skills 批量处理 `mearl` 与 `tdbank-account`：安装使用一次
-`add` 并注册 TDBank 插件，更新已跟踪项使用一次 `update`；卸载时使用一次 `remove` 批量移除 setup 管理的 Skill。
-更新发现 TDBank 插件缺少注册时，会在批量更新已跟踪项后通过一次 `add` 补装并恢复注册。
-该 registry 不用于下载插件。
-探测不可用时按普通外网流程只处理 Mearl Skill；内网批量命令失败时 setup 失败，不再逐项重试。
-`--skip-skill` 和 `--target-line` 安装不执行自动插件步骤。
+安装宿主提供的本地插件目录决定哪些能力由 preset 管理。install/update 只维护该目录中的托管注册，保留用户自行注册的同名插件；普通外网环境没有组织专属名单，也不探测组织 registry。卸载最后一个依赖环境时移除托管插件与 Mearl Skill；其他环境仍需要时保留。--skip-skill 与版本线安装维持原有跳过规则。整套 preset 准备、权限、宿主同步及实际安装状态通过统一安装合同处理。
 
-Mearl client 内置 `buc`、`authx` 与 `tdbank` 的安装来源。CLI、SDK、MCP 或另一个插件首次调用尚未注册的这些插件时，会通过内部幂等流程安装并重试一次；其他未注册名称不会触发安装。BUC 与 AuthX 不随 setup 预装。
+Native preset 批次新建的插件注册使用 setup 托管归属，后续通过 Agent 更新仍保留该归属；同目录已有的用户注册保持原归属，自定义用户别名也会保留。托管卸载遇到用户别名共用同一 Skill 时，只清除托管注册并保留 Skill 文件。
 
 自动注册默认使用安装目录名；入口可声明 `name` 指定简短命令名。
 重装会刷新同名绑定。JavaScript 入口必须默认导出 `register(app)`，Python 入口必须导出 `register(app)` 函数；完整协议见
-[Skill 插件规范](../skills/mearl-skill-creator/references/cli-plugin.md)。
+[插件运行时合同](../../docs/plugin-runtime.md)。
 
 已通过其他渠道分发的 skill 或自定义入口，可以直接传入路径注册：
 
 ```bash
-npx @mearl/setup plugin /absolute/path/to/yuque-doc-fetch
-npx @mearl/setup plugin custom ./skills/custom/entry.mjs
+npx @mearl/setup@beta plugin /absolute/path/to/browser-tab-manager
+npx @mearl/setup@beta plugin custom ./skills/custom/entry.mjs
 ```
 
 path 接受目录或具体文件；目录默认读取 `scripts/main.mjs` 或 `scripts/main.py`，相对路径基于调用工作目录解析。插件名优先使用显式 name，其次读取入口的 `name` metadata，最后回退到 Skill 目录名；常规注册只传 path，显式 name 仅用于覆盖或兼容旧入口。Python 插件要求 `python3 >= 3.9`，可通过 `MEARL_PYTHON` 指定解释器路径；setup 只验证入口可加载，不安装 Python，也不执行 `pip install`。
@@ -61,17 +54,17 @@ path 接受目录或具体文件；目录默认读取 `scripts/main.mjs` 或 `sc
 两种注册流程都会检查本机 `@mearl/client` 和 `@mearl/native-host`：缺失或低于当前 setup 版本时，
 复用已有包管理器安装 setup 的对应版本，更新后再次验证；更高版本保持不动。
 native-host 会幂等初始化 Skills 模式。基础环境补齐或初始化失败时保留已安装的 skill，并停止注册。
-注册后可在任意目录运行 `mearl <name> --help`，也可通过 `@mearl/client` 的 `invokePlugin` 或 MCP 的 `plugin_invoke` 工具调用。已注册插件的日常调用不执行安装或版本检查；只有缺失的 `buc`、`authx` 或 `tdbank` 会触发一次按需安装。
+注册后可在任意目录运行 `mearl <name> --help`，也可通过 `@mearl/client` 的 `invokePlugin` 或 MCP 的 `plugin_invoke` 工具调用。已注册插件的日常调用不执行安装或版本检查；只有已选目录中的缺失插件会触发一次按需安装。
 
 不再需要插件时执行：
 
 ```bash
-npx @mearl/setup plugin uninstall yuque
+npx @mearl/setup@beta plugin uninstall tabs
 ```
 
 若入口位于 `~/.agents/skills/<skill>/`，setup 会先执行
-`ali-skills remove <skill> --global --yes`，成功后清除该 Skill 对应的全部插件注册；
-入口目录已被手动删除时会让 Ali Skills 仍能识别本次移除，从而一并清理其跟踪记录。
+`skills remove <skill> --global --yes`，成功后清除该 Skill 对应的全部插件注册；
+入口目录已被手动删除时会让 Skills 仍能识别本次移除，从而一并清理其跟踪记录。
 移除失败时保留注册以便重试。手工注册的其他路径只解除 Mearl 注册，不删除源码。
 重复卸载未注册名称会成功返回，不产生改动。
 
@@ -82,13 +75,12 @@ Provider 由 npm 包分发，但包本身无需暴露 CLI 或安装脚本。setu
 可创建的浏览器类型名称及其表单参数：
 
 ```bash
-npx @mearl/setup provider install @ali/mearl-provider-brow
-npx @mearl/setup provider update brow
-npx @mearl/setup provider uninstall brow
+npx @mearl/setup@beta provider install @example/mearl-provider-device
+npx @mearl/setup@beta provider update example-device
+npx @mearl/setup@beta provider uninstall example-device
 ```
 
-安装参数接受包名、版本或 dist-tag；更新和卸载可使用 `providerId` 或完整包名。`@ali/*` 包的
-安装和更新固定使用 `https://registry.anpm.alibaba-inc.com/`。安装沿用启动 setup 的包管理器，
+安装参数接受包名、版本或 dist-tag；更新和卸载可使用 providerId 或完整包名。核心 @mearl 包固定使用公共 npm registry；其余 scope 沿用调用方的包管理器配置，组织 registry 由能力安装引导提供。安装沿用启动 setup 的包管理器，
 更新和卸载沿用当前 Provider 的原包管理器。Provider 登记只保存
 经过校验的包名、安装目录和包内入口；不接受包自行注入启动命令、参数、工作目录或环境变量。
 卸载仅在包管理器成功移除包后清除登记，以便失败时可以重试。
@@ -96,8 +88,8 @@ npx @mearl/setup provider uninstall brow
 ## 行为
 
 - Mearl 自有 npm 包的安装和更新固定使用 `https://registry.npmjs.org/`，与最新版本查询使用同一来源；第三方包沿用当前包管理器的源配置。
-- `install` 可以省略；直接执行 `npx @mearl/setup` 等同于 `npx @mearl/setup install`。
-  以选项开头时也默认安装，例如 `npx @mearl/setup --cloud --yes`。
+- `install` 可以省略；直接执行 `npx @mearl/setup@beta` 等同于 `npx @mearl/setup@beta install`。
+  以选项开头时也默认安装，例如 `npx @mearl/setup@beta --cloud --yes`。
 - `install` 未指定环境时默认 `--local`。
 - `-h` / `--help` 显示帮助，`-v` / `--version` 显示 setup 版本。
 - `update` 和 `uninstall` 未指定环境时，从当前 `PATH` 中的
@@ -113,23 +105,23 @@ npx @mearl/setup provider uninstall brow
   新配对但不起服务；卸载前均调用 `stop`。
 - local/cloud 共用一份 `@mearl/client`；组合安装只处理一次，卸载单个环境时若另一个环境仍在使用则保留。
 - 从 2.5.x 更新 cloud 环境时会先卸载旧 `@mearl/cloud-client`，避免它遗留的 `mearl` bin 与统一 client 冲突。
-- local/cloud 共用的全局 mearl skill 通过 `ali-skills` 的 JSON 清单定位，只处理一次。
-- 安装始终通过 `ali-skills add` 以 symlink 方式写入最新的全局 mearl skill，并关联当前检测到的 Agent；
+- local/cloud 共用的全局 mearl skill 通过 `skills` 的 JSON 清单定位，只处理一次。
+- 安装和更新通过 `skills add` 从公开仓库重新安装全局 mearl skill，并关联当前检测到的 Agent；更新须确认本次安装完成并核对全局 JSON 清单，不能仅依据第三方更新命令的退出码。
   可用 `--skip-skill` 跳过。
 - 卸载一个环境但另一个仍依赖全局 mearl skill 时会保留 skill。
+- 已选择 preset 的自动维护保留用户注册；托管卸载遇到同目录的用户别名时只移除托管注册并保留共享 Skill。
 - `uninstall --full` 在环境卸载之外，还会逐项卸载所有已注册 CLI 插件与浏览器 Provider。
-  Ali Skills 安装的插件会同时移除 Skill；手工注册的外部插件只清除注册、保留源码；Provider
+  Skills 安装的插件会同时移除 Skill；手工注册的外部插件只清除注册、保留源码；Provider
   只有在包管理器成功卸载 npm 包后才清除注册。单项失败不阻止其他项继续清理，命令最终返回非零。
   该选项不删除 Chrome 扩展；`extension --full` 仍表示安装扩展及完整本地环境。
 - `uninstall --full` 在所有环境、插件与 Provider 成功移除后统一收尾：停止插件执行服务，
-  确认没有活跃或退出状态未明的任务，再删除任务历史、源码快照、服务日志、AuthX SDK 缓存、
-  旧设计稿缓存和已结束宿主的页面会话文件。只卸载部分环境、单项失败或服务重新启动时保留共享缓存。
+  确认没有活跃或退出状态未明的任务，再删除任务历史、源码快照、服务日志和已结束宿主的页面会话文件。只卸载部分环境、单项失败或服务重新启动时保留共享缓存。
   即使包和注册已移除，也可以再次运行该命令完成缓存收尾。自定义 `MEARL_PLUGIN_DIR` 只清理该注册表的执行缓存。
   记事本、迭代记录、配置与身份、插件持久状态、Provider 私有数据、浏览器配置及用户导出的设计稿均保留；
   CDP 标签 ID 计数也保留，防止旧请求命中新标签。
 - `--mcp` 的客户端配置和清理由 `@mearl/mcp-server` 自己的命令完成。
 - 默认的 `install` / `update` 不处理浏览器扩展。`extension` 是独立命令：从
-  `https://mearl.alibaba-inc.com/` 识别并下载最新的 `mearl-chrome-v*.zip`，原子解压到
+  `https://github.com/F-loat/mearl/releases/download/v3.0.0-beta.1/` 读取同版本 beta 扩展发行元数据（正式 setup 使用 `releases/latest/download/`）并下载对应的 `mearl-chrome-v*.zip`，原子解压到
   `~/.mearl/chrome-extension`。首次安装通过浏览器级 CDP 的 `Extensions.loadUnpacked`
   加载；后续更新由 `mearl check --local --json` 确认当前扩展仍来自 setup 管理目录后，直接替换
   文件并通过 Native Host 触发扩展 reload。固定目录和 manifest 中的 `key` 保证扩展 ID
@@ -145,19 +137,19 @@ npx @mearl/setup provider uninstall brow
 ## 安装或更新浏览器扩展
 
 ```bash
-npx @mearl/setup extension
+npx @mearl/setup@beta extension
 ```
 
 首次使用时可一次安装完整的本地浏览器环境：
 
 ```bash
-npx @mearl/setup extension --full
+npx @mearl/setup@beta extension --full
 ```
 
 首次安装、旧版 setup 扩展首次迁移，或 Native Host reload 不可用时才需要 CDP。如果
 Chrome 尚未开放 CDP，交互命令会提示打开
 `chrome://inspect/#remote-debugging`、启用远程调试并允许连接，然后等待安装完成。面向人的
-安装指引不要添加 `--yes`。无 TTY 环境使用 `npx @mearl/setup extension --yes`；它只尝试
+安装指引不要添加 `--yes`。无 TTY 环境使用 `npx @mearl/setup@beta extension --yes`；它只尝试
 一次，CDP 不可用时立即中断。无法确认 setup 管理来源且 CDP 不可用时不会下载或修改插件
 目录，打开 CDP 后重新执行同一命令即可。Chrome 版本过低、缺少扩展安装所需的 CDP 方法时，
 命令会中断并提示升级 Chrome。
@@ -187,7 +179,7 @@ DevTools 面板的设置按钮会显示红点，快捷设置中提供“立即
 
 自动更新不会降级较新的 Host，也不会改动 cloud、MCP 或独立安装的 Mearl Skill。
 目标 npm 版本尚未发布、网络不可用或更新失败时，旧 Host 会继续运行；下一次扩展后台
-生命周期可重新尝试，也可手动执行 `npx @mearl/setup update --local`。
+生命周期可重新尝试，也可手动执行 `npx @mearl/setup@beta update --local`。
 
 ## 人工与 Agent 使用
 
@@ -205,38 +197,46 @@ DevTools 面板的设置按钮会显示红点，快捷设置中提供“立即
 npx @mearl/setup
 
 # 与上一条等价
-npx @mearl/setup install
+npx @mearl/setup@beta install
 
 # Agent / CI 无交互安装
-npx @mearl/setup --yes
+npx @mearl/setup@beta --yes
 
 # 安装云端 Agent 环境
-npx @mearl/setup --cloud
+npx @mearl/setup@beta --cloud
 
 # 同一台机器同时作为本地浏览器宿主和云端 Agent
-npx @mearl/setup --local --cloud
+npx @mearl/setup@beta --local --cloud
 
 # 自动更新当前 PATH 中检测到的全部 Mearl 环境
-npx @mearl/setup update
+npx @mearl/setup@beta update
 
 # 独立安装或更新到最新浏览器扩展
-npx @mearl/setup extension
+npx @mearl/setup@beta extension
 
 # 安装完整本地环境（client、Native Host、Skill 和扩展）
-npx @mearl/setup extension --full
+npx @mearl/setup@beta extension --full
 
 # 只卸载本地环境
-npx @mearl/setup uninstall --local
+npx @mearl/setup@beta uninstall --local
 
 # 自动检测并无交互卸载
-npx @mearl/setup uninstall --yes
+npx @mearl/setup@beta uninstall --yes
 
 # 卸载环境，并清理全部 CLI 插件与 Provider
-npx @mearl/setup uninstall --full
+npx @mearl/setup@beta uninstall --full
 
 # 安装可选浏览器 Provider
-npx @mearl/setup provider install @ali/mearl-provider-brow
-npx @mearl/setup provider install @ali/mearl-provider-agentbay
+npx @mearl/setup@beta provider install @example/mearl-provider-device
+npx @mearl/setup@beta provider install @example/mearl-provider-cloud
 ```
 
 原有 Mearl 环境包的 npm/npx 安装方式和 CLI 保持可用；setup 是统一的便利入口。
+
+## Preset 安装
+
+`mearl-setup preset apply <source-url-or-path>` 准备确切资源、激活本机 Node 选择，并向兼容扩展同步同一批浏览器资源；`preset update` 保留用户覆盖，`preset status` 只读检查实际就绪状态。退出码 3 表示存在待同步/安装组件。完整扩展、默认设置、Skills/Provider 和网页一键安装使用同一实际状态核验，见 [本机安装合同](../../docs/preset-installation.md)。
+
+普通 install/update 在替换包前保存选中 preset 的确切资源和期望选择，运行时初始化后再同步宿主和安装 Skills；`extension --full` 也在替换扩展前完成准备。已有本机 preset 优先保留，显式 `--preset` 可更新或修复资源；检测到已安装包为 3.0 以前版本且尚无选择时，读取公共部署目录的 `legacyPreset`。配置或资源不可用会在包变更前停止，不回退到无内部能力的安装。部分升级后的重试使用已保存安装记录，即使包版本已变为 3.x 也不重新下载。维护旧版本线和卸载不自动迁移。
+
+默认目录为公共站点的 `installation.json`，可通过 `MEARL_INSTALLATION_CONFIG_URL` 指定其他 HTTPS 目录（本地验证允许回环 HTTP）。核心不包含组织 ID 或私有来源；目录沿用网页安装的校验合同。本机与浏览器未全部确认时仍报告 pending，准备成功不表示已发行或已完成真实企业授权验收。

package/dist/browserExtension.d.ts

@@ -1,5 +1,5 @@
-export declare const MEARL_EXTENSION_DOWNLOAD_PAGE = "https://mearl.alibaba-inc.com/";
-export declare const MEARL_EXTENSION_REMOTE_CONFIG_URL = "https://mearl.alibaba-inc.com/config.json";
+export declare const MEARL_EXTENSION_DOWNLOAD_PAGE: string;
+export declare const MEARL_EXTENSION_REMOTE_CONFIG_URL: string;
 export declare const MEARL_EXTENSION_DIRECTORY_NAME = "chrome-extension";
 export declare const MEARL_EXTENSION_ID = "aoehhjnofngknnjefamjbplchbolghkm";
 export declare const MEARL_EXTENSION_SETUP_MARKER = ".mearl-setup.json";

package/dist/browserExtension.js

@@ -1,3 +1,5 @@
+import { SETUP_VERSION } from './setupVersion.js';
+import { readExtensionReleaseVersion } from '@mearl/browser-core';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -7,8 +9,12 @@ import { CLIENT_VERSION, invoke as invokeLocalMearl } from '@mearl/client/local'
 import extractZip from 'extract-zip';
 import WebSocket from 'ws';
 import { compareMearlReleaseVersions, isMearlReleaseVersion } from './version.js';
-export const MEARL_EXTENSION_DOWNLOAD_PAGE = 'https://mearl.alibaba-inc.com/';
-export const MEARL_EXTENSION_REMOTE_CONFIG_URL = `${MEARL_EXTENSION_DOWNLOAD_PAGE}config.json`;
+export const MEARL_EXTENSION_DOWNLOAD_PAGE = SETUP_VERSION.includes('-beta.')
+    ? `https://github.com/F-loat/mearl/releases/tag/v${SETUP_VERSION}`
+    : 'https://github.com/F-loat/mearl/releases/latest';
+export const MEARL_EXTENSION_REMOTE_CONFIG_URL = SETUP_VERSION.includes('-beta.')
+    ? `https://github.com/F-loat/mearl/releases/download/v${SETUP_VERSION}/config.json`
+    : 'https://github.com/F-loat/mearl/releases/latest/download/config.json';
 export const MEARL_EXTENSION_DIRECTORY_NAME = 'chrome-extension';
 export const MEARL_EXTENSION_ID = 'aoehhjnofngknnjefamjbplchbolghkm';
 export const MEARL_EXTENSION_SETUP_MARKER = '.mearl-setup.json';
@@ -46,13 +52,16 @@ export function extensionArchiveUrl(version) {
     if (!isMearlReleaseVersion(version)) {
         throw new Error(`Invalid Mearl browser extension version: ${version}`);
     }
-    return new URL(`mearl-chrome-v${version}.zip`, MEARL_EXTENSION_DOWNLOAD_PAGE).toString();
+    return `https://github.com/F-loat/mearl/releases/download/v${version}/mearl-chrome-v${version}.zip`;
 }
 function validateExtensionRelease(release) {
     if (!isMearlReleaseVersion(release.version)) {
         throw new Error('Remote extension config has an invalid latestVersion');
     }
-    const expectedArchiveUrl = extensionArchiveUrl(release.version);
+    const configSource = process.env.MEARL_EXTENSION_CONFIG_URL;
+    const expectedArchiveUrl = configSource && configSource !== MEARL_EXTENSION_REMOTE_CONFIG_URL
+        ? new URL(`mearl-chrome-v${release.version}.zip`, configSource).toString()
+        : extensionArchiveUrl(release.version);
     let archiveUrl;
     try {
         archiveUrl = new URL(release.archiveUrl).toString();
@@ -73,7 +82,7 @@ function validateExtensionRelease(release) {
     };
 }
 export async function fetchBrowserExtensionRelease(fetchImpl = fetch) {
-    const response = await fetchImpl(MEARL_EXTENSION_REMOTE_CONFIG_URL, { cache: 'no-store' });
+    const response = await fetchImpl(process.env.MEARL_EXTENSION_CONFIG_URL || MEARL_EXTENSION_REMOTE_CONFIG_URL, { cache: 'no-store' });
     if (!response.ok) {
         throw new Error(`Extension config returned HTTP ${response.status}`);
     }
@@ -84,16 +93,6 @@ export async function fetchBrowserExtensionRelease(fetchImpl = fetch) {
         version: typeof config.latestVersion === 'string' ? config.latestVersion : '',
     });
 }
-async function resolveExtensionArchive(fetchImpl) {
-    const response = await fetchImpl(MEARL_EXTENSION_DOWNLOAD_PAGE, { redirect: 'follow' });
-    if (!response.ok) {
-        throw new Error(`Extension release page returned HTTP ${response.status}`);
-    }
-    const version = findLatestExtensionVersion(await response.text());
-    if (!version)
-        throw new Error('No Mearl browser extension archive was found on the release page');
-    return { version, archiveUrl: extensionArchiveUrl(version) };
-}
 function readDevToolsActivePort(userDataDirectory) {
     try {
         const content = fs
@@ -282,12 +281,19 @@ async function inspectInstallationWithConnection(connection) {
             typeof installed.version !== 'string') {
             throw new Error('Chrome returned incomplete Mearl extension metadata');
         }
+        let version = installed.version;
+        try {
+            const manifest = JSON.parse(fs.readFileSync(path.join(installed.path, 'manifest.json'), 'utf8'));
+            if (manifest.version === installed.version)
+                version = readExtensionReleaseVersion(manifest) ?? version;
+        }
+        catch { }
         return {
             id: MEARL_EXTENSION_ID,
             location: installed.location,
             name: installed.name,
             path: installed.path,
-            version: installed.version,
+            version,
         };
     }
     finally {
@@ -403,7 +409,7 @@ function readExtensionManifest(directory) {
         parsed.key.length === 0) {
         throw new Error('Downloaded archive is not a valid Manifest V3 extension');
     }
-    if (!isMearlReleaseVersion(parsed.version)) {
+    if (!readExtensionReleaseVersion(parsed)) {
         throw new Error('Downloaded extension manifest has an invalid version');
     }
     return parsed;
@@ -437,7 +443,7 @@ async function downloadAndReplaceExtension(releaseInput, targetDirectory, fetchI
         await fs.promises.mkdir(stagingDirectory, { recursive: true });
         await extractArchive(archivePath, stagingDirectory);
         const manifest = readExtensionManifest(stagingDirectory);
-        if (manifest.version !== release.version) {
+        if (readExtensionReleaseVersion(manifest) !== release.version) {
             throw new Error(`Extension archive version ${String(manifest.version)} does not match ${release.version}`);
         }
         await writeSetupMarker(stagingDirectory, targetDirectory);
@@ -475,7 +481,7 @@ export async function installMearlBrowserExtension(options = {}, dependencies =
     const targetDirectory = path.resolve(options.targetDirectory ?? resolveMearlExtensionDirectory());
     const release = options.release
         ? validateExtensionRelease(options.release)
-        : await resolveExtensionArchive(fetchImpl);
+        : await fetchBrowserExtensionRelease(fetchImpl);
     const chromeUserDataDirectory = options.chromeUserDataDirectory ?? resolveChromeUserDataDirectory();
     const waitForCdpMs = Math.max(0, options.waitForCdpMs ?? 0);
     const useSharedCdpSession = !dependencies.inspectInstallation && !dependencies.loadUnpacked;

package/dist/cli.d.ts

@@ -4,13 +4,17 @@ import { runMearlLifecycle, type MearlLifecycleOperation } from './lifecycle.js'
 import type { MearlProfile } from './profiles.js';
 import { ensureOfficialPlugin, installPlugins, setupPlugin, uninstallPlugin } from './plugin.js';
 import { installProviderPackage, uninstallProviderPackage, updateProviderPackage } from './provider.js';
-export declare const SETUP_VERSION: string;
+import { runPresetCommand } from './preset.js';
+import { prepareSetupPreset } from './presetUpgrade.js';
+export { SETUP_VERSION } from './setupVersion.js';
 interface ParsedArgs {
     cloudMode?: 'websocket' | 'qoder';
     force?: boolean;
     full?: boolean;
     help: boolean;
-    operation?: MearlLifecycleOperation | 'extension' | 'plugin' | 'provider';
+    operation?: MearlLifecycleOperation | 'extension' | 'plugin' | 'provider' | 'preset';
+    presetCommand?: 'apply' | 'update' | 'status';
+    presetSource?: string;
     pluginName?: string;
     pluginPath?: string;
     pluginInstallArgs?: string[];
@@ -25,6 +29,8 @@ interface ParsedArgs {
     yes: boolean;
 }
 export interface SetupCliDependencies {
+    preparePreset?: typeof prepareSetupPreset;
+    runPreset?: typeof runPresetCommand;
     registerPlugin?: typeof setupPlugin;
     ensureOfficialPlugin?: typeof ensureOfficialPlugin;
     installPlugins?: typeof installPlugins;
@@ -37,4 +43,3 @@ export interface SetupCliDependencies {
 }
 export declare function parseSetupArgs(argv: string[]): ParsedArgs;
 export declare function main(argv?: string[], interactiveTerminal?: boolean, dependencies?: SetupCliDependencies): Promise<number>;
-export {};