@mearl/setup

Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全局安装 setup：

npx @mearl/setup [install] [--local] [--cloud|--qoder-cloud] [--mcp]
npx @mearl/setup update [--local] [--cloud|--qoder-cloud] [--mcp]
npx @mearl/setup uninstall [--local] [--cloud|--qoder-cloud] [--mcp] [--full]
npx @mearl/setup extension [--full] [--force]
npx @mearl/setup plugin [name] <path>
npx @mearl/setup plugin install <ali-skills add 参数...>
npx @mearl/setup plugin uninstall <name>
npx @mearl/setup provider <install|update|uninstall> <package|id>

浏览器 Provider 独立安装和演进。安装后运行 mearl <providerId> 查看该版本声明的能力、 配置和启动参数。

在 Qoder Cloud Agent 环境中，使用 npx @mearl/setup --qoder-cloud --yes 选择 Qoder 配对模式。它与 --cloud 安装同一套 cloud-server、client 和 Skill，只把 cloud-server 模式记录为 Qoder；mearl-cloud-server 的命令交互保持不变，start 和 restart 输出新的 配对指令后退出，不监听端口或保留守护进程。配对 URL 不包含 Qoder PAT。

安装与注册 Skill 插件

一个命令安装 skill 并注册它的 CLI、SDK 和 MCP 能力：

npx @mearl/setup plugin install trip/mearl --skill yuque-doc-fetch --yes
mearl yuque read "https://aliyuque.antfin.com/group/book/doc"

安装参数透传给 npx -y ali-skills add，末尾统一追加 --global --install-mode symlink；不接受会截断后置选项的 -- 参数分隔符， 确保 skill 存放在 ~/.agents/skills 并共享给所选 agent。安装日志实时显示，保留交互； setup 从 Installed … skill(s) 成功区块提取路径，仅注册本次安装且包含 scripts/main.mjs 或 scripts/main.py 的 skill；两者同时存在时使用 JavaScript 入口。 普通 skill 正常安装。输出格式无法识别时提示手动注册，不扫描其他 skill 或猜测安装结果。

默认 install 和 update 会用最多 5 秒的 npm ping 检查阿里内网 registry。 registry 可访问时通过 Ali Skills 批量处理 mearl 与 tdbank-account：安装使用一次 add 并注册 TDBank 插件，更新已跟踪项使用一次 update；卸载时使用一次 remove 批量移除 setup 管理的 Skill。 更新发现 TDBank 插件缺少注册时，会在批量更新已跟踪项后通过一次 add 补装并恢复注册。 该 registry 不用于下载插件。 探测不可用时按普通外网流程只处理 Mearl Skill；内网批量命令失败时 setup 失败，不再逐项重试。 --skip-skill 和 --target-line 安装不执行自动插件步骤。

Mearl client 内置 buc、authx 与 tdbank 的安装来源。CLI、SDK、MCP 或另一个插件首次调用尚未注册的这些插件时，会通过内部幂等流程安装并重试一次；其他未注册名称不会触发安装。BUC 与 AuthX 不随 setup 预装。

自动注册默认使用安装目录名；入口可声明 name 指定简短命令名。 重装会刷新同名绑定。JavaScript 入口必须默认导出 register(app)，Python 入口必须导出 register(app) 函数；完整协议见 Skill 插件规范。

已通过其他渠道分发的 skill 或自定义入口，可以直接传入路径注册：

npx @mearl/setup plugin /absolute/path/to/yuque-doc-fetch
npx @mearl/setup 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 工具调用。已注册插件的日常调用不执行安装或版本检查；只有缺失的 buc、authx 或 tdbank 会触发一次按需安装。

不再需要插件时执行：

npx @mearl/setup plugin uninstall yuque

若入口位于 ~/.agents/skills/<skill>/，setup 会先执行 ali-skills remove <skill> --global --yes，成功后清除该 Skill 对应的全部插件注册； 入口目录已被手动删除时会让 Ali Skills 仍能识别本次移除，从而一并清理其跟踪记录。 移除失败时保留注册以便重试。手工注册的其他路径只解除 Mearl 注册，不删除源码。 重复卸载未注册名称会成功返回，不产生改动。

管理浏览器 Provider

Provider 由 npm 包分发，但包本身无需暴露 CLI 或安装脚本。setup 使用当前 npm 包管理器 完成全局包生命周期，再读取包内的 package.json#mearl.provider 元数据登记协议入口、 可创建的浏览器类型名称及其表单参数：

npx @mearl/setup provider install @ali/mearl-provider-brow
npx @mearl/setup provider update brow
npx @mearl/setup provider uninstall brow

安装参数接受包名、版本或 dist-tag；更新和卸载可使用 providerId 或完整包名。@ali/* 包的 安装和更新固定使用 https://registry.anpm.alibaba-inc.com/。安装沿用启动 setup 的包管理器， 更新和卸载沿用当前 Provider 的原包管理器。Provider 登记只保存 经过校验的包名、安装目录和包内入口；不接受包自行注入启动命令、参数、工作目录或环境变量。 卸载仅在包管理器成功移除包后清除登记，以便失败时可以重试。

行为

• install 可以省略；直接执行 npx @mearl/setup 等同于 npx @mearl/setup install。 以选项开头时也默认安装，例如 npx @mearl/setup --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 的包管理器。
• 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 通过 ali-skills 的 JSON 清单定位，只处理一次。
• 安装始终通过 ali-skills add --install-mode symlink 写入最新的全局 mearl skill，并关联当前检测到的 Agent； 可用 --skip-skill 跳过。
• 卸载一个环境但另一个仍依赖全局 mearl skill 时会保留 skill。
• uninstall --full 在环境卸载之外，还会逐项卸载所有已注册 CLI 插件与浏览器 Provider。 Ali Skills 安装的插件会同时移除 Skill；手工注册的外部插件只清除注册、保留源码；Provider 只有在包管理器成功卸载 npm 包后才清除注册。单项失败不阻止其他项继续清理，命令最终返回非零。 该选项不删除 Chrome 扩展；extension --full 仍表示安装扩展及完整本地环境。
• --mcp 的客户端配置和清理由 @mearl/mcp-server 自己的命令完成。
• 默认的 install / update 不处理浏览器扩展。extension 是独立命令：从 https://mearl.alibaba-inc.com/ 识别并下载最新的 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 才会接管并替换这些版本。

安装或更新浏览器扩展

npx @mearl/setup extension

首次使用时可一次安装完整的本地浏览器环境：

npx @mearl/setup extension --full

首次安装、旧版 setup 扩展首次迁移，或 Native Host reload 不可用时才需要 CDP。如果 Chrome 尚未开放 CDP，交互命令会提示打开 chrome://inspect/#remote-debugging、启用远程调试并允许连接，然后等待安装完成。面向人的 安装指引不要添加 --yes。无 TTY 环境使用 npx @mearl/setup 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 update --local。

人工与 Agent 使用

• 人工在终端执行时不加 --yes，需要选择 Skill 安装目标或 MCP 客户端时会显示交互提示。
• Agent、CI 或其他无 TTY 环境应加 --yes（也可写 --non-interactive）。首次安装会选择已检测到的 Agent / MCP 客户端，卸载会清理 所有已检测到的相关配置。
• 无 TTY 环境执行 install 或 uninstall 却未加上述参数时，会在任何改动前退出并提示正确命令。
• 退出码 0 表示完整成功，1 表示执行未完成，2 表示参数或交互模式不适用。

示例

# 默认安装本地浏览器环境
npx @mearl/setup

# 与上一条等价
npx @mearl/setup install

# Agent / CI 无交互安装
npx @mearl/setup --yes

# 安装云端 Agent 环境
npx @mearl/setup --cloud

# 同一台机器同时作为本地浏览器宿主和云端 Agent
npx @mearl/setup --local --cloud

# 自动更新当前 PATH 中检测到的全部 Mearl 环境
npx @mearl/setup update

# 独立安装或更新到最新浏览器扩展
npx @mearl/setup extension

# 安装完整本地环境（client、Native Host、Skill 和扩展）
npx @mearl/setup extension --full

# 只卸载本地环境
npx @mearl/setup uninstall --local

# 自动检测并无交互卸载
npx @mearl/setup uninstall --yes

# 卸载环境，并清理全部 CLI 插件与 Provider
npx @mearl/setup uninstall --full

# 安装可选浏览器 Provider
npx @mearl/setup provider install @ali/mearl-provider-brow
npx @mearl/setup provider install @ali/mearl-provider-agentbay

原有 Mearl 环境包的 npm/npx 安装方式和 CLI 保持可用；setup 是统一的便利入口。