Momo Paper / FAQ

常见问题

关于 Momo Paper 的安装、使用和设计理念，这里有最常被问到的问题和解答。

Momo Paper 是一个路由式设计系统，将文档排版从「手工调 CSS」升级为「声明式路由」。以下是最常见的问题，按主题分组，帮助你快速找到答案。

如果你在这里没找到答案，欢迎在 GitHub 提交 Issue 或查看 references/ 目录下的详细文档。

快速入门

Momo Paper 是什么？

Momo Paper 是一个面向文档与视觉叙事的开源设计系统。它提供 15 种文档类型模板、一个 JSON 渲染引擎和 14 种图示原语。你可以直接编辑 HTML 模板，也可以通过 JSON 数据驱动渲染——两种方式输出排版精良、打印就绪的 HTML 文档。

需要什么前置条件？

如果你只使用直接 HTML 模板，不需要任何前置条件——打开文件、编辑内容、在浏览器中打开即可。如果要使用 JSON 渲染引擎，需要 Python 3.10+，以及 jinja2 和 click 两个依赖。

如何安装 JSON 引擎？

进入 scripts/json-engine/ 目录，运行 pip install -e . 即可。安装后你会获得 momo 和 momo-paper 两个等价的 CLI 命令。输入 momo list 查看支持的文档类型。

可以在 AI agent 中使用吗？

可以。Momo Paper 提供了 Claude Code Skill 定义（SKILL.md），AI agent 通过 bash 直接调用 momo CLI 命令（momo init、momo render 等）即可生成文档。scripts/json-engine/mcp-tool.json 是 MCP 工具的定义文档（接口描述），尚未实现完整的 MCP server，当前实际可用的集成路径是 Skill + CLI 模式。

引擎使用

如何选择文档类型？

根据你的内容需求选择：商业方案用 one_pager，深度长文用 long_doc，正式信函用 letter，简历用 resume，金融研报用 equity_report，数据报告用 stats_report，演示用 slides。完整列表见文档类型页面或运行 momo list。

JSON 数据的结构是什么？

所有文档共享顶层结构——document_type、locale、meta（标题/副标题/日期/作者）、sections（文档特定内容）。slides 类型用 slides 替代 sections。每种类型的 sections 字段由 JSON Schema 定义，运行 momo init -t 可生成骨架。

如何嵌入图表？

在任意 section 内添加 chart 对象，格式为 {"type": "图表类型", "title": "...", "height": 280, "data": {"labels": [...], "values": [...]}}。引擎自动将其渲染为内联 SVG。支持 bar、line、donut、candlestick 和 waterfall 五种类型。也可以用 momo chart 命令将图表渲染为独立 SVG。

支持哪些语言？

目前支持 zh-CN（中文）和 en（英文）两种 locale。locale 字段控制 section 标题语言的自动切换。中英文各有 15 套完整模板，共 30 个。

如何批量渲染？

scripts/json-engine/ 目录下提供了 render_all.py 脚本，可一键渲染 examples/ 目录中的所有示例文件。你可以参考该脚本编写自己的批量渲染逻辑，直接调用 momo_paper.engine.render_to_file() API。

设计与定制

设计令牌是如何工作的？

所有颜色、字体、间距等视觉属性都定义在 _base.html.j2 模板的 :root CSS 自定义属性中。每个文档类型的模板继承自 _base.html.j2，自动获得统一的视觉语言。设计令牌也以 JSON 格式导出在 assets/design-tokens.json 中。

可以自定义模板吗？

可以。引擎支持通过 --template-dir 参数指定自定义模板目录。你可以在保持 _base.html.j2 继承关系的前提下，创建新的文档类型模板。也可以用 --template 参数直接指定模板文件。

文档支持打印吗？

所有模板都内置了 @media print 样式规则。打印时会自动移除背景色、调整页边距、避免 section 跨页断裂。这是 Momo Paper 的核心设计原则之一——你不需要为打印单独准备文档。

和传统的文档工具（Word/LaTeX/Notion）有什么区别？

Momo Paper 的定位是「文档生成引擎」，而非编辑器。它的优势在于：输出是标准 HTML/CSS（任何浏览器都能打开），设计令牌确保视觉一致性，JSON 作为中间格式让 AI agent 可以结构化生成内容，打印安全内置无需额外处理。适合需要批量生成或 AI 辅助生成的场景。

最终说明

Momo Paper 正在持续演进中。当前的 15 种文档类型覆盖了大多数商业和个人文档场景，图表系统和设计令牌也在不断完善。如果你有新的文档类型建议或功能需求，欢迎参与贡献。

查看 GitHub 仓库获取最新代码和文档：github.com/gusibi/momo-paper