Zum Inhalt springen
Geprüft

Der Studio-LLM-Leitfaden

Das Prog-Dokumentmodell, die xu-*-Attributreferenz und die Workflow-Regeln, die einem KI-Agenten vor seinem ersten Tool-Aufruf beigebracht werden.

Jedes Studio-Projekt, jede Tabelle, jeder Bildschirm, jedes Skript und jede Route darin ist ein CouchDB-JSON-Dokument namens Prog (docType: "studio"). Diese Seite ist dieselbe Referenz, die ein KI-Agent erhält, wenn er eines baut, als Dokumentation umgeschrieben: die Form dieses Dokuments, die Attribute, die seine Oberfläche steuern, die Aktionen, die ein Workflow ausführen kann, und die Fehler, die in echten Builds auftauchen.

Wie ein KI-Agent diesen Leitfaden bekommt

Verbinde einen MCP-Client mit Xuda, und die erste Antwort, der initialize-Aufruf, trägt diesen Leitfaden als instructions der Sitzung, frisch aus den eigenen Live-Regeln der Plattform zusammengeführt, damit er nie etwas beschreibt, das der bereitgestellte Checker nicht mehr durchsetzt. Siehe Einen KI-Client über MCP verbinden.

Innerhalb einer Sitzung erreichen zwei Methoden dasselbe Material direkt, über MCP oder einfaches REST, und brauchen nichts über einen normalen API-Schlüssel hinaus:

Die vorgeschriebene Reihenfolge: Lies das Thema, das zu dem passt, was du baust, hole ein passendes Beispiel, erstelle das Prog über die Factory (create_prog), baue innerhalb seiner Inhaltsabschnitte, validiere (validate_prog) und behebe alles, was gemeldet wird, speichere (save_prog) und hole es dann erneut, um zu prüfen. Ein Speichern, das -409 zurückgibt, bedeutet, dass sich das Dokument seit dem Lesen geändert hat: erneut holen, erneut anwenden, erneut versuchen.

Das Prog-Dokumentmodell

Die Hülle

Der Server- und Factory-Code besitzt diese Felder; ein erstellter Bau bearbeitet immer nur die Inhaltsabschnitte darunter.

json
{
  "_id": "392_cmp_f15654997737",
  "_rev": "3-...",
  "docType": "studio",
  "stat": 3,
  "app_id": "prj...",
  "properties": { "menuType": "component", "menuName": "Orders", "menuTitle": "Orders" },
  "studio_meta": { "created": 1750000000000, "createdByUid": "...", "savedByUid": "...", "parentId": "programs" }
}
  • _id folgt <letzte 3 Zeichen von app_id>_<Typkürzel aus 3 Buchstaben>_<12 Hex>, zum Beispiel 392_cmp_... für eine Komponente, 392_tbl_... für eine Tabelle, 392_jvs_... für ein javascript-Prog, 392_gtd_... / 392_std_... für get_data / set_data, 392_fld_... für einen Ordner. Die Factory erzeugt IDs, ein Bau erfindet nie eine.
  • stat ist 3 für aktiv, 4 für weich gelöscht (was das Löschen eines Progs setzt). Der Baum von Studio zeigt nur stat: 3.
  • properties.menuType ist eines von globals, table, get_data, set_data, batch, alert, javascript, folder, route, api, component, ai_agent.
  • studio_meta.parentId platziert den Knoten im Studio-Baum: entweder die ID eines anderen Progs (meist ein Ordner) oder eine der Typ-Wurzeln, programs (Logik und Komponenten), database (Tabellen), routes, globals, ai_agents. Eine nicht erkannte parentId lässt den Knoten im Baum unsichtbar und ist ein Checker-Fehler.

Inhaltsabschnitte nach menuType

Das Globals-Dokument

Jedes Projekt hat genau ein Dokument global_<app_id> (menuType: "globals"). Seine progFields sind von jedem anderen Prog aus als @field_id lesbar. Zwei System-Globals werden in jedem Projekt mitgeliefert: @SYS_GLOBAL_OBJ_LOGIN_USER_INFO für den angemeldeten Nutzer und @SYS_GLOBAL_OBJ_REFS für mit xu-ref registrierte Elemente. Weder das Globals-Dokument noch die Baum-Wurzel lässt sich löschen.

Strukturelle Pflichten

  • properties, properties.menuType, properties.menuName, studio_meta und studio_meta.parentId sind in jedem Dokument Pflicht.
  • Ein progFields-Eintrag braucht eine eindeutige id, data.field_id, einen data.type von virtual, table, expression oder datasource und einen props.fieldType von string, number, boolean, array oder object.
  • Reservierte Laufzeit-Variablennamen, _NULL, _THIS, _FOR_KEY, _FOR_VAL, _ROWNO, _ROWID, _ROWDOC, _KEY, _VAL, werden nie als Feld-IDs neu definiert.
  • Doppelte IDs, unbekannte menuTypes und fehlerhafte Abschnitte sind alle harte Fehler, die validate_prog direkt meldet.

Ausdrücke und xu-*-Attribute

Ausdruckssyntax

Ausdrücke laufen gegen den eigenen Datensatz des Progs. Jedes Feld, lokal, tabellengebunden, global oder ein Parameter, wird mit @ referenziert: @search_v, @ORD_Total, @SYS_GLOBAL_OBJ_LOGIN_USER_INFO, einfaches JavaScript drumherum, @count_v > 0 ? 'has rows' : 'empty'. Ein Objektliteral braucht umschließende Klammern, ({ ORD_Status: @status_v }). Innerhalb einer xu-for-Schleife ist das aktuelle Element @_FOR_VAL und sein Schlüssel oder Index @_FOR_KEY (umbenennbar mit xu-for-key / xu-for-val). xu-render und andere Bedingungen geben den Wahr- oder Falsch-Wert direkt zurück, nie einen String "Y" / "N" oder einen zusätzlichen Vergleich.

xu-bind ist die eine Ausnahme

Überall sonst wird ein Feld mit @ referenziert. xu-bind nimmt stattdessen die bloße Feld-ID: xu-bind="search_v", nie xu-bind="@search_v".

Die xu-Attribute

Präfix-Familien

Attributfamilien, die ein Suffix nehmen. xu-on-Werte sind immer Arrays von Handler-Objekten; xu-exp-Werte sind immer Ausdrucks-Strings.

json
"xu-on:click": [{
  "handler": "custom",
  "props": {},
  "workflow": [
    { "id": "1", "data": { "action": "update", "name": { "value": "@saving_v: true" }, "enabled": true }, "props": {} },
    { "id": "2", "data": { "action": "set_data", "name": { "prog": "392_std_...", "properties": {}, "parameters": {} }, "enabled": true }, "props": { "condition": "@form_valid_v" } }
  ]
}]

Der Wert eines xu-on:*-Attributs ist immer ein Array von Handler-Objekten, und jeder workflow ist ein Array von Aktionsschritten (die vollständige Aktionsreferenz steht unten unter Logik-Progs und Workflows). Die props.condition eines Schritts steuert ihn; props.async: true löst ihn aus, ohne zu warten.

Kritische Semantik

  • xu-exp:class ersetzt das statische Attribut class, statt etwas hinzuzufügen. Trägt ein Element beides, wird das statische ignoriert, die Layout-Klassen gehören also auch in den Ausdruck: xu-exp:class="'card p-4 ' + (@active_v ? 'ring' : '')".
  • xu-script nimmt einen bloßen Ausdruck function (el) { ... }, mit eval ausgewertet und mit dem DOM-Element aufgerufen, sobald der Knoten sichtbar wird. Sichere dich gegen erneute Ausführungen ab (if (el.__bound) return; el.__bound = true;) und beschränke jede Abfrage auf el, nie auf document.
  • xu-style hat automatisch einen Gültigkeitsbereich: Jeder Selektor erhält das [xu-ui-id] des Knotens als Präfix, einfache Element- und Klassenselektoren bleiben also lokal und lecken nie.
  • Weder xu-script- noch xu-style-Werte dürfen ein Anführungszeichen (' oder ") enthalten, der Designer-Canvas serialisiert Attribute ohne Escaping, und ein Anführungszeichen beschädigt die Komponente. Der Abschnitt JavaScript-Progs unten behandelt Techniken ohne Anführungszeichen.
  • Statischer Text gehört in die Eigenschaft content eines Elements. xu-exp:xu-content ist nur für dynamischen Text.

Tags

Authoring-Tags neben einfachem HTML: xu-template, xu-single-view, xu-multi-view, xu-panel, xu-teleport, xu-slot.

  • xu-single-view begrenzt einen einzelnen Datensatz (eine Formular-Wurzel, auch verschachtelt nutzbar).
  • xu-multi-view wiederholt seine Kinder einmal pro Zeile der gebundenen Daten.
  • xu-panel bettet ein anderes Prog ein (Attribut program plus xu-exp:<param>-Eingaben). Neben den Parameter-Ausdrücken gehören nur Standard-HTML-Attribute (class, id, style, title, hidden, slot, name, role, tabindex) darauf.
  • xu-teleport rendert seine Kinder an einem anderen DOM-Ziel (to oder xu-exp:to).
  • Ein Tag-Name mit Großbuchstaben am Anfang (Button, Card) ist eine kompilierte Komponente, kein HTML-Element, siehe Einbetten unten.

Komponenten

Eine Komponente (menuType: "component") ist eine UI-Einheit: ein Elementbaum (progUi), gebunden an lokalen Zustand (progFields), optionale Daten (progDataSource), Lifecycle-Logik (progEvents) und eine Ein-/Ausgabe-Schnittstelle (properties.progParams).

Eigenschaften

json
{
  "menuType": "component", "menuName": "OrderList",
  "renderType": "form",
  "uiFramework": "@xuda.io/xuda-framework-plugin-tailwind",
  "rwMode": "R",
  "progParams": [{ "id": 1, "data": { "dir": "in", "parameter": "order_id_in", "type": "string" }, "props": {} }]
}
  • renderType ist form für einen einzelnen Datensatz (Wurzelelement xu-single-view) oder grid / list für eine pro Datenzeile wiederholte Ansicht (Wurzelelement xu-multi-view).
  • rwMode ist R zum Lesen oder U zum Aktualisieren; allowCreate sagt, ob eine neue Zeile eingefügt werden kann, wenn keine passt.
  • Namenskonvention für progParams: Parameter enden auf _in / _out, komponentenlokale virtuelle Felder enden auf _v.
  • uiFramework spiegelt wider, was die bestehenden Komponenten des Projekts bereits verwenden. Ein bestehendes Projekt, das es weglässt, sollte es weiter weglassen: Ein Framework-Plugin zu setzen, das das Drive des Projekts nicht tatsächlich ausliefert, lässt die Live-Vorschau auf einem leeren Bildschirm hängen.

Der Elementbaum (progUi)

json
{
  "id": "root", "type": "element", "tagName": "xu-single-view", "attributes": {},
  "children": [
    { "id": "ui-...", "type": "element", "tagName": "div",
      "attributes": { "class": "card", "xu-style": ".card { padding: 16px; border-radius: 12px; }" },
      "children": [
        { "id": "ui-...", "type": "element", "tagName": "h2", "content": "Orders", "attributes": {}, "children": [] },
        { "id": "ui-...", "type": "element", "tagName": "input", "children": [],
          "attributes": { "type": "text", "placeholder": "Search", "xu-bind": "search_v" } }
      ] }
  ]
}

Der Factory-Knoten root bleibt; ein Bau arbeitet in seinen children. Jeder Knoten braucht eine eindeutige ID (neue Knoten verwenden ui-<uuid>), type: "element" und einen tagName, keine Knotentypen comment oder text, statischer Text steht stattdessen in content. Jeder Knoten braucht attributes: {} und children: [], auch wenn sie leer sind, der Serialisierer des Designer-Canvas dereferenziert beides bei jedem Knoten, und ein Weglassen zerstört die eigene Vorschau der Komponente.

Einbetten: xu-panel oder eine kompilierte Komponente

Beide hängen sich transparent ein, ohne Wrapper-Element, und beide werden von einem Signal entschieden: ob tagName mit einem Großbuchstaben beginnt.

  • xu-panel, ein tagName in Kleinbuchstaben plus ein Attribut program, bettet ein anderes Prog ein, ein datenbankgebundenes oder zustandsbehaftetes Kind mit eigenen Feldern und Events. program ist die ID des Kindes (oder xu-exp:prog für ein dynamisches), Werte erreichen seine _in-Parameter über xu-exp:<param>.
  • Ein Tag mit Großbuchstaben plus ein Attribut library hängt eine kompilierte Komponente ein, ein Design-System-Primitiv oder einen Teil, den die App selbst kompiliert hat. Jedes einfache Attribut wird zu einer Prop (props.<name>), nie zu einem DOM-Attribut, da die Komponente kein eigenes Element rendert. Ein Komponentenknoten hat keine Out-Parameter, anders als bei xu-panel schreibt nichts einen Wert in deine Felder zurück.
Allein die Großschreibung entscheidet

Ein falsch geschriebenes <Buton> wird trotzdem als Komponenten-Tag beansprucht, fällt nie auf ein unbekanntes HTML-Element zurück und wirft beim Einhängen einen Fehler, der das Tag, die Bibliothek und jede versuchte Quelle nennt. validate_prog prüft Komponenten-Tags oder library-Werte heute nicht, die Live-Vorschau ist die einzige Prüfung.

progFields

json
[
  { "id": "<uuid>", "data": { "type": "virtual", "field_id": "search_v" }, "props": { "fieldType": "string" }, "workflow": [] },
  { "id": "<uuid>", "data": { "type": "table", "field_id": "ORD_Total" }, "props": { "fieldType": "number" }, "workflow": [] }
]

data.type ist virtual für lokalen Zustand, table für eine Spalte der gebundenen Datasource oder expression / datasource. Der workflow eines Feldes läuft bei einer Änderung. Ein Standardwert setzt props.fieldValue; ein berechnetes Feld setzt props.fieldComputed: true plus propExpressions.fieldValue.

progDataSource

Ein einzelner Datensatz über einen Schlüssel (Formular): dataSourceFilterModelType: "index" mit einer dataSourceIndexId, die in den eigenen tableIndexes der Tabelle existiert. Eine gefilterte Liste (Grid oder Liste): dataSourceFilterModelType: "query" mit filterModelMongoFx, einem Ausdrucks-String im Mongo-Stil. dataSourceType ist table, array, json, csv, none oder leer für eine rein darstellende Komponente ganz ohne Datenquelle.

progEvents und die drei Lifecycle-Hooks

Event-Typen: on_load, on_exit, before_record, after_record, record_not_found, locate_not_found, screen_ready, on_refresh, on_unload, client_interval, user_defined. user_defined-Events werden von überall mit der Aktion raise_event ausgelöst; screen_ready ist der übliche Mount-Hook.

Die drei eingebauten Hooks einer Komponente teilen die Arbeit auf, der falsche ist eine häufige Fehlerquelle:

screen_ready

Wird einmal pro Instanz ausgelöst. Erstelle hier DOM und Widgets.

on_refresh

Wird nach jedem Laden ausgelöst, auch dem ersten, direkt nach screen_ready. Gib neue Daten an Widgets weiter, die schon existieren. Legst du Refresh-Arbeit stattdessen in screen_ready, läuft der Erstellungscode erneut gegen DOM, das noch existiert, und stapelt ein zweites Widget.

on_unload

Wird ausgelöst, wenn die Instanz abgebaut wird. Zerstöre, was das Prog erstellt hat, Widgets, Timer, document- / window-Listener, Observer. Die Engine kann nur freigeben, was sie selbst erstellt hat, ein an document gebundener Listener überlebt sonst das Panel.

Muster

  • Lade- und Leerzustände: Setze xu-ref="myref" auf das datengebundene Element und steuere dann Skeleton- oder Leer-Elemente mit xu-render über (@SYS_GLOBAL_OBJ_REFS).myref, sein Datensatz hängt sich an, sobald Daten ankommen.
  • Modale Dialoge: Baue den Dialog als eigene Komponente und öffne ihn mit der Aktion call_modal.
  • Eine gebundene Zeile speichern oder löschen: invoke_action mit act_save / act_delete oder ein eigenes set_data-Prog für alles über die aktuelle Zeile hinaus.

Logik-Progs und Workflows

Logik-Prog-Typen teilen die Datenmaschinerie einer Komponente (progDataSource, progFields, progEvents, properties.progParams) ohne jede UI:

Parameter

json
"progParams": [
  { "id": 1, "data": { "dir": "in",  "parameter": "order_id_in", "type": "string" }, "props": {} },
  { "id": 2, "data": { "dir": "out", "parameter": "total_out",   "type": "number" }, "props": {} }
]

Ein Aufrufer übergibt Werte über die name.parameters der Aktion, { "order_id_in": { "value": "", "fx": "@selected_id_v" } }, value für einen statischen Wert, fx für einen Ausdruck. Der Checker prüft, dass das Zielprogramm existiert und sein menuType zur Aktion passt.

Workflow-Aktionen

Ein Workflow ist ein Array von Schritten, { "id": "...", "data": { "action": "...", "name": { ... }, "enabled": true }, "props": {} }, der Reihe nach ausgeführt. props.condition steuert einen Schritt, props.async: true löst ihn aus, ohne zu warten. Workflows erscheinen in xu-on:*-Handlern, progEvents[].workflow und im eigenen workflow eines Feldes.

invoke_action akzeptiert act_next, act_prev, act_first, act_last, act_reload, act_refresh, act_print, act_save, act_delete (nur im Komponentenkontext).

Veraltete Aktionen, die der Checker ablehnt

alter_ui_element, create_ui_element, info_ui_element, remove_ui_element, empty_ui_element, cache_ui_element, load_ui_element. Steuere die UI stattdessen über Felder und xu-exp / xu-render statt über eine imperative Elementaktion.

call_ai_agent und call_triage_agent sind keine echten Aktionen

Die eigene Aktionsauswahl von Studio bietet neben den obigen Aktionen Call AI Agent und Call Triage Agent an. Keine davon steht in dieser Tabelle, weil keine davon eine ist: validate_prog hat keinen Fall dafür und meldet invalid trigger type, und auch die Workflow-Engine der Laufzeit hat keinen Handler dafür, ein gespeicherter Schritt läuft also nie, selbst wenn der Fehler ignoriert wird. Damit ein Prog einen veröffentlichten Agenten erreicht, füge stattdessen der eigenen Tool-Liste eines anderen Agenten ein AI Agent-Tool hinzu (das agentConfig.agent_tools eines Dokuments mit menuType: "ai_agent"), nicht einen Workflow-Schritt an einer Komponente, einem get_data oder einem anderen Prog-Typ.

Der name.value von update weist Felder mit durch Semikolon getrennten Paaren @field: expression zu, oder mit einem JSON5-Objekt, "@saving_v: true; @status_v: 'sent'". Um ein anderes Programm aufzurufen, wird es unter name.prog benannt, wobei die Aktion zum eigenen Typ des Programms passen muss (get_data braucht ein get_data-Prog, call_native_javascript ein javascript-Prog und so weiter).

call_library ruft eine Methode eines installierten Plugins auf: name.plugin_name muss gekauft und in der App installiert sein, sonst lehnt der Checker den Schritt ab, name.library_method eine der Methoden, die das Plugin exportiert, name.library_props seine deklarierten Felder. Zwei Prop-Namen sind eine Konvention über Plugins hinweg und nicht spezifisch für eines: event_name_for_successful_callback löst dieses Event mit der Antwort der Methode aus, field_id_to_return_result schreibt die Antwort direkt in dieses Feld, keines ist erforderlich.

Typen von progEvents

on_load, on_exit, before_record, after_record, record_not_found, locate_not_found, screen_ready, on_refresh, on_unload, client_interval, user_defined. screen_ready ist der übliche Init-Hook; before_record / after_record / record_not_found / locate_not_found sind der Daten-Lifecycle, besonders für set_data und batch; client_interval ist ein wiederholender Timer; user_defined wird von der Aktion raise_event ausgelöst.

Tabellen

Ein Tabellen-Prog (menuType: "table") definiert eine Datenbanktabelle: ihre Spalten (tableFields), ihre Indizes (tableIndexes) und das Datenbank-Plugin, das sie speichert (properties.databaseSocket). Baum-Elternteil: database oder ein Ordner darunter.

json
{
  "properties": { "menuType": "table", "menuName": "ORD - Orders", "databaseSocket": "@xuda.io/xuda-dbs-plugin-xuda" },
  "tableFields": [
    { "id": "<uuid>", "data": { "field_id": "ORD_Id" }, "props": { "fieldType": "string", "mandatory": true } }
  ],
  "tableIndexes": [
    { "id": "<uuid>", "data": { "name": "index_1", "unique": true, "keys": ["ORD_Id"] }, "props": {} }
  ]
}
  • databaseSocket muss ein im Projekt installiertes Datenbank-Plugin nennen, @xuda.io/xuda-dbs-plugin-xuda ist der Plattform-Standard; eine bestehende Tabelle im selben Projekt ist die Referenz dafür, welchen Socket man wiederverwendet.
  • Mindestens ein Feld und mindestens ein Index sind erforderlich.
  • field_id beginnt mit einem Buchstaben, dann Buchstaben, Ziffern, Unterstrich, Bindestrich, Doppelpunkt oder Punkt, und bleibt innerhalb der Tabelle eindeutig.
  • fieldType ist string, number, boolean, array, object oder date; mandatory: true macht es beim Speichern erforderlich.
  • Jeder Index braucht einen nicht leeren name und keys, und jeder Schlüssel muss eine existierende field_id sein.

Konvention: Versieh Spalten mit einem dreibuchstabigen Tabellenkürzel als Präfix, eine Tabelle namens "ORD - Orders" bekommt ORD_Id, ORD_Total, ORD_Status. Gib jeder Tabelle ein eindeutiges Feld <TBL>_Id mit einem eindeutigen Index darauf, eine Einzeldatensatz-Bindung einer Komponente braucht es.

Eine Tabelle wird auf drei Arten verwendet: über die progDataSource.dataSourceTableId einer Komponente oder Abfrage, über ein get_data- / set_data- / batch-Prog für Zugriff auf Zeilenebene aus Workflows oder über xu.dbs_create / dbs_read / dbs_update / dbs_delete aus einem Skript, als Nächstes behandelt.

JavaScript-Progs

Ein javascript-Prog (menuType: "javascript") enthält echten JS-Quelltext in scriptData.value, beim Speichern kompiliert. save_prog löst diesen Build aus und gibt das Ergebnis als data.compile zurück, { ok: true, dependencies } oder { ok: false, error }. Eine fehlgeschlagene Kompilierung speichert das Dokument trotzdem, ein Bau liest also compile.ok und behebt es, bevor er weitermacht.

Der Ausführungsvertrag

Der Quelltext wird als einfacher async-Rumpf geschrieben, ohne export und ohne Wrapper. Zur Laufzeit wird er so ausgeführt:

js
async function (params, xu, SESSION_ID, SESSION_OBJ, jobNoP, $container, func, glb, APP_OBJ, evt) {
  /* source */
}

params sind die bereits ausgewerteten Eingaben des Aufrufers; xu ist die Laufzeit-API unten; ein Rückgabewert ist optional, der idiomatische Weg, Ergebnisse zurückzugeben, ist xu.set_field_value auf den Feldern der aufrufenden Komponente. Anführungszeichen sind hier in Ordnung, anders als in einem Attributwert von xu-script.

Die xu-Laufzeit-API

js
const raw = await xu.get_field_value(`rows_json_v`);
const rows = typeof raw === `string` ? JSON.parse(raw || `[]`) : raw || [];
for (const row of rows) {
  await xu.dbs_create(`392_tbl_...`, { CNT_Name: row.name || ``, CNT_Email: row.email || `` });
}
// dbs_read resolves to an ARRAY of { id, value } rows: the row id on .id, table fields under .value.
const all = await xu.dbs_read(`392_tbl_...`, {}, [], null, 999);
await xu.set_field_value(`status_v`, `Saved ` + rows.length + ` rows`);

dbs_*-Methoden nehmen die eigene _id des Tabellen-Progs, nie einen Namen. Selektoren sind Objekte im Mongo-Stil auf den Feld-IDs, {} gibt alles zurück (Standardlimit 999). Die Projektion fields ist optional, [] gibt alle Felder zurück und eine Liste von Feld-IDs nur diese.

Daten übergeben: Felder, nicht Parameter

call_native_javascript wertet keine Wrapper {value, fx} für Parameter aus, name.parameters erreicht das Skript roh. Der verlässliche Vertrag: Die Komponente legt die Nutzlast zuerst in ein Feld (ein update-Schritt oder eine xu-bind-Eingabe), der Workflow ruft das Prog mit leeren parameters: {} auf, und das Skript liest sie mit xu.get_field_value und meldet mit xu.set_field_value zurück. Beim Aufruf aus einem anderen Skript übergibt stattdessen xu.call_javascript(prog_id, {...}) Parameter direkt.

Eigenheiten der Live-Vorschau

  • Datenschreibzugriffe erreichen die echte Datenbank, aber xu.dbs_read liest einen lokalen Entwurfsspeicher, der frische Serverzeilen möglicherweise nicht enthält, ein Lesen direkt nach einem Schreiben kann in der Vorschau leer zurückkommen, obwohl das Schreiben angekommen ist (sichtbar im Tab Data der Tabelle in Studio). Bereitgestellte Apps lesen und schreiben denselben Speicher.
  • Kompilierte Skripte werden in Dev-Vorschauen hart gecacht, eine laufende Vorschau kann das vorherige Skript weiter ausführen, auch über Neuladungen hinweg, nachdem ein Speichern es neu kompiliert hat. Ein hartes Neuladen des Browsers behebt das.
  • xu.alert mit der Anzeige modal, toast oder browser kann in der Vorschau als natives, blockierendes alert() erscheinen. xu.set_field_value in ein Statusfeld ist der sicherere Weg, etwas zurückzumelden.

javascript-Prog im Vergleich zum Attribut xu-script

Techniken ohne Anführungszeichen für xu-script / xu-style

Der Designer-Canvas serialisiert Attributwerte ohne Escaping, ein einzelnes Anführungszeichen beschädigt also das Markup der Komponente. Template-Literale vermeiden String-Anführungszeichen vollständig (el.textContent = `Ready`); das Zeichen ", zum Beispiel beim Bauen von CSV, kommt aus String.fromCharCode(34); CSS-Attributselektoren sind ohne Anführungszeichen gültig (el.querySelector(`[data-role=import-btn]`)); und ein Schutz gegen erneutes Ausführen, if (el.__bound) return; el.__bound = true;, verhindert, dass ein Skript beim erneuten Rendern doppelt bindet.

Stolperfallen

Jeder Eintrag unten hat irgendwann einen echten Bau gebrochen. validate_prog fängt die meisten davon, führe es vor jedem Speichern aus.

API-Mechanik

  • Jede Antwort ist { code, data }, code < 0 ist ein Fehler.
  • create_prog gibt das neue Dokument unter data.prog zurück, speicherst du stattdessen die ganze Antwort, wird ein fehlerhaftes Dokument mit properties vergraben unter prog gespeichert.
  • save_prog ersetzt das ganze Dokument. Beginne mit dem aktuellen Dokument, nie mit einem von Hand zusammengesetzten Gerüst; ein -409 bedeutet, dass es sich seit dem letzten Lesen geändert hat: erneut holen, erneut anwenden, erneut versuchen.
  • Über MCP werden prog_json und properties_json als Strings übergeben, die Schema-Schicht des Tools entfernt unbekannte Schlüssel aus einem Objektparameter und kann ganze Abschnitte stillschweigend verwerfen.
  • delete_prog ist ein weiches Löschen, es setzt stat: 4. Der Knoten global_<app_id> lässt sich nicht löschen.

Dokumentinhalt

  • Kein ' oder " innerhalb von xu-script- oder xu-style-Werten.
  • Schlüssel mit $-Präfix ($folded, $childrenClass, $nodeBackClass) sowie path, code, editCode sind Ansichtszustand des Designers und gehören nie in einen gespeicherten progUi-Knoten.
  • Keine Knotentypen comment oder text, nur Elemente, statischer Text in content.
  • Jeder Elementknoten braucht attributes: {} und children: [], auch wenn sie leer sind.
  • xu-exp:class ersetzt das statische class, jede benötigte Klasse gehört in den Ausdruck.
  • xu-bind ist eine bloße Feld-ID, ohne @, überall sonst verwenden Felder @.
  • Nur die dokumentierten xu-*-Attribute bewirken etwas, ein erfundenes wird stillschweigend ignoriert, und validate_prog warnt.
  • Die Baum-Wurzel eines ai_agent-Progs ist ai_agents, speichere es mit studio_meta.parentId: "ai_agents" (oder einer Ordner-ID darunter), wenn der Checker parentId bemängelt.

Laufzeit und Rendering

  • Ein tagName mit Großbuchstaben am Anfang wird immer als Komponente beansprucht, auch bei einem Tippfehler, und wirft beim Einhängen einen Fehler, der das Tag, die library und jede versuchte Quelle nennt, es gibt kein stilles "wird nicht gerendert", wie es ein xu-panel ohne gewähltes Programm hat.
  • validate_prog prüft keine Komponenten-Tags oder library-Werte, nur die Live-Vorschau fängt ein falsch geschriebenes.
  • Kein Utility-CSS (Tailwind oder anderes) zur Laufzeit, es sei denn, das uiFramework-Plugin des Projekts stellt es tatsächlich bereit, Klassen wie p-4 bewirken sonst stillschweigend nichts. In sich geschlossene Gestaltung ist xu-style, automatisch durch [xu-ui-id] begrenzt.
  • xu-script läuft einmal pro Sichtbarkeit des Elements und kann beim erneuten Rendern erneut ausgelöst werden, sichere mit el.__bound ab und beschränke Abfragen auf el.

Daten und Skripte

  • Die Parameter von call_native_javascript werden nicht ausgewertet, übergib Daten stattdessen über Felder (siehe Daten übergeben oben).
  • dbs_read-Zeilen sind {id, value}, Felder liegen unter .value, die Zeilen-ID unter .id. Übergib keine Projektion fields, sie bricht das serverseitige Lesen.
  • Setze innerhalb von xu-for den Iterator in Klammern, (@_FOR_VAL).CNT_Name wird ausgewertet, @_FOR_VAL.CNT_Name scheitert stillschweigend und rendert stattdessen den ersetzten Quelltext.
  • Schreibzugriffe der Vorschau landen in der echten Datenbank; Lesezugriffe der Vorschau kommen aus einem lokalen Entwurfsspeicher, der direkt nach einem Schreiben leer aussehen kann.
  • Bevorzuge in Vorschauen ein Statusfeld gegenüber der Modal- oder Toast-Anzeige von xu.alert, sie kann als natives, blockierendes alert() erscheinen.

Deine Arbeit überprüfen

Hole nach dem Speichern mit get_prog erneut und vergleiche mit dem Erwarteten. Öffne für UI-Arbeit die Komponente in Studio und drücke die Vorschau-Abspieltaste oder die Live-Vorschau-URL des Projekts, wenn eine verfügbar ist. Prüfe bei einem javascript-Prog bei jedem Speichern data.compile.ok. Behebe jeden Fehler von validate_prog; behandle seine Warnungen, Anführungszeichen, $-Schlüssel, unbekannte Attribute, als Dinge, die sofort zu beheben sind, nicht als Rauschen.