Le guide LLM de Studio
Le modèle de document de prog, la référence des attributs xu-* et les règles de workflow qu'un agent IA apprend avant son premier appel d'outil.
Chaque projet Studio, et chaque table, écran, script et route qu'il contient, est un document JSON CouchDB appelé prog (docType: "studio"). Cette page est la même référence que reçoit un agent IA quand il en construit un, réécrite sous forme de documentation : la forme de ce document, les attributs qui pilotent son interface, les actions qu'un workflow peut effectuer et les erreurs qui apparaissent dans les vrais builds.
Comment un agent IA obtient ce guide
Connectez un client MCP à Xuda et la première réponse, l'appel initialize, transporte ce guide comme instructions de la session, fusionné à neuf à partir des propres règles actives de la plateforme pour qu'il ne décrive jamais quelque chose que le vérificateur déployé n'applique plus. Voir Connecter un client IA via MCP.
Depuis l'intérieur d'une session, deux méthodes atteignent directement le même matériel, via MCP ou en REST simple, et ne demandent rien de plus qu'une clé API normale :
L'ordre prescrit : lisez la rubrique qui correspond à ce que vous construisez, récupérez un exemple correspondant, créez le prog via la fabrique (create_prog), construisez dans ses sections de contenu, validez (validate_prog) et corrigez tout ce qu'il signale, enregistrez (save_prog), puis récupérez à nouveau pour vérifier. Un enregistrement qui renvoie -409 signifie que le document a changé depuis sa lecture : récupérez à nouveau, réappliquez, réessayez.
Le modèle de document de prog
L'enveloppe
Le code du serveur et de la fabrique possède ces champs ; un build rédigé ne modifie jamais que les sections de contenu qui se trouvent en dessous.
_idsuit<3 derniers caractères de app_id>_<abréviation de type en 3 lettres>_<12 hex>, par exemple392_cmp_...pour un composant,392_tbl_...pour une table,392_jvs_...pour un prog javascript,392_gtd_.../392_std_...pour get_data / set_data,392_fld_...pour un dossier. La fabrique génère les ids, un build n'en invente jamais.statvaut 3 pour actif, 4 pour supprimé de façon logique (ce que fixe la suppression d'un prog). L'arborescence de Studio n'affiche questat: 3.properties.menuTypeest l'un deglobals,table,get_data,set_data,batch,alert,javascript,folder,route,api,component,ai_agent.studio_meta.parentIdplace le nœud dans l'arborescence de Studio : soit l'id d'un autre prog (généralement un dossier), soit l'une des racines de type,programs(logique et composants),database(tables),routes,globals,ai_agents. UnparentIdnon reconnu rend le nœud invisible dans l'arborescence et constitue une erreur du vérificateur.
Sections de contenu par menuType
Le document globals
Chaque projet a exactement un document global_<app_id> (menuType: "globals"). Ses progFields sont lisibles depuis tous les autres progs sous la forme @field_id. Deux globals système sont fournis avec chaque projet : @SYS_GLOBAL_OBJ_LOGIN_USER_INFO pour l'utilisateur connecté, et @SYS_GLOBAL_OBJ_REFS pour les éléments enregistrés avec xu-ref. Ni le document globals ni la racine de l'arborescence ne peuvent être supprimés.
Obligations structurelles
properties,properties.menuType,properties.menuName,studio_metaetstudio_meta.parentIdsont obligatoires sur chaque document.- Une entrée de
progFieldsnécessite unidunique,data.field_id, undata.typevalantvirtual,table,expressionoudatasource, et unprops.fieldTypevalantstring,number,boolean,arrayouobject. - Les noms de variables de runtime réservés,
_NULL,_THIS,_FOR_KEY,_FOR_VAL,_ROWNO,_ROWID,_ROWDOC,_KEY,_VAL, ne sont jamais redéfinis comme ids de champs. - Les ids en double, les
menuTypeinconnus et les sections mal formées sont tous des erreurs bloquantes quevalidate_progsignale directement.
Expressions et attributs xu-*
Syntaxe des expressions
Les expressions s'exécutent sur le jeu de données propre au prog. Tout champ, local, lié à une table, global ou un paramètre, est référencé avec @ : @search_v, @ORD_Total, @SYS_GLOBAL_OBJ_LOGIN_USER_INFO, avec du JavaScript simple autour, @count_v > 0 ? 'has rows' : 'empty'. Un littéral d'objet doit être entouré de parenthèses, ({ ORD_Status: @status_v }). Dans une boucle xu-for, l'élément courant est @_FOR_VAL et sa clé ou son index @_FOR_KEY (renommables avec xu-for-key / xu-for-val). xu-render et les autres conditions renvoient directement la valeur vraie ou fausse, jamais une chaîne "Y" / "N" ni une comparaison supplémentaire.
Partout ailleurs, un champ est référencé avec @. xu-bind prend à la place l'id de champ seul : xu-bind="search_v", jamais xu-bind="@search_v".
Les attributs xu
Familles à préfixe
Des familles d'attributs qui prennent un suffixe. Les valeurs de xu-on sont toujours des tableaux d'objets gestionnaires ; les valeurs de xu-exp sont toujours des chaînes d'expression.
La valeur d'un attribut xu-on:* est toujours un tableau d'objets gestionnaires, et chaque workflow est un tableau d'étapes d'action (la référence complète des actions se trouve plus bas, sous Programmes logiques et workflows). props.condition d'une étape la conditionne ; props.async: true la déclenche sans attendre.
Sémantiques critiques
xu-exp:classremplace l'attributclassstatique au lieu de s'y ajouter. Pour un élément qui porte les deux, le statique est ignoré, donc les classes de mise en page doivent aussi figurer dans l'expression :xu-exp:class="'card p-4 ' + (@active_v ? 'ring' : '')".xu-scriptprend une expressionfunction (el) { ... }seule, passée àevalet appelée avec l'élément DOM une fois le nœud visible. Protégez-vous des ré-exécutions (if (el.__bound) return; el.__bound = true;) et limitez chaque requête àel, jamais àdocument.xu-stylea une portée automatique : chaque sélecteur est préfixé par le[xu-ui-id]du nœud, donc les sélecteurs d'éléments et de classes simples restent locaux et ne fuient jamais.- Ni les valeurs de
xu-scriptni celles dexu-stylene peuvent contenir de guillemet ('ou"), le canevas du concepteur sérialise les attributs sans échappement et un seul guillemet corrompt le composant. La section Programmes JavaScript ci-dessous couvre les techniques sans guillemets. - Le texte statique va dans la propriété
contentd'un élément.xu-exp:xu-contentne sert que pour le texte dynamique.
Balises
Balises d'écriture en dehors du HTML simple : xu-template, xu-single-view, xu-multi-view, xu-panel, xu-teleport, xu-slot.
xu-single-viewdélimite un seul enregistrement (la racine d'un formulaire, utilisable aussi imbriquée).xu-multi-viewrépète ses enfants une fois par ligne des données liées.xu-panelintègre un autre prog (attributprogramplus entréesxu-exp:<param>). Seuls les attributs HTML standard (class,id,style,title,hidden,slot,name,role,tabindex) y ont leur place, en dehors des expressions de paramètres.xu-teleportaffiche ses enfants à une autre cible DOM (toouxu-exp:to).- Un nom de balise en majuscule initiale (
Button,Card) est un composant compilé, pas un élément HTML, voir Intégration ci-dessous.
Composants
Un composant (menuType: "component") est une unité d'interface : une arborescence d'éléments (progUi) liée à un état local (progFields), à des données facultatives (progDataSource), à une logique de cycle de vie (progEvents) et à une interface d'entrée/sortie (properties.progParams).
Propriétés
renderTypevautformpour un seul enregistrement (élément racinexu-single-view) ougrid/listpour un élément répété par ligne de données (élément racinexu-multi-view).rwModevautRpour la lecture ouUpour la mise à jour ;allowCreateindique si une nouvelle ligne peut être insérée quand aucune ne correspond.- Convention de nommage de
progParams: les paramètres se terminent par_in/_out, les champs virtuels locaux au composant par_v. uiFrameworkreprend ce que les composants existants du projet utilisent déjà. Un projet existant qui l'omet doit continuer à l'omettre : définir un plugin de framework que le drive du projet ne sert pas réellement bloque l'aperçu en direct sur un écran vide.
L'arborescence d'éléments (progUi)
Le nœud root de la fabrique reste ; un build travaille dans ses children. Chaque nœud nécessite un id unique (les nouveaux nœuds utilisent ui-<uuid>), type: "element" et un tagName, pas de types de nœuds comment ou text, le texte statique vit plutôt dans content. Chaque nœud nécessite attributes: {} et children: [] même vides, le sérialiseur du canevas du concepteur déréférence les deux sur chaque nœud et une omission casse l'aperçu propre du composant.
Intégration : xu-panel ou un composant compilé
Les deux se montent de façon transparente, sans élément d'enveloppe, et les deux sont décidés par un seul signal : si tagName commence par une majuscule.
xu-panel,tagNameen minuscules plus un attributprogram, intègre un autre prog, un enfant lié à une base de données ou avec état, avec ses propres champs et événements.programest l'id de l'enfant (ouxu-exp:progpour un dynamique), les valeurs atteignent ses paramètres_inviaxu-exp:<param>.- Une balise en majuscule initiale plus un attribut
librarymonte un composant compilé, une primitive de système de design ou une pièce que l'app a elle-même compilée. Chaque attribut simple devient une prop (props.<name>), jamais un attribut DOM, puisque le composant n'affiche aucun élément propre. Un nœud de composant n'a pas de paramètres de sortie, contrairement àxu-panelrien n'écrit de valeur en retour dans vos champs.
Un <Buton> mal orthographié est quand même revendiqué comme balise de composant, ne retombe jamais sur un élément HTML inconnu, et lève une erreur au montage en nommant la balise, la bibliothèque et chaque source essayée. validate_prog ne vérifie pas aujourd'hui les balises de composants ni les valeurs de library, l'aperçu en direct est la seule vérification.
progFields
data.type vaut virtual pour l'état local, table pour une colonne de la source de données liée, ou expression / datasource. Le workflow d'un champ s'exécute à la modification. Une valeur par défaut définit props.fieldValue ; un champ calculé définit props.fieldComputed: true plus propExpressions.fieldValue.
progDataSource
Un seul enregistrement par clé (formulaire) : dataSourceFilterModelType: "index" avec un dataSourceIndexId qui existe dans les tableIndexes propres à la table. Une liste filtrée (grille ou liste) : dataSourceFilterModelType: "query" avec filterModelMongoFx, une chaîne d'expression de style Mongo. dataSourceType vaut table, array, json, csv, none, ou vide pour un composant purement de présentation sans aucune source de données.
progEvents et les trois hooks de cycle de vie
Types d'événements : on_load, on_exit, before_record, after_record, record_not_found, locate_not_found, screen_ready, on_refresh, on_unload, client_interval, user_defined. Les événements user_defined se déclenchent de n'importe où avec l'action raise_event ; screen_ready est le hook de montage habituel.
Les trois hooks intégrés d'un composant se répartissent le travail, utiliser le mauvais est une source courante de bugs :
screen_ready
Se déclenche une fois par instance. Créez-y le DOM et les widgets.
on_refresh
Se déclenche après chaque chargement, y compris le premier, juste après screen_ready. Transmettez les nouvelles données aux widgets qui existent déjà. Mettre le travail de rafraîchissement dans screen_ready relance le code de création sur un DOM qui existe encore et empile un second widget.
on_unload
Se déclenche quand l'instance est démontée. Détruisez ce que le prog a créé, widgets, minuteurs, écouteurs document / window, observateurs. Le moteur ne peut libérer que ce qu'il a créé, un écouteur lié à document survit sinon au panneau.
Modèles
- États de chargement et de vide : mettez
xu-ref="myref"sur l'élément lié aux données, puis conditionnez les éléments de squelette ou de vide avecxu-rendersur(@SYS_GLOBAL_OBJ_REFS).myref, son jeu de données s'attache dès que les données arrivent. - Fenêtres modales : construisez la boîte de dialogue comme son propre composant, ouvrez-la avec l'action
call_modal. - Enregistrer ou supprimer une ligne liée :
invoke_actionavecact_save/act_delete, ou un progset_datadédié pour tout ce qui dépasse la ligne courante.
Programmes logiques et workflows
Les types de prog logiques partagent la mécanique de données d'un composant (progDataSource, progFields, progEvents, properties.progParams) sans aucune interface :
Paramètres
Un appelant passe des valeurs via name.parameters de l'action, { "order_id_in": { "value": "", "fx": "@selected_id_v" } }, value pour une valeur statique, fx pour une expression. Le vérificateur contrôle que le programme cible existe et que son menuType correspond à l'action.
Actions de workflow
Un workflow est un tableau d'étapes, { "id": "...", "data": { "action": "...", "name": { ... }, "enabled": true }, "props": {} }, exécutées dans l'ordre. props.condition conditionne une étape, props.async: true la déclenche sans attendre. Les workflows apparaissent dans les gestionnaires xu-on:*, progEvents[].workflow et le workflow propre à un champ.
invoke_action accepte act_next, act_prev, act_first, act_last, act_reload, act_refresh, act_print, act_save, act_delete (contexte de composant uniquement).
alter_ui_element, create_ui_element, info_ui_element, remove_ui_element, empty_ui_element, cache_ui_element, load_ui_element. Pilotez plutôt l'interface via les champs et xu-exp / xu-render qu'avec une action d'élément impérative.
Le sélecteur d'actions propre à Studio propose Call AI Agent et Call Triage Agent à côté des actions ci-dessus. Aucune n'est dans ce tableau parce qu'aucune n'en est une : validate_prog n'a aucun cas pour elles et signale invalid trigger type, et le moteur de workflow du runtime n'a pas non plus de gestionnaire pour elles, donc une étape enregistrée ne s'exécute jamais même si l'erreur est ignorée. Pour qu'un prog atteigne un agent publié, ajoutez plutôt un outil Agent IA à la liste d'outils d'un autre agent (le agentConfig.agent_tools d'un document menuType: "ai_agent"), pas une étape de workflow sur un composant, un get_data ou tout autre type de prog.
Le name.value de update assigne des champs avec des paires @field: expression séparées par des points-virgules, ou un objet JSON5, "@saving_v: true; @status_v: 'sent'". Appeler un autre programme le nomme sous name.prog, en faisant correspondre l'action au type propre du programme (get_data nécessite un prog get_data, call_native_javascript un prog javascript, et ainsi de suite).
call_library appelle une méthode de plugin installé : name.plugin_name doit être acheté et installé sur l'app, sinon le vérificateur rejette l'étape, name.library_method l'une des méthodes que le plugin exporte, name.library_props ses champs déclarés. Deux noms de props sont une convention commune à plusieurs plugins plutôt que propres à l'un d'eux : event_name_for_successful_callback déclenche cet événement avec la réponse de la méthode, field_id_to_return_result écrit directement la réponse dans ce champ, aucun n'est obligatoire.
Types de 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 est le hook d'initialisation habituel ; before_record / after_record / record_not_found / locate_not_found relèvent du cycle de vie des données, surtout pour set_data et batch ; client_interval est un minuteur répétitif ; user_defined se déclenche depuis l'action raise_event.
Tables
Un prog de table (menuType: "table") définit une table de base de données : ses colonnes (tableFields), ses index (tableIndexes) et le plugin de base de données qui la stocke (properties.databaseSocket). Parent d'arborescence : database, ou un dossier en dessous.
databaseSocketdoit nommer un plugin de base de données installé sur le projet,@xuda.io/xuda-dbs-plugin-xudaest celui par défaut de la plateforme ; une table existante du même projet sert de référence pour le socket à réutiliser.- Au moins un champ et au moins un index sont requis.
field_idcommence par une lettre, puis des lettres, chiffres, tiret bas, tiret, deux-points ou point, et reste unique dans la table.fieldTypevautstring,number,boolean,array,objectoudate;mandatory: truele rend obligatoire à l'enregistrement.- Chaque index nécessite un
nameet deskeysnon vides, et chaque clé doit être unfield_idexistant.
Convention : préfixez les colonnes avec un code de table à trois lettres, une table nommée « ORD - Orders » obtient ORD_Id, ORD_Total, ORD_Status. Donnez à chaque table un champ unique <TBL>_Id avec un index unique dessus, une liaison de composant à enregistrement unique en a besoin.
Une table s'utilise de trois façons : le progDataSource.dataSourceTableId d'un composant ou d'une requête, un prog get_data / set_data / batch pour un accès au niveau des lignes depuis des workflows, ou xu.dbs_create / dbs_read / dbs_update / dbs_delete depuis un script, présenté ensuite.
Programmes JavaScript
Un prog javascript (menuType: "javascript") contient du vrai code source JS dans scriptData.value, compilé à l'enregistrement. save_prog déclenche cette compilation et renvoie le résultat sous data.compile, { ok: true, dependencies } ou { ok: false, error }. Une compilation échouée enregistre quand même le document, donc un build lit compile.ok et corrige avant de continuer.
Le contrat d'exécution
La source est écrite comme un simple corps asynchrone, sans export, sans enveloppe. À l'exécution, elle s'exécute ainsi :
params sont les entrées déjà évaluées de l'appelant ; xu est l'API de runtime ci-dessous ; une valeur de retour est facultative, la façon idiomatique de renvoyer des résultats est xu.set_field_value sur les champs du composant appelant. Les guillemets sont autorisés ici, contrairement à la valeur d'un attribut xu-script.
L'API de runtime xu
Les méthodes dbs_* prennent le propre _id du prog de table, jamais un nom. Les sélecteurs sont des objets de style Mongo sur les ids de champs, {} renvoie tout (limite par défaut 999). La projection fields est facultative, [] renvoie tous les champs et une liste d'ids de champs ne renvoie que ceux-là.
Transmettre des données : des champs, pas des paramètres
call_native_javascript n'évalue pas les enveloppes de paramètres {value, fx}, name.parameters atteint le script tel quel. Le contrat fiable : le composant place d'abord la charge utile dans un champ (une étape update ou une saisie xu-bind), le workflow appelle le prog avec parameters: {} vide, et le script la lit avec xu.get_field_value et rend compte avec xu.set_field_value. En appelant depuis un autre script, xu.call_javascript(prog_id, {...}) passe en revanche directement les paramètres.
Particularités de l'aperçu en direct
- Les écritures de données atteignent la vraie base de données, mais
xu.dbs_readlit un magasin de brouillon local qui peut ne pas contenir les lignes fraîches du serveur, une lecture juste après une écriture peut revenir vide dans l'aperçu même si l'écriture a abouti (visible dans l'onglet Données de la table dans Studio). Les apps déployées lisent et écrivent dans le même magasin. - Les scripts compilés se mettent fortement en cache dans les aperçus de développement, un aperçu en cours peut continuer à exécuter le script précédent même après des rechargements, quand un enregistrement le recompile. Un rafraîchissement forcé du navigateur règle le problème.
xu.alertavec l'affichagemodal,toastoubrowserpeut apparaître comme unalert()natif et bloquant dans l'aperçu.xu.set_field_valuedans un champ d'état est le moyen plus sûr de rendre compte.
prog javascript ou attribut xu-script
Techniques sans guillemets pour xu-script / xu-style
Le canevas du concepteur sérialise les valeurs d'attributs sans échappement, donc un seul guillemet corrompt le balisage du composant. Les littéraux de gabarit évitent entièrement les guillemets de chaîne (el.textContent = `Ready`) ; le caractère littéral ", par exemple pour construire un CSV, vient de String.fromCharCode(34) ; les sélecteurs d'attributs CSS sont valides sans guillemets (el.querySelector(`[data-role=import-btn]`)) ; et une protection contre la ré-exécution, if (el.__bound) return; el.__bound = true;, évite qu'un script se lie deux fois lors d'un nouveau rendu.
Pièges
Chaque entrée ci-dessous a, à un moment, fait échouer un vrai build. validate_prog en détecte la plupart, exécutez-le avant chaque enregistrement.
Mécanique de l'API
- Chaque réponse est
{ code, data },code < 0est une erreur. create_progrenvoie le nouveau document sousdata.prog, enregistrer toute la réponse au lieu de cela persiste un document mal formé avecpropertiesenfoui sousprog.save_progremplace tout le document. Partez du document actuel, jamais d'un squelette assemblé à la main ; un-409signifie qu'il a changé depuis la dernière lecture, récupérez à nouveau, réappliquez, réessayez.- Via MCP,
prog_jsonetproperties_jsonsont passés sous forme de chaînes, la couche de schéma de l'outil retire les clés inconnues d'un paramètre objet et peut supprimer silencieusement des sections entières. delete_progest une suppression logique, elle définitstat: 4. Le nœudglobal_<app_id>ne peut pas être supprimé.
Contenu du document
- Aucun
'ou"dans les valeurs dexu-scriptouxu-style. - Les clés préfixées par
$($folded,$childrenClass,$nodeBackClass), pluspath,code,editCode, sont de l'état de vue du concepteur et n'ont jamais leur place dans un nœudprogUienregistré. - Pas de types de nœuds
commentoutext, uniquement des éléments, le texte statique danscontent. - Chaque nœud élément nécessite
attributes: {}etchildren: []même vides. xu-exp:classremplace leclassstatique, chaque classe nécessaire doit figurer dans l'expression.xu-bindest un id de champ seul, sans@, partout ailleurs les champs utilisent@.- Seuls les attributs
xu-*documentés font quelque chose, un attribut inventé est ignoré silencieusement etvalidate_progavertit. - La racine d'arborescence d'un prog
ai_agentestai_agents, enregistrez-le avecstudio_meta.parentId: "ai_agents"(ou un id de dossier en dessous) si le vérificateur signaleparentId.
Runtime et rendu
- Un
tagNameen majuscule initiale est toujours revendiqué comme composant, même une faute de frappe, et lève une erreur au montage en nommant la balise, lalibraryet chaque source essayée, il n'y a pas de « ne s'affiche pas » silencieux comme pour unxu-panelsans programme sélectionné. validate_progne vérifie pas les balises de composants ni les valeurs delibrary, seul l'aperçu en direct détecte une faute d'orthographe.- Pas de CSS utilitaire (Tailwind ou autre) à l'exécution à moins que le plugin
uiFrameworkdu projet ne le fournisse réellement, des classes commep-4ne font rien silencieusement sinon. Un style autonome passe parxu-style, à portée automatique via[xu-ui-id]. xu-scripts'exécute une fois par visibilité d'élément et peut se redéclencher lors d'un nouveau rendu, protégez-vous avecel.__boundet limitez les requêtes àel.
Données et scripts
- Les paramètres de
call_native_javascriptne sont pas évalués, passez plutôt les données par des champs (voir Transmettre des données, ci-dessus). - Les lignes de
dbs_readsont{id, value}, les champs sont sous.value, l'id de ligne sur.id. Ne passez pas de projectionfields, elle casse la lecture côté serveur. - Dans
xu-for, mettez l'itérateur entre parenthèses,(@_FOR_VAL).CNT_Names'évalue,@_FOR_VAL.CNT_Nameéchoue silencieusement et affiche à la place le texte source substitué. - Les écritures de l'aperçu atterrissent dans la vraie base de données ; les lectures de l'aperçu viennent d'un magasin de brouillon local qui peut sembler vide juste après une écriture.
- Préférez un champ d'état à l'affichage modal ou toast de
xu.alertdans les aperçus, il peut s'afficher comme unalert()natif et bloquant.
Vérifier votre travail
Récupérez à nouveau avec get_prog après l'enregistrement et comparez à ce qui était attendu. Pour le travail d'interface, ouvrez le composant dans Studio et appuyez sur le bouton de lecture de l'aperçu, ou sur l'URL d'aperçu en direct du projet quand il y en a une. Pour un prog javascript, vérifiez data.compile.ok à chaque enregistrement. Corrigez chaque erreur de validate_prog ; traitez ses avertissements, guillemets, clés $, attributs inconnus, comme des éléments à corriger tout de suite plutôt que comme du bruit.