在终端用 OpenCLI 读取幕布(Mubu)文档:doc / docs / notes / recent / search 适配器完全指南

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

在终端用 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):

  1. Chrome 正在运行,并且已经登录 mubu.com;
  2. 已安装 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 的源码看,命令执行流程为:

  1. 先 page.goto('https://mubu.com/app') 进入应用页,确保页面上下文就绪;
  2. 通过 mubuPost(page, '/document/edit/get', { docId }) 调用 API 获取文档数据;
  3. 解析返回数据中的 definition 字段(JSON 字符串)得到节点树 nodes;
  4. 若解析失败(如空文档),降级返回文档标题 data.name;
  5. 依据 --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…;、&#…; 数字实体与 &amp;、&lt; 等命名实体。

此外,节点渲染还会保留 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):

  1. --from / --to 优先级最高,且 --to 不能单独使用;未指定 --to 时截止今天;--from 晚于 --to 会直接报错;
  2. 其次是 --year,解析为 YYYY-01-01 ~ YYYY-12-31;
  3. 再是 --month,自动计算当月最后一天;
  4. 然后是 --date,即当天;
  5. 全部省略时默认今天。

所有日期参数都会经过严格的合法性校验(年份为正整数、月份 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 工作流中访问幕布数据的稳定入口。

登录后查看全文
OpenCLI