Mubu Integration

核心功能与用法

幕布集成 Skill 提供了对国产大纲笔记工具「幕布」(mubu.com) 的完整 API 封装能力。该 Skill 基于对幕布 Web 端的逆向分析实现，并非官方开放接口，因此具备以下核心操作能力：

认证管理：支持手机号密码登录获取 JWT Token，内置 Token 自动缓存与过期刷新机制（access_token 2小时、refresh_token 30天）。

文档操作：覆盖文件夹与文档的 CRUD 全生命周期——创建文件夹、创建大纲文档、获取文档列表、读取文档内容、更新保存、移动与删除。

格式转换：内置幕布专有 JSON 大纲格式与标准 Markdown 的双向转换能力，支持将 AI 生成的结构化内容一键同步至幕布，或将幕布笔记导出为通用 Markdown。

显著优点

1. 工作流闭环：填补了 AI 对话与大纲笔记工具之间的自动化鸿沟，特别适合知识管理、项目规划、会议纪要等场景的结构化沉淀。

2. 格式原生支持：深度理解幕布的树形大纲结构，转换后的文档可完整保留层级关系，并支持幕布一键转思维导图的核心特性。

3. Token 管理完善：提供了本地文件缓存、自动过期检测、错误重试等生产级健壮性设计，降低使用门槛。

潜在局限与风险

非官方 API 的不稳定性：由于幕布未提供开放平台，所有接口基于逆向工程，存在随版本更新失效的风险，维护依赖社区持续跟进。

账号安全风险：需要以明文形式存储手机号密码环境变量，且 Token 本地缓存文件若权限配置不当可能导致凭证泄露。

频率限制与封禁风险：高频自动化操作可能触发平台风控，建议控制调用频率，避免账号异常。

功能边界：不支持幕布高级特性如协作权限管理、历史版本恢复、附件上传等，仅覆盖核心文档操作。

适合人群

• 重度幕布用户，希望将 AI 生成内容自动化归档
• 需要批量管理大纲文档的项目经理、知识管理者
• 构建个人/团队自动化工作流的开发者

常规风险提示

使用前务必确认 MUBU_PHONE 与 MUBU_PASSWORD 环境变量的安全性，避免硬编码在共享代码库中。建议配合 .env 文件与权限管控（chmod 600）使用，并定期轮换密码。由于 API 非官方性质，关键数据建议保留本地备份。

核心用法

幕布集成 Skill 是一款面向幕布（mubu.com）用户的第三方自动化工具，通过逆向工程实现的非官方 API 封装，提供完整的文档生命周期管理能力。用户可通过 Python 脚本完成登录认证、文件夹创建、文档增删改查、大纲导入导出等操作。核心工作流包含三类典型场景：一是将本地 Markdown 大纲同步至幕布生成结构化笔记；二是将幕布文档导出为 Markdown 格式用于其他平台；三是批量搭建项目文档目录体系。

使用流程以 JWT Token 认证为核心，支持手机号密码登录，Token 本地缓存 2 小时后自动过期。文档内容采用层级化 JSON 格式存储，支持多级嵌套大纲结构，内置转换器实现与 Markdown 的双向互通。命令行接口设计简洁，涵盖 login、list、create、get、save、delete 等常用操作，Agent 可据此响应"同步大纲到幕布""导出读书笔记""创建项目文件夹"等自然语言指令。

显著优点

极简工作流整合：无缝对接幕布的大纲-思维导图双模式，用户无需离开对话环境即可完成笔记托管，大幅降低跨平台操作成本。

双向格式互通：原生支持 Markdown 与幕布 JSON 格式的自动转换，既保留 Markdown 的通用性，又充分利用幕布的层级可视化优势，满足多场景输出需求。

轻量无依赖：仅依赖 Python 标准库与 requests，无复杂第三方依赖链，部署门槛低，适合快速集成至各类自动化工作流。

Token 智能管理：内置本地缓存与过期检测机制，自动处理 2 小时 access_token 续期，减少重复登录负担。

潜在缺点与局限性

非官方 API 风险：基于逆向分析实现，无幕布官方支持，API 端点、鉴权逻辑、数据结构可能随官方更新而失效，长期稳定性存疑。

功能覆盖边界：仅实现核心文档管理功能，未覆盖幕布高级特性（如协作编辑、主题样式、思维导图导出图片等），复杂场景仍需人工操作。

认证方式单一：目前仅支持手机号密码登录，不支持微信扫码、短信验证码等幕布主推的便捷登录方式，账号安全策略受限。

速率限制未知：文档未明确说明幕布 API 的调用频率限制，高频自动化场景存在触发服务限流的风险。

适合的目标群体

• 知识管理重度用户：已习惯幕布进行结构化笔记整理，希望打通本地编辑器与云端的开发者、产品经理、研究人员。
• 自动化工作流搭建者：需要将大纲笔记纳入 CI/CD、日报生成、文档发布等自动化管道的技术团队。
• 多平台内容创作者：频繁在 Markdown 写作工具与幕布可视化之间切换，追求格式无损转换的写作者。
• 小型项目协作组：需要快速搭建标准化文档目录结构，但暂无需企业级知识库方案的小团队。

使用风险

API 可用性风险：非官方集成依赖服务端的持续兼容，建议监控幕布官方更新动态，预留 API 失效时的数据迁移方案。

凭证安全风险：环境变量或本地文件中存储明文密码，若设备共享或配置误提交至版本控制，可能导致账号泄露。建议改用 .env 文件并严格设置 Token 缓存文件权限为 600。

Token 泄露风险：~/.mubu_token 文件包含会话凭证，若设备被他人访问，可直接操作用户文档。建议定期清理缓存、避免在公共环境使用。

数据一致性风险：自动化批量操作可能因网络中断或 API 异常导致文档状态不一致，关键操作前建议手动备份。

合规边界风险：逆向 API 可能触及服务条款灰色地带，企业用户需评估内部合规政策后再行部署。