KaguraNanaga/format-agent-skill

Agent de mise en forme

Reformate automatiquement les documents Word (.docx) mal structurés selon des spécifications données. Compréhension par l'IA, exécution par le code, échange via JSON.

Périmètre fonctionnel

• Deux sources de format : spécifications textuelles naturelles (.txt) ou modèle Word correctement formaté (.docx)
• Tout document déjà mis en forme peut servir de modèle : documents de comité/actionnaires/conseil d'administration, contrats, avis juridiques, rapports de conseil, thèses, communiqués de presse… L'Agent lit leur police/taille/interligne/retrait/numérotation et les applique au document cible
• Prise en charge des documents non structurés (l'agent détermine le rôle des paragraphes par compréhension sémantique) et des documents numérotés (numérotation manuelle comme I, (I), 1., Chapitre 1/Article 1, ou numérotation automatique Word, identification déterministe)
• Niveau page : marges, grille de lignes, en-têtes/pieds de page (champs de numérotation)
• Niveau paragraphe : police/taille/alignement/interligne/retrait première ligne/numérotation
• Niveau tableau : en-tête première ligne (gras/centré), police/taille/alignement des cellules, bordures
• Les rôles non spécifiés dans le modèle sont automatiquement alignés sur le corps du texte
• Aucune modification du texte : vérification automatique de la cohérence textuelle après chaque mise en forme (comparaison paragraphe par paragraphe entre original et résultat final), toute modification de texte est signalée
• Table des matières : génération automatique si le modèle contient un champ de table des matières (Word génère la TDM après mise à jour des champs) ; mise en page multicolonne : prise en charge (adaptée aux thèses universitaires en deux colonnes)
• La version actuelle ne reformate pas : la page de garde ; les structures de tableaux complexes avec cellules fusionnées restent inchangées

Prérequis système

• Python 3.10+, dépendances : pip install -r requirements.txt (python-docx, requests, PyMuPDF ; Windows nécessite en plus pywin32)
• Aucun modèle à configurer dans l'environnement de l'Agent : la compréhension est assurée par l'Agent hôte (voir "Utilisation 1")
• Le mode API autonome (sans Agent) nécessite une configuration modèle : Variables d'environnement / fichier .env : LLM_BASE_URL, LLM_API_KEY, LLM_MODEL (optionnel : LLM_VISION_MODEL, LLM_TIMEOUT, LLM_TEMPERATURE)

Choix du modèle (important : multimodal recommandé)

Ce skill n'est pas lié à un modèle spécifique, tout point de terminaison compatible OpenAI fonctionne. Il est cependant recommandé de configurer un modèle multimodal (acceptant à la fois texte et images, comme GPT-4o, Kimi K3, Qwen-VL, GLM-4V, etc.) :

• Le flux principal de mise en forme (extraction des règles, affectation des rôles) ne nécessite que des capacités textuelles
• L'auto-vérification visuelle (--verify) nécessite impérativement que le modèle examine les rendus ; les modèles purement textuels ne peuvent pas utiliser cette étape

Instruction pour l'Agent appelant : Avant de commencer, vérifiez quel est le modèle utilisé actuellement et s'il dispose de capacités multimodales (entrée image). Si ce n'est pas le cas, informez l'utilisateur : "Le modèle actuel ne supporte pas l'entrée image, l'auto-vérification visuelle ne sera pas disponible. Il est recommandé de passer à un modèle multimodal (par exemple XXX) pour bénéficier d'une vérification automatique après mise en forme, de meilleure qualité." Continuez après confirmation de l'utilisateur.

Utilisation

Ce skill propose deux modes d'utilisation. En environnement Agent, privilégiez le "mode intelligent intégré" – zéro configuration, aucune clé API nécessaire, la compréhension est assurée par vous (l'Agent hôte).

Utilisation 1 : Mode intelligent intégré à l'Agent (recommandé par défaut, zéro configuration)

Processus d'exécution pour vous, Agent hôte :

1. Extraire la structure du document cible :

   python main.py --extract-only --target document_a_formater.docx --out dossier_sortie/formate.docx
   

   Obtient dossier_sortie/formate_paragraphs.json, chaque paragraphe avec idx/text/size_pt/bold/alignment/style_name/in_table et métadonnées de numérotation.

2. Produire vous-même un FormatSpec (JSON des règles de format) :

   • L'utilisateur fournit des spécifications textuelles : lisez-les, écrivez le JSON selon le schéma ci-dessous, sauvegardez sous dossier_sortie/formate_formatspec.json ;
   • L'utilisateur fournit un modèle docx : exécutez d'abord --extract-only sur le modèle, lisez les rôles de chaque paragraphe (titre/corps/signature…), écrivez dans modele_rolemap.json (format {"0": "title", "1": "body", ...}), puis utilisez --template modele.docx --template-rolemap-json modele_rolemap.json pour que le code lise les formats du modèle de manière déterministe.

   Schéma FormatSpec :

   {
     "page": {"margin": {"top_mm": 37, "bottom_mm": 35, "left_mm": 28, "right_mm": 26},
              "line_grid": {"line_pt": 28}},
     "roles": {
       "body": {"font_eastasia": "仿宋_GB2312", "font_ascii": "Times New Roman",
                "size_pt": 16, "bold": false, "alignment": "justify",
                "first_line_indent_chars": 2, "line_spacing": {"type": "exact", "pt": 28}}
     }
   }
   

   Énumération des rôles : title/subtitle/heading_1/heading_2/heading_3/body/signature/date/attachment_label/attachment/other. body obligatoire ; valeurs d'alignement left/center/right/justify ; size_pt 872, marges 550mm. N'écrivez pas de rôles non mentionnés dans les spécifications, n'inventez pas de champs non spécifiés.

3. Produire vous-même un RoleMap (JSON des rôles de paragraphes) : lisez la liste des paragraphes de l'étape 1, attribuez à chaque paragraphe avec in_table=false un rôle de l'énumération, sauvegardez sous dossier_sortie/formate_rolemap.json, format {"0": "title", "1": "body", ...}, doit couvrir tous les paragraphes non-table. Critères d'appréciation : contenu textuel, ordre de position, indices de format actuels ; la signature est en fin de document avec un fort aspect de signature ; la date contient "année/mois/jour" ; le titre est au début et forme une ligne indépendante.

4. Exécuter la mise en forme (code déterministe) :

   # Source spécifications textuelles (FormatSpec produit par vous à l'étape 2)
   python main.py --spec-json dossier_sortie/formate_formatspec.json \
       --rolemap-json dossier_sortie/formate_rolemap.json \
       --target document_a_formater.docx --out dossier_sortie/formate.docx
   
   # Source modèle
   python main.py --template modele.docx --template-rolemap-json modele_rolemap.json \
       --rolemap-json dossier_sortie/formate_rolemap.json \
       --target document_a_formater.docx --out dossier_sortie/formate.docx
   

   Le JSON que vous produisez est ensuite validé par le code (rôles valides, couverture complète des paragraphes, limites numériques), les échecs de validation sont signalés avec explication, corrigez et relancez.

Utilisation 2 : Mode API autonome (optionnel)

Uniquement nécessaire dans un environnement sans Agent (serveur, tâche planifiée, exécution locale). Copiez .env.example en .env, remplissez LLM_BASE_URL / LLM_API_KEY / LLM_MODEL (modèle multimodal recommandé, voir section précédente), puis :

# Spécifications textuelles comme source de format (le LLM extrait automatiquement les règles)
python main.py --spec specifications.txt --target document_a_formater.docx --out dossier_sortie/formate.docx

# Modèle Word comme source de format
python main.py --template modele.docx --target document_a_formater.docx --out dossier_sortie/formate.docx

Le modèle peut être n'importe quel document déjà correctement formaté selon les spécifications (documents de comité du parti, modèles de contrat, avis juridiques, rapports de conseil, exemples de thèses…), aucune modification ou annotation préalable n'est nécessaire.

Auto-vérification visuelle (optionnel, uniquement mode 2 + modèle multimodal)

Ajoutez --verify : après mise en forme, rendu en image, le modèle visuel vérifie par rapport aux spécifications, corrige les écarts et effectue une nouvelle mise en forme (une seule itération, pas de boucle ouverte). Dans l'utilisation 1, si vous (l'Agent hôte) avez des capacités de compréhension d'image, vous pouvez également effectuer votre propre vérification après rendu : le dossier de sortie *_verify_render/ contient les PNG par page.

Produits de sortie

Chaque exécution produit (même répertoire, même préfixe de nom) :

• formate.docx – document propre avec styles nommés écrits
• formate_tracked.docx – mode suivi des modifications : visible dans le volet Révision de Word, chaque modification de format est identifiable, acceptation/refus possible par modification
• formate_report.docx / .md – rapport de comparaison des modifications (paramètres de page, règles, détails des paragraphes)
• formate_formatspec.json / _rolemap.json / _stylemap.json – produits intermédiaires (preuve de compréhension pour révision)

Dépannage rapide

• Configuration LLM manquante → vérifiez .env ou les variables d'environnement
• Échec répété de l'affectation des rôles → sortie JSON instable du modèle, utilisez --rolemap-json pour une annotation manuelle
• Vérification visuelle 400 temperature → ce modèle n'accepte que temperature=1, définissez LLM_TEMPERATURE=1 dans .env
• Erreur d'image lors de la vérification visuelle → le point de terminaison ne supporte pas les images inline data:base64, ou le modèle actuel n'a pas de capacité d'entrée image ; changez pour un modèle multimodal
• Échec du rendu → Windows nécessite Word installé (via COM), macOS/Linux nécessite LibreOffice

Répertoire examples/

• messy.docx : exemple de document officiel mal formaté (notification)
• spec.txt : exemple de spécifications de mise en forme de document officiel
• spec_std.json / rolemap_std.json : réponses standard pour l'exemple ci-dessus (référence de validation + entrée de secours)
• template-document-exemple.docx : exemple de source de format pour le mode modèle