MultiAgentor CLI

MultiAgentor CLI 是面向 AI Agent 的本地浏览器执行器。它把浏览器身份、场景包、任务和运行记录统一管理，让 Agent 按自然语言流程操作浏览器，并在多次运行之间保留登录状态。

项目采用“场景描述流程、Agent 判断下一步、CLI 执行动作”的方式：场景包告诉 Agent 要做什么，Agent 根据页面快照决定如何继续，CLI 提供受限的浏览器操作和本地运行证据。

核心能力

• 场景管理：搜索官方场景、下载流程包、查看本地场景；每次运行固定所使用的场景版本。
• 浏览器身份：创建和复用 Browser Profile，保存网站登录状态，支持独立打开浏览器、配置代理和导入导出 Cookie。
• 任务管理：将场景、浏览器和参数组合为可重复使用的任务，支持创建、修改、删除及手动运行。
• Agent 浏览器操作：通过 JSONL 会话执行 goto、snapshot、click、type、select、scroll、wait、back、reload 和 close。
• 运行管理：查看运行状态与日志、请求停止，保存场景快照、截图和结果文件。
• 独立工作区：账号数据相互隔离；同一 Profile 同时只允许一个 Run，不同 Profile 可以并行使用。

CLI 不自行调用模型，也不自动解释场景流程。运行任务需要当前 Agent 会话监督，或由调用方发送 JSONL 指令；任务目前只支持手动触发。

工作方式

用户提出目标
    ↓
Agent 读取场景包（scenario.json + SKILL.md）
    ↓
创建任务：场景 + Browser Profile + 参数
    ↓
Agent ↔ CLI：观察页面、执行动作、判断结果
    ↓
结束 Run，保存证据，保留 Profile 登录状态

浏览器动作成功只表示操作完成；是否达到业务目标，由 Agent 根据场景要求和实际页面判断。

安装

运行环境：Node.js 22+。浏览器运行时支持 Windows x64 和 Apple Silicon macOS；从源码构建还需要 pnpm 10+。

npm 包名为 multiagentor-scenario-cli，安装后的命令为 multiagentor。

npm 全局安装

npm install -g multiagentor-scenario-cli
multiagentor --help
multiagentor --version

从源码本地安装

在仓库目录执行：

pnpm install
pnpm build
npm install -g .
multiagentor --help
multiagentor --version

安装后可从任意目录运行 multiagentor。本地目录安装会关联源码目录，请保留该目录及依赖；源码更新后执行 pnpm build。如果命令未被识别，重新打开终端并检查 npm 全局目录是否位于 PATH。

首次启动浏览器时，CLI 会下载并校验 MultiAgentBrowser。也可以通过 MULTIAGENTOR_BROWSER_EXECUTABLE 指定已准备好的运行时绝对路径；项目不会下载 Playwright Chromium 或使用系统 Chrome 替代。

快速开始

以下示例适用于 Windows PowerShell。先准备可用的服务账号，将占位符替换为实际值；场景 ID 使用搜索结果中的 ID，浏览器和任务 ID 使用创建命令的返回值。

1. 登录并下载场景

multiagentor auth oauth
multiagentor auth status
multiagentor scenario search --query "X" --page 1 --page-size 20
multiagentor scenario get "<scenarioId>"

下载后得到 scenario.json 和 SKILL.md。Agent 应先读取场景流程，确认所需参数；场景更新需要再次显式下载。

2. 创建浏览器身份

multiagentor browser create --name "主浏览器" --system-os windows --system-version 11 --kernel-brand chrome --kernel-version 149
multiagentor browser list
multiagentor browser launch "<browserId>"

创建只保存配置，不启动浏览器。browser launch 打开可见窗口，可供人工登录网站；关闭窗口后，登录状态保留在该 Profile 中。macOS 请改用 --system-os macos 和服务端支持的系统版本。

3. 创建并运行任务

multiagentor task create --name "浏览任务" --scenario "<scenarioId>" --browser "<browserId>"
multiagentor task run "<taskId>"

有业务参数时，在创建命令中追加 --params-file "params.json"，文件内容为场景需要的 JSON 对象。

task run 启动浏览器并输出 run-started、Run ID 和 skillPath，随后等待调用方发送动作。Agent 读取 skillPath 中的流程，使用同一个进程的 stdin/stdout 持续观察和操作页面。直接运行这条命令不会自动完成场景。

4. 发送动作并结束会话

在仍运行的 task run 会话中，每次发送一整行 JSON，等待响应：

{"protocolVersion":"1.0","requestId":"1","action":"goto","params":{"url":"https://example.com"}}
{"protocolVersion":"1.0","requestId":"2","action":"snapshot","params":{}}
{"protocolVersion":"1.0","requestId":"3","action":"close","params":{"status":"stopped","reason":"example-ended"}}

这些是 JSONL 指令，不是 PowerShell 命令。点击、输入或定向滚动需要使用最新快照里的元素 ref；scroll 可传 {"ref":"<ref>","deltaY":480}，先把鼠标移动到目标中央，再滚动目标所在的内部容器。省略 ref 时仍在当前鼠标位置滚动。页面变化后重新获取快照。结束状态可选 succeeded、failed、stopped，只有实际达到场景目标时才使用 succeeded。

snapshot 返回视口感知的结构化观察：blocks 保存可见正文，elements 保存可交互元素及当前代 ref，scope 说明视口与上下 1000px 缓冲区，stats 和 truncated 说明裁剪情况。每次获取快照都会生成新一代引用，上一代 ref 立即失效；响应不再提供旧的顶层 text 字段。

另一个终端可查看或停止运行：

multiagentor run inspect "<runId>"
multiagentor run logs "<runId>" --tail 100
multiagentor run cancel "<runId>"

取消返回 pending: true 时，用 run inspect 确认最终状态。

命令概览

完整参数请执行 multiagentor --help。

| 命令组 | 子命令 | 用途 | |---|---|---| | auth | oauth / status / logout | 通过浏览器授权并管理服务账号会话 | | scenario | search / get / list | 搜索、下载与查看场景 | | browser | create / list / inspect / launch | 管理浏览器身份与独立启动 | | browser | proxy / export / import / cookie-import / delete | 代理、浏览器包和 Cookie 维护 | | task | create / list / inspect / update / delete / run | 管理和执行任务 | | run | list / inspect / logs / cancel | 查询与控制运行 | | data | path / migrate | 查看数据路径及迁移工作区 |

旧本地场景的 scenario resolve / scenario inspect 命令现已关闭。

配置与数据

| 环境变量 | 用途 | |---|---| | MULTIAGENTOR_API_URL | 覆盖服务 API 地址 | | MULTIAGENTOR_DATA_DIR | 指定工作区绝对路径 | | MULTIAGENTOR_BROWSER_EXECUTABLE | 指定 MultiAgentBrowser 运行时绝对路径 |

默认工作区：

| 系统 | 目录 | |---|---| | Windows | <用户主目录>/.multiagentor-scenario-cli | | macOS | <用户主目录>/Library/Application Support/multiagentor-scenario-cli | | Linux / 其他 POSIX | $XDG_DATA_HOME/multiagentor-scenario-cli，否则 <用户主目录>/.local/share/multiagentor-scenario-cli |

Linux 路径解析可用，浏览器运行时目前仍仅支持 Windows x64 / macOS ARM64。用 multiagentor data path 查看当前实际路径。工作区独立于旧版 MultiAgentor，保存 SQLite 数据库、场景包、浏览器 Profile 和 Run 证据。

auth oauth 会打开 app.multiagentor.com 授权页并轮询设备授权结果；CLI 不接收或保存登录密码。浏览器无法自动打开时，终端会给出可信授权地址供手动访问。本地数据库包含会话 Token 和代理凭据，导出的浏览器包含明文配置与 Cookie，请保存在用户私有目录。截图可能包含页面敏感信息，分享前应检查。浏览器包只迁移配置与 Cookie，不复制整个 Profile，也不能保证恢复所有网站登录状态。

开发

项目使用 TypeScript、Playwright Core 和 SQLite。

pnpm install
pnpm typecheck
pnpm test:unit
pnpm test:integration
pnpm build

集成测试需要已准备好的 MultiAgentBrowser，访问本机临时 HTTP 页面并使用临时 Profile。

| 目录 | 内容 | |---|---| | src/bin/ | CLI 程序入口 | | src/cli/ | 命令路由 | | src/modules/ | 工作区、浏览器执行与协议模块 | | src/shared/ | 公共类型和工具 | | tests/ | 自动化测试与验收材料 | | scripts/ | 场景上传等维护脚本 | | skills/ / scenarios-v2/ | Agent Skill 与当前维护的 V2 场景包 | | docs/ | 接口契约、使用参考与工程文档 |

更多文档

• CLI 技术参考：浏览器维护、代理、JSONL、旧协议与工作区迁移。
• 手工测试清单：逐项验证 CLI 功能。
• 服务端 API 契约：服务接口与场景包格式。
• 场景包开发流程：需求、开发、测试、Review 与上传关口。
• 场景上传说明：维护者使用的独立上传脚本。