signature-splice — 电子签名批量拼入 PDF

把 N 张签名图片按给定顺序、均匀排进 PDF 的某个区域，并渲染出来自查。 流程是对齐的（固定 4 步抽象工作流），但一切具体参数（PDF、签名图、顺序、目标区域、布局）都由参数传入， 脚本内零硬编码：不写死人名、文件名、路径、坐标、阈值。

⚠️ 适用前提：插入的是图片形式的签名（手写/电子签）。若需要 PDF 数字证书签名（签名域、时间戳、证书校验）， 那是另一类工具，本 skill 不覆盖。

抽象工作流（4 步，固定不变）

① 采集与规范命名   → 把签名图整理成有序列表（setup 由调用方完成，见下）
② 预处理           → preprocess_signatures.py   产出"透明底·紧裁·纯黑墨"的 PNG
③ 定位 + 插入      → locate_anchor.py 求区域 → insert_signatures.py 按序均匀排布
④ 自查             → render_pdf.py 看图 + verify_merge.py 校验（页数/正文/嵌入图）

关键点：每一张签名图都要先"归一化"成同一种干净形态（透明底、紧裁到墨迹、纯黑）， 再去排版；这样不同来源（白底 JPG、透明 PNG、"墨迹只在 alpha 通道"的 PNG、带截图边框的图）才能放进同一行而不突兀。

快速开始

$SK = "$env:USERPROFILE\.config\opencode\skills\signature-splice\scripts"
$FORM = "报名表.pdf"
$RAW  = "raw_signatures"          # 里面放 任意名字 的签名图
$TMP  = "$env:OPENCODE_SCRATCH_DIR\2026-09-27_sign"

# ② 预处理（可选先 --input 单张 + inspect_signatures.py 诊断）
python "$SK\preprocess_signatures.py" --input $RAW --outdir "$TMP\clean"

# ③ 定位（确认区域对不对）+ 插入（按名单顺序）
python "$SK\locate_anchor.py" --pdf $FORM --anchor "（签名）" --no-frames
python "$SK\insert_signatures.py" --pdf $FORM --input "$TMP\clean" `
       --anchor "（签名）" --order "甲,乙,丙,丁" --out "$TMP\signed.pdf"

# ④ 自查
python "$SK\render_pdf.py"   --pdf "$TMP\signed.pdf" --outdir "$TMP\png" --dpi 220 --crop "38,145,575,250"
python "$SK\verify_merge.py" --original $FORM --signed "$TMP\signed.pdf"

顺序来源：--order "甲,乙,丙,丁"（逗号分隔）或 --order-file names.txt（每行一个）。 按子串匹配文件名，把 --input 重排成名单顺序；匹配不全直接报错退出。 不传 --order 时就按 --input 给定/目录排序的顺序插入。

区域来源（三选一）：

• --anchor "（签名）"：自动找锚点文本所在行，取其外层框内、锚点行下方的空白区（推荐，见 §定位）。
• --box x0,y0,x1,y1：手动指定外层框（仍取锚点行下方）。
• --rect x0,y0,x1,y1：手动指定最终区域，完全绕过自动定位。

坐标单位：全部是 PDF point（1 pt = 1/72 inch），原点在页面左上。

脚本

所有脚本：argparse 参数化、stdout 只输出 JSON、进度写 stderr、失败非 0 退出。 输入支持多文件 --input a b c 或目录 --input dir --glob "*.png"；输出一律 --out / --outdir 指定。

scripts/preprocess_signatures.py

用途：把任意来源的签名图归一化为透明底、紧裁、纯黑墨的 RGBA PNG。

示例：python scripts/preprocess_signatures.py --input raw/ --outdir clean/ 输出：{"status":"ok","count":N,"items":[{src,dst,polarity,frame_trimmed,out_size,aspect,...}],"errors":[]}

scripts/locate_anchor.py

用途：由锚点文本数据驱动地求出插入区域（可当库用：from locate_anchor import find_region）。

示例：python scripts/locate_anchor.py --pdf form.pdf --anchor "（签名）" --no-frames 输出：{"status":"ok","anchor":{"bbox":...},"enclosing_frame":[...],"region":[x0,y0,x1,y1], ...}

scripts/insert_signatures.py

用途：按顺序把签名图均匀排进区域并写入新 PDF。

示例：python scripts/insert_signatures.py --pdf form.pdf --input clean/ --anchor "（签名）" --order "甲,乙,丙,丁" --out signed.pdf 输出：{"status":"ok","region":[...],"grid":[r,c],"slots":[{order,file,cell,target,drawn_pt}...]}

scripts/render_pdf.py

用途：PDF→PNG，用于插入后肉眼自查。

示例：python scripts/render_pdf.py --pdf signed.pdf --outdir png/ --dpi 220 --crop 38,145,575,250

scripts/verify_merge.py

用途：核对签字版与原稿：页数、正文文本是否逐页一致、嵌入了哪些图。

输出：{"original":{...},"signed":{...},"images_in_signed":[...],"text_identical":true/false}

scripts/contact_sheet.py

用途：把预处理结果拼成一张预览图（看透明底/裁剪/大小是否正常）。

scripts/inspect_signatures.py

用途：诊断难以处理的图（当预处理结果不对时先跑它）：模式/尺寸、alpha 与亮度范围、墨色色度、 合成背景亮度与极性猜测、检测到的截图边框线、墨迹包围盒与长宽比。

定位原理（为什么能自动找到签名栏）

1. 把页面矢量线条按相交/相邻合并成「框」（表格、方框、单元格都会各自合并成一个矩形）。
2. 找到含 --anchor 的文本行，取其行 bbox。
3. 在所有"包含该行、且高度 ≥ 2 倍行高"的框里，取面积最小的那个 → 该签名栏的框。
4. 区域 = 框内、锚点行下方（y = 行底 + gap 到 框底 − inset），横向 框左+inset 到 框右−inset。

若页面没有可用矢量框（纯扫描图、无边框），自动定位会报 error 并提示改用 --rect/--box。 表格类表单里如果锚点出现在多行（如"签名"两处），用 --nth 选第几个，或用 --rect 精确指定。

常见坑与对策

更多细节见 references/workflow.md。

依赖与文件管理

• 依赖：PyMuPDF(fitz)、Pillow、numpy、scipy。
• 所有产物/中间件写调用方指定的项目文件夹（--out/--outdir），skill 目录不留产物。
• 本机跨机同步：~/.config/opencode/skills/signature-splice/。