La guía LLM de Studio
El modelo de documentos de prog, la referencia de atributos xu-* y las reglas de flujo de trabajo que se enseñan a un agente de IA antes de su primera llamada a una herramienta.
Cada proyecto de Studio, y cada tabla, pantalla, script y ruta que contiene, es un documento JSON de CouchDB llamado prog (docType: "studio"). Esta página es la misma referencia que recibe un agente de IA cuando construye uno, reescrita como documentación: la forma de ese documento, los atributos que guían su interfaz, las acciones que puede ejecutar un flujo de trabajo y los errores que aparecen en construcciones reales.
Cómo obtiene esta guía un agente de IA
Conecta un cliente MCP a Xuda y la primera respuesta, la llamada initialize, lleva esta guía como las instructions de la sesión, combinada de nuevo a partir de las propias reglas vivas de la plataforma para que nunca pueda describir algo que el comprobador desplegado ya no aplique. Consulta Conectar un cliente de IA mediante MCP.
Desde dentro de una sesión, dos métodos llegan directamente al mismo material, por MCP o por REST simple, y no requieren nada más que una clave de API normal:
El orden prescrito: lee el tema que corresponde a lo que estás construyendo, obtén un ejemplo equivalente, crea el prog mediante la fábrica (create_prog), construye dentro de sus secciones de contenido, valida (validate_prog) y corrige todo lo que informe, guarda (save_prog) y después vuelve a obtenerlo para verificar. Un guardado que devuelve -409 significa que el documento cambió desde que se leyó: vuelve a obtenerlo, vuelve a aplicar los cambios y reintenta.
El modelo de documentos de prog
El envoltorio
El código del servidor y de la fábrica es dueño de estos campos; una construcción creada solo edita las secciones de contenido que hay debajo de ellos.
_idsigue el formato<last 3 chars of app_id>_<3-letter type abbreviation>_<12 hex>, por ejemplo392_cmp_...para un componente,392_tbl_...para una tabla,392_jvs_...para un prog javascript,392_gtd_.../392_std_...para get_data / set_data,392_fld_...para una carpeta. La fábrica genera los ids, una construcción nunca inventa uno.states 3 para activo, 4 para eliminado de forma lógica (lo que define eliminar un prog). El árbol de Studio solo muestrastat: 3.properties.menuTypees uno deglobals,table,get_data,set_data,batch,alert,javascript,folder,route,api,component,ai_agent.studio_meta.parentIdsitúa el nodo en el árbol de Studio: o bien el id de otro prog (normalmente una carpeta) o bien una de las raíces de tipo,programs(lógica y componentes),database(tablas),routes,globals,ai_agents. UnparentIdno reconocido deja el nodo invisible en el árbol y es un error del comprobador.
Secciones de contenido por menuType
El documento globals
Cada proyecto tiene exactamente un documento global_<app_id> (menuType: "globals"). Sus progFields se pueden leer desde cualquier otro prog como @field_id. Dos globales del sistema vienen en todos los proyectos: @SYS_GLOBAL_OBJ_LOGIN_USER_INFO para el usuario con sesión iniciada, y @SYS_GLOBAL_OBJ_REFS para los elementos registrados con xu-ref. Ni el documento globals ni la raíz del árbol se pueden eliminar.
Obligaciones estructurales
properties,properties.menuType,properties.menuName,studio_metaystudio_meta.parentIdson obligatorios en todos los documentos.- Una entrada de
progFieldsnecesita unidúnico,data.field_id, undata.typedevirtual,table,expressionodatasource, y unprops.fieldTypedestring,number,boolean,arrayuobject. - Los nombres de variable de runtime reservados,
_NULL,_THIS,_FOR_KEY,_FOR_VAL,_ROWNO,_ROWID,_ROWDOC,_KEY,_VAL, nunca se redefinen como ids de campo. - Los ids duplicados, los
menuTypedesconocidos y las secciones mal formadas son todos errores graves quevalidate_proginforma directamente.
Expresiones y atributos xu-*
Sintaxis de expresiones
Las expresiones se ejecutan sobre el propio conjunto de datos del prog. Cualquier campo, local, vinculado a tabla, global o un parámetro, se referencia con @: @search_v, @ORD_Total, @SYS_GLOBAL_OBJ_LOGIN_USER_INFO, con JavaScript simple a su alrededor, @count_v > 0 ? 'has rows' : 'empty'. Un literal de objeto necesita paréntesis envolventes, ({ ORD_Status: @status_v }). Dentro de un bucle xu-for, el elemento actual es @_FOR_VAL y su clave o índice @_FOR_KEY (renombrables con xu-for-key / xu-for-val). xu-render y otras condiciones devuelven directamente el valor verdadero o falso, nunca una cadena "Y" / "N" ni una comparación adicional.
En todos los demás sitios un campo se referencia con @. xu-bind recibe en su lugar el id de campo a secas: xu-bind="search_v", nunca xu-bind="@search_v".
Los atributos xu
Familias de prefijos
Familias de atributos que reciben un sufijo. Los valores de xu-on son siempre arrays de objetos manejadores; los valores de xu-exp son siempre cadenas de expresión.
El valor de un atributo xu-on:* es siempre un array de objetos manejadores, y cada workflow es un array de pasos de acción (la referencia completa de acciones está más abajo, en Programas lógicos y flujos de trabajo). El props.condition de un paso lo condiciona; props.async: true lo lanza sin esperar.
Semántica crítica
xu-exp:classreemplaza el atributoclassestático en lugar de añadirse a él. En un elemento que lleva ambos, el estático se ignora, así que las clases de diseño van también dentro de la expresión:xu-exp:class="'card p-4 ' + (@active_v ? 'ring' : '')".xu-scriptrecibe una expresiónfunction (el) { ... }a secas, pasada porevaly llamada con el elemento del DOM una vez que el nodo se hace visible. Protégete contra las reejecuciones (if (el.__bound) return; el.__bound = true;) y limita cada consulta ael, nunca adocument.xu-styletiene ámbito automático: cada selector lleva como prefijo el[xu-ui-id]del nodo, así que los selectores simples de elemento y de clase se mantienen locales y nunca se filtran.- Ni los valores de
xu-scriptni los dexu-stylepueden contener un carácter de comillas ('o"): el lienzo del diseñador serializa los atributos sin escapar y una sola comilla corrompe el componente. La sección de programas JavaScript más abajo trata técnicas sin comillas. - El texto estático va en la propiedad
contentde un elemento.xu-exp:xu-contentes solo para texto dinámico.
Etiquetas
Etiquetas de creación aparte del HTML simple: xu-template, xu-single-view, xu-multi-view, xu-panel, xu-teleport, xu-slot.
xu-single-viewdelimita un solo registro (una raíz de formulario, utilizable también anidada).xu-multi-viewrepite sus hijos una vez por cada fila de los datos enlazados.xu-panelincrusta otro prog (atributoprogrammás entradasxu-exp:<param>). Aparte de las expresiones de parámetros, solo le corresponden atributos HTML estándar (class,id,style,title,hidden,slot,name,role,tabindex).xu-teleportrenderiza sus hijos en otro destino del DOM (tooxu-exp:to).- Un nombre de etiqueta con mayúscula inicial (
Button,Card) es un componente compilado, no un elemento HTML; consulta Incrustar más abajo.
Componentes
Un componente (menuType: "component") es una unidad de UI: un árbol de elementos (progUi) enlazado a un estado local (progFields), datos opcionales (progDataSource), lógica de ciclo de vida (progEvents) y una interfaz de entrada/salida (properties.progParams).
Propiedades
renderTypeesformpara un solo registro (elemento raízxu-single-view) ogrid/listpara uno repetido por cada fila de datos (elemento raízxu-multi-view).rwModeesRpara lectura oUpara actualización;allowCreateindica si se puede insertar una fila nueva cuando ninguna coincide.- Convención de nombres de
progParams: los parámetros terminan en_in/_out, y los campos virtuales locales del componente terminan en_v. uiFrameworkrefleja lo que ya usen los componentes existentes del proyecto. Un proyecto existente que lo omite debe seguir omitiéndolo: definir un plugin de framework que el drive del proyecto no sirve realmente deja la vista previa en vivo atascada en una pantalla en blanco.
El árbol de elementos (progUi)
El nodo root de la fábrica se conserva; una construcción trabaja dentro de sus children. Cada nodo necesita un id único (los nodos nuevos usan ui-<uuid>), type: "element" y un tagName; no hay tipos de nodo comment ni text, el texto estático vive en content. Cada nodo necesita attributes: {} y children: [] aunque estén vacíos: el serializador del lienzo del diseñador desreferencia ambos en cada nodo y una omisión rompe la propia vista previa del componente.
Incrustar: xu-panel o un componente compilado
Ambos se montan de forma transparente, sin elemento envoltorio, y ambos se deciden por una sola señal: si tagName empieza por una letra mayúscula.
xu-panel, untagNameen minúsculas más un atributoprogram, incrusta otro prog, un hijo vinculado a una base de datos o con estado propio, con sus propios campos y eventos.programes el id del hijo (oxu-exp:progpara uno dinámico), y los valores llegan a sus parámetros_inmediantexu-exp:<param>.- Una etiqueta con mayúscula inicial más un atributo
librarymonta un componente compilado, una primitiva de un sistema de diseño o una pieza que la propia app compiló. Cada atributo simple se convierte en una prop (props.<name>), nunca en un atributo del DOM, ya que el componente no renderiza ningún elemento propio. Un nodo de componente no tiene parámetros de salida: a diferencia dexu-panel, nada devuelve un valor a tus campos.
Un <Buton> con errata se sigue reclamando como etiqueta de componente, nunca recurre a un elemento HTML desconocido, y lanza un error al montar que nombra la etiqueta, la biblioteca y todas las fuentes probadas. validate_prog no comprueba hoy las etiquetas de componente ni los valores de library: la vista previa en vivo es la única comprobación.
progFields
data.type es virtual para el estado local, table para una columna del datasource enlazado, o expression / datasource. El workflow de un campo se ejecuta al cambiar. Un valor por defecto define props.fieldValue; un campo calculado define props.fieldComputed: true más propExpressions.fieldValue.
progDataSource
Un solo registro por clave (formulario): dataSourceFilterModelType: "index" con un dataSourceIndexId que exista en los tableIndexes de la propia tabla. Una lista filtrada (grid o list): dataSourceFilterModelType: "query" con filterModelMongoFx, una cadena de expresión de estilo Mongo. dataSourceType es table, array, json, csv, none, o vacío para un componente puramente de presentación sin ningún origen de datos.
progEvents y los tres ganchos de ciclo de vida
Tipos de 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. Los eventos user_defined se disparan desde cualquier sitio con la acción raise_event; screen_ready es el gancho de montaje habitual.
Los tres ganchos integrados de un componente se reparten el trabajo, y usar el equivocado es una fuente habitual de errores:
screen_ready
Se dispara una vez por instancia. Crea aquí el DOM y los widgets.
on_refresh
Se dispara después de cada carga, incluida la primera, justo después de screen_ready. Entrega los datos nuevos a los widgets que ya existen. Poner el trabajo de refresco en screen_ready hace que se vuelva a ejecutar el código de creación sobre un DOM que sigue existiendo y apila un segundo widget.
on_unload
Se dispara cuando se desmonta la instancia. Destruye lo que creó el prog: widgets, temporizadores, oyentes de document / window, observadores. El motor solo puede liberar lo que creó él; de lo contrario, un oyente enlazado a document sobrevive al panel.
Patrones
- Estados de carga y vacío: pon
xu-ref="myref"en el elemento enlazado a datos, y después condiciona los elementos de esqueleto o de vacío conxu-rendersobre(@SYS_GLOBAL_OBJ_REFS).myref; su conjunto de datos se adjunta cuando llegan los datos. - Modales: construye el diálogo como su propio componente y ábrelo con la acción
call_modal. - Guardar o eliminar una fila enlazada:
invoke_actionconact_save/act_delete, o un progset_datadedicado para cualquier cosa que vaya más allá de la fila actual.
Programas lógicos y flujos de trabajo
Los tipos de prog lógicos comparten la maquinaria de datos de un componente (progDataSource, progFields, progEvents, properties.progParams) sin ninguna interfaz:
Parámetros
Quien llama pasa los valores mediante los name.parameters de la acción, { "order_id_in": { "value": "", "fx": "@selected_id_v" } }, value para un valor estático, fx para una expresión. El comprobador verifica que el programa de destino exista y que su menuType coincida con la acción.
Acciones de flujo de trabajo
Un flujo de trabajo es un array de pasos, { "id": "...", "data": { "action": "...", "name": { ... }, "enabled": true }, "props": {} }, que se ejecutan en orden. props.condition condiciona un paso, props.async: true lo lanza sin esperar. Los flujos de trabajo aparecen en los manejadores xu-on:*, en progEvents[].workflow y en el propio workflow de un campo.
invoke_action acepta act_next, act_prev, act_first, act_last, act_reload, act_refresh, act_print, act_save, act_delete (solo en contexto de componente).
alter_ui_element, create_ui_element, info_ui_element, remove_ui_element, empty_ui_element, cache_ui_element, load_ui_element. Guía la interfaz mediante campos y xu-exp / xu-render en lugar de una acción imperativa sobre elementos.
El propio selector de acciones de Studio ofrece Llamar al agente de IA y Llamar al agente de clasificación junto a las acciones anteriores. Ninguna de las dos está en esta tabla porque ninguna lo es: validate_prog no tiene ningún caso para ellas e informa de invalid trigger type, y el motor de flujos de trabajo del runtime tampoco tiene un manejador para ellas, así que un paso guardado nunca se ejecuta aunque se ignore el error. Para que un prog llegue a un agente publicado, añade en su lugar una herramienta de Agente de IA a la lista de herramientas de otro agente (el agentConfig.agent_tools de un documento menuType: "ai_agent"), no un paso de flujo de trabajo en un componente, un get_data ni ningún otro tipo de prog.
El name.value de update asigna campos con pares @field: expression separados por punto y coma, o un objeto JSON5, "@saving_v: true; @status_v: 'sent'". Llamar a otro programa lo nombra en name.prog, haciendo coincidir la acción con el tipo del propio programa (get_data necesita un prog get_data, call_native_javascript un prog javascript, y así sucesivamente).
call_library llama a un método de un plugin instalado: name.plugin_name debe estar comprado e instalado en la app o el comprobador rechaza el paso, name.library_method es uno de los métodos que exporta el plugin y name.library_props sus campos declarados. Dos nombres de prop son una convención entre plugins en lugar de ser específicos de uno solo: event_name_for_successful_callback lanza ese evento con la respuesta del método, field_id_to_return_result escribe la respuesta directamente en ese campo, y ninguno es obligatorio.
Tipos 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 es el gancho de inicio habitual; before_record / after_record / record_not_found / locate_not_found son ciclo de vida de datos, especialmente para set_data y batch; client_interval es un temporizador repetitivo; user_defined se dispara desde la acción raise_event.
Tablas
Un prog de tabla (menuType: "table") define una tabla de base de datos: sus columnas (tableFields), sus índices (tableIndexes) y el plugin de base de datos que la almacena (properties.databaseSocket). Padre del árbol: database, o una carpeta dentro de él.
databaseSocketdebe nombrar un plugin de base de datos instalado en el proyecto;@xuda.io/xuda-dbs-plugin-xudaes el valor por defecto de la plataforma; una tabla existente del mismo proyecto es la referencia de qué socket reutilizar.- Se requiere al menos un campo y al menos un índice.
field_idempieza por una letra, seguida de letras, dígitos, guion bajo, guion, dos puntos o punto, y es único dentro de la tabla.fieldTypeesstring,number,boolean,array,objectodate;mandatory: truelo hace obligatorio al guardar.- Cada índice necesita un
namey unaskeysno vacíos, y cada clave debe ser unfield_idexistente.
Convención: prefija las columnas con un código de tabla de tres letras; una tabla llamada "ORD - Orders" tiene ORD_Id, ORD_Total, ORD_Status. Da a cada tabla un campo <TBL>_Id único con un índice único sobre él: lo necesita el enlace de un componente a un solo registro.
Una tabla se usa de tres formas: el progDataSource.dataSourceTableId de un componente o consulta, un prog get_data / set_data / batch para acceso a nivel de fila desde flujos de trabajo, o xu.dbs_create / dbs_read / dbs_update / dbs_delete desde un script, que se trata a continuación.
Programas JavaScript
Un prog javascript (menuType: "javascript") contiene código JS real en scriptData.value, compilado al guardar. save_prog lanza esa compilación y devuelve el resultado como data.compile, { ok: true, dependencies } o { ok: false, error }. Una compilación fallida guarda igualmente el documento, así que una construcción lee compile.ok y lo corrige antes de continuar.
El contrato de ejecución
El código se escribe como un cuerpo async simple, sin export ni envoltorio. En tiempo de ejecución se ejecuta como:
params son las entradas ya evaluadas de quien llama; xu es la API del runtime de más abajo; un valor de retorno es opcional, y la forma idiomática de devolver resultados es xu.set_field_value sobre los campos del componente que llama. Aquí las comillas están permitidas, a diferencia del valor de un atributo xu-script.
La API de runtime xu
Los métodos dbs_* reciben el propio _id del prog de tabla, nunca un nombre. Los selectores son objetos de estilo Mongo sobre los ids de campo, {} devuelve todo (límite por defecto 999). La proyección de fields es opcional: [] devuelve todos los campos y una lista de ids de campo devuelve solo esos.
Pasar datos: campos, no parámetros
call_native_javascript no evalúa los envoltorios de parámetros {value, fx}: name.parameters llega sin procesar al script. El contrato fiable: el componente pone primero la carga en un campo (un paso update o un input con xu-bind), el flujo de trabajo llama al prog con parameters: {} vacío, y el script lo lee con xu.get_field_value e informa con xu.set_field_value. Si se llama desde otro script, xu.call_javascript(prog_id, {...}) sí pasa los parámetros directamente.
Particularidades de la vista previa en vivo
- Las escrituras de datos llegan a la base de datos real, pero
xu.dbs_readlee un almacén de borrador local que puede no contener las filas recientes del servidor; una lectura justo después de una escritura puede salir vacía en la vista previa aunque la escritura haya llegado (visible en la pestaña Datos de la tabla en Studio). Las apps desplegadas leen y escriben en el mismo almacén. - Los scripts compilados se almacenan en caché con fuerza en las vistas previas de desarrollo: una vista previa en ejecución puede seguir ejecutando el script anterior incluso tras recargar después de que un guardado lo recompile. Una actualización forzada del navegador lo limpia.
xu.alertcon presentaciónmodal,toastobrowserpuede aparecer en la vista previa como unalert()nativo bloqueante.xu.set_field_valueen un campo de estado es la forma más segura de informar.
Prog javascript frente al atributo xu-script
Técnicas sin comillas para xu-script / xu-style
El lienzo del diseñador serializa los valores de atributo sin escapar, así que una sola comilla corrompe el marcado del componente. Los literales de plantilla evitan por completo las comillas de cadena (el.textContent = `Ready`); el carácter literal ", por ejemplo al construir CSV, sale de String.fromCharCode(34); los selectores de atributo de CSS son válidos sin comillas (el.querySelector(`[data-role=import-btn]`)); y una protección contra reejecución, if (el.__bound) return; el.__bound = true;, evita que un script se enlace dos veces al volver a renderizar.
Trampas
Cada entrada siguiente rompió una construcción real en algún momento. validate_prog detecta la mayoría; ejecútalo antes de cada guardado.
Mecánica de la API
- Toda respuesta es
{ code, data }, ycode < 0es un error. create_progdevuelve el documento nuevo bajodata.prog; guardar la respuesta completa en su lugar persiste un documento mal formado conpropertiesenterrado bajoprog.save_progreemplaza todo el documento. Parte del documento actual, nunca de un esqueleto montado a mano; un-409significa que cambió desde la última lectura: vuelve a obtenerlo, vuelve a aplicar los cambios y reintenta.- Por MCP,
prog_jsonyproperties_jsonse pasan como cadenas: la capa de esquema de la herramienta elimina las claves desconocidas de un parámetro de objeto y puede descartar secciones enteras en silencio. delete_proges una eliminación lógica, definestat: 4. El nodoglobal_<app_id>no se puede eliminar.
Contenido del documento
- Ni
'ni"dentro de los valores dexu-scriptoxu-style. - Las claves con prefijo
$($folded,$childrenClass,$nodeBackClass), además depath,codeyeditCode, son estado de vista del diseñador y nunca pertenecen a un nodo deprogUiguardado. - Ningún tipo de nodo
commentnitext, solo elementos, con el texto estático encontent. - Cada nodo de elemento necesita
attributes: {}ychildren: []aunque estén vacíos. xu-exp:classreemplaza laclassestática; todas las clases necesarias van dentro de la expresión.xu-bindes un id de campo a secas, sin@; en todos los demás sitios los campos usan@.- Solo hacen algo los atributos
xu-*documentados; uno inventado se ignora en silencio yvalidate_proglo advierte. - La raíz del árbol de un prog
ai_agentesai_agents; guárdalo constudio_meta.parentId: "ai_agents"(o el id de una carpeta dentro de ella) si el comprobador marcaparentId.
Runtime y renderizado
- Un
tagNamecon mayúscula inicial siempre se reclama como componente, incluso una errata, y lanza un error al montar que nombra la etiqueta, lalibraryy todas las fuentes probadas; no hay un silencioso "no se renderiza" como el de unxu-panelsin programa seleccionado. validate_progno comprueba las etiquetas de componente ni los valores delibrary; solo la vista previa en vivo detecta uno mal escrito.- No hay CSS de utilidades (Tailwind u otro) en tiempo de ejecución a menos que el plugin
uiFrameworkdel proyecto lo proporcione realmente; clases comop-4no hacen nada en silencio en caso contrario. El estilo autocontenido esxu-style, con ámbito automático por[xu-ui-id]. xu-scriptse ejecuta una vez por visibilidad del elemento y puede volver a dispararse al volver a renderizar; protégete conel.__boundy limita las consultas ael.
Datos y scripts
- Los parámetros de
call_native_javascriptno se evalúan; pasa los datos mediante campos (consulta Pasar datos más arriba). - Las filas de
dbs_readson{id, value}, los campos viven en.valuey el id de fila en.id. No pases una proyección defields: rompe la lectura del lado del servidor. - Dentro de
xu-for, envuelve el iterador entre paréntesis:(@_FOR_VAL).CNT_Namese evalúa,@_FOR_VAL.CNT_Namefalla en silencio y renderiza en su lugar el texto fuente sustituido. - Las escrituras de la vista previa llegan a la base de datos real; las lecturas de la vista previa vienen de un almacén de borrador local que puede parecer vacío justo después de una escritura.
- Prefiere un campo de estado a la presentación modal o toast de
xu.alerten las vistas previas: puede renderizarse como unalert()nativo bloqueante.
Verificar tu trabajo
Vuelve a obtener con get_prog después de guardar y compara lo que esperabas. Para trabajo de UI, abre el componente en Studio y pulsa el botón de reproducir de la vista previa, o la URL de vista previa en vivo del proyecto cuando haya una disponible. Para un prog javascript, comprueba data.compile.ok en cada guardado. Corrige todos los errores de validate_prog; trata sus advertencias, comillas, claves $, atributos desconocidos, como cosas que corregir ahora y no como ruido.