Studio LLM-guiden
Prog-dokumentmodellen, referansen for xu-*-attributter og arbeidsflytreglene en AI-agent får lære før det første verktøykallet.
Hvert Studio-prosjekt, og hver tabell, skjerm, skript og rute i det, er ett CouchDB-JSON-dokument
kalt en prog (docType: "studio"). Denne siden er den samme referansen en AI-agent får når den
bygger en, skrevet om som dokumentasjon: formen på dokumentet, attributtene som driver
brukergrensesnittet, handlingene en arbeidsflyt kan utføre, og feilene som dukker opp i virkelige bygg.
Hvordan en AI-agent får denne guiden
Koble en MCP-klient til Xuda, så bærer det første svaret, initialize-kallet, denne guiden som
øktens instructions, slått sammen på nytt fra plattformens egne levende regler slik at den aldri kan
beskrive noe den distribuerte kontrollen ikke lenger håndhever. Se
Koble til en AI-klient over MCP.
Fra inne i en økt når to metoder det samme materialet direkte, over MCP eller vanlig REST, og de krever ingenting utover en vanlig API-nøkkel:
Den foreskrevne rekkefølgen: les emnet som passer det du bygger, hent et passende eksempel, opprett
progen gjennom fabrikken (create_prog), bygg inne i innholdsseksjonene, valider (validate_prog)
og rett alt den melder, lagre (save_prog), og hent så på nytt for å verifisere. En lagring som gir
-409 betyr at dokumentet er endret siden det ble lest: hent på nytt, bruk endringene på nytt, prøv
igjen.
Prog-dokumentmodellen
Konvolutten
Server- og fabrikkkode eier disse feltene; et skrevet bygg redigerer bare innholdsseksjonene under dem.
_idfølger<last 3 chars of app_id>_<3-letter type abbreviation>_<12 hex>, for eksempel392_cmp_...for en komponent,392_tbl_...for en tabell,392_jvs_...for en javascript-prog,392_gtd_.../392_std_...for get_data / set_data,392_fld_...for en mappe. Fabrikken genererer ID-er, et bygg finner aldri på en.stater 3 for aktiv, 4 for mykt slettet (det en sletting av en prog setter). Studios tre viser barestat: 3.properties.menuTypeer én avglobals,table,get_data,set_data,batch,alert,javascript,folder,route,api,component,ai_agent.studio_meta.parentIdplasserer noden i Studio-treet: enten ID-en til en annen prog (vanligvis en mappe) eller en av typerøttene,programs(logikk og komponenter),database(tabeller),routes,globals,ai_agents. EnparentIdsom ikke gjenkjennes gjør noden usynlig i treet og er en kontrollfeil.
Innholdsseksjoner etter menuType
Globals-dokumentet
Hvert prosjekt har nøyaktig ett global_<app_id>-dokument (menuType: "globals"). Feltene i
progFields kan leses fra alle andre progger som @field_id. To systemglobaler følger med i hvert
prosjekt: @SYS_GLOBAL_OBJ_LOGIN_USER_INFO for den innloggede brukeren, og @SYS_GLOBAL_OBJ_REFS
for elementer registrert med xu-ref. Verken globals-dokumentet eller trerota kan slettes.
Strukturelle krav
properties,properties.menuType,properties.menuName,studio_metaogstudio_meta.parentIder obligatoriske på hvert dokument.- En
progFields-oppføring trenger en unikid,data.field_id, endata.typesom ervirtual,table,expressionellerdatasource, og enprops.fieldTypesom erstring,number,boolean,arrayellerobject. - Reserverte variabelnavn i kjøretiden,
_NULL,_THIS,_FOR_KEY,_FOR_VAL,_ROWNO,_ROWID,_ROWDOC,_KEY,_VAL, defineres aldri på nytt som felt-ID-er. - Like ID-er, ukjente
menuType-verdier og feilformede seksjoner er alle harde feil somvalidate_progmelder direkte.
Uttrykk og xu-*-attributter
Uttrykkssyntaks
Uttrykk kjører mot progens eget datasett. Ethvert felt, lokalt, tabellbundet, globalt eller en
parameter, refereres til med @: @search_v, @ORD_Total, @SYS_GLOBAL_OBJ_LOGIN_USER_INFO, vanlig
JavaScript rundt, @count_v > 0 ? 'has rows' : 'empty'. En objektliteral må pakkes inn i parenteser,
({ ORD_Status: @status_v }). Inne i en xu-for-løkke er det gjeldende elementet @_FOR_VAL og
nøkkelen eller indeksen @_FOR_KEY (kan gis nytt navn med xu-for-key / xu-for-val). xu-render
og andre betingelser returnerer sann- eller usann-verdien direkte, aldri en "Y" / "N"-streng eller
en ekstra sammenligning.
Overalt ellers refereres et felt med @. xu-bind tar den blotte felt-ID-en i stedet:
xu-bind="search_v", aldri xu-bind="@search_v".
xu-attributtene
Prefiksfamilier
Attributtfamilier som tar et suffiks. xu-on-verdier er alltid matriser med håndteringsobjekter;
xu-exp-verdier er alltid uttrykksstrenger.
Verdien til et xu-on:*-attributt er alltid en matrise med håndteringsobjekter, og hver workflow
er en matrise med handlingstrinn (den fullstendige handlingsreferansen står nedenfor, under
Logikkprogrammer og arbeidsflyter). Et trinns props.condition styrer om det kjører; props.async: true utløser det uten å vente.
Kritisk semantikk
xu-exp:classerstatter det statiskeclass-attributtet i stedet for å legge til. På et element som har begge blir det statiske ignorert, så oppsettklassene hører hjemme inne i uttrykket også:xu-exp:class="'card p-4 ' + (@active_v ? 'ring' : '')".xu-scripttar et blottetfunction (el) { ... }-uttrykk,eval-et og kalt med DOM-elementet når noden blir synlig. Vokt mot ny kjøring (if (el.__bound) return; el.__bound = true;) og avgrens hvert oppslag tilel, aldri tildocument.xu-styleer automatisk avgrenset: hver velger får nodens[xu-ui-id]som prefiks, så vanlige element- og klassevelgere forblir lokale og lekker aldri.- Verken
xu-script- ellerxu-style-verdier kan inneholde et anførselstegn ('eller"), designerlerretet serialiserer attributter uten å escape dem, og ett anførselstegn ødelegger komponenten. Avsnittet om JavaScript-programmer nedenfor tar for seg teknikker uten anførselstegn. - Statisk tekst hører i et elements
content-egenskap.xu-exp:xu-contenter bare for dynamisk tekst.
Tagger
Skrivetagger i tillegg til vanlig HTML: xu-template, xu-single-view, xu-multi-view, xu-panel,
xu-teleport, xu-slot.
xu-single-viewavgrenser én enkelt post (en skjemarot, kan også brukes nøstet).xu-multi-viewgjentar barna sine én gang per rad i de bundne dataene.xu-panelbygger inn en annen prog (program-attributt plussxu-exp:<param>-inndata). Bare vanlige HTML-attributter (class,id,style,title,hidden,slot,name,role,tabindex) hører hjemme på den ved siden av parameteruttrykkene.xu-teleportgjengir barna sine på et annet DOM-mål (toellerxu-exp:to).- Et tagnavn som starter med stor bokstav (
Button,Card) er en kompilert komponent, ikke et HTML-element, se Innbygging nedenfor.
Komponenter
En komponent (menuType: "component") er en UI-enhet: et elementtre (progUi) bundet til lokal
tilstand (progFields), valgfrie data (progDataSource), livssykluslogikk (progEvents) og et
grensesnitt for inn- og utdata (properties.progParams).
Egenskaper
renderTypeerformfor én enkelt post (rotelementxu-single-view) ellergrid/listfor én gjentatt per datarad (rotelementxu-multi-view).rwModeerRfor lesing ellerUfor oppdatering;allowCreatesier om en ny rad kan settes inn når ingen samsvarer.- Navnekonvensjon for
progParams: parametere ender på_in/_out, komponentlokale virtuelle felt ender på_v. uiFrameworkspeiler det prosjektets eksisterende komponenter allerede bruker. Et eksisterende prosjekt som utelater den bør fortsette å utelate den, å sette en rammeverk-plugin som prosjektets drive faktisk ikke serverer, får live forhåndsvisningen til å stoppe på en blank skjerm.
Elementtreet (progUi)
Fabrikkens root-node blir stående; et bygg jobber inne i children. Hver node trenger en unik ID
(nye noder bruker ui-<uuid>), type: "element" og et tagName, ingen comment- eller
text-nodetyper, statisk tekst ligger i content i stedet. Hver node trenger attributes: {} og
children: [] selv når de er tomme, designerlerretets serialiserer dereferer begge på hver node, og
en utelatelse ødelegger komponentens egen forhåndsvisning.
Innbygging: xu-panel eller en kompilert komponent
Begge monteres transparent, uten omsluttende element, og begge avgjøres av ett signal: om tagName
starter med stor bokstav.
xu-panel,tagNamemed små bokstaver pluss etprogram-attributt, bygger inn en annen prog, et databundet eller tilstandsfullt barn med egne felt og hendelser.programer barnets ID (ellerxu-exp:progfor et dynamisk), verdier når_in-parameterne dets gjennomxu-exp:<param>.- En tag med stor bokstav pluss et
library-attributt monterer en kompilert komponent, en primitiv fra et designsystem eller en del appen selv har kompilert. Hvert vanlig attributt blir en prop (props.<name>), aldri et DOM-attributt, siden komponenten ikke gjengir noe element selv. En komponentnode har ingen utparametere, i motsetning tilxu-panelskriver ingenting en verdi tilbake til feltene dine.
En skrivefeil som <Buton> regnes fortsatt som en komponenttag, faller aldri tilbake til et ukjent
HTML-element, og kaster en feil ved montering som navngir taggen, biblioteket og hver kilde som ble
prøvd. validate_prog sjekker ikke komponenttagger eller library-verdier i dag, live
forhåndsvisningen er den eneste kontrollen.
progFields
data.type er virtual for lokal tilstand, table for en kolonne i den bundne datakilden, eller
expression / datasource. Et felts workflow kjører ved endring. En standardverdi setter
props.fieldValue; et beregnet felt setter props.fieldComputed: true pluss
propExpressions.fieldValue.
progDataSource
En enkelt post etter nøkkel (skjema): dataSourceFilterModelType: "index" med en dataSourceIndexId
som finnes i tabellens egne tableIndexes. En filtrert liste (grid eller list):
dataSourceFilterModelType: "query" med filterModelMongoFx, en uttrykksstreng i Mongo-stil.
dataSourceType er table, array, json, csv, none, eller tom for en rent presentasjonell
komponent uten noen datakilde i det hele tatt.
progEvents og de tre livssykluskrokene
Hendelsestyper: 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-hendelser utløses fra hvor som helst med raise_event-handlingen; screen_ready er
den vanlige monteringskroken.
En komponents tre innebygde kroker deler arbeidet, og å bruke feil en er en vanlig kilde til feil:
screen_ready
Utløses én gang per instans. Lag DOM og widgeter her.
on_refresh
Utløses etter hver innlasting, også den første, rett etter screen_ready. Gi nye data til widgeter
som allerede finnes. Hvis du legger oppfriskingsarbeid i screen_ready i stedet, kjøres opprettelseskode
på nytt mot DOM som fortsatt finnes, og en andre widget stables oppå den første.
on_unload
Utløses når instansen rives ned. Ødelegg det progen opprettet, widgeter, tidtakere,
document- / window-lyttere, observatører. Motoren kan bare frigjøre det den selv opprettet, en
lytter bundet til document overlever ellers panelet.
Mønstre
- Innlastings- og tomtilstander: sett
xu-ref="myref"på det databundne elementet, og styr så skjelett- eller tomelementer medxu-renderover(@SYS_GLOBAL_OBJ_REFS).myref, datasettet festes når dataene kommer. - Modaler: bygg dialogen som en egen komponent, åpne den med
call_modal-handlingen. - Lagre eller slette en bundet rad:
invoke_actionmedact_save/act_delete, eller en egenset_data-prog for alt utover gjeldende rad.
Logikkprogrammer og arbeidsflyter
Logikkprogtyper deler en komponents datamaskineri (progDataSource, progFields, progEvents,
properties.progParams) uten noe brukergrensesnitt:
Parametere
En kaller sender verdier gjennom handlingens name.parameters,
{ "order_id_in": { "value": "", "fx": "@selected_id_v" } }, value for en statisk verdi, fx for
et uttrykk. Kontrollen sjekker at målprogrammet finnes og at dens menuType samsvarer med
handlingen.
Arbeidsflythandlinger
En arbeidsflyt er en matrise med trinn, { "id": "...", "data": { "action": "...", "name": { ... }, "enabled": true }, "props": {} }, kjørt i rekkefølge. props.condition styrer om et trinn kjører,
props.async: true utløser det uten å vente. Arbeidsflyter finnes i xu-on:*-håndterere,
progEvents[].workflow og et felts egen workflow.
invoke_action godtar act_next, act_prev, act_first, act_last, act_reload,
act_refresh, act_print, act_save, act_delete (bare i komponentkontekst).
alter_ui_element, create_ui_element, info_ui_element, remove_ui_element,
empty_ui_element, cache_ui_element, load_ui_element. Styr brukergrensesnittet gjennom felt og
xu-exp / xu-render i stedet for en imperativ elementhandling.
Studios egen handlingsvelger tilbyr Kall AI-agent og Kall triageagent ved siden av
handlingene ovenfor. Ingen av dem står i denne tabellen fordi ingen av dem er en ekte handling:
validate_prog har ingen case for dem og melder invalid trigger type, og arbeidsflytmotoren i
kjøretiden har heller ingen håndterer for dem, så et lagret trinn kjører aldri selv om feilen
ignoreres. For å la én prog nå en publisert agent, legg til et AI-agent-verktøy i en annen agents
egen verktøyliste i stedet (et menuType: "ai_agent"-dokuments agentConfig.agent_tools), ikke et
arbeidsflyttrinn på en komponent, get_data eller noen annen progtype.
updates name.value tildeler felt med semikolonseparerte @field: expression-par, eller et
JSON5-objekt, "@saving_v: true; @status_v: 'sent'". Å kalle et annet program navngir det under
name.prog, og handlingen må samsvare med programmets egen type
(get_data trenger en get_data-prog, call_native_javascript en javascript-prog, og så videre).
call_library kaller en installert plugin-metode: name.plugin_name må være kjøpt og installert på
appen, ellers avviser kontrollen trinnet, name.library_method er en av metodene pluginen eksporterer,
name.library_props de deklarerte feltene. To prop-navn er en konvensjon på tvers av plugin-moduler
og ikke spesifikke for noen av dem: event_name_for_successful_callback utløser den hendelsen med
metodens svar, field_id_to_return_result skriver svaret rett inn i det feltet, ingen av dem er
påkrevd.
Typer for 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 er den
vanlige init-kroken; before_record / after_record /
record_not_found / locate_not_found er datalivssyklus, særlig for set_data og batch;
client_interval er en gjentakende tidtaker; user_defined utløses fra raise_event-handlingen.
Tabeller
En tabellprog (menuType: "table") definerer en databasetabell: kolonnene (tableFields),
indeksene (tableIndexes) og database-pluginen som lagrer den (properties.databaseSocket).
Treforelder: database, eller en mappe under den.
databaseSocketmå navngi en database-plugin som er installert i prosjektet,@xuda.io/xuda-dbs-plugin-xudaer plattformens standard; en eksisterende tabell i samme prosjekt er referansen for hvilken socket som skal gjenbrukes.- Minst ett felt og minst én indeks er påkrevd.
field_idstarter med en bokstav, så bokstaver, sifre, understrek, bindestrek, kolon eller punktum, og forblir unik i tabellen.fieldTypeerstring,number,boolean,array,objectellerdate;mandatory: truegjør det påkrevd ved lagring.- Hver indeks trenger et ikke-tomt
nameogkeys, og hver nøkkel må være en eksisterendefield_id.
Konvensjon: sett en tre-bokstavs tabellkode som prefiks på kolonnene, en tabell som heter
"ORD - Orders" får ORD_Id, ORD_Total, ORD_Status. Gi hver tabell et unikt <TBL>_Id-felt med en
unik indeks på det, en komponentbinding mot én enkelt post trenger det.
En tabell brukes på tre måter: en komponents eller et søks progDataSource.dataSourceTableId, en
get_data / set_data / batch-prog for tilgang på radnivå fra arbeidsflyter, eller xu.dbs_create /
dbs_read / dbs_update / dbs_delete fra et skript, som behandles neste.
JavaScript-programmer
En javascript-prog (menuType: "javascript") holder ekte JS-kildekode i scriptData.value,
kompilert ved lagring. save_prog utløser den byggingen og returnerer resultatet som data.compile,
{ ok: true, dependencies } eller { ok: false, error }. En mislykket kompilering lagrer likevel dokumentet, så
et bygg leser compile.ok og retter det før det går videre.
Utførelseskontrakten
Kilden skrives som en vanlig async-kropp, uten export, uten omslag. Ved kjøring utføres den som:
params er kallerens allerede evaluerte inndata; xu er kjøretids-API-et nedenfor; en returverdi er
valgfri, den vanlige måten å gi resultater tilbake på er xu.set_field_value på den kallende
komponentens felt. Anførselstegn er greit her, i motsetning til i en xu-script-attributtverdi.
Kjøretids-API-et xu
dbs_*-metodene tar tabellprogens egen _id, aldri et navn. Velgere er objekter i Mongo-stil på
felt-ID-ene, {} returnerer alt (standardgrense 999). fields-projeksjonen er valgfri, [] gir alle felt, og en liste med felt-ID-er gir bare dem.
Sende inn data: felt, ikke parametere
call_native_javascript evaluerer ikke {value, fx}-parameteromslag, name.parameters når skriptet
rått. Den pålitelige kontrakten: komponenten legger nyttelasten i et felt først (et update-trinn
eller en xu-bind-inndata), arbeidsflyten kaller progen med tomme parameters: {}, og skriptet leser
den med xu.get_field_value og rapporterer tilbake med xu.set_field_value. Hvis du i stedet kaller
fra et annet skript, sender xu.call_javascript(prog_id, {...}) parametere direkte.
Særheter i live forhåndsvisning
- Dataskrivinger når den ekte databasen, men
xu.dbs_readleser et lokalt kladdelager som kanskje ikke har ferske serverrader, en lesing rett etter en skriving kan komme tom tilbake i forhåndsvisning selv om skrivingen traff (synlig i tabellens Data-fane i Studio). Distribuerte apper leser og skriver det samme lageret. - Kompilerte skript caches hardt i utviklingsforhåndsvisninger, en kjørende forhåndsvisning kan fortsette å kjøre det forrige skriptet selv etter omlastinger når en lagring kompilerer det på nytt. En hard nettleseroppfriskning løser det.
xu.alertmedmodal-,toast- ellerbrowser-visning kan dukke opp som en innebygd, blokkerendealert()i forhåndsvisning.xu.set_field_valueinn i et statusfelt er en tryggere måte å melde tilbake på.
javascript-prog eller xu-script-attributt
Teknikker uten anførselstegn for xu-script / xu-style
Designerlerretet serialiserer attributtverdier uten å escape dem, så ett enkelt anførselstegn ødelegger
komponentens markup. Malstrenger unngår anførselstegn i strenger helt
(el.textContent = `Ready`); selve "-tegnet, for eksempel når du bygger CSV, kommer fra
String.fromCharCode(34); CSS-attributtvelgere er gyldige uten anførselstegn
(el.querySelector(`[data-role=import-btn]`)); og en vakt mot ny kjøring,
if (el.__bound) return; el.__bound = true;, hindrer at et skript bindes to ganger ved ny gjengivelse.
Fallgruver
Hver oppføring nedenfor ødela et virkelig bygg på et tidspunkt. validate_prog fanger de fleste av
dem, kjør den før hver lagring.
API-mekanikk
- Hvert svar er
{ code, data },code < 0er en feil. create_progreturnerer det nye dokumentet underdata.prog, å lagre hele svaret i stedet lagrer et feilformet dokument medpropertiesbegravd underprog.save_progerstatter hele dokumentet. Start fra det gjeldende dokumentet, aldri et skjelett satt sammen for hånd; en-409betyr at det er endret siden siste lesing, hent på nytt, bruk endringene på nytt, prøv igjen.- Over MCP sendes
prog_jsonogproperties_jsonsom strenger, verktøyskjemalaget fjerner ukjente nøkler fra en objektparameter og kan stille droppe hele seksjoner. delete_proger en myk sletting, den setterstat: 4.global_<app_id>-noden kan ikke slettes.
Dokumentinnhold
- Ingen
'eller"inne ixu-script- ellerxu-style-verdier. $-prefiksede nøkler ($folded,$childrenClass,$nodeBackClass), plusspath,code,editCode, er visningstilstand i designeren og hører aldri hjemme i en lagretprogUi-node.- Ingen
comment- ellertext-nodetyper, bare elementer, statisk tekst icontent. - Hver elementnode trenger
attributes: {}ogchildren: []selv når de er tomme. xu-exp:classerstatter den statiskeclass, hver nødvendig klasse hører hjemme inne i uttrykket.xu-binder en blott felt-ID, uten@, overalt ellers bruker felt@.- Bare de dokumenterte
xu-*-attributtene gjør noe, et oppfunnet blir stille ignorert ogvalidate_progadvarer. - Treroten til en
ai_agent-prog erai_agents, lagre den medstudio_meta.parentId: "ai_agents"(eller en mappe-ID under den) hvis kontrollen flaggerparentId.
Kjøretid og gjengivelse
- Et
tagNamemed stor bokstav regnes alltid som en komponent, selv en skrivefeil, og kaster en feil ved montering som navngir taggen,libraryog hver kilde som ble prøvd, det finnes ingen stille «gjengis ikke» slik enxu-paneluten valgt program har. validate_progsjekker ikke komponenttagger ellerlibrary-verdier, bare live forhåndsvisning fanger en feilstavet en.- Ingen verktøy-CSS (Tailwind eller annen) i kjøretiden med mindre prosjektets
uiFramework-plugin faktisk gir den, klasser somp-4gjør stille ingenting ellers. Selvstendig styling erxu-style, automatisk avgrenset av[xu-ui-id]. xu-scriptkjører én gang per synlighet av elementet og kan utløses på nytt ved ny gjengivelse, vokt medel.__boundog avgrens oppslag tilel.
Data og skript
call_native_javascript-parametere evalueres ikke, send data gjennom felt i stedet (se Sende inn data, ovenfor).dbs_read-rader er{id, value}, felt ligger under.value, rad-ID-en på.id. Ikke send enfields-projeksjon, den ødelegger lesingen på serversiden.- Inne i
xu-for, pakk iteratoren i parenteser,(@_FOR_VAL).CNT_Nameevalueres,@_FOR_VAL.CNT_Namefeiler stille og gjengir den erstattede kildeteksten i stedet. - Skrivinger i forhåndsvisning havner i den ekte databasen; lesinger i forhåndsvisning kommer fra et lokalt kladdelager som kan se tomt ut rett etter en skriving.
- Foretrekk et statusfelt framfor
xu.alerts modal- eller toast-visning i forhåndsvisninger, den kan gjengis som en innebygd, blokkerendealert().
Verifisere arbeidet ditt
Hent på nytt med get_prog etter lagring og sammenlign med det du forventet. For UI-arbeid, åpne
komponenten i Studio og trykk på avspillingsknappen for forhåndsvisning, eller prosjektets
live-forhåndsvisnings-URL når en finnes. For en javascript-prog, sjekk data.compile.ok ved hver
lagring. Rett hver validate_prog-feil; behandle advarslene, anførselstegn, $-nøkler, ukjente
attributter, som ting som skal rettes nå i stedet for støy.