sunge-latex-pdf

name	sunge-latex-pdf
description	将中文 Markdown、公众号文章或 Obsidian 笔记生成高质量 LaTeX PDF，提供孙割原版、界面志、屏幕图录三套风格，并完整处理网络图片、本地图片、Obsidian 图片、中文代码、表格和公式。用户提到 LaTeX 排版、Markdown 转 PDF、孙割模板、批量生成多种 PDF、中文 PDF 缺字或图片进入 PDF 时，应使用本 Skill。

孙割 LaTeX PDF

把一份 Markdown 生成一套或三套中文 PDF。生成过程只使用本 Skill 自带的脚本、字体和模板。

三套风格

参数	名称	适合内容
sun	孙割原版	文字为主的小开本，保留 5×8 英寸、红黑封面和安静书页
journal	界面志	图文、代码比例接近的中文技术长文，默认推荐
atlas	屏幕图录	界面截图、宽表格和操作教程，横屏阅读
all	三套全部生成	对比风格或一次交付多个版本

孙割原项目正文没有图片规则。本 Skill 的 sun 风格重新实现了正文图片与图注，并让宽图按小开本正文宽度完整缩放，同时保留原版视觉。

执行流程

1. 确认输入 Markdown 的绝对路径
2. 运行 scripts/doctor.sh 检查 Pandoc、XeLaTeX、ImageMagick、Poppler 和内置字体
3. 根据用户指定选择风格；没有指定时使用 journal
4. 调用 scripts/build.sh 生成 PDF
5. 检查构建输出中的页数、中文数量、字体、图片数量、内容顺序和代码复制
6. 运行 scripts/check_visual_layout.py 检查标题字号、标题孤行、图注位置、图注大小和低内容空白页
7. 用 pdftoppm 渲染全部页面，实际查看封面、正文、代码、横图、竖图和最后一页
8. 发现缺字、空白图、裁切、重叠或页眉遮挡时，修复模板并重新生成

生成命令

指定一种风格：

bash scripts/build.sh \
  --input "/绝对路径/文章.md" \
  --style journal \
  --output "/绝对路径/输出/文章"

一次生成三套：

bash scripts/build.sh \
  --input "/绝对路径/文章.md" \
  --style all \
  --output "/绝对路径/输出/文章"

覆盖标题或作者：

bash scripts/build.sh \
  --input "/绝对路径/文章.md" \
  --style all \
  --output "/绝对路径/输出/文章" \
  --title "新的标题" \
  --author "作者名"

网络图片已经进入缓存后，可以增加 --offline 离线重建。需要目录时增加 --toc。

图片要求

支持以下写法：

![网络图片](https://example.com/image.png)
![本地图片](assets/截图.png)
![[assets/设计图.png]]
![[assets/设计图.png|图片说明]]

图片处理遵循这些规则：

• 网络图片先下载并缓存
• 本地图片复制为安全文件名，允许中文和空格路径
• SVG、WebP、GIF 转成 XeLaTeX 可以处理的格式
• 图片保持比例，受最大宽度和最大高度双重限制
• 孙割原版中的宽图按正文宽度完整缩放，标题、说明和图片保持连续
• 图片与图注按同一中心线排列，三套模板的图注保持一致的阅读大小
• 有说明时生成图注，空说明时不生成空图注
• 缺图、下载失败或转换失败时中止并指出原地址
• 禁止静默丢图

中文要求

• 正文使用思源宋体
• 标题和图注使用思源黑体
• 代码中的中文使用霞鹜文楷等宽
• 三种字体随 Skill 提供并附许可证
• PDF 必须嵌入字体，中文必须能够复制和搜索
• 长命令与网址必须自动换行

验收命令

生成后运行：

python3 scripts/verify_pdf.py \
  --pdf "/绝对路径/文章-界面志.pdf" \
  --minimum-images 1

完整回归测试：

bash scripts/smoke-test.sh

固定案例是 examples/deepseek-harness-plugins.md。它包含 15 个标题、12 个代码块和 13 张网络图片，三套模板每次发布前都必须重新生成并逐页检查。

失败处理

• 缺少命令：运行 scripts/doctor.sh，按 README 安装
• 网络图片失败：报告具体 URL，网络恢复后重试；已有缓存时使用 --offline
• 中文缺字：检查 assets/fonts 三个字体文件，禁止退回系统默认字体
• 图片太小：优先使用 atlas；孙割原版优先保持小开本连续阅读
• 内容越界：保留构建目录 --keep-build，检查日志中的 Overfull 与 Missing character

交付前必须完成真实构建和可视检查。仅通过编译不代表完成。