O guia LLM do Studio
O modelo de documentos de prog, a referência de atributos xu-* e as regras de fluxo de trabalho que um agente de IA aprende antes da sua primeira chamada a uma ferramenta.
Cada projeto do Studio, e cada tabela, ecrã, script e rota dentro dele, é um documento JSON do CouchDB
chamado prog (docType: "studio"). Esta página é a mesma referência que um agente de IA recebe quando
constrói um, reescrita como documentação: a forma desse documento, os atributos que comandam
a sua interface, as ações que um fluxo de trabalho pode executar e os erros que surgem em construções reais.
Como um agente de IA obtém este guia
Ligue um cliente MCP ao Xuda e a primeira resposta, a chamada initialize, traz este guia como
instructions da sessão, fundido de novo a partir das regras ativas da própria plataforma, para que nunca possa
descrever algo que o verificador implementado já não aplique. Veja
Ligar um cliente de IA por MCP.
A partir de dentro de uma sessão, dois métodos chegam diretamente ao mesmo material, por MCP ou por REST simples, e não exigem nada além de uma chave de API normal:
A ordem prescrita: leia o tópico que corresponde ao que está a construir, obtenha um exemplo correspondente,
crie o prog através da fábrica (create_prog), construa dentro das suas secções de conteúdo, valide
(validate_prog) e corrija tudo o que for reportado, guarde (save_prog) e volte a obter para verificar. Um
guardar que devolva -409 significa que o documento mudou desde que foi lido: obtenha de novo, reaplique, tente outra vez.
O modelo de documentos de prog
O envelope
O código do servidor e da fábrica é dono destes campos; uma construção escrita só edita as secções de conteúdo abaixo deles.
_idsegue<last 3 chars of app_id>_<3-letter type abbreviation>_<12 hex>, por exemplo392_cmp_...para um componente,392_tbl_...para uma tabela,392_jvs_...para um prog javascript,392_gtd_.../392_std_...para get_data / set_data,392_fld_...para uma pasta. A fábrica gera os ids, uma construção nunca inventa um.staté 3 para ativo, 4 para eliminado de forma suave (o que eliminar um prog define). A árvore do Studio só mostrastat: 3.properties.menuTypeé um deglobals,table,get_data,set_data,batch,alert,javascript,folder,route,api,component,ai_agent.studio_meta.parentIdcoloca o nó na árvore do Studio: ou o id de outro prog (normalmente uma pasta) ou uma das raízes de tipo,programs(lógica e componentes),database(tabelas),routes,globals,ai_agents. UmparentIdnão reconhecido deixa o nó invisível na árvore e é um erro do verificador.
Secções de conteúdo por menuType
O documento globals
Cada projeto tem exatamente um documento global_<app_id> (menuType: "globals"). Os seus progFields
são legíveis a partir de qualquer outro prog como @field_id. Dois globais de sistema vêm em todos os projetos:
@SYS_GLOBAL_OBJ_LOGIN_USER_INFO para o utilizador com sessão iniciada e @SYS_GLOBAL_OBJ_REFS para os elementos
registados com xu-ref. Nem o documento globals nem a raiz da árvore podem ser eliminados.
Obrigações estruturais
properties,properties.menuType,properties.menuName,studio_metaestudio_meta.parentIdsão obrigatórios em todos os documentos.- Uma entrada de
progFieldsprecisa de umidúnico,data.field_id, umdata.typedevirtual,table,expressionoudatasource, e umprops.fieldTypedestring,number,boolean,arrayouobject. - Os nomes de variáveis de runtime reservados,
_NULL,_THIS,_FOR_KEY,_FOR_VAL,_ROWNO,_ROWID,_ROWDOC,_KEY,_VAL, nunca são redefinidos como ids de campo. - Ids duplicados,
menuTypedesconhecidos e secções mal formadas são todos erros graves que ovalidate_progreporta diretamente.
Expressões e atributos xu-*
Sintaxe das expressões
As expressões executam-se sobre o conjunto de dados do próprio prog. Qualquer campo, local, ligado a uma tabela, global ou
um parâmetro, é referenciado com @: @search_v, @ORD_Total, @SYS_GLOBAL_OBJ_LOGIN_USER_INFO,
com JavaScript simples à volta, @count_v > 0 ? 'has rows' : 'empty'. Um literal de objeto precisa de parênteses
à volta, ({ ORD_Status: @status_v }). Dentro de um ciclo xu-for, o item atual é @_FOR_VAL e
a sua chave ou índice @_FOR_KEY (renomeáveis com xu-for-key / xu-for-val). xu-render e outras
condições devolvem diretamente o valor verdadeiro ou falso, nunca uma string "Y" / "N" nem uma comparação
adicional.
Em todos os outros sítios um campo é referenciado com @. O xu-bind recebe o id do campo simples:
xu-bind="search_v", nunca xu-bind="@search_v".
Os atributos xu
Famílias de prefixos
Famílias de atributos que recebem um sufixo. Os valores de xu-on são sempre arrays de objetos de tratamento;
os valores de xu-exp são sempre strings de expressão.
O valor de um atributo xu-on:* é sempre um array de objetos de tratamento, e cada workflow é
um array de passos de ação (a referência completa das ações está abaixo, em Programas de lógica e
fluxos de trabalho). O props.condition de um passo condiciona-o; props.async: true dispara-o sem esperar.
Semântica crítica
xu-exp:classsubstitui o atributoclassestático em vez de lhe acrescentar. Num elemento que tenha ambos, o estático é ignorado, por isso as classes de layout pertencem também dentro da expressão:xu-exp:class="'card p-4 ' + (@active_v ? 'ring' : '')".xu-scriptrecebe uma expressãofunction (el) { ... }simples, avaliada comevale chamada com o elemento do DOM quando o nó se torna visível. Proteja-se contra novas execuções (if (el.__bound) return; el.__bound = true;) e limite todas as consultas ael, nunca adocument.xu-styletem âmbito automático: cada seletor recebe como prefixo o[xu-ui-id]do nó, por isso os seletores simples de elementos e classes ficam locais e nunca vazam.- Nem os valores de
xu-scriptnem os dexu-stylepodem conter um carácter de aspas ('ou"): o canvas do designer serializa os atributos sem escape e uma só aspa corrompe o componente. A secção Programas JavaScript abaixo trata de técnicas sem aspas. - O texto estático pertence à propriedade
contentde um elemento.xu-exp:xu-contentserve apenas para texto dinâmico.
Tags
Tags de escrita para além do HTML simples: xu-template, xu-single-view, xu-multi-view, xu-panel,
xu-teleport, xu-slot.
xu-single-viewdelimita um único registo (uma raiz de formulário, utilizável também aninhada).xu-multi-viewrepete os seus filhos uma vez por linha dos dados ligados.xu-panelincorpora outro prog (atributoprogrammais entradasxu-exp:<param>). Para além das expressões de parâmetros, só pertencem a ele atributos HTML padrão (class,id,style,title,hidden,slot,name,role,tabindex).xu-teleportrenderiza os seus filhos noutro destino do DOM (toouxu-exp:to).- Um nome de tag com maiúscula inicial (
Button,Card) é um componente compilado, não um elemento HTML, veja Incorporar abaixo.
Componentes
Um componente (menuType: "component") é uma unidade de interface: uma árvore de elementos (progUi) ligada ao
estado local (progFields), a dados opcionais (progDataSource), a lógica de ciclo de vida (progEvents) e a uma
interface de entrada/saída (properties.progParams).
Propriedades
renderTypeéformpara um único registo (elemento raizxu-single-view) ougrid/listpara um repetido por cada linha de dados (elemento raizxu-multi-view).rwModeéRpara leitura ouUpara atualização;allowCreateindica se pode ser inserida uma nova linha quando nenhuma corresponde.- Convenção de nomes de
progParams: os parâmetros terminam em_in/_out, os campos virtuais locais do componente terminam em_v. uiFrameworkreflete o que os componentes já existentes do projeto usam. Um projeto existente que o omita deve continuar a omiti-lo: definir um plugin de framework que o drive do projeto não serve de facto deixa a pré-visualização em direto parada num ecrã em branco.
A árvore de elementos (progUi)
O nó root da fábrica mantém-se; uma construção trabalha dentro dos seus children. Cada nó precisa de um id único
(os novos nós usam ui-<uuid>), type: "element" e um tagName, sem tipos de nó comment nem text,
o texto estático vive em content. Cada nó precisa de attributes: {} e children: []
mesmo quando vazios: o serializador do canvas do designer desreferencia ambos em cada nó e uma omissão
estraga a pré-visualização do próprio componente.
Incorporar: xu-panel ou um componente compilado
Ambos se montam de forma transparente, sem elemento invólucro, e ambos são decididos por um só sinal: se
tagName começa por uma letra maiúscula.
xu-panel,tagNameem minúsculas mais um atributoprogram, incorpora outro prog, um filho ligado a uma base de dados ou com estado, com os seus próprios campos e eventos.programé o id do filho (ouxu-exp:progpara um dinâmico), os valores chegam aos seus parâmetros_inatravés dexu-exp:<param>.- Uma tag com maiúscula inicial mais um atributo
librarymonta um componente compilado, uma primitiva de design system ou uma peça que a própria aplicação compilou. Cada atributo simples torna-se uma prop (props.<name>), nunca um atributo do DOM, uma vez que o componente não renderiza nenhum elemento próprio. Um nó de componente não tem parâmetros de saída: ao contrário doxu-panel, nada escreve um valor de volta nos seus campos.
Um <Buton> com erro de digitação continua a ser reclamado como tag de componente, nunca recorre a um
elemento HTML desconhecido e lança um erro ao montar, indicando a tag, a biblioteca e todas as origens tentadas. O validate_prog
não verifica tags de componentes nem valores de library hoje, a pré-visualização em direto é a única verificação.
progFields
data.type é virtual para estado local, table para uma coluna do datasource ligado, ou
expression / datasource. O workflow de um campo executa-se quando ele muda. Uma predefinição define
props.fieldValue; um campo calculado define props.fieldComputed: true mais
propExpressions.fieldValue.
progDataSource
Um único registo por chave (formulário): dataSourceFilterModelType: "index" com um dataSourceIndexId
que existe nos próprios tableIndexes da tabela. Uma lista filtrada (grid ou list):
dataSourceFilterModelType: "query" com filterModelMongoFx, uma string de expressão ao estilo Mongo.
dataSourceType é table, array, json, csv, none, ou vazio para um componente puramente de apresentação
sem nenhuma fonte de dados.
progEvents e os três hooks 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.
Os eventos user_defined são disparados de qualquer sítio com a ação
raise_event; screen_ready é o hook de montagem habitual.
Os três hooks incorporados de um componente repartem o trabalho, e usar o errado é uma fonte comum de erros:
screen_ready
Dispara uma vez por instância. Crie aqui o DOM e os widgets.
on_refresh
Dispara após cada carregamento, incluindo o primeiro, logo a seguir a screen_ready. Entregue os novos dados a widgets
que já existem. Pôr o trabalho de atualização em screen_ready faz voltar a executar o código de criação sobre DOM
que ainda existe e empilha um segundo widget.
on_unload
Dispara quando a instância é desmontada. Destrua o que o prog criou: widgets, temporizadores,
ouvintes de document / window, observadores. O motor só consegue libertar o que criou: um ouvinte
ligado a document sobrevive ao painel de outra forma.
Padrões
- Estados de carregamento e de vazio: ponha
xu-ref="myref"no elemento ligado a dados e depois condicione os elementos de esqueleto ou de vazio comxu-rendersobre(@SYS_GLOBAL_OBJ_REFS).myref, o seu conjunto de dados fica associado quando os dados chegam. - Modais: construa a caixa de diálogo como um componente próprio e abra-a com a ação
call_modal. - Guardar ou eliminar uma linha ligada:
invoke_actioncomact_save/act_delete, ou um progset_datadedicado para qualquer coisa para além da linha atual.
Programas de lógica e fluxos de trabalho
Os tipos de prog de lógica partilham a maquinaria de dados de um componente (progDataSource, progFields,
progEvents, properties.progParams) sem qualquer interface:
Parâmetros
Quem chama passa valores através de name.parameters da ação,
{ "order_id_in": { "value": "", "fx": "@selected_id_v" } }, value para um valor estático, fx para
uma expressão. O verificador confirma que o programa de destino existe e que o seu menuType corresponde à
ação.
Ações de fluxo de trabalho
Um fluxo de trabalho é um array de passos, { "id": "...", "data": { "action": "...", "name": { ... }, "enabled": true }, "props": {} }, executados por ordem. props.condition condiciona um passo, props.async: true dispara-o sem esperar. Os fluxos de trabalho aparecem em tratadores xu-on:*, progEvents[].workflow
e no próprio workflow de um campo.
O invoke_action aceita act_next, act_prev, act_first, act_last, act_reload,
act_refresh, act_print, act_save, act_delete (apenas em contexto de componente).
alter_ui_element, create_ui_element, info_ui_element, remove_ui_element,
empty_ui_element, cache_ui_element, load_ui_element. Conduza a interface através de campos e de xu-exp /
xu-render em vez de uma ação imperativa sobre elementos.
O próprio seletor de ações do Studio oferece Call AI Agent e Call Triage Agent a seguir às ações
acima. Nenhuma está nesta tabela porque nenhuma é uma ação: o validate_prog não tem nenhum caso para elas e
reporta invalid trigger type, e o motor de fluxos de trabalho do runtime também não tem tratador para elas, por isso
um passo guardado nunca se executa, mesmo que o erro seja ignorado. Para fazer um prog alcançar um agente publicado, adicione
uma ferramenta AI Agent à lista de ferramentas de outro agente (o agentConfig.agent_tools de um documento menuType: "ai_agent"),
não um passo de fluxo de trabalho num componente, get_data ou qualquer outro tipo de prog.
O name.value de update atribui campos com pares @field: expression separados por ponto e vírgula, ou com um
objeto JSON5, "@saving_v: true; @status_v: 'sent'". Chamar outro programa indica-o em name.prog,
fazendo corresponder a ação ao tipo do próprio programa
(get_data precisa de um prog get_data, call_native_javascript de um prog javascript, e assim por diante).
O call_library chama um método de plugin instalado: name.plugin_name tem de estar comprado e
instalado na aplicação ou o verificador rejeita o passo, name.library_method um dos métodos que o
plugin exporta, name.library_props os seus campos declarados. Dois nomes de props são uma convenção entre
plugins e não específicos de nenhum: event_name_for_successful_callback dispara esse
evento com a resposta do método, field_id_to_return_result escreve a resposta diretamente nesse campo,
nenhum é obrigatório.
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 é
o hook de inicialização habitual; before_record / after_record /
record_not_found / locate_not_found são ciclo de vida de dados, sobretudo para set_data e batch;
client_interval é um temporizador repetitivo; user_defined dispara a partir da ação raise_event.
Tabelas
Um prog de tabela (menuType: "table") define uma tabela de base de dados: as suas colunas (tableFields), os seus
índices (tableIndexes) e o plugin de base de dados que a armazena (properties.databaseSocket). Pai na árvore:
database, ou uma pasta dentro dela.
databaseSockettem de indicar um plugin de base de dados instalado no projeto,@xuda.io/xuda-dbs-plugin-xudaé a predefinição da plataforma; uma tabela existente no mesmo projeto é a referência para saber que socket reutilizar.- É exigido pelo menos um campo e pelo menos um índice.
field_idcomeça por uma letra, seguida de letras, dígitos, sublinhado, hífen, dois pontos ou ponto, e é único dentro da tabela.fieldTypeéstring,number,boolean,array,objectoudate;mandatory: truetorna-o obrigatório ao guardar.- Cada índice precisa de um
namee dekeysnão vazios, e cada chave tem de ser umfield_idexistente.
Convenção: prefixe as colunas com um código de tabela de três letras, uma tabela chamada "ORD - Orders" recebe
ORD_Id, ORD_Total, ORD_Status. Dê a cada tabela um campo <TBL>_Id único com um índice único
sobre ele, a ligação de um componente a um só registo precisa dele.
Uma tabela é usada de três formas: o progDataSource.dataSourceTableId de um componente ou consulta, um
prog get_data / set_data / batch para acesso ao nível da linha a partir de fluxos de trabalho, ou xu.dbs_create /
dbs_read / dbs_update / dbs_delete a partir de um script, tratado a seguir.
Programas JavaScript
Um prog javascript (menuType: "javascript") contém código-fonte JS real em scriptData.value, compilado
ao guardar. O save_prog dispara essa compilação e devolve o resultado como data.compile, { ok: true, dependencies } ou { ok: false, error }. Uma compilação falhada guarda na mesma o documento, por isso uma construção lê
compile.ok e corrige antes de avançar.
O contrato de execução
A fonte é escrita como um corpo assíncrono simples, sem export, sem invólucro. Em runtime executa-se como:
params são as entradas já avaliadas de quem chama; xu é a API de runtime abaixo; um valor de retorno
é opcional, a forma idiomática de devolver resultados é xu.set_field_value nos campos do
componente que chama. Aqui as aspas são aceites, ao contrário do valor de um atributo xu-script.
A API de runtime xu
Os métodos dbs_* recebem o _id do próprio prog da tabela, nunca um nome. Os seletores são objetos ao estilo Mongo sobre
os ids de campos, {} devolve tudo (limite predefinido 999). A projeção fields é opcional: [] devolve todos os campos e uma lista de ids de campos devolve só esses.
Passar dados: campos, não parâmetros
O call_native_javascript não avalia os invólucros de parâmetros {value, fx}, name.parameters
chega em bruto ao script. O contrato fiável: o componente põe primeiro a carga num campo (um passo
update ou uma entrada xu-bind), o fluxo de trabalho chama o prog com parameters: {} vazio e
o script lê-a com xu.get_field_value e reporta com xu.set_field_value. Ao chamar
a partir de outro script, xu.call_javascript(prog_id, {...}) já passa os parâmetros diretamente.
Particularidades da pré-visualização em direto
- As escritas de dados chegam à base de dados real, mas o
xu.dbs_readlê um armazenamento local de rascunho que pode não conter linhas novas do servidor: uma leitura logo a seguir a uma escrita pode vir vazia na pré-visualização mesmo que a escrita tenha chegado (visível no separador Dados da tabela no Studio). As aplicações implementadas leem e escrevem o mesmo armazenamento. - Os scripts compilados ficam muito em cache nas pré-visualizações de desenvolvimento: uma pré-visualização em execução pode continuar a executar o script anterior mesmo depois de recarregamentos, após um guardar recompilá-lo. Um refrescamento forçado do navegador limpa-o.
- O
xu.alertcom apresentaçãomodal,toastoubrowserpode surgir como umalert()nativo e bloqueante na pré-visualização. Oxu.set_field_valuepara um campo de estado é a forma mais segura de reportar.
prog javascript vs atributo xu-script
Técnicas sem aspas para xu-script / xu-style
O canvas do designer serializa os valores de atributos sem escape, por isso uma só aspa corrompe a
marcação do componente. Os template literals evitam por completo as aspas de strings
(el.textContent = `Ready`); o carácter literal ", por exemplo ao construir CSV, vem
de String.fromCharCode(34); os seletores de atributos CSS são válidos sem aspas
(el.querySelector(`[data-role=import-btn]`)); e uma proteção contra nova execução,
if (el.__bound) return; el.__bound = true;, impede um script de se ligar duas vezes ao voltar a renderizar.
Armadilhas
Cada entrada abaixo estragou uma construção real em algum momento. O validate_prog apanha a maioria delas, execute-o
antes de cada guardar.
Mecânica da API
- Toda a resposta é
{ code, data },code < 0é um erro. - O
create_progdevolve o novo documento emdata.prog, guardar a resposta inteira em vez disso persiste um documento mal formado compropertiesenterrado emprog. - O
save_progsubstitui o documento inteiro. Parta do documento atual, nunca de um esqueleto montado à mão; um-409significa que mudou desde a última leitura: obtenha de novo, reaplique, tente outra vez. - Por MCP,
prog_jsoneproperties_jsonsão passados como strings: a camada de esquema da ferramenta retira as chaves desconhecidas de um parâmetro de objeto e pode descartar secções inteiras em silêncio. - O
delete_progé uma eliminação suave, definestat: 4. O nóglobal_<app_id>não pode ser eliminado.
Conteúdo do documento
- Nenhum
'nem"dentro de valores dexu-scriptouxu-style. - As chaves com prefixo
$($folded,$childrenClass,$nodeBackClass), maispath,code,editCode, são estado de vista do designer e nunca pertencem a um nó deprogUiguardado. - Nenhum tipo de nó
commentnemtext, apenas elementos, texto estático emcontent. - Cada nó de elemento precisa de
attributes: {}echildren: []mesmo quando vazios. xu-exp:classsubstitui oclassestático, todas as classes necessárias pertencem dentro da expressão.xu-bindé um id de campo simples, sem@, em todos os outros sítios os campos usam@.- Só os atributos
xu-*documentados fazem alguma coisa, um inventado é ignorado em silêncio e ovalidate_progavisa. - A raiz da árvore de um prog
ai_agentéai_agents, guarde-o comstudio_meta.parentId: "ai_agents"(ou um id de pasta dentro dela) se o verificador assinalarparentId.
Runtime e renderização
- Um
tagNamecom maiúscula inicial é sempre reclamado como componente, mesmo um erro de digitação, e lança um erro ao montar indicando a tag, alibrarye todas as origens tentadas, não há um "não renderiza" silencioso como acontece com umxu-panelsem programa selecionado. - O
validate_prognão verifica tags de componentes nem valores delibrary, só a pré-visualização em direto apanha um com erro ortográfico. - Nenhum CSS utilitário (Tailwind ou outro) em runtime a menos que o plugin
uiFrameworkdo projeto o forneça realmente, classes comop-4não fazem nada em silêncio caso contrário. O estilo autónomo éxu-style, com âmbito automático por[xu-ui-id]. - O
xu-scriptexecuta-se uma vez por visibilidade do elemento e pode voltar a disparar ao renderizar de novo, proteja comel.__bounde limite as consultas ael.
Dados e scripts
- Os parâmetros de
call_native_javascriptnão são avaliados, passe os dados através de campos (veja Passar dados, acima). - As linhas de
dbs_readsão{id, value}, os campos vivem em.value, o id da linha em.id. Não passe uma projeçãofields, estraga a leitura no servidor. - Dentro de
xu-for, ponha o iterador entre parênteses,(@_FOR_VAL).CNT_Nameé avaliado,@_FOR_VAL.CNT_Namefalha em silêncio e renderiza em vez disso o texto-fonte substituído. - As escritas da pré-visualização chegam à base de dados real; as leituras da pré-visualização vêm de um armazenamento local de rascunho que pode parecer vazio logo a seguir a uma escrita.
- Prefira um campo de estado à apresentação modal ou toast de
xu.alertnas pré-visualizações, pode ser renderizada como umalert()nativo e bloqueante.
Verificar o seu trabalho
Volte a obter com get_prog depois de guardar e compare com o esperado. Para trabalho de interface, abra o componente
no Studio e prima o botão de reprodução da pré-visualização, ou o URL de pré-visualização em direto do projeto quando
existir. Para um prog javascript, verifique data.compile.ok em cada guardar. Corrija todos os
erros do validate_prog; trate os seus avisos, aspas, chaves $, atributos desconhecidos, como itens a corrigir já
e não como ruído.