@mearl/setup

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

npx @mearl/setup [install] [--local] [--cloud] [--mcp] [--yes]
npx @mearl/setup <update|uninstall> [--local] [--cloud] [--mcp] [--yes]

配置 AgentBay API Key 时只需执行一次下面的命令，然后在隐藏输入提示中粘贴 Key。 重复执行会更新现有 Key，并保留 ~/.mearl/.env 中的其他配置：

npx @mearl/setup agentbay

无交互环境可使用 --stdin 或 --key-file <path>。为避免 Key 进入 shell history 和 进程参数，不接受把 Key 直接写在命令行中。

Qoder Cloud Agent 仅在常规云连接失败、Mearl Skill 进入 Qoder 异常接管分支时使用 npx @mearl/setup qoder --yes 生成一次性配对指令。它不安装额外隧道，也不会把 Qoder PAT 写入配对 URL；正常安装和连接流程无需执行该命令。

行为

• 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 可以组合，显式传入时只处理选中的环境。
• 已有环境沿用其原包管理器和全局安装前缀；首次安装沿用启动 setup 的包管理器。
• cloud 环境统一管理 @mearl/cloud-server 与 @mearl/client：首次安装后启动 Server，更新后仅在 Server 原本运行时重启，卸载前停止。
• local/cloud 共用一份 @mearl/client；组合安装只处理一次，卸载单个环境时若另一个环境仍在使用则保留。
• 从 2.5.x 更新 cloud 环境时会先卸载旧 @mearl/cloud-client，避免它遗留的 mearl bin 与统一 client 冲突。
• local/cloud 共用的全局 mearl skill 通过 ali-skills 的 JSON 清单定位，只处理一次。
• 安装始终通过 ali-skills add 写入最新的全局 mearl skill，并关联当前检测到的 Agent； 可用 --skip-skill 跳过。
• 卸载一个环境但另一个仍依赖全局 mearl skill 时会保留 skill。
• --mcp 的客户端配置和清理由 @mearl/mcp-server 自己的命令完成。

跟随浏览器扩展自动更新

浏览器扩展与 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 uninstall --local

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

# 配置或更新 AgentBay API Key
npx @mearl/setup agentbay

# 无交互配置（从权限受控的文件读取）
npx @mearl/setup agentbay --key-file ./agentbay.key

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