OpenCLI 的 Manus 适配器实战指南:用 Connect-RPC 把 manus.im 变成纯读 CLI

原创2026-09-19 16:04:581,655 阅读
文章标签:CLI浏览器控制GUI 自动化开发工具AI 技能网页爬虫

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 分两步:

  1. 检查 https://manus.im 域名下是否存在 auth_session、manus_token、_session、session 等会话 Cookie;
  2. 请求 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/UserInfo
  • user.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 命中/未命中/缺参/畸形载荷四种路径;
  • credits 8 字段输出与畸形载荷拒绝;
  • 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 工具,这套方法论都值得直接借鉴。

登录后查看全文
OpenCLI