Community图像github.com

个人笔迹工坊

图像技能。从真实纸笔照片构建个人手写字形库,检查目标草稿的字符覆盖率,指导仅补充缺失字符,并以程序化方式渲染出逼真的多页手写文档和PDF(含表格、公式和自定义模板),无AI图像生成伪影。当用户想要数字化自己的笔迹、创建或扩展现有字形库、或渲染手写作业、笔记或实验报告时使用。

个人笔迹工坊 是什么?

个人笔迹工坊是一个面向开发者和AI代理用户的完整手写数字化与渲染流水线。该技能的核心价值在于实现从真实纸笔照片到可复用字形库的闭环流程,并生成无AI伪影的程序化手写文档。它支持macOS、Linux和Windows平台,依赖uv或Python 3.10+,并自动处理依赖项。流水线分为三步:首先通过覆盖检查工具扫描目标草稿(如pages.json或纯文本)与字形清单,生成精确的缺失字符列表或A4书写纸模板;其次,使用光照归一化预处理照片(支持DNG、HEIC、JPG、PNG),通过行引导连通分量聚类切分字符,并强制要求视觉接触表审计后再提交字形;最后,利用2倍超采样、自然基线波动、手绘风格表格和公式等算法渲染多页手写PDF。技能特别强调严格的审计机制——在ingest阶段必须先用--dry-run检查切分标注是否正确——以避免因墨渍或拼写错误导致的字形错位。它适用于数字化手写笔记、生成作业报告或实验室记录等场景,并明确警告不要使用AI扩散模型或系统字体作为替代。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Elizhng/personal-handwriting/tree/HEAD

Installed? Explore more 图像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

个人笔迹工坊 是做什么的?

将真实纸笔手写照片转化为可复用的个人字形库,并以程序化方式渲染出逼真的多页手写文档和PDF —— 零AI生成字体伪影。

概述

该技能编排了一个闭环的、100%程序化的手写流水线:

  1. 工作区初始化:在本地创建个人工作区(通过.gitignore排除出Git仓库)。
  2. 覆盖预检:对照glyphs/manifest.json扫描目标草稿(pages.json或纯文本),生成精确的最小缺失字符列表(或可打印的A4书写纸模板)。
  3. 照片预处理与引导式录入:解码.DNG / .HEIC / .JPG / .PNG照片并进行光照归一化(去除阴影和纸张洇染),通过跨平台的行引导连通分量聚类切分字符,并在提交字形前运行强制性的视觉接触表审计。
  4. 逼真排版与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种变体,使渲染页面看起来自然),并拍摄一张平整、光线均匀的照片。

阶段二:预处理、行引导录入与强制性视觉审计

  1. 运行 preprocess 将 .DNG / .HEIC / .JPG / .PNG 解码为 <base>_clean.png 和 <base>_ink.png(透明RGBA)。若照片包含桌面边缘或阴影,可使用 --crop x0,y0,x1,y1(归一化 0.0–1.0)。
  2. 创建一个 rows_spec.json,列出每行书写的字符(用 "□" 或 "SKIP" 忽略划掉的错误或散落墨点;参见 examples/usst_lab_report/sample_rows_spec.json)。
  3. 始终先使用 --dry-run 运行 ingest。 利用你的文件读取/视觉工具检查 <base>_debug.png(覆盖在墨迹上的边界框)和 <base>_sheet.png(带标签的单字符接触表)。
  4. 确认没有错位、墨渍或裁剪的笔画。只有确认无误后,才能在不加 --dry-run 的情况下重新运行 ingest,以跨平台大小写安全的文件名(upper_<X>_k.png、lower_<x>_k.png、sym_u<4hex>_k.png、<ch>_k.png)将字形提交到 manifest.json。

阶段三:渲染与逐页质量检查

  1. 运行 render。该脚本强制执行100%字符覆盖率预检(verify_all_chars_covered),如果有任何字符缺失则快速失败。
  2. 视觉检查每个渲染的 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

常见错误

  1. 在 ingest 阶段跳过 --dry-run 视觉审计:单个划掉的墨渍或相邻笔画合并可能导致整行标签偏移。提交前务必检查 <base>_debug.png 和 <base>_sheet.png。
  2. 使用AI图像生成或系统字体回退:切勿使用扩散模型生成手写页面或用系统字体替代缺失字符。始终通过 check → ingest 捕捉真正的缺失字形。
  3. 大小写不敏感文件系统冲突:在 macOS (APFS) 和 Windows (NTFS) 上,A_0.png 和 a_0.png 会互相覆盖。始终使用 handwrite.py(它强制使用 upper_A_0.png / lower_a_0.png / sym_uXXXX_0.png)。
  4. 在沙盒内调用 macOS 的 sips:sips 在沙盒环境中可能静默输出纯黑色图像。handwrite.py preprocess 通过纯Python处理 .DNG,通过 pillow-heif 或 ffmpeg 处理 .HEIC。
  5. 将个人手写提交到Git:将个人工作区(glyphs/、photos/、output/)保持在技能仓库之外,或放在被 .gitignore 忽略的路径中。

相关技能