V4TIME/V4SKILL

Docx-Fähigkeit (Docx Skill)

Erstellen, Lesen, Bearbeiten und Vorlagen für Microsoft Word .docx-Dateien mit python-docx über kleine CLIs. Sie behandelt Text, Stile, Listen, Tabellen, Bilder, Kopf-/Fußzeilen, {{token}}-Vorlagen, nachverfolgte Änderungen (anzeigen/akzeptieren/ablehnen), Kommentare (anzeigen/hinzufügen/löschen), Inhaltsverzeichnis- und Seitenzahl-Felder sowie Paket-Integritätsprüfungen. Sie rendert keine Dokumente selbst (PDF benötigt LibreOffice – siehe Umwandlung in PDF) und bearbeitet keine veralteten .doc-Dateien.

Wann verwenden

• Der Benutzer bittet um die Erstellung eines Word-Dokuments (Bericht, Brief, Vertrag).
• Sie benötigen den Text, die Gliederung, Stile oder eingebettete Bilder eines .docx.
• Sie müssen ein vorhandenes .docx ändern: Text ersetzen, Tabellenzellen bearbeiten, Absätze einfügen/löschen, Stile anwenden, fragmentierte Läufe (Runs) zusammenführen.
• Sie haben eine .docx-Vorlage mit {{Platzhaltern}}, die mit Daten gefüllt werden müssen.
• Das Dokument enthält nachverfolgte Änderungen, die geprüft, akzeptiert oder abgelehnt werden sollen.
• Sie müssen Kommentare von Prüfern lesen oder Kommentare hinzufügen/löschen.
• Eine .docx-Datei lässt sich nicht öffnen oder verhält sich seltsam, und Sie müssen eine Fehlerbehebung (Triage) durchführen.
• Das Dokument benötigt ein Inhaltsverzeichnis oder eine "Seite X von Y"-Fußzeile.
• Nicht geeignet für: .doc (alt), .odt oder WYSIWYG-Layout-Arbeiten.

Voraussetzungen

• Python 3.10+ mit installiertem python-docx: pip install python-docx (der Importname ist docx; lxml wird damit installiert).
• comments add verwendet die native API für python-docx >= 1.2 und einen XML-Fallback auf älteren Versionen – beides geschieht automatisch.
• Für Bildblöcke: Die Bilddateien müssen lokal vorhanden sein (PNG/JPEG).

Ausführung

Alle Helfer befinden sich im Verzeichnis scripts/ neben dieser Datei. Führen Sie sie mit dem terminal-Werkzeug aus; jedes unterstützt --help und gibt JSON auf stdout aus.

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

Kurzreferenz

Aufgabe	Befehl
Aus JSON-Spezifikation erstellen	docx_create.py spec.json out.docx
Volltext (Textkörper+Tabellen+Kopf-/Fußzeilen)	docx_read.py f.docx --text
Überschrift-Gliederung + Tabellenformen	docx_read.py f.docx --structure
Tatsächlich verwendete Stile	docx_read.py f.docx --styles
Eingebettete Bilder extrahieren	docx_read.py f.docx --images outdir/
Nachverfolgte Änderungen/Kommentare erkennen	docx_read.py f.docx --revisions
Suchen/Ersetzen (Formatierung bleibt erhalten)	docx_edit.py replace f.docx --find A --replace B -o out.docx
Tabellenzelle setzen	docx_edit.py set-cell f.docx --table 0 --row 1 --col 2 --text X
Absatz vor Index N einfügen	docx_edit.py insert f.docx --index N --text X --style Normal
Absatz N löschen	docx_edit.py delete f.docx --index N
Stil auf Absatz N anwenden	docx_edit.py style f.docx --index N --style "Heading 1"
Benachbarte Läufe mit gleicher Formatierung zusammenführen	docx_edit.py normalize f.docx -o out.docx
TOC-Feld vor Absatz N einfügen	docx_edit.py toc f.docx --index N -o out.docx
"Seite X von Y"-Fußzeilenfelder	docx_edit.py page-numbers f.docx
{{tokens}} füllen	docx_template.py tpl.docx values.json out.docx --strict
Änderungen auflisten (ID/Autor/Datum/Text)	docx_revisions.py list f.docx
Alle Änderungen akzeptieren / ablehnen	docx_revisions.py accept-all f.docx -o out.docx (oder reject-all)
Eine einzelne Änderung akzeptieren / ablehnen	docx_revisions.py accept f.docx --id 3 -o out.docx
Kommentare auflisten (+verankerter Text)	docx_comments.py list f.docx
Kommentar zu Text hinzufügen	docx_comments.py add f.docx --target "Satzteil" --text "Notiz" --author You
Kommentar nach ID löschen	docx_comments.py delete f.docx --id 0
Integritätsprüfung des Pakets	docx_validate.py f.docx (Exit-Code 1 bei Fehlern)

Vorgehensweise

1. Erstellen. Schreiben Sie eine JSON-Spezifikation mit write_file und führen Sie dann scripts/docx_create.py aus. Die Spezifikation unterstützt: page (Größe und Ränder in mm), header/footer-Zeichenketten, footer_page_numbers (fügt "Seite X von Y"-Fußzeilenfeld hinzu), styles (benutzerdefinierte Absatzstile mit Schriftart, Größe, fett/kursiv, hex color) und blocks – heading (Ebene 1-9), paragraph (entweder text oder eine runs-Liste, bei der jeder Lauf bold/italic/underline setzen kann), bullet_list, numbered_list, table (header-Zeile wird fett gerendert, rows, optionaler integrierter style wie Table Grid), image (path, optional width_mm), toc (Inhaltsverzeichnis-Feld) und page_break. Das vollständige Spezifikationsformat ist oben in scripts/docx_create.py dokumentiert.
2. Lesen. Verwenden Sie scripts/docx_read.py mit genau einem Modus-Flag. --text gibt Absätze des Textkörpers, allen Text aus Tabellenzellen sowie Kopf-/Fußzeilentext als JSON zurück. --structure gibt die Überschriften-Gliederung plus Anzahl der Absätze/Tabellen/Abschnitte zurück. --images DIR kopiert alle Dateien aus word/media/ aus dem Paket.
3. Bearbeiten. Verwenden Sie scripts/docx_edit.py. replace durchläuft Textkörper, Tabellen (auch verschachtelte), Kopf- und Fußzeilen und bewahrt die Lauf-Formatierung; fügen Sie --body-only hinzu, um Kopf-/Fußzeilen zu überspringen. Übergeben Sie -o out.docx, um das Original zu erhalten; lassen Sie es weg, um direkt zu bearbeiten. Absatzindizes für insert/delete/style/toc beziehen sich auf die --structure/--text-Reihenfolge des Textkörpers. Führen Sie zuerst normalize für Dokumente aus, die viel in Word bearbeitet wurden – es führt benachbarte Läufe mit identischer Formatierung zusammen, sodass spätere Suchen/Ersetzen zuverlässig funktionieren.
4. Änderungen prüfen. docx_revisions.py list meldet jedes w:ins und w:del (ID, Autor, Datum, betroffener Text) im Textkörper, in Tabellen, Kopf- oder Fußzeilen. accept-all / reject-all erledigt sie in einem Rutsch; accept/reject --id N behandelt eine einzelne Änderung. Akzeptieren behält Einfügungen und verwirft gelöschten Text; Ablehnen macht das Gegenteil.
5. Kommentare. docx_comments.py list gibt für jeden Kommentar ID, Autor, Datum, Text und den verankerten Dokumenttext zurück. add --target "ein Satzteil" verankert einen neuen Kommentar am ersten Vorkommen dieses Satzteils (Läufe werden bei Bedarf geteilt; Formatierung bleibt erhalten). delete --id N entfernt den Kommentar und seine Markierungen, ohne den Dokumenttext zu berühren.
6. Vorlage. Setzen Sie {{name}}-artige Platzhalter in das Dokument. Führen Sie scripts/docx_template.py mit einem JSON-Objekt der Werte aus. Verwenden Sie --strict, um einen Fehler zu melden, wenn Platzhalter unausgefüllt bleiben; die JSON-Ausgabe listet in jedem Fall filled-Anzahl und unfilled_tokens auf.
7. Überprüfen (immer): Lesen Sie die Ausgabe mit --text oder --structure erneut ein, und führen Sie docx_validate.py auf alles aus, das Sie durch Änderungs-/Kommentar-Operationen erstellt haben.

Umwandlung in PDF

Kein Skript erforderlich. Wenn LibreOffice installiert ist, konvertieren Sie ohne GUI:

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

Überprüfen Sie zuerst die Verfügbarkeit (command -v soffice || command -v libreoffice). Wenn keines existiert, teilen Sie dem Benutzer mit, dass die PDF-Konvertierung in dieser Umgebung nicht verfügbar ist, anstatt improvisieren – python-docx kann keine PDFs rendern, und Layout-Treue erfordert einen echten Renderer.

Fallstricke

• Platzhalter über Läufe hinweg aufgeteilt. Word fragmentiert Text oft in mehrere Läufe. Die Ersetzungshelfer lassen übereinstimmende Läufe kollabieren (die Ersetzung übernimmt die Formatierung des ersten Laufs); die vorherige Ausführung von docx_edit.py normalize reduziert die Fragmentierung für alle späteren Bearbeitungen.
• Abdeckung von Änderungen. docx_revisions.py löst lauf-basierte Einfügungen und Löschungen auf (die überwältigende Mehrheit). Absatzmarkierungs- und Tabellenzeilenänderungen, Formatierungsänderungen und Verschiebungen werden von --revisions erkannt, aber nicht automatisch aufgelöst – siehe references/revisions-and-comments.md und überlassen Sie diese Word.
• Kommentar-Threading. Antworten und der Status "erledigt" befinden sich in commentsExtended.xml, das diese Fähigkeit ignoriert; hinzugefügte Kommentare sind einfache Kommentare der obersten Ebene.
• Feldergebnisse werden von Word berechnet. toc, page-numbers und die toc/footer_page_numbers-Spezifikationsoptionen schreiben Feldcodes. Word/LibreOffice füllt die eigentlichen Einträge und Nummern, wenn die Datei geöffnet wird (Word fordert möglicherweise zum Aktualisieren der Felder auf); python-docx berechnet sie nie, daher wird bis dahin Platzhaltertext angezeigt.
• Validierung ist eine Gesundheitsprüfung, keine Schema-Validierung. docx_validate.py überprüft das ZIP, erforderliche Teile, Beziehungsziele, Bild-Magic-Bytes und referenzierte Stile. Es ist KEINE XSD-Validierung – eine Datei kann bestehen und trotzdem XML enthalten, das Word nicht mag.
• Stilnamen müssen existieren. Das Anwenden eines Stils, der nicht im Dokument definiert ist, löst eine KeyError-Ausnahme aus. Integrierte Stile wie Heading 1, List Bullet, List Number, Table Grid sind in der Standardvorlage vorhanden; benutzerdefinierte Stile müssen zuerst in der Erstellungsspezifikation deklariert werden.
• Nummerierte Listen setzen zurück. List Number verlässt sich auf die Standardnummerierung von Word; separate Listen in einem Dokument können die Nummerierung fortsetzen anstatt neu zu beginnen. Warnen Sie Benutzer, die eine präzise Nummerierung für mehrere Listen benötigen.
• Zellen-Schreibzugriffe ersetzen Formatierung. set-cell verwendet cell.text = ..., was die Läufe in dieser Zelle auf einfache Formatierung zurücksetzt.
• Kodierung. Alle JSON-Spezifikations-/Wertedateien werden explizit als UTF-8 gelesen; verlassen Sie sich nie auf lokale Standardeinstellungen, wenn Sie eigenen Klebecode schreiben.
• Nicht das XML entpacken und mit sed bearbeiten. Bearbeiten Sie über die Skripte (oder python-docx); rohe Textersetzung in document.xml beschädigt Dateien leicht. Verwenden Sie patch/write_file nur für die JSON-Eingaben, niemals für die .docx-Datei selbst.

Überprüfung

• Führen Sie nach dem Erstellen/Bearbeiten/Vorlagen docx_read.py out.docx --text aus und prüfen Sie, ob die erwarteten Zeichenketten erscheinen (und alte Zeichenketten verschwunden sind).
• Nach dem Akzeptieren/Ablehnen sollte docx_revisions.py list [] zurückgeben (oder nur die IDs, die Sie absichtlich übrig gelassen haben); nach Kommentar-Operationen sollte docx_comments.py list die Änderung widerspiegeln und die --text-Ausgabe muss unverändert sein.
• docx_validate.py out.docx beendet sich mit 0 und "ok": true bei einem gesunden Paket – führen Sie es nach jeder Änderungs-/Kommentar-/Feld-Manipulation aus.
• Für Vorlagen, die mit --strict ausgeführt wurden, oder prüfen Sie unfilled_tokens == [].
• Strukturprüfungen: --structure sollte die erwartete Überschriften-Gliederung und Tabellenformen anzeigen; --styles bestätigt angewendete benutzerdefinierte Stile.