当你需要生成中文 PDF(交付资料、技术报告、说明书、BOM / 接线表),或用户反馈 PDF "文字溢出表格 / 多行混杂看不清 / 图内文字重叠"时,用这个 skill。
它覆盖 CJK 字体注册、表格中文自动换行、列宽等比填满、框图 top-down 坐标,以及用 PyMuPDF 做程序化溢出检测的完整闭环——生成后不是靠肉眼"觉得排好了",而是用脚本体检。
它的铁律是:表格单元格必须用 Paragraph 而不能直接传 str(连续中文不会自动断行),并强调生成后必须用程序验证"排好了"。
reportlab 和 pymupdf(PyMuPDF 旧名 fitz 仍可用但会告警):pip install reportlab pymupdf。UnicodeCIDFont('STSong-Light'),无需外部 ttf 文件。dirname/ls/tail/grep,删临时文件 / 列目录用 Python 的 os.remove / os.listdir 代替 rm / ls。pdfmetrics.registerFont(UnicodeCIDFont('STSong-Light')),之后 FONT = 'STSong-Light'。段落里 <b>粗体</b>、<br/> 都能用(Paragraph 支持受限 HTML)。
用 grid_table 体系,所有单元格(含表头)都用 Paragraph 包裹 → 中文自动换行、不溢出。列宽用权重等比填满正文宽:CONTENT_W = (210 - 18 - 18) * mm,函数内 scale = CONTENT_W / sum(weights)。
reportlab 原生是 bottom-up(y=0 在底部),而人脑是 top-down。全部用"距图顶"坐标,只在一个函数里换算(如 tbox / ty);文字手工拆行,每行不超盒宽。
写生成脚本 → python -m py_compile 过语法 → 运行生成 PDF 并打印文件大小 → 跑溢出检测脚本(目标 body overflow = 0)→ 读渲染出的关键页 PNG 肉眼确认无重叠 → 修正循环直至通过 → 清理临时脚本只留正式生成器。
你:这份中文交付资料帮我生成 PDF,但之前生成的表格里的中文都冲到邻列去了,看不清。
AI大模型或AI智能体:那是 reportlab 的老坑——表格直接传字符串时,连续中文不会自动断行,会单行无限延伸冲出边界。我会把所有单元格用 Paragraph 包裹,中文就能自动换行;列宽用权重等比填满,不会越界也不会留大白边。生成完我还会用 PyMuPDF 跑一遍溢出检测,保证 body overflow = 0,再把关键页渲成 PNG 给你肉眼确认无重叠。
你:框图里的文字怎么跑到图外面、还和别的盒子叠一起了?
AI大模型或AI智能体:reportlab 的 Drawing 坐标是 bottom-up(y=0 在底部),和咱们习惯的"距图顶"相反,混用就会把元素放到图外被裁。我统一改成 top-down:所有盒子位置都按"距图顶"算,只在一个换算函数里转成 reportlab 的 y。文字我手工拆好行,标签放到盒子间的空白带,不压标题。生成后照样用脚本体检 + 肉眼复核。
y0<50 或 y0>780 排除,否则误报一堆。