Ghidul LLM pentru Studio
Modelul de documente prog, referința atributelor xu-* și regulile de flux de lucru pe care le învață un agent AI înainte de primul apel de tool.
Fiecare proiect Studio, fiecare tabel, ecran, script și rută din el, este un document JSON CouchDB
numit prog (docType: "studio"). Această pagină este aceeași referință pe care o primește un agent AI când
construiește unul, rescrisă ca documentație: forma acelui document, atributele care îi conduc
UI-ul, acțiunile pe care le poate face un flux de lucru și greșelile care apar în build-urile reale.
Cum primește un agent AI acest ghid
Conectează un client MCP la Xuda, iar primul răspuns, apelul initialize, poartă acest ghid ca
instructions ale sesiunii, îmbinat proaspăt din regulile live ale platformei, ca să nu poată
descrie ceva ce checker-ul publicat nu mai aplică. Vezi
Conectarea unui client AI prin MCP.
Din interiorul unei sesiuni, două metode ajung direct la același material, prin MCP sau REST simplu, și nu cer nimic în plus față de o cheie API obișnuită:
Ordinea prescrisă: citește subiectul care se potrivește cu ce construiești, preia un exemplu potrivit,
creează prog-ul prin factory (create_prog), construiește în secțiunile lui de conținut, validează
(validate_prog) și repară tot ce raportează, salvează (save_prog), apoi preia-l din nou ca să verifici. O
salvare care returnează -409 înseamnă că documentul s-a schimbat de când l-ai citit: preia din nou, reaplică, reîncearcă.
Modelul de documente prog
Plicul
Codul serverului și al factory-ului dețin aceste câmpuri; un build creat de autor editează doar secțiunile de conținut de sub ele.
_idurmează<ultimele 3 caractere din app_id>_<abreviere de tip din 3 litere>_<12 hex>, de exemplu392_cmp_...pentru o componentă,392_tbl_...pentru un tabel,392_jvs_...pentru un prog javascript,392_gtd_.../392_std_...pentru get_data / set_data,392_fld_...pentru un folder. Factory-ul generează id-urile, un build nu inventează niciodată unul.stateste 3 pentru activ, 4 pentru șters soft (ce setează ștergerea unui prog). Arborele Studio arată doarstat: 3.properties.menuTypeeste unul dintreglobals,table,get_data,set_data,batch,alert,javascript,folder,route,api,component,ai_agent.studio_meta.parentIdplasează nodul în arborele Studio: fie id-ul altui prog (de obicei un folder), fie una dintre rădăcinile de tip,programs(logică și componente),database(tabele),routes,globals,ai_agents. UnparentIdnerecunoscut lasă nodul invizibil în arbore și este o eroare de checker.
Secțiuni de conținut după menuType
Documentul globals
Fiecare proiect are exact un document global_<app_id> (menuType: "globals"). progFields-urile lui
se pot citi din orice alt prog ca @field_id. Două globale de sistem vin cu fiecare proiect:
@SYS_GLOBAL_OBJ_LOGIN_USER_INFO pentru utilizatorul conectat și @SYS_GLOBAL_OBJ_REFS pentru elementele
înregistrate cu xu-ref. Nici documentul globals, nici rădăcina arborelui nu pot fi șterse.
Obligații structurale
properties,properties.menuType,properties.menuName,studio_metașistudio_meta.parentIdsunt obligatorii pe fiecare document.- O intrare
progFieldsare nevoie de unidunic,data.field_id, undata.typede tipvirtual,table,expressionsaudatasourceși unprops.fieldTypede tipstring,number,boolean,arraysauobject. - Numele rezervate de variabile de runtime,
_NULL,_THIS,_FOR_KEY,_FOR_VAL,_ROWNO,_ROWID,_ROWDOC,_KEY,_VAL, nu se redefinesc niciodată ca id-uri de câmp. - Id-urile duplicate,
menuType-urile necunoscute și secțiunile malformate sunt toate erori grave pe carevalidate_progle raportează direct.
Expresii și atribute xu-*
Sintaxa expresiilor
Expresiile rulează pe setul de date propriu al prog-ului. Orice câmp, local, legat de tabel, global sau
parametru, este referențiat cu @: @search_v, @ORD_Total, @SYS_GLOBAL_OBJ_LOGIN_USER_INFO,
cu JavaScript simplu în jur, @count_v > 0 ? 'has rows' : 'empty'. Un literal de obiect are nevoie de paranteze
în jur, ({ ORD_Status: @status_v }). În interiorul unei bucle xu-for, elementul curent este @_FOR_VAL, iar
cheia sau indexul lui @_FOR_KEY (redenumibile cu xu-for-key / xu-for-val). xu-render și alte
condiții returnează direct valoarea truthy sau falsy, niciodată un șir "Y" / "N" sau o comparație în plus.
În rest, un câmp este referențiat cu @. xu-bind primește în schimb id-ul simplu al câmpului:
xu-bind="search_v", niciodată xu-bind="@search_v".
Atributele xu
Familii de prefixe
Familii de atribute care primesc un sufix. Valorile xu-on sunt întotdeauna array-uri de obiecte handler;
valorile xu-exp sunt întotdeauna șiruri de expresii.
Valoarea unui atribut xu-on:* este întotdeauna un array de obiecte handler, iar fiecare workflow este
un array de pași de acțiune (referința completă a acțiunilor este mai jos, la Programe de logică și
fluxuri de lucru). props.condition al unui pas îl condiționează; props.async: true îl lansează fără să aștepte.
Semantică critică
xu-exp:classînlocuiește atributul staticclass, în loc să adauge la el. La un element care le are pe ambele, cel static este ignorat, așa că și clasele de layout aparțin în expresie:xu-exp:class="'card p-4 ' + (@active_v ? 'ring' : '')".xu-scriptprimește o expresie simplăfunction (el) { ... }, evaluată cuevalși apelată cu elementul DOM când nodul devine vizibil. Protejează-te împotriva rulărilor repetate (if (el.__bound) return; el.__bound = true;) și limitează fiecare interogare lael, niciodată ladocument.xu-styleare scope automat: fiecare selector este prefixat cu[xu-ui-id]al nodului, așa că selectorii simpli de element și de clasă rămân locali și nu se scurg.- Nici valorile
xu-script, nici celexu-stylenu pot conține un caracter de ghilimele ('sau"), canvas-ul designerului serializează atributele fără escape, iar o singură ghilimea corupe componenta. Secțiunea Programe JavaScript de mai jos tratează tehnici fără ghilimele. - Textul static aparține proprietății
contenta unui element.xu-exp:xu-contenteste doar pentru text dinamic.
Tag-uri
Tag-uri de creare în afară de HTML simplu: xu-template, xu-single-view, xu-multi-view, xu-panel,
xu-teleport, xu-slot.
xu-single-viewdelimitează o singură înregistrare (o rădăcină de formular, utilizabilă și imbricat).xu-multi-viewîși repetă copiii o dată pentru fiecare rând al datelor legate.xu-panelîncorporează alt prog (atributulprogramplus intrărixu-exp:<param>). Pe lângă expresiile de parametri, pe el aparțin doar atributele HTML standard (class,id,style,title,hidden,slot,name,role,tabindex).xu-teleportrandează copiii lui la altă țintă DOM (tosauxu-exp:to).- Un nume de tag cu majusculă (
Button,Card) este o componentă compilată, nu un element HTML, vezi Încorporarea mai jos.
Componente
O componentă (menuType: "component") este o unitate de UI: un arbore de elemente (progUi) legat de starea
locală (progFields), date opționale (progDataSource), logică de ciclu de viață (progEvents) și o
interfață de intrare/ieșire (properties.progParams).
Proprietăți
renderTypeesteformpentru o singură înregistrare (element rădăcinăxu-single-view) saugrid/listpentru una repetată pe fiecare rând de date (element rădăcinăxu-multi-view).rwModeesteRpentru citire sauUpentru actualizare;allowCreatespune dacă se poate insera un rând nou când niciunul nu se potrivește.- Convenția de denumire pentru
progParams: parametrii se termină în_in/_out, câmpurile virtuale locale ale componentei se termină în_v. uiFrameworkreflectă ce folosesc deja componentele existente ale proiectului. Un proiect existent care îl omite trebuie să continue să îl omită; setarea unui plugin de framework pe care drive-ul proiectului nu îl servește de fapt blochează previzualizarea live pe un ecran gol.
Arborele de elemente (progUi)
Nodul root al factory-ului rămâne; un build lucrează în children ale lui. Fiecare nod are nevoie de un id unic
(nodurile noi folosesc ui-<uuid>), type: "element" și un tagName, fără tipuri de nod comment sau text,
textul static trăiește în schimb în content. Fiecare nod are nevoie de attributes: {} și children: []
chiar și când sunt goale, serializatorul canvas-ului designerului dereferențiază ambele pe fiecare nod, iar o omisiune
strică previzualizarea propriei componente.
Încorporarea: xu-panel sau o componentă compilată
Ambele se montează transparent, fără element wrapper, și ambele sunt decise de un singur semnal: dacă
tagName începe cu literă mare.
xu-panel,tagNamecu litere mici plus un atributprogram, încorporează alt prog, un copil legat de bază de date sau cu stare, cu propriile câmpuri și evenimente.programeste id-ul copilului (sauxu-exp:progpentru unul dinamic), valorile ajung la parametrii lui_inprinxu-exp:<param>.- Un tag cu majusculă plus un atribut
librarymontează o componentă compilată, o primitivă de design system sau o piesă pe care aplicația însăși a compilat-o. Fiecare atribut simplu devine un prop (props.<name>), niciodată un atribut DOM, deoarece componenta nu randează niciun element propriu. Un nod de componentă nu are parametri de ieșire, spre deosebire dexu-panel, nimic nu scrie înapoi o valoare în câmpurile tale.
Un <Buton> cu greșeală de scriere este tot revendicat ca tag de componentă, nu revine niciodată la un element HTML
necunoscut și aruncă o eroare la montare, numind tag-ul, biblioteca și fiecare sursă încercată. validate_prog
nu verifică astăzi tag-urile de componentă sau valorile library, previzualizarea live este singura verificare.
progFields
data.type este virtual pentru stare locală, table pentru o coloană a datasource-ului legat sau
expression / datasource. workflow-ul unui câmp rulează la schimbare. O valoare implicită setează
props.fieldValue; un câmp calculat setează props.fieldComputed: true plus
propExpressions.fieldValue.
progDataSource
O singură înregistrare după cheie (formular): dataSourceFilterModelType: "index" cu un dataSourceIndexId
care există în tableIndexes ale tabelului. O listă filtrată (grid sau list):
dataSourceFilterModelType: "query" cu filterModelMongoFx, un șir de expresie în stil Mongo.
dataSourceType este table, array, json, csv, none sau gol pentru o componentă pur prezentațională
fără nicio sursă de date.
progEvents și cele trei hook-uri de ciclu de viață
Tipuri de evenimente: on_load, on_exit, before_record, after_record, record_not_found,
locate_not_found, screen_ready, on_refresh, on_unload, client_interval, user_defined.
Evenimentele user_defined se declanșează de oriunde cu acțiunea
raise_event; screen_ready este hook-ul obișnuit de montare.
Cele trei hook-uri încorporate ale unei componente își împart munca, iar folosirea celui greșit este o sursă frecventă de bug-uri:
screen_ready
Se declanșează o dată pe instanță. Creează aici DOM și widget-uri.
on_refresh
Se declanșează după fiecare încărcare, inclusiv prima, imediat după screen_ready. Dă date noi widget-urilor
care există deja. Dacă pui munca de reîmprospătare în screen_ready, se rulează din nou codul de creare pe DOM
care există încă și se suprapune un al doilea widget.
on_unload
Se declanșează când instanța este demontată. Distruge ce a creat prog-ul, widget-uri, timere,
listeneri pe document / window, observatori. Motorul poate elibera doar ce a creat el, un listener
legat de document supraviețuiește altfel panoului.
Tipare
- Stări de încărcare și goale: pune
xu-ref="myref"pe elementul legat de date, apoi condiționează elementele skeleton sau goale cuxu-renderpeste(@SYS_GLOBAL_OBJ_REFS).myref, setul lui de date se atașează când sosesc datele. - Modale: construiește dialogul ca o componentă separată, deschide-l cu acțiunea
call_modal. - Salvarea sau ștergerea unui rând legat:
invoke_actioncuact_save/act_deletesau un progset_datadedicat pentru orice dincolo de rândul curent.
Programe de logică și fluxuri de lucru
Tipurile de prog de logică împart mecanismul de date al unei componente (progDataSource, progFields,
progEvents, properties.progParams) fără UI:
Parametri
Un apelant transmite valori prin name.parameters al acțiunii,
{ "order_id_in": { "value": "", "fx": "@selected_id_v" } }, value pentru o valoare statică, fx pentru
o expresie. Checker-ul verifică dacă programul țintă există și dacă menuType al lui se potrivește cu
acțiunea.
Acțiuni de flux de lucru
Un flux de lucru este un array de pași, { "id": "...", "data": { "action": "...", "name": { ... }, "enabled": true }, "props": {} }, rulați în ordine. props.condition condiționează un pas, props.async: true îl lansează fără să aștepte. Fluxurile de lucru apar în handler-ele xu-on:*, progEvents[].workflow
și în workflow-ul propriu al unui câmp.
invoke_action acceptă act_next, act_prev, act_first, act_last, act_reload,
act_refresh, act_print, act_save, act_delete (doar în context de componentă).
alter_ui_element, create_ui_element, info_ui_element, remove_ui_element,
empty_ui_element, cache_ui_element, load_ui_element. Conduci UI-ul prin câmpuri și xu-exp /
xu-render, în loc de o acțiune imperativă pe element.
Selectorul de acțiuni propriu al Studio oferă Apelează agent AI și Apelează agentul de triere lângă acțiunile
de mai sus. Niciuna nu este în acest tabel, pentru că niciuna nu este o acțiune: validate_prog nu are un caz pentru ele și
raportează invalid trigger type, iar motorul de fluxuri de lucru din runtime nu are nici el un handler pentru ele, așa că
un pas salvat nu rulează niciodată, chiar dacă eroarea este ignorată. Ca un prog să ajungă la un agent publicat, adaugă
un tool Agent AI în lista de tool-uri a altui agent (agentConfig.agent_tools al unui document menuType: "ai_agent"),
nu un pas de flux de lucru pe o componentă, pe get_data sau pe orice alt tip de prog.
name.value al lui update atribuie câmpuri cu perechi @field: expression separate prin punct și virgulă sau un
obiect JSON5, "@saving_v: true; @status_v: 'sent'". Apelarea altui program îl numește în name.prog,
potrivind acțiunea cu tipul propriu al programului
(get_data are nevoie de un prog get_data, call_native_javascript de un prog javascript și așa mai departe).
call_library apelează o metodă de plugin instalat: name.plugin_name trebuie să fie cumpărat și
instalat pe aplicație, altfel checker-ul respinge pasul, name.library_method una dintre metodele pe care
plugin-ul le exportă, name.library_props câmpurile lui declarate. Două nume de prop sunt o convenție la toate
plugin-urile, nu specifice vreunuia: event_name_for_successful_callback declanșează acel eveniment
cu răspunsul metodei, field_id_to_return_result scrie răspunsul direct în acel câmp, niciunul
nu este obligatoriu.
Tipuri 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 este
hook-ul obișnuit de inițializare; before_record / after_record /
record_not_found / locate_not_found țin de ciclul de viață al datelor, mai ales pentru set_data și batch;
client_interval este un timer repetitiv; user_defined se declanșează din acțiunea raise_event.
Tabele
Un prog de tip tabel (menuType: "table") definește un tabel de bază de date: coloanele lui (tableFields),
indexurile (tableIndexes) și plugin-ul de bază de date care îl stochează (properties.databaseSocket). Părinte
în arbore: database sau un folder de sub el.
databaseSockettrebuie să numească un plugin de bază de date instalat pe proiect,@xuda.io/xuda-dbs-plugin-xudaeste implicitul platformei; un tabel existent din același proiect este referința pentru ce socket să reutilizezi.- Este nevoie de cel puțin un câmp și cel puțin un index.
field_idîncepe cu o literă, apoi litere, cifre, underscore, liniuță, două puncte sau punct, și rămâne unic în tabel.fieldTypeestestring,number,boolean,array,objectsaudate;mandatory: trueîl face obligatoriu la salvare.- Fiecare index are nevoie de un
namenevid și dekeys, iar fiecare cheie trebuie să fie unfield_idexistent.
Convenție: prefixează coloanele cu un cod de tabel din trei litere, un tabel numit „ORD - Orders" primește
ORD_Id, ORD_Total, ORD_Status. Dă fiecărui tabel un câmp unic <TBL>_Id cu un index unic
pe el, o legare a unei componente la o singură înregistrare are nevoie de el.
Un tabel se folosește în trei moduri: progDataSource.dataSourceTableId al unei componente sau interogări, un
prog get_data / set_data / batch pentru acces la nivel de rând din fluxuri de lucru sau xu.dbs_create /
dbs_read / dbs_update / dbs_delete dintr-un script, tratate în continuare.
Programe JavaScript
Un prog javascript (menuType: "javascript") conține cod sursă JS real în scriptData.value, compilat
la salvare. save_prog declanșează acel build și returnează rezultatul ca data.compile, { ok: true, dependencies } sau { ok: false, error }. O compilare eșuată salvează totuși documentul, așa că un build citește
compile.ok și o repară înainte să meargă mai departe.
Contractul de execuție
Sursa se scrie ca un corp async simplu, fără export, fără wrapper. La runtime se execută astfel:
params sunt intrările deja evaluate ale apelantului; xu este API-ul de runtime de mai jos; o valoare returnată
este opțională, modul idiomatic de a trimite rezultate înapoi este xu.set_field_value pe câmpurile
componentei apelante. Ghilimelele sunt în regulă aici, spre deosebire de o valoare de atribut xu-script.
API-ul de runtime xu
Metodele dbs_* primesc _id-ul propriu al prog-ului de tabel, niciodată un nume. Selectorii sunt obiecte în stil Mongo pe
id-urile de câmp, {} returnează tot (limita implicită 999). Proiecția fields este opțională, [] returnează toate câmpurile, iar o listă de id-uri de câmp returnează doar acele câmpuri.
Transmiterea datelor: câmpuri, nu parametri
call_native_javascript nu evaluează wrapper-ele de parametri {value, fx}, name.parameters
ajunge brut la script. Contractul fiabil: componenta pune mai întâi payload-ul într-un câmp (un
pas update sau un input xu-bind), fluxul de lucru apelează prog-ul cu parameters: {} gol, iar
scriptul îl citește cu xu.get_field_value și raportează înapoi cu xu.set_field_value. Dacă apelezi
în schimb dintr-un alt script, xu.call_javascript(prog_id, {...}) transmite parametrii direct.
Particularități ale previzualizării live
- Scrierile de date ajung în baza de date reală, dar
xu.dbs_readcitește un depozit local de ciorne care poate să nu conțină rânduri proaspete de pe server, o citire imediat după o scriere poate reveni goală în previzualizare, deși scrierea a ajuns (vizibilă în fila Data a tabelului din Studio). Aplicațiile publicate citesc și scriu în același depozit. - Scripturile compilate se țin puternic în cache în previzualizările de dev, o previzualizare în rulare poate continua să execute scriptul anterior chiar și după reîncărcări, după ce o salvare îl recompilează. O reîmprospătare forțată a browserului o curăță.
xu.alertcu afișaremodal,toastsaubrowserpoate apărea în previzualizare ca unalert()nativ, blocant.xu.set_field_valueîntr-un câmp de status este modul mai sigur de a raporta înapoi.
prog javascript față de atributul xu-script
Tehnici fără ghilimele pentru xu-script / xu-style
Canvas-ul designerului serializează valorile atributelor fără escape, așa că o singură ghilimea corupe
markup-ul componentei. Template literal-urile evită complet ghilimelele de șir
(el.textContent = `Ready`); caracterul literal ", de exemplu la construirea unui CSV, vine
din String.fromCharCode(34); selectorii de atribut CSS sunt valizi fără ghilimele
(el.querySelector(`[data-role=import-btn]`)); iar o protecție la rulări repetate,
if (el.__bound) return; el.__bound = true;, împiedică un script să se lege de două ori la o re-randare.
Capcane
Fiecare intrare de mai jos a stricat la un moment dat un build real. validate_prog le prinde pe cele mai multe, rulează-l
înainte de fiecare salvare.
Mecanica API
- Fiecare răspuns este
{ code, data },code < 0este o eroare. create_progreturnează documentul nou subdata.prog, salvarea întregului răspuns în loc de asta persistă un document malformat cupropertiesîngropat subprog.save_progînlocuiește întregul document. Pornește de la documentul curent, niciodată de la un schelet asamblat manual; un-409înseamnă că s-a schimbat de la ultima citire, preia din nou, reaplică, reîncearcă.- Prin MCP,
prog_jsonșiproperties_jsonse transmit ca șiruri, stratul de schemă al tool-ului elimină cheile necunoscute dintr-un parametru obiect și poate pierde în tăcere secțiuni întregi. delete_progeste o ștergere soft, seteazăstat: 4. Nodulglobal_<app_id>nu poate fi șters.
Conținutul documentului
- Niciun
'sau"în valorilexu-scriptsauxu-style. - Cheile cu prefix
$($folded,$childrenClass,$nodeBackClass), pluspath,code,editCode, sunt stare de vizualizare a designerului și nu aparțin niciodată unui nodprogUisalvat. - Fără tipuri de nod
commentsautext, doar elemente, text static încontent. - Fiecare nod de element are nevoie de
attributes: {}șichildren: [], chiar și când sunt goale. xu-exp:classînlocuieșteclassstatic, fiecare clasă necesară aparține în expresie.xu-bindeste un id de câmp simplu, fără@, peste tot în rest câmpurile folosesc@.- Doar atributele
xu-*documentate fac ceva, unul inventat este ignorat în tăcere, iarvalidate_progavertizează. - Rădăcina de arbore a unui prog
ai_agentesteai_agents, salvează-l custudio_meta.parentId: "ai_agents"(sau un id de folder de sub ea) dacă checker-ul semnaleazăparentId.
Runtime și randare
- Un
tagNamecu majusculă este întotdeauna revendicat ca o componentă, chiar și o greșeală de scriere, și aruncă o eroare la montare numind tag-ul,libraryși fiecare sursă încercată, nu există un „nu se randează" tăcut, cum are unxu-panelfără program selectat. validate_prognu verifică tag-urile de componentă sau valorilelibrary, doar previzualizarea live prinde una scrisă greșit.- Fără CSS utilitar (Tailwind sau altul) la runtime, dacă plugin-ul
uiFrameworkal proiectului nu îl oferă de fapt, clase precump-4nu fac nimic în tăcere. Stilizarea autonomă estexu-style, cu scope automat prin[xu-ui-id]. xu-scriptrulează o dată la vizibilitatea elementului și se poate declanșa din nou la re-randare, protejează cuel.__boundși limitează interogările lael.
Date și scripturi
- Parametrii
call_native_javascriptnu sunt evaluați, transmite datele prin câmpuri (vezi Transmiterea datelor, mai sus). - Rândurile
dbs_readsunt{id, value}, câmpurile se află sub.value, id-ul rândului pe.id. Nu transmite o proiecțiefields, strică citirea pe server. - În interiorul
xu-for, pune iteratorul între paranteze,(@_FOR_VAL).CNT_Namese evaluează,@_FOR_VAL.CNT_Nameeșuează în tăcere și randează în schimb textul sursă substituit. - Scrierile din previzualizare ajung în baza de date reală; citirile din previzualizare vin dintr-un depozit local de ciorne care poate părea gol imediat după o scriere.
- Preferă un câmp de status în locul afișării modal sau toast a lui
xu.alertîn previzualizări, poate fi randat ca unalert()nativ, blocant.
Verificarea muncii tale
Preia din nou cu get_prog după salvare și compară cu ce te așteptai. Pentru munca de UI, deschide componenta
în Studio și apasă butonul de redare al previzualizării sau URL-ul de previzualizare live al proiectului, când
este disponibil. Pentru un prog javascript, verifică data.compile.ok la fiecare salvare. Repară fiecare
eroare validate_prog; tratează avertismentele lui, ghilimele, chei $, atribute necunoscute, ca lucruri de reparat imediat,
nu ca zgomot.