Import DOCX : aller-retour des documents Word dans un éditeur IA

Ingénierie 9 mai 2026 · 9 min de lecture

Il y a deux semaines, nous avons livré la réécriture de l'export DOCX/PDF : un document modifié dans AgentDoc (aussi : agent doc, agentdocs, docedit) quitte désormais l'éditeur sous la forme d'un fichier Word avec ses polices, ses couleurs, sa mise en page et ses en-têtes/pieds de page intacts. Cela résolvait exactement la moitié du flux de travail vraiment utile. L'autre moitié — faire entrer un document Word dans l'éditeur sans perdre sa structure — est ce qui a abouti cette semaine.

Cet article est le pendant de la réécriture de l'export : même modèle de données, sens opposé, même exigence de ne rien perdre de ce que l'utilisateur peut voir à l'écran.

Le cahier des charges

Un utilisateur téléverse un contract_v3.docx qu'il modifiait dans Word. Après l'import, l'ouverture du même document dans l'éditeur devrait afficher :

Les titres, paragraphes, listes, tableaux — au bon niveau, dans le bon ordre.
La mise en forme en ligne — gras, italique, souligné, barré, indice/exposant.
Les couleurs et surlignages — les couleurs réelles de la palette de l'éditeur, et non celles que Word a substituées par défaut.
Les polices et les tailles — associées aux douze jetons de l'éditeur (Inter, Playfair Display, Roboto Mono, etc.).
L'alignement, le retrait, l'interligne.
Les hyperliens — cliquables, avec leurs URL d'origine.
Les sauts de page là où l'auteur les a placés.
L'en-tête et le pied de page, avec leur propre mise en forme préservée.

Réexporté en DOCX, le même fichier devrait être comparable en structure (pas identique au bit près — Word écrit beaucoup de XML accessoire — mais visuellement indiscernable pour un lecteur).

Pourquoi analyser du DOCX n'est pas aussi accommodant qu'analyser du HTML

Un DOCX est un ZIP contenant du XML. Le schéma est l'OOXML (ECMA-376) et python-docx l'enveloppe dans un joli modèle objet paragraphe/run. L'ennui, c'est que l'essentiel de ce qui rend un vrai document Word intéressant vit en dehors de ce modèle objet accommodant :

Les sauts de page sont des éléments <w:br w:type="page"/> intégrés à l'intérieur des runs. Ils apparaissent bien dans paragraph.runs, mais, par effet de bord, un \n se glisse dans le texte du run — comptez-le une fois et vous vous retrouvez avec un saut de ligne parasite.
Les hyperliens vivent dans des éléments <w:hyperlink> qui sont des frères des éléments <w:r> à l'intérieur du paragraphe. paragraph.runs les ignore entièrement — n'itérez que sur les runs et le texte du lien disparaît (ou subsiste, mais l'URL est perdue).
Les propriétés de section (taille de page, en-têtes, pieds de page) pendent à sections[*].header / .footer avec des indicateurs d'héritage en cascade (is_linked_to_previous) que l'API accommodante résout silencieusement.
L'interligne est un multiplicateur flottant sur paragraph_format.line_spacing ; le réassocier aux jetons discrets de l'éditeur (tight / normal / relaxed / loose / double) exige une passe d'alignement sur la valeur la plus proche.

Si votre import DOCX n'utilise que paragraph.runs, votre document perd discrètement chaque hyperlien et chaque saut de page dès qu'il touche votre pipeline. Les deux font l'aller-retour sous forme de texte brut ou disparaissent entièrement. Nous avons rencontré ces deux bugs dès la première exécution d'intégration.

La structure : import_docx_bytes renvoie six clés

Avant ce travail, notre chemin d'import renvoyait un 2-tuple (markdown_body, formatting_array) — le contenu du corps plus les décalages de mise en forme stand-off. C'était correct pour les documents limités au corps, mais on perdait tout en-tête / pied de page créé par l'auteur.

Nous avons changé le type de retour pour un dictionnaire à six clés qui reflète le modèle de stockage de l'éditeur :

{
  "body_md":           "# Heading\n\nFirst paragraph...",
  "body_formatting":   [{"start": 0, "end": 9, "classes": "font-playfair"}, …],
  "header_md":         "Confidential — Q3 2026",
  "header_formatting": [{"start": 0, "end": 11, "classes": "decoration-bold"}],
  "footer_md":         "Page",
  "footer_formatting": [],
}

Chaque *_md utilise son propre espace d'index à base zéro ; les décalages d'en-tête / de pied de page ne sont pas partagés avec le corps. Les trois parcours partagent un même utilitaire (walk_container) qui réinitialise md_parts, formatting et le curseur à l'entrée, afin qu'ils ne déteignent pas leurs décalages les uns sur les autres.

Nous ne prenons que sections[0] (l'éditeur impose un en-tête / un pied de page par document) et nous respectons is_linked_to_previous — lorsqu'une section hérite d'une précédente (le défaut pour sections[0]), elle n'a pas d'en-tête / de pied de page créé par l'auteur et nous contribuons des chaînes vides. Tout le bloc en-tête / pied de page est enveloppé dans un try / except, de sorte qu'un sectPr mal formé se dégrade en « pas d'en-tête / de pied de page » au lieu de faire échouer l'import entier.

Sauts de page : parcourir le XML brut

python-docx expose le texte d'un run sous la forme run.text — une concaténation de ses enfants <w:t> avec les <w:br> réduits à \n. Cela nous donne le texte mais perd la distinction entre un saut souple et un saut de page dur.

Correctif : parcourir paragraph._element.iter(qn("w:br")) sur chaque paragraphe et vérifier l'attribut w:type de chaque saut. Lorsque w:type == "page", émettre notre marqueur [PAGE BREAK]\n\n avant le contenu du paragraphe, afin qu'un saut-de-page-avant-titre dans Word survive sous forme de [PAGE BREAK]\n\n# Heading dans notre markdown. Si le paragraphe ne contient rien d'autre que le saut, ignorer le bloc final vide pour éviter les doubles sauts de ligne parasites, et retirer le \n induit par le saut de page du texte du run afin que le marqueur ne soit pas compté en double.

Hyperliens : itérer directement sur les enfants XML du paragraphe

Pour les hyperliens, l'astuce consiste à renoncer entièrement à paragraph.runs et à itérer sur les enfants XML du paragraphe, en répartissant selon la balise :

for child in paragraph._element:
    tag = etree.QName(child).localname
    if tag == "r":
        emit_run(child)
    elif tag == "hyperlink":
        emit_hyperlink(child)

emit_hyperlink résout r:id par rapport à la table de relations du paragraphe pour obtenir l'URL externe, avec un repli sur #anchor pour les hyperliens internes (entrées de table des matières pointant vers des signets de titre) afin que la structure survive même lorsque nous ne pouvons pas résoudre le signet. Nous émettons du markdown natif [text](url) — le chemin de lien markdown existant du moteur de rendu produit un véritable <a href> sans passe supplémentaire après coup.

Le style interne à l'intérieur de l'hyperlien (texte de lien en gras, texte de lien coloré) passe par le même pipeline emit_run que les runs simples, de sorte qu'un lien bleu en gras reste un lien bleu en gras dans l'éditeur.

Interligne : alignement sur la valeur la plus proche, dans les deux sens

L'éditeur n'accepte pas des flottants d'interligne arbitraires — il dispose de cinq jetons (tight / normal / relaxed / loose / double) qui correspondent respectivement à 1.2 / 1.6 / 2.0 / 2.5 / 3.0. De l'éditeur vers le DOCX, la correspondance est directe. Le retour est plus flou : un document Word créé avec un interligne de 1,5x (typique pour le corps de texte) devrait faire l'aller-retour vers linespacing-normal, sans être rejeté.

L'implémentation est l'inverse du _nearest_size_token côté export : une passe d'alignement sur la valeur la plus proche contre les cinq mêmes valeurs de référence. Le résultat est émis sous la forme d'un attribut de bloc au niveau du paragraphe {: .linespacing-X } aux côtés de l'alignement et du retrait.

Le test d'aller-retour

Les conversions bidirectionnelles sont faciles à casser et difficiles à repérer. Nous avons ajouté backend/tests/manual_docx_roundtrip.py — un script d'audit manuel (dans l'esprit des autres audits manual_*.py) qui fait :

doc = build_test_document()
docx_1 = generate_docx_bytes(doc)        # Editor -> Word
parsed = import_docx_bytes(docx_1)       # Word -> Editor
docx_2 = generate_docx_bytes(parsed)     # Editor -> Word again

assert paragraph_count(docx_1) == paragraph_count(docx_2)
assert heading_levels(docx_1) == heading_levels(docx_2)
assert run_properties(docx_1) == run_properties(docx_2)

Ce n'est pas un test pytest — il s'exécute contre le conteneur backend en direct et inspecte le XML OOXML réel des deux fichiers docx générés. La sortie est constituée de diffs lisibles par un humain de ce qui a changé d'une passe à l'autre. Nous ajoutons une nouvelle assertion chaque fois qu'une régression est découverte, de sorte que la prochaine fois que le même cas limite apparaît, l'audit échoue bruyamment au lieu de se perdre silencieusement dans un document complexe.

Ce qui reste imparfait

Sections multiples. Un document avec des sauts de section (des en-têtes différents au chapitre 1 et au chapitre 2) est aplati au chrome de la première section. Le modèle de données de l'éditeur ne prend en charge qu'un en-tête / un pied de page par document, et changer cela est une opération bien plus lourde que le seul chemin d'import.
Commentaires et suivi des modifications. Les deux sont présents dans l'OOXML mais nous les laissons tomber aujourd'hui. L'éditeur n'a d'interface pour ni l'un ni l'autre, donc les importer reviendrait de toute façon à les écarter à la prochaine sauvegarde.
Images. Nous extrayons bien les références d'images, mais seulement sous forme de substituts reliés. Extraire les octets réels de l'image du dossier média du DOCX, les persister, et réécrire la référence de l'image dans le markdown est la prochaine passe.
Styles personnalisés. Un document qui utilise un style Word personnalisé (« Citation en retrait du corps ») qui ne fait pas partie des styles connus de l'éditeur se voit attribuer la correspondance la plus proche de notre table de styles. L'aller-retour fidèle de styles personnalisés arbitraires exigerait de transporter leurs définitions à travers le modèle de données de l'éditeur, ce que nous ne faisons pas.

Ce que cela change pour les utilisateurs

Le flux de travail vedette est désormais symétrique. Vous pouvez :

Prendre un document Word existant — une lettre en brouillon, un article de recherche, un contrat.
Le téléverser dans AgentDoc (un simple clic sur le bouton « Importer .docx » de la barre latérale, ou un simple POST /api/docs/import/docx pour les agents autonomes — voir la documentation des agents).
Le modifier à la voix ou par chat, l'agent effectuant des modifications structurées tandis que la mise en page reste exactement telle que vous l'avez créée.
Le réexporter vers Word, et votre collaborateur ouvre le fichier dans le même Word avec lequel il a commencé, avec les mêmes polices, les mêmes couleurs, la même géométrie de page.

Pour le flux de travail côté agent en particulier, cela boucle aussi le cycle où un client MCP autonome ne pouvait construire des documents qu'à partir de zéro. Avec import_docx_bytes branché, un agent peut ingérer un DOCX gabarit (par ex. un en-tête d'entreprise avec des champs pré-remplis), piloter les modifications via la surface d'outils MCP, et exporter le résultat — exactement le genre de cas d'usage « remplissez ce formulaire » où retaper depuis zéro est le goulot d'étranglement.