@mearl/setup 3.0.0-beta.8 → 3.0.0

package/README.en.md

@@ -0,0 +1,276 @@
+# @mearl/setup
+
+[简体中文](README.md) | [English](README.en.md)
+
+Use `@3` to select the latest stable 3.x installer and install matching runtime and extension versions.
+
+One-time installation, updates, removal, and configuration for Mearl environments. No global setup installation is needed:
+
+Run `node --version` before installation to verify Node.js >= 20.18.0.
+
+```bash
+npx @mearl/setup@3 [install] [--local] [--cloud] [--cloud-mode <id>] [--mcp]
+npx @mearl/setup@3 update [--local] [--cloud] [--cloud-mode <id>] [--mcp]
+npx @mearl/setup@3 uninstall [--local] [--cloud] [--cloud-mode <id>] [--mcp] [--full]
+npx @mearl/setup@3 extension [--full] [--force]
+npx @mearl/setup@3 extension --extract
+npx @mearl/setup@3 plugin [name] <path>
+npx @mearl/setup@3 plugin install <skills add arguments...>
+npx @mearl/setup@3 plugin uninstall <name>
+npx @mearl/setup@3 provider <install|update|uninstall> <package|id>
+npx @mearl/setup@3 profile install <source> [--browser <id-or-name>]
+npx @mearl/setup@3 preset repair [--replace-skill <name> ...]
+```
+
+Browser Providers install and evolve independently. After installation, run `mearl <providerId>` to inspect that version's capabilities,
+configuration, and launch arguments.
+
+Install optional cloud protocols through a preset before selecting `--cloud-mode <id>`. See [`@mearl/plugin-qoder`](../plugin-qoder/README.en.md) for Qoder pairing; setup does not include or install it by default.
+
+## Install App emulation
+
+```bash
+npx @mearl/setup@3 profile install mearlhq/wechat-profile
+```
+
+The source can be a public GitHub `owner/repo`, `owner/repo@ref`, or a full HTTPS bundle manifest URL. GitHub sources load the root `bundle.json` from the resolved commit. The command installs every App emulation configuration declared by that bundle and preserves the active Preset. When multiple local extensions are connected, select a target with `--browser`. Confirm source access in the extension if prompted.
+
+In the extension's quick settings, open the App selector and choose **Add App emulation** to select an official option or enter a source. The App button opens the installer directly when the list is empty.
+
+## Install and register Skill plugins
+
+Install a Skill and register its CLI, SDK, and MCP capabilities with one command:
+
+```bash
+npx @mearl/setup@3 plugin install https://github.com/mearlhq/mearl --skill browser-tab-manager --yes
+mearl tabs summary
+```
+
+Installation arguments pass to a pinned public Skills CLI (currently skills@1.5.0, compatible with the project's minimum Node version) using the global shared directory. Both default symlink and copy modes support registration. Copy mode uses list --global --json to confirm the canonical path for this successful install, without guessing directories or scanning other Skills. Set MEARL_SKILLS_PATH for a custom CLI. Arguments reject the -- separator, which would truncate trailing options.
+
+The installation host's local plugin catalog determines preset-managed capabilities. install/update maintains managed registrations and preserves user registrations. Removing the last dependent environment removes managed plugins and the Mearl Skill; other dependent environments retain them. Configuration preparation, host synchronization, and actual status share the [installation contract](../../docs/preset-installation.en.md).
+
+New registrations created by Native preset batches are setup-managed and retain that ownership through Agent updates. Existing user registrations in the same directory and custom user aliases retain their ownership. Managed removal encountering user aliases sharing a Skill removes only managed registrations and keeps Skill files.
+
+GUI and CLI share the preset installer and override rules. If a saved installation is incomplete, `preset repair` retries accepted local resources without redownloading the preset or implicitly replacing conflicting sources. Explicit repeated `--replace-skill` authorizes replacing those Skills' sources or same-name plugin registrations for this invocation:
+
+```bash
+npx @mearl/setup@3 preset repair --replace-skill example-skill --replace-skill another-skill
+```
+
+Already installed Skills receive registration repair only; source conflicts reinstall. Unlisted conflicts still block installation, and undeclared tool names or changed installation identities are rejected. Replacement authorization does not persist into later repairs or automatic updates. Missing browser permissions still require extension authorization. Output uses preset JSON: ready exits `0`, pending components `3`, installation failure `1`, and invalid arguments `2`.
+
+Automatic registration defaults to the installation directory name; an entry can declare `name` for a shorter command.
+Reinstallation refreshes same-name bindings. JavaScript entries must default-export `register(app)`; Python entries must export a `register(app)` function. See the
+[plugin runtime contract](../../docs/plugin-runtime.en.md).
+
+Register a Skill distributed elsewhere or a custom entry directly by path:
+
+```bash
+npx @mearl/setup@3 plugin /absolute/path/to/browser-tab-manager
+npx @mearl/setup@3 plugin custom ./skills/custom/entry.mjs
+```
+
+path accepts a directory or file. Directories default to `scripts/main.mjs` or `scripts/main.py`; relative paths resolve against the calling working directory. Plugin names prefer explicit name, then entry `name` metadata, then the Skill directory name. Normal registration needs only path; explicit name is for overrides or older entries. Python requires `python3 >= 3.9`; `MEARL_PYTHON` selects an interpreter. setup validates loading but does not install Python or run `pip install`.
+Registration checks the entry's register function and saves its absolute path. Same-name registration updates the binding.
+Both flows check local `@mearl/client` and `@mearl/native-host`. If absent or older than setup,
+the existing package manager installs setup's matching versions and revalidates. Newer versions remain untouched.
+native-host idempotently initializes Skills mode. If environment completion or initialization fails, the installed Skill remains and registration stops.
+JavaScript plugins may export `setup({ runCommand })` to prepare Skill-owned dependencies before registration. Both installation paths await it, and registration stops on failure. Skills implement their own first-use dependency checks; see the [client contract](../client/README.en.md#skill-plugins).
+
+After registration, run `mearl <name> --help` anywhere, use SDK `invokePlugin`, or MCP `plugin_invoke`. Ordinary calls do not update Skill sources; missing plugins in the selected catalog trigger one on-demand installation. Skill-owned dependencies are prepared by their installation hooks and first-use checks.
+
+To remove a plugin:
+
+```bash
+npx @mearl/setup@3 plugin uninstall tabs
+```
+
+For entries under `~/.agents/skills/<skill>/`, setup first runs
+`skills remove <skill> --global --yes`, then clears all registrations for that Skill on success.
+If the entry directory was manually deleted, Skills can still identify the removal and clean its tracking records.
+Removal failures preserve registrations for retry. Other manually registered paths only unregister from Mearl without deleting source.
+Repeated removal of an unregistered name succeeds without changes.
+
+## Manage browser Providers
+
+Providers ship as npm packages without requiring their own CLI or install scripts. setup uses the current npm package manager
+for global package lifecycle and reads `package.json#mearl.provider` to register the protocol entry,
+browser type name, and form arguments:
+
+```bash
+npx @mearl/setup@3 provider install @example/mearl-provider-device
+npx @mearl/setup@3 provider update example-device
+npx @mearl/setup@3 provider uninstall example-device
+```
+
+Install accepts package names, versions, and dist-tags; update/remove accept providerId or full package name. Core @mearl packages always use public npm; other scopes follow caller package-manager settings. Installation uses the package manager launching setup;
+updates and removal reuse the Provider's original manager. Records contain only
+validated package names, installation directories, and package-local entries. Packages cannot inject launch commands, arguments, working directories, or environment variables.
+Registration clears only after successful package removal, allowing retries.
+
+## Behavior
+
+- Mearl-owned npm packages install and update from `https://registry.npmjs.org/`, matching version queries. Third-party packages use current manager registry settings.
+- `install` is optional: `npx @mearl/setup@3` equals `npx @mearl/setup@3 install`.
+  An initial option also implies installation, such as `npx @mearl/setup@3 --cloud --yes`.
+- `install` defaults to `--local` when no environment is specified.
+- `-h` / `--help` shows help; `-v` / `--version` shows setup's version.
+- Without environment flags, `update` and `uninstall` detect
+  `mearl-native-host`, `mearl-cloud-server`, and `mearl-mcp-server` in the current `PATH` and may process
+  multiple installed environments.
+- Combine `--local`, `--cloud`, and `--mcp` to process only selected environments.
+  `--cloud-mode <id>` also selects cloud and requires an installed mode capability.
+- Existing environments keep their original package manager and global prefix; first installation uses the manager launching setup.
+- `uninstall` recognizes development symlinks installed through `npm link` or `dev:link` into npm global directories,
+  removing packages and command links through the original npm prefix while preserving repository source. Install/update autodetection handles normal global installations only.
+- Cloud manages `@mearl/cloud-server` and `@mearl/client` together. WebSocket mode starts the server after first installation
+  and restarts after updates only if it was running. Other modes use installed `cloud.server.<id>`; all call `stop` before removal.
+- local/cloud share `@mearl/client`. Combined installation processes it once; removing one environment retains it if the other needs it.
+- Updating a 2.5.x cloud environment first removes `@mearl/cloud-client` to avoid its `mearl` bin conflicting with the unified client.
+- local/cloud share the global mearl Skill, located through the Skills JSON inventory and processed once.
+- Install/update reinstalls the global mearl Skill from the public repository through `skills add`, associating detected Agents. Updates must confirm this installation and check the global JSON inventory, not rely only on a third-party updater's exit code.
+  Skip with `--skip-skill`.
+- Removing one environment retains the global mearl Skill if another depends on it.
+- Automatic maintenance of selected presets preserves user registrations. Managed removal keeps shared Skill files when user aliases use the same directory.
+- `uninstall --full` also removes every registered CLI plugin and browser Provider.
+  Skills-installed plugins remove their Skills; manually registered external plugins only unregister, retaining source. Provider
+  registrations clear only after successful npm removal. Individual failures do not block other cleanup, but the final exit is nonzero.
+  This does not remove the Chrome extension. `extension --full` still means installing the extension and complete local environment.
+- After all environments, plugins, and Providers are successfully removed, `uninstall --full` stops the plugin service,
+  confirms no active or uncertain-exit tasks remain, and removes task history, source snapshots, service logs, and page-session files of ended hosts. Partial removal, individual failures, or a restarted service retain shared caches.
+  Rerun to finish cache cleanup even after packages and registrations are gone. Custom `MEARL_PLUGIN_DIR` limits cleanup to that registry's execution cache.
+  Notes, iteration records, settings, identities, plugin persistent state, Provider-private data, browser profiles, and exported designs remain;
+  CDP tab-ID counters also remain so stale requests cannot target new tabs.
+- `@mearl/mcp-server` commands handle `--mcp` client configuration and cleanup.
+- Default `install` / `update` do not manage the browser extension. The separate `extension` command reads
+  matching beta extension metadata from `https://github.com/mearlhq/mearl/releases/download/v<version>/` (stable setup uses `releases/latest/download/`) and downloads `mearl-chrome-v*.zip`, atomically extracting it into
+  `~/.mearl/chrome-extension`. First installation uses browser-level CDP `Extensions.loadUnpacked`;
+  later updates use `mearl check --local --json` to confirm the running extension comes from the setup-managed directory, replace
+  files, and reload through Native Host. The fixed directory and manifest `key` keep the extension ID
+  and browser storage stable.
+- `extension --full` first installs or updates the extension, then uses the local profile to install
+  `@mearl/client`, install and initialize `@mearl/native-host`, and install the global Mearl Skill.
+  Both parts are attempted; any failure returns nonzero while retaining installed components. It does not install
+  cloud or MCP environments.
+- Before downloading, CDP checks the source of an extension with the same ID. Installation proceeds if absent or `UNPACKED`
+  from the fixed directory. Chrome Web Store, enterprise-policy, and other local-directory installations remain by default. Only explicit
+  `--force` takes over and replaces them.
+
+## Install or update the browser extension
+
+For first use, run `npx @mearl/setup@3` and load the matching release ZIP. You can also use the Chrome Web Store when it offers the matching version. [Installation steps](../../README.en.md#install-locally)
+
+Use this command to let setup manage the extension.
+
+```bash
+npx @mearl/setup@3 extension
+```
+
+Add `--full` to also install the local CLI, Native Host, and Skill in the same run.
+
+To load the extension manually, run `npx @mearl/setup@3 extension --extract`. Setup downloads the release ZIP,
+unpacks it into a new directory under `~/.mearl/extension-downloads/`, and prints the full path. Open
+`chrome://extensions/`, enable **Developer mode**, click **Load unpacked**, and select that directory.
+Keep the directory while Chrome uses the extension. This works with Chrome closed and with remote debugging disabled.
+
+Automatic installation uses CDP for first installation, initial migration of older setup extensions, or unavailable Native Host reload. If
+Chrome has not enabled CDP, interactive setup prompts you to open
+`chrome://inspect/#remote-debugging`, enable remote debugging, and allow the connection, then waits for installation. Human-facing
+instructions should omit `--yes`. Without a TTY, use `npx @mearl/setup@3 extension --yes`: it tries
+once and stops immediately if CDP is unavailable. If setup ownership cannot be confirmed and CDP is unavailable, it does not download or modify
+the extension directory. Enable CDP and rerun the same command. If Chrome lacks required extension-installation CDP methods,
+the command stops and asks for a Chrome upgrade.
+
+Each invocation reads the newest extension version from the download page, without requiring it to match setup, CLI, or Native Host.
+CDP source checks and `Extensions.loadUnpacked` reuse one connection to avoid repeated authorization.
+A successful installation saves a setup-management marker. `mearl check --local --json` reads the marker from the running extension too;
+CDP-free updates require matching paths on both sides. If the user later installs the Store version, that running extension
+does not return the marker. setup checks through CDP again and preserves the Store installation
+unless `--force` is supplied.
+
+Setup-managed extensions check remote `config.json` for updates without silently updating. A newer version adds
+a red dot to the DevTools settings button and **Update now** and **Release notes** entries to quick settings.
+Only clicking **Update now** makes Native Host revalidate the remote version, ownership marker, download URL,
+optional SHA256, and ZIP manifest, then atomically replace the directory and reload. This path never falls back to CDP; Store,
+enterprise-policy, and other-directory installations do not use setup updates. For updates downloaded by Chrome,
+the extension passively listens to `runtime.onUpdateAvailable` and shows the same user-triggered reload notification, without
+actively calling `runtime.requestUpdateCheck()`.
+
+## Automatic updates following the extension
+
+The extension and Native Host exchange versions on first connection. Each extension background startup checks once. When the extension
+moves to a higher `major.minor` release line, the older Host keeps its connection available while invoking
+the newest `@mearl/setup` in that `major.minor.x` range to update both `@mearl/native-host` and
+`@mearl/client` to the newest versions in that range. On success, Host exits and the extension's existing reconnect mechanism
+starts the new version. Success requires both local CLI versions to match and belong to the extension's release line.
+
+Automatic updates never downgrade a newer Host or modify cloud, MCP, or independently installed Mearl Skills.
+If the npm version is unpublished, the network unavailable, or updating fails, the old Host keeps running. The next extension background
+lifecycle may retry; manual updates use `npx @mearl/setup@3 update --local`.
+
+## Human and Agent use
+
+- Humans running interactively should omit `--yes`; setup prompts for Skill targets or MCP clients when needed.
+- Agents, CI, and other non-TTY environments should pass `--yes` or
+  `--non-interactive`. First installation selects detected Agent / MCP clients; removal clears
+  all detected relevant configuration.
+- Non-TTY `install` / `uninstall` without these flags exits before changes and prints the correct command.
+- Exit `0` means complete success, `1` incomplete execution, and `2` invalid arguments or interaction mode.
+
+## Examples
+
+```bash
+# Default local browser environment installation
+npx @mearl/setup@3
+
+# Equivalent to the previous command
+npx @mearl/setup@3 install
+
+# Noninteractive Agent / CI installation
+npx @mearl/setup@3 --yes
+
+# Install the cloud Agent environment
+npx @mearl/setup@3 --cloud
+
+# Use one machine as both a local browser host and cloud Agent
+npx @mearl/setup@3 --local --cloud
+
+# Update all detected Mearl environments in the current PATH
+npx @mearl/setup@3 update
+
+# Independently install or update the latest browser extension
+npx @mearl/setup@3 extension
+
+# Complete local environment: client, Native Host, Skill, and extension
+npx @mearl/setup@3 extension --full
+
+# Remove only the local environment
+npx @mearl/setup@3 uninstall --local
+
+# Detect and uninstall without interaction
+npx @mearl/setup@3 uninstall --yes
+
+# Uninstall environments and all CLI plugins and Providers
+npx @mearl/setup@3 uninstall --full
+
+# Install an optional browser Provider
+npx @mearl/setup@3 provider install @example/mearl-provider-device
+npx @mearl/setup@3 provider install @example/mearl-provider-cloud
+```
+
+Existing npm/npx installation methods and CLIs for Mearl environment packages remain available; setup is the unified convenience entry.
+
+## Preset installation
+
+`mearl-setup preset apply <source-url-or-path>` prepares exact resources, activates local Node selections, and synchronizes browser resources to connected, compatible extensions. `preset update` preserves user overrides, and `preset status` reports local readiness and the status of connected extensions. CLI setup exits `3` when local components still need synchronization or installation. [Local installation contract](../../docs/preset-installation.en.md)
+
+Before replacing packages, install/update saves exact resources and expected selections for the selected Preset, then synchronizes hosts and installs Skills after runtime initialization. `extension --full` prepares the same resources before replacing the extension. Existing local selections take priority; explicit `--preset` updates or repairs resources. Unavailable configuration or resources stop package changes; retries after partial upgrades use saved records. Removal never prepares or installs Presets.
+
+The default directory is the public site's `installation.json`; override with HTTPS `MEARL_INSTALLATION_CONFIG_URL` (loopback HTTP allowed for local validation). It uses the web installation validation contract and reports pending until both local and browser sides confirm.
+
+## Browser presets and distribution entry points
+
+Explicit setup first reuses the local preset. Without one, after runtime initialization and before Skill installation, it adopts the connected browser's trusted preset. Explicit `--preset <source>` wins. Differing browser selections, untrusted sources, or failed state reads require an explicit choice. First connection waits about one minute; closed browsers receive only the base environment and retry guidance. Ordinary connections and background core updates do not install an initial local preset.
+
+Distributions can set local-process `MEARL_SETUP_DEFAULT_PRESET` to a default manifest source. It applies only when neither side has a selection. Plugin, Provider, removal, and other subcommands keep their behavior. The public installer still owns installation and status verification.

package/README.md

@@ -1,22 +1,25 @@
 # @mearl/setup
 
-3.0 当前以 beta 发行。使用 `@beta` 入口安装同版本的 setup、运行包和扩展；正式版使用 `latest` 标签。
+[简体中文](README.md) | [English](README.en.md)
+
+使用 `@3` 选择最新稳定 3.x 安装器，并配套安装同版的运行包和扩展。
 
 Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全局安装 setup：
 
-要求 Node.js >= 20.18.0。安装前检查 `node --version`；3.0 beta 继续显式使用 `@beta`，
-避免 npm 在未指定版本时按旧 Node 的兼容性选到历史安装器。
+安装前用 `node --version` 确认 Node.js >= 20.18.0。
 
 ```bash
-npx @mearl/setup@beta [install] [--local] [--cloud] [--cloud-mode <id>] [--mcp]
-npx @mearl/setup@beta update [--local] [--cloud] [--cloud-mode <id>] [--mcp]
-npx @mearl/setup@beta uninstall [--local] [--cloud] [--cloud-mode <id>] [--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>
-npx @mearl/setup@beta preset repair [--replace-skill <name> ...]
+npx @mearl/setup@3 [install] [--local] [--cloud] [--cloud-mode <id>] [--mcp]
+npx @mearl/setup@3 update [--local] [--cloud] [--cloud-mode <id>] [--mcp]
+npx @mearl/setup@3 uninstall [--local] [--cloud] [--cloud-mode <id>] [--mcp] [--full]
+npx @mearl/setup@3 extension [--full] [--force]
+npx @mearl/setup@3 extension --extract
+npx @mearl/setup@3 plugin [name] <path>
+npx @mearl/setup@3 plugin install <skills add 参数...>
+npx @mearl/setup@3 plugin uninstall <name>
+npx @mearl/setup@3 provider <install|update|uninstall> <package|id>
+npx @mearl/setup@3 profile install <来源> [--browser <标识或名称>]
+npx @mearl/setup@3 preset repair [--replace-skill <name> ...]
 ```
 
 浏览器 Provider 独立安装和演进。安装后运行 `mearl <providerId>` 查看该版本声明的能力、
@@ -24,12 +27,22 @@ npx @mearl/setup@beta preset repair [--replace-skill <name> ...]
 
 可选云协议先通过 preset 安装对应能力，再用 `--cloud-mode <id>` 选择。Qoder 配对见 [`@mearl/plugin-qoder`](../plugin-qoder/README.md)；setup 不默认包含或安装它。
 
+## 安装端模拟
+
+```bash
+npx @mearl/setup@3 profile install mearlhq/wechat-profile
+```
+
+来源支持公开 GitHub 仓库的 `owner/repo`、`owner/repo@ref`，或能力包清单的完整 HTTPS 地址。GitHub 来源从解析后的提交读取根目录 `bundle.json`。命令安装能力包声明的全部端模拟配置，保留当前 Preset。有多个本地扩展连接时，用 `--browser` 选择目标。若扩展提示授权，请确认来源。
+
+在扩展快捷设置的客户端下拉菜单中选择「添加端模拟」，可以选择官方端模拟或输入来源。列表为空时，点击「客户端」可直接打开安装弹窗。
+
 ## 安装与注册 Skill 插件
 
 一个命令安装 skill 并注册它的 CLI、SDK 和 MCP 能力：
 
 ```bash
-npx @mearl/setup@beta plugin install https://github.com/mearlhq/mearl --skill browser-tab-manager --yes
+npx @mearl/setup@3 plugin install https://github.com/mearlhq/mearl --skill browser-tab-manager --yes
 mearl tabs summary
 ```
 
@@ -42,7 +55,7 @@ Native preset 批次新建的插件注册使用 setup 托管归属，后续通
 GUI 和 CLI 使用同一套 preset 安装器及覆盖规则。已保存的安装尚未完成时，运行 `preset repair` 从接受的本地资源重试，不重新下载 preset，也不隐式覆盖冲突来源。显式重复指定 `--replace-skill` 即授权本次替换这些 Skill 的来源或同名旧插件注册：
 
 ```bash
-npx @mearl/setup@beta preset repair --replace-skill example-skill --replace-skill another-skill
+npx @mearl/setup@3 preset repair --replace-skill example-skill --replace-skill another-skill
 ```
 
 已安装的 Skill 仅修复注册；来源冲突项重新安装。未列出的冲突仍会阻止安装，声明外的工具名与变更后的安装身份也会被拒绝。覆盖授权不会保留到后续普通修复或自动更新。缺少浏览器权限时仍需在扩展中授权。输出沿用 preset JSON，已就绪退出 `0`、仍有待完成项退出 `3`、安装失败退出 `1`，无效参数退出 `2`。
@@ -54,8 +67,8 @@ npx @mearl/setup@beta preset repair --replace-skill example-skill --replace-skil
 已通过其他渠道分发的 skill 或自定义入口，可以直接传入路径注册：
 
 ```bash
-npx @mearl/setup@beta plugin /absolute/path/to/browser-tab-manager
-npx @mearl/setup@beta plugin custom ./skills/custom/entry.mjs
+npx @mearl/setup@3 plugin /absolute/path/to/browser-tab-manager
+npx @mearl/setup@3 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`。
@@ -63,12 +76,14 @@ 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` 工具调用。已注册插件的日常调用不执行安装或版本检查；只有已选目录中的缺失插件会触发一次按需安装。
+JavaScript 插件可导出 `setup({ runCommand })`，在注册前准备 Skill 自己的依赖。两种安装入口都会等待执行完成，失败时停止注册。首次使用的依赖检查由 Skill 自行处理，见 [client 契约](../client/README.md#skill-插件)。
+
+注册后可在任意目录运行 `mearl <name> --help`，也可通过 `@mearl/client` 的 `invokePlugin` 或 MCP 的 `plugin_invoke` 工具调用。日常调用不更新 Skill 源码；已选目录中的缺失插件会触发一次按需安装。Skill 自身的依赖由安装钩子和首次使用检查准备。
 
 不再需要插件时执行：
 
 ```bash
-npx @mearl/setup@beta plugin uninstall tabs
+npx @mearl/setup@3 plugin uninstall tabs
 ```
 
 若入口位于 `~/.agents/skills/<skill>/`，setup 会先执行
@@ -84,9 +99,9 @@ Provider 由 npm 包分发，但包本身无需暴露 CLI 或安装脚本。setu
 可创建的浏览器类型名称及其表单参数：
 
 ```bash
-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
+npx @mearl/setup@3 provider install @example/mearl-provider-device
+npx @mearl/setup@3 provider update example-device
+npx @mearl/setup@3 provider uninstall example-device
 ```
 
 安装参数接受包名、版本或 dist-tag；更新和卸载可使用 providerId 或完整包名。核心 @mearl 包固定使用公共 npm registry；其余 scope 沿用调用方的包管理器配置。安装沿用启动 setup 的包管理器，
@@ -97,8 +112,8 @@ npx @mearl/setup@beta provider uninstall example-device
 ## 行为
 
 - Mearl 自有 npm 包的安装和更新固定使用 `https://registry.npmjs.org/`，与最新版本查询使用同一来源；第三方包沿用当前包管理器的源配置。
-- `install` 可以省略；直接执行 `npx @mearl/setup@beta` 等同于 `npx @mearl/setup@beta install`。
-  以选项开头时也默认安装，例如 `npx @mearl/setup@beta --cloud --yes`。
+- `install` 可以省略；直接执行 `npx @mearl/setup@3` 等同于 `npx @mearl/setup@3 install`。
+  以选项开头时也默认安装，例如 `npx @mearl/setup@3 --cloud --yes`。
 - `install` 未指定环境时默认 `--local`。
 - `-h` / `--help` 显示帮助，`-v` / `--version` 显示 setup 版本。
 - `update` 和 `uninstall` 未指定环境时，从当前 `PATH` 中的
@@ -144,20 +159,25 @@ npx @mearl/setup@beta provider uninstall example-device
 
 ## 安装或更新浏览器扩展
 
-```bash
-npx @mearl/setup@beta extension
-```
+首次使用时，先运行 `npx @mearl/setup@3`，再加载同版的离线 ZIP。商店提供同版扩展时，也可以直接安装。[安装步骤](../../README.md#安装本机环境)
 
-首次使用时可一次安装完整的本地浏览器环境：
+如需由 setup 管理扩展，运行下面的命令。
 
 ```bash
-npx @mearl/setup@beta extension --full
+npx @mearl/setup@3 extension
 ```
 
-首次安装、旧版 setup 扩展首次迁移，或 Native Host reload 不可用时才需要 CDP。如果
+加上 `--full` 可以在同一次运行中安装本机 CLI、Native Host 和 Skill。
+
+需要手动导入时，运行 `npx @mearl/setup@3 extension --extract`。setup 会下载发行 ZIP，
+在 `~/.mearl/extension-downloads/` 下创建新目录并解压，然后打印完整路径。打开
+`chrome://extensions/`，启用**开发者模式**，点击**加载已解压的扩展程序**并选择该目录。
+Chrome 使用扩展期间请保留目录。Chrome 关闭或远程调试关闭时也可以下载。
+
+自动安装在首次安装、旧版 setup 扩展首次迁移，或 Native Host reload 不可用时使用 CDP。如果
 Chrome 尚未开放 CDP，交互命令会提示打开
 `chrome://inspect/#remote-debugging`、启用远程调试并允许连接，然后等待安装完成。面向人的
-安装指引不要添加 `--yes`。无 TTY 环境使用 `npx @mearl/setup@beta extension --yes`；它只尝试
+安装指引不要添加 `--yes`。无 TTY 环境使用 `npx @mearl/setup@3 extension --yes`；它只尝试
 一次，CDP 不可用时立即中断。无法确认 setup 管理来源且 CDP 不可用时不会下载或修改插件
 目录，打开 CDP 后重新执行同一命令即可。Chrome 版本过低、缺少扩展安装所需的 CDP 方法时，
 命令会中断并提示升级 Chrome。
@@ -187,7 +207,7 @@ DevTools 面板的设置按钮会显示红点，快捷设置中提供“立即
 
 自动更新不会降级较新的 Host，也不会改动 cloud、MCP 或独立安装的 Mearl Skill。
 目标 npm 版本尚未发布、网络不可用或更新失败时，旧 Host 会继续运行；下一次扩展后台
-生命周期可重新尝试，也可手动执行 `npx @mearl/setup@beta update --local`。
+生命周期可重新尝试，也可手动执行 `npx @mearl/setup@3 update --local`。
 
 ## 人工与 Agent 使用
 
@@ -202,48 +222,48 @@ DevTools 面板的设置按钮会显示红点，快捷设置中提供“立即
 
 ```bash
 # 默认安装本地浏览器环境
-npx @mearl/setup
+npx @mearl/setup@3
 
 # 与上一条等价
-npx @mearl/setup@beta install
+npx @mearl/setup@3 install
 
 # Agent / CI 无交互安装
-npx @mearl/setup@beta --yes
+npx @mearl/setup@3 --yes
 
 # 安装云端 Agent 环境
-npx @mearl/setup@beta --cloud
+npx @mearl/setup@3 --cloud
 
 # 同一台机器同时作为本地浏览器宿主和云端 Agent
-npx @mearl/setup@beta --local --cloud
+npx @mearl/setup@3 --local --cloud
 
 # 自动更新当前 PATH 中检测到的全部 Mearl 环境
-npx @mearl/setup@beta update
+npx @mearl/setup@3 update
 
 # 独立安装或更新到最新浏览器扩展
-npx @mearl/setup@beta extension
+npx @mearl/setup@3 extension
 
 # 安装完整本地环境（client、Native Host、Skill 和扩展）
-npx @mearl/setup@beta extension --full
+npx @mearl/setup@3 extension --full
 
 # 只卸载本地环境
-npx @mearl/setup@beta uninstall --local
+npx @mearl/setup@3 uninstall --local
 
 # 自动检测并无交互卸载
-npx @mearl/setup@beta uninstall --yes
+npx @mearl/setup@3 uninstall --yes
 
 # 卸载环境，并清理全部 CLI 插件与 Provider
-npx @mearl/setup@beta uninstall --full
+npx @mearl/setup@3 uninstall --full
 
 # 安装可选浏览器 Provider
-npx @mearl/setup@beta provider install @example/mearl-provider-device
-npx @mearl/setup@beta provider install @example/mearl-provider-cloud
+npx @mearl/setup@3 provider install @example/mearl-provider-device
+npx @mearl/setup@3 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)。
+`mearl-setup preset apply <source-url-or-path>` 准备确切资源、激活本机 Node 选择，并向已连接的兼容扩展同步浏览器资源。`preset update` 保留用户覆盖，`preset status` 报告本机就绪情况和已连接扩展的状态。CLI setup 返回退出码 `3` 表示仍有本机组件待同步或安装。 [本机安装合同](../../docs/preset-installation.md)
 
 install/update 在替换包前保存选中 Preset 的确切资源和期望选择，运行时初始化后同步宿主并安装 Skills；`extension --full` 在替换扩展前完成同一准备流程。已有本机选择优先保留，显式 `--preset` 用于更新或修复资源。配置或资源不可用时停止包变更；部分升级后的重试使用已保存记录。卸载不准备或安装 Preset。
 

package/dist/browserExtension.d.ts

@@ -74,6 +74,9 @@ export declare function loadUnpackedViaCdp(extensionDirectory: string, chromeUse
 export declare function inspectMearlExtensionViaCdp(chromeUserDataDirectory?: string): Promise<InstalledBrowserExtension | null>;
 declare function inspectSetupManagedExtension(targetDirectory: string): Promise<string[]>;
 declare function reloadInstalledExtension(browserIds: string[]): Promise<void>;
+export declare function downloadMearlBrowserExtension(directory?: string, dependencies?: Pick<BrowserExtensionDependencies, 'extractArchive' | 'fetch'>): Promise<BrowserExtensionRelease & {
+    path: string;
+}>;
 export declare function updateSetupManagedBrowserExtensionFiles(options: SetupManagedBrowserExtensionUpdateOptions, dependencies?: Pick<BrowserExtensionDependencies, 'extractArchive' | 'fetch'>): Promise<SetupManagedBrowserExtensionUpdateResult>;
 export declare function installMearlBrowserExtension(options?: BrowserExtensionInstallOptions, dependencies?: BrowserExtensionDependencies): Promise<BrowserExtensionInstallResult>;
 export {};

package/dist/browserExtension.js

@@ -430,7 +430,7 @@ async function extractExtensionArchive(archivePath, destination) {
     }
     await archive.extractAllToAsync(destination, false);
 }
-async function downloadAndReplaceExtension(releaseInput, targetDirectory, fetchImpl, extractArchive) {
+async function downloadAndReplaceExtension(releaseInput, targetDirectory, fetchImpl, extractArchive, { managed = true } = {}) {
     const release = validateExtensionRelease(releaseInput);
     const parentDirectory = path.dirname(targetDirectory);
     const stagingDirectory = `${targetDirectory}.staging-${randomUUID()}`;
@@ -462,7 +462,8 @@ async function downloadAndReplaceExtension(releaseInput, targetDirectory, fetchI
         if (readExtensionReleaseVersion(manifest) !== release.version) {
             throw new Error(`Extension archive version ${String(manifest.version)} does not match ${release.version}`);
         }
-        await writeSetupMarker(stagingDirectory, targetDirectory);
+        if (managed)
+            await writeSetupMarker(stagingDirectory, targetDirectory);
         await replaceDirectory(stagingDirectory, targetDirectory);
         return release;
     }
@@ -471,6 +472,21 @@ async function downloadAndReplaceExtension(releaseInput, targetDirectory, fetchI
         await fs.promises.rm(stagingDirectory, { force: true, recursive: true });
     }
 }
+export async function downloadMearlBrowserExtension(directory = path.join(os.homedir(), '.mearl', 'extension-downloads'), dependencies = {}) {
+    const fetchImpl = dependencies.fetch ?? fetch;
+    const release = await fetchBrowserExtensionRelease(fetchImpl);
+    const parent = path.resolve(directory);
+    await fs.promises.mkdir(parent, { recursive: true });
+    const target = await fs.promises.mkdtemp(path.join(parent, `mearl-v${release.version}-`));
+    try {
+        await downloadAndReplaceExtension(release, target, fetchImpl, dependencies.extractArchive ?? extractExtensionArchive, { managed: false });
+        return { ...release, path: target };
+    }
+    catch (error) {
+        await fs.promises.rm(target, { force: true, recursive: true });
+        throw error;
+    }
+}
 export async function updateSetupManagedBrowserExtensionFiles(options, dependencies = {}) {
     const targetDirectory = path.resolve(options.targetDirectory);
     if (!hasSetupMarker(targetDirectory)) {

package/dist/browserPreset.d.ts

@@ -4,7 +4,6 @@ import { createNodePresetLoader } from './preset.js';
 import type { StagedPresetInstallation } from './preset.js';
 interface Options {
     env?: NodeJS.ProcessEnv;
-    waitMs?: number;
     writeLine?: (line: string) => void;
 }
 interface Dependencies {
@@ -12,8 +11,6 @@ interface Dependencies {
     invoke?: typeof invokeLocalHost;
     configuration?: () => ReturnType<typeof loadInstallationConfig>;
     load?: ReturnType<typeof createNodePresetLoader>;
-    now?: () => number;
-    sleep?: (ms: number) => Promise<void>;
 }
 /** Explicit setup may complete a trusted browser selection before installing any Skills. */
 export declare function prepareBrowserSetupPreset(options?: Options, dependencies?: Dependencies): Promise<StagedPresetInstallation | undefined>;