lov-any2pdf

用途

lov-any2pdf（PDF大师 · PDF Master）用于将任意 Markdown 文件转换为出版级质量的 PDF。它使用 Python 的 reportlab 库实现，并针对真实的中文技术报告经过大量迭代，解决了朴素 MD→PDF 转换器常见的若干难题。

主要能力

• CJK 混排：支持中文、日文、韩文与拉丁文字混排，通过 _font_wrap() 自动切换字体。
• 代码块：esc_code() 保留缩进、行内对齐与换行。
• 表格：根据内容长度按比例分配列宽，最小 18mm。
• 图片：支持本地、相对路径、file:// 与远程 Markdown 图片，按正文框架缩放，出错时显示回退文本。
• 封面与目录：可生成封面页、目录、扉页、封底横幅、免责声明与版权信息。
• 书签：ChapterMark flowable 生成 PDF 侧边栏书签与命名锚点。
• 标注块：Obsidian 风格的 > [!NOTE] 块渲染为带主题的方框标注。
• 公式：显示公式可使用可选的 matplotlib mathtext 图片，并提供样式化文本回退。
• Emoji：可用时渲染为缓存的 Twemoji PNG，或使用本地 emoji 字体回退。
• 水印：支持水印文字、字号、透明度、角度与间距设置。
• 主题：内置多种主题，如 songti-reading、warm-academic、nord-frost、github-light、solarized-light、paper-classic、ocean-breeze、monokai-warm、dracula-soft、tufte、classic-thesis、ieee-journal、elegant-book、chinese-red、ink-wash、consulting-navy。

使用方式

快速开始命令：

python md2pdf/scripts/md2pdf.py \
  --input report.md \
  --output report.pdf \
  --title "My Report" \
  --author "Author Name"

除 --input 外所有参数均为可选。未提供主题时，渲染器会根据文档内容与结构自动选择。

配置解析顺序（强制）：

1. 当前请求中的用户明确指令，然后是 CLI 参数或文档 frontmatter；
2. 用户在 lov_any2pdf 偏好命名空间中最近一次明确确认的值；
3. 主题的内容感知决策，或非视觉设置的文档化安全默认值。

当用户明确确认或更改可复用参数后，记录该值作为最新偏好，下次用户未指定时复用。可复用参数包括主题、封面/目录、页面尺寸、扉页模式、水印文字与几何、图片封面模式、封底模式/横幅、免责声明、版权、页眉与页脚。

内容感知主题决策（决策线索，非固定关键词路由）：

• 长中文散文、知识笔记、密集表格 → songti-reading
• 战略、商业、市场或研究报告 → consulting-navy
• 含摘要/方法/结果/参考文献的学术论文 → ieee-journal 或 classic-thesis
• 代码密集的技术指南或 API 文档 → github-light
• 含图表与指标的数据叙事 → tufte
• 文学、艺术、摄影或设计随笔 → ink-wash
• 正式中文政策或机构文档 → chinese-red
• 中性英文散文或印刷优先文档 → paper-classic

适用场景

• 用户希望将 .md 转换为 .pdf。
• 用户有 Markdown 报告/文档，希望获得专业排版。
• 文档包含 CJK 字符与拉丁文字混排。
• 文档包含围栏代码块、Markdown 表格或嵌套列表。
• 文档包含本地/远程图片、Obsidian 标注、emoji 或数学公式。
• 用户希望在 PDF 中加入封面页、目录或水印。

不适用场景：

• 用户只想修改 Markdown 内容，不需要 PDF 输出。
• 源文件是 HTML、DOCX 或其他格式，且用户未授权 Markdown 转换步骤。
• 用户需要幻灯片、可编辑 Word 文档或图片导出，而非 PDF。

限制

• 仅接受 Markdown 文件作为输入。HTML、DOCX 等格式需先转换为 Markdown（例如 pandoc --wrap=none）。
• Markdown 中嵌入的 HTML 块会作为文本传递，需在调用前将视觉内容（图表、复杂表格）预处理为纯 Markdown 表格或图片引用。
• 当 reportlab 失败（如宽/复杂表格导致表格宽度计算无限循环）时，回退到 pandoc + XeLaTeX。
• pandoc 回退的已知限制：无封面页（pandoc article 类无内置封面）；不支持扉页/封底（需使用 md2pdf.py）；→ ★ ☆ 符号在 Palatino 中可能警告，通过 CJK 字体回退渲染，可忽略；ASCII art 图表渲染为代码块。

依赖

pip install reportlab --break-system-packages
# 可选公式渲染：
pip install matplotlib --break-system-packages

推荐的 Ubuntu/Debian 字体：

sudo apt install fonts-dejavu-core fonts-liberation fonts-freefont-ttf fonts-noto fonts-noto-cjk fonts-noto-color-emoji

pandoc 回退依赖：

brew install pandoc
brew install --cask mactex-no-gui   # 或 basictex

架构

Markdown → 预处理（拆分合并标题）→ 解析（代码围栏感知）→ Story（reportlab flowables）→ PDF 构建。

关键组件包括字体系统、CJK 包装器、混合文本渲染器、代码块处理器、智能表格宽度、书签系统、标题预处理器、图片处理器、标注渲染器、公式渲染器与 emoji 回退。

运行上下文

运行前读取本 Skill 包的 skill.yaml，由宿主提供 skill-runtime/v1 上下文。字段解析顺序为：当前请求、项目上下文、个人 Preferences、品牌 Profile、通用默认值。只使用 Manifest 声明的字段；Profile 保存公开品牌事实，Preferences 保存个人工作偏好。required: true 字段缺失时，按 Manifest 的问题配置向用户提出一个聚焦问题；用户明确同意后再保存回答。报错提供可复制的 context_id、字段路径与来源。