Back to search
Donat-Vocabulary-Trainer
SkillGitHub
The only vocabulary trainer you will ever need
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/annichaotica--donat-vocabulary-trainer)HTML
<a href="/listings/annichaotica--donat-vocabulary-trainer"><img src="/api/listings/annichaotica--donat-vocabulary-trainer/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 223 lines
- # Vokabeltrainer
- [](LICENSE)
- [](https://codespaces.new/annichaotica/Donat-Vocabulary-Trainer)
- *English: [README.en.md](README.en.md)*
- > **Arbeitsname: Donat.** Nach Aelius Donatus, dessen *Ars minor* das
- > Lateinlehrbuch des Mittelalters war — und »Donat« wurde im Deutschen
- > zum Wort für das Schulbuch selbst. Der Name steht an EINER Stelle:
- > [`backend/marke.py`](backend/marke.py). Das Verzeichnis heißt weiter
- > `vokabeltrainer`.
- Browserbasiert, eigene Datenbank, läuft im Heimnetz. Gebaut, weil die
- üblichen Trainer eine Vokabel als *Paar aus zwei Zeichenketten* begreifen und
- daran alles scheitert, was man eigentlich pauken muss — Formen, Zeiten,
- Konjugationen.
- Das Konzept samt Begründung der Entwurfsentscheidungen steht in
- [`00-konzept.md`](00-konzept.md). Die Festlegung für die KI-gestützte
- Befüllung in [`01-format-fuer-ki-befuellung.md`](01-format-fuer-ki-befuellung.md).
- ## Was ihn unterscheidet
- | | |
- |---|---|
- | **Formen statt Paare** | Ein Lexem hat Formen (mit Merkmalen beschrieben) und Bedeutungen (mit beliebig vielen gültigen Übersetzungen). Daraus folgt freie Abfragerichtung von selbst. |
- | **Aufgaben werden erzeugt** | Terminiert wird nicht „das Wort", sondern jede einzelne Aufgabe darüber. „Bedeutung weiß ich, Konjugation nicht" ist ein Zustand, den das Modell kennt. |
- | **Verwechslung statt Tippfehler** | Wer bei der 1. Person *vas* schreibt, hat sich nicht vertippt. Der Trainer sagt: „Das ist die 2. Person Singular." |
- | **Fehler werden benannt** | „b und d sehen sich ähnlich", „hier gehört mm hin", „die Reihenfolge stimmt nicht" — statt bloß „falsch". |
- | **Keine Selbsteinschätzung** | Die Bewertung wird aus Richtigkeit, Fehlerart, Versuchen und Denkzeit abgeleitet — und begründet. |
- | **Offene Rechnung** | FSRS-5, aber Stabilität, Schwierigkeit und Abrufwahrscheinlichkeit sind jederzeit einsehbar: „Warum kommt das jetzt?" |
- | **Sprachen sind Daten** | Formgruppen, Prüfregeln und Artikel stehen im Sprachprofil, nicht im Code — und lassen sich über die Schnittstelle ändern. |
- Mitgeliefert: Französisch, Spanisch, Englisch, Griechisch, Mittelhochdeutsch,
- Deutsch. Weitere lassen sich ohne Codeänderung einrichten.
- ## Starten
- ### Auf dem Mac, zum Entwickeln
- ```sh
- python3 -m venv .venv
- .venv/bin/pip install -r requirements.txt -r requirements-test.txt
- .venv/bin/python werkzeuge/beispieldaten.py # Beispielbestand
- .venv/bin/uvicorn app:app --app-dir backend --reload --port 8030
- ```
- Dann <http://localhost:8030>. Tests: `.venv/bin/python -m pytest tests/ -q`
- ### Auf dem eigenen Server
- ```sh
- ssh <dein-server>
- sudo mkdir -p /srv/vokabeltrainer && sudo chown "$USER" /srv/vokabeltrainer
- # Projekt dorthin kopieren, dann:
- cd /srv/vokabeltrainer && docker compose up -d --build
- ```
- Erreichbar unter `http://<dein-server>:8030`, nur im Heimnetz.
- Port 8030, weil die näherliegenden belegt sind: 80 und **8020** gehören dem
- Caddy (Startseite und der Autodesk-Spiegel), 2283 Immich, 8010 Paperless,
- 9925 Mealie.
- Auf dem iPhone oder iPad die Seite aufrufen und „Zum Home-Bildschirm" —
- dann startet sie wie eine App.
- ### Sicherung
- Die Datenbank läuft im **WAL-Modus**. Sie einfach mitzukopieren ergibt
- während eines Schreibvorgangs einen unvollständigen Stand — die Änderungen
- stehen dann noch im Begleitprotokoll. Für eine Sicherung gehört darum ein
- Abzug über die Sicherungsschnittstelle von SQLite davor:
- ```sh
- werkzeuge/sicherung.sh [zieldatei]
- ```
- Das Skript nimmt einen in sich stimmigen Abzug, auch während gelernt wird,
- stellt ihn auf `journal_mode=delete` (damit keine Begleitdateien
- danebenliegen), prüft ihn und behält die letzten sieben.
- Wer ein eigenes Sicherungsskript hat, hängt es dort ein und **schließt die
- laufende Datei samt `-wal` und `-shm` aus dem Archiv aus** — sonst sichert
- man zweimal, einmal davon unbrauchbar.
- ### Von außen erreichbar
- Über einen Cloudflare-Tunnel mit Cloudflare Access davor — siehe
- [`deploy/cloudflared/LIESMICH.md`](deploy/cloudflared/LIESMICH.md). Kein
- offener Port im Router.
- ## Der MCP-Server
- Damit kann Claude Vokabeln samt vollständigen Paradigmen unmittelbar
- eintragen — ohne Dateien hin und her zu tragen. Nach jedem Anlegen läuft die
- Qualitätsprüfung mit und ihr Ergebnis geht zurück: ob der Stamm ableitbar ist,
- ob das Paradigma Lücken hat, ob eine Übersetzung fehlt.
- Er braucht **keine Fremdpakete**, nur Python 3.
- ### In Claude Code einrichten
- ```sh
- claude mcp add vokabeltrainer \
- --env VOKABEL_URL=http://<dein-server>:8030 \
- -- python3 ~/Projects/Vokabeltrainer/mcp/vokabeltrainer_mcp.py
- ```
- ### In der Claude-App einrichten
- In `~/Library/Application Support/Claude/claude_desktop_config.json`:
- ```json
- {
- "mcpServers": {
- "vokabeltrainer": {
- "command": "python3",
- "args": ["~/Projects/Vokabeltrainer/mcp/vokabeltrainer_mcp.py"],
- "env": { "VOKABEL_URL": "http://<dein-server>:8030" }
- }
- }
- }
- ```
- ### Die Werkzeuge
- | Werkzeug | wofür |
- |---|---|
- | `sammlungen_auflisten` | Der erste Aufruf — ohne `sammlung_id` geht nichts |
- | `formgruppen_zeigen` | **Vor** dem ersten Eintragen in einer Sprache: welche Merkmalsbündel die Formen tragen müssen |
- | `vokabel_anlegen` | Ein ganzes Wort mit allen Formen und Bedeutungen in einem Zug |
- | `vokabel_nachschlagen` | Über Lemma, **alle Formen** und alle Übersetzungen |
- | `formen_ergaenzen` | Einem bestehenden Eintrag eine weitere Zeit anfügen |
- | `eintrag_pruefen`, `sammlung_pruefen` | Taugt das für die Fähigkeiten des Trainers? |
- | `sprachprofil_lesen`, `sprachprofil_anpassen`, `sprache_einrichten` | Eine Sprache zum Laufen bringen, ohne Codeänderung |
- **Eingetragene Formen bleiben ungeprüft**, bis ein Mensch sie freigibt. Das
- ist Absicht: eine erfundene Form, die unbemerkt gepaukt wird, ist schlimmer
- als eine fehlende.
- ## Aufbau
- ```
- backend/
- schema.sql Datenbank. 23 Tabellen, mit Kommentaren
- merkmale.py Grammatische Merkmale, deutsche Beschriftungen
- sprachen.py Sprachprofile: Formgruppen, Prüfregeln, Artikel
- pruefung.py Antwortprüfung in Schichten
- legasthenie.py Fehlerarten benennen, Stamm ableiten, Silben
- fsrs.py Lernalgorithmus, nachvollziehbar
- bewertung.py Note aus Richtigkeit, Fehlerart und Denkzeit
- aufgaben.py Aufgaben erzeugen, stellen, prüfen
- lernen.py Die Sitzung
- lernziele.py Ziele und dynamische Lernblöcke
- qualitaet.py Prüft Einträge auf das, was der Trainer braucht
- datenbank.py SQLite, Wanderungen
- app.py HTTP-Schnittstelle
- frontend/ HTML, CSS, ES-Module. Kein Bauschritt, kein npm
- mcp/ MCP-Server, nur Standardbibliothek
- werkzeuge/ Beispieldaten, Sicherung
- tests/ 495 Tests
- ```
- Warum kein Bauschritt im Frontend: ein Vokabeltrainer soll in fünf Jahren noch
- starten, ohne dass sich ein Paketbaum von 2026 neu auflösen lässt.
- ## Tastatur
- | | |
- |---|---|
- | <kbd>Enter</kbd> | prüfen; danach weiter mit der automatischen Wertung |
- | <kbd>1</kbd>–<kbd>4</kbd> | von Hand anders werten |
- | <kbd>l</kbd> / <kbd>w</kbd> / <kbd>u</kbd> | lernen, Wortschatz, Übersicht |
- Für Akzente gibt es eine Zeichenleiste unter dem Antwortfeld. Für Sprachen
- mit eigener Schrift — Griechisch — lohnt ein richtiges Tastaturlayout; die
- Anleitung dazu steht unter `#/tastatur`.
- ## Stand
- **Fertig:** Datenmodell, Antwortprüfung, FSRS mit automatischer Bewertung,
- Abfrage für sechs Aufgabentypen, Wortschatzverwaltung mit Eingabemaske,
- Sprachprofile als Daten, Qualitätsprüfung, Wörterbuchsuche über alle Formen,
- Lernziele mit dynamischen Blöcken, Legastheniemodus, MCP-Server, Docker.
- Dazu Textverständnis: Texte einwerfen, Deckungsanalyse gegen den eigenen
- Wortschatz, Übersetzen je Abschnitt, fehlende Wörter beim Chatprogramm
- anfordern. Geführte Rundgänge und ein englischer Übungskurs zum
- Ausprobieren.
- **Als Nächstes:** Import aus CSV und Anki, Paradigma-Generator,
- Wiktionary-Anbindung, Diktat und Aussprache, Paradigmentabellen als
- Aufgabentyp, Lückensätze, Statistik.
- **Erwogen und vorerst abgelehnt:** eine direkt angebundene KI. Der
- Trainer ruft heute nirgends nach außen; alles, was eine KI tut, tut sie
- über den MCP-Server und das Chatprogramm der Benutzerin. Warum das so
- bleibt und unter welchen Bedingungen es sich ändern dürfte, steht in
- [02-geplant-ki-adapter.md](02-geplant-ki-adapter.md).
- ## Lizenz und Mitarbeit
- Copyright © 2026 Annuschka Brenner.
- Freie Software unter der [GNU Affero General Public License, Fassung 3 oder
- später](LICENSE). Du darfst sie benutzen, verändern und weitergeben.
- Die AGPL hat gegenüber den üblichen freien Lizenzen eine Besonderheit, und
- sie ist hier ausdrücklich gewollt: **wer eine veränderte Fassung über das
- Netz anbietet, muss seinen Quelltext veröffentlichen.** Wer den Trainer zu
- Hause im eigenen Netz betreibt — also der Normalfall —, ist davon nicht
- betroffen. Verbesserungen an einem Lernwerkzeug sollen aber nicht in einem
- geschlossenen Dienst verschwinden.
- Darum bietet die laufende Fassung ihren Quelltext selbst an: in der Fußzeile
- der Oberfläche und unter `GET /api/zustand`.
- **Mitarbeit am Repo ist auf Anfrage** — siehe [CONTRIBUTING.md](CONTRIBUTING.md).
- Fehlerberichte sind jederzeit willkommen, auch ohne Rückfrage. Für eigene
- Anpassungen braucht es niemanden zu fragen: abspalten und loslegen.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.