Communitygithub.com

V4TIME/V4SKILL

Créer, lire, éditer, générer à partir de modèles et réviser des fichiers Word .docx.

Qu'est-ce que V4SKILL ?

Cette compétence permet aux agents IA de manipuler des documents Microsoft Word au format `.docx` via une interface en ligne de commande utilisant la bibliothèque python-docx. Elle couvre la création à partir d'une spécification JSON, la lecture du texte, de la structure, des styles et des images intégrées, ainsi que l'édition fine (rechercher/remplacer, modification des cellules de tableau, insertion/suppression de paragraphes, fusion de fragments de texte). Elle gère également les fonctionnalités avancées comme le templating avec placeholders `{{token}}`, les révisions (suivi des modifications : lister/accepter/rejeter), les commentaires (ajouter/supprimer/lister), l'insertion de tables des matières et de champs de numérotation de pages, et la validation de l'intégrité du fichier. La compétence ne convertit pas en PDF (nécessite LibreOffice) et ne fonctionne pas avec le format `.doc` hérité. Son utilité est cruciale pour les agents qui doivent générer des rapports, lettres ou contrats, ou automatiser des révisions et la gestion des commentaires dans des documents professionnels. La procédure d'utilisation suit un workflow clair : créer via spec JSON, lire pour inspecter, éditer avec des commandes ciblées, réviser les modifications, gérer les commentaires, appliquer un modèle, puis vérifier le résultat.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/V4TIME/V4SKILL/tree/HEAD/productivity/docx

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Compétence Docx

Créer, lire, éditer et générer à partir de modèles des fichiers Microsoft Word .docx avec python-docx via de petites CLI. Elle gère le texte, les styles, les listes, les tableaux, les images, les en-têtes/pieds de page, le templating {{token}}, les révisions (lister/accepter/rejeter), les commentaires (lister/ajouter/supprimer), les champs TdM et de numérotation de pages, et les vérifications d'intégrité. Elle ne rend pas elle-même les documents (PDF nécessite LibreOffice — voir Conversion en PDF) et ne modifie pas le format .doc hérité.

Quand l'utiliser

  • L'utilisateur demande de générer un document Word (rapport, lettre, contrat).
  • Vous avez besoin du texte, du plan, des styles ou des images intégrées d'un .docx.
  • Vous devez modifier un .docx existant : remplacer du texte, modifier des cellules de tableau, insérer/supprimer des paragraphes, appliquer des styles, fusionner des fragments de texte.
  • Vous avez un modèle .docx avec des {{placeholders}} à remplir à partir de données.
  • Le document comporte des révisions (suivi des modifications) à examiner, accepter ou rejeter.
  • Vous devez lire les commentaires des relecteurs, ou ajouter/supprimer des commentaires.
  • Un .docx ne s'ouvre pas ou se comporte étrangement et vous devez diagnostiquer une corruption.
  • Le document a besoin d'une table des matières ou de pieds de page « Page X sur Y ».
  • Ne convient pas pour : .doc (hérité), .odt ou travail de mise en page WYSIWYG.

Prérequis

  • Python 3.10+ avec python-docx installé : pip install python-docx (le nom d'importation est docx ; lxml est inclus).
  • Les commentaires add utilisent l'API native sur python-docx >= 1.2 et une solution de repli XML sur les versions plus anciennes — les deux sont automatiques.
  • Pour les blocs d'image : les fichiers image doivent exister localement (PNG/JPEG).

Comment exécuter

Tous les scripts se trouvent dans scripts/ à côté de ce fichier. Exécutez-les avec l'outil terminal ; chacun prend en charge --help et affiche du JSON sur stdout.

python scripts/docx_create.py spec.json out.docx
python scripts/docx_read.py out.docx --text
python scripts/docx_edit.py replace out.docx --find old --replace new
python scripts/docx_template.py tpl.docx values.json filled.docx
python scripts/docx_revisions.py list out.docx
python scripts/docx_comments.py list out.docx
python scripts/docx_validate.py out.docx

Référence rapide

TâcheCommande
Créer à partir d'une spécification JSONdocx_create.py spec.json out.docx
Texte intégral (corps+tableaux+en-têtes/pieds)docx_read.py f.docx --text
Plan des titres + formes des tableauxdocx_read.py f.docx --structure
Styles réellement utilisésdocx_read.py f.docx --styles
Extraire les images intégréesdocx_read.py f.docx --images outdir/
Détecter les révisions/commentairesdocx_read.py f.docx --revisions
Rechercher/remplacer (formatage conservé)docx_edit.py replace f.docx --find A --replace B -o out.docx
Définir une cellule de tableaudocx_edit.py set-cell f.docx --table 0 --row 1 --col 2 --text X
Insérer un paragraphe avant l'index Ndocx_edit.py insert f.docx --index N --text X --style Normal
Supprimer le paragraphe Ndocx_edit.py delete f.docx --index N
Appliquer un style au paragraphe Ndocx_edit.py style f.docx --index N --style "Heading 1"
Fusionner les fragments adjacents de même formatdocx_edit.py normalize f.docx -o out.docx
Insérer un champ TdM avant le para Ndocx_edit.py toc f.docx --index N -o out.docx
Pieds de page « Page X sur Y »docx_edit.py page-numbers f.docx
Remplir {{tokens}}docx_template.py tpl.docx values.json out.docx --strict
Lister les révisions (id/auteur/date/texte)docx_revisions.py list f.docx
Accepter / Rejeter toutes les révisionsdocx_revisions.py accept-all f.docx -o out.docx (ou reject-all)
Accepter / Rejeter une révisiondocx_revisions.py accept f.docx --id 3 -o out.docx
Lister les commentaires (+texte ancré)docx_comments.py list f.docx
Ajouter un commentaire ancré à du textedocx_comments.py add f.docx --target "phrase" --text "note" --author You
Supprimer un commentaire par iddocx_comments.py delete f.docx --id 0
Vérifier l'intégrité du packagedocx_validate.py f.docx (sortie 1 en cas d'erreur)

Procédure

  1. Créer. Rédigez une spécification JSON avec write_file, puis exécutez scripts/docx_create.py. La spécification prend en charge : page (taille + marges en mm), chaînes header/footer, footer_page_numbers (ajoute un champ de pied de page « Page X sur Y »), styles (styles de paragraphe personnalisés avec police, taille, gras/italique, couleur hexadécimale color), et blocks — heading (niveau 1-9), paragraph (soit text soit une liste runs où chaque passage peut définir bold/italic/underline), bullet_list, numbered_list, table (ligne d'header rendue en gras, rows, style de tableau intégré optionnel tel que Table Grid), image (path, width_mm optionnel), toc (champ de table des matières), et page_break. Le format complet de la spécification est documenté en haut de scripts/docx_create.py.
  2. Lire. Utilisez scripts/docx_read.py avec exactement un indicateur de mode. --text renvoie les paragraphes du corps, tout le texte des cellules de tableau et le texte des en-têtes/pieds de page au format JSON. --structure renvoie le plan des titres plus le nombre de paragraphes/tableaux/sections. --images DIR copie tous les fichiers sous word/media/ hors du package.
  3. Éditer. Utilisez scripts/docx_edit.py. replace parcourt le corps, les tableaux (imbriqués inclus), les en-têtes et les pieds de page, et préserve le formatage des passages ; ajoutez --body-only pour ignorer les en-têtes/pieds de page. Utilisez -o out.docx pour conserver l'original ; omettez-le pour modifier sur place. Les index de paragraphe pour insert/delete/style/toc se réfèrent à l'ordre du corps de --structure/--text. Lancez normalize d'abord sur les documents issus d'une édition Word intensive — il fusionne les passages adjacents avec un formatage identique afin que les recherches/remplacements ultérieurs correspondent de manière fiable.
  4. Réviser les révisions. docx_revisions.py list signale chaque w:ins et w:del (id, auteur, date, texte affecté) partout dans le corps, les tableaux, les en-têtes ou les pieds de page. accept-all / reject-all les résolvent en masse ; accept/reject --id N gère une seule révision. Accepter conserve les insertions et supprime le texte supprimé ; rejeter fait l'inverse.
  5. Commentaires. docx_comments.py list renvoie pour chaque commentaire son id, auteur, date, texte du corps, et le texte du document auquel il est ancré. add --target "une phrase" ancre un nouveau commentaire à la première occurrence de cette phrase (les passages sont divisés si nécessaire ; le formatage est conservé). delete --id N supprime le commentaire et ses marqueurs sans toucher au texte du document.
  6. Modèle. Placez des jetons de style {{nom}} dans le document. Lancez scripts/docx_template.py avec un objet JSON de valeurs. Utilisez --strict pour échouer lorsque des jetons restent non remplis ; la sortie JSON liste les comptes filled et unfilled_tokens dans les deux cas.
  7. Vérifier (toujours) : relisez la sortie avec --text ou --structure, et exécutez docx_validate.py sur tout ce que vous avez produit via une intervention sur les révisions/commentaires.

Conversion en PDF

Aucun script nécessaire. Lorsque LibreOffice est installé, convertissez sans interface :

soffice --headless --convert-to pdf --outdir outdir/ file.docx

Vérifiez d'abord la disponibilité (command -v soffice || command -v libreoffice). Si aucun des deux n'existe, dites à l'utilisateur que la conversion PDF est indisponible dans cet environnement plutôt que de bricoler — python-docx ne peut pas rendre les PDF, et la fidélité de mise en page nécessite un moteur de rendu réel.

Pièges à éviter

  • Jetons fragmentés entre passages. Word fragmente souvent le texte en plusieurs passages. Les scripts de remplacement regroupent les passages correspondants (le remplacement hérite du formatage du premier passage) ; l'exécution de docx_edit.py normalize en premier réduit la fragmentation pour toutes les modifications ultérieures.
  • Couverture des révisions. docx_revisions.py résout les insertions et suppressions au niveau des passages (l'écrasante majorité). Les révisions de marques de paragraphe et de lignes de tableau, les enregistrements de changement de format et les déplacements sont détectés par --revisions mais pas résolus automatiquement — voir references/revisions-and-comments.md et transmettez-les à Word.
  • Threads de commentaires. Les réponses et le statut « résolu » vivent dans commentsExtended.xml, que cette compétence ignore ; les commentaires qu'elle ajoute sont des commentaires simples de premier niveau.
  • Les résultats des champs sont calculés par Word. toc, page-numbers et les options de spécification toc/footer_page_numbers écrivent des codes de champ. Word/LibreOffice peuple les entrées et numéros réels lorsque le fichier est ouvert (Word peut demander à mettre à jour les champs) ; python-docx ne les calcule jamais, donc un texte de remplacement s'affiche jusqu'à ce moment.
  • La validation est une vérification d'intégrité, pas une validation de schéma. docx_validate.py vérifie le zip, les parties requises, les cibles des relations, les octets magiques des images et les styles référencés. Ce n'est PAS une validation XSD — un fichier peut réussir et contenir du XML que Word n'aime pas.
  • Les noms de styles doivent exister. Appliquer un style qui n'est pas défini dans le document lève KeyError. Les styles intégrés comme Heading 1, List Bullet, List Number, Table Grid existent dans le modèle par défaut ; les styles personnalisés doivent d'abord être déclarés dans la spécification de création.
  • Les listes numérotées redémarrent. List Number repose sur la numérotation par défaut de Word ; des listes séparées dans un même document peuvent continuer la numérotation au lieu de redémarrer. Avertissez les utilisateurs ayant besoin d'une numérotation précise pour plusieurs listes.
  • Les écritures dans les cellules remplacent le formatage. set-cell utilise cell.text = ..., ce qui réinitialise les passages dans cette cellule à un formatage simple.
  • Encodage. Tous les fichiers de spécifications/valeurs JSON sont lus explicitement en UTF-8 ; ne vous fiez jamais aux valeurs par défaut de la locale lorsque vous écrivez votre propre code de liaison.
  • Ne dézippez pas et n'utilisez pas sed sur le XML. Modifiez via les scripts (ou python-docx) ; une substitution de texte brut dans document.xml corrompt facilement les fichiers. Utilisez patch/write_file uniquement pour les entrées JSON, jamais sur le fichier .docx lui-même.

Vérification

  • Après création/édition/modèle, exécutez docx_read.py out.docx --text et vérifiez que les chaînes attendues apparaissent (et que les anciennes chaînes ont disparu).
  • Après acceptation/rejet, docx_revisions.py list devrait retourner [] (ou seulement les identifiants que vous avez intentionnellement laissés) ; après une intervention sur les commentaires, docx_comments.py list devrait refléter le changement et la sortie --text doit être inchangée.
  • docx_validate.py out.docx sort 0 avec "ok" : true sur un package sain — exécutez-le après toute manipulation de révisions/commentaires/champs.
  • Pour les modèles exécutés avec --strict, ou vérifiez que unfilled_tokens == [].
  • Vérifications de structure : --structure devrait montrer le plan de titres attendu et les formes des tableaux ; --styles confirme que les styles personnalisés ont été appliqués.

Individual skills in this repo

This repo contains 12 individual skills — each has its own dedicated page.

Skills associés