技能介绍

它解决什么问题

给 PDF 加水印看着简单，实际很容易翻车：把水印画在物理坐标系上，页面一带 /Rotate，视觉方向就歪了；换个环境跑，又找不到中文字体；网格参数手写一遍，批量文档里就再也对不齐了。这个技能把这套流程收敛成一次调用——你只提供水印文字，排版、旋转、换行、非 A4 页面处理全部按默认值执行。

核心能力与工作流程

半透明文字网格：以页面中心为轴心铺开行列网格，默认 10 x 10，行列对称居中。
参数可覆盖：字号、颜色、不透明度、旋转角度、行列数、行列间距都能通过命令行选项调整，不传则用默认值。
自动换行：文字超过阈值（默认 7 字）时每行最多 7 字并尽量均衡分配；含英文单词时优先按词断行，避免把词切开。
非 A4 预处理：竖版非 A4 缩放到 A4 竖版，横版同理，保持视觉方向并留少量白边，/Rotate 一并烘焙成 0。
输出副本：源文件只读不改，结果写到同目录的 xxx_水印.pdf。

执行流程是：确认源文件路径存在 → 检查 Python venv 里的 pypdf 和 reportlab → 运行 scripts/add_watermark.py 传入源路径与水印文字 → 用 pymupdf 渲染预览图确认效果。

`/Rotate` 的补偿逻辑

PDF 内部可能标记 /Rotate 为 0/90/180/270，导致物理坐标系与你看到的方向不一致。脚本会读取每页的 /Rotate 值，计算 effective_rotation = 用户设定角度 + 页面/Rotate，这样无论文件内部怎么标，水印都落在你期望的视觉方向上。非 A4 页面因为在预处理阶段已经用单一 CTM 把旋转烘焙进内容，/Rotate 置 0，后续只按设定角度倾斜即可。

适用边界与注意点

单个文件用默认值就够了；要调整全局参数（比如把角度改成 45°），必须对已生成的全部文件重跑一遍，工具不做增量更新。
输出文件被其他程序占用时写入会失败，脚本改用 _水印2 之类的临时名，需要关闭占用进程后再改名。
字体探测顺序是 Windows 微软雅黑 / macOS PingFang / Linux Noto·文泉驿，全找不到才回退 reportlab 内置 CID 字体 STSong-Light，无需额外安装。
reportlab 5.0+ 中 from reportlab.pdfbase.ttfonts import TTFont 已不可用，需改用 import reportlab.pdfbase.ttfonts as ttfonts 再调用 ttfonts.TTFont(...)；注册 msyh.ttc 这类 TTC 集合字体时还要带 subfontIndex=0。
网格默认允许溢出到页面边缘之外，要严格收在页内就得显式调整行列数与间距。