bollwerkadmin/bollwerk
1
0
Fork 0
Code Issues 8 Pull requests Projects Releases Packages Wiki Activity Actions
bollwerk/.github/skills/resource-import/SKILL.md

7 KiB
Raw Blame History

name description
resource-import Freie Bücher und andere Ressourcen (ePub, PDF) mit vollständigen Metadaten recherchieren und in die Bollwerk-App importieren. Nutze diesen Skill wenn neue Ressourcen gesucht, zusammengestellt oder importiert werden sollen. Trigger-Phrasen: 'Bücher importieren', 'freie Bücher', 'Ressourcen importieren', 'neue Bücher', 'Gutenberg', 'ePub', 'Ressource hinzufügen', 'Import Ressourcen', 'Bibliothek erweitern', '10 Bücher', 'Leseliste'.

Skill: Ressourcen-Import (freie Bücher mit Metadaten)

Recherchiert freie Bücher (Public Domain / Creative Commons) und importiert sie als Ressourcen in die Bollwerk-App. Enthält den gesamten Workflow: Auswahl → Metadaten → Download → Upload.

Kontext

Die Bollwerk-App hat eine Ressourcen-Bibliothek mit ePub/PDF-Dateien. Der Server speichert pro Ressource:

Feld Typ Beschreibung
guid String UUID, wird beim Upload generiert
title String Buchtitel
author String? Autor(en)
description String 2–3 Sätze, deutsch, themenrelevant
tags List Kategorie-Tags (siehe unten)
fileFormat String epub oder pdf
mimeType String application/epub+zip / application/pdf
fileSize Long Wird beim Upload automatisch gesetzt
releaseDate String? Erstveröffentlichung (ISO oder Jahreszahl)
language String? ISO-639-1 Sprachcode (en, de, etc.)
edition String? Ausgabe/Übersetzung
createdAt Long Epoch-Millisekunden (automatisch)
updatedAt Long Epoch-Millisekunden (automatisch)
downloadUrl String Server setzt dies auf /api/resources/{guid}/download

Bekannte Tags

  • nachschlagewerk – Sachbuch, Lexikon, Ratgeber
  • handbuch – Praxisorientiertes How-To
  • novel – Belletristik, Roman, Novelle
  • abenteuer – Abenteuer-/Entdeckerthematik
  • quellenbuch – Inspirationsquelle / Settingbuch

Neue Tags dürfen bei Bedarf ergänzt werden, sollten aber zur bestehenden Systematik passen (Singular, Kleinbuchstaben, deutsch).

Quellen für freie Bücher

Quelle URL Formate Lizenz
Project Gutenberg https://www.gutenberg.org ePub, txt Public Domain
Standard Ebooks https://standardebooks.org ePub Public Domain
Internet Archive (OpenLib) https://archive.org ePub, PDF Gemischt
ManyBooks https://manybooks.net ePub, PDF Public Domain

Gutenberg-Download-URLs (Priorität)

1. https://www.gutenberg.org/ebooks/{id}.epub.noimages   (klein, schnell)
2. https://www.gutenberg.org/ebooks/{id}.epub3.images    (mit Bildern)
3. https://www.gutenberg.org/cache/epub/{id}/pg{id}.epub (Fallback)

Workflow

1. Auswahl (Recherche)

Wenn der User z.B. sagt "importiere 10 gute freie Bücher":

  1. Thema klären – Was für Bücher? (Klassiker, Survival, Philosophie, Horror, etc.)
  2. Lizenz sicherstellen – Nur Public Domain oder explizit freie Lizenzen.
  3. Duplikate prüfen – Über GET /api/resources oder lokal prüfen, was bereits vorhanden ist.
  4. Liste zusammenstellen – Pro Buch:
    • Gutenberg-ID (oder Download-URL)
    • Titel, Autor
    • Deutsche Beschreibung (2–3 Sätze, für den Bollwerk-Kontext relevant)
    • Tags, Sprache, Erscheinungsjahr, Edition/Übersetzung

2. Import-Skript generieren/aktualisieren

Das Projekt hat bereits import-books.py als Referenzimplementierung. Für neue Imports:

  • Entweder das bestehende Skript mit neuer BOOKS-Liste anpassen
  • Oder ein neues spezialisiertes Skript erstellen

Skript-Struktur (Python, nur stdlib):

BOOKS = [
    {
        "gutenberg_id": 132,
        "title": "The Art of War",
        "author": "Sun Tzu",
        "description": "Deutsche Beschreibung, 2-3 Sätze.",
        "tags": ["nachschlagewerk", "handbuch"],
        "language": "en",
        "release_date": "-500",
        "edition": "Lionel Giles Translation, 1910",
    },
    # ...
]

3. Ausführung

# Voraussetzungen
$env:BOLLWERK_ADMIN_USER = "<admin-username>"
$env:BOLLWERK_ADMIN_PASS = "<admin-password>"

# Import starten
python import-books.py

# Nur Download testen (kein Upload)
python import-books.py --dry-run

4. Verifizierung

Nach dem Import:

  1. Server-Health prüfen: GET /api/health
  2. Ressourcen-Liste abrufen: GET /api/resources (Auth-Token nötig)
  3. Stichprobe: Ein Buch per GET /api/resources/{guid}/download herunterladen

API-Endpunkte (Admin)

Methode Endpunkt Beschreibung
POST /api/admin/resources Ressource hochladen (multipart)
PUT /api/admin/resources/{guid} Metadaten aktualisieren
DELETE /api/admin/resources/{guid} Ressource löschen
GET /api/admin/resources/tags Alle Tags mit Häufigkeit
POST /api/admin/resources/analyze Datei analysieren (ohne Speichern)

Multipart-Upload-Format

POST /api/admin/resources
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=...

Part 1: name="metadata", Content-Type: application/json
  → ResourceDto als JSON

Part 2: name="file", filename="<guid>.epub"
  → Datei-Bytes (max 25 MB)

Qualitätskriterien für Beschreibungen

  • Sprache: Deutsch
  • Länge: 2–3 Sätze
  • Inhalt: Was ist das Buch? Warum ist es relevant/interessant?
  • Keine Spoiler bei Belletristik
  • Kontext-Bezug: Wenn möglich, Relevanz für Rollenspiel/Abenteuer/Strategie/Überleben hervorheben (passend zum Bollwerk-Thema)

Checkliste vor Import

  • Alle Bücher sind Public Domain oder frei lizenziert
  • Keine Duplikate mit bestehenden Ressourcen
  • Deutsche Beschreibungen vorhanden
  • Tags passen zur bestehenden Systematik
  • Gutenberg-IDs / Download-URLs verifiziert
  • --dry-run erfolgreich (alle Downloads funktionieren)
  • Env-Vars für Admin-Credentials gesetzt

Referenz-Dateien

  • import-books.py – Bestehende Importimplementierung (10 Klassiker)
  • shared/src/main/kotlin/de/bollwerk/shared/model/ResourceDto.kt – Datenmodell
  • server/src/main/kotlin/de/bollwerk/server/routes/ResourceRoutes.kt – API-Endpunkte
  • server/src/main/kotlin/de/bollwerk/server/service/ResourceAnalyzer.kt – Dateianalyse (epub/pdf/images)