lukezielke/lecture-to-anki

Vorlesung → Anki (v2)

Handle als evidenzbasierter Fach-Tutor, nicht als Folien-zu-Stichpunkte-Konverter. Wandle lokale Vorlesungsmaterialien, Hausaufgaben, Lösungen und Altklausuren in präzise, prüfungsrelevante, atomare, in sich geschlossene Anki-Notizen um. Bewahre Quellenverweise und Identitäten, damit erneut importierte Pakete vorhandene Notizen aktualisieren. Rate niemals bei einer nicht gelesenen Abbildung oder einer nicht gelösten Klausurfrage.

Eingaben, Standardwerte, Einschränkungen

• Kurs-Root: Benutzerordner oder Arbeitsverzeichnis. Lies rekursiv, schließe anki-output/, .git, .agents, build usw. aus.
• Ausgabe: <course>/anki-output; kanonische editierbare Daten sind cards.json.
• Deck: Verwende den Kurs-Ordnernamen, sofern nicht anders angegeben; benenne es nicht zwischen Updates um, da dies die Deck/Modell-Identität ändert.
• Modi: exam-focused (Standard), comprehensive, topic-specific und update.
• Lieferung: Standardmäßig deck.apkg, optional basic.txt / cloze.txt. Erfordert genanki für .apkg. Installiere es nur mit Erlaubnis des Benutzers, wenn nötig; falls nicht verfügbar, exportiere Text mit --format text und erkläre die Einschränkung.
• Lese und schreibe nur innerhalb des Kurs-Baums / des vorgesehenen Ausgabeordners; verändere oder lösche keine Vorlesungsmaterialien; keine Drittanbieter-Uploads oder Web-Recherchen ohne Benutzeraufforderung.
• Behalte denselben Deck-Namen, Notiz-id-Werte und Kartentypen bei Updates. Das Ändern des Notiztyps einer Karte zerstört ihre Identität und kann in Anki eine separate Notiz erzeugen.

Arbeitsablauf

1) Bestimme vor der Extraktion, ob Ersterstellung oder Update

Wenn <output>/cards.json und <output>/source_manifest.json existieren, führe zuerst aus:

python3 <skill-dir>/scripts/plan_update.py "/path/to/course"

Lese anki-output/update_plan.json. Es meldet neu hinzugefügte, geänderte und gelöschte Quelldateien (SHA-256-Hashes) sowie vorhandene Notizen, die von geänderten/entfernten Dateien unterstützt werden. Dieser Schritt muss vor einem neuen Export erfolgen, da ein erfolgreicher Export das aktualisierte Manifest festschreibt. Wenn es keine Basislinie gibt, generiere ein erstes vollständiges Deck. Ein Update ohne inhaltliche Änderungen erfordert normalerweise keine neuen Karten; erlaube dennoch explizit angeforderte Verbesserungen.

Alte v1 cards.json ohne explizite Notiz-IDs: vor dem Bearbeiten von Fragen einmal ausführen:

python3 <skill-dir>/scripts/migrate_ids.py "/path/to/course/anki-output/cards.json"

Dies schreibt eine .bak-Sicherungskopie und füllt fehlende IDs unter Verwendung der ursprünglichen Fragen aus. Behalte diese IDs für immer unverändert (auch wenn sich der Wortlaut der entsprechenden Frage oder die zitierte Folie ändert).

2) Lese die Quellen ein und inventarisiere sie

python3 <skill-dir>/scripts/extract_sources.py "/path/to/course" \
  --output "/path/to/course/anki-output/sources.jsonl"

Konsultiere sources_report.json; es enthält pro-Datei-Hashes, -Typen, Kategorie-Klassifizierung, nicht zugängliche Dateien und leere PDF-Seiten. Kategorien: Vorlesungen, Hausaufgaben, Hausaufgabenlösungen, Altklausuren, Klausurlösungen und Notizen. PDF-Text benötigt pdftotext oder pymupdf. PPTX/DOCX/Markdown/LaTeX/HTML/Text werden unterstützt. Bildlastige oder gescannte Dateien erfordern visuelle Inspektion; Textextraktion ist kein Beweis dafür, dass alle Inhalte verstanden wurden. Verwende bei Bedarf lokale PDF/PPTX-Renderer, keine erfundenen OCR-/Diagramminterpretationen. Halte ausgelassene Inhalte in coverage.md fest.

Lies alle relevanten Quelldokumente beim ersten Durchlauf. Bei inkrementellen Durchläufen untersuche hauptsächlich neue/geänderte Quellen und zugehöriges vorhandenes Material, um Konflikte und überlappende Fakten zu erkennen. Behalte eine übergreifende Kursübersicht/Abdeckungskarte für beides. Erstelle keine Karten nur auf Basis von Dateinamen oder isolierten Ausschnitten.

3) Erstelle eine prüfungsorientierte Lernlandkarte

1. Folien sind der Umfang: Schlüsselbegriffe, Theoreme, formale Annahmen, Notation, Algorithmen, Beispiele.
2. Hausaufgaben trainieren den Transfer: Übungsstrategien, Beweismuster, wiederkehrende Missverständnisse.
3. Lösungen validieren Antworten; erfinde niemals die Antwort auf eine Klausur-/Hausaufgabe, die keine verifizierte Lösung hat.
4. Altklausuren zeigen Häufigkeit und erwartete Aufgabenformate, sind aber kein vollständiger Lehrplan. Behandle historische Wiederholungen als Evidenz, niemals als garantierte Prüfungsvorhersage.
5. Bewerte Themen nach Zentralität, Kurs-Lernzielen, Wiederholung in unabhängigen Materialien und Klausur-/Hausaufgaben-Schwerpunkt. Priorisiere wiederverwendbares Wissen vor dem Auswendiglernen isolierter alter Antworten.

Bevor du Karten schreibst, lies beide:

• references/card-quality.md
• references/math-cs-cards.md

Verwende einen thematischen Abdeckungsplan: Definitionen + Bedingungen, Verständnis/Warum, Anwendung/Erkennung, Fehlerfälle. Für Mathematik/Informatik besonders Theorem / Annahmen / Beweisstrategie / Beweisschritt / Gegenbeispiel / Invariante / Komplexität / Algorithmus-Trace / Reduktion / Mikroanwendung beachten. Nicht jedes Thema benötigt jeden Typ; wähle nur begründete, prägnante, testbare Karten. Bewahre Quantoren und Voraussetzungen. Gib an, welches Komplexitätsmaß, welche Eingabeannahmen und welche Graphkonventionen verwendet werden. Verwende Anki MathJax \(...\) oder \[...\], mit korrektem JSON-Escaping.

4) Bilder und Diagramme wo nötig

Ein reiner Text-Prompt kann für einen Graphen, Automaten, Baum, Architekturdiagramm, Algorithmus-Trace, geometrische Konstruktion oder notationslastige Formel unzureichend sein. Wenn die Visualisierung wesentlich ist, füge die Abbildung in die Karte ein, anstatt den Lernenden sie sich vorstellen zu lassen.

Überprüfe die Abbildung zuerst visuell, um den genauen Bereich zu bestimmen; kopiere nicht automatisch ganze Folien oder füge Abbildungen wahllos ein.

Für ein zugeschnittenes PDF-Diagramm (Koordinaten in PDF-Punkten):

python3 <skill-dir>/scripts/prepare_media.py pdf "/path/to/course/slides/L3.pdf" \
  --page 12 --crop 100,90,490,330 --output "/path/to/course/anki-output/media"

Für eine vollständige PPTX-Folie (benötigt LibreOffice + PyMuPDF) oder ein eingebettetes PPTX-Bild:

python3 <skill-dir>/scripts/prepare_media.py pptx-slide "/path/to/course/slides/L3.pptx" \
  --slide 7 --output "/path/to/course/anki-output/media"
python3 <skill-dir>/scripts/prepare_media.py pptx-image "/path/to/course/slides/L3.pptx" \
  --slide 7 --image 1 --output "/path/to/course/anki-output/media"

Für vorhandene .png, .jpg usw. verwende prepare_media.py image ... --output ....

Füge den genauen Basisnamen in das HTML der Karte ein: <img src="lta_example_abcdef1234.png">. Füge ebenfalls "media": ["media/lta_example_abcdef1234.png"] zu dieser Notiz hinzu. Der HTML-Dateiname ist nur der Basisname (kein media/-Präfix). Assets müssen lokal und im gewählten Ausgabeordner sein. Dadurch wird sichergestellt, dass sie im .apkg enthalten sind. Siehe references/cards-schema.md.

Vermeide es, benutzerspezifische Kursantworten als Bilder zu speichern, wenn kopierbarer und screenreader-freundlicher mathematischer Text denselben Inhalt vermitteln kann; beschreibe oder untertitelt wichtige visuelle Beziehungen im Text. Abbildungen sind kein Ersatz für die Überprüfung der inhaltlichen Korrektheit.

5) Erstelle/verwalte cards.json

Verwende das Schema in references/cards-schema.md; jede Notiz muss eine eindeutige stabile id haben (z. B. graphs.dijkstra.nonnegative). Leite NIEMALS eine neue ID aus bearbeitetem Fragetext während eines Updates ab. Erstelle eine stabile ID bei der ersten Generierung; behalte sie in cards.json. IDs müssen innerhalb des Decks eindeutig bleiben, und der Kartentyp type sollte stabil sein.

Enthalten:

• type: basic oder cloze (Anki-Notiztyp; die meisten Mathe/Informatik-Aufgaben profitieren von Basic).
• kind: z. B. theorem, proof_idea, counterexample, algorithm_trace, complexity, application (Klassifikations-Tag, keine Anki-Vorlage).
• front/back oder text/extra.
• source_file und source_location, plus supporting_sources, wenn Inhalte über mehrere Dateien hinweg verifiziert wurden.
• tags mit topic::..., priority::..., from::....
• media, wenn verwendet.

Eine Basic-Frage muss in etwa 5–30 Sekunden unabhängig beantwortbar sein, auf einen Fakt oder eine Idee abzielen und Annahmen von Schlussfolgerungen unterscheiden. Zerlege lange Algorithmus-Durchläufe/Beweise in kurze testbare Schritte. Lückentexte sollten sinnvolle kontextuelle Inhalte testen; lücke niemals einen ganzen Absatz aus.

6) Inkrementelle Update-Regeln

Bei einem späteren Durchlauf:

1. Lese update_plan.json, alte cards.json und den neuen/relevanten Quelltext.
2. Überprüfe betroffene Themen und Notizen erneut, revidiere sie, wenn sich Quellfakten/Notation geändert haben, behalte die Notiz-id bei. Lasse unveränderte Notizen wortwörtlich stehen.
3. Füge neu benötigte Notizen mit neuen IDs nur hinzu, wenn sie neue Erinnerungen/Fähigkeiten beitragen. Überprüfe das gesamte Deck auf semantische Duplikate, bevor du hinzufügst.
4. Gelöschte Quellen: Überprüfe zuerst alternative Zitate; markiere verwaiste/nicht unterstützte Notizen zur Überprüfung. Lösche niemals automatisch Karten oder Quellen bei einer Dateilöschung.
5. Halte type stabil. Für einen signifikanten Basic-zu-Cloze-Ersatz erstelle eine separate ID, markiere die Legacy-Notiz explizit zur manuellen Löschung in Anki (Import entfernt fehlende Notizen nicht).
6. Überschreibe cards.json bei Validierungsfehlern nicht; bewahre die vorherige Version in cards.json.bak vor großen Bearbeitungen auf.
7. Exportiere erst, nachdem jede betroffene Notiz überprüft wurde, um das neue source_manifest.json zu committen. Zeige nicht an, dass die Aktualisierung eines Quell-Snapshots bedeutet, dass seine Inhalte verstanden wurden.

Sowohl die Deck-/Modell-IDs des Pakets als auch die Notiz-GUIDs sind für dasselbe Deck und dieselben Karten-IDs stabil. Beim erneuten Import in Anki wähle die Option zum Aktualisieren vorhandener Notizen; die Importeinstellungen und Änderungszeiten von Anki können beeinflussen, ob Änderungen tatsächlich angewendet werden. Vorhandene Zeitpläne bleiben im Allgemeinen erhalten, wenn dieselben Notizen aktualisiert werden, überprüfe jedoch die Vorschau deines Anki-Imports. Ein erneuter Import löscht nicht veraltete, zuvor importierte Notizen. Bearbeite nicht manuell die Sammlungsdateien von Anki oder verwende AnkiConnect, es sei denn, der Benutzer fordert es ausdrücklich an.

7) Validieren und exportieren

python3 <skill-dir>/scripts/export_anki.py "/path/to/course/anki-output/cards.json" \
  --output "/path/to/course/anki-output" \
  --course "/path/to/course" --format both

--format both (Standard) erzeugt deck.apkg, basic.txt, cloze.txt (wo zutreffend), export_report.json und source_manifest.json. Importiere entweder die .apkg- ODER die .txt-Dateien in eine bestimmte Anki-Sammlung, nicht beide: unterschiedliche Notiztypen würden sonst Duplikate erzeugen. --format text funktioniert ohne genanki, aber sein Import verwendet Erstfeld-Abgleich und kann Fragen nicht sicher nach ID überarbeiten. Verwende .apkg für fortlaufende inkrementelle Updates. --format apkg überspringt den Textexport.

Installiere .apkg-Abhängigkeit, falls verfügbar:

python3 -m pip install genanki

Überprüfe export_report.json auf Kartenanzahlen, fehlende explizite IDs, übersprungene exakte Duplikate, Medienanzahl. Löse Validierungsfehler, anstatt sie zu ignorieren. Medien-Quelldateinamen müssen eindeutig und korrekt referenziert sein. Importiere .apkg über Ankis Datei → Import.

8) Fasse Abdeckung und QA zusammen

Schreibe <output>/coverage.md mit:

• Gelesene Materialien vs. übersprungene Dateien; liste Scan-/Abbildungslücken explizit auf.
• Abgedeckte Themen und Anzahl der Notizen nach kind und priority; Gleichgewicht zwischen Definition und Anwendung.
• Wiederkehrende Klausur-/Hausaufgabenmuster, mit Unsicherheit und Referenzen.
• Konflikte oder ungelöste Beweis-/Lösungsannahmen.
• Bei Update: neue/geänderte/gelöschte Quellen, beibehaltene/überarbeitete/hinzugefügte Notizen, verwaiste Notizen, die eine Überprüfung erfordern; stelle sicher, dass es keine ungerechtfertigten stillen Löschungen gibt.
• Exportierte Dateinamen und Importanweisungen; weise darauf hin, dass der .apkg-Import fehlende Notizen nicht löscht und dass Anki-Updates von den Importoptionen des Benutzers abhängen können.

Wenn die Abdeckung unvollständig ist, sage dies; behaupte keine vollständige Kartengenerierung für Quellen, die du nicht einsehen konntest.