Průvodce Studia pro LLM
Dokumentový model programů, reference atributů xu-* a pravidla workflow, která se AI agent učí před prvním voláním nástroje.
Každý projekt Studia, každá tabulka, obrazovka, skript a trasa v něm je jeden dokument JSON
v CouchDB, nazývaný prog (docType: "studio"). Tato stránka je táž reference, kterou dostane
AI agent, když ho vytváří, přepsaná jako dokumentace: tvar tohoto dokumentu, atributy, které
řídí jeho UI, akce, které může workflow provést, a chyby, které se objevují ve skutečných
sestaveních.
Jak AI agent tohoto průvodce získá
Připojte klienta MCP k Xudě a první odpověď, volání initialize, nese tohoto průvodce jako
instructions relace, čerstvě sloučené z živých pravidel platformy, takže nemůže popsat něco, co
nasazený kontrolor už nevynucuje. Viz
Připojení AI klienta přes MCP.
Zevnitř relace se k témuž materiálu dostanou přímo dvě metody, přes MCP nebo běžné REST, a nevyžadují nic víc než běžný klíč API:
Předepsané pořadí: přečtěte téma odpovídající tomu, co stavíte, načtěte odpovídající příklad,
vytvořte prog přes továrnu (create_prog), stavějte uvnitř jeho obsahových sekcí, zvalidujte
(validate_prog) a opravte vše, co ohlásí, uložte (save_prog) a pak znovu načtěte a ověřte.
Uložení, které vrátí -409, znamená, že se dokument od přečtení změnil: znovu načtěte, znovu
aplikujte, zkuste to znovu.
Dokumentový model progu
Obálka
Tato pole vlastní kód serveru a továrny; vytvářené sestavení vždy upravuje jen obsahové sekce pod nimi.
_idmá tvar<poslední 3 znaky app_id>_<3písmenná zkratka typu>_<12 hex>, například392_cmp_...pro komponentu,392_tbl_...pro tabulku,392_jvs_...pro javascriptový prog,392_gtd_.../392_std_...pro get_data / set_data,392_fld_...pro složku. Id generuje továrna, sestavení si žádné nevymýšlí.statje 3 pro aktivní, 4 pro měkce smazané (to nastaví smazání progu). Strom Studia ukazuje jenstat: 3.properties.menuTypeje jedno zglobals,table,get_data,set_data,batch,alert,javascript,folder,route,api,component,ai_agent.studio_meta.parentIdumisťuje uzel do stromu Studia: buď id jiného progu (obvykle složky), nebo jeden z kořenů typů,programs(logika a komponenty),database(tabulky),routes,globals,ai_agents. NerozpoznanéparentIdnechá uzel ve stromu neviditelný a je to chyba kontroly.
Obsahové sekce podle menuType
Dokument globals
Každý projekt má právě jeden dokument global_<app_id> (menuType: "globals"). Jeho progFields
jsou čitelná z každého jiného progu jako @field_id. Dva systémové globály se dodávají s každým
projektem: @SYS_GLOBAL_OBJ_LOGIN_USER_INFO pro přihlášeného uživatele a @SYS_GLOBAL_OBJ_REFS
pro prvky registrované pomocí xu-ref. Dokument globals ani kořen stromu nelze smazat.
Strukturální povinnosti
properties,properties.menuType,properties.menuName,studio_metaastudio_meta.parentIdjsou povinné u každého dokumentu.- Položka
progFieldspotřebuje unikátníid,data.field_id,data.typezvirtual,table,expressionnebodatasourceaprops.fieldTypezstring,number,boolean,arrayneboobject. - Vyhrazené názvy proměnných runtime,
_NULL,_THIS,_FOR_KEY,_FOR_VAL,_ROWNO,_ROWID,_ROWDOC,_KEY,_VAL, se nikdy nedefinují znovu jako id polí. - Duplicitní id, neznámé
menuTypea chybně utvořené sekce jsou vesměs tvrdé chyby, kterévalidate_proghlásí přímo.
Výrazy a atributy xu-*
Syntaxe výrazů
Výrazy běží nad vlastní datovou sadou progu. Jakékoli pole, lokální, vázané na tabulku, globální
nebo parametr, se odkazuje pomocí @: @search_v, @ORD_Total, @SYS_GLOBAL_OBJ_LOGIN_USER_INFO,
kolem něj běžný JavaScript, @count_v > 0 ? 'has rows' : 'empty'. Objektový literál potřebuje
obalit závorkami, ({ ORD_Status: @status_v }). Uvnitř smyčky xu-for je aktuální položka
@_FOR_VAL a její klíč nebo index @_FOR_KEY (přejmenovatelné pomocí xu-for-key / xu-for-val).
xu-render a další podmínky vracejí pravdivou nebo nepravdivou hodnotu přímo, nikdy řetězec
"Y" / "N" ani další porovnání.
Všude jinde se pole odkazuje pomocí @. xu-bind bere místo toho holé id pole:
xu-bind="search_v", nikdy xu-bind="@search_v".
Atributy xu
Rodiny předpon
Rodiny atributů, které berou příponu. Hodnoty xu-on jsou vždy pole objektů obslužných rutin;
hodnoty xu-exp jsou vždy řetězce výrazů.
Hodnota atributu xu-on:* je vždy pole objektů obslužných rutin a každé workflow je pole
kroků akcí (úplná reference akcí je níže, v části Logické progy a workflow). props.condition
kroku ho podmiňuje; props.async: true ho spustí bez čekání.
Klíčová sémantika
xu-exp:classnahrazuje statický atributclass, nepřidává k němu. U prvku, který nese obojí, se statický ignoruje, takže třídy rozvržení patří i dovnitř výrazu:xu-exp:class="'card p-4 ' + (@active_v ? 'ring' : '')".xu-scriptbere holý výrazfunction (el) { ... }, vyhodnocený přesevala volaný s elementem DOM, jakmile se uzel stane viditelným. Chraňte se před opětovným spuštěním (if (el.__bound) return; el.__bound = true;) a každý dotaz omezte nael, nikdy nadocument.xu-stylemá automatický obor: každý selektor se opatří předponou[xu-ui-id]uzlu, takže běžné selektory prvků a tříd zůstávají lokální a nikam neuniknou.- Hodnoty
xu-scriptanixu-stylenesmí obsahovat znak uvozovky ('nebo"), plátno návrháře serializuje atributy bez escapování a jediná uvozovka poškodí komponentu. Techniky bez uvozovek popisuje níže část o programech JavaScript. - Statický text patří do vlastnosti
contentprvku.xu-exp:xu-contentje jen pro dynamický text.
Tagy
Tagy pro psaní kromě čistého HTML: xu-template, xu-single-view, xu-multi-view, xu-panel,
xu-teleport, xu-slot.
xu-single-viewvymezuje jeden záznam (kořen formuláře, použitelný i vnořeně).xu-multi-viewopakuje své potomky jednou pro každý řádek vázaných dat.xu-panelvkládá jiný prog (atributprogramplus vstupyxu-exp:<param>). Kromě výrazů parametrů na něj patří jen standardní atributy HTML (class,id,style,title,hidden,slot,name,role,tabindex).xu-teleportvykresluje své potomky do jiného cíle DOM (toneboxu-exp:to).- Název tagu s velkým písmenem (
Button,Card) je zkompilovaná komponenta, ne element HTML, viz Vkládání níže.
Komponenty
Komponenta (menuType: "component") je jednotka UI: strom elementů (progUi) vázaný na lokální
stav (progFields), volitelná data (progDataSource), logiku životního cyklu (progEvents)
a rozhraní vstupů a výstupů (properties.progParams).
Vlastnosti
renderTypejeformpro jeden záznam (kořenový elementxu-single-view) nebogrid/listpro jeden opakovaný pro každý datový řádek (kořenový elementxu-multi-view).rwModejeRpro čtení neboUpro aktualizaci;allowCreateříká, zda lze vložit nový řádek, když žádný neodpovídá.- Konvence pojmenování
progParams: parametry končí_in/_out, virtuální pole lokální v komponentě končí_v. uiFrameworkzrcadlí to, co už používají stávající komponenty projektu. Stávající projekt, který ho vynechává, by ho měl vynechávat dál; nastavení pluginu frameworku, který drive projektu ve skutečnosti neservíruje, zablokuje živý náhled na prázdné obrazovce.
Strom elementů (progUi)
Uzel root z továrny zůstává; sestavení pracuje uvnitř jeho children. Každý uzel potřebuje
unikátní id (nové uzly používají ui-<uuid>), type: "element" a tagName, žádné typy uzlů
comment ani text, statický text místo toho žije v content. Každý uzel potřebuje
attributes: {} a children: [] i když jsou prázdné, serializér plátna návrháře dereferencuje
obojí na každém uzlu a vynechání rozbije vlastní náhled komponenty.
Vkládání: xu-panel nebo zkompilovaná komponenta
Obojí se připojuje průhledně, bez obalového elementu, a obojí rozhoduje jeden signál: zda
tagName začíná velkým písmenem.
xu-panel,tagNamemalými písmeny plus atributprogram, vkládá jiný prog, potomka vázaného na databázi nebo se stavem, s vlastními poli a událostmi.programje id potomka (neboxu-exp:progpro dynamické), hodnoty se do jeho parametrů_indostávají přesxu-exp:<param>.- Tag s velkým písmenem plus atribut
librarypřipojuje zkompilovanou komponentu, primitiv design systému nebo část, kterou aplikace sama zkompilovala. Každý běžný atribut se stává vlastností (props.<name>), nikdy atributem DOM, protože komponenta nevykresluje žádný vlastní element. Uzel komponenty nemá výstupní parametry, na rozdíl odxu-panelnic nezapisuje hodnotu zpět do vašich polí.
Překlep <Buton> se stále bere jako tag komponenty, nikdy se nevrátí k neznámému elementu HTML
a při připojení vyhodí chybu s názvem tagu, knihovny a každého vyzkoušeného zdroje. validate_prog
dnes tagy komponent ani hodnoty library nekontroluje, jedinou kontrolou je živý náhled.
progFields
data.type je virtual pro lokální stav, table pro sloupec vázaného zdroje dat nebo
expression / datasource. workflow pole se spouští při změně. Výchozí hodnotu nastavuje
props.fieldValue; počítané pole nastavuje props.fieldComputed: true plus
propExpressions.fieldValue.
progDataSource
Jeden záznam podle klíče (formulář): dataSourceFilterModelType: "index" s dataSourceIndexId,
které existuje v tableIndexes samotné tabulky. Filtrovaný seznam (grid nebo list):
dataSourceFilterModelType: "query" s filterModelMongoFx, řetězcem výrazu ve stylu Mongo.
dataSourceType je table, array, json, csv, none nebo prázdné pro čistě prezentační
komponentu bez zdroje dat.
progEvents a tři háčky životního cyklu
Typy událostí: on_load, on_exit, before_record, after_record, record_not_found,
locate_not_found, screen_ready, on_refresh, on_unload, client_interval, user_defined.
Události user_defined se spouštějí odkudkoli akcí raise_event; screen_ready je obvyklý
háček připojení.
Tři vestavěné háčky komponenty dělí práci a použití špatného je častým zdrojem chyb:
screen_ready
Spustí se jednou na instanci. Zde vytvářejte DOM a widgety.
on_refresh
Spustí se po každém načtení, včetně prvního, hned po screen_ready. Předejte nová data widgetům,
které už existují. Pokud práci s obnovou dáte místo toho do screen_ready, znovu se spustí kód
pro vytvoření nad DOM, který stále existuje, a vznikne druhý widget navíc.
on_unload
Spustí se při rozebrání instance. Zničte, co prog vytvořil: widgety, časovače, posluchače
document / window, pozorovatele. Engine umí uvolnit jen to, co vytvořil; posluchač navázaný
na document jinak přežije panel.
Vzory
- Stavy načítání a prázdna: dejte
xu-ref="myref"na prvek vázaný na data, pak podmiňte kostry nebo prázdné prvky pomocíxu-rendernad(@SYS_GLOBAL_OBJ_REFS).myref, jehož datová sada se připojí, jakmile data dorazí. - Modální okna: dialog postavte jako samostatnou komponentu a otevřete ji akcí
call_modal. - Uložení nebo smazání vázaného řádku:
invoke_actionsact_save/act_delete, nebo vyhrazený progset_datapro cokoli nad rámec aktuálního řádku.
Logické progy a workflow
Typy logických progů sdílejí datový aparát komponenty (progDataSource, progFields,
progEvents, properties.progParams) bez jakéhokoli UI:
Parametry
Volající předává hodnoty přes name.parameters akce,
{ "order_id_in": { "value": "", "fx": "@selected_id_v" } }, value pro statickou hodnotu, fx
pro výraz. Kontrola ověřuje, že cílový program existuje a jeho menuType odpovídá akci.
Akce workflow
Workflow je pole kroků, { "id": "...", "data": { "action": "...", "name": { ... }, "enabled": true }, "props": {} }, spouštěných v pořadí. props.condition krok podmiňuje,
props.async: true ho spustí bez čekání. Workflow se objevují v obslužných rutinách xu-on:*,
v progEvents[].workflow a ve vlastním workflow pole.
invoke_action přijímá act_next, act_prev, act_first, act_last, act_reload,
act_refresh, act_print, act_save, act_delete (jen v kontextu komponenty).
alter_ui_element, create_ui_element, info_ui_element, remove_ui_element,
empty_ui_element, cache_ui_element, load_ui_element. UI řiďte místo imperativní akce nad
prvkem přes pole a xu-exp / xu-render.
Vlastní výběr akcí Studia nabízí Volat AI agenta a Volat třídicího agenta vedle výše
uvedených akcí. Ani jedna není v této tabulce, protože ani jedna není skutečnou akcí: validate_prog
pro ně nemá žádný případ a hlásí invalid trigger type, a ani runtime engine workflow pro ně nemá
obslužnou rutinu, takže uložený krok se nikdy nespustí, i když chybu ignorujete. Aby jeden prog
dosáhl na publikovaného agenta, přidejte místo toho nástroj AI agent do seznamu nástrojů jiného
agenta (agentConfig.agent_tools dokumentu menuType: "ai_agent"), ne krok workflow na komponentě,
get_data nebo jakémkoli jiném typu progu.
name.value akce update přiřazuje pole dvojicemi @field: expression oddělenými středníky
nebo objektem JSON5, "@saving_v: true; @status_v: 'sent'". Volání jiného programu ho pojmenuje
pod name.prog a akce musí odpovídat typu programu
(get_data potřebuje prog get_data, call_native_javascript prog javascript a tak dále).
call_library volá metodu nainstalovaného pluginu: name.plugin_name musí být zakoupen
a nainstalován v aplikaci, jinak kontrola krok odmítne, name.library_method je jedna z metod,
které plugin exportuje, name.library_props jeho deklarovaná pole. Dva názvy vlastností jsou
konvencí napříč pluginy, ne specifikou některého z nich: event_name_for_successful_callback
vyvolá tuto událost s odpovědí metody, field_id_to_return_result zapíše odpověď přímo do daného
pole, ani jedno není povinné.
Typy 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 je
obvyklý inicializační háček; before_record / after_record /
record_not_found / locate_not_found jsou životní cyklus dat, zejména pro set_data a batch;
client_interval je opakující se časovač; user_defined se spouští akcí raise_event.
Tabulky
Prog tabulky (menuType: "table") definuje databázovou tabulku: její sloupce (tableFields),
indexy (tableIndexes) a databázový plugin, který ji ukládá (properties.databaseSocket).
Rodič ve stromu: database nebo složka pod ním.
databaseSocketmusí pojmenovávat databázový plugin nainstalovaný v projektu,@xuda.io/xuda-dbs-plugin-xudaje výchozí platformy; stávající tabulka ve stejném projektu je vodítkem, který socket znovu použít.- Vyžaduje se alespoň jedno pole a alespoň jeden index.
field_idzačíná písmenem, pak následují písmena, číslice, podtržítko, pomlčka, dvojtečka nebo tečka, a je v rámci tabulky unikátní.fieldTypejestring,number,boolean,array,objectnebodate;mandatory: trueho činí povinným při uložení.- Každý index potřebuje neprázdné
nameakeysa každý klíč musí být existujícífield_id.
Konvence: sloupce opatřete třípísmenným kódem tabulky, tabulka pojmenovaná „ORD - Orders“ dostane
ORD_Id, ORD_Total, ORD_Status. Každé tabulce dejte unikátní pole <TBL>_Id s unikátním
indexem, vazba komponenty na jeden záznam ho potřebuje.
Tabulka se používá třemi způsoby: jako progDataSource.dataSourceTableId komponenty nebo dotazu,
jako prog get_data / set_data / batch pro přístup na úrovni řádků z workflow, nebo přes
xu.dbs_create / dbs_read / dbs_update / dbs_delete ze skriptu, což je popsáno dále.
Programy JavaScript
Prog javascript (menuType: "javascript") drží skutečný zdroj JS v scriptData.value, kompilovaný
při uložení. save_prog toto sestavení spustí a vrátí výsledek jako data.compile, { ok: true, dependencies } nebo { ok: false, error }. Neúspěšná kompilace dokument stále uloží, takže
sestavení čte compile.ok a opraví ho, než půjde dál.
Smlouva o provádění
Zdroj se píše jako obyčejné asynchronní tělo, bez export, bez obalu. Za běhu se provádí takto:
params jsou už vyhodnocené vstupy volajícího; xu je API runtime níže; návratová hodnota je
volitelná, běžný způsob předání výsledků zpět je xu.set_field_value na polích volající
komponenty. Uvozovky jsou zde v pořádku, na rozdíl od hodnoty atributu xu-script.
API runtime xu
Metody dbs_* berou vlastní _id progu tabulky, nikdy název. Selektory jsou objekty ve stylu Mongo
nad id polí, {} vrátí vše (výchozí limit 999). Projekce fields je volitelná, [] vrátí všechna pole a seznam id polí vrátí jen tato pole.
Předávání dat: pole, ne parametry
call_native_javascript nevyhodnocuje obaly parametrů {value, fx}, name.parameters se
ke skriptu dostanou syrové. Spolehlivá smlouva: komponenta nejdřív uloží obsah do pole (krokem
update nebo vstupem xu-bind), workflow zavolá prog s prázdnými parameters: {} a skript ho
přečte pomocí xu.get_field_value a odpoví pomocí xu.set_field_value. Při volání z jiného
skriptu místo toho xu.call_javascript(prog_id, {...}) předá parametry přímo.
Zvláštnosti živého náhledu
- Zápisy dat se dostanou do skutečné databáze, ale
xu.dbs_readčte lokální úložiště konceptů, které nemusí obsahovat čerstvé řádky ze serveru, takže čtení hned po zápisu se může v náhledu vrátit prázdné, i když zápis proběhl (viditelný na záložce Data tabulky ve Studiu). Nasazené aplikace čtou a zapisují do stejného úložiště. - Zkompilované skripty se ve vývojových náhledech silně cachují, běžící náhled může dál provádět předchozí skript i napříč znovunačteními po uložení, které ho překompiluje. Vyčistí to tvrdé obnovení prohlížeče.
xu.alertse zobrazenímmodal,toastnebobrowserse může v náhledu projevit jako nativní blokujícíalert(). Bezpečnější způsob hlášení zpět jexu.set_field_valuedo stavového pole.
prog javascript vs atribut xu-script
Techniky bez uvozovek pro xu-script / xu-style
Plátno návrháře serializuje hodnoty atributů bez escapování, takže jediná uvozovka poškodí markup
komponenty. Šablonové literály se řetězcovým uvozovkám zcela vyhnou
(el.textContent = `Ready`); samotný znak ", například při sestavování CSV, pochází
z String.fromCharCode(34); selektory atributů CSS jsou platné bez uvozovek
(el.querySelector(`[data-role=import-btn]`)); a ochrana proti opakovanému spuštění,
if (el.__bound) return; el.__bound = true;, brání skriptu navázat se dvakrát při opětovném
vykreslení.
Nášlapné miny
Každá položka níže někdy rozbila skutečné sestavení. validate_prog zachytí většinu z nich,
spouštějte ho před každým uložením.
Mechanika API
- Každá odpověď je
{ code, data },code < 0je chyba. create_progvrací nový dokument poddata.prog, uložení celé odpovědi místo toho uchová chybně utvořený dokument spropertieszahrabanými podprog.save_prognahrazuje celý dokument. Vycházejte ze stávajícího dokumentu, nikdy z ručně složené kostry;-409znamená, že se od posledního čtení změnil, znovu načtěte, znovu aplikujte, zkuste to znovu.- Přes MCP se
prog_jsonaproperties_jsonpředávají jako řetězce, vrstva schématu nástroje odstraňuje neznámé klíče z objektového parametru a může tiše zahodit celé sekce. delete_progje měkké smazání, nastavístat: 4. Uzelglobal_<app_id>nelze smazat.
Obsah dokumentu
- Žádné
'ani"uvnitř hodnotxu-scriptneboxu-style. - Klíče s předponou
$($folded,$childrenClass,$nodeBackClass) pluspath,code,editCodejsou stav zobrazení návrháře a do uloženého uzluprogUinikdy nepatří. - Žádné typy uzlů
commentanitext, jen elementy, statický text vcontent. - Každý uzel elementu potřebuje
attributes: {}achildren: []i když jsou prázdné. xu-exp:classnahrazuje statickéclass, každá potřebná třída patří dovnitř výrazu.xu-bindje holé id pole, bez@, všude jinde pole používají@.- Cokoli dělají jen zdokumentované atributy
xu-*, vymyšlený se tiše ignoruje avalidate_progvaruje. - Kořenem stromu progu
ai_agentjeai_agents, uložte ho sstudio_meta.parentId: "ai_agents"(nebo id složky pod ním), pokud kontrola označíparentId.
Runtime a vykreslování
tagNames velkým písmenem se vždy bere jako komponenta, i překlep, a při připojení vyhodí chybu s názvem tagu,librarya každého vyzkoušeného zdroje, neexistuje žádné tiché „nevykreslí se“, jaké máxu-panelbez vybraného programu.validate_prognekontroluje tagy komponent ani hodnotylibrary, špatně napsanou zachytí jen živý náhled.- Žádné utility CSS (Tailwind ani jiné) za běhu, pokud je plugin
uiFrameworkprojektu skutečně neposkytuje, třídy jakop-4jinak tiše nic nedělají. Soběstačné stylování jexu-styles automatickým oborem[xu-ui-id]. xu-scriptběží jednou při viditelnosti elementu a může se znovu spustit při opětovném vykreslení, chraňte ho pomocíel.__bounda dotazy omezte nael.
Data a skripty
- Parametry
call_native_javascriptse nevyhodnocují, data předávejte přes pole (viz Předávání dat výše). - Řádky
dbs_readjsou{id, value}, pole žijí pod.value, id řádku na.id. Nepředávejte projekcifields, rozbije čtení na straně serveru. - Uvnitř
xu-forobalte iterátor závorkami,(@_FOR_VAL).CNT_Namese vyhodnotí,@_FOR_VAL.CNT_Nametiše selže a vykreslí místo toho nahrazený zdrojový text. - Zápisy z náhledu se dostanou do skutečné databáze; čtení z náhledu pocházejí z lokálního úložiště konceptů, které může hned po zápisu vypadat prázdně.
- V náhledech dávejte přednost stavovému poli před zobrazením
modalnebotoastuxu.alert, může se vykreslit jako nativní blokujícíalert().
Ověření práce
Po uložení znovu načtěte pomocí get_prog a porovnejte, co se očekávalo. Pro práci na UI otevřete
komponentu ve Studiu a stiskněte tlačítko přehrání náhledu, nebo adresu URL živého náhledu projektu,
je-li k dispozici. U progu javascript kontrolujte data.compile.ok při každém uložení. Opravte
každou chybu validate_prog; s jeho varováními, uvozovkami, klíči $ a neznámými atributy
zacházejte jako s věcmi k okamžité opravě, ne jako s šumem.