La guida LLM di Studio
Il modello di documento dei prog, il riferimento degli attributi xu-* e le regole dei flussi di lavoro che vengono insegnate a un agente AI prima della sua prima chiamata a uno strumento.
Ogni progetto Studio, e ogni tabella, schermata, script e route al suo interno, è un singolo documento JSON di CouchDB chiamato prog (docType: "studio"). Questa pagina è lo stesso riferimento che riceve un agente AI quando ne costruisce uno, riscritto come documentazione: la forma di quel documento, gli attributi che ne guidano l'UI, le azioni che un flusso di lavoro può compiere e gli errori che compaiono nelle build reali.
Come un agente AI ottiene questa guida
Collega un client MCP a Xuda e la prima risposta, la chiamata initialize, porta questa guida come instructions della sessione, unita ogni volta dalle regole attive della piattaforma stessa, così da non poter mai descrivere qualcosa che il checker distribuito non applica più. Vedi Collegare un client AI tramite MCP.
Dall'interno di una sessione, due metodi raggiungono direttamente lo stesso materiale, tramite MCP o REST semplice, e non richiedono nulla oltre a una normale chiave API:
L'ordine prescritto: leggi l'argomento che corrisponde a ciò che stai costruendo, recupera un esempio corrispondente, crea il prog tramite la factory (create_prog), costruisci dentro le sue sezioni di contenuto, convalida (validate_prog) e correggi tutto ciò che segnala, salva (save_prog), poi recupera di nuovo per verificare. Un salvataggio che restituisce -409 significa che il documento è cambiato da quando è stato letto: recupera di nuovo, riapplica, riprova.
Il modello di documento dei prog
L'envelope
Il codice del server e della factory possiede questi campi; una build creata modifica solo le sezioni di contenuto che stanno sotto di essi.
_idsegue il formato<ultimi 3 caratteri di app_id>_<abbreviazione di 3 lettere del tipo>_<12 esadecimali>, per esempio392_cmp_...per un componente,392_tbl_...per una tabella,392_jvs_...per un prog javascript,392_gtd_.../392_std_...per get_data / set_data,392_fld_...per una cartella. La factory genera gli id, una build non ne inventa mai uno.statè 3 per attivo, 4 per eliminato in modo soft (ciò che imposta l'eliminazione di un prog). L'albero di Studio mostra solostat: 3.properties.menuTypeè uno traglobals,table,get_data,set_data,batch,alert,javascript,folder,route,api,component,ai_agent.studio_meta.parentIdcolloca il nodo nell'albero di Studio: o l'id di un altro prog (di solito una cartella) o una delle radici di tipo,programs(logica e componenti),database(tabelle),routes,globals,ai_agents. UnparentIdnon riconosciuto rende il nodo invisibile nell'albero ed è un errore del checker.
Sezioni di contenuto per menuType
Il documento globals
Ogni progetto ha esattamente un documento global_<app_id> (menuType: "globals"). I suoi progFields sono leggibili da ogni altro prog come @field_id. Due globali di sistema sono presenti in ogni progetto: @SYS_GLOBAL_OBJ_LOGIN_USER_INFO per l'utente connesso e @SYS_GLOBAL_OBJ_REFS per gli elementi registrati con xu-ref. Né il documento globals né la radice dell'albero possono essere eliminati.
Requisiti strutturali
properties,properties.menuType,properties.menuName,studio_metaestudio_meta.parentIdsono obbligatori in ogni documento.- Una voce di
progFieldsrichiede unidunivoco,data.field_id, undata.typetravirtual,table,expressionodatasource, e unprops.fieldTypetrastring,number,boolean,arrayoobject. - I nomi di variabili di runtime riservati,
_NULL,_THIS,_FOR_KEY,_FOR_VAL,_ROWNO,_ROWID,_ROWDOC,_KEY,_VAL, non vanno mai ridefiniti come id di campo. - Id duplicati,
menuTypesconosciuti e sezioni malformate sono tutti errori bloccanti chevalidate_progsegnala direttamente.
Espressioni e attributi xu-*
Sintassi delle espressioni
Le espressioni vengono eseguite sul dataset del prog stesso. Qualsiasi campo, locale, collegato a una tabella, globale o un parametro, viene referenziato con @: @search_v, @ORD_Total, @SYS_GLOBAL_OBJ_LOGIN_USER_INFO, con JavaScript normale intorno, @count_v > 0 ? 'has rows' : 'empty'. Un letterale oggetto richiede parentesi che lo racchiudano, ({ ORD_Status: @status_v }). All'interno di un ciclo xu-for, l'elemento corrente è @_FOR_VAL e la sua chiave o indice @_FOR_KEY (rinominabili con xu-for-key / xu-for-val). xu-render e le altre condizioni restituiscono direttamente il valore vero o falso, mai una stringa "Y" / "N" o un confronto aggiuntivo.
Ovunque altrove un campo viene referenziato con @. xu-bind accetta invece l'id del campo nudo: xu-bind="search_v", mai xu-bind="@search_v".
Gli attributi xu
Famiglie con prefisso
Famiglie di attributi che accettano un suffisso. I valori di xu-on sono sempre array di oggetti gestore; i valori di xu-exp sono sempre stringhe di espressione.
Il valore di un attributo xu-on:* è sempre un array di oggetti gestore, e ogni workflow è un array di passaggi di azione (il riferimento completo delle azioni è più sotto, in Programmi di logica e flussi di lavoro). props.condition di un passaggio lo condiziona; props.async: true lo avvia senza attendere.
Semantica critica
xu-exp:classsostituisce l'attributoclassstatico invece di aggiungersi a esso. Un elemento che li porta entrambi ha quello statico ignorato, quindi anche le classi di layout vanno dentro l'espressione:xu-exp:class="'card p-4 ' + (@active_v ? 'ring' : '')".xu-scriptaccetta un'espressionefunction (el) { ... }nuda, valutata conevale chiamata con l'elemento DOM quando il nodo diventa visibile. Proteggiti dalle riesecuzioni (if (el.__bound) return; el.__bound = true;) e limita ogni query ael, mai adocument.xu-styleha un ambito automatico: ogni selettore viene prefissato con[xu-ui-id]del nodo, quindi i selettori di elementi e classi semplici restano locali e non si diffondono.- Né i valori di
xu-scriptné quelli dixu-stylepossono contenere un carattere di virgolette ('o"): il canvas del designer serializza gli attributi senza escape e una sola virgoletta corrompe il componente. La sezione Programmi JavaScript qui sotto tratta le tecniche senza virgolette. - Il testo statico va nella proprietà
contentdi un elemento.xu-exp:xu-contentserve solo per il testo dinamico.
Tag
Tag di scrittura oltre all'HTML semplice: xu-template, xu-single-view, xu-multi-view, xu-panel, xu-teleport, xu-slot.
xu-single-viewdelimita un singolo record (una radice di modulo, utilizzabile anche annidata).xu-multi-viewripete i suoi figli una volta per ogni riga dei dati collegati.xu-panelincorpora un altro prog (attributoprogrampiù inputxu-exp:<param>). Oltre alle espressioni dei parametri, vi appartengono solo gli attributi HTML standard (class,id,style,title,hidden,slot,name,role,tabindex).xu-teleportrenderizza i suoi figli in un'altra destinazione del DOM (tooxu-exp:to).- Un nome di tag con la maiuscola (
Button,Card) è un componente compilato, non un elemento HTML, vedi Incorporare più sotto.
Componenti
Un componente (menuType: "component") è un'unità di UI: un albero di elementi (progUi) collegato a uno stato locale (progFields), dati facoltativi (progDataSource), logica del ciclo di vita (progEvents) e un'interfaccia di input/output (properties.progParams).
Proprietà
renderTypeèformper un singolo record (elemento radicexu-single-view) oppuregrid/listper uno ripetuto per ogni riga di dati (elemento radicexu-multi-view).rwModeèRper la lettura oUper l'aggiornamento;allowCreateindica se è possibile inserire una nuova riga quando nessuna corrisponde.- Convenzione di denominazione di
progParams: i parametri terminano con_in/_out, i campi virtuali locali del componente terminano con_v. uiFrameworkrispecchia ciò che usano già i componenti esistenti del progetto. Un progetto esistente che lo omette deve continuare a ometterlo: impostare un plugin di framework che il drive del progetto non serve davvero blocca l'anteprima dal vivo su una schermata vuota.
L'albero degli elementi (progUi)
Il nodo root della factory resta; una build lavora dentro i suoi children. Ogni nodo richiede un id univoco (i nuovi nodi usano ui-<uuid>), type: "element" e un tagName, nessun tipo di nodo comment o text, il testo statico sta invece in content. Ogni nodo richiede attributes: {} e children: [] anche quando sono vuoti: il serializzatore del canvas del designer dereferenzia entrambi su ogni nodo e un'omissione rompe l'anteprima stessa del componente.
Incorporare: xu-panel o un componente compilato
Entrambi si montano in modo trasparente, senza elemento wrapper, ed entrambi sono decisi da un solo segnale: se tagName inizia con una lettera maiuscola.
xu-panel, untagNameminuscolo più un attributoprogram, incorpora un altro prog, un figlio collegato a un database o con stato proprio, con i propri campi ed eventi.programè l'id del figlio (oxu-exp:progper uno dinamico), i valori raggiungono i suoi parametri_intramitexu-exp:<param>.- Un tag con la maiuscola più un attributo
librarymonta un componente compilato, una primitiva di un design system o una parte che l'app stessa ha compilato. Ogni attributo semplice diventa una prop (props.<name>), mai un attributo DOM, dato che il componente non renderizza alcun elemento proprio. Un nodo componente non ha parametri out, a differenza dixu-panelnulla riscrive un valore nei tuoi campi.
Un <Buton> con un refuso viene comunque rivendicato come tag di componente, non ripiega mai su un elemento HTML sconosciuto e lancia un errore al montaggio che nomina il tag, la libreria e ogni sorgente provata. validate_prog oggi non controlla i tag dei componenti né i valori di library, l'anteprima dal vivo è l'unico controllo.
progFields
data.type è virtual per lo stato locale, table per una colonna del datasource collegato, oppure expression / datasource. Il workflow di un campo viene eseguito alla modifica. Un valore predefinito imposta props.fieldValue; un campo calcolato imposta props.fieldComputed: true più propExpressions.fieldValue.
progDataSource
Un singolo record per chiave (modulo): dataSourceFilterModelType: "index" con un dataSourceIndexId che esiste tra i tableIndexes della tabella stessa. Un elenco filtrato (grid o list): dataSourceFilterModelType: "query" con filterModelMongoFx, una stringa di espressione in stile Mongo. dataSourceType è table, array, json, csv, none, oppure vuoto per un componente puramente di presentazione senza alcun datasource.
progEvents e i tre hook del ciclo di vita
Tipi di evento: on_load, on_exit, before_record, after_record, record_not_found, locate_not_found, screen_ready, on_refresh, on_unload, client_interval, user_defined. Gli eventi user_defined si attivano da qualsiasi punto con l'azione raise_event; screen_ready è il consueto hook di montaggio.
I tre hook integrati di un componente si dividono il lavoro, usare quello sbagliato è una fonte comune di bug:
screen_ready
Si attiva una volta per istanza. Crea qui DOM e widget.
on_refresh
Si attiva dopo ogni caricamento, compreso il primo, subito dopo screen_ready. Passa i nuovi dati ai widget che esistono già. Mettere invece il lavoro di aggiornamento in screen_ready riesegue il codice di creazione su un DOM che esiste ancora e accumula un secondo widget.
on_unload
Si attiva quando l'istanza viene smantellata. Distruggi ciò che il prog ha creato: widget, timer, listener su document / window, osservatori. Il motore può liberare solo ciò che ha creato: altrimenti un listener collegato a document sopravvive al pannello.
Schemi
- Stati di caricamento e vuoto: metti
xu-ref="myref"sull'elemento collegato ai dati, poi condiziona gli elementi skeleton o vuoti conxu-rendersu(@SYS_GLOBAL_OBJ_REFS).myref, il suo dataset si collega quando arrivano i dati. - Modali: costruisci la finestra di dialogo come componente a sé, aprila con l'azione
call_modal. - Salvare o eliminare una riga collegata:
invoke_actionconact_save/act_delete, oppure un progset_datadedicato per qualsiasi cosa oltre la riga corrente.
Programmi di logica e flussi di lavoro
I tipi di prog di logica condividono i meccanismi dati di un componente (progDataSource, progFields, progEvents, properties.progParams) senza alcuna UI:
Parametri
Un chiamante passa i valori tramite name.parameters dell'azione, { "order_id_in": { "value": "", "fx": "@selected_id_v" } }, value per un valore statico, fx per un'espressione. Il checker verifica che il programma di destinazione esista e che il suo menuType corrisponda all'azione.
Azioni dei flussi di lavoro
Un flusso di lavoro è un array di passaggi, { "id": "...", "data": { "action": "...", "name": { ... }, "enabled": true }, "props": {} }, eseguiti in ordine. props.condition condiziona un passaggio, props.async: true lo avvia senza attendere. I flussi di lavoro compaiono nei gestori xu-on:*, in progEvents[].workflow e nel workflow di un campo.
invoke_action accetta act_next, act_prev, act_first, act_last, act_reload, act_refresh, act_print, act_save, act_delete (solo in contesto di componente).
alter_ui_element, create_ui_element, info_ui_element, remove_ui_element, empty_ui_element, cache_ui_element, load_ui_element. Guida l'UI tramite campi e xu-exp / xu-render invece di un'azione imperativa sugli elementi.
Il selettore di azioni di Studio offre Call AI Agent e Call Triage Agent accanto alle azioni qui sopra. Nessuna delle due è in questa tabella perché nessuna delle due lo è: validate_prog non ha alcun caso per esse e segnala invalid trigger type, e anche il motore dei flussi di lavoro del runtime non ha alcun gestore per esse, quindi un passaggio salvato non viene mai eseguito nemmeno se si ignora l'errore. Per far raggiungere a un prog un agente pubblicato, aggiungi invece uno strumento AI Agent all'elenco di strumenti di un altro agente (l'agentConfig.agent_tools di un documento menuType: "ai_agent"), non un passaggio di flusso di lavoro su un componente, un get_data o qualsiasi altro tipo di prog.
Il name.value di update assegna i campi con coppie @field: expression separate da punto e virgola, oppure con un oggetto JSON5, "@saving_v: true; @status_v: 'sent'". Chiamare un altro programma lo indica sotto name.prog, abbinando l'azione al tipo del programma stesso (get_data richiede un prog get_data, call_native_javascript un prog javascript, e così via).
call_library chiama un metodo di un plugin installato: name.plugin_name deve essere acquistato e installato nell'app altrimenti il checker rifiuta il passaggio, name.library_method uno dei metodi che il plugin esporta, name.library_props i suoi campi dichiarati. Due nomi di prop sono una convenzione tra i plugin più che specifici di uno solo: event_name_for_successful_callback solleva quell'evento con la risposta del metodo, field_id_to_return_result scrive la risposta direttamente in quel campo, nessuno dei due è obbligatorio.
Tipi di 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 è il consueto hook di inizializzazione; before_record / after_record / record_not_found / locate_not_found sono il ciclo di vita dei dati, soprattutto per set_data e batch; client_interval è un timer ripetuto; user_defined si attiva dall'azione raise_event.
Tabelle
Un prog di tipo tabella (menuType: "table") definisce una tabella di database: le sue colonne (tableFields), i suoi indici (tableIndexes) e il plugin di database che la memorizza (properties.databaseSocket). Genitore dell'albero: database, o una cartella al suo interno.
databaseSocketdeve nominare un plugin di database installato nel progetto,@xuda.io/xuda-dbs-plugin-xudaè quello predefinito della piattaforma; una tabella esistente nello stesso progetto è il riferimento per sapere quale socket riutilizzare.- Sono richiesti almeno un campo e almeno un indice.
field_idinizia con una lettera, poi lettere, cifre, trattino basso, trattino, due punti o punto, e resta univoco all'interno della tabella.fieldTypeèstring,number,boolean,array,objectodate;mandatory: truelo rende obbligatorio al salvataggio.- Ogni indice richiede un
nameekeysnon vuoti, e ogni chiave deve essere unfield_idesistente.
Convenzione: prefissa le colonne con un codice tabella di tre lettere, una tabella chiamata "ORD - Orders" ottiene ORD_Id, ORD_Total, ORD_Status. Dai a ogni tabella un campo univoco <TBL>_Id con un indice univoco su di esso, il collegamento di un componente a un singolo record lo richiede.
Una tabella si usa in tre modi: tramite progDataSource.dataSourceTableId di un componente o di una query, tramite un prog get_data / set_data / batch per l'accesso a livello di riga dai flussi di lavoro, oppure tramite xu.dbs_create / dbs_read / dbs_update / dbs_delete da uno script, trattati di seguito.
Programmi JavaScript
Un prog javascript (menuType: "javascript") contiene vero sorgente JS in scriptData.value, compilato al salvataggio. save_prog avvia quella build e restituisce il risultato come data.compile, { ok: true, dependencies } oppure { ok: false, error }. Una compilazione fallita salva comunque il documento, quindi una build legge compile.ok e lo corregge prima di proseguire.
Il contratto di esecuzione
Il sorgente viene scritto come un semplice corpo async, senza export, senza wrapper. A runtime viene eseguito così:
params sono gli input già valutati del chiamante; xu è l'API di runtime qui sotto; un valore restituito è facoltativo, il modo idiomatico di restituire i risultati è xu.set_field_value sui campi del componente chiamante. Qui le virgolette vanno bene, a differenza del valore di un attributo xu-script.
L'API di runtime xu
I metodi dbs_* accettano l'_id del prog tabella stesso, mai un nome. I selettori sono oggetti in stile Mongo sugli id dei campi, {} restituisce tutto (limite predefinito 999). La proiezione fields è facoltativa: [] restituisce tutti i campi e un elenco di id di campo restituisce solo quelli.
Passare i dati: campi, non parametri
call_native_javascript non valuta i wrapper di parametri {value, fx}, name.parameters arriva grezzo allo script. Il contratto affidabile: il componente mette prima il payload in un campo (un passaggio update o un input xu-bind), il flusso di lavoro chiama il prog con parameters: {} vuoto, e lo script lo legge con xu.get_field_value e risponde con xu.set_field_value. Chiamando invece da un altro script, xu.call_javascript(prog_id, {...}) passa direttamente i parametri.
Stranezze dell'anteprima dal vivo
- Le scritture di dati raggiungono il vero database, ma
xu.dbs_readlegge un archivio di bozza locale che può non contenere le righe fresche del server, una lettura subito dopo una scrittura può tornare vuota in anteprima anche se la scrittura è arrivata (visibile nella scheda Dati della tabella in Studio). Le app distribuite leggono e scrivono lo stesso archivio. - Gli script compilati vengono memorizzati in cache in modo aggressivo nelle anteprime di sviluppo, un'anteprima in esecuzione può continuare a eseguire lo script precedente anche dopo i ricaricamenti, quando un salvataggio lo ricompila. Un aggiornamento forzato del browser lo risolve.
xu.alertcon visualizzazionemodal,toastobrowserpuò comparire come unalert()nativo e bloccante in anteprima.xu.set_field_valuein un campo di stato è il modo più sicuro di restituire una risposta.
Prog javascript e attributo xu-script
Tecniche senza virgolette per xu-script / xu-style
Il canvas del designer serializza i valori degli attributi senza escape, quindi una sola virgoletta corrompe il markup del componente. I template literal evitano del tutto le virgolette di stringa (el.textContent = `Ready`); il carattere letterale ", per esempio quando si costruisce un CSV, viene da String.fromCharCode(34); i selettori di attributo CSS sono validi senza virgolette (el.querySelector(`[data-role=import-btn]`)); e una protezione dalle riesecuzioni, if (el.__bound) return; el.__bound = true;, impedisce a uno script di collegarsi due volte a un nuovo rendering.
Trappole
Ogni voce qui sotto ha rotto una build reale a un certo punto. validate_prog ne rileva la maggior parte, eseguilo prima di ogni salvataggio.
Meccaniche dell'API
- Ogni risposta è
{ code, data },code < 0è un errore. create_progrestituisce il nuovo documento sottodata.prog, salvare l'intera risposta invece rende persistente un documento malformato conpropertiessepolto sottoprog.save_progsostituisce l'intero documento. Parti dal documento corrente, mai da uno scheletro assemblato a mano; un-409significa che è cambiato dall'ultima lettura, recupera di nuovo, riapplica, riprova.- Tramite MCP,
prog_jsoneproperties_jsonvengono passati come stringhe, il livello dello schema degli strumenti elimina le chiavi sconosciute da un parametro oggetto e può far sparire in silenzio intere sezioni. delete_progè un'eliminazione soft, impostastat: 4. Il nodoglobal_<app_id>non può essere eliminato.
Contenuto del documento
- Nessun
'o"dentro i valori dixu-scriptoxu-style. - Le chiavi con prefisso
$($folded,$childrenClass,$nodeBackClass), piùpath,code,editCode, sono stato di vista del designer e non appartengono mai a un nodoprogUisalvato. - Nessun tipo di nodo
commentotext, solo elementi, il testo statico incontent. - Ogni nodo elemento richiede
attributes: {}echildren: []anche quando sono vuoti. xu-exp:classsostituisceclassstatico, ogni classe necessaria va dentro l'espressione.xu-bindè un id di campo nudo, senza@, ovunque altrove i campi usano@.- Solo gli attributi
xu-*documentati fanno qualcosa, uno inventato viene ignorato in silenzio evalidate_progavvisa. - La radice dell'albero di un prog
ai_agentèai_agents, salvalo constudio_meta.parentId: "ai_agents"(o l'id di una cartella al suo interno) se il checker segnalaparentId.
Runtime e rendering
- Un
tagNamecon la maiuscola viene sempre rivendicato come componente, anche un refuso, e lancia un errore al montaggio che nomina il tag, lalibrarye ogni sorgente provata, non esiste un silenzioso "non viene renderizzato" come per unxu-panelsenza programma selezionato. validate_prognon controlla i tag dei componenti né i valori dilibrary, solo l'anteprima dal vivo rileva uno scritto male.- Nessun CSS di utilità (Tailwind o altro) a runtime a meno che il plugin
uiFrameworkdel progetto lo fornisca davvero, classi comep-4altrimenti non fanno nulla in silenzio. Lo stile autonomo èxu-style, con ambito automatico tramite[xu-ui-id]. xu-scriptviene eseguito una volta per visibilità dell'elemento e può riattivarsi a un nuovo rendering, proteggiti conel.__bounde limita le query ael.
Dati e script
- I parametri di
call_native_javascriptnon vengono valutati, passa i dati tramite campi (vedi Passare i dati, sopra). - Le righe di
dbs_readsono{id, value}, i campi stanno sotto.value, l'id della riga su.id. Non passare una proiezionefields, rompe la lettura lato server. - Dentro
xu-for, racchiudi l'iteratore tra parentesi,(@_FOR_VAL).CNT_Nameviene valutato,@_FOR_VAL.CNT_Namefallisce in silenzio e renderizza invece il testo sorgente sostituito. - Le scritture in anteprima arrivano nel vero database; le letture in anteprima provengono da un archivio di bozza locale che può sembrare vuoto subito dopo una scrittura.
- In anteprima preferisci un campo di stato alla visualizzazione modale o toast di
xu.alert, può essere renderizzata come unalert()nativo e bloccante.
Verificare il tuo lavoro
Recupera di nuovo con get_prog dopo il salvataggio e confronta con ciò che ti aspettavi. Per il lavoro sull'UI, apri il componente in Studio e premi il pulsante di riproduzione dell'anteprima, oppure l'URL dell'anteprima dal vivo del progetto quando disponibile. Per un prog javascript, controlla data.compile.ok a ogni salvataggio. Correggi ogni errore di validate_prog; tratta i suoi avvisi, virgolette, chiavi $, attributi sconosciuti, come cose da correggere subito e non come rumore.