Studio LLM-vejledningen
Prog-dokumentmodellen, xu-*-attributreferencen og de workflow-regler, en AI-agent får lært, før dens første værktøjskald.
Hvert Studio-projekt, og hver tabel, skærm, script og rute i det, er ét CouchDB-JSON-dokument kaldet
en prog (docType: "studio"). Denne side er den samme reference, som en AI-agent får, når den
bygger en, skrevet om som dokumentation: dokumentets form, de attributter der driver dets
brugerflade, de handlinger en workflow kan udføre, og de fejl, der dukker op i rigtige builds.
Sådan får en AI-agent denne vejledning
Forbind en MCP-klient til Xuda, og det første svar, initialize-kaldet, bærer denne vejledning som
sessionens instructions, frisk sammenflettet fra platformens egne levende regler, så den aldrig
kan beskrive noget, som den udrullede checker ikke længere håndhæver. Se
Forbind en AI-klient over MCP.
Inde fra en session når to metoder det samme materiale direkte, over MCP eller almindelig REST, og kræver intet ud over en normal API-nøgle:
Den foreskrevne rækkefølge: læs det emne, der passer til det, du bygger, hent et matchende eksempel,
opret prog'en gennem fabrikken (create_prog), byg inde i dens indholdssektioner, valider
(validate_prog) og ret alt, den rapporterer, gem (save_prog), og hent den så igen for at
verificere. Et gem, der returnerer -409, betyder, at dokumentet er ændret, siden det blev læst:
hent igen, anvend ændringerne igen, prøv igen.
Prog-dokumentmodellen
Konvolutten
Server- og fabrikskode ejer disse felter. Et forfattet build redigerer kun de indholdssektioner, der ligger 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 tabel,392_jvs_...for en javascript-prog,392_gtd_.../392_std_...for get_data / set_data og392_fld_...for en mappe. Fabrikken genererer id'er, et build opfinder aldrig et.stater 3 for aktiv og 4 for blødt slettet (det, en sletning af en prog sætter). Studios træ viser kunstat: 3.properties.menuTypeer en afglobals,table,get_data,set_data,batch,alert,javascript,folder,route,api,component,ai_agent.studio_meta.parentIdplacerer noden i Studios træ: enten en anden progs id (som regel en mappe) eller en af typeroddene,programs(logik og komponenter),database(tabeller),routes,globals,ai_agents. Et ukendtparentIdgør noden usynlig i træet og er en checker-fejl.
Indholdssektioner efter menuType
Globals-dokumentet
Hvert projekt har præcis ét global_<app_id>-dokument (menuType: "globals"). Dets progFields kan
læses fra alle andre progs som @field_id. To systemglobaler følger med i hvert projekt:
@SYS_GLOBAL_OBJ_LOGIN_USER_INFO for den bruger, der er logget ind, og @SYS_GLOBAL_OBJ_REFS for
elementer registreret med xu-ref. Hverken globals-dokumentet eller trærødden kan slettes.
Strukturelle krav
properties,properties.menuType,properties.menuName,studio_metaogstudio_meta.parentIder obligatoriske på hvert dokument.- En
progFields-post har brug for et uniktid,data.field_id, endata.typeafvirtual,table,expressionellerdatasourceog enprops.fieldTypeafstring,number,boolean,arrayellerobject. - Reserverede runtime-variabelnavne,
_NULL,_THIS,_FOR_KEY,_FOR_VAL,_ROWNO,_ROWID,_ROWDOC,_KEY,_VAL, defineres aldrig igen som felt-id'er. - Dublerede id'er, ukendte
menuTypes og forkert opbyggede sektioner er alle hårde fejl, somvalidate_prograpporterer direkte.
Udtryk og xu-*-attributter
Udtrykssyntaks
Udtryk køres mod progens eget datasæt. Ethvert felt, lokalt, tabelbundet, globalt eller en
parameter, refereres med @: @search_v, @ORD_Total, @SYS_GLOBAL_OBJ_LOGIN_USER_INFO, med
almindelig JavaScript omkring, @count_v > 0 ? 'has rows' : 'empty'. En objektliteral skal omsluttes
af parenteser, ({ ORD_Status: @status_v }). Inde i en xu-for-løkke er det aktuelle element
@_FOR_VAL og dets nøgle eller indeks @_FOR_KEY (kan omdøbes med xu-for-key / xu-for-val).
xu-render og andre betingelser returnerer sand- eller falsk-værdien direkte, aldrig en
"Y" / "N"-streng eller en ekstra sammenligning.
Alle andre steder refereres et felt med @. xu-bind tager i stedet det rene felt-id:
xu-bind="search_v", aldrig xu-bind="@search_v".
xu-attributterne
Præfiksfamilier
Attributfamilier, der tager et suffiks. xu-on-værdier er altid arrays af handler-objekter.
xu-exp-værdier er altid udtryksstrenge.
Værdien af en xu-on:*-attribut er altid et array af handler-objekter, og hver workflow er et
array af handlingstrin (den fulde handlingsreference står nedenfor, under Logikprogrammer og
workflows). Et trins props.condition styrer det. props.async: true udløser det uden at vente.
Afgørende semantik
xu-exp:classerstatter den statiskeclass-attribut i stedet for at lægge til den. Et element, der har begge, får den statiske ignoreret, så layoutklasserne hører også hjemme inde i udtrykket:xu-exp:class="'card p-4 ' + (@active_v ? 'ring' : '')".xu-scripttager et rentfunction (el) { ... }-udtryk, som køres medevalog kaldes med DOM-elementet, når noden bliver synlig. Beskyt mod gentagne kørsler (if (el.__bound) return; el.__bound = true;) og afgræns hver forespørgsel tilel, aldrig tildocument.xu-styleer automatisk afgrænset: hver selektor får nodens[xu-ui-id]som præfiks, så almindelige element- og klasseselektorer forbliver lokale og aldrig lækker.- Hverken
xu-script- ellerxu-style-værdier må indeholde et anførselstegn ('eller"), designerlærredet serialiserer attributter uden escape, og ét anførselstegn ødelægger komponenten. Afsnittet om JavaScript-programmer nedenfor dækker teknikker uden anførselstegn. - Statisk tekst hører hjemme i et elements
content-egenskab.xu-exp:xu-contenter kun til dynamisk tekst.
Tags
Skrive-tags ud over almindelig HTML: xu-template, xu-single-view, xu-multi-view, xu-panel,
xu-teleport, xu-slot.
xu-single-viewafgrænser en enkelt post (en formularrod, kan også bruges indlejret).xu-multi-viewgentager sine børn én gang pr. række i de bundne data.xu-panelindlejrer en anden prog (program-attribut plusxu-exp:<param>-input). Kun almindelige HTML-attributter (class,id,style,title,hidden,slot,name,role,tabindex) hører hjemme på den ud over parameterudtrykkene.xu-teleportrenderer sine børn på et andet DOM-mål (toellerxu-exp:to).- Et tagnavn med stort begyndelsesbogstav (
Button,Card) er en kompileret komponent, ikke et HTML-element, se Indlejring nedenfor.
Komponenter
En komponent (menuType: "component") er en brugerfladeenhed: et element-træ (progUi) bundet til
lokal tilstand (progFields), valgfri data (progDataSource), livscykluslogik (progEvents) og en
input/output-grænseflade (properties.progParams).
Egenskaber
renderTypeerformfor en enkelt post (rodelementxu-single-view) ellergrid/listfor én gentaget pr. datarække (rodelementxu-multi-view).rwModeerRfor læsning ellerUfor opdatering.allowCreatesiger, om en ny række kan indsættes, når ingen matcher.- Navnekonvention for
progParams: parametre ender på_in/_out, komponentlokale virtuelle felter ender på_v. uiFrameworkfølger det, projektets eksisterende komponenter allerede bruger. Et eksisterende projekt, der udelader det, bør fortsat udelade det: at sætte et frameworkplugin, som projektets drev ikke faktisk serverer, får live-forhåndsvisningen til at hænge på en blank skærm.
Element-træet (progUi)
Fabrikkens root-node bliver, og et build arbejder inde i dens children. Hver node skal have et
unikt id (nye noder bruger ui-<uuid>), type: "element" og et tagName, ingen nodetyper som
comment eller text, statisk tekst ligger i stedet i content. Hver node skal have
attributes: {} og children: [], også når de er tomme, designerlærredets serializer
dereferencer begge på hver node, og en udeladelse ødelægger komponentens egen forhåndsvisning.
Indlejring: xu-panel eller en kompileret komponent
Begge monteres transparent, uden omsluttende element, og begge afgøres af ét signal: om tagName
begynder med et stort bogstav.
xu-panel,tagNamemed små bogstaver plus enprogram-attribut, indlejrer en anden prog, et databundet eller tilstandsbærende barn med egne felter og hændelser.programer barnets id (ellerxu-exp:progtil et dynamisk), og værdier når dets_in-parametre gennemxu-exp:<param>.- Et tag med stort begyndelsesbogstav plus en
library-attribut monterer en kompileret komponent, en designsystem-primitiv eller en del, appen selv har kompileret. Hver almindelig attribut bliver en prop (props.<name>), aldrig en DOM-attribut, da komponenten ikke renderer noget eget element. En komponentnode har ingen out-parametre, i modsætning tilxu-panelskriver intet en værdi tilbage til dine felter.
Et tastefejlsramt <Buton> bliver stadig taget som et komponent-tag, falder aldrig tilbage til et
ukendt HTML-element og kaster en fejl ved montering, der nævner tagget, biblioteket og alle kilder,
der blev prøvet. validate_prog tjekker ikke komponent-tags eller library-værdier i dag,
live-forhåndsvisningen er det eneste tjek.
progFields
data.type er virtual for lokal tilstand, table for en kolonne i den bundne datakilde eller
expression / datasource. Et felts workflow køres ved ændring. En standardværdi sætter
props.fieldValue. Et beregnet felt sætter props.fieldComputed: true plus
propExpressions.fieldValue.
progDataSource
En enkelt post via nøgle (formular): dataSourceFilterModelType: "index" med et dataSourceIndexId,
der findes i tabellens egne tableIndexes. En filtreret liste (grid eller liste):
dataSourceFilterModelType: "query" med filterModelMongoFx, en udtryksstreng i Mongo-stil.
dataSourceType er table, array, json, csv, none eller tom for en rent præsentationsmæssig
komponent uden nogen datakilde.
progEvents og de tre livscykluskroge
Hændelsestyper: 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-hændelser udløses hvor som helst fra med handlingen raise_event. screen_ready er
den sædvanlige monteringskrog.
En komponents tre indbyggede kroge deler arbejdet, og at bruge den forkerte er en almindelig kilde til fejl:
screen_ready
Udløses én gang pr. instans. Opret DOM og widgets her.
on_refresh
Udløses efter hver indlæsning, også den første, lige efter screen_ready. Giv nye data til widgets,
der allerede findes. Lægger du opdateringsarbejde i screen_ready i stedet, køres oprettelseskoden
igen mod DOM, der stadig findes, og der stables endnu en widget oven på.
on_unload
Udløses, når instansen rives ned. Ødelæg det, prog'en har oprettet: widgets, timere,
document- / window-lyttere, observatører. Motoren kan kun frigive det, den selv har oprettet, en
lytter bundet til document overlever ellers panelet.
Mønstre
- Indlæsnings- og tomme tilstande: sæt
xu-ref="myref"på det databundne element, og styr så skelet- eller tomme elementer medxu-renderover(@SYS_GLOBAL_OBJ_REFS).myref, dets datasæt knyttes til, når data ankommer. - Modaler: byg dialogen som sin egen komponent og åbn den med handlingen
call_modal. - Gem eller slet en bundet række:
invoke_actionmedact_save/act_delete, eller en dedikeretset_data-prog til alt ud over den nuværende række.
Logikprogrammer og workflows
Logik-prog-typer deler en komponents datamaskineri (progDataSource, progFields, progEvents,
properties.progParams) uden nogen brugerflade:
Parametre
En kalder sender værdier gennem handlingens name.parameters,
{ "order_id_in": { "value": "", "fx": "@selected_id_v" } }, value for en statisk værdi, fx for
et udtryk. Checkeren verificerer, at målprogrammet findes, og at dets menuType matcher handlingen.
Workflow-handlinger
En workflow er et array af trin, { "id": "...", "data": { "action": "...", "name": { ... }, "enabled": true }, "props": {} }, der køres i rækkefølge. props.condition styrer et trin,
props.async: true udløser det uden at vente. Workflows optræder i xu-on:*-handlere,
progEvents[].workflow og et felts egen workflow.
invoke_action accepterer act_next, act_prev, act_first, act_last, act_reload,
act_refresh, act_print, act_save, act_delete (kun i komponentkontekst).
alter_ui_element, create_ui_element, info_ui_element, remove_ui_element,
empty_ui_element, cache_ui_element, load_ui_element. Styr brugerfladen gennem felter og
xu-exp / xu-render i stedet for en imperativ elementhandling.
Studios egen handlingsvælger tilbyder Kald AI-agent og Kald triage-agent ved siden af
handlingerne ovenfor. Ingen af dem står i tabellen, fordi ingen af dem er en rigtig handling:
validate_prog har intet tilfælde for dem og rapporterer invalid trigger type, og
runtime-workflowmotoren har heller ingen handler for dem, så et gemt trin kører aldrig, selv om
fejlen ignoreres. For at lade én prog nå en udgivet agent skal du i stedet tilføje et
AI-agent-værktøj til en anden agents egen værktøjsliste (et menuType: "ai_agent"-dokuments
agentConfig.agent_tools), ikke et workflow-trin på en komponent, get_data eller en anden
prog-type.
updates name.value tildeler felter med @field: expression-par adskilt af semikolon, eller et
JSON5-objekt, "@saving_v: true; @status_v: 'sent'". Når du kalder et andet program, angives det
under name.prog, og handlingen skal matche programmets egen type (get_data kræver en
get_data-prog, call_native_javascript en javascript-prog, og så videre).
call_library kalder en metode i et installeret plugin: name.plugin_name skal være købt og
installeret på appen, ellers afviser checkeren trinnet, name.library_method en af de metoder,
pluginet eksporterer, name.library_props dets erklærede felter. To prop-navne er en konvention på
tværs af plugins og ikke specifikke for ét af dem: event_name_for_successful_callback udløser den
hændelse med metodens svar, field_id_to_return_result skriver svaret direkte ind i det felt, ingen
af dem er påkrævet.
Typer i 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
sædvanlige startkrog. before_record / after_record / record_not_found / locate_not_found er
datalivscyklus, især for set_data og batch. client_interval er en gentagen timer.
user_defined udløses fra handlingen raise_event.
Tabeller
En tabel-prog (menuType: "table") definerer en databasetabel: dens kolonner (tableFields), dens
indekser (tableIndexes) og det databaseplugin, der gemmer den (properties.databaseSocket).
Trærod: database eller en mappe under den.
databaseSocketskal navngive et databaseplugin, der er installeret på projektet,@xuda.io/xuda-dbs-plugin-xudaer platformens standard. En eksisterende tabel i det samme projekt er referencen for, hvilken socket der skal genbruges.- Mindst ét felt og mindst ét indeks er påkrævet.
field_idbegynder med et bogstav, derefter bogstaver, cifre, understreg, bindestreg, kolon eller punktum, og er unikt i tabellen.fieldTypeerstring,number,boolean,array,objectellerdate.mandatory: truegør det påkrævet ved gem.- Hvert indeks skal have et ikke-tomt
nameogkeys, og hver nøgle skal være et eksisterendefield_id.
Konvention: giv kolonner et præfiks med en tobogstavs- eller trebogstavskode for tabellen, en tabel
ved navn "ORD - Orders" får ORD_Id, ORD_Total, ORD_Status. Giv hver tabel et unikt
<TBL>_Id-felt med et unikt indeks på det, en komponentbinding til en enkelt post har brug for det.
En tabel bruges på tre måder: en komponents eller forespørgsels progDataSource.dataSourceTableId,
en get_data / set_data / batch-prog til adgang på rækkeniveau fra workflows eller
xu.dbs_create / dbs_read / dbs_update / dbs_delete fra et script, som beskrives næste gang.
JavaScript-programmer
En javascript-prog (menuType: "javascript") rummer rigtig JS-kilde i scriptData.value, kompileret
ved gem. save_prog udløser det build og returnerer resultatet som data.compile, { ok: true, dependencies } eller { ok: false, error }. En mislykket kompilering gemmer stadig dokumentet, så
et build læser compile.ok og retter det, før det går videre.
Udførelseskontrakten
Kilden skrives som en almindelig async-krop, uden export og uden omslag. Ved kørsel udføres den
som:
params er kalderens allerede evaluerede input. xu er runtime-API'en nedenfor. En returværdi er
valgfri, den idiomatiske måde at give resultater tilbage på er xu.set_field_value på den kaldende
komponents felter. Anførselstegn er i orden her, i modsætning til en xu-script-attributværdi.
xu-runtime-API'en
dbs_*-metoderne tager tabelprog'ens eget _id, aldrig et navn. Selektorer er objekter i
Mongo-stil på felt-id'erne, {} returnerer alt (standardgrænse 999). fields-projektionen er valgfri, [] returnerer alle felter, og en liste af felt-id'er returnerer kun dem.
Send data ind: felter, ikke parametre
call_native_javascript evaluerer ikke {value, fx}-parameteromslag, name.parameters når
scriptet rå. Den pålidelige kontrakt: komponenten lægger nyttelasten i et felt først (et
update-trin eller et xu-bind-input), workflow'en kalder prog'en med tomme parameters: {}, og
scriptet læser den med xu.get_field_value og rapporterer tilbage med xu.set_field_value. Kalder
du i stedet fra et andet script, sender xu.call_javascript(prog_id, {...}) parametre direkte.
Særheder i live-forhåndsvisningen
- Dataskrivninger når den rigtige database, men
xu.dbs_readlæser et lokalt kladdelager, der måske ikke rummer friske serverrækker, så en læsning lige efter en skrivning kan komme tom tilbage i forhåndsvisningen, selv om skrivningen er landet (synligt i tabellens fane Data i Studio). Udrullede apps læser og skriver i det samme lager. - Kompilerede scripts caches hårdt i udviklingsforhåndsvisninger, en kørende forhåndsvisning kan blive ved med at køre det forrige script, selv efter genindlæsninger, efter et gem kompilerer det igen. En hård browseropdatering rydder det.
xu.alertmed visningenmodal,toastellerbrowserkan dukke op som en indbygget, blokerendealert()i forhåndsvisningen.xu.set_field_valueind i et statusfelt er den sikrere måde at rapportere tilbage på.
javascript-prog eller xu-script-attribut
Teknikker uden anførselstegn til xu-script / xu-style
Designerlærredet serialiserer attributværdier uden escape, så ét enkelt anførselstegn ødelægger
komponentens markup. Skabelonliteraler undgår strengcitationstegn helt
(el.textContent = `Ready`). Selve tegnet ", for eksempel når man bygger CSV, kommer fra
String.fromCharCode(34). CSS-attributselektorer er gyldige uden anførselstegn
(el.querySelector(`[data-role=import-btn]`)). Og en vagt mod gentagen kørsel,
if (el.__bound) return; el.__bound = true;, forhindrer et script i at binde dobbelt ved
gen-rendering.
Fælder
Hver post nedenfor har på et tidspunkt ødelagt et rigtigt build. validate_prog fanger de fleste,
kør den før hvert gem.
API-mekanik
- Hvert svar er
{ code, data },code < 0er en fejl. create_progreturnerer det nye dokument underdata.prog, hvis du gemmer hele svaret i stedet, bliver et fejlbehæftet dokument lagret medpropertiesbegravet underprog.save_progerstatter hele dokumentet. Start fra det nuværende dokument, aldrig et håndsamlet skelet. En-409betyder, at det er ændret, siden det sidst blev læst: hent igen, anvend igen, prøv igen.- Over MCP sendes
prog_jsonogproperties_jsonsom strenge, værktøjsskemalaget fjerner ukendte nøgler fra en objektparameter og kan i stilhed tabe hele sektioner. delete_proger en blød sletning, den sætterstat: 4. Nodenglobal_<app_id>kan ikke slettes.
Dokumentindhold
- Intet
'eller"inde ixu-script- ellerxu-style-værdier. - Nøgler med
$-præfiks ($folded,$childrenClass,$nodeBackClass) samtpath,code,editCodeer designerens visningstilstand og hører aldrig hjemme i en gemtprogUi-node. - Ingen nodetyper som
commentellertext, kun elementer, statisk tekst icontent. - Hver elementnode skal have
attributes: {}ogchildren: [], også når de er tomme. xu-exp:classerstatter den statiskeclass, hver nødvendig klasse hører hjemme inde i udtrykket.xu-binder et rent felt-id, uden@, alle andre steder bruger felter@.- Kun de dokumenterede
xu-*-attributter gør noget, en opfundet ignoreres i stilhed, ogvalidate_progadvarer. - En
ai_agent-progs trærod erai_agents, gem den medstudio_meta.parentId: "ai_agents"(eller et mappe-id under den), hvis checkeren markererparentId.
Runtime og rendering
- Et
tagNamemed stort begyndelsesbogstav tages altid som en komponent, også en tastefejl, og kaster en fejl ved montering, der nævner tagget,libraryog alle kilder, der blev prøvet, der er ingen stille "renderer ikke", sådan som etxu-paneluden valgt program har. validate_progtjekker ikke komponent-tags ellerlibrary-værdier, kun live-forhåndsvisningen fanger en stavefejl.- Ingen utility-CSS (Tailwind eller andet) i runtime, medmindre projektets
uiFramework-plugin faktisk leverer det, klasser somp-4gør ellers ingenting i stilhed. Selvstændig styling erxu-style, automatisk afgrænset af[xu-ui-id]. xu-scriptkøres én gang pr. elements synlighed og kan udløses igen ved gen-rendering, beskyt medel.__boundog afgræns forespørgsler tilel.
Data og scripts
- Parametre til
call_native_javascriptevalueres ikke, send data gennem felter i stedet (se Send data ind, ovenfor). dbs_read-rækker er{id, value}, felter ligger under.value, række-id'et på.id. Send ikke enfields-projektion, den ødelægger læsningen på serveren.- Inde i
xu-forskal iteratoren omsluttes af parenteser,(@_FOR_VAL).CNT_Nameevalueres,@_FOR_VAL.CNT_Namefejler i stilhed og renderer den erstattede kildetekst i stedet. - Skrivninger fra forhåndsvisningen lander i den rigtige database. Læsninger i forhåndsvisningen kommer fra et lokalt kladdelager, som kan se tomt ud lige efter en skrivning.
- Foretræk et statusfelt frem for
xu.alerts modal- eller toast-visning i forhåndsvisninger, den kan blive vist som en indbygget, blokerendealert().
Verificér dit arbejde
Hent igen med get_prog efter gem og sammenlign med det forventede. Til brugerfladearbejde åbner du
komponenten i Studio og trykker på forhåndsvisningens afspilningsknap, eller projektets
live-forhåndsvisnings-URL, når en er tilgængelig. For en javascript-prog tjekker du data.compile.ok
ved hvert gem. Ret hver validate_prog-fejl. Behandl dens advarsler, anførselstegn, $-nøgler,
ukendte attributter, som ting, der skal rettes nu, ikke som støj.