在终端用 OpenCLI 读取幕布(Mubu)文档:doc / docs / notes / recent / search 适配器完全指南
在终端用 OpenCLI 读取幕布(Mubu)文档:doc / docs / notes / recent / search 适配器完全指南
幕布(mubu.com)是国内常见的树形大纲笔记工具,其文档、速记、任务节点等数据通常深藏在网页应用中,难以被脚本、Agent 或 LLM 直接消费。OpenCLI 为它提供了完整的浏览器适配器,让你在终端里直接读取文档正文(Markdown / 纯文本)、浏览文件夹、拉取每日速记、查看最近编辑以及做全量全文搜索。读完本文,你将掌握 opencli mubu 全部 5 个命令的参数细节与输出格式,并理解其基于已登录 Chrome 会话、通过 Jwt-Token 调用 api2.mubu.com 接口的底层实现原理。
适配器概览:Mode 与 Domain
幕布适配器的元信息定义在 clis/mubu 目录 下,共 6 个文件:doc.js、docs.js、notes.js、recent.js、search.js 与共享工具 utils.js。每个命令声明统一为:
| 字段 | 值 | 说明 |
|---|---|---|
site |
mubu |
命令前缀,即 opencli mubu ... |
domain |
mubu.com |
目标站点域名 |
access |
read |
全部命令均为只读操作 |
strategy |
Strategy.COOKIE |
复用浏览器已登录会话,无需 API Key |
Strategy.COOKIE 在 src/registry.ts 中定义,是 OpenCLI 浏览器类适配器的标准策略:所有请求都发生在浏览器页面上下文内,直接携带你登录后的 Cookie 与令牌,从而绕开账号密码、验证码与反爬风控。
前置条件:登录态 Chrome + Browser Bridge
使用任何 opencli mubu 命令之前,需要满足两个前提(这也是 docs/adapters/browser/mubu.md 中明确列出的 Prerequisites):
- Chrome 正在运行,并且已经登录 mubu.com;
- 已安装 Browser Bridge 扩展。
Browser Bridge 是 OpenCLI 连接浏览器的轻量桥梁:一个 Chrome 扩展 + 自动启动的微守护进程(micro-daemon)。它的架构为 CLI(Node.js)↔ WebSocket(localhost:19825)↔ 微守护进程 ↔ Chrome 扩展 ↔ 页面,扩展在页面上下文中执行 JavaScript,从而访问到登录会话。安装后可运行 opencli doctor 校验扩展与守护进程连通性;守护进程常驻,可用 opencli daemon stop 优雅关闭。
命令一览
| Command | Description |
|---|---|
opencli mubu doc |
读取文档内容(Markdown / 纯文本) |
opencli mubu docs |
列出文档和文件夹 |
opencli mubu notes |
读取速记(今日 / 指定日期范围) |
opencli mubu recent |
最近编辑的文档 |
opencli mubu search |
全文搜索文档节点 |
读取文档内容:opencli mubu doc
doc 命令读取单篇幕布文档的完整大纲,默认输出 Markdown,也可以切换为纯文本:
# Read a document in Markdown (default)
opencli mubu doc <doc-id>
# Read a document as plain text
opencli mubu doc <doc-id> --output text
参数说明:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
id |
positional,必填 | — | 文档 ID,可通过 docs / recent / search 命令获得 |
--output |
枚举 | md |
md:缩进列表 Markdown,适合导入 Obsidian;text:纯文本,适合终端阅读 |
从 clis/mubu/doc.js 的源码看,命令执行流程为:
- 先
page.goto('https://mubu.com/app')进入应用页,确保页面上下文就绪; - 通过
mubuPost(page, '/document/edit/get', { docId })调用 API 获取文档数据; - 解析返回数据中的
definition字段(JSON 字符串)得到节点树nodes; - 若解析失败(如空文档),降级返回文档标题
data.name; - 依据
--output选择 utils.js 中的nodesToMarkdown(nodes)或nodesToText(nodes)渲染。
Markdown 输出中的富文本能力
doc 的 Markdown 输出不是简单的缩进列表,而是经过 htmlToMarkdown 的完整富文本转换(见 clis/mubu/utils.js),支持:
- 表格:
<div class="table-container">内的 HTML 表格转为标准 Markdown 表格(首行作为表头,自动生成---分隔行),单元格内的<br>先替换为占位符再还原,避免表格断裂; - 加粗 / 斜体 / 删除线 / 下划线:识别
bold、italic、strikethrough、underline样式类,分别映射为**、*、~~、<u>; - 主题链接(node-mention):幕布的主题引用节点会转为指向
https://mubu.com/app/edit/<docId>的 Markdown 链接; - 外部链接:
<a href>转为text,并继承链接自身的加粗、斜体等样式; - HTML 实体解码:同时处理
&#x…;、&#…;数字实体与&、<等命名实体。
此外,节点渲染还会保留 emoji 图标、任务状态与任务元数据:taskStatus === 2 输出 [x](已完成),否则输出 [ ];带 deadline 输出 📅 日期、带 remindAt 输出 ⏰ 提醒时间;节点内的图片以 image 形式输出(相对路径自动拼上 https://api2.mubu.com/v3 前缀);节点的**备注(note)**以 > 引用 形式附加在节点下方。
纯文本输出
纯文本模式使用 nodesToText 与 htmlToText:表格转为 Tab 分隔的文本行,<br> 转为换行,标签全部剥离,图片以 [图片: <url>] 占位表示,任务前缀与元数据同样保留。适合在终端快速浏览、配合 grep 等管道工具做文本处理。
列出文档和文件夹:opencli mubu docs
# List documents in root folder
opencli mubu docs
# List starred (quick-access) documents
opencli mubu docs --starred
# List documents in a specific folder
opencli mubu docs --folder <folder-id>
参数说明:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--folder |
字符串 | 0 |
文件夹 ID,0 表示根目录 |
--starred |
布尔 | false |
只显示快速访问(收藏)的文档和文件夹 |
--limit |
整数 | 50 |
最多显示条数 |
命令内部调用 /list/get 接口(clis/mubu/docs.js):普通模式请求体为 { folderId },收藏模式请求体为 { source: 'star' }。返回结果把文件夹(📁)与文档(📄)合并为一个列表,每行包含 type / id / name / updated / stared 五列,其中 updated 由 formatDate 格式化为 YYYY-MM-DD HH:mm,收藏项带 ★ 标记。
读取速记:opencli mubu notes
速记(daily notes)是幕布按日期组织的每日笔记。notes 命令默认读取今天,支持多种时间范围参数:
# Read today's daily notes
opencli mubu notes
# Read notes for a specific date
opencli mubu notes --date 2026-04-10
# Read notes for an entire month
opencli mubu notes --month 2026-04
# List note dates with entry counts (no content)
opencli mubu notes --list --month 2026-04
# Read notes for a custom date range
opencli mubu notes --from 2026-01-01 --to 2026-03-31
参数说明:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--date |
YYYY-MM-DD |
今天 | 单日速记 |
--month |
YYYY-MM |
— | 整月速记 |
--year |
整数 | — | 整年速记 |
--from / --to |
YYYY-MM-DD |
— | 自定义范围,两者须成对使用 |
--list |
布尔 | false |
概览模式:只输出日期与条数,不输出内容 |
--output |
枚举 | md |
md 或 text |
时间范围解析规则
clis/mubu/notes.js 中的 resolveRange 定义了清晰的优先级(源码 clis/mubu/notes.js):
--from/--to优先级最高,且--to不能单独使用;未指定--to时截止今天;--from晚于--to会直接报错;- 其次是
--year,解析为YYYY-01-01 ~ YYYY-12-31; - 再是
--month,自动计算当月最后一天; - 然后是
--date,即当天; - 全部省略时默认今天。
所有日期参数都会经过严格的合法性校验(年份为正整数、月份 1–12、日期不超过当月天数),格式错误会抛出 ArgumentError。
底层取数方式
notes 的实现没有独立的速记 API,而是复用文档接口:先从 localStorage 的 daily_notes_doc_list 中找到名为「YYYY年」的年度文档 ID(clis/mubu/notes.js),再调用 /document/edit/get 拉取年度文档,遍历「月节点 → 日节点」两层结构,通过正则匹配「X月X日」生成带日期 key 的条目。多个年份用 Promise.all 并行加载,最后按 [startKey, endKey] 字符串比较过滤出目标范围。--list 概览模式只输出每个日期的条目计数,便于快速浏览哪些天有记录。
最近编辑的文档:opencli mubu recent
# Show recently edited documents
opencli mubu recent --limit 10
参数只有 --limit(整数,默认 20)。实现上调用 /list/get 并传入 { folderId: 'recent' }(clis/mubu/recent.js),返回文档的 id / name / updated 三列,按更新时间排序。适合配合 doc 命令快速回溯最近改过的笔记。
全文搜索:opencli mubu search
# Full-text search
opencli mubu search "关键词"
参数说明:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
query |
positional,必填 | — | 搜索关键词 |
--limit |
整数 | 100 |
最多显示条数,结果被截断时调大 |
搜索调用服务端 /list/search 接口(标题 + 内容全量匹配,clis/mubu/search.js)。结果包含两类:
- folder:匹配的文件夹,含
type / id / name / path,path为父路径(父级 > 子级形式); - doc:匹配的文档,额外带
hits(命中数)与snippet(各命中节点的纯文本摘要,用|拼接)。
当结果超过 --limit 时,输出末尾会自动追加一行提示(type: '...'),告知还有多少条未显示并给出查看全部的命令建议。
输出格式:表格与 JSON
所有命令默认以对齐的表格列输出(每个命令通过 columns 声明列名)。文档级内容命令(doc / notes)则以 content 单列承载 Markdown 或纯文本。需要机器可读输出时,使用全局输出选项:
# JSON output
opencli mubu docs -f json
-f json 适用于全部命令,方便把结果直接交给脚本、Agent 或 LLM 做进一步处理。
底层原理:mubuPost 与 Jwt-Token 认证
所有命令的 API 调用都收敛在 clis/mubu/utils.js 的 mubuPost 函数中,这是理解整个适配器安全模型的关键:
- API 基地址:
https://api2.mubu.com/v3/api,命令在页面上下文内以 XHR POST 请求,路径如/document/edit/get、/list/get、/list/search; - 令牌来源:从页面
localStorage读取Jwt-Token,通过同名请求头Jwt-Token携带——这与幕布网页应用自身的前端机制完全一致; - 不经过 Node 进程:请求由
page.evaluate在浏览器页面里发起,避免 CORS 问题与扩展 fetch 拦截,这一模式在代码注释中被明确说明为参考了 zsxq 适配器; - 错误分类:
localStorage中无 token、HTTP 401/403、或业务响应命中not logged in / 未登录 / 登录已过期等关键词时,抛出AuthRequiredError(提示语为 "Mubu requires a logged-in browser session at mubu.com");其余非 0 业务码(data.code !== 0)抛CommandExecutionError,附带接口路径、HTTP 状态与错误消息。
因此,一旦浏览器登录态失效,所有 opencli mubu 命令都会得到明确的"需要登录"错误,而不是含糊的网络异常——只要重新在 Chrome 中登录 mubu.com 即可恢复。
延伸阅读
- Browser Bridge 安装与验证:扩展安装、
opencli doctor校验、tab 与会话生命周期; - 快速上手:OpenCLI 全局使用方式与浏览器命令基础;
- 安装指南:
opencli本体安装; - 远程编排:在远程机器上运行 opencli、本地保留浏览器会话的 SSH 反向隧道方案;
- clis/mubu 适配器源码:
doc.js/docs.js/notes.js/recent.js/search.js/utils.js六个文件的完整实现,可作为理解 Browser + Cookie 策略适配器的参考范本。
总之,opencli mubu 是一套完整、只读、可脚本化的幕布 CLI 接口:从单篇文档的富文本导出,到按日期/月/年/区间的速记拉取,再到全局全文搜索,全部基于你已登录的 Chrome 会话零配置运行,既适合个人在终端快速查阅笔记,也适合作为 Agent 工作流中访问幕布数据的稳定入口。