Apps

Experimentell Premium-Funktion

Eine App ist eine Oberfläche, die in einem Projekt gebaut, in einen Katalog veröffentlicht und dort als benannte, fortsetzbare Instanz geöffnet wird. Was jemand einträgt, bleibt erhalten und wird live übertragen: Dieselbe App auf Laptop und Telefon bleibt im Gleichstand.

Der Unterschied zu einem Chat: Eine App überdauert das Gespräch. Sie hat einen eigenen Zustand, eine eigene Adresse und eine eigene Lebensdauer.

Dorthin gelangen und die erste App bauen

Wo sie zu finden ist: Öffnen Sie Apps in der linken Seitenleiste. Fehlt der Eintrag, ist die Funktion für Ihren Arbeitsbereich noch nicht freigeschaltet — siehe Freischalten.

Die Seite listet die verfügbaren Apps, Ihre eigenen gespeicherten Instanzen und, unter Meine Entwürfe, die Apps, an denen Sie gerade bauen. Neue App fragt zuerst, zu welchem Projekt der Entwurf gehören soll, und öffnet dann den App-Builder mit einem leeren Dokument. Sie brauchen dafür weder einen API-Schlüssel noch eine Zeile JSON.

Der Baukasten in fünf Spalten

Spalte	Wofür sie da ist
Komponenten	Die Palette. Ein Klick setzt die Komponente in das gerade ausgewählte Element.
Struktur	Der Baum des Dokuments: auswählen, per Ziehen umsortieren, Löschen.
Vorschau	Die App, wie sie aussehen wird — in Auswählen zum Bauen, in Interagieren zum Ausprobieren.
Inspektor	Alles am ausgewählten Element: Eigenschaften, Daten, Assistent, Aktion.
Assistent fragen	Ein Assistent, der dasselbe Dokument bearbeitet wie Sie.

Gespeichert wird laufend — „Wird gespeichert…" erscheint kurz im Kopf, ein Speichern-Knopf existiert nicht. Rückgängig und Wiederholen liegen links in der Werkzeugleiste und benennen im Tooltip, was sie zurücknehmen würden („Card hinzugefügt", „Element verschoben").

Die ersten fünf Minuten

1. Neue App → Projekt auswählen → Erstellen. Der Baukasten öffnet sich mit einer leeren Karte als Wurzel.
2. Wurzelelement im Baum auswählen, dann in Komponenten auf Card klicken — und in dieser Karte auf Input und Text.
3. Den Input auswählen, im Inspektor unter Eigenschaften neben value auf An Zustand binden klicken, als Zeiger /name eintragen und Übernehmen wählen. Dasselbe für die Eigenschaft text des Text-Elements.
4. Oben auf Interagieren umschalten und in das Feld tippen: Der Text darunter folgt sofort. Beide Elemente hängen an derselben Stelle im Zustand.
5. Veröffentlichen → im Dialog Alle auf dieser Instanz wählen → Veröffentlichen. Die App erscheint unter Apps; ein Klick auf Neue Kopie startet sie als Instanz. Was dort eingetragen wird, ist beim nächsten Öffnen noch da.

Damit ein Knopf etwas tut, bekommt er im Inspektor unter Aktion ein Werkzeug des Projekts zugewiesen — siehe Ein Knopf kann sofort etwas tun.

Testen und Veröffentlichen sind zwei verschiedene Knöpfe

• Testen veröffentlicht den aktuellen Stand privat: Die Version taucht im Katalog nicht auf, aber es entsteht sofort eine echte Instanz, die sich öffnet. Ein halbfertiger Entwurf wird dadurch also nicht für andere sichtbar. Testen fragt nichts nach — es veröffentlicht immer privat.
• Veröffentlichen fragt zuerst, wer die Version sehen darf (siehe unten), und stellt sie erst danach ein.

Wer die veröffentlichte App sehen darf

Veröffentlichen öffnet einen Dialog mit zwei Möglichkeiten. Die Vorgabe ist immer Nur ich — auch dann, wenn Sie beim letzten Mal etwas anderes gewählt haben.

• Nur ich. Die Version bleibt aus dem App-Katalog heraus. Nur Sie können sie öffnen. Das ist dieselbe Sichtbarkeit, die auch Testen verwendet.

• Alle auf dieser Instanz. Die Version kommt in den App-Katalog — und der Katalog ist die gesamte Instanz: jede angemeldete Person dieser BasePeak.AI-Instanz kann die App dort finden und starten, nicht nur die Mitglieder Ihres Projekts. Eine feinere Freigabe (pro Person oder pro Gruppe) gibt es noch nicht.

  Zurücknehmen lässt sich das nur, indem eine Administratorin oder ein Administrator die App archiviert — und Archivieren kann nicht rückgängig gemacht werden: Ist eine App einmal archiviert, lässt sich keine weitere Version davon veröffentlichen, auch nicht von Ihnen. Wählen Sie diese Möglichkeit also erst, wenn die App wirklich für alle gedacht ist.

Nach dem Veröffentlichen steht im Baukasten, was passiert ist: „Veröffentlicht — im App-Katalog sichtbar." beziehungsweise „Privat veröffentlicht — nicht im App-Katalog gelistet."

Sie können jederzeit erneut veröffentlichen und dabei eine andere Möglichkeit wählen; jede Veröffentlichung ist eine eigene Version.

Der Unterschied ist wichtiger, als er klingt: Aktionen laufen in der Vorschau nicht. Hinter der Vorschau steht keine Instanz, gegen die ein Werkzeugaufruf laufen könnte, und der Baukasten sagt das auch: „Aktionen laufen nur in einer veröffentlichten App — nutze ‚Testen', um sie wirklich auszuführen." Testen ist der kurze Weg dorthin.

Findet die Prüfung beim Bearbeiten etwas, das eine Veröffentlichung nicht überstehen würde — ein Element, das von der Wurzel aus nicht erreichbar ist, eine Eigenschaft mit der falschen Form —, steht das unter der Werkzeugleiste und beide Knöpfe sind deaktiviert, bis es behoben ist.

Der Assistent baut mit, im selben Dokument

Ganz rechts liegt Assistent fragen. Was Sie dort beschreiben, wird als Änderung am gleichen Dokument ausgeführt, das auch Palette, Baum und Inspektor bearbeiten — es gibt keine zweite Fassung, die auseinanderlaufen könnte. Die Änderungen erscheinen, während die Antwort noch läuft.

Zwei Eigenschaften sind dabei wichtig:

• Ein Zug des Assistenten ist genau ein Schritt. Fügt er auf eine Bitte hin drei Elemente ein, nimmt ein Klick auf Rückgängig alle drei zusammen zurück — nicht eines davon.
• Es ist ein gemeinsamer Stapel. Ihre eigenen Handgriffe und die Züge des Assistenten liegen in derselben Reihenfolge übereinander; im Tooltip von Rückgängig steht bei einem Zug des Assistenten dessen eigene Zusammenfassung. Eine gewöhnliche Änderung nach einem Rückgängig verwirft den Wiederholen-Stapel, wie überall sonst auch.

Bricht eine Antwort ab, bleibt erhalten, was bereits übernommen wurde — der Baukasten weist darauf hin und überlässt Ihnen, ob Sie es rückgängig machen oder noch einmal fragen.

Dieser Assistent ist nicht der Assistent Ihres Projekts, sondern ein eingebauter Baukasten-Assistent. Er bearbeitet Entwürfe und kommt an den Zustand einer laufenden Instanz nicht heran.

Wenn ein Werkzeug fehlt

Die Werkzeugauswahl unter Aktion zeigt die Werkzeuge dieses Projekts. Nennt das Dokument ein Werkzeug, das dort nicht vorkommt, warnt der Inspektor:

Das gebundene Werkzeug „…" ist in diesem Projekt nicht verfügbar — wer diese App ausführt, könnte ein Projekt wählen, das es hat.

Die Bindung bleibt dabei erhalten, sie wird nicht stillschweigend verworfen.

Was die Warnung bedeutet — und was nicht

Sie bedeutet: Das Werkzeug gehört gar nicht zum Werkzeugbestand dieses Projekts. Sie bedeutet nicht, dass ein Werkzeug gerade abgeschaltet ist. Ein Werkzeug, das in der Projektkonfiguration unter Werkzeuge auf „aus" steht, dem Agenten aber weiterhin zur Verfügung steht, wird von einer Aktion trotzdem ausgeführt — und deshalb wird dafür auch nicht gewarnt. Der Schalter im Projekt steuert, was der Assistent im Gespräch von sich aus benutzt; ob eine Aktion laufen darf, entscheidet der Werkzeugbestand des Agenten.

Der Lebensweg einer App

Schritt	Was entsteht	Wer macht es
Entwurf	Ein Dokument im Projekt	Wer die App baut
Veröffentlichen	Eine unveränderliche Version im Katalog	Wer die App baut
Instanz	Eine laufende Kopie mit eigenem Zustand	Wer die App benutzt

Eine veröffentlichte Version ist unveränderlich. Instanzen bleiben an die Version geheftet, mit der sie angelegt wurden. Ein erneutes Veröffentlichen stört deshalb niemanden, der gerade mitten in einer Eingabe steckt — laufende Instanzen laufen unbeirrt auf ihrer Version weiter.

Veröffentlichen erweitert keine laufende Instanz

Das gilt auch in die andere Richtung, und das ist die wichtigere: Wer einen Entwurf um weitere Freigaben für den Assistenten ergänzt und neu veröffentlicht, gibt damit keiner bereits laufenden Instanz neue Möglichkeiten. Deren Werkzeuge werden bei jedem Zug aus der Version abgeleitet, an die sie geheftet ist. Wer eine App vor echtem Publikum betreibt, kann sich darauf verlassen.

Den Katalog erreichen Sie über Apps in der Seitenleiste. Er zeigt sowohl die verfügbaren Apps als auch die eigenen gespeicherten Instanzen zum Fortsetzen.

Ein Assistent kann mitarbeiten

Dies ist der zweite, andere Chat: nicht der Baukasten-Assistent, der am Entwurf arbeitet, sondern ein Assistent in der laufenden App, der mit deren Daten arbeitet.

Rechts neben einer geöffneten App lässt sich ein Chat-Bereich aufziehen — über die Lasche am rechten Rand. Er teilt sich die Fläche mit der App, statt sie zu verdecken, und die Trennlinie lässt sich verschieben: So bleibt das Dokument im Blick, während der Assistent daran arbeitet. Auf dem Telefon nimmt der Bereich die ganze Breite ein.

Wer dort eines seiner Projekte auswählt und eine Nachricht schickt, gibt dem Assistenten dieses Projekts Werkzeuge für genau die Teile der App, die deren Autorin oder Autor freigegeben hat — nicht mehr und nicht weniger.

Im Screenshot oben ist das Formular vollständig aus einem Satz Fließtext entstanden: Kunde, Menge und beide Tabellenzeilen hat der Assistent gesetzt.

Freigabe geschieht Element für Element

Die Freigabe wird beim Bauen der App vergeben, an jedem einzelnen Element — im Inspektor unter Assistent:

• Vom Assistenten lesbar — der Assistent darf den Wert sehen.
• Vom Assistenten beschreibbar — der Assistent bekommt ein Werkzeug, um den Wert zu ändern.
• nicht markiert — das Element ist für den Assistenten nicht vorhanden.

Nichts ist standardmäßig freigegeben

Ein Element ohne Markierung ist unsichtbar — es gibt kein Werkzeug, über das ein Assistent es überhaupt versuchen könnte, und die Schnittstelle, die Schreibzugriffe annimmt, weist jeden Pfad zurück, für den sie kein Werkzeug erzeugt hätte.

Im Screenshot oben steht in Interne Notiz ein Text, den der Mensch sieht. Auf die Frage, was dort steht, antwortet der Assistent, dass er kein solches Feld findet. Genau so ist es gedacht: Der Mensch sieht alles, der Assistent nur das Markierte.

Woran die Grenze hängt

Drei Eigenschaften tragen diese Zusage:

1. Die erzeugten Werkzeuge sind die Durchsetzung. Es gibt keine zweite Liste, die man vergessen könnte zu pflegen. Werkzeugangebot und Schreibprüfung werden aus demselben Dokument abgeleitet und können deshalb nicht auseinanderlaufen.
2. Abgeleitet wird bei jedem Zug neu, aus der Version, an die die Instanz geheftet ist. Ein erneutes Veröffentlichen mit mehr Freigaben erweitert eine laufende Instanz deshalb nicht.
3. Abwesenheit bedeutet Verweigerung. Fehlt die Markierung, fehlt der Zugriff.

Was der Assistent zurückmeldet

Wird ein Schreibzugriff abgelehnt, nennt die Antwort den betroffenen Pfad. Das ist kein Detail für Entwickler: Nur dadurch kann das Modell sich selbst korrigieren und etwas anderes versuchen, statt denselben abgelehnten Aufruf zu wiederholen.

Ebenso wird ein Wert abgelehnt, der nicht zur angegebenen Form passt — etwa Text in einem Feld, das als ganze Zahl deklariert ist.

Ein annotiertes Element

Der Inspektor schreibt in das Dokument, was Sie eintragen. So sieht die Freigabe dort aus — die Felder Zweck, Datenform und die beiden Häkchen unter Assistent:

"customerField": {
  "type": "Input",
  "props": { "label": "Kunde", "value": { "$bindState": "/customer" } },
  "annotation": { "purpose": "Der Kunde, für den dieses Angebot erstellt wird." },
  "agent": { "readable": true, "writable": true }
}

• annotation.purpose wird zur Beschreibung des erzeugten Werkzeugs. Sie ist das, woran das Modell erkennt, wofür ein Feld da ist — hier lohnt sich ein klarer Satz. Beschreiben Sie, was das Element tut: Ein Zweck, der eine Einschränkung formuliert („darf nicht …"), landet unverändert in der Werkzeugbeschreibung und kann dazu führen, dass der Assistent es gar nicht erst versucht. Der Inspektor weist darauf hin.
• annotation.dataShape (optional) beschränkt, was eingetragen werden darf, und wird bei jedem Schreibzugriff geprüft.
• agent vergibt die Freigabe.

Ein Element ganz ohne agent-Block — wie Interne Notiz im Beispiel — bleibt dem Assistenten verborgen.

Ein Knopf kann sofort etwas tun

Manche Elemente sind nicht nur mit einem Wert verbunden, sondern mit einer Aktion: Ein Klick löst sie sofort aus — ohne dass die KI erst nachdenken muss. Ein Knopf kann zum Beispiel etwas nachschlagen, eine Nachricht verschicken oder einen anderen Dienst aufrufen, und das Ergebnis erscheint augenblicklich im Dokument.

Wer die App baut, legt für so einen Knopf im Inspektor unter Aktion fest, was er tut: welches Werkzeug, mit welchen Parametern, und an welche Stelle im Zustand das Ergebnis beziehungsweise ein Fehler geschrieben wird (Ergebnis-Zeiger und Fehler-Zeiger). Beim Klick sammelt die App die aktuellen Eingaben, führt die Aktion im Hintergrund aus und trägt das Ergebnis dort ein. Für heikle Aktionen lässt sich zusätzlich eine Rückfrage einblenden, die erst bestätigt werden muss, bevor etwas passiert.

Steht ein solcher Knopf in einer Liste, kann er gezielt auf die Zeile wirken, in der er steht: „Diese Bestellung nachschlagen" betrifft nur die angeklickte Zeile, nicht die ganze Liste.

Der Assistent kann dieselben Knöpfe drücken

Ein Knopf, den seine Autorin oder ihr Autor dafür ausdrücklich freigegeben hat (Vom Assistenten aufrufbar), lässt sich auch vom Assistenten im Chat-Bereich drücken — mit demselben Ergebnis wie ein menschlicher Klick, und bei einer Zeile in einer Liste sagt der Assistent dazu, welche Zeile er gemeint hat. Eine Rückfrage am Knopf schützt nur den menschlichen Klick: Drückt der Assistent denselben Knopf, bekommt er sie nicht zu sehen und führt die Aktion sofort aus.

Ist ein Knopf nicht für den Assistenten freigegeben, oder ist der Dienst dahinter für dieses Projekt gar nicht verfügbar, bekommt der Assistent das genannt und probiert es nicht einfach noch einmal mit demselben Aufruf — genau wie bei einem abgelehnten Schreibzugriff weiter oben.

Listen und Wiederholungen

Ein Container kann sich über eine Liste im Zustand wiederholen: Im Inspektor unter Daten schalten Sie Wiederholt sich über eine Liste ein, tragen unter Wiederholt über den Zeiger auf die Liste ein (etwa /orders) und unter Zeilenschlüssel das Feld, das eine Zeile eindeutig macht (etwa id).

Elemente innerhalb dieser Wiederholung binden nicht an den Zustand als Ganzes, sondern an ein Feld der jeweiligen Zeile: Der Inspektor beschriftet das Zeigerfeld dann als Zeilenbezogener Zeiger, und dort steht name, nicht /orders/0/name. Jede Zeile bekommt so ihre eigene Fassung desselben Elements — ein Eingabefeld in Zeile 1 schreibt in Zeile 1, eines in Zeile 2 in Zeile 2.

Grenzen dieser Ausbaustufe

Diese Punkte sind bewusst so gewählt und werden in einer späteren Ausbaustufe aufgehoben:

• Elemente innerhalb einer Wiederholung erreicht ein Assistent nicht, auch wenn sie markiert sind. Für Menschen funktionieren sie; dem Assistenten fehlt die zeilengenaue Adressierung, und im Zweifel wird lieber gar nichts freigegeben.
• Tabellen und Listen werden immer als Ganzes geschrieben. Wer den Assistenten bittet, eine Position zu ergänzen, bekommt die vollständige neue Liste — es gibt keine schmalere Operation.
• Eine Zeile lässt sich nur ansteuern, nicht ändern. Eine Aktion kann gezielt auf eine Zeile einer Liste wirken — sie lesen, einen Dienst mit ihren Werten aufrufen —, aber einen einzelnen Wert in genau dieser Zeile ändern kann weiterhin nur ein kompletter Listenaustausch, wie oben beschrieben.
• Aktionen laufen kurz. Eine Aktion, die länger als eine knappe Minute braucht, wird abgebrochen; für lang laufende Abläufe gibt es noch kein eigenes Modell.
• Für den Chat-Bereich muss man das gewählte Projekt besitzen. Ein Projekt, in dem man nur Mitglied ist, steht dort noch nicht zur Auswahl.

Apps aus einem Programm heraus anlegen

Der Baukasten ist der übliche Weg. Wer Entwürfe aus einem anderen System heraus anlegen oder pflegen will — etwa aus einer Vorlage, einem Skript oder einer Migration —, kann denselben Entwurf über die API bearbeiten. Es ist dasselbe Dokument; beide Wege können sich abwechseln.

Nötig ist ein API-Schlüssel mit den Geltungsbereichen project:widgets (lesen) und project:widgets-write (schreiben). Adressiert wird über die Projekt-ID:

Route	Geltungsbereich
GET /api/projects/{projekt}/widgets	project:widgets
POST /api/projects/{projekt}/widgets	project:widgets-write
GET /api/projects/{projekt}/widgets/{id}	project:widgets
PUT /api/projects/{projekt}/widgets/{id}	project:widgets-write
PATCH /api/projects/{projekt}/widgets/{id}/document	project:widgets-write
POST /api/projects/{projekt}/widgets/{id}/undo bzw. /redo	project:widgets-write
DELETE /api/projects/{projekt}/widgets/{id}	project:widgets-write

Undo und Redo gehören zum Schreibrecht: Wer ein Dokument ohnehin vollständig ersetzen darf, gewinnt nichts hinzu, wenn er es stattdessen abschnittsweise ändert oder einen eigenen Fehler zurücknimmt.

Das kleinste Dokument, das funktioniert:

das Dokument

{
  "version": 1,
  "root": "card",
  "elements": {
    "card":  { "type": "Card",  "props": { "title": "Erste App" }, "children": ["name", "shown"] },
    "name":  { "type": "Input", "props": { "label": "Ihr Name", "value": { "$bindState": "/name" } } },
    "shown": { "type": "Text",  "props": { "text": { "$bindState": "/name" } } }
  },
  "state": { "name": "" }
}

# Entwurf anlegen (das Dokument oben als {"name": …, "document": …} verpacken)
curl -X POST "$BASE/api/projects/$PROJECT/widgets" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"name":"Erste App","document":{ … }}'

Der Entwurf steht danach unter Apps → Meine Entwürfe und lässt sich im Baukasten weiterbearbeiten.

Was ein API-Schlüssel nicht kann

Veröffentlichen gehört nicht zu dieser Fläche. Weder …/publish noch der Katalog noch Instanzen sind für Schlüssel freigegeben — eine App wird von einem Menschen im Baukasten veröffentlicht. Ebenso wenig erreicht ein Schlüssel den Ereignisstrom …/widgets/{id}/events: Eine dauerhaft offene Verbindung an einem langlebigen Zugangsdatum ist etwas anderes als ein einzelner Aufruf. Wer den aktuellen Stand braucht, holt ihn per GET.

Die vollständigen Feldbeschreibungen stehen im Entwicklerhandbuch docs/widget-apps.md im Quellcode-Repository.

Verwaltung für den ganzen Arbeitsbereich

Im Administrationsbereich unter Apps steht jede auf dieser Instanz veröffentlichte App, eine Zeile pro Version — auch private Versionen und solche, deren Herausgeber die Instanz verlassen hat. Die Seite verlangt die Berechtigung app:manage; ohne sie ist sie nicht erreichbar. Sie ergänzt die bisherige Administratorrolle, sie ersetzt sie nicht.

Zwei Eingriffe gibt es dort, beide für die ganze App und nicht nur für die angeklickte Zeile:

• Archivieren — es entstehen keine neuen Instanzen mehr, für alle Versionen dieser App. Bereits laufende Instanzen bleiben bestehen. Das lässt sich nicht rückgängig machen, und es gilt auch gegenüber der herausgebenden Person: Ein späteres Veröffentlichen derselben App wird abgelehnt, die App lässt sich also nicht durch erneutes Veröffentlichen in den Katalog zurückholen.
• Löschen — entfernt alle Versionen dieser App und alle laufenden Instanzen. Ebenfalls endgültig.

Beide fragen vorher nach und nennen dabei, was genau passiert.

Freischalten

Apps sind standardmäßig ausgeschaltet und müssen für den Arbeitsbereich freigeschaltet werden (Funktionsschlüssel apps). Solange das nicht geschehen ist, ist /apps nicht erreichbar und sämtliche zugehörigen Schnittstellen antworten mit „nicht freigegeben".

Ein Wechsel des Projekts im Chat-Bereich beginnt übrigens eine neue Unterhaltung. Die vorherige wird nicht verworfen: Sie bleibt dort, wo sie war, bei dem Projekt, zu dem sie gehörte.