Skip to content
Back to search

Donat-Vocabulary-Trainer

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/annichaotica--donat-vocabulary-trainer/badge.svg)](/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
  1. # Vokabeltrainer
  2. [![Lizenz: AGPL v3](https://img.shields.io/badge/Lizenz-AGPL%20v3-blue.svg)](LICENSE)
  3. [![In GitHub Codespaces öffnen](https://github.com/codespaces/badge.svg)](https://codespaces.new/annichaotica/Donat-Vocabulary-Trainer)
  4. *English: [README.en.md](README.en.md)*
  5. > **Arbeitsname: Donat.** Nach Aelius Donatus, dessen *Ars minor* das
  6. > Lateinlehrbuch des Mittelalters war — und »Donat« wurde im Deutschen
  7. > zum Wort für das Schulbuch selbst. Der Name steht an EINER Stelle:
  8. > [`backend/marke.py`](backend/marke.py). Das Verzeichnis heißt weiter
  9. > `vokabeltrainer`.
  10. Browserbasiert, eigene Datenbank, läuft im Heimnetz. Gebaut, weil die
  11. üblichen Trainer eine Vokabel als *Paar aus zwei Zeichenketten* begreifen und
  12. daran alles scheitert, was man eigentlich pauken muss — Formen, Zeiten,
  13. Konjugationen.
  14. Das Konzept samt Begründung der Entwurfsentscheidungen steht in
  15. [`00-konzept.md`](00-konzept.md). Die Festlegung für die KI-gestützte
  16. Befüllung in [`01-format-fuer-ki-befuellung.md`](01-format-fuer-ki-befuellung.md).
  17. ## Was ihn unterscheidet
  18. | | |
  19. |---|---|
  20. | **Formen statt Paare** | Ein Lexem hat Formen (mit Merkmalen beschrieben) und Bedeutungen (mit beliebig vielen gültigen Übersetzungen). Daraus folgt freie Abfragerichtung von selbst. |
  21. | **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. |
  22. | **Verwechslung statt Tippfehler** | Wer bei der 1. Person *vas* schreibt, hat sich nicht vertippt. Der Trainer sagt: „Das ist die 2. Person Singular." |
  23. | **Fehler werden benannt** | „b und d sehen sich ähnlich", „hier gehört mm hin", „die Reihenfolge stimmt nicht" — statt bloß „falsch". |
  24. | **Keine Selbsteinschätzung** | Die Bewertung wird aus Richtigkeit, Fehlerart, Versuchen und Denkzeit abgeleitet — und begründet. |
  25. | **Offene Rechnung** | FSRS-5, aber Stabilität, Schwierigkeit und Abrufwahrscheinlichkeit sind jederzeit einsehbar: „Warum kommt das jetzt?" |
  26. | **Sprachen sind Daten** | Formgruppen, Prüfregeln und Artikel stehen im Sprachprofil, nicht im Code — und lassen sich über die Schnittstelle ändern. |
  27. Mitgeliefert: Französisch, Spanisch, Englisch, Griechisch, Mittelhochdeutsch,
  28. Deutsch. Weitere lassen sich ohne Codeänderung einrichten.
  29. ## Starten
  30. ### Auf dem Mac, zum Entwickeln
  31. ```sh
  32. python3 -m venv .venv
  33. .venv/bin/pip install -r requirements.txt -r requirements-test.txt
  34. .venv/bin/python werkzeuge/beispieldaten.py # Beispielbestand
  35. .venv/bin/uvicorn app:app --app-dir backend --reload --port 8030
  36. ```
  37. Dann <http://localhost:8030>. Tests: `.venv/bin/python -m pytest tests/ -q`
  38. ### Auf dem eigenen Server
  39. ```sh
  40. ssh <dein-server>
  41. sudo mkdir -p /srv/vokabeltrainer && sudo chown "$USER" /srv/vokabeltrainer
  42. # Projekt dorthin kopieren, dann:
  43. cd /srv/vokabeltrainer && docker compose up -d --build
  44. ```
  45. Erreichbar unter `http://<dein-server>:8030`, nur im Heimnetz.
  46. Port 8030, weil die näherliegenden belegt sind: 80 und **8020** gehören dem
  47. Caddy (Startseite und der Autodesk-Spiegel), 2283 Immich, 8010 Paperless,
  48. 9925 Mealie.
  49. Auf dem iPhone oder iPad die Seite aufrufen und „Zum Home-Bildschirm" —
  50. dann startet sie wie eine App.
  51. ### Sicherung
  52. Die Datenbank läuft im **WAL-Modus**. Sie einfach mitzukopieren ergibt
  53. während eines Schreibvorgangs einen unvollständigen Stand — die Änderungen
  54. stehen dann noch im Begleitprotokoll. Für eine Sicherung gehört darum ein
  55. Abzug über die Sicherungsschnittstelle von SQLite davor:
  56. ```sh
  57. werkzeuge/sicherung.sh [zieldatei]
  58. ```
  59. Das Skript nimmt einen in sich stimmigen Abzug, auch während gelernt wird,
  60. stellt ihn auf `journal_mode=delete` (damit keine Begleitdateien
  61. danebenliegen), prüft ihn und behält die letzten sieben.
  62. Wer ein eigenes Sicherungsskript hat, hängt es dort ein und **schließt die
  63. laufende Datei samt `-wal` und `-shm` aus dem Archiv aus** — sonst sichert
  64. man zweimal, einmal davon unbrauchbar.
  65. ### Von außen erreichbar
  66. Über einen Cloudflare-Tunnel mit Cloudflare Access davor — siehe
  67. [`deploy/cloudflared/LIESMICH.md`](deploy/cloudflared/LIESMICH.md). Kein
  68. offener Port im Router.
  69. ## Der MCP-Server
  70. Damit kann Claude Vokabeln samt vollständigen Paradigmen unmittelbar
  71. eintragen — ohne Dateien hin und her zu tragen. Nach jedem Anlegen läuft die
  72. Qualitätsprüfung mit und ihr Ergebnis geht zurück: ob der Stamm ableitbar ist,
  73. ob das Paradigma Lücken hat, ob eine Übersetzung fehlt.
  74. Er braucht **keine Fremdpakete**, nur Python 3.
  75. ### In Claude Code einrichten
  76. ```sh
  77. claude mcp add vokabeltrainer \
  78. --env VOKABEL_URL=http://<dein-server>:8030 \
  79. -- python3 ~/Projects/Vokabeltrainer/mcp/vokabeltrainer_mcp.py
  80. ```
  81. ### In der Claude-App einrichten
  82. In `~/Library/Application Support/Claude/claude_desktop_config.json`:
  83. ```json
  84. {
  85. "mcpServers": {
  86. "vokabeltrainer": {
  87. "command": "python3",
  88. "args": ["~/Projects/Vokabeltrainer/mcp/vokabeltrainer_mcp.py"],
  89. "env": { "VOKABEL_URL": "http://<dein-server>:8030" }
  90. }
  91. }
  92. }
  93. ```
  94. ### Die Werkzeuge
  95. | Werkzeug | wofür |
  96. |---|---|
  97. | `sammlungen_auflisten` | Der erste Aufruf — ohne `sammlung_id` geht nichts |
  98. | `formgruppen_zeigen` | **Vor** dem ersten Eintragen in einer Sprache: welche Merkmalsbündel die Formen tragen müssen |
  99. | `vokabel_anlegen` | Ein ganzes Wort mit allen Formen und Bedeutungen in einem Zug |
  100. | `vokabel_nachschlagen` | Über Lemma, **alle Formen** und alle Übersetzungen |
  101. | `formen_ergaenzen` | Einem bestehenden Eintrag eine weitere Zeit anfügen |
  102. | `eintrag_pruefen`, `sammlung_pruefen` | Taugt das für die Fähigkeiten des Trainers? |
  103. | `sprachprofil_lesen`, `sprachprofil_anpassen`, `sprache_einrichten` | Eine Sprache zum Laufen bringen, ohne Codeänderung |
  104. **Eingetragene Formen bleiben ungeprüft**, bis ein Mensch sie freigibt. Das
  105. ist Absicht: eine erfundene Form, die unbemerkt gepaukt wird, ist schlimmer
  106. als eine fehlende.
  107. ## Aufbau
  108. ```
  109. backend/
  110. schema.sql Datenbank. 23 Tabellen, mit Kommentaren
  111. merkmale.py Grammatische Merkmale, deutsche Beschriftungen
  112. sprachen.py Sprachprofile: Formgruppen, Prüfregeln, Artikel
  113. pruefung.py Antwortprüfung in Schichten
  114. legasthenie.py Fehlerarten benennen, Stamm ableiten, Silben
  115. fsrs.py Lernalgorithmus, nachvollziehbar
  116. bewertung.py Note aus Richtigkeit, Fehlerart und Denkzeit
  117. aufgaben.py Aufgaben erzeugen, stellen, prüfen
  118. lernen.py Die Sitzung
  119. lernziele.py Ziele und dynamische Lernblöcke
  120. qualitaet.py Prüft Einträge auf das, was der Trainer braucht
  121. datenbank.py SQLite, Wanderungen
  122. app.py HTTP-Schnittstelle
  123. frontend/ HTML, CSS, ES-Module. Kein Bauschritt, kein npm
  124. mcp/ MCP-Server, nur Standardbibliothek
  125. werkzeuge/ Beispieldaten, Sicherung
  126. tests/ 495 Tests
  127. ```
  128. Warum kein Bauschritt im Frontend: ein Vokabeltrainer soll in fünf Jahren noch
  129. starten, ohne dass sich ein Paketbaum von 2026 neu auflösen lässt.
  130. ## Tastatur
  131. | | |
  132. |---|---|
  133. | <kbd>Enter</kbd> | prüfen; danach weiter mit der automatischen Wertung |
  134. | <kbd>1</kbd>–<kbd>4</kbd> | von Hand anders werten |
  135. | <kbd>l</kbd> / <kbd>w</kbd> / <kbd>u</kbd> | lernen, Wortschatz, Übersicht |
  136. Für Akzente gibt es eine Zeichenleiste unter dem Antwortfeld. Für Sprachen
  137. mit eigener Schrift — Griechisch — lohnt ein richtiges Tastaturlayout; die
  138. Anleitung dazu steht unter `#/tastatur`.
  139. ## Stand
  140. **Fertig:** Datenmodell, Antwortprüfung, FSRS mit automatischer Bewertung,
  141. Abfrage für sechs Aufgabentypen, Wortschatzverwaltung mit Eingabemaske,
  142. Sprachprofile als Daten, Qualitätsprüfung, Wörterbuchsuche über alle Formen,
  143. Lernziele mit dynamischen Blöcken, Legastheniemodus, MCP-Server, Docker.
  144. Dazu Textverständnis: Texte einwerfen, Deckungsanalyse gegen den eigenen
  145. Wortschatz, Übersetzen je Abschnitt, fehlende Wörter beim Chatprogramm
  146. anfordern. Geführte Rundgänge und ein englischer Übungskurs zum
  147. Ausprobieren.
  148. **Als Nächstes:** Import aus CSV und Anki, Paradigma-Generator,
  149. Wiktionary-Anbindung, Diktat und Aussprache, Paradigmentabellen als
  150. Aufgabentyp, Lückensätze, Statistik.
  151. **Erwogen und vorerst abgelehnt:** eine direkt angebundene KI. Der
  152. Trainer ruft heute nirgends nach außen; alles, was eine KI tut, tut sie
  153. über den MCP-Server und das Chatprogramm der Benutzerin. Warum das so
  154. bleibt und unter welchen Bedingungen es sich ändern dürfte, steht in
  155. [02-geplant-ki-adapter.md](02-geplant-ki-adapter.md).
  156. ## Lizenz und Mitarbeit
  157. Copyright © 2026 Annuschka Brenner.
  158. Freie Software unter der [GNU Affero General Public License, Fassung 3 oder
  159. später](LICENSE). Du darfst sie benutzen, verändern und weitergeben.
  160. Die AGPL hat gegenüber den üblichen freien Lizenzen eine Besonderheit, und
  161. sie ist hier ausdrücklich gewollt: **wer eine veränderte Fassung über das
  162. Netz anbietet, muss seinen Quelltext veröffentlichen.** Wer den Trainer zu
  163. Hause im eigenen Netz betreibt — also der Normalfall —, ist davon nicht
  164. betroffen. Verbesserungen an einem Lernwerkzeug sollen aber nicht in einem
  165. geschlossenen Dienst verschwinden.
  166. Darum bietet die laufende Fassung ihren Quelltext selbst an: in der Fußzeile
  167. der Oberfläche und unter `GET /api/zustand`.
  168. **Mitarbeit am Repo ist auf Anfrage** — siehe [CONTRIBUTING.md](CONTRIBUTING.md).
  169. Fehlerberichte sind jederzeit willkommen, auch ohne Rückfrage. Für eigene
  170. Anpassungen braucht es niemanden zu fragen: abspalten und loslegen.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.