Saltar al contenido
Verificada

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.

json
{
  "_id": "392_cmp_f15654997737",
  "_rev": "3-...",
  "docType": "studio",
  "stat": 3,
  "app_id": "prj...",
  "properties": { "menuType": "component", "menuName": "Orders", "menuTitle": "Orders" },
  "studio_meta": { "created": 1750000000000, "createdByUid": "...", "savedByUid": "...", "parentId": "programs" }
}
  • _id sigue el formato <last 3 chars of app_id>_<3-letter type abbreviation>_<12 hex>, por ejemplo 392_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.
  • stat es 3 para activo, 4 para eliminado de forma lógica (lo que define eliminar un prog). El árbol de Studio solo muestra stat: 3.
  • properties.menuType es uno de globals, table, get_data, set_data, batch, alert, javascript, folder, route, api, component, ai_agent.
  • studio_meta.parentId sitú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. Un parentId no 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_meta y studio_meta.parentId son obligatorios en todos los documentos.
  • Una entrada de progFields necesita un id único, data.field_id, un data.type de virtual, table, expression o datasource, y un props.fieldType de string, number, boolean, array u object.
  • 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 menuType desconocidos y las secciones mal formadas son todos errores graves que validate_prog informa 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.

xu-bind es la única excepción

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.

json
"xu-on:click": [{
  "handler": "custom",
  "props": {},
  "workflow": [
    { "id": "1", "data": { "action": "update", "name": { "value": "@saving_v: true" }, "enabled": true }, "props": {} },
    { "id": "2", "data": { "action": "set_data", "name": { "prog": "392_std_...", "properties": {}, "parameters": {} }, "enabled": true }, "props": { "condition": "@form_valid_v" } }
  ]
}]

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:class reemplaza el atributo class está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-script recibe una expresión function (el) { ... } a secas, pasada por eval y 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 a el, nunca a document.
  • xu-style tiene á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-script ni los de xu-style pueden 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 content de un elemento. xu-exp:xu-content es 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-view delimita un solo registro (una raíz de formulario, utilizable también anidada).
  • xu-multi-view repite sus hijos una vez por cada fila de los datos enlazados.
  • xu-panel incrusta otro prog (atributo program más entradas xu-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-teleport renderiza sus hijos en otro destino del DOM (to o xu-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

json
{
  "menuType": "component", "menuName": "OrderList",
  "renderType": "form",
  "uiFramework": "@xuda.io/xuda-framework-plugin-tailwind",
  "rwMode": "R",
  "progParams": [{ "id": 1, "data": { "dir": "in", "parameter": "order_id_in", "type": "string" }, "props": {} }]
}
  • renderType es form para un solo registro (elemento raíz xu-single-view) o grid / list para uno repetido por cada fila de datos (elemento raíz xu-multi-view).
  • rwMode es R para lectura o U para actualización; allowCreate indica 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.
  • uiFramework refleja 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)

json
{
  "id": "root", "type": "element", "tagName": "xu-single-view", "attributes": {},
  "children": [
    { "id": "ui-...", "type": "element", "tagName": "div",
      "attributes": { "class": "card", "xu-style": ".card { padding: 16px; border-radius: 12px; }" },
      "children": [
        { "id": "ui-...", "type": "element", "tagName": "h2", "content": "Orders", "attributes": {}, "children": [] },
        { "id": "ui-...", "type": "element", "tagName": "input", "children": [],
          "attributes": { "type": "text", "placeholder": "Search", "xu-bind": "search_v" } }
      ] }
  ]
}

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, un tagName en minúsculas más un atributo program, incrusta otro prog, un hijo vinculado a una base de datos o con estado propio, con sus propios campos y eventos. program es el id del hijo (o xu-exp:prog para uno dinámico), y los valores llegan a sus parámetros _in mediante xu-exp:<param>.
  • Una etiqueta con mayúscula inicial más un atributo library monta 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 de xu-panel, nada devuelve un valor a tus campos.
Solo decide la mayúscula inicial

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

json
[
  { "id": "<uuid>", "data": { "type": "virtual", "field_id": "search_v" }, "props": { "fieldType": "string" }, "workflow": [] },
  { "id": "<uuid>", "data": { "type": "table", "field_id": "ORD_Total" }, "props": { "fieldType": "number" }, "workflow": [] }
]

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 con xu-render sobre (@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_action con act_save / act_delete, o un prog set_data dedicado 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

json
"progParams": [
  { "id": 1, "data": { "dir": "in",  "parameter": "order_id_in", "type": "string" }, "props": {} },
  { "id": 2, "data": { "dir": "out", "parameter": "total_out",   "type": "number" }, "props": {} }
]

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).

Acciones obsoletas que el comprobador rechaza

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.

call_ai_agent y call_triage_agent no son acciones reales

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.

json
{
  "properties": { "menuType": "table", "menuName": "ORD - Orders", "databaseSocket": "@xuda.io/xuda-dbs-plugin-xuda" },
  "tableFields": [
    { "id": "<uuid>", "data": { "field_id": "ORD_Id" }, "props": { "fieldType": "string", "mandatory": true } }
  ],
  "tableIndexes": [
    { "id": "<uuid>", "data": { "name": "index_1", "unique": true, "keys": ["ORD_Id"] }, "props": {} }
  ]
}
  • databaseSocket debe nombrar un plugin de base de datos instalado en el proyecto; @xuda.io/xuda-dbs-plugin-xuda es 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_id empieza por una letra, seguida de letras, dígitos, guion bajo, guion, dos puntos o punto, y es único dentro de la tabla.
  • fieldType es string, number, boolean, array, object o date; mandatory: true lo hace obligatorio al guardar.
  • Cada índice necesita un name y unas keys no vacíos, y cada clave debe ser un field_id existente.

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:

js
async function (params, xu, SESSION_ID, SESSION_OBJ, jobNoP, $container, func, glb, APP_OBJ, evt) {
  /* source */
}

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

js
const raw = await xu.get_field_value(`rows_json_v`);
const rows = typeof raw === `string` ? JSON.parse(raw || `[]`) : raw || [];
for (const row of rows) {
  await xu.dbs_create(`392_tbl_...`, { CNT_Name: row.name || ``, CNT_Email: row.email || `` });
}
// dbs_read resolves to an ARRAY of { id, value } rows: the row id on .id, table fields under .value.
const all = await xu.dbs_read(`392_tbl_...`, {}, [], null, 999);
await xu.set_field_value(`status_v`, `Saved ` + rows.length + ` rows`);

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_read lee 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.alert con presentación modal, toast o browser puede aparecer en la vista previa como un alert() nativo bloqueante. xu.set_field_value en 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 }, y code < 0 es un error.
  • create_prog devuelve el documento nuevo bajo data.prog; guardar la respuesta completa en su lugar persiste un documento mal formado con properties enterrado bajo prog.
  • save_prog reemplaza todo el documento. Parte del documento actual, nunca de un esqueleto montado a mano; un -409 significa que cambió desde la última lectura: vuelve a obtenerlo, vuelve a aplicar los cambios y reintenta.
  • Por MCP, prog_json y properties_json se 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_prog es una eliminación lógica, define stat: 4. El nodo global_<app_id> no se puede eliminar.

Contenido del documento

  • Ni ' ni " dentro de los valores de xu-script o xu-style.
  • Las claves con prefijo $ ($folded, $childrenClass, $nodeBackClass), además de path, code y editCode, son estado de vista del diseñador y nunca pertenecen a un nodo de progUi guardado.
  • Ningún tipo de nodo comment ni text, solo elementos, con el texto estático en content.
  • Cada nodo de elemento necesita attributes: {} y children: [] aunque estén vacíos.
  • xu-exp:class reemplaza la class estática; todas las clases necesarias van dentro de la expresión.
  • xu-bind es 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 y validate_prog lo advierte.
  • La raíz del árbol de un prog ai_agent es ai_agents; guárdalo con studio_meta.parentId: "ai_agents" (o el id de una carpeta dentro de ella) si el comprobador marca parentId.

Runtime y renderizado

  • Un tagName con mayúscula inicial siempre se reclama como componente, incluso una errata, y lanza un error al montar que nombra la etiqueta, la library y todas las fuentes probadas; no hay un silencioso "no se renderiza" como el de un xu-panel sin programa seleccionado.
  • validate_prog no comprueba las etiquetas de componente ni los valores de library; 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 uiFramework del proyecto lo proporcione realmente; clases como p-4 no hacen nada en silencio en caso contrario. El estilo autocontenido es xu-style, con ámbito automático por [xu-ui-id].
  • xu-script se ejecuta una vez por visibilidad del elemento y puede volver a dispararse al volver a renderizar; protégete con el.__bound y limita las consultas a el.

Datos y scripts

  • Los parámetros de call_native_javascript no se evalúan; pasa los datos mediante campos (consulta Pasar datos más arriba).
  • Las filas de dbs_read son {id, value}, los campos viven en .value y el id de fila en .id. No pases una proyección de fields: rompe la lectura del lado del servidor.
  • Dentro de xu-for, envuelve el iterador entre paréntesis: (@_FOR_VAL).CNT_Name se evalúa, @_FOR_VAL.CNT_Name falla 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.alert en las vistas previas: puede renderizarse como un alert() 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.