Studio LLM-guiden
Programdokumentmodellen, xu-*-attributreferensen och de arbetsflödesregler som en AI-agent lär sig före sitt första verktygsanrop.
Varje Studio-projekt, och varje tabell, skärm, skript och rutt i det, är ett CouchDB-JSON-dokument som
kallas ett prog (docType: "studio"). Den här sidan är samma referens som en AI-agent får när
den bygger ett sådant, omskriven som dokumentation: dokumentets form, attributen som styr dess
gränssnitt, åtgärderna som ett arbetsflöde kan utföra och misstagen som dyker upp i verkliga bygg.
Så får en AI-agent den här guiden
Anslut en MCP-klient till Xuda så bär det första svaret, anropet initialize, den här guiden som
sessionens instructions, nysammanslagen från plattformens egna levande regler så att den aldrig kan
beskriva något som den distribuerade kontrollen inte längre tillämpar. Se
Ansluta en AI-klient över MCP.
Inifrån en session når två metoder samma material direkt, över MCP eller vanlig REST, och kräver inget utöver en vanlig API-nyckel:
Den föreskrivna ordningen: läs ämnet som matchar det du bygger, hämta ett matchande exempel, skapa
progen via fabriken (create_prog), bygg inuti dess innehållssektioner, validera (validate_prog) och
åtgärda allt den rapporterar, spara (save_prog) och hämta sedan om för att verifiera. En
sparning som returnerar -409 betyder att dokumentet har ändrats sedan det lästes: hämta om, tillämpa
på nytt, försök igen.
Prog-dokumentmodellen
Höljet
Server- och fabrikskod äger de här fälten; ett författat bygge redigerar bara innehållssektionerna under dem.
_idföljer<last 3 chars of app_id>_<3-letter type abbreviation>_<12 hex>, till exempel392_cmp_...för en komponent,392_tbl_...för en tabell,392_jvs_...för en javascript-prog,392_gtd_.../392_std_...för get_data / set_data,392_fld_...för en mapp. Fabriken genererar id:n, ett bygge hittar aldrig på ett.statär 3 för aktiv, 4 för mjukraderad (det som en radering av en prog sätter). Studios träd visar barastat: 3.properties.menuTypeär en avglobals,table,get_data,set_data,batch,alert,javascript,folder,route,api,component,ai_agent.studio_meta.parentIdplacerar noden i Studios träd: antingen en annan progs id (oftast en mapp) eller en av typrötterna,programs(logik och komponenter),database(tabeller),routes,globals,ai_agents. Ett okäntparentIdgör noden osynlig i trädet och är ett kontrollfel.
Innehållssektioner per menuType
Globals-dokumentet
Varje projekt har exakt ett global_<app_id>-dokument (menuType: "globals"). Dess progFields
kan läsas från varje annan prog som @field_id. Två systemglobaler levereras med varje projekt:
@SYS_GLOBAL_OBJ_LOGIN_USER_INFO för den inloggade användaren och @SYS_GLOBAL_OBJ_REFS för element
som registrerats med xu-ref. Varken globals-dokumentet eller trädroten kan raderas.
Strukturella krav
properties,properties.menuType,properties.menuName,studio_metaochstudio_meta.parentIdär obligatoriska på varje dokument.- En
progFields-post behöver ett uniktid,data.field_id, endata.typesom ärvirtual,table,expressionellerdatasource, och enprops.fieldTypesom ärstring,number,boolean,arrayellerobject. - Reserverade runtime-variabelnamn,
_NULL,_THIS,_FOR_KEY,_FOR_VAL,_ROWNO,_ROWID,_ROWDOC,_KEY,_VAL, omdefinieras aldrig som fält-id:n. - Dubbla id:n, okända
menuType-värden och felformade sektioner är alla hårda fel somvalidate_prograpporterar direkt.
Uttryck och xu-*-attribut
Uttryckssyntax
Uttryck körs mot progens egen datamängd. Varje fält, lokalt, tabellbundet, globalt eller en
parameter, refereras med @: @search_v, @ORD_Total, @SYS_GLOBAL_OBJ_LOGIN_USER_INFO,
med vanlig JavaScript runt, @count_v > 0 ? 'has rows' : 'empty'. En objektliteral behöver omslutande
parenteser, ({ ORD_Status: @status_v }). Inuti en xu-for-loop är det aktuella elementet @_FOR_VAL och
dess nyckel eller index @_FOR_KEY (kan döpas om med xu-for-key / xu-for-val). xu-render och andra
villkor returnerar sanningsvärdet direkt, aldrig en "Y" / "N"-sträng eller en extra
jämförelse.
Överallt annars refereras ett fält med @. xu-bind tar det nakna fält-id:t i stället:
xu-bind="search_v", aldrig xu-bind="@search_v".
xu-attributen
Prefixfamiljer
Attributfamiljer som tar ett suffix. xu-on-värden är alltid arrayer av hanterarobjekt;
xu-exp-värden är alltid uttryckssträngar.
Värdet på ett xu-on:*-attribut är alltid en array av hanterarobjekt, och varje workflow är
en array av åtgärdssteg (hela åtgärdsreferensen finns nedan, under Logikprogram och
arbetsflöden). Ett stegs props.condition styr om det körs; props.async: true startar det utan att vänta.
Kritisk semantik
xu-exp:classersätter det statiskaclass-attributet i stället för att lägga till. Ett element som har båda får det statiska ignorerat, så layoutklasserna hör hemma inuti uttrycket också:xu-exp:class="'card p-4 ' + (@active_v ? 'ring' : '')".xu-scripttar ett naketfunction (el) { ... }-uttryck,eval-kört och anropat med DOM-elementet när noden blir synlig. Skydda mot omkörningar (if (el.__bound) return; el.__bound = true;) och avgränsa varje fråga tillel, aldrig tilldocument.xu-stylehar automatiskt avgränsat omfång: varje selektor får nodens[xu-ui-id]som prefix, så vanliga element- och klassselektorer förblir lokala och läcker aldrig.- Varken
xu-script- ellerxu-style-värden får innehålla ett citattecken ('eller"), designerns canvas serialiserar attribut utan escape och ett enda citattecken förstör komponenten. Avsnittet om JavaScript-program nedan tar upp tekniker utan citattecken. - Statisk text hör hemma i ett elements
content-egenskap.xu-exp:xu-contentär bara till för dynamisk text.
Taggar
Skrivtaggar förutom vanlig HTML: xu-template, xu-single-view, xu-multi-view, xu-panel,
xu-teleport, xu-slot.
xu-single-viewavgränsar en enda post (en formulärrot, kan också användas nästlad).xu-multi-viewupprepar sina barn en gång per rad i den bundna datan.xu-panelbäddar in en annan prog (program-attribut plusxu-exp:<param>-indata). Bara vanliga HTML-attribut (class,id,style,title,hidden,slot,name,role,tabindex) hör hemma på den förutom param-uttrycken.xu-teleportrenderar sina barn vid ett annat DOM-mål (toellerxu-exp:to).- Ett tagnamn med versal (
Button,Card) är en kompilerad komponent, inte ett HTML-element, se Inbäddning nedan.
Komponenter
En komponent (menuType: "component") är en gränssnittsenhet: ett elementträd (progUi) bundet till
lokalt tillstånd (progFields), valfri data (progDataSource), livscykellogik (progEvents) och ett
in-/utdatagränssnitt (properties.progParams).
Egenskaper
renderTypeärformför en enda post (rotelementxu-single-view) ellergrid/listför en som upprepas per datarad (rotelementxu-multi-view).rwModeärRför läsning ellerUför uppdatering;allowCreateanger om en ny rad kan läggas in när ingen matchar.- Namnkonvention för
progParams: parametrar slutar på_in/_out, komponentlokala virtuella fält slutar på_v. uiFrameworkspeglar det som projektets befintliga komponenter redan använder. Ett befintligt projekt som utelämnar det bör fortsätta utelämna det, att sätta ett ramverksplugin som projektets Drive inte faktiskt serverar får liveförhandsgranskningen att fastna på en tom skärm.
Elementträdet (progUi)
Fabrikens root-nod stannar kvar; ett bygge arbetar inuti dess children. Varje nod behöver ett unikt id
(nya noder använder ui-<uuid>), type: "element" och ett tagName, inga nodtyper comment eller text,
statisk text finns i stället i content. Varje nod behöver attributes: {} och children: []
även när de är tomma, designerns canvas-serialiserare avreferar båda på varje nod och en utelämning
förstör komponentens egen förhandsgranskning.
Inbäddning: xu-panel eller en kompilerad komponent
Båda monteras genomskinligt, utan omslagselement, och båda avgörs av en enda signal: om
tagName börjar med en versal.
xu-panel,tagNamemed gemener plus ettprogram-attribut, bäddar in en annan prog, ett databundet eller tillståndsbärande barn med egna fält och händelser.programär barnets id (ellerxu-exp:progför ett dynamiskt), värden når dess_in-parametrar viaxu-exp:<param>.- En tagg med versal plus ett
library-attribut monterar en kompilerad komponent, en designsystemsprimitiv eller en del som appen själv kompilerat. Varje vanligt attribut blir en prop (props.<name>), aldrig ett DOM-attribut, eftersom komponenten inte renderar något eget element. En komponentnod har inga utparametrar, till skillnad frånxu-panelskriver inget tillbaka ett värde till dina fält.
Ett felstavat <Buton> räknas ändå som en komponenttagg, faller aldrig tillbaka på ett okänt HTML-element
och ger ett fel vid montering som nämner taggen, biblioteket och varje källa som provats. validate_prog
kontrollerar inte komponenttaggar eller library-värden i dag, liveförhandsgranskningen är den enda kontrollen.
progFields
data.type är virtual för lokalt tillstånd, table för en kolumn i den bundna datakällan, eller
expression / datasource. Ett fälts workflow körs vid ändring. Ett standardvärde sätter
props.fieldValue; ett beräknat fält sätter props.fieldComputed: true plus
propExpressions.fieldValue.
progDataSource
En enda post via nyckel (formulär): dataSourceFilterModelType: "index" med ett dataSourceIndexId
som finns i tabellens egna tableIndexes. En filtrerad lista (grid eller list):
dataSourceFilterModelType: "query" med filterModelMongoFx, en uttryckssträng i Mongo-stil.
dataSourceType är table, array, json, csv, none, eller tomt för en rent presentationell
komponent helt utan datakälla.
progEvents och de tre livscykelkrokarna
Händelsetyper: 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 utlöses varifrån som helst med åtgärden
raise_event; screen_ready är den vanliga monteringskroken.
En komponents tre inbyggda krokar delar upp arbetet, och att använda fel är en vanlig felkälla:
screen_ready
Utlöses en gång per instans. Skapa DOM och widgets här.
on_refresh
Utlöses efter varje laddning, den första inräknad, direkt efter screen_ready. Ge ny data till widgets
som redan finns. Om du lägger uppdateringsarbetet i screen_ready i stället körs skapandekoden om mot DOM
som fortfarande finns kvar och en andra widget staplas.
on_unload
Utlöses när instansen rivs. Förstör det som progen skapade, widgets, timers,
document- / window-lyssnare, observatörer. Motorn kan bara frigöra det den själv skapade, en lyssnare
bunden till document överlever annars panelen.
Mönster
- Laddnings- och tomma tillstånd: sätt
xu-ref="myref"på det databundna elementet och styr sedan skelett- eller tomma element medxu-renderöver(@SYS_GLOBAL_OBJ_REFS).myref, dess datamängd kopplas på när datan kommer. - Modaler: bygg dialogen som en egen komponent och öppna den med åtgärden
call_modal. - Spara eller radera en bunden rad:
invoke_actionmedact_save/act_delete, eller en dedikeradset_data-prog för allt utöver den aktuella raden.
Logikprogram och arbetsflöden
Logikprogramtyper delar en komponents datamaskineri (progDataSource, progFields,
progEvents, properties.progParams) utan något gränssnitt:
Parametrar
En anropare skickar värden via åtgärdens name.parameters,
{ "order_id_in": { "value": "", "fx": "@selected_id_v" } }, value för ett statiskt värde, fx för
ett uttryck. Kontrollen verifierar att målprogrammet finns och att dess menuType matchar
åtgärden.
Arbetsflödesåtgärder
Ett arbetsflöde är en array av steg, { "id": "...", "data": { "action": "...", "name": { ... }, "enabled": true }, "props": {} }, som körs i ordning. props.condition styr om ett steg körs, props.async: true startar det utan att vänta. Arbetsflöden finns i xu-on:*-hanterare, progEvents[].workflow
och ett fälts eget workflow.
invoke_action accepterar act_next, act_prev, act_first, act_last, act_reload,
act_refresh, act_print, act_save, act_delete (bara i komponentkontext).
alter_ui_element, create_ui_element, info_ui_element, remove_ui_element,
empty_ui_element, cache_ui_element, load_ui_element. Styr gränssnittet via fält och xu-exp /
xu-render i stället för en imperativ elementåtgärd.
Studios egen åtgärdsväljare erbjuder Anropa AI-agent och Anropa triage-agent bredvid åtgärderna
ovan. Ingen av dem finns i tabellen eftersom ingen av dem är en åtgärd: validate_prog har inget fall för dem
och rapporterar invalid trigger type, och runtime:s arbetsflödesmotor har inte heller någon hanterare för dem, så
ett sparat steg körs aldrig även om felet ignoreras. För att låta en prog nå en publicerad agent, lägg i stället till
ett AI-agent-verktyg i en annan agents egen verktygslista (ett menuType: "ai_agent"-dokuments
agentConfig.agent_tools), inte ett arbetsflödessteg på en komponent, get_data eller någon annan programtyp.
updates name.value tilldelar fält med semikolonseparerade @field: expression-par, eller ett
JSON5-objekt, "@saving_v: true; @status_v: 'sent'". Att anropa ett annat program anger det under
name.prog, där åtgärden matchar programmets egen typ
(get_data behöver en get_data-prog, call_native_javascript en javascript-prog och så vidare).
call_library anropar en metod i ett installerat plugin: name.plugin_name måste vara köpt och
installerat på appen annars avvisar kontrollen steget, name.library_method en av metoderna som
pluginet exporterar, name.library_props dess deklarerade fält. Två prop-namn är en konvention över
plugin snarare än specifika för något av dem: event_name_for_successful_callback utlöser den
händelsen med metodens svar, field_id_to_return_result skriver svaret direkt i det fältet, ingen
av dem är obligatorisk.
progEvents-typer
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 är
den vanliga init-kroken; before_record / after_record /
record_not_found / locate_not_found är datalivscykel, särskilt för set_data och batch;
client_interval är en återkommande timer; user_defined utlöses från åtgärden raise_event.
Tabeller
En tabell-prog (menuType: "table") definierar en databastabell: dess kolumner (tableFields), dess
index (tableIndexes) och databaspluginet som lagrar den (properties.databaseSocket). Trädförälder:
database, eller en mapp under den.
databaseSocketmåste ange ett databasplugin som är installerat i projektet,@xuda.io/xuda-dbs-plugin-xudaär plattformens standard; en befintlig tabell i samma projekt är referensen för vilken socket som ska återanvändas.- Minst ett fält och minst ett index krävs.
field_idbörjar med en bokstav, följt av bokstäver, siffror, understreck, bindestreck, kolon eller punkt, och är unikt inom tabellen.fieldTypeärstring,number,boolean,array,objectellerdate;mandatory: truegör det obligatoriskt vid sparning.- Varje index behöver ett icke-tomt
nameochkeys, och varje nyckel måste vara ett befintligtfield_id.
Konvention: sätt en tretecknad tabellkod som prefix på kolumnerna, en tabell som heter "ORD - Orders" får
ORD_Id, ORD_Total, ORD_Status. Ge varje tabell ett unikt <TBL>_Id-fält med ett unikt index
på det, en bindning av en enskild post i en komponent behöver det.
En tabell används på tre sätt: en komponents eller frågans progDataSource.dataSourceTableId, en
get_data / set_data / batch-prog för åtkomst på radnivå från arbetsflöden, eller xu.dbs_create /
dbs_read / dbs_update / dbs_delete från ett skript, vilket tas upp härnäst.
JavaScript-program
En javascript-prog (menuType: "javascript") håller riktig JS-källkod i scriptData.value, kompilerad
vid sparning. save_prog startar bygget och returnerar resultatet som data.compile, { ok: true, dependencies } eller { ok: false, error }. En misslyckad kompilering sparar ändå dokumentet, så ett bygge läser
compile.ok och åtgärdar det innan det går vidare.
Körningskontraktet
Källan skrivs som en vanlig async-kropp, utan export, utan omslag. Vid körning exekveras den som:
params är anroparens redan utvärderade indata; xu är runtime-API:t nedan; ett returvärde är
valfritt, det idiomatiska sättet att lämna tillbaka resultat är xu.set_field_value på den anropande
komponentens fält. Citattecken går bra här, till skillnad från ett xu-script-attributvärde.
Runtime-API:t xu
dbs_*-metoderna tar tabellprogens eget _id, aldrig ett namn. Selektorer är objekt i Mongo-stil på
fält-id:n, {} returnerar allt (standardgräns 999). Projektionen fields är valfri, [] returnerar alla fält och en lista med fält-id:n returnerar bara dem.
Skicka in data: fält, inte parametrar
call_native_javascript utvärderar inte {value, fx}-parameteromslag, name.parameters
når skriptet orörd. Det tillförlitliga kontraktet: komponenten lägger nyttolasten i ett fält först (ett
update-steg eller en xu-bind-indata), arbetsflödet anropar progen med tomma parameters: {} och
skriptet läser den med xu.get_field_value och rapporterar tillbaka med xu.set_field_value. Om man
anropar från ett annat skript i stället skickar xu.call_javascript(prog_id, {...}) parametrar direkt.
Egenheter i liveförhandsgranskningen
- Dataskrivningar når den riktiga databasen, men
xu.dbs_readläser ett lokalt utkastlager som kanske inte innehåller nya serverrader, en läsning direkt efter en skrivning kan komma tillbaka tom i förhandsgranskningen trots att skrivningen gick igenom (synligt på tabellens flik Data i Studio). Distribuerade appar läser och skriver samma lager. - Kompilerade skript cachas hårt i förhandsgranskningar i dev, en körande förhandsgranskning kan fortsätta köra det tidigare skriptet även över omladdningar efter att en sparning kompilerat om det. En hård webbläsaruppdatering rensar det.
xu.alertmed visningenmodal,toastellerbrowserkan dyka upp som ett inbyggt, blockerandealert()i förhandsgranskningen.xu.set_field_valuein i ett statusfält är det säkrare sättet att rapportera tillbaka.
javascript-prog jämfört med xu-script-attribut
Tekniker utan citattecken för xu-script / xu-style
Designerns canvas serialiserar attributvärden utan escape, så ett enda citattecken förstör
komponentens markup. Mallliteraler undviker strängcitattecken helt
(el.textContent = `Ready`); själva tecknet ", till exempel när CSV byggs, kommer
från String.fromCharCode(34); CSS-attributselektorer är giltiga utan citattecken
(el.querySelector(`[data-role=import-btn]`)); och en omkörningsvakt,
if (el.__bound) return; el.__bound = true;, hindrar ett skript från att bindas två gånger vid omrendering.
Fallgropar
Varje post nedan har förstört ett verkligt bygge någon gång. validate_prog fångar de flesta av dem, kör den
före varje sparning.
API-mekanik
- Varje svar är
{ code, data },code < 0är ett fel. create_progreturnerar det nya dokumentet underdata.prog, att spara hela svaret i stället sparar ett felformat dokument medpropertiesbegravt underprog.save_progersätter hela dokumentet. Utgå från det aktuella dokumentet, aldrig ett handbyggt skelett; en-409betyder att det ändrats sedan senaste läsningen, hämta om, tillämpa på nytt, försök igen.- Över MCP skickas
prog_jsonochproperties_jsonsom strängar, verktygsschemalagret tar bort okända nycklar från en objektparameter och kan tyst tappa hela sektioner. delete_progär en mjuk radering, den sätterstat: 4. Nodenglobal_<app_id>kan inte raderas.
Dokumentinnehåll
- Inget
'eller"inutixu-script- ellerxu-style-värden. - Nycklar med
$-prefix ($folded,$childrenClass,$nodeBackClass), pluspath,code,editCode, är designerns vytillstånd och hör aldrig hemma i en sparadprogUi-nod. - Inga nodtyper
commentellertext, bara element, statisk text icontent. - Varje elementnod behöver
attributes: {}ochchildren: []även när de är tomma. xu-exp:classersätter det statiskaclass, varje klass som behövs hör hemma inuti uttrycket.xu-bindär ett naket fält-id, utan@, överallt annars använder fält@.- Bara de dokumenterade
xu-*-attributen gör något, ett påhittat ignoreras tyst ochvalidate_progvarnar. - En
ai_agent-progs trädrot ärai_agents, spara den medstudio_meta.parentId: "ai_agents"(eller ett mapp-id under den) om kontrollen flaggarparentId.
Runtime och rendering
- Ett
tagNamemed versal räknas alltid som en komponent, även ett felstavat, och ger ett fel vid montering som nämner taggen,libraryoch varje källa som provats, det finns ingen tyst "renderas inte" som enxu-panelutan vald prog har. validate_progkontrollerar inte komponenttaggar ellerlibrary-värden, bara liveförhandsgranskningen fångar ett felstavat.- Ingen verktygs-CSS (Tailwind eller annan) vid körning om inte projektets
uiFramework-plugin faktiskt tillhandahåller den, klasser somp-4gör annars tyst ingenting. Fristående formgivning ärxu-style, med automatiskt omfång via[xu-ui-id]. xu-scriptkörs en gång per elementsynlighet och kan utlösas igen vid omrendering, skydda medel.__boundoch avgränsa frågor tillel.
Data och skript
- Parametrar till
call_native_javascriptutvärderas inte, skicka data via fält i stället (se Skicka in data, ovan). dbs_read-rader är{id, value}, fälten finns under.value, rad-id:t på.id. Skicka inte enfields-projektion, den förstör läsningen på serversidan.- Inuti
xu-for, omslut iteratorn med parenteser,(@_FOR_VAL).CNT_Nameutvärderas,@_FOR_VAL.CNT_Namemisslyckas tyst och renderar den ersatta källtexten i stället. - Skrivningar i förhandsgranskningen hamnar i den riktiga databasen; läsningar i förhandsgranskningen kommer från ett lokalt utkastlager som kan se tomt ut direkt efter en skrivning.
- Föredra ett statusfält framför
xu.alerts modal- eller toastvisning i förhandsgranskningar, det kan renderas som ett inbyggt, blockerandealert().
Verifiera ditt arbete
Hämta om med get_prog efter sparning och jämför med det du förväntade dig. För gränssnittsarbete, öppna komponenten
i Studio och tryck på uppspelningsknappen för förhandsgranskning, eller projektets URL för liveförhandsgranskning när en finns
tillgänglig. För en javascript-prog, kontrollera data.compile.ok vid varje sparning. Åtgärda varje
validate_prog-fel; behandla dess varningar, citattecken, $-nycklar, okända attribut, som saker att åtgärda direkt
snarare än brus.