OpenCLI 的 Manus 适配器实战指南:用 Connect-RPC 把 manus.im 变成纯读 CLI
OpenCLI 的 Manus 适配器实战指南:用 Connect-RPC 把 manus.im 变成纯读 CLI
导读
Manus(manus.im)是一款主打"Hands On AI"的自主智能体 Web 应用,用户可以在浏览器中让它执行多步骤任务,并消耗账户信用额度(credits)。OpenCLI 以浏览器适配器(Browser Adapter)的方式为其提供了一套纯只读的命令行接口:你无需抓取 DOM、无需逆向前端 JS,就能在终端里查询账户快照、会话列表、会话详情、信用额度、连接器与技能。读完本文,你将掌握该适配器的认证机制(Cookie 复用 + Connect-RPC)、全部 6 个命令的用法与参数、底层实现原理,以及它刻意不暴露破坏性操作的工程考量。
一、适配器定位与整体架构
OpenCLI 中每个网站适配器位于 clis/ 目录下,Manus 适配器集中在 clis/manus/,包含 6 个业务命令文件(status.js、list.js、read.js、credits.js、connectors.js、skills.js)、共享工具 clis/manus/_utils.js、站点登录注册 clis/manus/auth.js 以及完整测试 clis/manus/manus.test.js。
适配器使用 Cookie 策略(Strategy.COOKIE):它不持有 Manus 的账号密码,而是复用用户在 OpenCLI Browser Bridge 中已经登录的浏览器会话。所有命令都声明为 access: 'read'、browser: true、siteSession: 'persistent',即只读取数据、不修改任何远程状态。
终端 (opencli manus ...)
│
▼
OpenCLI Browser Bridge(已登录 manus.im 的浏览器页面)
│ 注入 callManusAPI(),读取 session_id cookie
▼
https://api.manus.im/ (Connect-RPC POST + JSON)
二、认证机制:Cookie 复用 + Connect-RPC Bearer
2.1 登录与身份校验
适配器通过 clis/manus/auth.js 调用通用站点认证模块 registerSiteAuthCommands(定义于 clis/_shared/site-auth.js),自动注册 opencli manus login 与 opencli manus whoami 两个命令:
login:打开https://manus.im/login,等待用户在浏览器中完成登录;whoami:返回user_id与name两列身份信息。
其身份校验流程 verifyManusIdentity 分两步:
- 检查
https://manus.im域名下是否存在auth_session、manus_token、_session、session等会话 Cookie; - 请求
https://manus.im/api/auth/session(携带凭据)探测用户身份,若无id/userId字段则判定为未登录,抛出AuthRequiredError。
2.2 核心:session_id 复用为 Bearer Token
真正被业务命令使用的是名为 session_id 的 Cookie,它内部是一个约 357 字节的 JWT。共享工具 clis/manus/_utils.js 中定义了三个关键常量:
export const MANUS_DOMAIN = 'manus.im';
export const MANUS_URL = 'https://manus.im/app';
export const API_HOST = 'https://api.manus.im';
并注入一段浏览器端 IIFE MANUS_API_CALL_JS,其中 callManusAPI(rpcPath, body) 完成整条 RPC 调用链:
const jwt = document.cookie.split('session_id=')[1]?.split(';')[0];
const r = await fetch('https://api.manus.im/' + rpcPath, {
method: 'POST',
credentials: 'include',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + jwt,
'Connect-Protocol-Version': '1',
},
body: JSON.stringify(body || {}),
});
要点:
- Bearer 认证:JWT 直接作为
Authorization: Bearer <token>请求头; - Connect-RPC 协议:请求头
Connect-Protocol-Version: 1,路径为<包名>.<Service>/<Method>风格,POST + JSON body; - 同源语义:由于
fetch是在manus.im域名的页面上下文中执行,配合credentials: 'include'能复用 Cookie 会话; - 失败标记:无 Cookie 返回
{ __authRequired: true },HTTP 非 2xx 返回{ __httpError: status, message },JSON 解析失败返回{ __error: 'invalid_json' }——这些标记会被下游requireObject等守卫识别并转换为对应的 OpenCLI 异常类型(AuthRequiredError/CommandExecutionError)。
每个业务命令执行前还会调用 ensureOnManus(page):先读取 window.location.href 判断是否已在 manus.im 域名下,否则跳转到 https://manus.im/app 并等待 2 秒,确保脚本运行在正确的站点上下文中。
三、命令总览
适配器注册的全部命令(均只读):
| 命令 | 说明 | 默认/参数 |
|---|---|---|
manus status |
账户快照:邮箱、显示名、用户 ID、会员层级、核心信用数字 | 无参数 |
manus list [--limit N] [--archived] |
列出最近会话,id 可直接回传 read 使用;默认隐藏已归档会话 |
--limit 默认 20 |
manus read <uid> |
展示单个会话的字段级详情(用 list 输出的 id 查找) |
uid 为位置参数 |
manus credits |
完整信用额度拆分 | 无参数 |
manus connectors [--limit N] |
列出可用连接器(Apify、GitHub、Outlook、Slack 等) | --limit 默认 50 |
manus skills |
列出技能,区分用户添加(source=user)与系统(source=system) |
无参数 |
clis/manus/manus.test.js 的第 1 组用例验证了这 6 个命令均以 access: 'read'、domain: 'manus.im'、siteSession: 'persistent' 注册到命令注册表。
四、命令详解与示例输出
4.1 manus status:账户快照
对应 clis/manus/status.js。它通过 Promise.all 并发调用两个 RPC:
user.v1.UserService/UserInfouser.v1.UserService/GetAvailableCredits
合并输出为 Field / Value 两列:
$ opencli manus status
Field: Email Value: zhongyuelin990405@gmail.com
Field: Display Name Value: Lin Zhongyue
Field: Membership Tier Value: 60
Field: Total Credits Value: 12311
Field: Periodic Credits Value: 12000
Field: Refresh Credits Value: 300
源码同时会输出 User ID 与 Next Refresh 字段。注意 Email/Display Name/User ID/Membership Tier 来自 UserInfo,Total/Periodic/Refresh Credits 与 Next Refresh 来自 GetAvailableCredits——两条 RPC 的返回在浏览器内合并后一次交回。
4.2 manus list:会话列表
对应 clis/manus/list.js,调用 session.v1.SessionService/ListSessions,请求体为 { page: 1, pageSize: <limit> }。
--limit:正整数,默认 20,上限 200,经validatedLimit()校验(拒绝负数、零、NaN、非整数,超出范围抛ArgumentError);--archived:布尔开关,默认 false;不传时在客户端过滤掉isArchived: true的会话;- 输出列为
id / Title / Status / Last Message / Last Updated / Credits;Status会去掉SESSION_STATUS_前缀并转小写(如stopped),Credits即该会话消耗的costedCredits; - 结果为空时抛
EmptyResultError。
$ opencli manus list --limit 3
id: 8UcpCxMFLrNk63ZJmzALfV Title: 制作技术方案路演风格PPT的详细要求 Status: stopped
id: YOpdpcVj7vPFD4gsBfEwVu Title: Defining Empire: … Status: stopped
测试用例还验证了 --limit 0、-5、1.5 都会被拒绝,以及 --limit 1 会真实反映到注入脚本的 pageSize: 1 上(见 clis/manus/manus.test.js 的 list 测试组)。
4.3 manus read <uid>:会话详情
对应 clis/manus/read.js。uid 是必填位置参数(缺失抛 ArgumentError)。实现上调用与 list 相同的 ListSessions(pageSize: 100),在浏览器内按 uid 精确匹配后返回字段级详情:
$ opencli manus read 8UcpCxMFLrNk63ZJmzALfV
Field: UID Value: 8UcpCxMFLrNk63ZJmzALfV
Field: Title Value: 制作技术方案路演风格PPT的详细要求
Field: Status Value: SESSION_STATUS_STOPPED
Field: Mode Value: AGENT_TASK_MODE_HIGH_EFFORT
Field: Credits Value: 4564
完整输出还包括 Created、Updated、Last Display Message。若 100 条内找不到匹配 uid,抛 EmptyResultError("Session not found")。
4.4 manus credits:信用额度拆分
对应 clis/manus/credits.js,仅调用 GetAvailableCredits 一个 RPC,输出 8 个字段:
| 字段 | 含义 |
|---|---|
| Total Credits | 当前总余额 |
| Free Credits | 免费额度 |
| Periodic Credits | 周期发放额度 |
| Pro Monthly Credits | Pro 月度额度 |
| Refresh Credits | 本次可刷新额度 |
| Max Refresh Credits | 刷新额度上限 |
| Next Refresh | 下次刷新时间 |
| Refresh Interval | 刷新周期(如 daily) |
若返回对象中四个核心键(totalCredits/freeCredits/periodicCredits/refreshCredits)全部缺失,则判定为畸形响应并抛错。
4.5 manus connectors:连接器列表
对应 clis/manus/connectors.js,调用 connectors.v1.ConnectorsService/ListConnectors,输出 UID / Name / Brief 三列。--limit 默认 50、上限 500。连接器示例包括 Apify、GitHub、Outlook、Slack 等。
4.6 manus skills:技能列表
对应 clis/manus/skills.js,调用 skill.v1.SkillService/ListSkills,输出 ID / Name / Description / Source 四列:
userAddedSkills数组 →Source: user(用户添加的技能);systemSkills或skills数组 →Source: system(系统技能,兼容两种响应键名);- 两类都缺失则判定为畸形响应;全部为空则抛
EmptyResultError。
五、底层实现要点:API-first 与失败关闭
5.1 为什么不抓 DOM
原文档明确说明:适配器是 API-first 实现——每个命令只发一次(status 为并发两次)Connect-RPC POST 到 api.manus.im,而不是解析页面 DOM。这样即便 Manus 前端 UI 换肤、改版,只要后端 RPC 契约不变,CLI 依然可用,天然对前端重绘免疫。
5.2 统一响应守卫
clis/manus/_utils.js 提供了一组"失败关闭"(fail-closed)的守卫函数,所有命令共用:
unwrapEvaluateResult(payload):识别并剥离 Browser Bridge 的{ session, data }信封,向下取data;requireObject/requireArray/requireString:依次检查__authRequired(→AuthRequiredError)、__httpError(→ 带 HTTP 状态码的CommandExecutionError)、__error(→ 通用CommandExecutionError),再校验类型是否匹配,畸形载荷一律报错而非静默吞掉;validatedLimit(raw, fallback, max):参数校验,与服务端 Buf Validate 规则保持一致,先本地报错以省去一次无效网络往返。
5.3 域名安全校验
isManusUrl(url) 要求协议为 https: 且主机名严格等于 manus.im 或 www.manus.im,用于 ensureOnManus 判断当前页面是否处于正确站点。测试覆盖了 https://manus.im.evil.com、http://manus.im 等被拒绝的边界情况。
六、刻意不暴露的操作(设计边界)
原文档指出,以下命令不在 CLI 范围内:
manus open <uid>:/app/session/<uid>返回 404,Manus 的/app是纯 React SPA,没有按会话粒度的 URL 路由;manus new-task <prompt>、manus chat <uid> <message>、manus pause/resume/cancel <uid>:属于破坏性状态变更,且没有稳定的 post-state(URL 从不变化、无确认对话框)可供断言验证结果;manus delete <uid>/manus archive <uid>:同理。
这是值得借鉴的适配器设计原则:只暴露能通过稳定可验证状态确认结果的命令。在 Manus 官方暴露按会话的 URL 路由或确认对话框之前,这些操作被有意排除,避免 CLI 在无法验证执行结果的情况下误导用户。
七、已知限制与注意事项
manus read的 100 条上限:read通过ListSessions(pageSize=100)在进程内过滤查找。如果目标会话不在最近 100 条之内,命令会报告"not found"。这是当前实现明确声明的限制。- 枚举原始值:
Status(如SESSION_STATUS_STOPPED)与Mode(如AGENT_TASK_MODE_HIGH_EFFORT)直接透传 RPC 原始枚举字符串;Membership Tier是数字层级码(如60)。脚本化消费这些字段时需按枚举值处理,而不是按显示文案。 list的过滤是客户端行为:默认隐藏归档会话是在拿到sessions数组后由filter(s => !s.isArchived)完成的,pageSize仍可能包含已归档项,因此--archived只是显示层开关。
八、测试与验证
clis/manus/manus.test.js 使用 vitest 对适配器做了系统验证,覆盖:
- 6 个命令的注册信息(access/domain/siteSession);
status合并输出与信封解包、身份缺失时报错;list默认过滤归档、--archived返回全部、--limit注入pageSize、非法 limit 拒绝、畸形载荷报错;read命中/未命中/缺参/畸形载荷四种路径;credits8 字段输出与畸形载荷拒绝;connectors的 limit 截断与畸形行拒绝;skills的source=user归属与畸形载荷拒绝;__authRequired→AuthRequiredError、__httpError→CommandExecutionError的错误映射;isManusUrl的合法/非法 URL 判定。
运行 npm test(或项目文档 TESTING.md 中说明的测试命令)即可执行这些用例;你也可以在本地用 opencli manus <command> 直接体验全部命令。
九、相关源码速查
| 关注点 | 文件 |
|---|---|
| 共享工具(常量、RPC 注入、守卫、limit 校验) | clis/manus/_utils.js |
| 登录 / 身份校验 | clis/manus/auth.js |
| 通用站点认证注册器 | clis/_shared/site-auth.js |
| 账户快照 | clis/manus/status.js |
| 会话列表 | clis/manus/list.js |
| 会话详情 | clis/manus/read.js |
| 信用额度 | clis/manus/credits.js |
| 连接器 | clis/manus/connectors.js |
| 技能 | clis/manus/skills.js |
| 单元测试 | clis/manus/manus.test.js |
从这套实现可以提炼出可复用的适配器模式:Cookie 复用 + Connect-RPC Bearer、浏览器内注入 RPC 调用、统一信封解包与失败关闭守卫、严格参数校验、以及"无稳定 post-state 即不做破坏性操作"的能力边界。无论是接入新的 AI 智能体平台,还是设计只读 CLI 工具,这套方法论都值得直接借鉴。