DOCX-Import: Word-Dokumente durch einen KI-Editor und zurück

Engineering 9. Mai 2026 · 9 Min. Lesezeit

Vor zwei Wochen haben wir die Neufassung des DOCX/PDF-Exports ausgeliefert: Ein in AgentDoc (auch: agent doc, agentdocs, docedit) bearbeitetes Dokument verlässt den Editor jetzt als Word-Datei mit intakten Schriftarten, Farben, Seitenlayout und Kopf-/Fußzeilen. Damit war genau die Hälfte des eigentlich nützlichen Workflows gelöst. Die andere Hälfte — ein Word-Dokument in den Editor zu bringen, ohne dabei Struktur zu verlieren — ist diese Woche gelandet.

Dieser Beitrag ist das Pendant zur Export-Neufassung: dasselbe Datenmodell, entgegengesetzte Richtung, dasselbe Beharren darauf, nichts zu verlieren, was die Nutzerin oder der Nutzer auf dem Bildschirm sehen kann.

Der Vertrag

Jemand lädt eine contract_v3.docx hoch, die in Word bearbeitet wurde. Nach dem Import sollte das Öffnen desselben Dokuments im Editor Folgendes zeigen:

Überschriften, Absätze, Listen, Tabellen — auf der richtigen Ebene, in der richtigen Reihenfolge.
Inline-Formatierung — fett, kursiv, unterstrichen, durchgestrichen, tief-/hochgestellt.
Farben und Hervorhebungen — die tatsächlichen Farben aus der Editor-Palette, nicht irgendein Word-Standard-Ersatz.
Schriftarten und -größen — abgebildet auf die zwölf Tokens des Editors (Inter, Playfair Display, Roboto Mono usw.).
Ausrichtung, Einrückung, Zeilenabstand.
Hyperlinks — anklickbar, mit ihren ursprünglichen URLs.
Seitenumbrüche dort, wo die verfassende Person sie gesetzt hat.
Die Kopf- und Fußzeile der Seite, mit ihrer jeweils eigenen Formatierung.

Zurück nach DOCX exportiert, sollte dieselbe Datei in ihrer Struktur byte-vergleichbar sein (nicht bit-identisch — Word schreibt jede Menge beiläufiges XML — aber für eine Leserin oder einen Leser visuell ununterscheidbar).

Warum das Parsen von DOCX nicht so freundlich ist wie das Parsen von HTML

DOCX ist ein ZIP, das XML enthält. Das Schema ist OOXML (ECMA-376), und python-docx packt es in ein hübsches Absatz-/Run-Objektmodell. Das Problem ist, dass das meiste von dem, was ein echtes Word-Dokument interessant macht, außerhalb dieses freundlichen Objektmodells lebt:

Seitenumbrüche sind <w:br w:type="page"/>-Elemente, die in Runs eingebettet sind. Sie tauchen zwar in paragraph.runs auf, aber als Nebeneffekt schleicht sich ein \n in den Run-Text ein — zähle es einmal mit und du hast einen überzähligen Zeilenumbruch.
Hyperlinks leben in <w:hyperlink>-Elementen, die Geschwister von <w:r>-Elementen innerhalb des Absatzes sind. paragraph.runs überspringt sie komplett — iterierst du nur über Runs, verschwindet der Linktext (oder bleibt, aber die URL geht verloren).
Abschnittseigenschaften (Seitengröße, Kopfzeilen, Fußzeilen) hängen an sections[*].header / .footer mit kaskadierenden Vererbungs-Flags (is_linked_to_previous), die die freundliche API stillschweigend auflöst.
Der Zeilenabstand ist ein Float-Multiplikator auf paragraph_format.line_spacing; ihn wieder auf die diskreten Tokens des Editors (tight / normal / relaxed / loose / double) abzubilden, erfordert einen Snap-auf-den-nächsten-Wert-Durchlauf.

Wenn dein DOCX-Import nur paragraph.runs nutzt, verliert dein Dokument klammheimlich jeden Hyperlink und jeden Seitenumbruch, sobald es deine Pipeline berührt. Beide kommen als Klartext durch den Round-Trip oder verschwinden ganz. Wir sind beim ersten Integrationslauf in beide Bugs gelaufen.

Die Struktur: import_docx_bytes gibt sechs Schlüssel zurück

Vor dieser Arbeit gab unser Import-Pfad ein 2-Tupel (markdown_body, formatting_array) zurück — Body-Inhalt plus die Stand-off-Formatierungs-Offsets. Das war in Ordnung für Body-only-Dokumente, verlor aber jede verfasste Kopf-/Fußzeile.

Wir haben den Rückgabetyp in ein Dict mit sechs Schlüsseln geändert, das das Speichermodell des Editors widerspiegelt:

{
  "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": [],
}

Jedes *_md verwendet seinen eigenen, bei null beginnenden Indexraum; Kopf-/Fußzeilen-Offsets teilen sich keinen mit dem Body. Die drei Walks teilen sich einen Helfer (walk_container), der md_parts, formatting und den Cursor beim Eintritt zurücksetzt, damit sie keine Offsets ineinander überlaufen lassen.

Wir nehmen nur sections[0] (der Editor erzwingt eine Kopf-/eine Fußzeile pro Dokument) und respektieren is_linked_to_previous — wenn ein Abschnitt von einem vorherigen erbt (der Standard für sections[0]), hat er keine verfasste Kopf-/Fußzeile und wir steuern leere Strings bei. Der gesamte Kopf-/Fußzeilen-Block ist in try / except gewickelt, sodass ein fehlerhaftes sectPr zu „keine Kopf-/Fußzeile“ degradiert, statt den gesamten Import scheitern zu lassen.

Seitenumbrüche: durch das rohe XML laufen

python-docx stellt den Text eines Runs als run.text bereit — eine Verkettung seiner <w:t>-Kinder, wobei <w:br> zu \n kollabiert wird. Das liefert uns Text, verliert aber die Unterscheidung zwischen einem weichen Umbruch und einem harten Seitenumbruch.

Lösung: Lauf bei jedem Absatz über paragraph._element.iter(qn("w:br")) und prüfe das w:type-Attribut jedes Umbruchs. Wenn w:type == "page", gib unseren [PAGE BREAK]\n\n-Marker vor dem Absatzinhalt aus, sodass ein Seitenumbruch-vor-Überschrift in Word als [PAGE BREAK]\n\n# Heading in unserem Markdown überlebt. Enthält der Absatz nichts außer dem Umbruch, überspringe den leeren abschließenden Block, um überzählige doppelte Zeilenumbrüche zu vermeiden, und entferne das vom Seitenumbruch verursachte \n aus dem Run-Text, damit der Marker nicht doppelt gezählt wird.

Hyperlinks: über die XML-Kinder des Absatzes direkt iterieren

Bei Hyperlinks besteht der Trick darin, paragraph.runs komplett aufzugeben und über die XML-Kinder des Absatzes zu iterieren, mit Dispatch nach Tag:

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

emit_hyperlink löst r:id gegen die Beziehungstabelle des Absatzes auf, um die externe URL zu erhalten, mit einem Fallback auf #anchor für interne Hyperlinks (TOC-Einträge, die auf Überschriften-Lesezeichen zeigen), sodass die Struktur selbst dann überlebt, wenn wir das Lesezeichen nicht auflösen können. Wir geben natives Markdown [text](url) aus — der bestehende Markdown-Link-Pfad des Renderers erzeugt ein echtes <a href> ohne einen separaten Nachlauf.

Internes Styling innerhalb des Hyperlinks (fetter Linktext, farbiger Linktext) durchläuft dieselbe emit_run-Pipeline wie einfache Runs, sodass ein fetter blauer Link auch im Editor ein fetter blauer Link bleibt.

Zeilenabstand: Snap auf den nächsten Wert, in beide Richtungen

Der Editor akzeptiert keine beliebigen Zeilenabstands-Floats — er hat fünf Tokens (tight / normal / relaxed / loose / double), die auf 1.2 / 1.6 / 2.0 / 2.5 / 3.0 abbilden. Vom Editor nach DOCX ist die Abbildung direkt. Der Rückweg ist unschärfer: Ein Word-Dokument, das mit 1,5-fachem Zeilenabstand verfasst wurde (typisch für Fließtext), sollte zu linespacing-normal zurückkommen, nicht abgelehnt werden.

Die Implementierung ist die Umkehrung des export-seitigen _nearest_size_token: ein Snap-auf-den-nächsten-Wert-Durchlauf gegen dieselben fünf Referenzwerte. Das Ergebnis wird als absatz-ebenes {: .linespacing-X }-Block-Attribut neben Ausrichtung und Einrückung ausgegeben.

Der Round-Trip-Test

Zwei-Wege-Konvertierungen lassen sich leicht kaputtmachen und schwer entdecken. Wir haben backend/tests/manual_docx_roundtrip.py hinzugefügt — ein manuelles Audit-Skript (im Geiste der anderen manual_*.py-Audits), das Folgendes tut:

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)

Es ist kein pytest-Test — es läuft gegen den Live-Backend-Container und inspiziert das tatsächliche OOXML-XML der beiden generierten docx-Dateien. Die Ausgabe sind menschenlesbare Diffs dessen, was sich über die beiden Durchläufe geändert hat. Wir fügen jedes Mal eine neue Assertion hinzu, wenn eine Regression entdeckt wird, sodass beim nächsten Auftreten desselben Edge Case das Audit laut scheitert, statt in einem komplexen Dokument stillschweigend verloren zu gehen.

Was noch unvollkommen ist

Mehrere Abschnitte. Ein Dokument mit Abschnittsumbrüchen (unterschiedliche Kopfzeilen in Kapitel 1 vs. Kapitel 2) wird auf das Chrome des ersten Abschnitts plattgedrückt. Das Datenmodell des Editors unterstützt nur eine Kopf-/eine Fußzeile pro Dokument, und das zu ändern, ist eine viel größere Operation als der Import-Pfad allein.
Kommentare und Änderungsverfolgung. Beide sind im OOXML vorhanden, aber wir lassen sie heute unter den Tisch fallen. Der Editor hat für keines von beiden eine UI, also würde sie zu importieren ohnehin nur bedeuten, sie beim nächsten Speichern zu verwerfen.
Bilder. Wir extrahieren zwar Bildreferenzen, aber nur als neu verlinkte Platzhalter. Die tatsächlichen Bild-Bytes aus dem DOCX-Media-Ordner herauszuziehen, sie zu persistieren und die Bildreferenz im Markdown umzuschreiben, ist der nächste Durchlauf.
Benutzerdefinierte Stile. Ein Dokument, das einen benutzerdefinierten Word-Stil („Body Indented Quote“) verwendet, der nicht zu den bekannten Stilen des Editors gehört, bekommt die nächstbeste Entsprechung aus unserer Stiltabelle. Ein verbindlicher Round-Trip beliebiger benutzerdefinierter Stile würde erfordern, ihre Definitionen durch das Datenmodell des Editors mitzuführen, was wir nicht tun.

Was sich dadurch für Nutzerinnen und Nutzer ändert

Der zentrale Workflow ist jetzt symmetrisch. Du kannst:

Ein bestehendes Word-Dokument nehmen — einen Briefentwurf, eine wissenschaftliche Arbeit, einen Vertrag.
Es zu AgentDoc hochladen (ein einziger Klick auf den Button „.docx importieren“ in der Seitenleiste, oder ein einziges POST /api/docs/import/docx für autonome Agents — siehe die Agent-Dokumentation).
Es per Sprache oder per Chat bearbeiten, wobei der Agent strukturierte Bearbeitungen vornimmt, während das Seitenlayout genau so bleibt, wie du es verfasst hast.
Zurück nach Word exportieren, und deine Mitarbeiterin oder dein Mitarbeiter öffnet die Datei in demselben Word, mit dem sie oder er begonnen hat — mit denselben Schriftarten, denselben Farben, derselben Seitengeometrie.

Speziell für den Agent-seitigen Workflow schließt das auch die Lücke, in der ein autonomer MCP-Client Dokumente nur von Grund auf neu bauen konnte. Mit verdrahtetem import_docx_bytes kann ein Agent eine vorlagenbasierte DOCX aufnehmen (z. B. einen Firmenbriefkopf mit vorausgefüllten Feldern), Bearbeitungen über die MCP-Tool-Oberfläche steuern und das Ergebnis exportieren — genau die Art von „Fülle dieses Formular aus“-Anwendungsfall, bei dem das Neutippen von Grund auf der Flaschenhals ist.

Passende Lektüre

PDF- + DOCX-Export neu gebaut — das Spiegelbild dieses Beitrags auf dem Weg aus dem Editor heraus.
Tool-Granularität bei LLM-Agents — das Tool-Design-Framework, das die MCP-Oberfläche antreibt, die autonome Agents gegen importierte Dokumente nutzen.

← PDF- + DOCX-Export neu gebaut Alle Beiträge →