De Studio LLM-gids
Het prog-documentmodel, de xu-*-attribuutreferentie en de workflowregels die een AI-agent leert vóór zijn eerste toolaanroep.
Elke Studio-project, elke tabel, elk scherm, script en route erin, is één CouchDB-JSON-document dat
een prog heet (docType: "studio"). Deze pagina is dezelfde referentie die een AI-agent krijgt
wanneer hij er een bouwt, herschreven als documentatie: de vorm van dat document, de attributen die
de UI aansturen, de acties die een workflow kan uitvoeren en de fouten die in echte builds voorkomen.
Hoe een AI-agent deze gids krijgt
Koppel een MCP-client aan Xuda en het eerste antwoord, de aanroep initialize, bevat deze gids als
de instructions van de sessie, vers samengevoegd uit de eigen live regels van het platform, zodat
hij nooit iets kan beschrijven dat de gedeployde checker niet meer afdwingt. Zie
Een AI-client koppelen via MCP.
Vanuit een sessie bereiken twee methoden hetzelfde materiaal direct, via MCP of gewone REST, en ze vragen niets meer dan een gewone API-sleutel:
De voorgeschreven volgorde: lees het onderwerp dat past bij wat je bouwt, haal een passend voorbeeld
op, maak de prog aan via de factory (create_prog), bouw binnen de inhoudssecties, valideer
(validate_prog) en los alles op wat het meldt, sla op (save_prog) en haal hem daarna opnieuw op
om te controleren. Een opslag die -409 teruggeeft, betekent dat het document is gewijzigd sinds
het werd gelezen: haal opnieuw op, pas opnieuw toe, probeer opnieuw.
Het prog-documentmodel
De envelop
Server- en factorycode beheren deze velden; een geschreven build bewerkt alleen de inhoudssecties eronder.
_idvolgt<laatste 3 tekens van app_id>_<afkorting van 3 letters voor het type>_<12 hex>, bijvoorbeeld392_cmp_...voor een component,392_tbl_...voor een tabel,392_jvs_...voor een javascript-prog,392_gtd_.../392_std_...voor get_data / set_data,392_fld_...voor een map. De factory genereert id's, een build verzint er nooit een.statis 3 voor actief, 4 voor zacht verwijderd (wat het verwijderen van een prog instelt). De boom van Studio toont alleenstat: 3.properties.menuTypeis een vanglobals,table,get_data,set_data,batch,alert,javascript,folder,route,api,component,ai_agent.studio_meta.parentIdplaatst de node in de Studio-boom: de id van een andere prog (meestal een map) of een van de typeroots:programs(logica en componenten),database(tabellen),routes,globals,ai_agents. Een onbekendeparentIdlaat de node onzichtbaar in de boom en is een checkerfout.
Inhoudssecties per menuType
Het globals-document
Elk project heeft precies één document global_<app_id> (menuType: "globals"). De progFields
ervan zijn vanuit elke andere prog te lezen als @field_id. Twee systeemglobals zitten in elk
project: @SYS_GLOBAL_OBJ_LOGIN_USER_INFO voor de ingelogde gebruiker, en @SYS_GLOBAL_OBJ_REFS
voor elementen die met xu-ref zijn geregistreerd. Noch het globals-document noch de boomroot kan
worden verwijderd.
Structurele verplichtingen
properties,properties.menuType,properties.menuName,studio_metaenstudio_meta.parentIdzijn verplicht op elk document.- Een
progFields-item heeft een uniekeid,data.field_id, eendata.typevanvirtual,table,expressionofdatasource, en eenprops.fieldTypevanstring,number,boolean,arrayofobjectnodig. - Gereserveerde runtimevariabelenamen,
_NULL,_THIS,_FOR_KEY,_FOR_VAL,_ROWNO,_ROWID,_ROWDOC,_KEY,_VAL, worden nooit opnieuw als veld-id gedefinieerd. - Dubbele id's, onbekende
menuTypes en misvormde secties zijn allemaal harde fouten dievalidate_progdirect meldt.
Expressies en xu-*-attributen
Expressiesyntaxis
Expressies draaien op de eigen dataset van de prog. Elk veld, lokaal, aan een tabel gebonden, globaal
of een parameter, wordt met @ aangeduid: @search_v, @ORD_Total,
@SYS_GLOBAL_OBJ_LOGIN_USER_INFO, met gewone JavaScript eromheen, @count_v > 0 ? 'has rows' : 'empty'. Een objectliteral heeft omhullende haakjes nodig, ({ ORD_Status: @status_v }). Binnen een
xu-for-lus is het huidige item @_FOR_VAL en zijn sleutel of index @_FOR_KEY (te hernoemen met
xu-for-key / xu-for-val). xu-render en andere condities geven direct de waarde terug die waar
of onwaar is, nooit een string "Y" / "N" of een extra vergelijking.
Overal elders wordt een veld met @ aangeduid. xu-bind neemt in plaats daarvan de kale veld-id:
xu-bind="search_v", nooit xu-bind="@search_v".
De xu-attributen
Voorvoegselfamilies
Attribuutfamilies die een achtervoegsel nemen. xu-on-waarden zijn altijd arrays van
handler-objecten; xu-exp-waarden zijn altijd expressiestrings.
De waarde van een xu-on:*-attribuut is altijd een array van handler-objecten, en elke workflow
is een array van actiestappen (de volledige actiereferentie staat hieronder, onder Logicaprogramma's
en workflows). Met props.condition van een stap kun je hem afhankelijk maken van een conditie;
props.async: true start hem zonder te wachten.
Kritieke semantiek
xu-exp:classvervangt het statischeclass-attribuut in plaats van eraan toe te voegen. Bij een element met beide wordt het statische genegeerd, dus de layoutklassen horen ook in de expressie:xu-exp:class="'card p-4 ' + (@active_v ? 'ring' : '')".xu-scriptneemt een kalefunction (el) { ... }-expressie, metevaluitgevoerd en aangeroepen met het DOM-element zodra de node zichtbaar wordt. Bescherm tegen herhaalde runs (if (el.__bound) return; el.__bound = true;) en beperk elke query totel, nooit totdocument.xu-styleheeft automatisch een eigen bereik: elke selector krijgt het voorvoegsel[xu-ui-id]van de node, dus gewone element- en klasseselectors blijven lokaal en lekken nooit.- Waarden van
xu-scriptenxu-stylemogen geen aanhalingsteken bevatten ('of"): het designercanvas serialiseert attributen zonder escaping en één aanhalingsteken beschadigt de component. De sectie JavaScript-programma's hieronder behandelt technieken zonder aanhalingstekens. - Statische tekst hoort in de eigenschap
contentvan een element.xu-exp:xu-contentis alleen voor dynamische tekst.
Tags
Schrijftags naast gewone HTML: xu-template, xu-single-view, xu-multi-view, xu-panel,
xu-teleport, xu-slot.
xu-single-viewbegrenst één record (een formulierroot, ook genest te gebruiken).xu-multi-viewherhaalt zijn kinderen één keer per rij van de gebonden data.xu-panelsluit een andere prog in (attribuutprogramplusxu-exp:<param>-invoer). Naast de param-expressies horen er alleen standaard HTML-attributen (class,id,style,title,hidden,slot,name,role,tabindex) op.xu-teleportrendert zijn kinderen op een ander DOM-doel (toofxu-exp:to).- Een tagnaam met hoofdletter (
Button,Card) is een gecompileerde component, geen HTML-element, zie Insluiten hieronder.
Componenten
Een component (menuType: "component") is een UI-eenheid: een elementboom (progUi) gebonden aan
lokale state (progFields), optionele data (progDataSource), lifecyclelogica (progEvents) en
een invoer-/uitvoerinterface (properties.progParams).
Eigenschappen
renderTypeisformvoor één record (root-elementxu-single-view) ofgrid/listvoor een herhaling per datarij (root-elementxu-multi-view).rwModeisRvoor lezen ofUvoor bijwerken;allowCreatebepaalt of een nieuwe rij kan worden ingevoegd als er geen overeenkomt.- Naamconventie van
progParams: parameters eindigen op_in/_out, virtuele velden die lokaal bij de component horen eindigen op_v. uiFrameworkvolgt wat de bestaande componenten van het project al gebruiken. Een bestaand project dat het weglaat, moet het blijven weglaten: een frameworkplugin instellen die de drive van het project niet echt serveert, laat de live preview op een leeg scherm vastlopen.
De elementboom (progUi)
De root-node van de factory blijft staan; een build werkt binnen zijn children. Elke node heeft
een unieke id nodig (nieuwe nodes gebruiken ui-<uuid>), type: "element" en een tagName, geen
nodetypen comment of text, statische tekst staat in plaats daarvan in content. Elke node
heeft attributes: {} en children: [] nodig, ook als ze leeg zijn: de serializer van het
designercanvas dereferentieert beide op elke node en een weglating breekt de eigen preview van de
component.
Insluiten: xu-panel of een gecompileerde component
Beide mounten transparant, zonder wrapper-element, en beide worden bepaald door één signaal: of
tagName met een hoofdletter begint.
xu-panel,tagNamein kleine letters plus een attribuutprogram, sluit een andere prog in, een aan een database gebonden of stateful kind met eigen velden en events.programis de id van het kind (ofxu-exp:progvoor een dynamische), waarden bereiken de_in-params viaxu-exp:<param>.- Een tag met hoofdletter plus een attribuut
librarymount een gecompileerde component, een designsysteem-primitive of een onderdeel dat de app zelf heeft gecompileerd. Elk gewoon attribuut wordt een prop (props.<name>), nooit een DOM-attribuut, omdat de component geen eigen element rendert. Een componentnode heeft geen out-params: anders dan bijxu-panelschrijft niets een waarde terug naar je velden.
Een <Buton> met een typfout wordt nog steeds als componenttag opgeëist, valt nooit terug op een
onbekend HTML-element en geeft bij het mounten een fout met de tag, de library en elke geprobeerde
bron. validate_prog controleert componenttags of library-waarden nu niet, de live preview is de
enige controle.
progFields
data.type is virtual voor lokale state, table voor een kolom van de gebonden datasource, of
expression / datasource. De workflow van een veld draait bij een wijziging. Een standaardwaarde
zet props.fieldValue; een berekend veld zet props.fieldComputed: true plus
propExpressions.fieldValue.
progDataSource
Eén record op sleutel (formulier): dataSourceFilterModelType: "index" met een dataSourceIndexId
die bestaat in de eigen tableIndexes van de tabel. Een gefilterde lijst (grid of list):
dataSourceFilterModelType: "query" met filterModelMongoFx, een expressiestring in Mongo-stijl.
dataSourceType is table, array, json, csv, none, of leeg voor een puur presentationele
component zonder enige datasource.
progEvents en de drie lifecycle-hooks
Eventtypen: 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 vuren van overal af met de actie raise_event; screen_ready is de gebruikelijke mount-hook.
De drie ingebouwde hooks van een component verdelen het werk, en de verkeerde gebruiken is een veelvoorkomende bron van bugs:
screen_ready
Vuurt één keer per instantie af. Maak hier DOM en widgets aan.
on_refresh
Vuurt na elke load af, ook de eerste, direct na screen_ready. Geef hier nieuwe data aan widgets
die al bestaan. Als je refresh-werk in plaats daarvan in screen_ready zet, voert het create-code
opnieuw uit tegen DOM die nog bestaat en stapelt het een tweede widget.
on_unload
Vuurt af wanneer de instantie wordt afgebroken. Vernietig wat de prog heeft gemaakt: widgets,
timers, document- / window-listeners, observers. De engine kan alleen vrijgeven wat hij zelf
heeft gemaakt: een listener die aan document is gebonden, overleeft anders het paneel.
Patronen
- Laad- en lege toestanden: zet
xu-ref="myref"op het aan data gebonden element en bescherm dan skeleton- of lege elementen metxu-renderover(@SYS_GLOBAL_OBJ_REFS).myref, de dataset daarvan wordt gekoppeld zodra er data binnenkomt. - Modals: bouw het dialoogvenster als eigen component en open het met de actie
call_modal. - Een gebonden rij opslaan of verwijderen:
invoke_actionmetact_save/act_delete, of een eigenset_data-prog voor alles voorbij de huidige rij.
Logicaprogramma's en workflows
Logica-progtypen delen de datamachinerie van een component (progDataSource, progFields,
progEvents, properties.progParams) zonder UI:
Parameters
Een aanroeper geeft waarden door via de name.parameters van de actie,
{ "order_id_in": { "value": "", "fx": "@selected_id_v" } }, value voor een statische waarde,
fx voor een expressie. De checker controleert of het doelprogramma bestaat en of zijn menuType
bij de actie past.
Workflowacties
Een workflow is een array van stappen, { "id": "...", "data": { "action": "...", "name": { ... }, "enabled": true }, "props": {} }, in volgorde uitgevoerd. props.condition maakt een stap
voorwaardelijk, props.async: true start hem zonder te wachten. Workflows komen voor in
xu-on:*-handlers, progEvents[].workflow en de eigen workflow van een veld.
invoke_action accepteert act_next, act_prev, act_first, act_last, act_reload,
act_refresh, act_print, act_save, act_delete (alleen in componentcontext).
alter_ui_element, create_ui_element, info_ui_element, remove_ui_element,
empty_ui_element, cache_ui_element, load_ui_element. Stuur de UI aan via velden en xu-exp /
xu-render in plaats van een imperatieve elementactie.
De eigen actiekiezer van Studio biedt AI-agent aanroepen en Triage-agent aanroepen naast de
acties hierboven. Geen van beide staat in deze tabel omdat het geen van beide een echte actie is:
validate_prog heeft er geen case voor en meldt invalid trigger type, en de workflow-engine van
de runtime heeft er ook geen handler voor, dus een opgeslagen stap wordt nooit uitgevoerd, ook niet
als je de fout negeert. Wil je dat één prog een gepubliceerde agent bereikt, voeg dan een
AI-agent-tool toe aan de eigen toollijst van een andere agent (de agentConfig.agent_tools van
een document met menuType: "ai_agent"), niet een workflowstap op een component, get_data of een
ander progtype.
De name.value van update wijst velden toe met @field: expression-paren gescheiden door
puntkomma's, of een JSON5-object, "@saving_v: true; @status_v: 'sent'". Een ander programma
aanroepen noemt het onder name.prog, waarbij de actie bij het eigen type van het programma past
(get_data heeft een get_data-prog nodig, call_native_javascript een javascript-prog, enzovoort).
call_library roept een methode van een geïnstalleerde plugin aan: name.plugin_name moet zijn
gekocht en op de app geïnstalleerd, anders wijst de checker de stap af, name.library_method is een
van de methoden die de plugin exporteert, name.library_props zijn gedeclareerde velden. Twee
propnamen zijn een conventie over plugins heen en niet specifiek voor één ervan:
event_name_for_successful_callback vuurt dat event af met het antwoord van de methode,
field_id_to_return_result schrijft het antwoord direct in dat veld, geen van beide is verplicht.
Typen van 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 is de
gebruikelijke init-hook; before_record / after_record /
record_not_found / locate_not_found zijn datalifecycle, vooral voor set_data en batch;
client_interval is een herhalende timer; user_defined vuurt af vanuit de actie raise_event.
Tabellen
Een tabelprog (menuType: "table") definieert een databasetabel: zijn kolommen (tableFields),
zijn indexen (tableIndexes) en de databaseplugin die hem opslaat (properties.databaseSocket).
Boomouder: database, of een map eronder.
databaseSocketmoet een databaseplugin noemen die op het project is geïnstalleerd,@xuda.io/xuda-dbs-plugin-xudais de standaard van het platform; een bestaande tabel in hetzelfde project is de referentie voor welke socket je hergebruikt.- Minstens één veld en minstens één index zijn verplicht.
field_idbegint met een letter, gevolgd door letters, cijfers, underscore, streepje, dubbele punt of punt, en blijft uniek binnen de tabel.fieldTypeisstring,number,boolean,array,objectofdate;mandatory: truemaakt het verplicht bij het opslaan.- Elke index heeft een niet-lege
nameenkeysnodig, en elke sleutel moet een bestaandefield_idzijn.
Conventie: geef kolommen een voorvoegsel met een tabelcode van drie letters, een tabel met de naam
"ORD - Orders" krijgt ORD_Id, ORD_Total, ORD_Status. Geef elke tabel een uniek veld
<TBL>_Id met een unieke index erop, een binding van een component aan één record heeft die nodig.
Een tabel wordt op drie manieren gebruikt: de progDataSource.dataSourceTableId van een component
of query, een get_data / set_data / batch-prog voor toegang op rijniveau vanuit workflows, of
xu.dbs_create / dbs_read / dbs_update / dbs_delete vanuit een script, hierna behandeld.
JavaScript-programma's
Een javascript-prog (menuType: "javascript") bevat echte JS-broncode in scriptData.value,
bij het opslaan gecompileerd. save_prog start die build en geeft het resultaat terug als
data.compile, { ok: true, dependencies } of { ok: false, error }. Een mislukte compilatie
slaat het document nog steeds op, dus een build leest compile.ok en lost het op voordat hij
verdergaat.
Het uitvoeringscontract
De broncode is geschreven als een gewone async-body, zonder export en zonder wrapper. Tijdens de
uitvoering draait hij als:
params zijn de al geëvalueerde invoer van de aanroeper; xu is de runtime-API hieronder; een
returnwaarde is optioneel, de idiomatische manier om resultaten terug te geven is
xu.set_field_value op de velden van de aanroepende component. Aanhalingstekens zijn hier prima,
anders dan in een waarde van het attribuut xu-script.
De xu-runtime-API
dbs_*-methoden nemen de eigen _id van de tabelprog, nooit een naam. Selectors zijn objecten in
Mongo-stijl op de veld-id's, {} geeft alles terug (standaardlimiet 999). De projectie fields is optioneel: [] geeft alle velden terug en een lijst veld-id's alleen die velden.
Data aanleveren: velden, geen parameters
call_native_javascript evalueert geen {value, fx}-parameterwrappers, name.parameters komt
ongewijzigd bij het script aan. Het betrouwbare contract: de component zet de payload eerst in een
veld (een update-stap of een xu-bind-invoer), de workflow roept de prog aan met lege
parameters: {}, en het script leest het met xu.get_field_value en rapporteert terug met
xu.set_field_value. Aanroepen vanuit een ander script, xu.call_javascript(prog_id, {...}), geeft
params wel direct door.
Eigenaardigheden van de live preview
- Datawrites bereiken de echte database, maar
xu.dbs_readleest een lokale conceptopslag die mogelijk geen verse serverrijen bevat: een read direct na een write kan in de preview leeg terugkomen terwijl de write is aangekomen (zichtbaar in het tabblad Data van de tabel in Studio). Gedeployde apps lezen en schrijven dezelfde opslag. - Gecompileerde scripts cachen hard in dev-previews: een draaiende preview kan het vorige script blijven uitvoeren, ook na herladen nadat een opslag het opnieuw compileert. Een harde browserverversing lost het op.
xu.alertmet weergavemodal,toastofbrowserkan in de preview verschijnen als een native, blokkerendealert().xu.set_field_valuein een statusveld is de veiligere manier om terug te rapporteren.
javascript-prog tegenover het attribuut xu-script
Technieken zonder aanhalingstekens voor xu-script / xu-style
Het designercanvas serialiseert attribuutwaarden zonder escaping, dus één aanhalingsteken
beschadigt de markup van de component. Template literals vermijden stringaanhalingstekens helemaal
(el.textContent = `Ready`); het letterlijke teken ", bijvoorbeeld bij het bouwen van CSV,
komt uit String.fromCharCode(34); CSS-attribuutselectors zijn zonder aanhalingstekens geldig
(el.querySelector(`[data-role=import-btn]`)); en een bescherming tegen herhaalde runs,
if (el.__bound) return; el.__bound = true;, voorkomt dat een script bij opnieuw renderen dubbel bindt.
Valkuilen
Elk item hieronder heeft ooit een echte build gebroken. validate_prog vangt de meeste op, voer het
vóór elke opslag uit.
API-werking
- Elk antwoord is
{ code, data },code < 0is een fout. create_proggeeft het nieuwe document terug onderdata.prog; het hele antwoord opslaan in plaats daarvan bewaart een misvormd document metpropertiesbegraven onderprog.save_progvervangt het hele document. Begin vanuit het huidige document, nooit vanuit een met de hand samengesteld skelet; een-409betekent dat het sinds de laatste read is gewijzigd, haal opnieuw op, pas opnieuw toe, probeer opnieuw.- Via MCP worden
prog_jsonenproperties_jsonals strings doorgegeven: de laag met het toolschema verwijdert onbekende sleutels uit een objectparameter en kan stilletjes hele secties laten vallen. delete_progis een zachte verwijdering, het zetstat: 4. De nodeglobal_<app_id>kan niet worden verwijderd.
Documentinhoud
- Geen
'of"in waarden vanxu-scriptofxu-style. - Sleutels met het voorvoegsel
$($folded,$childrenClass,$nodeBackClass), pluspath,code,editCode, zijn view-state van de designer en horen nooit in een opgeslagenprogUi-node. - Geen nodetypen
commentoftext, alleen elementen, statische tekst incontent. - Elke elementnode heeft
attributes: {}enchildren: []nodig, ook als ze leeg zijn. xu-exp:classvervangt de statischeclass, elke benodigde klasse hoort in de expressie.xu-bindis een kale veld-id, zonder@, overal elders gebruiken velden@.- Alleen de gedocumenteerde
xu-*-attributen doen iets, een verzonnen attribuut wordt stilletjes genegeerd envalidate_progwaarschuwt. - De boomroot van een
ai_agent-prog isai_agents, sla hem op metstudio_meta.parentId: "ai_agents"(of een map-id eronder) als de checkerparentIdaanvlagt.
Runtime en rendering
- Een
tagNamemet hoofdletter wordt altijd als component opgeëist, zelfs bij een typfout, en geeft bij het mounten een fout met de tag, delibraryen elke geprobeerde bron, er is geen stil "wordt niet gerenderd" zoals bij eenxu-panelzonder geselecteerd programma. validate_progcontroleert componenttags oflibrary-waarden niet, alleen de live preview vangt een verkeerd gespelde op.- Geen utility-CSS (Tailwind of anders) tijdens runtime, tenzij de
uiFramework-plugin van het project het echt levert, klassen alsp-4doen anders stilletjes niets. Zelfstandige styling isxu-style, automatisch afgebakend door[xu-ui-id]. xu-scriptdraait één keer per zichtbaarheid van het element en kan bij opnieuw renderen weer afgaan, bescherm metel.__bounden beperk queries totel.
Data en scripts
- Parameters van
call_native_javascriptworden niet geëvalueerd, geef data in plaats daarvan door via velden (zie Data aanleveren hierboven). - Rijen van
dbs_readzijn{id, value}, velden staan onder.value, de rij-id op.id. Geef geen projectiefieldsmee, die breekt het lezen aan de serverkant. - Zet binnen
xu-forde iterator tussen haakjes,(@_FOR_VAL).CNT_Nameevalueert,@_FOR_VAL.CNT_Namefaalt stilletjes en rendert in plaats daarvan de vervangen brontekst. - Writes uit de preview komen in de echte database; reads in de preview komen uit een lokale conceptopslag die direct na een write leeg kan lijken.
- Geef de voorkeur aan een statusveld boven de weergave
modaloftoastvanxu.alertin previews, die kan renderen als een native, blokkerendealert().
Je werk verifiëren
Haal na het opslaan opnieuw op met get_prog en vergelijk met wat je verwachtte. Open voor UI-werk
de component in Studio en druk op de afspeelknop voor de preview, of op de live-preview-URL van het
project als die beschikbaar is. Controleer bij een javascript-prog data.compile.ok bij elke
opslag. Los elke fout van validate_prog op; behandel de waarschuwingen, aanhalingstekens,
$-sleutels, onbekende attributen, als punten om nu op te lossen en niet als ruis.