SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场pdf-creator

pdf-creator

办公与效率

查看项目

更新于 10-13 20:08

技能介绍

PDF Creator 用于从 Markdown 生成专业 PDF 文档，具备中文字体支持与主题系统。若输入源为已有的 .docx 文件，官方建议改用 docx-creator/references/word-to-pdf.md 的路径，并依据权威输入与实际输出后缀来判断使用哪条流程。

【用途与定位】 该技能解决的是 Markdown → PDF 的中文排版问题。文档明确指出，手工组合 pandoc 与 Chrome 的流程会以难以察觉的方式失败，因此建议直接用此技能替代手工命令。

【主要能力】

  1. 中文排版：注入 CJK 字体栈与排版补丁，避免出现方框或空白。对于代码块中的中日韩字符，脚本会自动检测并转换为可支撑 CJK 字体的样式化 div。
  2. 主题系统：主题存放在 themes/*.css，每个主题是独立 CSS 文件。内置主题包括：default（A4、宋体 SC + 黑体 SC、黑灰配色，适合法律文书、合同、正式报告）、cjk-auto（A4、宋体 SC + 黑体 SC、黑灰配色，适合表格列内容不均的课程表与清单）、warm-terra（A4、苹方 SC、赤陶色 #d97756 与暖中性色，适合课程大纲、培训材料、工作坊）、warm-terra-menu（warm-terra 的加固变体，针对模块菜单与列表，长文本表格两列换行不溢出，并以 Menlo unicode-range 保持 CJK 行内代码在 Preview/Adobe 中不空白）、mobile（148mm × 210mm、苹方 SC、赤陶色系，适合手机阅读、微信分享）。
  3. 快速开始：脚本路径相对于技能自身目录，需在该目录下运行，否则会报 Failed to spawn: 'scripts/md_to_pdf.py'。省略输出路径时，会从输入文件名推导（input.md → input.pdf，位于输入所在目录）。命令示例包括：uv run --with weasyprint scripts/md_to_pdf.py input.md output.pdf；--theme warm-terra；--theme mobile；批量 uv run --with weasyprint scripts/batch_convert.py *.md --theme warm-terra --no-preview；无 weasyprint 时用 python scripts/md_to_pdf.py input.md --theme warm-terra --backend chrome；用 python scripts/md_to_pdf.py --list-themes dummy.md 列出主题。新建主题的方式是复制 themes/default.css 修改后另存为 themes/your-theme.css。
  4. 后端自动路由：依据内容 × 主题选择后端。CJK + 宋体/黑体类主题（default、cjk-auto）走 weasyprint，因为这些主题嵌入 CID TrueType，各类阅读器均可渲染；CJK + 苹方类主题（warm-terra、mobile、warm-terra-menu 及任何不在安全名单中的主题）走 Chrome，因为 weasyprint 会把苹方 SC 子集嵌入为 CID Type 0C OpenType，macOS Preview 与 Adobe Reader 无法渲染；非 CJK 内容走 weasyprint。可用 --backend 显式覆盖。主题名称并不指示实际使用的后端，需查看 Generated: 行中的 backend= 字段；当 weasyprint 不可导入时，default/cjk-auto 会回退到 Chrome 并在 stderr 给出警告且退出码为 0。
  5. Chrome 裁切问题与检查：Chrome 会在 @page 内容框处加裁切路径，超出部分仍在对象层但永不绘制。在 A4、margin: 2.5cm 2cm 2cm 2cm 下测得裁切路径止于 538.90pt，而表格右边框位于 545.18pt，边框被无声截断。default 与 cjk-auto 主题设置 table { table-layout: fixed; width: 100% }，因此两列表格与十列表格同样触及该边界；这是主题宽度与单元格内边距所致，并非宽表特有问题。溢出本身是 CJK 排版层设置 overflow-wrap: normal 的设计取舍，在 weasyprint 下安全，在 Chrome 下有害。由于预览 PNG 会遵循裁切，可用 check_table_borders.py 进行检查：单文件形式对每个检测到的表格列边界统计光栅中是否有墨迹，退出非零并指出有几何无墨迹的边界；表单二形式则用同一主题、另一后端生成参考 PDF 再做比对。退出码：0 通过、1 至少一项未通过、2 无法运行、3 未检测到表格（3 不等于通过）。参考文件仅作标尺，绝不作为交付物。规则数量比较为双向且以文档为单位，因为两种后端对同一源文件分页不同。
  6. 批量转换：batch_convert.py 支持 --theme、--output-dir 与 --no-preview；--no-preview 关闭可视化自检，但不免除运行边框检查的义务。检查脚本可一次接收多个文件，但 --reference 不支持批量，因此一批由 Chrome 渲染且含表格的文档需要逐份配对运行。

【使用方式与适用场景】 按输出渠道选择主题：A4 打印、讲义、合同用 default；培训材料与课程大纲用 warm-terra；微信发送与手机阅读用 mobile；同时需要打印与手机版时用不同主题运行两次。未指定时，培训或课程内容默认 warm-terra，正式文档默认 default；但当表格列内容不均（课程表、分项清单）时应选 cjk-auto 而非 default，因为该主题的 table-layout: auto 正是为此存在。仅在输出渠道不明时询问是否需要手机版。

【限制与注意事项】 中文显示为方框时，确认已安装宋体 SC、苹方 SC 等中文字体。weasyprint import 报错时改用 uv run --with weasyprint 或 --backend chrome。行内代码混排 CJK 与 ASCII 在 macOS Preview 中显示空白，是因为 weasyprint 将苹方 SC 以 OpenType 子集嵌入，可在主题中将 CID TrueType 中文字体排在苹方 SC 之前。表格第一列短标签被从中间断开，是因为 pandoc 会依据分隔行破折号数量自动生成 colgroup 宽度。若绕过本技能手工使用 Chrome headless，出现页眉页脚即为首个症状。