c0sogi/write-korean-meeting-minutes-hwpx

HWPX-Erstellung koreanischer Sitzungsprotokolle

Erstellt ein offizielles koreanisches Sitzungsprotokoll auf der Grundlage von Audio-/Videoaufnahmen oder Transkripten und liefert es als gültige .hwpx-Datei. Falls kein Transkript vorliegt, wird zunächst mit meetdown ein Markdown-Transkript erstellt. Der aktuelle Umfang umfasst die HWPX-Erstellung, nicht die PDF-Konvertierung.

Ausführungsumgebung

• Verwendet Dateisystem- und Shell-Ausführungsberechtigungen.
• Für Python-Befehle und Paketausführung werden uv und uvx verwendet. Das Transkriptionstool meetdown==0.2.1 erfordert Python 3.12 oder höher.
• Für die Audiotranskription ist eine Netzwerkverbindung und Authentifizierung für CLOVA Speech, OpenAI oder Gemini erforderlich.
• Für die HWPX-Erstellung wird eine gebündelte Vorlage und ein Skript verwendet, das auf der Python-Standardbibliothek basiert.

Zwingend einzuhaltende Prinzipien

• Datum, Uhrzeit, Ort, Teilnehmer, Sprecher echte Namen, Verantwortliche, Fristen, Entscheidungen, Zahlen und Eigennamen werden nicht spekuliert.
• Das Created at von meetdown ist der Zeitpunkt der Transkripterstellung, nicht das Sitzungsdatum.
• Bezeichnungen wie A, B, [[SPEAKER_1]] sind keine echten Namen. Sie werden nur durch Namen ersetzt, wenn eine Sprecherzuordnung vom Benutzer vorliegt.
• Vorschlag, Bedenken, Entscheidung, Folgemaßnahme und offene Punkte werden unterschieden.
• Mehrfach genannte Ideen werden nicht automatisch zu Entscheidungen erhoben.
• Weichen anfängliche Meinungen von der expliziten Einigung am Ende der Sitzung ab, hat die letztendliche Einigung oder Anweisung Vorrang.
• Äußerungen, die auf den Bildschirm verweisen (z. B. „hier“, „dieses Bild“, „diese Seite“), werden ohne Referenzmaterial nicht konkretisiert.
• API-Schlüssel werden nicht in Befehlsargumenten, Protokollen, Markdown, JSON, HWPX oder der endgültigen Antwort offengelegt.
• Dokumenttitel sowie Abschnitts- und Unterabschnittsüberschriften werden fett dargestellt.
• Nur kurze Passagen wichtiger Entscheidungen, Schlussfolgerungen oder Folgemaßnahmen werden in Blau (#2F5597) und fett hervorgehoben. Der Großteil des Textes wird nicht blau eingefärbt.

Enthaltene Referenzen

Es werden nur die relevanten Referenzen gelesen.

• references/meetdown-guide.md: Wird gelesen, wenn kein Transkript vorliegt oder die meetdown-Ausführung fehlschlägt.
• references/minutes-writing.md: Wird vor der Umstrukturierung des Transkripts in ein Protokoll gelesen.
• references/hwpx-template.md: Wird gelesen, wenn die HWPX-Vorlage erstellt, ersetzt oder geändert wird.
• references/installation.md: Wird gelesen, wenn Installationsort oder Betreibereinstellungen erläutert werden.
• references/evaluation.md: Wird gelesen, wenn nach einer Skill-Änderung Regressionstests entworfen werden.
• assets/minutes.schema.json: Referenz für die Struktur von minutes.json.
• assets/example-minutes.json: Dient nur als Beispiel für die Datenstruktur, nicht als Textvorlage.
• assets/example-audit.json: Beispiel für das Audit-Log-Format.
• assets/meeting-minutes-template.hwpx: Standardprotokollvorlage.

Zu verwendende Skripte

Alle Pfade sind relativ zum Skill-Root-Verzeichnis.

• scripts/transcribe.py: Führt meetdown nicht-interaktiv aus und schützt Geheimnisse.
• scripts/inspect_transcript.py: Überprüft die Struktur und Risikofaktoren des meetdown-Markdowns.
• scripts/validate_minutes.py: Validiert minutes.json vor der HWPX-Erstellung.
• scripts/render_hwpx.py: Setzt strukturierte Inhalte in die HWPX-Vorlage um.
• scripts/validate_hwpx.py: Überprüft ZIP, XML, erforderliche Phrasen, Fettdruck und blaue Hervorhebung.
• scripts/validate_skill.py: Überprüft die Kernregeln für Agent Skills.
• scripts/self_test.py: Führt den gesamten lokalen Ablauf ohne Netzwerk durch.

Arbeitsablauf

Fortschrittsstatus:

• 1. Eingabedateien und Referenzmaterialien klassifizieren.
• 2. Transkribieren mit meetdown, falls kein Transkript vorliegt.
• 3. Transkriptstruktur und -qualität überprüfen.
• 4. Audit-Log erstellen.
• 5. minutes.json erstellen und validieren.
• 6. HWPX generieren.
• 7. HWPX validieren und Fehler korrigieren.
• 8. Ergebnisse und zu überprüfende Punkte melden.

1. Eingabedaten klassifizieren

Die folgende Priorität wird angewendet.

1. Vom Benutzer bestätigte Sitzungsmetadaten, Sprecherzuordnung, Terminologie und Korrekturen
2. Referenzmaterialien aus der tatsächlichen Sitzung: Tagesordnung, Präsentationsfolien, RFPs, Teilnehmerlisten usw.
3. Gültiges Transkript mit Zeitstempeln und Sprechern
4. Vollständiges Transkript ohne Zeitstempel
5. Datumshinweise im Dateinamen nur, wenn das Format angegeben ist

Verarbeitung nach Eingabetyp:

• Liegt ein gültiges Transkript-Markdown vor, wird es direkt verwendet. Die gleiche Aufnahme wird nicht erneut transkribiert.
• Liegen nur Audio-/Videoaufnahmen vor, wird vor der Protokollerstellung transkribiert.
• Liegen sowohl Transkript als auch Aufnahme vor, hat das Transkript Vorrang. Nur wenn das Transkript leer, beschädigt oder von einer anderen Sitzung ist, wird erneut transkribiert.
• Mehrere Aufnahmen werden einzeln transkribiert. Nur wenn bestätigt ist, dass es sich um fortlaufende Aufnahmen derselben Sitzung handelt, werden sie unter Beibehaltung der Dateireihenfolge zusammengeführt.
• Liegen weder Aufnahme noch Transkript vor, wird nur dann ein Entwurfsprotokoll erstellt, wenn ausreichende Sitzungsnotizen vorhanden sind. Bei unzureichender Grundlage wird der Sitzungsinhalt nicht erfunden.

2. Transkription bei Bedarf

Vor der Transkription references/meetdown-guide.md lesen.

Standardausführung für koreanische Sitzungen und CLOVA Speech:

uv run scripts/transcribe.py "<Aufnahmedatei>" \
  -o "<Transkript.md>" \
  --provider clova \
  --language ko-KR

Nur wenn der einmalige Upload einer langen Datei fehlschlägt oder eindeutige Provider-Beschränkungen vorliegen, mit den folgenden Optionen erneut versuchen.

--chunk-duration 10m

Standardkomprimierung ist smallest. Nur wenn es Anhaltspunkte gibt, dass die Transkriptionsqualität durch die Komprimierung leidet, wird mit lossless wiederholt. Bei Sitzungen mit mehreren Teilnehmern wird die Sprechertrennung beibehalten, sofern kein besonderer Grund dagegen spricht.

Nach der Transkription muss geprüft werden.

uv run scripts/inspect_transcript.py "<Transkript.md>" \
  -o "<Transkript.inspect.json>"

Protokolle werden nicht erstellt aus: leeren Dateien, HTML-Fehlerseiten, Dateien ohne verwendbares vollständiges Transkript oder ohne Zeitstempelabschnitte.

3. Metadaten bereinigen

Falls bestätigt, werden die folgenden Werte erfasst.

• Tagesordnung
• Datum/Uhrzeit
• Verantwortliche Organisation
• Ort
• Teilnehmerzahl
• Haupttagesordnungspunkte
• Sprecherzuordnung
• Bestätigte Schreibweise von Personen-, Organisations-, Projekt-, Produktnamen und technischen Begriffen

Fehlende, weniger wichtige Metadaten unterbrechen die Arbeit nicht. Ein Entwurfsprotokoll wird erstellt, in die entsprechende Zelle wird Prüfung erforderlich eingetragen, und der Mangel wird in quality.missing_metadata vermerkt. Nur Informationen, die für ein vollständiges endgültiges Protokoll zwingend erforderlich sind und das Ergebnis wesentlich beeinflussen, werden zusätzlich überprüft.

4. Audit-Log erstellen

Vor dem Verfassen des endgültigen Texts wird minutes.audit.json erstellt. Für jeden wichtigen Inhalt wird das folgende Format verwendet.

{
  "type": "fact | proposal | concern | decision | action | open_question",
  "statement": "Normalisierte kurze Aussage",
  "source": "Dateiname des Transkripts oder Referenzmaterials",
  "speaker": "A oder bestätigter echter Name",
  "start": "00:42:02",
  "end": "00:42:10",
  "confidence": "high | medium | low"
}

Klassifizierungskriterien:

• fact: In der Sitzung bestätigte oder erläuterte Tatsache
• proposal: Vorschlag, Idee, Option
• concern: Einwand, Risiko, Einschränkung
• decision: Explizite Zustimmung, Wahl, Bestätigung, Genehmigung, Anweisung
• action: Konkrete, zu erledigende Aufgabe
• open_question: Noch nicht abgeschlossene Angelegenheit

Folgemassnahmen müssen einen konkreten Auftrag enthalten. Verantwortlicher und Frist werden nur eingetragen, wenn eine Grundlage dafür vorliegt.

5. Protokolldaten erstellen

references/minutes-writing.md und assets/minutes.schema.json folgen. assets/example-minutes.json dient nur als Referenz für die Struktur, der Inhalt wird nicht kopiert.

Erforderliche Dokumentstruktur:

• PROTOKOLL
• Obere Metadatentabelle
• SITZUNGSINHALT
  • Zusammenfassung der Sitzung
  • 2. Hauptdiskussion
  • 2.1 bis 2.n thematische Diskussionen, in der Regel 3–7
• SITZUNGSERGEBNIS
  • [Zusammenfassung]
  • [Folgemassnahmen]
  • [Zu Überprüfende Punkte] nur bei Bedarf

Der Stil ist prägnant und neutral im koreanischen Geschäftsstil. Standardendungen sind -함, -하기로 함, -논의됨, -필요함, -판단됨. Füllwörter, Stottern, Wiederholungen und irrelevantes Geplauder werden entfernt, aber Einwände, technische Einschränkungen, Kosten und Zeitpläne, die Grundlage einer Entscheidung sind, bleiben erhalten.

Blau hervorzuhebende Phrasen werden als exakte, kurze Zeichenfolgen in das emphasis-Array aufgenommen. Wichtige Elemente werden mit important: true markiert.

Validierung:

uv run scripts/validate_minutes.py "<minutes.json>"

Alle Fehler werden korrigiert. Auch Warnungen zu fehlenden Metadaten, nicht im Text vorkommenden Hervorhebungen, übermäßigem Hervorhebungsanteil und zu langen Absätzen werden überprüft.

6. HWPX generieren

Wenn der Benutzer keine kompatible Vorlage bereitstellt, wird die Standardvorlage verwendet.

uv run scripts/render_hwpx.py \
  --template assets/meeting-minutes-template.hwpx \
  --data "<minutes.json>" \
  --output "<FinalesProtokoll.hwpx>"

Der Renderer behält die Tabellenstruktur und bestehenden Absatzstile bei, setzt Überschriften und Unterüberschriften fett und stellt die angegebenen Kernphrasen in #2F5597 und fett dar. Bei langem Inhalt wird die Schriftgröße nicht übermäßig verkleinert, sondern der Inhalt läuft natürlich auf die nächste Seite über.

Stellt der Benutzer eine deutlich abweichende HWPX-Vorlage bereit, wird nicht blind ausgeführt. Gemäß references/hwpx-template.md werden zunächst die Tabellenzellenadressen und die Absatzstruktur überprüft und der Renderer angepasst.

7. HWPX validieren

uv run scripts/validate_hwpx.py "<FinalesProtokoll.hwpx>" \
  --expect-data "<minutes.json>"

Bei fehlgeschlagener Validierung werden JSON oder Vorlage korrigiert und neu generiert. Dateien in den folgenden Zuständen werden nicht ausgeliefert.

• mimetype ist nicht der erste ZIP-Eintrag oder ist komprimiert
• Erforderliches XML fehlt oder kann nicht geparst werden
• Erwarteter Text fehlt
• Dokumenttitel oder Abschnittsüberschriften sind nicht fett
• Hervorhebung angefordert, aber kein blauer, fetter Stil vorhanden
• Unvollständige Platzhalter sind vorhanden

Wenn Hancom Office verfügbar ist, wird die Datei direkt geöffnet, um Tabellenrahmen, Schriftartersatz, Seitenumbrüche, abgeschnittene Sätze und den letzten Absatz zu überprüfen. Wurde die Datei nicht tatsächlich geöffnet, wird nicht behauptet, dass eine Sichtprüfung abgeschlossen ist.

8. Ergebnisse und Bericht

Je nach Situation werden folgende Dateien erstellt.

• Bei Bedarf an Transkription: transcript.md
• transcript.inspect.json
• minutes.json
• minutes.audit.json
• Bei unbestätigten Punkten: minutes.review.md
• Endgültige .hwpx-Datei

Endgültiges Berichtsformat:

Abgeschlossen
- HWPX: <Pfad>
- Transkript: <Pfad oder „Vorhandenes Transkript verwendet“>
- Validierung: bestanden | Warnungen vorhanden
- Zu überprüfen: keine | Zusammenfassung der Kernpunkte

Fehlerbehandlung

• Fehlen Authentifizierungsinformationen, wird nur der Name der erforderlichen Umgebungsvariablen mitgeteilt. Der Benutzer wird nicht aufgefordert, das Geheimnis in den Chat einzugeben.
• Bei Größen- oder Zeitbeschränkungen wird mit --chunk-duration 10m wiederholt.
• Bei niedriger Transkriptionszuverlässigkeit werden Eigennamen und Zahlen nicht willkürlich korrigiert, sondern als Prüfpunkte vermerkt.
• Schlägt das HWPX-Rendering fehl, wird die Ursache gemeldet, und es wird keine beschädigte Datei als Ergebnis geliefert.
• Wird eine PDF-Ausgabe verlangt, wird mitgeteilt, dass dies außerhalb des aktuellen Skill-Umfangs liegt, und auf die Notwendigkeit einer separaten Konvertierungsumgebung hingewiesen.

Selbsttest

Nach der Skill-Installation oder nach Änderungen an Skripten/Vorlagen ausführen.

uv run scripts/self_test.py

Dieser Test ruft keine Spracherkennungs-API auf, sondern führt Transkript-Parsing, JSON-Validierung, HWPX-Erstellung und strukturelle Validierung durch.