.STAGE

Mit dem StageManagerService (RAGAI.STAGE) kannst du deinen Bot in verschiedene Zustände (Stages) aufteilen. Jede Stage kann eigene Skills aktivieren, JavaScript-Code beim Betreten und Verlassen ausführen und optional eine Footer-Anzeige steuern. Stages eignen sich hervorragend für mehrstufige Dialoge, Quiz-Szenarien oder geführte Abläufe.

StageDefinition

Jede Stage wird durch ein StageDefinition-Objekt beschrieben:

Eigenschaft	Typ	Beschreibung
title	string	Anzeigename der Stage.
name	string	Eindeutiger technischer Name der Stage.
hidden	boolean (optional)	Wenn true, wird die Stage in der sichtbaren Liste ausgeblendet.
skills	string[]	Liste der Skill-IDs, die in dieser Stage aktiv sein sollen.
forceSkills	boolean (optional)	Wenn true, werden die Skills erzwungen (forciert) statt nur aktiviert.
footer	boolean	Gibt an, ob ein Footer in dieser Stage angezeigt werden soll.
enterFn	() => Promise<void> (optional)	Async-Funktion, die beim Betreten der Stage ausgeführt wird.
exitFn	() => Promise<void> (optional)	Async-Funktion, die beim Verlassen der Stage ausgeführt wird.
sortFloat	number	Sortierwert zur Bestimmung der Reihenfolge der Stages.

Properties

currentStage

Gibt die aktuell aktive Stage zurück.

const stage = RAGAI.STAGE.currentStage;
console.log(stage.name); // z. B. 'Einleitung'

beforeStageChange

Ein EventEmitter, der vor einem Stage-Wechsel ausgelöst wird. Du kannst damit Aktionen ausführen, bevor der Wechsel stattfindet.

RAGAI.STAGE.beforeStageChange.subscribe((event) => {
  console.log('Stage wird gewechselt von:', event);
});

afterStageChange

Ein EventEmitter, der nach einem Stage-Wechsel ausgelöst wird. Nutze ihn, um auf den abgeschlossenen Wechsel zu reagieren.

RAGAI.STAGE.afterStageChange.subscribe((event) => {
  console.log('Stage wurde gewechselt zu:', event);
});

stageEnter

Ein EventEmitter, der beim Betreten einer Stage ausgelöst wird.

RAGAI.STAGE.stageEnter.subscribe((stage) => {
  console.log('Stage betreten:', stage.name);
});

stageExit

Ein EventEmitter, der beim Verlassen einer Stage ausgelöst wird.

RAGAI.STAGE.stageExit.subscribe((stage) => {
  console.log('Stage verlassen:', stage.name);
});

allStages

Gibt ein Array aller registrierten Stages zurück – inklusive versteckter Stages.

const stages = RAGAI.STAGE.allStages;
console.log(stages); // [{ name: 'Start', ... }, { name: 'Ende', ... }]

visibleStages

Gibt ein Array aller sichtbaren (nicht versteckten) Stages zurück.

const sichtbar = RAGAI.STAGE.visibleStages;
console.log(sichtbar.length); // Anzahl sichtbarer Stages

---

Methoden

.add(name, stage)

Fügt eine neue Stage hinzu. Der erste Parameter ist der Name, der zweite ein partielles StageDefinition-Objekt mit den gewünschten Eigenschaften.

RAGAI.STAGE.add('Einleitung', {
  skills: ['skill-begruessung', 'skill-hilfe'],
  footer: true,
  sortFloat: 1,
  enterFn: async () => {
    console.log('Willkommen in der Einleitung!');
  },
  exitFn: async () => {
    console.log('Einleitung verlassen.');
  }
});

Du kannst auch eine minimale Stage ohne Optionen erstellen:

RAGAI.STAGE.add('Start', {
  skills: [],
  footer: false,
  sortFloat: 0
});

.remove(name)

Entfernt eine registrierte Stage anhand ihres Namens.

RAGAI.STAGE.remove('Einleitung');

.hide(name)

Verbirgt eine Stage, sodass sie nicht mehr in visibleStages aufgeführt wird. Die Stage bleibt aber registriert und kann weiterhin direkt angesteuert werden.

RAGAI.STAGE.hide('Geheim');

.show(name)

Macht eine zuvor versteckte Stage wieder sichtbar.

RAGAI.STAGE.show('Geheim');

.goTo(value)

Wechselt zur angegebenen Stage – entweder per Index (Zahl) oder per Name (String). Die exitFn der aktuellen Stage und die enterFn der Ziel-Stage werden dabei ausgeführt.

// Per Name
await RAGAI.STAGE.goTo('Einleitung');

// Per Index
await RAGAI.STAGE.goTo(0);

.goToName(name)

Wechselt zur Stage mit dem angegebenen Namen. Funktioniert wie goTo() mit einem String-Argument.

await RAGAI.STAGE.goToName('Quiz');

.goToIndex(index)

Wechselt zur Stage an der angegebenen Array-Position (0-basiert).

await RAGAI.STAGE.goToIndex(2); // Wechselt zur dritten Stage

.goToRandom(possibleNames?)

Wechselt zu einer zufällig ausgewählten Stage. Optional kannst du ein Array mit erlaubten Stage-Namen übergeben, aus dem zufällig gewählt wird. Ohne Parameter wird aus allen verfügbaren Stages gewählt.

// Zufällig aus allen Stages
await RAGAI.STAGE.goToRandom();

// Zufällig aus bestimmten Stages
await RAGAI.STAGE.goToRandom(['Quiz-1', 'Quiz-2', 'Quiz-3']);

.next()

Wechselt zur nächsten Stage in der Reihenfolge (relativ zur aktuellen Stage).

await RAGAI.STAGE.next();

.prev()

Wechselt zur vorherigen Stage in der Reihenfolge (relativ zur aktuellen Stage).

await RAGAI.STAGE.prev();

.restore()

Stellt die zuletzt verwendete Stage wieder her. Das ist nützlich, wenn du nach einem Ausflug in eine andere Stage zur vorherigen zurückkehren möchtest.

await RAGAI.STAGE.restore();

.list(includeHidden?)

Gibt ein Array mit den Namen aller registrierten Stages zurück. Mit includeHidden = true werden auch versteckte Stages aufgelistet.

// Nur sichtbare Stages
const namen = RAGAI.STAGE.list();
console.log(namen); // ['Start', 'Quiz', 'Ende']

// Alle Stages inklusive versteckter
const alle = RAGAI.STAGE.list(true);
console.log(alle); // ['Start', 'Quiz', 'Geheim', 'Ende']

---

Beispiel: Mehrstufiger Quiz-Bot

// Stages definieren
RAGAI.STAGE.add('Begrüßung', {
  skills: ['skill-willkommen'],
  footer: true,
  sortFloat: 0,
  enterFn: async () => {
    await RAGAI.SCORE.reset();
  }
});

RAGAI.STAGE.add('Frage-1', {
  skills: ['skill-frage-1'],
  footer: false,
  sortFloat: 1
});

RAGAI.STAGE.add('Frage-2', {
  skills: ['skill-frage-2'],
  footer: false,
  sortFloat: 2
});

RAGAI.STAGE.add('Ergebnis', {
  skills: ['skill-ergebnis'],
  footer: true,
  sortFloat: 3,
  enterFn: async () => {
    const punkte = RAGAI.SCORE.get();
    console.log('Erreichte Punkte:', punkte);
  }
});

// Stage-Wechsel überwachen
RAGAI.STAGE.afterStageChange.subscribe((stage) => {
  console.log('Aktuelle Stage:', stage);
});

// Zur ersten Stage wechseln
await RAGAI.STAGE.goToName('Begrüßung');