c0sogi/meeting-minutes

Erstellung koreanischer Besprechungsprotokolle (HWPX)

Erstellt ein offizielles koreanisches Besprechungsprotokoll basierend auf Audio-/Videodateien oder einer Transkription und liefert es als gültige .hwpx-Datei. Falls keine Transkription vorliegt, wird zunächst eine Markdown-Transkription mit meetdown erstellt. Der aktuelle Umfang beschränkt sich auf die Erstellung von HWPX-Dateien; eine PDF-Konvertierung wird nicht durchgeführt.

Ausführungsumgebung

• Nutzt Dateisystem- und Shell-Ausführungsrechte.
• Für die Ausführung von Python-Befehlen und -Paketen werden uv und uvx verwendet. Das Spracherkennungstool meetdown==0.2.1 erfordert Python 3.12 oder höher.
• Die Spracherkennung benötigt eine Netzwerkverbindung und Anmeldeinformationen für einen der folgenden Dienste: CLOVA Speech, OpenAI oder Gemini.
• Die Anmeldeinformationen werden als Umgebungsvariablen bereitgestellt. Wurde die Skill als Claude-Code-Plugin installiert, können sie auch in den Plugin-Einstellungen hinterlegt werden. Sofern beide vorhanden sind, haben die Plugin-Einstellungen Vorrang.
• Die HWPX-Erstellung verwendet eine gebündelte Vorlage und ein Skript, das auf der Python-Standardbibliothek basiert.

Zwingend einzuhaltende Grundsätze

• Es werden keine Vermutungen über Datum/Uhrzeit, Ort, Teilnehmer, Sprechernamen, Verantwortliche, Fristen, Entscheidungen, Zahlen oder Eigennamen angestellt.
• Das Feld Created at von Meetdown gibt den Erstellungszeitpunkt der Transkription an und nicht das Datum/die Uhrzeit des Meetings.
• Bezeichnungen wie A, B oder [[SPEAKER_1]] sind keine echten Namen. Sie werden nur dann durch tatsächliche Namen ersetzt, wenn eine Sprecherzuordnung vom Benutzer vorliegt.
• Es wird zwischen Vorschlägen, Bedenken, Entscheidungen, Folgemaßnahmen und offenen Punkten unterschieden.
• Mehrfach geäußerte Ideen werden nicht automatisch als Entscheidungen gewertet.
• Weicht eine anfängliche Meinung von einer ausdrücklichen Einigung am Ende der Besprechung ab, hat die letztendliche Einigung oder Anweisung Vorrang.
• Äußerungen, die auf nicht vorhandene Referenzmaterialien verweisen (z. B. „hier“, „dieses Bild“, „diese Seite“), werden 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 gedruckt.
• Nur kurze, wichtige Phrasen zu Entscheidungen, Schlussfolgerungen und Folgemaßnahmen werden in Blau (#2F5597) und fett hervorgehoben. Der Haupttext wird nicht großflächig blau eingefärbt.

Enthaltene Materialien

Es werden nur die für die jeweilige Situation relevanten Materialien gelesen.

• references/meetdown-guide.md: Wird gelesen, wenn keine Transkription vorliegt oder die Ausführung von Meetdown fehlschlägt.
• references/minutes-writing.md: Wird vor der Umstrukturierung der Transkription in ein Protokoll gelesen.
• references/hwpx-template.md: Wird beim Erstellen, Ersetzen oder Ändern der HWPX-Vorlage gelesen.
• references/installation.md: Dient zur Anleitung bei Installationsorten oder Konfigurationen durch den Administrator.
• references/evaluation.md: Wird beim Entwerfen von Regressionstests nach einer Skill-Änderung gelesen.
• assets/minutes.schema.json: Definiert die Struktur der minutes.json.
• assets/example-minutes.json: Dient nur als Beispiel für die Datenstruktur, nicht als Textvorlage.
• assets/example-audit.json: Beispiel für ein Audit-Trail-Dokument.
• assets/meeting-minutes-template.hwpx: Standardvorlage für das Besprechungsprotokoll.

Zu verwendende Skripte

Alle Pfade beziehen sich auf das Stammverzeichnis der Fertigkeit. Bei Installation als Plugin befindet sich das Stammverzeichnis außerhalb des Arbeitsordners im Cache. Daher werden Eingabe- und Ausgabedateien als absolute Pfade im Arbeitsordner des Benutzers angegeben, und Artefakte werden nicht im Skill-Ordner gespeichert.

• scripts/transcribe.py: Führt Meetdown nicht-interaktiv aus und schützt Geheimnisse.
• scripts/inspect_transcript.py: Überprüft die Struktur und Risikofaktoren der Meetdown-Markdown-Datei.
• scripts/validate_minutes.py: Validiert die minutes.json vor der HWPX-Erstellung.
• scripts/render_hwpx.py: Überträgt die strukturierten Inhalte in die HWPX-Vorlage.
• scripts/validate_hwpx.py: Prüft ZIP, XML, erforderliche Phrasen, Fettdruck und blaue Hervorhebungen.
• scripts/validate_skill.py: Prüft die Kernregeln der Agentenfertigkeit.
• scripts/self_test.py: Führt einen vollständigen lokalen Test ohne Netzwerk durch.

Arbeitsablauf

Status:

• 1. Eingabedateien und Referenzmaterialien klassifizieren.
• 2. Falls keine Transkription vorliegt, mit Meetdown transkribieren.
• 3. Struktur und Qualität der Transkription prüfen.
• 4. Audit-Trail-Dokument erstellen.
• 5. minutes.json erstellen und validieren.
• 6. HWPX-Datei generieren.
• 7. HWPX-Datei validieren und Fehler korrigieren.
• 8. Über die Ausgabe und zu klärende Punkte berichten.

1. Eingabedaten klassifizieren

Es gilt die folgende Priorität:

1. Vom Benutzer bestätigte Besprechungsmetadaten, Sprecherzuordnungen, Begriffsschreibweisen und Korrekturen
2. Referenzmaterialien wie Tagesordnungen, Präsentationen, RFPs und Teilnehmerlisten aus der eigentlichen Besprechung
3. Gültige Transkription mit Zeitstempeln und Sprechern
4. Vollständige Transkription ohne Zeitstempel
5. Datumshinweise aus Dateinamen, nur wenn das Format explizit angegeben ist

Behandlung pro Eingabe:

• Liegt eine gültige Transkription als Markdown vor, wird diese ohne erneute Transkription derselben Aufnahme verwendet.
• Liegen nur Audio-/Videodateien vor, wird vor der Protokollerstellung transkribiert.
• Sind sowohl Transkription als auch Aufnahme vorhanden, hat die Transkription Vorrang. Eine erneute Transkription erfolgt nur, wenn die Transkription leer, beschädigt ist oder den Inhalt einer anderen Besprechung enthält.
• Mehrere Aufnahmen werden einzeln transkribiert. Eine Zusammenführung in Dateireihenfolge erfolgt nur, wenn bestätigt ist, dass es sich um fortlaufende Aufnahmen derselben Besprechung handelt.
• Liegen weder Aufnahme noch Transkription vor, wird nur eine Überprüfungsversion erstellt, wenn die Besprechungsnotizen ausreichend sind. Bei unzureichender Grundlage wird kein Besprechungsinhalt erfunden.

2. Bei Bedarf transkribieren

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

Standardausführung für koreanische Besprechungen mit CLOVA Speech:

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

Steht ein Tool namens transcribe_meeting zur Verfügung, wird stattdessen dieses aufgerufen. Die in den Plugin-Einstellungen hinterlegten Anmeldeinformationen werden nur an dieses Tool weitergegeben. input_path und output_path werden als absolute Pfade angegeben, die folgenden Optionen werden als entsprechende Parameter (z. B. chunk_duration) übergeben.

Nur bei Fehlschlagen eines einzelnen Uploads bei langen Dateien oder bei eindeutigen Anbietereinschränkungen wird mit den folgenden Optionen wiederholt:

--chunk-duration 10m

Als Standardkomprimierung wird smallest verwendet. Nur bei Nachweis einer Verschlechterung der Transkriptionsqualität durch die Komprimierung wird mit lossless wiederholt. Bei Besprechungen mit mehreren Teilnehmern wird die Sprechertrennung beibehalten, sofern kein besonderer Grund dagegen spricht.

Nach der Transkription muss zwingend eine Überprüfung erfolgen:

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

Es wird kein Besprechungsprotokoll erstellt, wenn die Datei leer ist, eine HTML-Fehlerseite enthält oder weder eine nutzbare Volltranskription noch Zeitstempelabschnitte vorhanden sind.

3. Metadaten bereinigen

Falls bekannt, werden die folgenden Werte festgehalten:

• Tagesordnung
• Datum/Uhrzeit
• Verantwortliche Organisation
• Ort
• Teilnehmerzahl
• Haupttagesordnungspunkte
• Sprecherzuordnung
• Festgelegte Schreibweisen für Personen-, Organisations-, Projekt-, Produktnamen und Fachbegriffe

Das Fehlen von Metadaten mit geringer Priorität unterbricht den Arbeitsablauf nicht. Es wird eine Überprüfungsversion erstellt, das entsprechende Feld mit Überprüfung erforderlich markiert und in quality.missing_metadata festgehalten. Es werden nur Informationen zusätzlich abgefragt, wenn eine vollständige Endversion zwingend erforderlich ist und die Informationen das Ergebnis maßgeblich beeinflussen.

4. Audit-Trail-Dokument erstellen

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

{
  "type": "fact | proposal | concern | decision | action | open_question",
  "statement": "Kurzer, normalisierter Inhalt",
  "source": "Dateiname der Transkription oder des Referenzmaterials",
  "speaker": "A oder bestätigter Name",
  "start": "00:42:02",
  "end": "00:42:10",
  "confidence": "high | medium | low"
}

Klassifikationskriterien:

• fact: Tatsachen, die in der Besprechung bestätigt oder erläutert wurden
• proposal: Vorschläge, Ideen, Optionen
• concern: Gegenargumente, Risiken, Einschränkungen
• decision: Ausdrückliche Zustimmung, Auswahl, Bestätigung, Genehmigung, Anweisung
• action: Konkrete Aufgaben, die durchgeführt werden sollen
• open_question: Noch nicht abgeschlossene Punkte

Folgeaktionspunkte müssen eine Aufgabe enthalten. Verantwortliche und Fristen werden nur bei Vorliegen einer Grundlage eingetragen.

5. Protokolldaten erstellen

Den Vorgaben in references/minutes-writing.md und assets/minutes.schema.json folgen. assets/example-minutes.json dient nur als Strukturbeispiel, der Inhalt wird nicht kopiert.

Erforderliche Dokumentstruktur:

• B E S P R E C H U N G S P R O T O K O L L
• Metadatentabelle im Kopf
• B E S P R E C H U N G S V E R L A U F
  • Zusammenfassung der Besprechung
  • 2. Hauptdiskussionen
  • 2.1 ff. thematische Diskussionen, in der Regel 3–7 Stück
• E R G E B N I S S E
  • [Zusammenfassung]
  • [Folgeaktionspunkte]
  • Bei Bedarf [Zu klärende Punkte]

Der Sprachstil ist prägnant und sachlich im koreanischen Geschäftsstil. Endungen wie -함, -하기로 함, -논의됨, -필요함, -판단됨 werden standardmäßig verwendet. Füllwörter, Stottern, Wiederholungen und irrelevante Abschweifungen werden entfernt. Gegenargumente, technische Einschränkungen, Kosten und Termine, die Grundlage für Entscheidungen sind, bleiben jedoch erhalten.

In das emphasis-Array werden kurze, mit dem Haupttext exakt identische Zeichenfolgen eingetragen, die blau dargestellt werden sollen. Wichtige Einträge werden mit important: true gekennzeichnet.

Validierung:

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

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

6. HWPX generieren

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

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

Der Renderer behält die Tabellenstruktur und die vorhandenen Absatzstile bei, setzt Titel und Untertitel fett, markiert die angegebenen Schlüsselphrasen in #2F5597 und fett, und lässt übermäßig lange Inhalte auf natürliche Weise auf die nächste Seite übergehen, ohne die Schriftgröße übermäßig zu verkleinern.

Stellt der Benutzer eine deutlich abweichende HWPX-Vorlage bereit, wird nicht blindlings vorgegangen. Gemäß references/hwpx-template.md werden Tabellenzelladressen und Absatzstruktur des Haupttextes überprüft und der Renderer entsprechend angepasst.

7. HWPX validieren

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

Bei Fehlschlagen der Validierung werden die JSON oder die Vorlage korrigiert und neu generiert. Dateien mit den folgenden Eigenschaften werden nicht ausgeliefert:

• mimetype ist nicht der erste ZIP-Eintrag oder ist komprimiert
• Erforderliche XML-Dateien fehlen oder lassen sich nicht parsen
• Erwartete Phrasen fehlen
• Dokumenttitel oder Abschnittsüberschriften sind nicht fett
• Hervorhebung wurde angefordert, aber der blaue, fette Stil fehlt
• Unvollständige Platzhalter sind noch vorhanden

Die Validierung erfolgt durch Prüfung der ZIP-Struktur, der XML-Dateien, des Inhalts und der Formatierungseinstellungen. Es werden keine Ausführung von Hancom-Office, Computer Use oder Bildschirmprüfung per Screenshot durchgeführt.

8. Ausgabe und Bericht

Je nach Situation werden die folgenden Dateien erstellt:

• Falls eine Transkription erforderlich war: transcript.md
• transcript.inspect.json
• minutes.json
• minutes.audit.json
• Falls unbestätigte Punkte vorhanden sind: minutes.review.md
• Endgültige .hwpx-Datei

Endgültiges Berichtsformat:

Abgeschlossen
- HWPX: <Pfad>
- Transkription: <Pfad oder Hinweis auf Verwendung der vorhandenen Transkription>
- Validierung: Erfolgreich | Warnungen vorhanden
- Zu überprüfen: Keine | Zusammenfassung der Kernpunkte

Fehlerbehandlung

• Fehlen Anmeldeinformationen, wird der Name der erforderlichen Umgebungsvariable mitgeteilt. Bei Claude Code wird darauf hingewiesen, dass die Daten in den Plugin-Einstellungen von /plugin für das hwpx-Plugin eingegeben werden können. Der Benutzer wird nicht aufgefordert, Geheimnisse in den Chat einzugeben.
• Bei Kapazitäts- oder Zeitlimitbeschränkungen wird mit --chunk-duration 10m wiederholt.
• Ist die Transkriptionszuverlässigkeit gering, werden Eigennamen und Zahlen nicht willkürlich geändert, sondern als Überprüfungspunkte belassen.
• Schlägt das HWPX-Rendering fehl, wird die Ursache gemeldet, und die beschädigte Datei wird nicht als Ergebnis bereitgestellt.
• Wird eine PDF-Ausgabe angefordert, wird darauf hingewiesen, dass dies außerhalb des aktuellen Skill-Umfangs liegt und eine separate Konvertierungsumgebung erforderlich ist.

Selbsttest

Ausführung nach der Installation der Skill oder nach Änderungen an Skripten oder Vorlagen:

uv run scripts/self_test.py

Dieser Test führt keine Spracherkennungs-API aus, sondern prüft das Parsen von Transkriptionen, die JSON-Validierung, die HWPX-Erstellung und die Strukturvalidierung.