@mearl/setup 3.0.0 → 3.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/README.en.md +46 -43
  2. package/README.md +46 -43
  3. package/dist/cli.d.ts +1 -1
  4. package/dist/cli.js +50 -19
  5. package/dist/preset.d.ts +7 -2
  6. package/dist/preset.js +296 -49
  7. package/dist/skillSourceReceipts.d.ts +1 -1
  8. package/dist/skillSourceReceipts.js +54 -10
  9. package/dist/skillSources.d.ts +1 -1
  10. package/dist/skillSources.js +85 -33
  11. package/dist/skills.d.ts +1 -1
  12. package/dist/skills.js +60 -14
  13. package/package.json +6 -6
package/README.en.md CHANGED
@@ -9,17 +9,18 @@ One-time installation, updates, removal, and configuration for Mearl environment
9
9
  Run `node --version` before installation to verify Node.js >= 20.18.0.
10
10
 
11
11
  ```bash
12
- npx @mearl/setup@3 [install] [--local] [--cloud] [--cloud-mode <id>] [--mcp]
13
- npx @mearl/setup@3 update [--local] [--cloud] [--cloud-mode <id>] [--mcp]
14
- npx @mearl/setup@3 uninstall [--local] [--cloud] [--cloud-mode <id>] [--mcp] [--full]
15
- npx @mearl/setup@3 extension [--full] [--force]
16
- npx @mearl/setup@3 extension --extract
17
- npx @mearl/setup@3 plugin [name] <path>
18
- npx @mearl/setup@3 plugin install <skills add arguments...>
19
- npx @mearl/setup@3 plugin uninstall <name>
20
- npx @mearl/setup@3 provider <install|update|uninstall> <package|id>
21
- npx @mearl/setup@3 profile install <source> [--browser <id-or-name>]
22
- npx @mearl/setup@3 preset repair [--replace-skill <name> ...]
12
+ npx @mearl/setup [install] [--local] [--cloud] [--cloud-mode <id>] [--mcp]
13
+ npx @mearl/setup update [--local] [--cloud] [--cloud-mode <id>] [--mcp]
14
+ npx @mearl/setup uninstall [--local] [--cloud] [--cloud-mode <id>] [--mcp] [--full]
15
+ npx @mearl/setup extension [--full] [--force]
16
+ npx @mearl/setup extension --extract
17
+ npx @mearl/setup plugin [name] <path>
18
+ npx @mearl/setup plugin install <skills add arguments...>
19
+ npx @mearl/setup plugin uninstall <name>
20
+ npx @mearl/setup provider <install|update|uninstall> <package|id>
21
+ npx @mearl/setup profile install <source> [--browser <id-or-name>]
22
+ npx @mearl/setup preset apply [source]
23
+ npx @mearl/setup preset <update|status|uninstall>
23
24
  ```
24
25
 
25
26
  Browser Providers install and evolve independently. After installation, run `mearl <providerId>` to inspect that version's capabilities,
@@ -30,7 +31,7 @@ Install optional cloud protocols through a preset before selecting `--cloud-mode
30
31
  ## Install App emulation
31
32
 
32
33
  ```bash
33
- npx @mearl/setup@3 profile install mearlhq/wechat-profile
34
+ npx @mearl/setup profile install mearlhq/wechat-profile
34
35
  ```
35
36
 
36
37
  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.
@@ -42,24 +43,26 @@ In the extension's quick settings, open the App selector and choose **Add App em
42
43
  Install a Skill and register its CLI, SDK, and MCP capabilities with one command:
43
44
 
44
45
  ```bash
45
- npx @mearl/setup@3 plugin install https://github.com/mearlhq/mearl --skill browser-tab-manager --yes
46
+ npx @mearl/setup plugin install https://github.com/mearlhq/mearl --skill browser-tab-manager --yes
46
47
  mearl tabs summary
47
48
  ```
48
49
 
49
- 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.
50
+ Installation arguments pass to the public Skills CLI using the global shared directory. By default, `npx` resolves `skills` for the current Node.js version. 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.
50
51
 
51
52
  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).
52
53
 
53
54
  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.
54
55
 
55
- 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:
56
+ GUI and CLI share the preset installer and override rules. `preset apply` accepts a URL or local file path. Omitting the source retries from the saved snapshot. `preset update` rereads the current source. Repeat `--replace-skill` during a retry to authorize replacing those Skill sources or same-name plugin registrations for this invocation.
56
57
 
57
58
  ```bash
58
- npx @mearl/setup@3 preset repair --replace-skill example-skill --replace-skill another-skill
59
+ npx @mearl/setup preset apply --replace-skill example-skill --replace-skill another-skill
59
60
  ```
60
61
 
61
62
  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`.
62
63
 
64
+ Run `preset uninstall` to remove the local preset and matching selections in connected extensions. Removal clears preset-managed capability packages and setup-managed registrations in the selected plugin catalog. It preserves independent capabilities, Skill files, Providers, and browser permissions. [See what preset removal covers](../../docs/preset-installation.en.md)
65
+
63
66
  Automatic registration defaults to the installation directory name; an entry can declare `name` for a shorter command.
64
67
  Reinstallation refreshes same-name bindings. JavaScript entries must default-export `register(app)`; Python entries must export a `register(app)` function. See the
65
68
  [plugin runtime contract](../../docs/plugin-runtime.en.md).
@@ -67,8 +70,8 @@ Reinstallation refreshes same-name bindings. JavaScript entries must default-exp
67
70
  Register a Skill distributed elsewhere or a custom entry directly by path:
68
71
 
69
72
  ```bash
70
- npx @mearl/setup@3 plugin /absolute/path/to/browser-tab-manager
71
- npx @mearl/setup@3 plugin custom ./skills/custom/entry.mjs
73
+ npx @mearl/setup plugin /absolute/path/to/browser-tab-manager
74
+ npx @mearl/setup plugin custom ./skills/custom/entry.mjs
72
75
  ```
73
76
 
74
77
  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`.
@@ -83,7 +86,7 @@ After registration, run `mearl <name> --help` anywhere, use SDK `invokePlugin`,
83
86
  To remove a plugin:
84
87
 
85
88
  ```bash
86
- npx @mearl/setup@3 plugin uninstall tabs
89
+ npx @mearl/setup plugin uninstall tabs
87
90
  ```
88
91
 
89
92
  For entries under `~/.agents/skills/<skill>/`, setup first runs
@@ -99,9 +102,9 @@ for global package lifecycle and reads `package.json#mearl.provider` to register
99
102
  browser type name, and form arguments:
100
103
 
101
104
  ```bash
102
- npx @mearl/setup@3 provider install @example/mearl-provider-device
103
- npx @mearl/setup@3 provider update example-device
104
- npx @mearl/setup@3 provider uninstall example-device
105
+ npx @mearl/setup provider install @example/mearl-provider-device
106
+ npx @mearl/setup provider update example-device
107
+ npx @mearl/setup provider uninstall example-device
105
108
  ```
106
109
 
107
110
  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;
@@ -112,8 +115,8 @@ Registration clears only after successful package removal, allowing retries.
112
115
  ## Behavior
113
116
 
114
117
  - Mearl-owned npm packages install and update from `https://registry.npmjs.org/`, matching version queries. Third-party packages use current manager registry settings.
115
- - `install` is optional: `npx @mearl/setup@3` equals `npx @mearl/setup@3 install`.
116
- An initial option also implies installation, such as `npx @mearl/setup@3 --cloud --yes`.
118
+ - `install` is optional: `npx @mearl/setup` equals `npx @mearl/setup install`.
119
+ An initial option also implies installation, such as `npx @mearl/setup --cloud --yes`.
117
120
  - `install` defaults to `--local` when no environment is specified.
118
121
  - `-h` / `--help` shows help; `-v` / `--version` shows setup's version.
119
122
  - Without environment flags, `update` and `uninstall` detect
@@ -159,17 +162,17 @@ Registration clears only after successful package removal, allowing retries.
159
162
 
160
163
  ## Install or update the browser extension
161
164
 
162
- 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)
165
+ For first use, run `npx @mearl/setup` 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)
163
166
 
164
167
  Use this command to let setup manage the extension.
165
168
 
166
169
  ```bash
167
- npx @mearl/setup@3 extension
170
+ npx @mearl/setup extension
168
171
  ```
169
172
 
170
173
  Add `--full` to also install the local CLI, Native Host, and Skill in the same run.
171
174
 
172
- To load the extension manually, run `npx @mearl/setup@3 extension --extract`. Setup downloads the release ZIP,
175
+ To load the extension manually, run `npx @mearl/setup extension --extract`. Setup downloads the release ZIP,
173
176
  unpacks it into a new directory under `~/.mearl/extension-downloads/`, and prints the full path. Open
174
177
  `chrome://extensions/`, enable **Developer mode**, click **Load unpacked**, and select that directory.
175
178
  Keep the directory while Chrome uses the extension. This works with Chrome closed and with remote debugging disabled.
@@ -177,7 +180,7 @@ Keep the directory while Chrome uses the extension. This works with Chrome close
177
180
  Automatic installation uses CDP for first installation, initial migration of older setup extensions, or unavailable Native Host reload. If
178
181
  Chrome has not enabled CDP, interactive setup prompts you to open
179
182
  `chrome://inspect/#remote-debugging`, enable remote debugging, and allow the connection, then waits for installation. Human-facing
180
- instructions should omit `--yes`. Without a TTY, use `npx @mearl/setup@3 extension --yes`: it tries
183
+ instructions should omit `--yes`. Without a TTY, use `npx @mearl/setup extension --yes`: it tries
181
184
  once and stops immediately if CDP is unavailable. If setup ownership cannot be confirmed and CDP is unavailable, it does not download or modify
182
185
  the extension directory. Enable CDP and rerun the same command. If Chrome lacks required extension-installation CDP methods,
183
186
  the command stops and asks for a Chrome upgrade.
@@ -207,7 +210,7 @@ starts the new version. Success requires both local CLI versions to match and be
207
210
 
208
211
  Automatic updates never downgrade a newer Host or modify cloud, MCP, or independently installed Mearl Skills.
209
212
  If the npm version is unpublished, the network unavailable, or updating fails, the old Host keeps running. The next extension background
210
- lifecycle may retry; manual updates use `npx @mearl/setup@3 update --local`.
213
+ lifecycle may retry; manual updates use `npx @mearl/setup update --local`.
211
214
 
212
215
  ## Human and Agent use
213
216
 
@@ -222,41 +225,41 @@ lifecycle may retry; manual updates use `npx @mearl/setup@3 update --local`.
222
225
 
223
226
  ```bash
224
227
  # Default local browser environment installation
225
- npx @mearl/setup@3
228
+ npx @mearl/setup
226
229
 
227
230
  # Equivalent to the previous command
228
- npx @mearl/setup@3 install
231
+ npx @mearl/setup install
229
232
 
230
233
  # Noninteractive Agent / CI installation
231
- npx @mearl/setup@3 --yes
234
+ npx @mearl/setup --yes
232
235
 
233
236
  # Install the cloud Agent environment
234
- npx @mearl/setup@3 --cloud
237
+ npx @mearl/setup --cloud
235
238
 
236
239
  # Use one machine as both a local browser host and cloud Agent
237
- npx @mearl/setup@3 --local --cloud
240
+ npx @mearl/setup --local --cloud
238
241
 
239
242
  # Update all detected Mearl environments in the current PATH
240
- npx @mearl/setup@3 update
243
+ npx @mearl/setup update
241
244
 
242
245
  # Independently install or update the latest browser extension
243
- npx @mearl/setup@3 extension
246
+ npx @mearl/setup extension
244
247
 
245
248
  # Complete local environment: client, Native Host, Skill, and extension
246
- npx @mearl/setup@3 extension --full
249
+ npx @mearl/setup extension --full
247
250
 
248
251
  # Remove only the local environment
249
- npx @mearl/setup@3 uninstall --local
252
+ npx @mearl/setup uninstall --local
250
253
 
251
254
  # Detect and uninstall without interaction
252
- npx @mearl/setup@3 uninstall --yes
255
+ npx @mearl/setup uninstall --yes
253
256
 
254
257
  # Uninstall environments and all CLI plugins and Providers
255
- npx @mearl/setup@3 uninstall --full
258
+ npx @mearl/setup uninstall --full
256
259
 
257
260
  # Install an optional browser Provider
258
- npx @mearl/setup@3 provider install @example/mearl-provider-device
259
- npx @mearl/setup@3 provider install @example/mearl-provider-cloud
261
+ npx @mearl/setup provider install @example/mearl-provider-device
262
+ npx @mearl/setup provider install @example/mearl-provider-cloud
260
263
  ```
261
264
 
262
265
  Existing npm/npx installation methods and CLIs for Mearl environment packages remain available; setup is the unified convenience entry.
@@ -273,4 +276,4 @@ The default directory is the public site's `installation.json`; override with HT
273
276
 
274
277
  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.
275
278
 
276
- 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.
279
+ 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. Setup performs installation and verifies its status.
package/README.md CHANGED
@@ -9,17 +9,18 @@ Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全
9
9
  安装前用 `node --version` 确认 Node.js >= 20.18.0。
10
10
 
11
11
  ```bash
12
- npx @mearl/setup@3 [install] [--local] [--cloud] [--cloud-mode <id>] [--mcp]
13
- npx @mearl/setup@3 update [--local] [--cloud] [--cloud-mode <id>] [--mcp]
14
- npx @mearl/setup@3 uninstall [--local] [--cloud] [--cloud-mode <id>] [--mcp] [--full]
15
- npx @mearl/setup@3 extension [--full] [--force]
16
- npx @mearl/setup@3 extension --extract
17
- npx @mearl/setup@3 plugin [name] <path>
18
- npx @mearl/setup@3 plugin install <skills add 参数...>
19
- npx @mearl/setup@3 plugin uninstall <name>
20
- npx @mearl/setup@3 provider <install|update|uninstall> <package|id>
21
- npx @mearl/setup@3 profile install <来源> [--browser <标识或名称>]
22
- npx @mearl/setup@3 preset repair [--replace-skill <name> ...]
12
+ npx @mearl/setup [install] [--local] [--cloud] [--cloud-mode <id>] [--mcp]
13
+ npx @mearl/setup update [--local] [--cloud] [--cloud-mode <id>] [--mcp]
14
+ npx @mearl/setup uninstall [--local] [--cloud] [--cloud-mode <id>] [--mcp] [--full]
15
+ npx @mearl/setup extension [--full] [--force]
16
+ npx @mearl/setup extension --extract
17
+ npx @mearl/setup plugin [name] <path>
18
+ npx @mearl/setup plugin install <skills add 参数...>
19
+ npx @mearl/setup plugin uninstall <name>
20
+ npx @mearl/setup provider <install|update|uninstall> <package|id>
21
+ npx @mearl/setup profile install <来源> [--browser <标识或名称>]
22
+ npx @mearl/setup preset apply [来源]
23
+ npx @mearl/setup preset <update|status|uninstall>
23
24
  ```
24
25
 
25
26
  浏览器 Provider 独立安装和演进。安装后运行 `mearl <providerId>` 查看该版本声明的能力、
@@ -30,7 +31,7 @@ npx @mearl/setup@3 preset repair [--replace-skill <name> ...]
30
31
  ## 安装端模拟
31
32
 
32
33
  ```bash
33
- npx @mearl/setup@3 profile install mearlhq/wechat-profile
34
+ npx @mearl/setup profile install mearlhq/wechat-profile
34
35
  ```
35
36
 
36
37
  来源支持公开 GitHub 仓库的 `owner/repo`、`owner/repo@ref`，或能力包清单的完整 HTTPS 地址。GitHub 来源从解析后的提交读取根目录 `bundle.json`。命令安装能力包声明的全部端模拟配置，保留当前 Preset。有多个本地扩展连接时，用 `--browser` 选择目标。若扩展提示授权，请确认来源。
@@ -42,24 +43,26 @@ npx @mearl/setup@3 profile install mearlhq/wechat-profile
42
43
  一个命令安装 skill 并注册它的 CLI、SDK 和 MCP 能力：
43
44
 
44
45
  ```bash
45
- npx @mearl/setup@3 plugin install https://github.com/mearlhq/mearl --skill browser-tab-manager --yes
46
+ npx @mearl/setup plugin install https://github.com/mearlhq/mearl --skill browser-tab-manager --yes
46
47
  mearl tabs summary
47
48
  ```
48
49
 
49
- 安装参数传给固定版本的公共 Skills CLI（当前 skills@1.5.0，兼容项目的 Node 最低版本），使用全局共享目录。公共 CLI 的默认 symlink 和复制模式都可注册；复制模式通过 list --global --json 确认本次成功结果对应的 canonical path，不猜测目录，也不扫描其他 Skills。自定义 CLI 可通过 MEARL_SKILLS_PATH 指定。参数不接受截断后置选项的 -- 分隔符。
50
+ 安装参数传给公共 Skills CLI，使用全局共享目录。默认由 `npx` 按当前 Node.js 版本解析 `skills`。公共 CLI 的默认 symlink 和复制模式都可注册；复制模式通过 list --global --json 确认本次成功结果对应的 canonical path，不猜测目录，也不扫描其他 Skills。自定义 CLI 可通过 MEARL_SKILLS_PATH 指定。参数不接受截断后置选项的 -- 分隔符。
50
51
 
51
52
  安装宿主提供的本地插件目录决定哪些能力由 preset 管理。install/update 维护目录中的托管注册，保留用户自行注册的插件。卸载最后一个依赖环境时移除托管插件与 Mearl Skill；其他环境需要时保留。配置准备、宿主同步和实际安装状态共用 [安装合同](../../docs/preset-installation.md)。
52
53
 
53
54
  Native preset 批次新建的插件注册使用 setup 托管归属，后续通过 Agent 更新仍保留该归属；同目录已有的用户注册保持原归属，自定义用户别名也会保留。托管卸载遇到用户别名共用同一 Skill 时，只清除托管注册并保留 Skill 文件。
54
55
 
55
- GUI 和 CLI 使用同一套 preset 安装器及覆盖规则。已保存的安装尚未完成时，运行 `preset repair` 从接受的本地资源重试，不重新下载 preset，也不隐式覆盖冲突来源。显式重复指定 `--replace-skill` 即授权本次替换这些 Skill 的来源或同名旧插件注册：
56
+ GUI 和 CLI 使用同一套 preset 安装器及覆盖规则。`preset apply` 接受 URL 或本地文件路径。省略来源时使用已保存的快照重试。`preset update` 重新读取当前来源。重试时可显式重复指定 `--replace-skill`，授权本次替换这些 Skill 的来源或同名旧插件注册。
56
57
 
57
58
  ```bash
58
- npx @mearl/setup@3 preset repair --replace-skill example-skill --replace-skill another-skill
59
+ npx @mearl/setup preset apply --replace-skill example-skill --replace-skill another-skill
59
60
  ```
60
61
 
61
62
  已安装的 Skill 仅修复注册；来源冲突项重新安装。未列出的冲突仍会阻止安装，声明外的工具名与变更后的安装身份也会被拒绝。覆盖授权不会保留到后续普通修复或自动更新。缺少浏览器权限时仍需在扩展中授权。输出沿用 preset JSON，已就绪退出 `0`、仍有待完成项退出 `3`、安装失败退出 `1`，无效参数退出 `2`。
62
63
 
64
+ 运行 `preset uninstall` 清理本机 preset 和匹配的已连接扩展。卸载会移除 preset 托管的能力包和当前目录中由 setup 托管的插件注册，保留独立安装的能力、Skill 文件、Provider 和浏览器权限。[查看卸载范围](../../docs/preset-installation.md)
65
+
63
66
  自动注册默认使用安装目录名；入口可声明 `name` 指定简短命令名。
64
67
  重装会刷新同名绑定。JavaScript 入口必须默认导出 `register(app)`，Python 入口必须导出 `register(app)` 函数；完整协议见
65
68
  [插件运行时合同](../../docs/plugin-runtime.md)。
@@ -67,8 +70,8 @@ npx @mearl/setup@3 preset repair --replace-skill example-skill --replace-skill a
67
70
  已通过其他渠道分发的 skill 或自定义入口，可以直接传入路径注册：
68
71
 
69
72
  ```bash
70
- npx @mearl/setup@3 plugin /absolute/path/to/browser-tab-manager
71
- npx @mearl/setup@3 plugin custom ./skills/custom/entry.mjs
73
+ npx @mearl/setup plugin /absolute/path/to/browser-tab-manager
74
+ npx @mearl/setup plugin custom ./skills/custom/entry.mjs
72
75
  ```
73
76
 
74
77
  path 接受目录或具体文件；目录默认读取 `scripts/main.mjs` 或 `scripts/main.py`，相对路径基于调用工作目录解析。插件名优先使用显式 name，其次读取入口的 `name` metadata，最后回退到 Skill 目录名；常规注册只传 path，显式 name 仅用于覆盖或兼容旧入口。Python 插件要求 `python3 >= 3.9`，可通过 `MEARL_PYTHON` 指定解释器路径；setup 只验证入口可加载，不安装 Python，也不执行 `pip install`。
@@ -83,7 +86,7 @@ JavaScript 插件可导出 `setup({ runCommand })`，在注册前准备 Skill
83
86
  不再需要插件时执行：
84
87
 
85
88
  ```bash
86
- npx @mearl/setup@3 plugin uninstall tabs
89
+ npx @mearl/setup plugin uninstall tabs
87
90
  ```
88
91
 
89
92
  若入口位于 `~/.agents/skills/<skill>/`，setup 会先执行
@@ -99,9 +102,9 @@ Provider 由 npm 包分发，但包本身无需暴露 CLI 或安装脚本。setu
99
102
  可创建的浏览器类型名称及其表单参数：
100
103
 
101
104
  ```bash
102
- npx @mearl/setup@3 provider install @example/mearl-provider-device
103
- npx @mearl/setup@3 provider update example-device
104
- npx @mearl/setup@3 provider uninstall example-device
105
+ npx @mearl/setup provider install @example/mearl-provider-device
106
+ npx @mearl/setup provider update example-device
107
+ npx @mearl/setup provider uninstall example-device
105
108
  ```
106
109
 
107
110
  安装参数接受包名、版本或 dist-tag；更新和卸载可使用 providerId 或完整包名。核心 @mearl 包固定使用公共 npm registry；其余 scope 沿用调用方的包管理器配置。安装沿用启动 setup 的包管理器，
@@ -112,8 +115,8 @@ npx @mearl/setup@3 provider uninstall example-device
112
115
  ## 行为
113
116
 
114
117
  - Mearl 自有 npm 包的安装和更新固定使用 `https://registry.npmjs.org/`，与最新版本查询使用同一来源；第三方包沿用当前包管理器的源配置。
115
- - `install` 可以省略；直接执行 `npx @mearl/setup@3` 等同于 `npx @mearl/setup@3 install`。
116
- 以选项开头时也默认安装，例如 `npx @mearl/setup@3 --cloud --yes`。
118
+ - `install` 可以省略；直接执行 `npx @mearl/setup` 等同于 `npx @mearl/setup install`。
119
+ 以选项开头时也默认安装，例如 `npx @mearl/setup --cloud --yes`。
117
120
  - `install` 未指定环境时默认 `--local`。
118
121
  - `-h` / `--help` 显示帮助，`-v` / `--version` 显示 setup 版本。
119
122
  - `update` 和 `uninstall` 未指定环境时，从当前 `PATH` 中的
@@ -159,17 +162,17 @@ npx @mearl/setup@3 provider uninstall example-device
159
162
 
160
163
  ## 安装或更新浏览器扩展
161
164
 
162
- 首次使用时，先运行 `npx @mearl/setup@3`，再加载同版的离线 ZIP。商店提供同版扩展时，也可以直接安装。[安装步骤](../../README.md#安装本机环境)
165
+ 首次使用时，先运行 `npx @mearl/setup`，再加载同版的离线 ZIP。商店提供同版扩展时，也可以直接安装。[安装步骤](../../README.md#安装本机环境)
163
166
 
164
167
  如需由 setup 管理扩展，运行下面的命令。
165
168
 
166
169
  ```bash
167
- npx @mearl/setup@3 extension
170
+ npx @mearl/setup extension
168
171
  ```
169
172
 
170
173
  加上 `--full` 可以在同一次运行中安装本机 CLI、Native Host 和 Skill。
171
174
 
172
- 需要手动导入时，运行 `npx @mearl/setup@3 extension --extract`。setup 会下载发行 ZIP，
175
+ 需要手动导入时，运行 `npx @mearl/setup extension --extract`。setup 会下载发行 ZIP，
173
176
  在 `~/.mearl/extension-downloads/` 下创建新目录并解压，然后打印完整路径。打开
174
177
  `chrome://extensions/`，启用**开发者模式**，点击**加载已解压的扩展程序**并选择该目录。
175
178
  Chrome 使用扩展期间请保留目录。Chrome 关闭或远程调试关闭时也可以下载。
@@ -177,7 +180,7 @@ Chrome 使用扩展期间请保留目录。Chrome 关闭或远程调试关闭时
177
180
  自动安装在首次安装、旧版 setup 扩展首次迁移，或 Native Host reload 不可用时使用 CDP。如果
178
181
  Chrome 尚未开放 CDP，交互命令会提示打开
179
182
  `chrome://inspect/#remote-debugging`、启用远程调试并允许连接，然后等待安装完成。面向人的
180
- 安装指引不要添加 `--yes`。无 TTY 环境使用 `npx @mearl/setup@3 extension --yes`；它只尝试
183
+ 安装指引不要添加 `--yes`。无 TTY 环境使用 `npx @mearl/setup extension --yes`；它只尝试
181
184
  一次，CDP 不可用时立即中断。无法确认 setup 管理来源且 CDP 不可用时不会下载或修改插件
182
185
  目录，打开 CDP 后重新执行同一命令即可。Chrome 版本过低、缺少扩展安装所需的 CDP 方法时，
183
186
  命令会中断并提示升级 Chrome。
@@ -207,7 +210,7 @@ DevTools 面板的设置按钮会显示红点，快捷设置中提供“立即
207
210
 
208
211
  自动更新不会降级较新的 Host，也不会改动 cloud、MCP 或独立安装的 Mearl Skill。
209
212
  目标 npm 版本尚未发布、网络不可用或更新失败时，旧 Host 会继续运行；下一次扩展后台
210
- 生命周期可重新尝试，也可手动执行 `npx @mearl/setup@3 update --local`。
213
+ 生命周期可重新尝试，也可手动执行 `npx @mearl/setup update --local`。
211
214
 
212
215
  ## 人工与 Agent 使用
213
216
 
@@ -222,41 +225,41 @@ DevTools 面板的设置按钮会显示红点，快捷设置中提供“立即
222
225
 
223
226
  ```bash
224
227
  # 默认安装本地浏览器环境
225
- npx @mearl/setup@3
228
+ npx @mearl/setup
226
229
 
227
230
  # 与上一条等价
228
- npx @mearl/setup@3 install
231
+ npx @mearl/setup install
229
232
 
230
233
  # Agent / CI 无交互安装
231
- npx @mearl/setup@3 --yes
234
+ npx @mearl/setup --yes
232
235
 
233
236
  # 安装云端 Agent 环境
234
- npx @mearl/setup@3 --cloud
237
+ npx @mearl/setup --cloud
235
238
 
236
239
  # 同一台机器同时作为本地浏览器宿主和云端 Agent
237
- npx @mearl/setup@3 --local --cloud
240
+ npx @mearl/setup --local --cloud
238
241
 
239
242
  # 自动更新当前 PATH 中检测到的全部 Mearl 环境
240
- npx @mearl/setup@3 update
243
+ npx @mearl/setup update
241
244
 
242
245
  # 独立安装或更新到最新浏览器扩展
243
- npx @mearl/setup@3 extension
246
+ npx @mearl/setup extension
244
247
 
245
248
  # 安装完整本地环境（client、Native Host、Skill 和扩展）
246
- npx @mearl/setup@3 extension --full
249
+ npx @mearl/setup extension --full
247
250
 
248
251
  # 只卸载本地环境
249
- npx @mearl/setup@3 uninstall --local
252
+ npx @mearl/setup uninstall --local
250
253
 
251
254
  # 自动检测并无交互卸载
252
- npx @mearl/setup@3 uninstall --yes
255
+ npx @mearl/setup uninstall --yes
253
256
 
254
257
  # 卸载环境，并清理全部 CLI 插件与 Provider
255
- npx @mearl/setup@3 uninstall --full
258
+ npx @mearl/setup uninstall --full
256
259
 
257
260
  # 安装可选浏览器 Provider
258
- npx @mearl/setup@3 provider install @example/mearl-provider-device
259
- npx @mearl/setup@3 provider install @example/mearl-provider-cloud
261
+ npx @mearl/setup provider install @example/mearl-provider-device
262
+ npx @mearl/setup provider install @example/mearl-provider-cloud
260
263
  ```
261
264
 
262
265
  原有 Mearl 环境包的 npm/npx 安装方式和 CLI 保持可用；setup 是统一的便利入口。
@@ -273,4 +276,4 @@ install/update 在替换包前保存选中 Preset 的确切资源和期望选择
273
276
 
274
277
  主动执行 setup 时，先沿用本机已选 preset；本机未选择时，在运行时初始化后、安装 Skill 前采用已连接浏览器的受信 preset。显式 `--preset <source>` 优先。多个浏览器的选择不同、来源不受信或状态读取失败时要求显式选择。首次连接最多等待约一分钟；浏览器关闭时只安装基础环境并说明重试方式。普通连接和后台核心更新不会自动安装首次本机 preset。
275
278
 
276
- 发行包可设置本机进程环境变量 `MEARL_SETUP_DEFAULT_PRESET` 提供默认清单来源；默认值仅在两端均无选择时生效，插件、Provider、卸载等子命令保持原行为。安装与状态核验仍由公共安装器负责。
279
+ 发行包可设置本机进程环境变量 `MEARL_SETUP_DEFAULT_PRESET` 提供默认清单来源；默认值仅在两端均无选择时生效，插件、Provider、卸载等子命令保持原行为。安装与状态核验仍由安装器负责。
package/dist/cli.d.ts CHANGED
@@ -16,7 +16,7 @@ interface ParsedArgs {
16
16
  operation?: MearlLifecycleOperation | 'extension' | 'plugin' | 'provider' | 'preset' | 'profile';
17
17
  profileSource?: string;
18
18
  profileBrowser?: string;
19
- presetCommand?: 'apply' | 'update' | 'status' | 'repair';
19
+ presetCommand?: Exclude<Parameters<typeof runPresetCommand>[0], 'repair'>;
20
20
  presetSource?: string;
21
21
  presetReplaceSkills?: string[];
22
22
  pluginName?: string;
package/dist/cli.js CHANGED
@@ -2,8 +2,8 @@
2
2
  import { Command, CommanderError } from 'commander';
3
3
  import { invoke, listLiveBrowsers } from '@mearl/client/local';
4
4
  import { parseProfileSource } from '@mearl/preset/bundles';
5
- import { downloadMearlBrowserExtension, installMearlBrowserExtension, isUnsupportedCdpMethodError } from './browserExtension.js';
6
- import { runMearlLifecycle } from './lifecycle.js';
5
+ import { downloadMearlBrowserExtension, installMearlBrowserExtension, isUnsupportedCdpMethodError, } from './browserExtension.js';
6
+ import { runMearlLifecycle, } from './lifecycle.js';
7
7
  import { isMearlReleaseLine } from './version.js';
8
8
  import { ensureOfficialPlugin, installPlugins, setupPlugin, uninstallPlugin } from './plugin.js';
9
9
  import { installProviderPackage, uninstallProviderPackage, updateProviderPackage, } from './provider.js';
@@ -30,18 +30,28 @@ export function parseSetupArgs(argv) {
30
30
  if (argv[0] === 'profile') {
31
31
  if (argv.length === 2 && (argv[1] === '--help' || argv[1] === '-h'))
32
32
  return { ...baseParsedArgs(), help: true };
33
- if (argv[1] !== 'install' || !argv[2] || (argv.length !== 3 && !(argv.length === 5 && argv[3] === '--browser' && argv[4]))) {
33
+ if (argv[1] !== 'install' ||
34
+ !argv[2] ||
35
+ (argv.length !== 3 && !(argv.length === 5 && argv[3] === '--browser' && argv[4]))) {
34
36
  throw new Error('profile requires install <GitHub owner/repo[@ref] or HTTPS bundle URL> [--browser <id-or-name>]');
35
37
  }
36
38
  parseProfileSource(argv[2]);
37
- return { ...baseParsedArgs(), operation: 'profile', profileSource: argv[2], profileBrowser: argv[4] };
39
+ return {
40
+ ...baseParsedArgs(),
41
+ operation: 'profile',
42
+ profileSource: argv[2],
43
+ profileBrowser: argv[4],
44
+ };
38
45
  }
39
46
  if (argv[0] === 'preset') {
40
- if (argv[1] === 'repair') {
41
- const command = new Command('preset repair')
47
+ if (argv.length === 2 && (argv[1] === '--help' || argv[1] === '-h'))
48
+ return { ...baseParsedArgs(), help: true };
49
+ if (argv[1] === 'apply') {
50
+ const command = new Command('preset apply')
42
51
  .exitOverride()
43
52
  .configureOutput({ writeErr: () => { }, writeOut: () => { } })
44
53
  .allowExcessArguments(false)
54
+ .argument('[source]')
45
55
  .option('--replace-skill <name>', 'Replace the named Skill source or conflicting plugin registration', (name, previous) => [...previous, name], []);
46
56
  try {
47
57
  command.parse(argv.slice(2), { from: 'user' });
@@ -55,15 +65,27 @@ export function parseSetupArgs(argv) {
55
65
  throw error;
56
66
  }
57
67
  const names = command.opts().replaceSkill;
58
- if (names.length > 256 || new Set(names).size !== names.length || names.some(name => !/^[a-z][a-z0-9-]{0,79}$/.test(name)))
68
+ if (names.length > 256 ||
69
+ new Set(names).size !== names.length ||
70
+ names.some(name => !/^[a-z][a-z0-9-]{0,79}$/.test(name)))
59
71
  throw new Error('--replace-skill requires unique valid Skill names (up to 256)');
60
- return { ...baseParsedArgs(), operation: 'preset', presetCommand: 'repair', ...(names.length ? { presetReplaceSkills: names } : {}) };
72
+ const source = command.args[0];
73
+ if (source !== undefined && !source.trim())
74
+ throw new Error('Expected a preset source URL or path');
75
+ if (source !== undefined && names.length)
76
+ throw new Error('--replace-skill requires preset apply without a source');
77
+ return {
78
+ ...baseParsedArgs(),
79
+ operation: 'preset',
80
+ presetCommand: 'apply',
81
+ presetSource: source,
82
+ ...(names.length ? { presetReplaceSkills: names } : {}),
83
+ };
61
84
  }
62
- if (argv[1] === 'apply' && argv.length === 3 && argv[2])
63
- return { ...baseParsedArgs(), operation: 'preset', presetCommand: 'apply', presetSource: argv[2] };
64
- if ((argv[1] === 'update' || argv[1] === 'status') && argv.length === 2)
85
+ if ((argv[1] === 'update' || argv[1] === 'status' || argv[1] === 'uninstall') &&
86
+ argv.length === 2)
65
87
  return { ...baseParsedArgs(), operation: 'preset', presetCommand: argv[1] };
66
- throw new Error('preset requires apply <source-url-or-path>, update, repair [--replace-skill <name>], or status');
88
+ throw new Error('preset requires apply [source-url-or-path], update, status, or uninstall');
67
89
  }
68
90
  if (argv[0] === 'provider') {
69
91
  const command = argv[1];
@@ -223,10 +245,10 @@ Environment commands:
223
245
 
224
246
  Integration commands:
225
247
  profile install <source> Install one App profile bundle in a connected extension
226
- preset apply <source> Apply a preset, synchronize hosts and install declared components
248
+ preset apply [source] Apply a URL or local file, or retry the saved snapshot
227
249
  preset update Update the selected preset, preserving user overrides
228
- preset repair Retry the installed preset using its accepted resources
229
250
  preset status Report actual readiness (exit 3 when synchronization is pending)
251
+ preset uninstall Remove the preset from the local host and connected extensions
230
252
  plugin install <arguments...> Install Skills and register their CLI plugins
231
253
  plugin uninstall <name> Uninstall one CLI plugin
232
254
  plugin [name] <path> Register an existing plugin; name overrides metadata
@@ -254,7 +276,7 @@ Extension options:
254
276
  --full Install the extension and complete local environment
255
277
  --force Replace an extension managed by another source
256
278
 
257
- Preset repair options:
279
+ Preset apply options (without a source):
258
280
  --replace-skill <name> Replace one Skill source or conflicting registration; repeat for more
259
281
 
260
282
  General options:
@@ -271,13 +293,19 @@ Examples:
271
293
  npx @mearl/setup uninstall --full
272
294
  npx @mearl/setup plugin uninstall tabs
273
295
  npx @mearl/setup provider install @example/mearl-provider-device
274
- npx @mearl/setup preset repair --replace-skill example-skill
296
+ npx @mearl/setup preset apply --replace-skill example-skill
275
297
  npx @mearl/setup extension --full`;
276
298
  console.log(output.replaceAll('npx @mearl/setup', SETUP_COMMAND));
277
299
  }
278
300
  async function runSetupLifecycle(options, dependencies) {
279
301
  let preset;
280
- const callback = options.operation === 'uninstall' ? undefined : { onPresetStatus: (status) => { preset = status; } };
302
+ const callback = options.operation === 'uninstall'
303
+ ? undefined
304
+ : {
305
+ onPresetStatus: (status) => {
306
+ preset = status;
307
+ },
308
+ };
281
309
  const lifecycle = dependencies.runLifecycle ?? runMearlLifecycle;
282
310
  const defaultPresetSource = process.env.MEARL_SETUP_DEFAULT_PRESET;
283
311
  const configured = defaultPresetSource ? { ...options, defaultPresetSource } : options;
@@ -298,7 +326,8 @@ async function runSetupLifecycle(options, dependencies) {
298
326
  }
299
327
  async function installProfile(source, browser) {
300
328
  if (!browser) {
301
- const extensions = listLiveBrowsers().filter(target => target.transport === 'extension' && (target.status === undefined || target.status === 'connected'));
329
+ const extensions = listLiveBrowsers().filter(target => target.transport === 'extension' &&
330
+ (target.status === undefined || target.status === 'connected'));
302
331
  if (extensions.length !== 1)
303
332
  throw new Error(extensions.length
304
333
  ? 'Multiple extensions are connected. Select one with --browser <id-or-name>.'
@@ -341,7 +370,9 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
341
370
  try {
342
371
  const run = dependencies.runPreset ?? runPresetCommand;
343
372
  const result = parsed.presetReplaceSkills
344
- ? await run(parsed.presetCommand, parsed.presetSource, { replaceSkills: parsed.presetReplaceSkills })
373
+ ? await run(parsed.presetCommand, parsed.presetSource, {
374
+ replaceSkills: parsed.presetReplaceSkills,
375
+ })
345
376
  : await run(parsed.presetCommand, parsed.presetSource);
346
377
  console.log(JSON.stringify(result, null, 2));
347
378
  return result.ready ? 0 : 3;
package/dist/preset.d.ts CHANGED
@@ -93,16 +93,21 @@ export declare class PresetInstaller {
93
93
  private stageSource;
94
94
  /** Save exact resources and desired selection; activate once after runtime setup, then retry via resume. */
95
95
  stage(source: string, options?: PresetApplyOptions): Promise<StagedPresetInstallation>;
96
- apply(source: string, options?: PresetApplyOptions): Promise<PresetInstallStatus>;
96
+ apply(source?: string, options?: PresetApplyOptions & {
97
+ replaceSkills?: readonly string[];
98
+ }): Promise<PresetInstallStatus>;
97
99
  update(options?: Pick<PresetApplyOptions, 'validatePrepared' | 'skipUnchanged' | 'signal'>): Promise<PresetInstallStatus>;
98
100
  resume(expectedRevision: string, options?: {
99
101
  replaceSkills?: readonly string[];
100
102
  }): Promise<PresetInstallStatus>;
103
+ private resumeSelected;
104
+ /** @deprecated Use apply() without a source. */
101
105
  repair(options?: {
102
106
  replaceSkills?: readonly string[];
103
107
  }): Promise<PresetInstallStatus>;
108
+ uninstall(): Promise<PresetInstallStatus>;
104
109
  configure(value: JsonObject): Promise<PresetInstallStatus>;
105
110
  }
106
- export declare function runPresetCommand(command: 'apply' | 'update' | 'status' | 'repair', source?: string, options?: {
111
+ export declare function runPresetCommand(command: 'apply' | 'update' | 'status' | 'uninstall' | 'repair', source?: string, options?: {
107
112
  replaceSkills?: readonly string[];
108
113
  }): Promise<PresetInstallStatus>;