Coursmith-Kurs

Erstellen und Veröffentlichen eines Coursmith-Kurses

Sie schreiben einen Kurs als Ordner, der course.json und ein assets/-Verzeichnis enthält, prüfen ihn mit der coursmith CLI und reichen ihn ein. Ein Überprüfungsagent im Portal genehmigt ihn dann, fordert eine Überarbeitung an oder lehnt ihn ab. Ihre Aufgabe endet, wenn der Kurs genehmigt ist oder Sie dem Benutzer das Überprüfungsergebnis erläutert haben.

Führen Sie die CLI aus als npx --yes coursmith@latest <befehl> --json. Das öffentliche npm-Paket enthält die CLI und diese Fähigkeit; es ist kein GitHub-Zugriff oder eine globale Installation erforderlich. Wenn npx fehlt, bitten Sie den Benutzer, Node.js 20 oder neuer zu installieren und der Anleitung unter /install zu folgen. Mit --json gibt jeder Befehl ein JSON-Dokument aus; lesen Sie es, anstatt zu raten.

Referenzdateien in diesem Fähigkeitsordner (lesen Sie sie, wenn Sie den entsprechenden Schritt erreichen):

Datei	Verwendung
references/course.schema.json	Die genaue Struktur von course.json. Unbekannte Schlüssel werden abgelehnt.
references/block-catalog.md	Jeder Inhaltsblock und jede visuelle Darstellung, mit gültigen JSON-Beispielen und Regeln.
references/animation-presets.md	Die 7 Animationsvorgaben und wann sie verwendet werden.
references/writing-guide.md	Wie man Schritte, Glossare und Quizze schreibt, die die Überprüfung bestehen.
references/content-policy.md	Was nicht erlaubt ist und wie mit sensiblen Themen umzugehen ist.
examples/sample-course/	Ein vollständiger Kurs, der die Validierung besteht. Kopieren Sie dessen Form.

1. Anmelden

1. Führen Sie npx --yes coursmith@latest whoami --json aus. Wenn es einen username ausgibt, fahren Sie mit Schritt 2 fort.
2. Andernfalls führen Sie npx --yes coursmith@latest login --no-wait --json aus. Zeigen Sie dem Benutzer die verificationUri und den userCode und bitten Sie ihn, den Link zu öffnen, den Code zu überprüfen und auf Approve zu klicken.
3. Wenn der Benutzer bestätigt, führen Sie npx --yes coursmith@latest login --resume --json aus und prüfen Sie, ob logged_in ausgegeben wird.

2. Den Kurs mit dem Benutzer abstimmen

Fragen Sie in einer Nachricht nach allem, was der Benutzer noch nicht angegeben hat:

• Thema und, falls nützlich, den Blickwinkel oder die Zielgruppe.
• Sprache des Kurses (jede Sprache; Sie benötigen ihren BCP-47-Code wie it, en, pt-BR).
• Schwierigkeitsgrad: beginner, intermediate oder advanced.
• Optional: gewünschte Länge (Standard etwa 30 Minuten), Voraussetzungen, Dinge, die einbezogen oder vermieden werden sollen.

Prüfen Sie das Thema anhand von references/content-policy.md. Ist es nicht erlaubt, sagen Sie dies und brechen Sie ab. Handelt es sich um ein sensibles Thema (Gesundheit, Recht, Finanzen, Politik, Religion …), planen Sie eine neutrale Behandlung und einen Haftungsausschluss.

3. Eine Gliederung vorschlagen und genehmigen lassen

Zeigen Sie dem Benutzer:

• Titel, einzeiligen Untertitel, 2–6 Lernziele;
• 3–6 Abschnitte, jeweils mit einer einzeiligen Zusammenfassung und 2–5 Schritttiteln;
• für jeden Schritt die geplante visuelle Darstellung (Diagramm, Animation, Bild oder keine);
• die geplante Anzahl von Quizfragen (mindestens 10, die jeden Abschnitt abdecken).

Überarbeiten Sie, bis der Benutzer zustimmt. Schreiben Sie course.json nicht vorher.

4. Den Kurs schreiben

Erstellen Sie einen neuen Ordner, benannt nach dem Kurs (kebab-case), mit course.json und assets/. Folgen Sie genau references/course.schema.json und kopieren Sie die Struktur von examples/sample-course/course.json.

Regeln, die der Validator durchsetzt (Details in references/block-catalog.md):

• schemaVersion ist "1.0". Schreiben Sie courseId nicht: Die CLI verwaltet es.
• Alle IDs sind Kleinbuchstaben, Ziffern und Bindestriche, kursweit eindeutig (Abschnitte, Schritte, Assets, Quizfragen).
• Jeder Schritt hat einen title und mindestens einen Block; die meisten Schritte haben auch eine visual.
• Glossar: Jeder Abschnitt hat ein glossary, das jedes Konzept definiert, das er einführt, und jeden technischen oder domänenspezifischen Begriff, den er verwendet. Markieren Sie im Text jeden Begriff als [[term]] oder [[term|angezeigter Text]], wenn die Schreibweise abweicht (verwenden Sie aliases für Pluralformen und Beugungen). Ein markierter Begriff muss im selben Abschnitt oder einem früheren definiert sein. Definitionen sind in sich geschlossen und in der Kurssprache verfasst.
• Visuelle Darstellungen: Diagramme sind Vega-Lite-Spezifikationen mit Inline-data.values (keine URLs); Diagramme sind Mermaid ohne click oder %%{init}%%; Animationen verwenden eine der 7 Vorgaben; Bilder verweisen auf ein Asset per ID.
• Markdown: Kein rohes HTML, keine Markdown-Bilder (verwenden Sie einen Bildblock), Links müssen https:// sein.
• Abschlussquiz: Mindestens 10 Fragen; jeder Abschnitt wird durch mindestens eine Frage getestet (sectionRef); jede Frage hat eine explanation. Typen: single, multiple, true_false, ordering (Reihenfolge-Elemente sind in der richtigen Reihenfolge aufgelistet; das Portal mischt sie).
• Optionale check-Fragen am Ende eines Schrittes geben Lernenden schnelles Feedback und werden nicht bewertet.

Schreiben Sie Abschnitt für Abschnitt und halten Sie Sprache, Schwierigkeitsgrad und Terminologie durchgängig konsistent (siehe references/writing-guide.md).

5. Die Assets erstellen

• Ein Titelbild ist erforderlich (meta.coverImage), idealerweise 1200×630.
• Wenn Sie ein Bildgenerierungswerkzeug haben, erstellen Sie PNG-, JPEG- oder WebP-Dateien. Andernfalls schreiben Sie sauberes SVG von Hand: einfache Formen, eine klare Palette, viewBox gesetzt, keine Skripte, keine externen Links oder Schriftarten, keine eingebetteten Bilder.
• Für eine highlight-svg-Animation geben Sie den hervorzuhebenden Elementen ein id-Attribut.
• Legen Sie jede Datei direkt in assets/ und deklarieren Sie sie in assets[] mit kind (image oder svg), file (assets/<name>) und einem sinnvollen alt-Text. Füllen Sie generatedBy für KI-generierte Bilder aus.
• Jede Datei muss unter 3 MB sein; das gesamte Bündel unter 25 MB.

6. Validieren, bis keine Fehler mehr vorhanden sind

Führen Sie npx --yes coursmith@latest validate <ordner> --json aus. Es gibt { "ok": ..., "issues": [...] } aus; jedes Problem hat severity, code, path (z.B. sections[1].steps[0].blocks[2]) und message.

Beheben Sie jeden error, dann führen Sie es erneut aus. Wiederholen Sie dies, bis ok true ist. Beheben Sie auch Warnungen, wenn sie schnell zu beheben sind (z.B. glossary.unreferenced: markieren Sie den Begriff mit [[...]], wo er verwendet wird).

7. Einreichen und der Überprüfung folgen

1. Führen Sie npx --yes coursmith@latest submit <ordner> --json aus. Es lädt den Kurs hoch und gibt status: "in_review" mit einer submissionId aus. Die CLI schreibt .coursmith.json in den Ordner; behalten Sie es, da es spätere Einreichungen mit demselben Kurs verknüpft.
2. Führen Sie npx --yes coursmith@latest status --dir <ordner> --wait --json aus (es wartet bis zu 10 Minuten; führen Sie es erneut aus, wenn der Status immer noch in_review ist).
3. Handeln Sie entsprechend dem status:
   • approved: Geben Sie dem Benutzer die courseUrl. Erwähnen Sie optionale Vorschläge in review.issues.
   • needs_revision: Öffnen Sie für jedes Problem in review.issues das Element unter path, wenden Sie den suggestion an (oder beheben Sie, was message beschreibt), validieren Sie dann und reichen Sie erneut ein. Teilen Sie dem Benutzer mit, was Sie geändert haben. Probleme mit severity: "warning" sind optional.
   • rejected: Erklären Sie dem Benutzer review.summary. Reichen Sie denselben Inhalt nicht erneut ein.

Wenn submit review_in_progress meldet, warten Sie zuerst mit status --wait auf die aktuelle Überprüfung.

Aktualisieren eines veröffentlichten Kurses

Bearbeiten Sie denselben Ordner (behalten Sie .coursmith.json) und reichen Sie erneut ein. Die neue Version durchläuft die Überprüfung, während die aktuelle online bleibt; halten Sie Schritt-IDs stabil, damit Lernende ihren Fortschritt behalten.

Fehlerbehebung

CLI-Ausgabe	Maßnahme
not_logged_in / Exit-Code 3	Gehen Sie zurück zu Schritt 1.
client_outdated	Wiederholen Sie mit npx --yes coursmith@latest, damit npm die neueste CLI abruft.
validation_failed von submit	Führen Sie validate aus und beheben Sie die aufgeführten Probleme.
rate_limited	Der Benutzer hat das tägliche Einreichungslimit erreicht; versuchen Sie es morgen erneut.
assets.content_type / assets.invalid	Der Dateiinhalt stimmt nicht mit der Erweiterung überein oder ist beschädigt. Exportieren Sie sie neu.
animation.unknown_element	Dem SVG fehlt ein Element mit dieser id (IDs bleiben erhalten, Skripte und externe Links werden entfernt).