个人笔迹工坊 是做什么的?
将真实纸笔手写照片转化为可复用的个人字形库,并以程序化方式渲染出逼真的多页手写文档和PDF —— 零AI生成字体伪影。
概述
该技能编排了一个闭环的、100%程序化的手写流水线:
- 工作区初始化:在本地创建个人工作区(通过
.gitignore排除出Git仓库)。 - 覆盖预检:对照
glyphs/manifest.json扫描目标草稿(pages.json或纯文本),生成精确的最小缺失字符列表(或可打印的A4书写纸模板)。 - 照片预处理与引导式录入:解码
.DNG/.HEIC/.JPG/.PNG照片并进行光照归一化(去除阴影和纸张洇染),通过跨平台的行引导连通分量聚类切分字符,并在提交字形前运行强制性的视觉接触表审计。 - 逼真排版与PDF渲染:在空白纸张或自定义模板上排版页面,使用2倍超采样笔画宽度归一化(约0.6毫米中性笔一致性)、滑动窗口多变体去重、自然基线波动、摇晃的手绘风格表格/公式,以及100%字符覆盖率验证。
依赖项
- 运行环境:
uv(推荐)或 Python 3.10+ 并安装pillow和numpy。scripts/handwrite.py包含 PEP 723 内联元数据,因此uv run scripts/handwrite.py ...可在 macOS、Linux 和 Windows 上自动安装依赖。 - 可选:
ffmpeg(或pillow-heif)用于解码.HEIC照片。- macOS 的
swift,仅在需要可选的自由形态 Apple Vision OCR 提取器时使用(参见 references/macos_vision_ocr.md)。
快速开始
# 1. 初始化个人工作区(可选USST实验报告模板示例)
uv run scripts/handwrite.py init --workspace ./my_handwriting --with-example
# 2. 检查草稿中有哪些字符在你的字形库中缺失
uv run scripts/handwrite.py check \
--content ./my_handwriting/content/sample_pages.json \
--manifest ./my_handwriting/glyphs/manifest.json \
--output ./my_handwriting/coverage_report.json \
--grid-dir ./my_handwriting/missing_grid
# 3. 预处理手写纸张照片(DNG / HEIC / JPG / PNG)
uv run scripts/handwrite.py preprocess \
--input ./my_handwriting/photos/sheet1.jpg \
--output-dir ./my_handwriting/preprocessed
# 4. 执行试运行切分并视觉审计,之后才提交到manifest.json
uv run scripts/handwrite.py ingest \
--input ./my_handwriting/preprocessed/sheet1_ink.png \
--rows-spec ./my_handwriting/content/rows_spec.json \
--manifest ./my_handwriting/glyphs/manifest.json \
--contact-dir ./my_handwriting/contact_sheets \
--dry-run
# 5. 视觉检查调试叠加图和接触表后,提交字形(省略 --dry-run)
uv run scripts/handwrite.py ingest \
--input ./my_handwriting/preprocessed/sheet1_ink.png \
--rows-spec ./my_handwriting/content/rows_spec.json \
--manifest ./my_handwriting/glyphs/manifest.json \
--contact-dir ./my_handwriting/contact_sheets
# 6. 渲染逼真的多页手写PNG + 合并PDF
uv run scripts/handwrite.py render \
--content ./my_handwriting/content/sample_pages.json \
--manifest ./my_handwriting/glyphs/manifest.json \
--assets-dir ./my_handwriting \
--output-dir ./my_handwriting/output \
--pdf-name report.pdf
标准代理工作流程
阶段一:在要求用户书写之前进行覆盖预检
- 将用户的草稿转换为结构化的
pages.json(参见 references/page_schema.md),或直接将.txt纯文本草稿传给check。 - 运行
uv run scripts/handwrite.py check ...以按频率排序精确计算缺失字符。 - 让用户在空白白纸上用黑色中性笔仅手写缺失字符(高频字符、数字
0–9和标点符号建议写2–4种变体,使渲染页面看起来自然),并拍摄一张平整、光线均匀的照片。
阶段二:预处理、行引导录入与强制性视觉审计
- 运行
preprocess将.DNG/.HEIC/.JPG/.PNG解码为<base>_clean.png和<base>_ink.png(透明RGBA)。若照片包含桌面边缘或阴影,可使用--crop x0,y0,x1,y1(归一化0.0–1.0)。 - 创建一个
rows_spec.json,列出每行书写的字符(用"□"或"SKIP"忽略划掉的错误或散落墨点;参见examples/usst_lab_report/sample_rows_spec.json)。 - 始终先使用
--dry-run运行ingest。 利用你的文件读取/视觉工具检查<base>_debug.png(覆盖在墨迹上的边界框)和<base>_sheet.png(带标签的单字符接触表)。 - 确认没有错位、墨渍或裁剪的笔画。只有确认无误后,才能在不加
--dry-run的情况下重新运行ingest,以跨平台大小写安全的文件名(upper_<X>_k.png、lower_<x>_k.png、sym_u<4hex>_k.png、<ch>_k.png)将字形提交到manifest.json。
阶段三:渲染与逐页质量检查
- 运行
render。该脚本强制执行100%字符覆盖率预检(verify_all_chars_covered),如果有任何字符缺失则快速失败。 - 视觉检查每个渲染的
page_<N>.png:- 在标准输出中检查垂直填充百分比;若出现
[WARNING] ... overflowed bottom margin,则减小--font-size(典型范围28–34),收紧line_h_ratio(1.38–1.50),或将内容拆分到额外的续页上。 - 确认封面字段在下方线上对齐,表格未裁剪单元格文字,笔画粗细看起来均匀。
- 在标准输出中检查垂直填充百分比;若出现
工具脚本参考
| 子命令 | 描述 | 关键标志 |
|---|---|---|
init | 创建干净的个人工作区 | --workspace, --with-example |
check | 计算字形覆盖与可选A4缺失字符网格 | --content, --manifest, --output, --grid-dir |
preprocess | 解码照片并提取无阴影RGBA墨迹 | --input, --output-dir, --crop, --hi, --lo |
ingest | 行引导切分为RGBA字形 + 审计表 | --input, --rows-spec, --manifest, --contact-dir, --dry-run, --source-id |
contact-sheet | 从 manifest.json 生成带标签的接触表 | --manifest, --output, --chars |
render | 将 pages.json 渲染到模板并导出PDF | --content, --manifest, --output-dir, --assets-dir, --pdf-name, --font-size, --messiness, --seed |
常见错误
- 在
ingest阶段跳过--dry-run视觉审计:单个划掉的墨渍或相邻笔画合并可能导致整行标签偏移。提交前务必检查<base>_debug.png和<base>_sheet.png。 - 使用AI图像生成或系统字体回退:切勿使用扩散模型生成手写页面或用系统字体替代缺失字符。始终通过
check→ingest捕捉真正的缺失字形。 - 大小写不敏感文件系统冲突:在 macOS (APFS) 和 Windows (NTFS) 上,
A_0.png和a_0.png会互相覆盖。始终使用handwrite.py(它强制使用upper_A_0.png/lower_a_0.png/sym_uXXXX_0.png)。 - 在沙盒内调用 macOS 的
sips:sips在沙盒环境中可能静默输出纯黑色图像。handwrite.py preprocess通过纯Python处理.DNG,通过pillow-heif或ffmpeg处理.HEIC。 - 将个人手写提交到Git:将个人工作区(
glyphs/、photos/、output/)保持在技能仓库之外,或放在被.gitignore忽略的路径中。