KaguraNanaga/format-agent-skill

Formatierungsskill für Agenten

Formatieren Sie Word-Dokumente (.docx) automatisch nach vorgegebenem Schema. Verstehen übernimmt die KI, die Formatierung der Code, dazwischen JSON als Schnittstelle.

Funktionsumfang

• Unterstützt zwei Formatierungsquellen: Klartext-Beschreibung (.txt) oder korrekt formatierte Word-Vorlage (.docx)
• Jedes korrekt formatierte Dokument kann als Vorlage dienen: Sitzungsunterlagen von Partei-/Aktionärsvorständen, Verträge, Gutachten, Berichte, wissenschaftliche Arbeiten, Pressemitteilungen ... Der Agent liest Schriftart, Schriftgröße, Zeilenabstand, Einzüge und Nummerierung und wendet sie auf das Zieldokument an.
• Unterstützt unstrukturierte Dokumente (der KI-Agent bestimmt Absatzrollen semantisch) und strukturierte Dokumente (manuelle oder automatische Nummerierung wie 1., (1), a), I., §1 usw.)
• Seitenebene: Seitenränder, Zeilenraster, Kopf- und Fußzeilen (mit Seitenzahlen)
• Absatzebene: Schriftart, Schriftgröße, Fettdruck, Ausrichtung, Zeilenabstand, Erste-Zeile-Einzug, Nummerierungsstil
• Tabellenebene: Kopfzeile (Fett, zentriert), Zellen-Schriftart/-größe/-ausrichtung, Rahmen
• Nicht in der Vorlage definierte Rollen werden automatisch mit dem Fließtext vereinheitlicht
• Keine Änderungen am Textinhalt: Nach jeder Formatierung wird automatisch eine Textkonsistenzprüfung durchgeführt (Absatz für Absatz zwischen Original und Endfassung). Jede Textänderung wird klar gemeldet.
• Inhaltsverzeichnis: Automatische Erstellung, wenn die Vorlage ein Inhaltsverzeichnisfeld enthält (nach Öffnen in Word aktualisieren); Mehrspaltige Layouts werden unterstützt (z. B. für hochschulische Arbeiten)
• Aktuelle Version formatiert nicht um: Deckblatt-Layout, komplexe Zellenverbünde in Tabellen bleiben unverändert

Systemvoraussetzungen

• Python 3.10+, Abhängigkeiten: pip install -r requirements.txt (python-docx, requests, PyMuPDF; unter Windows wird zusätzlich pywin32 benötigt)
• Im Agent-Setup ist kein Modell erforderlich: Die Analyse übernimmt der Host-Agent (siehe "Verwendung 1")
• Nur im eigenständigen API-Modus (ohne Agent) wird ein Modell benötigt: Umgebungsvariablen/.env-Datei: LLM_BASE_URL, LLM_API_KEY, LLM_MODEL (optional LLM_VISION_MODEL, LLM_TIMEOUT, LLM_TEMPERATURE)

Modellauswahl (Wichtig: Multi-Modell-Modus empfohlen)

Dieser Skill ist nicht an ein bestimmtes Modell gebunden. Jeder OpenAI-kompatible Endpunkt funktioniert. Es wird jedoch ein Multi-Modell-Modell (Text + Bild) empfohlen (z. B. GPT-4o, Kimi K3, Qwen-VL, GLM-4V):

• Kernablauf der Formatierung (Regel-Extraktion, Rollen-Mapping) benötigt nur Textfähigkeiten
• Visuelle Qualitätskontrolle (--verify) muss das gerenderte Bild an das Modell übergeben; reine Textmodelle können diesen Schritt nicht nutzen

Hinweis für den aufrufenden Agenten: Vor Beginn prüfen, welches Modell verwendet wird und ob es Multi-Modell-Fähigkeiten (Bildeingabe) unterstützt. Falls nicht, den Benutzer aktiv informieren: "Das aktuelle Modell unterstützt keine Bildeingabe, die visuelle Qualitätskontrolle ist nicht verfügbar. Es wird empfohlen, auf ein Multi-Modell-Modell (z. B. XXX) zu wechseln, um die automatische Qualitätsprüfung nach der Formatierung zu ermöglichen.” Nach Bestätigung fortfahren.

Verwendung

Dieser Skill kann auf zwei Arten verwendet werden. Im Agent-Setup bevorzugt den integrierten intelligenten Modus – null Konfiguration, kein API-Key, die Analyse übernimmt der Host-Agent selbst.

Verwendung 1: Agent-integrierter intelligenter Modus (Standard, empfohlen)

Ablauf, wenn Sie der Host-Agent sind:

1. Dokumentstruktur extrahieren:

   python main.py --extract-only --target zu_formatieren.docx --out Ausgabe/fertig.docx
   

   Ergebnis: Ausgabe/fertig_paragraphs.json mit jedem Absatz, der idx/text/size_pt/bold/alignment/style_name/in_table sowie Nummerierungs-Metadaten enthält.

2. Sie selbst erstellen das FormatSpec (Formatierungsregeln-JSON):

   • Enthält der Benutzer eine Klartext-Beschreibung: Lesen Sie diese, schreiben Sie das JSON nach dem folgenden Schema und speichern Sie es als Ausgabe/fertig_formatspec.json.
   • Enthält der Benutzer eine .docx-Vorlage: Extrahieren Sie zunächst die Vorlage mit --extract-only, lesen Sie die Rollen der Absätze (Titel, Fließtext, Unterschrift ...) und schreiben Sie Vorlage_rolemap.json (Format {"0": "title", "1": "body", ...}). Anschließend verwenden Sie --template Vorlage.docx --template-rolemap-json Vorlage_rolemap.json, damit der Code die Formatierung der Vorlage deterministisch liest.

   FormatSpec-Schema:

   {
     "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}}
     }
   }
   

   Rollen-Enumeration: title/subtitle/heading_1/heading_2/heading_3/body/signature/date/attachment_label/attachment/other. body ist Pflicht; Ausrichtung: left/center/right/justify; size_pt 872, Seitenränder 550 mm. Nicht erwähnte Rollen und Felder weglassen.

3. Sie selbst erstellen das RoleMap (Absatzrollen-JSON): Lesen Sie die Absatzliste aus Schritt 1, weisen Sie jedem Absatz mit in_table=false eine Rolle aus der Enumeration zu und speichern Sie als Ausgabe/fertig_rolemap.json im Format {"0": "title", "1": "body", ...}. Alle Absätze außerhalb von Tabellen müssen erfasst werden. Kriterien: Textinhalt, Position, aktuelle Formatierung; Unterschrift am Ende, Datum enthält Tag/Monat/Jahr, Titel am Anfang und eigenständig.

4. Formatierung ausführen (deterministischer Code übernimmt):

   # Klartext-Beschreibung als Quelle (FormatSpec von Ihnen in Schritt 2 erstellt)
   python main.py --spec-json Ausgabe/fertig_formatspec.json \
       --rolemap-json Ausgabe/fertig_rolemap.json \
       --target zu_formatieren.docx --out Ausgabe/fertig.docx
   
   # Vorlage als Quelle
   python main.py --template Vorlage.docx --template-rolemap-json Vorlage_rolemap.json \
       --rolemap-json Ausgabe/fertig_rolemap.json \
       --target zu_formatieren.docx --out Ausgabe/fertig.docx
   

   Das von Ihnen erstellte JSON wird vom Code erneut überprüft (Rollen legal, Abdeckung aller Absätze, Wertebereich). Bei Fehlern wird ein Fehler gemeldet und die Ursache erläutert. Nach Korrektur erneut ausführen.

Verwendung 2: Eigenständiger API-Modus (optional)

Nur in Umgebungen ohne Agent (Server, geplante Tasks, lokale Ausführung) ist ein Modell erforderlich: Kopieren Sie .env.example zu .env und füllen Sie LLM_BASE_URL, LLM_API_KEY, LLM_MODEL (empfohlen Multi-Modell, siehe oben). Anschließend:

# Klartext-Beschreibung als Formatierungsquelle (LLM extrahiert Regeln automatisch)
python main.py --spec formatierungsregeln.txt --target zu_formatieren.docx --out Ausgabe/fertig.docx

# Word-Vorlage als Formatierungsquelle
python main.py --template Vorlage.docx --target zu_formatieren.docx --out Ausgabe/fertig.docx

Die Vorlage kann jedes korrekt formatierte Dokument sein (Sitzungsunterlagen, Vertragsmuster, Gutachten, Berichte, Beispiel-Arbeit ...). Es sind keine Anpassungen oder Markierungen erforderlich.

Visuelle Qualitätskontrolle (optional, nur für Verwendung 2 + Multi-Modell)

Fügen Sie --verify hinzu: Nach der Formatierung wird das Dokument gerendert, das visuelle Modell überprüft es anhand der Vorgaben und korrigiert Abweichungen gezielt (nur ein Durchgang, keine offene Schleife). In Verwendung 1 können Sie als Host-Agent mit Bildverständnis selbst rendern und prüfen: Das Ausgabeverzeichnis *_verify_render/ enthält die einzelnen Seiten als PNG.

Ausgabe

Pro Lauf entstehen (gleiches Verzeichnis, gleicher Präfix):

• fertig.docx – saubere Datei mit zugewiesenen Formatvorlagen
• fertig_tracked.docx – Änderungsmodus: Jede Formatierungsänderung in Word sichtbar, einzeln akzeptierbar/ablehnbar
• fertig_report.docx / .md – Änderungsbericht (Seiteneinrichtung, Regeln, Absatzdetails)
• fertig_formatspec.json / _rolemap.json / _stylemap.json – Zwischenergebnisse (für Prüfung als "Verständnisbelege")

Fehlerbehebung

• Fehlende LLM-Konfiguration → Überprüfen Sie .env oder Umgebungsvariablen
• Rollen-Mapping wiederholt fehlgeschlagen → Instabiles Modell-JSON; wechseln Sie zu --rolemap-json für manuelle Angabe
• Visuelle Überprüfung 400 temperature → Das Modell akzeptiert nur temperature=1. Setzen Sie LLM_TEMPERATURE=1 in .env
• Visuelle Überprüfung meldet Bildfehler → Endpunkt unterstützt keine data:base64-Bilder oder das Modell hat keine Bildeingabe; wechseln Sie zu einem Multi-Modell-Modell
• Rendering fehlgeschlagen → Unter Windows Word erforderlich (COM), unter macOS/Linux LibreOffice

Verzeichnis examples/

• messy.docx: Beispiel-Dokument (Benachrichtigung) mit unordentlicher Formatierung
• spec.txt: Beispiel für Formatierungsregeln in Klartext
• spec_std.json / rolemap_std.json: Musterlösungen für die obigen Beispiele (Prüfstandard + Fallback-Eingabe)
• Vorlage-Muster-Sitzungsunterlagen.docx: Beispiel für die Formatierungsquelle im Vorlagenmodus