Que fait Studio d'Écriture Manuelle Personnelle ?
Transformez des photos réelles de stylo sur papier en une bibliothèque de glyphes manuscrits réutilisable et générez par programmation des documents manuscrits réalistes multipages et des PDF — sans aucun artefact de police générée par IA.
Aperçu
Ce skill orchestre un pipeline d'écriture manuscrite en boucle fermée, 100% programmatique :
- Initialisation de l'espace de travail : Créez un espace de travail local personnel (conservé hors de git via
.gitignore). - Vérification préalable de la couverture : Analysez un brouillon cible (
pages.jsonou texte brut) par rapport àglyphs/manifest.jsonet produisez la liste minimale exacte (ou une feuille A4 imprimable) des caractères manquants. - Prétraitement photo et ingestion guidée : Décodez les photos
.DNG/.HEIC/.JPG/.PNGavec normalisation de l'éclairage (suppression des ombres et du transpercement du papier), découpez les caractères via un clustering de composants connectés guidé par lignes, et exécutez un audit visuel obligatoire via planche-contact avant de valider les glyphes. - Mise en page réaliste et rendu PDF : Composez les pages sur du papier vierge ou des modèles personnalisés en utilisant une normalisation de l'épaisseur du trait suréchantillonnée 2× (consistance stylo gel ~0.6 mm), une déduplication multi-variantes par fenêtre glissante, une ligne de base ondulée naturelle, des tableaux/équations dessinés à main levée tremblante, et une vérification de la couverture à 100% des caractères.
Dépendances
- Exécution :
uv(recommandé) ou Python 3.10+ avecpillowetnumpy.scripts/handwrite.pyinclut des métadonnées en ligne PEP 723, doncuv run scripts/handwrite.py ...provisionne automatiquement les dépendances sur macOS, Linux et Windows. - Optionnel :
ffmpeg(oupillow-heif) pour décoder les photos.HEIC.swiftde macOS uniquement si vous utilisez l'extracteur OCR optionnel Apple Vision (voir references/macos_vision_ocr.md).
Démarrage rapide
# 1. Initialiser un espace de travail personnel (avec l'exemple facultatif de rapport de laboratoire USST)
uv run scripts/handwrite.py init --workspace ./mon_ecriture --with-example
# 2. Vérifier quels caractères d'un brouillon sont manquants dans votre bibliothèque de glyphes
uv run scripts/handwrite.py check \
--content ./mon_ecriture/content/sample_pages.json \
--manifest ./mon_ecriture/glyphs/manifest.json \
--output ./mon_ecriture/coverage_report.json \
--grid-dir ./mon_ecriture/missing_grid
# 3. Prétraiter une photo de votre feuille manuscrite (DNG / HEIC / JPG / PNG)
uv run scripts/handwrite.py preprocess \
--input ./mon_ecriture/photos/feuille1.jpg \
--output-dir ./mon_ecriture/preprocessed
# 4. Simulation de découpage et audit visuel avant validation dans manifest.json
uv run scripts/handwrite.py ingest \
--input ./mon_ecriture/preprocessed/feuille1_ink.png \
--rows-spec ./mon_ecriture/content/rows_spec.json \
--manifest ./mon_ecriture/glyphs/manifest.json \
--contact-dir ./mon_ecriture/contact_sheets \
--dry-run
# 5. Après inspection visuelle de la superposition de débogage et de la planche-contact, valider les glyphes (omettre --dry-run)
uv run scripts/handwrite.py ingest \
--input ./mon_ecriture/preprocessed/feuille1_ink.png \
--rows-spec ./mon_ecriture/content/rows_spec.json \
--manifest ./mon_ecriture/glyphs/manifest.json \
--contact-dir ./mon_ecriture/contact_sheets
# 6. Générer des PNG manuscrits réalistes multipages + PDF combiné
uv run scripts/handwrite.py render \
--content ./mon_ecriture/content/sample_pages.json \
--manifest ./mon_ecriture/glyphs/manifest.json \
--assets-dir ./mon_ecriture \
--output-dir ./mon_ecriture/output \
--pdf-name rapport.pdf
Flux de travail standard de l'agent
Étape 1 : Vérification préalable de la couverture avant de demander à l'utilisateur d'écrire
- Convertissez le brouillon de l'utilisateur en un
pages.jsonstructuré (voir references/page_schema.md) ou passez un brouillon.txtdirectement àcheck. - Exécutez
uv run scripts/handwrite.py check ...pour calculer les caractères manquants exacts triés par fréquence. - Demandez à l'utilisateur d'écrire à la main uniquement les caractères manquants sur du papier blanc vierge avec un stylo gel noir (recommandez d'écrire 2 à 4 variantes pour les caractères à haute fréquence, les chiffres
0–9et la ponctuation afin que les pages rendues aient l'air naturelles), et prenez une photo plate et uniformément éclairée.
Étape 2 : Prétraitement, ingestion guidée par lignes et audit visuel obligatoire
- Exécutez
preprocesspour décoder les photos.DNG/.HEIC/.JPG/.PNGen<base>_clean.pnget<base>_ink.png(RGBA transparent). Utilisez--crop x0,y0,x1,y1(normalisé0.0–1.0) si la photo inclut des bords de bureau ou des ombres. - Créez un
rows_spec.jsonlistant les caractères écrits sur chaque ligne (utilisez"□"ou"SKIP"pour ignorer les erreurs barrées ou les taches parasites ; voirexamples/usst_lab_report/sample_rows_spec.json). - Exécutez toujours
ingestavec--dry-runen premier. Inspectez à la fois<base>_debug.png(cadres de délimitation sur l'encre) et<base>_sheet.png(planche-contact des caractères individuels étiquetés) à l'aide de votre outil de lecture/vision de fichiers. - Confirmez l'absence de mauvais alignements, de taches d'encre ou de traits tronqués. Seulement alors, réexécutez
ingestsans--dry-runpour valider les glyphes dansmanifest.jsonen utilisant des noms de fichiers insensibles à la casse multiplateforme (upper_<X>_k.png,lower_<x>_k.png,sym_u<4hex>_k.png,<ch>_k.png).
Étape 3 : Rendu et assurance qualité page par page
- Exécutez
render. Le script applique une vérification préalable de couverture à 100% des caractères (verify_all_chars_covered) et échoue rapidement si un caractère est manquant. - Inspectez visuellement chaque
page_<N>.pngrendue :- Vérifiez le pourcentage de remplissage vertical dans stdout ; si
[WARNING] ... overflowed bottom marginapparaît, réduisez--font-size(plage typique28–34), resserrezline_h_ratio(1.38–1.50), ou divisez le contenu sur une page de continuation supplémentaire. - Vérifiez que les champs de couverture s'alignent proprement sur les soulignements, que les tableaux ne coupent pas le texte des cellules et que les épaisseurs de trait semblent uniformes.
- Vérifiez le pourcentage de remplissage vertical dans stdout ; si
Référence des scripts utilitaires
| Sous-commande | Description | Principaux indicateurs |
|---|---|---|
init | Créer un espace de travail personnel propre | --workspace, --with-example |
check | Calculer la couverture des glyphes et une grille A4 facultative des caractères manquants | --content, --manifest, --output, --grid-dir |
preprocess | Décoder la photo et extraire l'encre RGBA sans ombre | --input, --output-dir, --crop, --hi, --lo |
ingest | Découpage guidé par lignes en glyphes RGBA + feuilles d'audit | --input, --rows-spec, --manifest, --contact-dir, --dry-run, --source-id |
contact-sheet | Générer une planche-contact étiquetée à partir de manifest.json | --manifest, --output, --chars |
render | Rendre pages.json sur des modèles et exporter en PDF | --content, --manifest, --output-dir, --assets-dir, --pdf-name, --font-size, --messiness, --seed |
Erreurs courantes
- Sauter l'audit visuel
--dry-runlors de l'ingestion : Une seule tache barrée ou une paire de traits adjacents fusionnés peut décaler les étiquettes d'une ligne entière. Inspectez toujours<base>_debug.pnget<base>_sheet.pngavant de valider. - Utiliser la génération d'images IA ou des polices système de secours : Ne générez jamais de pages manuscrites avec des modèles de diffusion et ne substituez pas des polices système pour les caractères manquants. Capturez toujours les glyphes manquants réels via
check→ingest. - Collisions de noms de fichiers insensibles à la casse : Sur macOS (APFS) et Windows (NTFS),
A_0.pngeta_0.pngs'écrasent mutuellement. Utilisez toujourshandwrite.py(qui imposeupper_A_0.png/lower_a_0.png/sym_uXXXX_0.png). - Appeler
sipsde macOS dans des environnements sandboxés :sipspeut produire silencieusement des images noires pleines dans des environnements sandboxés.handwrite.py preprocesstraite.DNGen Python pur et.HEICviapillow-heifouffmpeg. - Valider l'écriture manuscrite personnelle dans Git : Gardez les espaces de travail personnels (
glyphs/,photos/,output/) en dehors du dépôt du skill ou dans des chemins ignorés par git.