@mearl/setup 3.0.0-beta.0 → 3.0.0-beta.10

package/README.md

@@ -1,78 +1,91 @@
 # @mearl/setup
 
-3.0 当前以 beta 发行。使用 `@beta` 入口安装同版本的 setup、运行包和扩展；正式版 `latest` 保留 2.22。组织能力由独立 preset 分发。
+[English](README.md) | [简体中文](README.zh-CN.md)
 
-Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全局安装 setup：
+Version 3.0 is currently in beta. Use `@beta` to install matching setup, runtime packages, and extension versions; stable releases use `latest`.
+
+One-time installation, updates, removal, and configuration for Mearl environments. No global setup installation is needed:
+
+Requires Node.js >= 20.18.0. Check `node --version` before installation and explicitly use `@beta` for 3.0 beta
+so npm does not select a historical installer based on compatibility with an older Node version.
 
 ```bash
-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 [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 install <skills add arguments...>
 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> ...]
 ```
 
-浏览器 Provider 独立安装和演进。安装后运行 `mearl <providerId>` 查看该版本声明的能力、
-配置和启动参数。
+Browser Providers install and evolve independently. After installation, run `mearl <providerId>` to inspect that version's capabilities,
+configuration, and launch arguments.
 
-在 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。
+Install optional cloud protocols through a preset before selecting `--cloud-mode <id>`. See [`@mearl/plugin-qoder`](../plugin-qoder/README.md) for Qoder pairing; setup does not include or install it by default.
 
-## 安装与注册 Skill 插件
+## Install and register Skill plugins
 
-一个命令安装 skill 并注册它的 CLI、SDK 和 MCP 能力：
+Install a Skill and register its CLI, SDK, and MCP capabilities with one command:
 
 ```bash
-npx @mearl/setup@beta plugin install https://github.com/F-loat/mearl/tree/v3.0.0-beta.0 --skill browser-tab-manager --yes
+npx @mearl/setup@beta plugin install https://github.com/mearlhq/mearl --skill browser-tab-manager --yes
 mearl tabs summary
 ```
 
-安装参数传给固定版本的公共 Skills CLI（当前 skills@1.5.0，兼容项目的 Node 最低版本），使用全局共享目录。公共 CLI 的默认 symlink 和复制模式都可注册；复制模式通过 list --global --json 确认本次成功结果对应的 canonical path，不猜测目录，也不扫描其他 Skills。自定义 CLI 可通过 MEARL_SKILLS_PATH 指定。参数不接受截断后置选项的 -- 分隔符。
+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.md).
 
-安装宿主提供的本地插件目录决定哪些能力由 preset 管理。install/update 只维护该目录中的托管注册，保留用户自行注册的同名插件；普通外网环境没有组织专属名单，也不探测组织 registry。卸载最后一个依赖环境时移除托管插件与 Mearl Skill；其他环境仍需要时保留。--skip-skill 与版本线安装维持原有跳过规则。整套 preset 准备、权限、宿主同步及实际安装状态通过统一安装合同处理。
+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.
 
-Native preset 批次新建的插件注册使用 setup 托管归属，后续通过 Agent 更新仍保留该归属；同目录已有的用户注册保持原归属，自定义用户别名也会保留。托管卸载遇到用户别名共用同一 Skill 时，只清除托管注册并保留 Skill 文件。
+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@beta preset repair --replace-skill example-skill --replace-skill another-skill
+```
 
-自动注册默认使用安装目录名；入口可声明 `name` 指定简短命令名。
-重装会刷新同名绑定。JavaScript 入口必须默认导出 `register(app)`，Python 入口必须导出 `register(app)` 函数；完整协议见
-[插件运行时合同](../../docs/plugin-runtime.md)。
+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`.
 
-已通过其他渠道分发的 skill 或自定义入口，可以直接传入路径注册：
+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.md).
+
+Register a Skill distributed elsewhere or a custom entry directly by path:
 
 ```bash
 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`。
-命令检查入口注册函数，然后保存绝对入口路径，同名注册更新绑定。
-两种注册流程都会检查本机 `@mearl/client` 和 `@mearl/native-host`：缺失或低于当前 setup 版本时，
-复用已有包管理器安装 setup 的对应版本，更新后再次验证；更高版本保持不动。
-native-host 会幂等初始化 Skills 模式。基础环境补齐或初始化失败时保留已安装的 skill，并停止注册。
-注册后可在任意目录运行 `mearl <name> --help`，也可通过 `@mearl/client` 的 `invokePlugin` 或 MCP 的 `plugin_invoke` 工具调用。已注册插件的日常调用不执行安装或版本检查；只有已选目录中的缺失插件会触发一次按需安装。
+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.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@beta plugin uninstall tabs
 ```
 
-若入口位于 `~/.agents/skills/<skill>/`，setup 会先执行
-`skills remove <skill> --global --yes`，成功后清除该 Skill 对应的全部插件注册；
-入口目录已被手动删除时会让 Skills 仍能识别本次移除，从而一并清理其跟踪记录。
-移除失败时保留注册以便重试。手工注册的其他路径只解除 Mearl 注册，不删除源码。
-重复卸载未注册名称会成功返回，不产生改动。
+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.
 
-## 管理浏览器 Provider
+## Manage browser Providers
 
-Provider 由 npm 包分发，但包本身无需暴露 CLI 或安装脚本。setup 使用当前 npm 包管理器
-完成全局包生命周期，再读取包内的 `package.json#mearl.provider` 元数据登记协议入口、
-可创建的浏览器类型名称及其表单参数：
+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@beta provider install @example/mearl-provider-device
@@ -80,163 +93,168 @@ npx @mearl/setup@beta provider update example-device
 npx @mearl/setup@beta provider uninstall example-device
 ```
 
-安装参数接受包名、版本或 dist-tag；更新和卸载可使用 providerId 或完整包名。核心 @mearl 包固定使用公共 npm registry；其余 scope 沿用调用方的包管理器配置，组织 registry 由能力安装引导提供。安装沿用启动 setup 的包管理器，
-更新和卸载沿用当前 Provider 的原包管理器。Provider 登记只保存
-经过校验的包名、安装目录和包内入口；不接受包自行注入启动命令、参数、工作目录或环境变量。
-卸载仅在包管理器成功移除包后清除登记，以便失败时可以重试。
-
-## 行为
-
-- Mearl 自有 npm 包的安装和更新固定使用 `https://registry.npmjs.org/`，与最新版本查询使用同一来源；第三方包沿用当前包管理器的源配置。
-- `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` 中的
-  `mearl-native-host`、`mearl-cloud-server`、`mearl-mcp-server` 自动检测，可同时处理
-  多个已安装环境。
-- `--local`、`--cloud` 与 `--mcp` 可以组合，显式传入时只处理选中的环境；
-  `--qoder-cloud` 选择相同的 cloud 环境并记录 Qoder 配对模式，不能与 `--cloud` 同时使用。
-- 已有环境沿用其原包管理器和全局安装前缀；首次安装沿用启动 setup 的包管理器。
-- `uninstall` 也识别 `npm link` 或 `dev:link` 注册到 npm 全局目录的开发软链，
-  通过原 npm 前缀移除包与命令链接，保留仓库源码。安装和更新的自动检测仅处理常规全局安装。
-- cloud 环境统一管理 `@mearl/cloud-server` 与 `@mearl/client`：WebSocket 模式首次安装后
-  启动 Server，更新后仅在 Server 原本运行时重启；Qoder 模式由相同的 `start` 命令生成
-  新配对但不起服务；卸载前均调用 `stop`。
-- local/cloud 共用一份 `@mearl/client`；组合安装只处理一次，卸载单个环境时若另一个环境仍在使用则保留。
-- 从 2.5.x 更新 cloud 环境时会先卸载旧 `@mearl/cloud-client`，避免它遗留的 `mearl` bin 与统一 client 冲突。
-- local/cloud 共用的全局 mearl skill 通过 `skills` 的 JSON 清单定位，只处理一次。
-- 安装和更新通过 `skills add` 从公开仓库重新安装全局 mearl skill，并关联当前检测到的 Agent；更新须确认本次安装完成并核对全局 JSON 清单，不能仅依据第三方更新命令的退出码。
-  可用 `--skip-skill` 跳过。
-- 卸载一个环境但另一个仍依赖全局 mearl skill 时会保留 skill。
-- 已选择 preset 的自动维护保留用户注册；托管卸载遇到同目录的用户别名时只移除托管注册并保留共享 Skill。
-- `uninstall --full` 在环境卸载之外，还会逐项卸载所有已注册 CLI 插件与浏览器 Provider。
-  Skills 安装的插件会同时移除 Skill；手工注册的外部插件只清除注册、保留源码；Provider
-  只有在包管理器成功卸载 npm 包后才清除注册。单项失败不阻止其他项继续清理，命令最终返回非零。
-  该选项不删除 Chrome 扩展；`extension --full` 仍表示安装扩展及完整本地环境。
-- `uninstall --full` 在所有环境、插件与 Provider 成功移除后统一收尾：停止插件执行服务，
-  确认没有活跃或退出状态未明的任务，再删除任务历史、源码快照、服务日志和已结束宿主的页面会话文件。只卸载部分环境、单项失败或服务重新启动时保留共享缓存。
-  即使包和注册已移除，也可以再次运行该命令完成缓存收尾。自定义 `MEARL_PLUGIN_DIR` 只清理该注册表的执行缓存。
-  记事本、迭代记录、配置与身份、插件持久状态、Provider 私有数据、浏览器配置及用户导出的设计稿均保留；
-  CDP 标签 ID 计数也保留，防止旧请求命中新标签。
-- `--mcp` 的客户端配置和清理由 `@mearl/mcp-server` 自己的命令完成。
-- 默认的 `install` / `update` 不处理浏览器扩展。`extension` 是独立命令：从
-  `https://github.com/F-loat/mearl/releases/download/v3.0.0-beta.0/` 读取同版本 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
-  与浏览器存储保持稳定。
-- `extension --full` 会先安装或更新扩展，再复用 local profile 安装
-  `@mearl/client`、安装并初始化 `@mearl/native-host`，最后安装全局 Mearl Skill。
-  两部分都会尽量执行；任一步失败时命令返回非零退出码，已安装的部分会保留。它不安装
-  cloud 或 MCP 环境。
-- 下载前会通过 CDP 检查同 ID 插件的来源。未安装，或来源为固定目录中的 `UNPACKED`
-  插件时可继续；Chrome 商店、企业策略或其他本地目录安装的版本默认保持不变。只有显式
-  传入 `--force` 才会接管并替换这些版本。
-
-## 安装或更新浏览器扩展
+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@beta` equals `npx @mearl/setup@beta install`.
+  An initial option also implies installation, such as `npx @mearl/setup@beta --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
 
 ```bash
 npx @mearl/setup@beta extension
 ```
 
-首次使用时可一次安装完整的本地浏览器环境：
+For first use, install the complete local browser environment at once:
 
 ```bash
 npx @mearl/setup@beta extension --full
 ```
 
-首次安装、旧版 setup 扩展首次迁移，或 Native Host reload 不可用时才需要 CDP。如果
-Chrome 尚未开放 CDP，交互命令会提示打开
-`chrome://inspect/#remote-debugging`、启用远程调试并允许连接，然后等待安装完成。面向人的
-安装指引不要添加 `--yes`。无 TTY 环境使用 `npx @mearl/setup@beta extension --yes`；它只尝试
-一次，CDP 不可用时立即中断。无法确认 setup 管理来源且 CDP 不可用时不会下载或修改插件
-目录，打开 CDP 后重新执行同一命令即可。Chrome 版本过低、缺少扩展安装所需的 CDP 方法时，
-命令会中断并提示升级 Chrome。
-
-该命令每次都读取下载页上的最新插件版本，不要求与 setup、CLI 或 Native Host 同版本。
-CDP 来源检查和 `Extensions.loadUnpacked` 复用同一条连接，避免一次安装重复请求授权。
-安装成功后目录内会保存 setup 管理标记；`mearl check --local --json` 同时从当前运行扩展读取该
-标记，只有两侧路径一致时才允许无 CDP 更新。如果用户后来改装 Chrome 商店版本，运行中
-的扩展不会返回 setup 标记，命令会重新通过 CDP 检查来源，并在未传 `--force` 时保持商店
-版本不变。
-
-setup 管理的扩展会读取远端 `config.json` 检查新版本，但不会静默更新。发现更高版本后，
-DevTools 面板的设置按钮会显示红点，快捷设置中提供“立即更新”和对应版本的“更新日志”。
-只有用户点击“立即更新”后，Native Host 才会重新校验远端版本、setup 管理标记、下载地址、
-可选的 SHA256 和压缩包 manifest，再原子替换目录并 reload。该入口不会回退到 CDP；商店版、
-企业策略版和其他本地目录版本不会进入 setup 更新链路。对于 Chrome 自身管理并已下载完成的
-更新，扩展只被动监听 `runtime.onUpdateAvailable`，沿用相同的更新提示并由用户点击 reload；不会
-调用 `runtime.requestUpdateCheck()` 主动检查。
-
-## 跟随浏览器扩展自动更新
-
-浏览器扩展与 Native Host 首次建联时会交换版本。每次扩展后台启动只检查一次；当扩展
-进入更高的 `major.minor` release line 时，旧 Host 会在保持当前连接可用的前提下，调用
-对应 `major.minor.x` 范围内最新的 `@mearl/setup`，把 `@mearl/native-host` 与
-`@mearl/client` 一起更新到该范围内的最新版本。成功后 Host 退出，扩展通过已有重连机制
-启动新版本。只有两个本地 CLI 版本一致且都属于扩展的 release line 时，更新才会被视为成功。
-
-自动更新不会降级较新的 Host，也不会改动 cloud、MCP 或独立安装的 Mearl Skill。
-目标 npm 版本尚未发布、网络不可用或更新失败时，旧 Host 会继续运行；下一次扩展后台
-生命周期可重新尝试，也可手动执行 `npx @mearl/setup@beta update --local`。
-
-## 人工与 Agent 使用
-
-- 人工在终端执行时不加 `--yes`，需要选择 Skill 安装目标或 MCP 客户端时会显示交互提示。
-- Agent、CI 或其他无 TTY 环境应加 `--yes`（也可写
-  `--non-interactive`）。首次安装会选择已检测到的 Agent / MCP 客户端，卸载会清理
-  所有已检测到的相关配置。
-- 无 TTY 环境执行 `install` 或 `uninstall` 却未加上述参数时，会在任何改动前退出并提示正确命令。
-- 退出码 `0` 表示完整成功，`1` 表示执行未完成，`2` 表示参数或交互模式不适用。
-
-## 示例
+CDP is needed only 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@beta 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@beta 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
 
-# 与上一条等价
+# Equivalent to the previous command
 npx @mearl/setup@beta install
 
-# Agent / CI 无交互安装
+# Noninteractive Agent / CI installation
 npx @mearl/setup@beta --yes
 
-# 安装云端 Agent 环境
+# Install the cloud Agent environment
 npx @mearl/setup@beta --cloud
 
-# 同一台机器同时作为本地浏览器宿主和云端 Agent
+# Use one machine as both a local browser host and cloud Agent
 npx @mearl/setup@beta --local --cloud
 
-# 自动更新当前 PATH 中检测到的全部 Mearl 环境
+# Update all detected Mearl environments in the current PATH
 npx @mearl/setup@beta update
 
-# 独立安装或更新到最新浏览器扩展
+# Independently install or update the latest browser extension
 npx @mearl/setup@beta extension
 
-# 安装完整本地环境（client、Native Host、Skill 和扩展）
+# Complete local environment: client, Native Host, Skill, and extension
 npx @mearl/setup@beta extension --full
 
-# 只卸载本地环境
+# Remove only the local environment
 npx @mearl/setup@beta uninstall --local
 
-# 自动检测并无交互卸载
+# Detect and uninstall without interaction
 npx @mearl/setup@beta uninstall --yes
 
-# 卸载环境，并清理全部 CLI 插件与 Provider
+# Uninstall environments and all CLI plugins and Providers
 npx @mearl/setup@beta uninstall --full
 
-# 安装可选浏览器 Provider
+# Install an optional browser Provider
 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 是统一的便利入口。
+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 the same browser resources to compatible extensions. `preset update` preserves user overrides; `preset status` reads actual readiness. Exit `3` means pending synchronization/installation. The extension, defaults, Skills/Providers, and web installation use the same actual-state checks; see the [local installation contract](../../docs/preset-installation.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.
 
-## Preset 安装
+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.
 
-`mearl-setup preset apply <source-url-or-path>` 准备确切资源、激活本机 Node 选择，并向兼容扩展同步同一批浏览器资源；`preset update` 保留用户覆盖，`preset status` 只读检查实际就绪状态。退出码 3 表示存在待同步/安装组件。完整扩展、默认设置、Skills/Provider 和网页一键安装使用同一实际状态核验，见 [本机安装合同](../../docs/preset-installation.md)。
+## Browser presets and distribution entry points
 
-普通 install/update 在替换包前保存选中 preset 的确切资源和期望选择，运行时初始化后再同步宿主和安装 Skills；`extension --full` 也在替换扩展前完成准备。已有本机 preset 优先保留，显式 `--preset` 可更新或修复资源；检测到已安装包为 3.0 以前版本且尚无选择时，读取公共部署目录的 `legacyPreset`。配置或资源不可用会在包变更前停止，不回退到无内部能力的安装。部分升级后的重试使用已保存安装记录，即使包版本已变为 3.x 也不重新下载。维护旧版本线和卸载不自动迁移。
+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.
 
-默认目录为公共站点的 `installation.json`，可通过 `MEARL_INSTALLATION_CONFIG_URL` 指定其他 HTTPS 目录（本地验证允许回环 HTTP）。核心不包含组织 ID 或私有来源；目录沿用网页安装的校验合同。本机与浏览器未全部确认时仍报告 pending，准备成功不表示已发行或已完成真实企业授权验收。
+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.