Preskočiť na obsah
Overené

Sprievodca Studio LLM

Dokumentový model progu, referencia atribútov xu-* a pravidlá pracovných postupov, ktoré sa AI agent učí pred prvým volaním nástroja.

Každý projekt Studia, každá tabuľka, obrazovka, skript a trasa v ňom je jeden dokument JSON v CouchDB nazývaný prog (docType: "studio"). Táto stránka je tá istá referencia, ktorú dostane AI agent, keď ho vytvára, prepísaná ako dokumentácia: tvar tohto dokumentu, atribúty, ktoré riadia jeho UI, akcie, ktoré môže pracovný postup vykonať, a chyby, ktoré sa objavujú v skutočných zostaveniach.

Ako AI agent získa tohto sprievodcu

Pripojte klienta MCP k Xuda a prvá odpoveď, volanie initialize, nesie tohto sprievodcu ako instructions relácie, čerstvo zlúčeného z vlastných živých pravidiel platformy, takže nikdy nemôže opísať niečo, čo nasadená kontrola už nevynucuje. Pozrite si Pripojenie AI klienta cez MCP.

Z vnútra relácie sa k tomu istému materiálu dostanú priamo dve metódy, cez MCP alebo obyčajné REST, a nevyžadujú nič okrem bežného API kľúča:

Predpísané poradie: prečítajte tému, ktorá zodpovedá tomu, čo vytvárate, načítajte zodpovedajúci príklad, vytvorte prog cez továreň (create_prog), stavajte vnútri jeho obsahových sekcií, overte (validate_prog) a opravte všetko, čo hlási, uložte (save_prog) a potom znova načítajte na overenie. Uloženie, ktoré vráti -409, znamená, že sa dokument od prečítania zmenil: znova načítajte, znova použite zmeny a skúste znova.

Dokumentový model progu

Obálka

Tieto polia vlastní server a kód továrne; vytváraná zostava upravuje len obsahové sekcie pod nimi.

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 má tvar <last 3 chars of app_id>_<3-letter type abbreviation>_<12 hex>, napríklad 392_cmp_... pre komponent, 392_tbl_... pre tabuľku, 392_jvs_... pre prog javascript, 392_gtd_... / 392_std_... pre get_data / set_data, 392_fld_... pre priečinok. Id generuje továreň, zostava si ho nikdy nevymýšľa.
  • stat je 3 pre aktívny, 4 pre mäkko zmazaný (to nastaví zmazanie progu). Strom Studia zobrazuje iba stat: 3.
  • properties.menuType je jedno z globals, table, get_data, set_data, batch, alert, javascript, folder, route, api, component, ai_agent.
  • studio_meta.parentId umiestňuje uzol do stromu Studia: buď id iného progu (zvyčajne priečinka), alebo jeden z koreňov typov, programs (logika a komponenty), database (tabuľky), routes, globals, ai_agents. Nerozpoznané parentId nechá uzol v strome neviditeľný a je to chyba kontroly.

Obsahové sekcie podľa menuType

Dokument globals

Každý projekt má presne jeden dokument global_<app_id> (menuType: "globals"). Jeho progFields sú čitateľné z každého iného progu ako @field_id. S každým projektom sa dodávajú dva systémové globály: @SYS_GLOBAL_OBJ_LOGIN_USER_INFO pre prihláseného používateľa a @SYS_GLOBAL_OBJ_REFS pre elementy zaregistrované cez xu-ref. Dokument globals ani koreň stromu sa nedajú zmazať.

Štrukturálne povinnosti

  • properties, properties.menuType, properties.menuName, studio_meta a studio_meta.parentId sú povinné na každom dokumente.
  • Záznam progFields potrebuje jedinečné id, data.field_id, data.type z virtual, table, expression alebo datasource a props.fieldType z string, number, boolean, array alebo object.
  • Vyhradené názvy premenných runtime, _NULL, _THIS, _FOR_KEY, _FOR_VAL, _ROWNO, _ROWID, _ROWDOC, _KEY, _VAL, sa nikdy nedefinujú znova ako id polí.
  • Duplicitné id, neznáme menuType a chybne utvorené sekcie sú všetko tvrdé chyby, ktoré validate_prog hlási priamo.

Výrazy a atribúty xu-*

Syntax výrazov

Výrazy bežia nad vlastnou množinou dát progu. Každé pole, lokálne, viazané na tabuľku, globálne alebo parameter, sa označuje pomocou @: @search_v, @ORD_Total, @SYS_GLOBAL_OBJ_LOGIN_USER_INFO, okolo toho obyčajný JavaScript, @count_v > 0 ? 'has rows' : 'empty'. Objektový literál potrebuje obaľujúce zátvorky, ({ ORD_Status: @status_v }). Vnútri cyklu xu-for je aktuálna položka @_FOR_VAL a jej kľúč alebo index @_FOR_KEY (premenovateľné cez xu-for-key / xu-for-val). xu-render a ďalšie podmienky vracajú pravdivú alebo nepravdivú hodnotu priamo, nikdy reťazec "Y" / "N" ani ďalšie porovnanie.

xu-bind je jediná výnimka

Všade inde sa pole označuje pomocou @. xu-bind namiesto toho berie holé id poľa: xu-bind="search_v", nikdy xu-bind="@search_v".

Atribúty xu

Rodiny s predponou

Rodiny atribútov, ktoré berú príponu. Hodnoty xu-on sú vždy polia objektov handlerov; hodnoty xu-exp sú vždy reťazce výrazov.

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" } }
  ]
}]

Hodnota atribútu xu-on:* je vždy pole objektov handlerov a každý workflow je pole krokov akcií (úplná referencia akcií je nižšie, v časti Logické proggy a pracovné postupy). props.condition kroku ho podmieňuje; props.async: true ho spustí bez čakania.

Kľúčová sémantika

  • xu-exp:class nahrádza statický atribút class, nepridáva k nemu. Pri elemente, ktorý nesie oboje, sa statický ignoruje, takže triedy rozloženia patria aj do výrazu: xu-exp:class="'card p-4 ' + (@active_v ? 'ring' : '')".
  • xu-script berie holý výraz function (el) { ... }, vykonaný cez eval a zavolaný s elementom DOM, keď sa uzol stane viditeľným. Chráňte sa pred opakovaným spustením (if (el.__bound) return; el.__bound = true;) a každý dotaz obmedzte na el, nikdy nie na document.
  • xu-style má automatický rozsah: každý selektor má predponu [xu-ui-id] uzla, takže obyčajné selektory elementov a tried zostávajú lokálne a nikdy neuniknú.
  • Hodnoty xu-script ani xu-style nesmú obsahovať úvodzovku (' ani "), plátno návrhára serializuje atribúty bez escapovania a jedna úvodzovka komponent poškodí. Techniky bez úvodzoviek sú v časti Programy JavaScript nižšie.
  • Statický text patrí do vlastnosti content elementu. xu-exp:xu-content je len pre dynamický text.

Tagy

Tagy na tvorbu okrem obyčajného HTML: xu-template, xu-single-view, xu-multi-view, xu-panel, xu-teleport, xu-slot.

  • xu-single-view vymedzuje jeden záznam (koreň formulára, použiteľný aj vnorený).
  • xu-multi-view zopakuje svoje deti raz pre každý riadok viazaných dát.
  • xu-panel vloží iný prog (atribút program plus vstupy xu-exp:<param>). Okrem výrazov parametrov patria naň iba štandardné atribúty HTML (class, id, style, title, hidden, slot, name, role, tabindex).
  • xu-teleport vykreslí svoje deti na inom cieli DOM (to alebo xu-exp:to).
  • Názov tagu s veľkým začiatočným písmenom (Button, Card) je skompilovaný komponent, nie element HTML, pozrite si Vkladanie nižšie.

Komponenty

Komponent (menuType: "component") je jednotka UI: strom elementov (progUi) viazaný na lokálny stav (progFields), voliteľné dáta (progDataSource), logiku životného cyklu (progEvents) a rozhranie vstupu a výstupu (properties.progParams).

Vlastnosti

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 je form pre jeden záznam (koreňový element xu-single-view) alebo grid / list pre jeden opakovaný na každý riadok dát (koreňový element xu-multi-view).
  • rwMode je R pre čítanie alebo U pre úpravu; allowCreate hovorí, či sa môže vložiť nový riadok, keď žiadny nezodpovedá.
  • Konvencia pomenovania progParams: parametre končia _in / _out, virtuálne polia lokálne pre komponent končia _v.
  • uiFramework preberá to, čo už používajú existujúce komponenty projektu. Existujúci projekt, ktorý ho vynecháva, by ho mal naďalej vynechávať, nastavenie pluginu frameworku, ktorý drive projektu skutočne neposkytuje, zablokuje živý náhľad na prázdnej obrazovke.

Strom elementov (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" } }
      ] }
  ]
}

Uzol root z továrne zostáva; zostava pracuje v jeho children. Každý uzol potrebuje jedinečné id (nové uzly používajú ui-<uuid>), type: "element" a tagName, žiadne typy uzlov comment ani text, statický text žije namiesto toho v content. Každý uzol potrebuje attributes: {} a children: [], aj keď sú prázdne, serializátor plátna návrhára pristupuje k obom na každom uzle a vynechanie pokazí vlastný náhľad komponentu.

Vkladanie: xu-panel alebo skompilovaný komponent

Obe sa pripájajú transparentne, bez obaľovacieho elementu, a oboje rozhoduje jeden signál: či tagName začína veľkým písmenom.

  • xu-panel, tagName malými písmenami plus atribút program, vkladá iný prog, dieťa viazané na databázu alebo so stavom, s vlastnými poľami a udalosťami. program je id dieťaťa (alebo xu-exp:prog pre dynamické), hodnoty sa dostanú k jeho parametrom _in cez xu-exp:<param>.
  • Tag s veľkým písmenom plus atribút library pripojí skompilovaný komponent, primitívum dizajnového systému alebo časť, ktorú aplikácia sama skompilovala. Každý obyčajný atribút sa stane propom (props.<name>), nikdy atribútom DOM, pretože komponent nevykresľuje žiadny vlastný element. Uzol komponentu nemá výstupné parametre, na rozdiel od xu-panel nič nezapisuje hodnotu späť do vašich polí.
Rozhoduje samotné veľké písmeno

Preklepnuté <Buton> sa stále berie ako tag komponentu, nikdy sa nevráti k neznámemu elementu HTML a pri pripojení vyhodí chybu s názvom tagu, knižnicou a každým vyskúšaným zdrojom. validate_prog dnes tagy komponentov ani hodnoty library nekontroluje, jedinou kontrolou je živý náhľad.

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 je virtual pre lokálny stav, table pre stĺpec viazaného zdroja dát alebo expression / datasource. workflow poľa sa spustí pri zmene. Predvolená hodnota nastavuje props.fieldValue; vypočítané pole nastavuje props.fieldComputed: true plus propExpressions.fieldValue.

progDataSource

Jeden záznam podľa kľúča (formulár): dataSourceFilterModelType: "index" s dataSourceIndexId, ktoré existuje v tableIndexes samotnej tabuľky. Filtrovaný zoznam (grid alebo list): dataSourceFilterModelType: "query" s filterModelMongoFx, reťazcom výrazu v štýle Mongo. dataSourceType je table, array, json, csv, none alebo prázdne pre čisto prezentačný komponent bez zdroja dát vôbec.

progEvents a tri hooky životného cyklu

Typy udalostí: on_load, on_exit, before_record, after_record, record_not_found, locate_not_found, screen_ready, on_refresh, on_unload, client_interval, user_defined. Udalosti user_defined sa spúšťajú odkiaľkoľvek akciou raise_event; screen_ready je obvyklý hook pripojenia.

Tri vstavané hooky komponentu si rozdeľujú prácu, použitie nesprávneho je častým zdrojom chýb:

screen_ready

Spustí sa raz na inštanciu. Tu vytvárajte DOM a widgety.

on_refresh

Spustí sa po každom načítaní, vrátane prvého, hneď po screen_ready. Tu odovzdávajte nové dáta widgetom, ktoré už existujú. Ak by ste prácu pri obnove dali do screen_ready, vytvárací kód by sa znova spustil nad DOM, ktorý stále existuje, a naskladal by druhý widget.

on_unload

Spustí sa, keď sa inštancia zruší. Zničte, čo prog vytvoril, widgety, časovače, poslucháčov document / window, pozorovateľov. Engine vie uvoľniť len to, čo vytvoril, poslucháč pripojený na document inak panel prežije.

Vzory

  • Stavy načítania a prázdne stavy: dajte xu-ref="myref" na element viazaný na dáta a potom podmieňte elementy skeletonu alebo prázdneho stavu pomocou xu-render nad (@SYS_GLOBAL_OBJ_REFS).myref, jeho množina dát sa pripojí, keď dáta dorazia.
  • Modálne okná: vytvorte dialóg ako samostatný komponent a otvorte ho akciou call_modal.
  • Uloženie alebo zmazanie viazaného riadku: invoke_action s act_save / act_delete alebo vyhradený prog set_data pre všetko nad rámec aktuálneho riadku.

Logické proggy a pracovné postupy

Typy logických progov zdieľajú dátový aparát komponentu (progDataSource, progFields, progEvents, properties.progParams) bez akéhokoľvek UI:

Parametre

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": {} }
]

Volajúci odovzdáva hodnoty cez name.parameters akcie, { "order_id_in": { "value": "", "fx": "@selected_id_v" } }, value pre statickú hodnotu, fx pre výraz. Kontrola overí, že cieľový program existuje a jeho menuType zodpovedá akcii.

Akcie pracovného postupu

Pracovný postup je pole krokov, { "id": "...", "data": { "action": "...", "name": { ... }, "enabled": true }, "props": {} }, vykonávaných v poradí. props.condition krok podmieňuje, props.async: true ho spustí bez čakania. Pracovné postupy sa objavujú v handleroch xu-on:*, progEvents[].workflow a vo vlastnom workflow poľa.

invoke_action akceptuje act_next, act_prev, act_first, act_last, act_reload, act_refresh, act_print, act_save, act_delete (iba v kontexte komponentu).

Zastarané akcie, ktoré kontrola odmieta

alter_ui_element, create_ui_element, info_ui_element, remove_ui_element, empty_ui_element, cache_ui_element, load_ui_element. Namiesto imperatívnej akcie nad elementom riaďte UI cez polia a xu-exp / xu-render.

call_ai_agent a call_triage_agent nie sú skutočné akcie

Vlastný výber akcií Studia ponúka Zavolať AI agenta a Zavolať triážneho agenta vedľa akcií vyššie. Ani jedna nie je v tejto tabuľke, pretože ani jedna nie je skutočná: validate_prog pre ne nemá žiadny prípad a hlási invalid trigger type a ani runtime engine pracovných postupov pre ne nemá handler, takže uložený krok sa nikdy nespustí, ani keď chybu ignorujete. Ak má jeden prog siahnuť na zverejneného agenta, pridajte namiesto toho nástroj AI agent do zoznamu nástrojov iného agenta (agentConfig.agent_tools dokumentu menuType: "ai_agent"), nie krok pracovného postupu na komponente, get_data ani žiadnom inom type progu.

name.value akcie update priraďuje polia pomocou párov @field: expression oddelených bodkočiarkou alebo objektom JSON5, "@saving_v: true; @status_v: 'sent'". Volanie iného programu ho pomenúva pod name.prog a akcia musí zodpovedať typu samotného programu (get_data potrebuje prog get_data, call_native_javascript prog javascript a tak ďalej).

call_library volá metódu nainštalovaného pluginu: name.plugin_name musí byť zakúpený a nainštalovaný v aplikácii, inak kontrola krok odmietne, name.library_method jedna z metód, ktoré plugin exportuje, name.library_props jeho deklarované polia. Dva názvy propov sú konvenciou naprieč pluginmi, nie špecifické pre niektorý z nich: event_name_for_successful_callback vyvolá túto udalosť s odpoveďou metódy, field_id_to_return_result zapíše odpoveď priamo do tohto poľa, ani jedno nie je 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ý hook; before_record / after_record / record_not_found / locate_not_found sú životný cyklus dát, hlavne pre set_data a batch; client_interval je opakujúci sa časovač; user_defined sa spúšťa akciou raise_event.

Tabuľky

Prog tabuľky (menuType: "table") definuje databázovú tabuľku: jej stĺpce (tableFields), jej indexy (tableIndexes) a databázový plugin, ktorý ju ukladá (properties.databaseSocket). Rodič v strome: database alebo priečinok pod ním.

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 musí pomenovať databázový plugin nainštalovaný v projekte, @xuda.io/xuda-dbs-plugin-xuda je predvolená hodnota platformy; existujúca tabuľka v tom istom projekte je referenciou, ktorý socket znova použiť.
  • Vyžaduje sa aspoň jedno pole a aspoň jeden index.
  • field_id začína písmenom, potom písmená, číslice, podčiarkovník, pomlčka, dvojbodka alebo bodka a v rámci tabuľky zostáva jedinečné.
  • fieldType je string, number, boolean, array, object alebo date; mandatory: true ho robí povinným pri uložení.
  • Každý index potrebuje neprázdne name a keys a každý kľúč musí byť existujúce field_id.

Konvencia: stĺpce majú predponu trojpísmenového kódu tabuľky, tabuľka s názvom "ORD - Orders" dostane ORD_Id, ORD_Total, ORD_Status. Každej tabuľke dajte jedinečné pole <TBL>_Id s jedinečným indexom, viazanie komponentu na jeden záznam ho potrebuje.

Tabuľka sa používa tromi spôsobmi: progDataSource.dataSourceTableId komponentu alebo dotazu, prog get_data / set_data / batch pre prístup na úrovni riadkov z pracovných postupov, alebo xu.dbs_create / dbs_read / dbs_update / dbs_delete zo skriptu, čo je ďalej.

Programy JavaScript

Prog javascript (menuType: "javascript") drží skutočný zdroj JS v scriptData.value, kompilovaný pri uložení. save_prog spustí toto zostavenie a vráti výsledok ako data.compile, { ok: true, dependencies } alebo { ok: false, error }. Zlyhaná kompilácia dokument stále uloží, takže zostava prečíta compile.ok a opraví to skôr, než pôjde ďalej.

Zmluva o vykonávaní

Zdroj sa píše ako obyčajné asynchrónne telo, bez export, bez obalu. Za behu sa vykoná ako:

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

params sú už vyhodnotené vstupy volajúceho; xu je API runtime nižšie; návratová hodnota je voliteľná, idiomatický spôsob, ako vrátiť výsledky, je xu.set_field_value na poliach volajúceho komponentu. Úvodzovky tu nevadia, na rozdiel od hodnoty atribútu xu-script.

API 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`);

Metódy dbs_* berú vlastné _id progu tabuľky, nikdy nie názov. Selektory sú objekty v štýle Mongo nad id polí, {} vráti všetko (predvolený limit 999). Projekcia fields je voliteľná, [] vráti každé pole a zoznam id polí vráti iba tie.

Odovzdávanie dát: polia, nie parametre

call_native_javascript nevyhodnocuje obaly parametrov {value, fx}, name.parameters sa k skriptu dostane surové. Spoľahlivá zmluva: komponent najprv vloží dáta do poľa (krok update alebo vstup xu-bind), pracovný postup zavolá prog s prázdnymi parameters: {} a skript ich prečíta cez xu.get_field_value a ohlási späť cez xu.set_field_value. Pri volaní z iného skriptu naopak xu.call_javascript(prog_id, {...}) odovzdáva parametre priamo.

Zvláštnosti živého náhľadu

  • Zápisy dát sa dostanú do skutočnej databázy, ale xu.dbs_read číta lokálne úložisko konceptu, ktoré nemusí obsahovať čerstvé riadky zo servera, čítanie hneď po zápise sa môže v náhľade vrátiť prázdne, hoci zápis pristál (viditeľné na karte Dáta tabuľky v Studiu). Nasadené aplikácie čítajú a zapisujú do toho istého úložiska.
  • Skompilované skripty sa vo vývojových náhľadoch silno kešujú, bežiaci náhľad môže naďalej vykonávať predchádzajúci skript aj po opätovnom načítaní po uložení, ktoré ho znova skompiluje. Vyčistí to tvrdé obnovenie prehliadača.
  • xu.alert so zobrazením modal, toast alebo browser sa môže v náhľade objaviť ako natívny, blokujúci alert(). Bezpečnejší spôsob, ako ohlásiť výsledok, je xu.set_field_value do poľa stavu.

Prog javascript oproti atribútu xu-script

Techniky bez úvodzoviek pre xu-script / xu-style

Plátno návrhára serializuje hodnoty atribútov bez escapovania, takže jedna úvodzovka poškodí značkovanie komponentu. Šablónové literály sa úvodzovkám reťazcov úplne vyhnú (el.textContent = `Ready`); samotný znak ", napríklad pri skladaní CSV, pochádza z String.fromCharCode(34); selektory atribútov CSS sú platné aj bez úvodzoviek (el.querySelector(`[data-role=import-btn]`)); a stráž proti opakovanému spusteniu, if (el.__bound) return; el.__bound = true;, bráni skriptu dvojito sa previazať pri opätovnom vykreslení.

Pasce

Každý záznam nižšie sa niekedy pokazil v skutočnom zostavení. validate_prog zachytí väčšinu z nich, spustite ho pred každým uložením.

Mechanika API

  • Každá odpoveď je { code, data }, code < 0 je chyba.
  • create_prog vráti nový dokument pod data.prog, uloženie celej odpovede namiesto toho uloží chybne utvorený dokument s properties zahrabanými pod prog.
  • save_prog nahradí celý dokument. Začnite z aktuálneho dokumentu, nikdy nie z ručne zloženej kostry; -409 znamená, že sa od posledného čítania zmenil, znova načítajte, znova použite zmeny, skúste znova.
  • Cez MCP sa prog_json a properties_json odovzdávajú ako reťazce, vrstva schémy nástroja z parametra objektu odstráni neznáme kľúče a môže ticho zahodiť celé sekcie.
  • delete_prog je mäkké zmazanie, nastaví stat: 4. Uzol global_<app_id> sa nedá zmazať.

Obsah dokumentu

  • Žiadne ' ani " vo vnútri hodnôt xu-script alebo xu-style.
  • Kľúče s predponou $ ($folded, $childrenClass, $nodeBackClass), plus path, code, editCode, sú stav zobrazenia návrhára a do uloženého uzla progUi nikdy nepatria.
  • Žiadne typy uzlov comment ani text, iba elementy, statický text v content.
  • Každý uzol elementu potrebuje attributes: {} a children: [], aj keď sú prázdne.
  • xu-exp:class nahrádza statickú class, každá potrebná trieda patrí do výrazu.
  • xu-bind je holé id poľa, bez @, všade inde polia používajú @.
  • Niečo robia iba zdokumentované atribúty xu-*, vymyslený sa ticho ignoruje a validate_prog varuje.
  • Koreňom stromu progu ai_agent je ai_agents, uložte ho s studio_meta.parentId: "ai_agents" (alebo id priečinka pod ním), ak kontrola označí parentId.

Runtime a vykresľovanie

  • tagName s veľkým písmenom sa vždy berie ako komponent, aj preklep, a pri pripojení vyhodí chybu s názvom tagu, library a každým vyskúšaným zdrojom, neexistuje ticho "nevykreslí sa", aké má xu-panel bez vybraného programu.
  • validate_prog nekontroluje tagy komponentov ani hodnoty library, nesprávne napísaný zachytí iba živý náhľad.
  • Žiadne pomocné CSS (Tailwind ani iné) za behu, pokiaľ ho plugin uiFramework projektu skutočne neposkytuje, triedy ako p-4 inak ticho nič nerobia. Samostatné štýlovanie je xu-style s automatickým rozsahom [xu-ui-id].
  • xu-script beží raz pri viditeľnosti elementu a môže sa pri opätovnom vykreslení spustiť znova, chráňte sa pomocou el.__bound a dotazy obmedzte na el.

Dáta a skripty

  • Parametre call_native_javascript sa nevyhodnocujú, dáta odovzdávajte radšej cez polia (pozrite si Odovzdávanie dát vyššie).
  • Riadky dbs_read sú {id, value}, polia žijú pod .value, id riadku na .id. Neodovzdávajte projekciu fields, pokazí čítanie na strane servera.
  • Vnútri xu-for obaľte iterátor zátvorkami, (@_FOR_VAL).CNT_Name sa vyhodnotí, @_FOR_VAL.CNT_Name ticho zlyhá a vykreslí namiesto toho dosadený zdrojový text.
  • Zápisy z náhľadu pristanú v skutočnej databáze; čítania z náhľadu pochádzajú z lokálneho úložiska konceptu, ktoré môže hneď po zápise vyzerať prázdne.
  • V náhľadoch uprednostnite pole stavu pred modálnym alebo toastovým zobrazením xu.alert, môže sa vykresliť ako natívny, blokujúci alert().

Overenie vašej práce

Po uložení znova načítajte cez get_prog a porovnajte, čo sa očakávalo. Pri práci na UI otvorte komponent v Studiu a stlačte tlačidlo prehrávania náhľadu alebo URL živého náhľadu projektu, ak je k dispozícii. Pri progu javascript skontrolujte data.compile.ok pri každom uložení. Opravte každú chybu validate_prog; jeho varovania, úvodzovky, kľúče $, neznáme atribúty, berte ako veci na okamžitú opravu, nie ako šum.