Przejdź do treści
Zweryfikowano

Przewodnik LLM po Studio

Model dokumentu progu, dokumentacja atrybutów xu-* i reguły przepływu pracy, których agent AI uczy się przed pierwszym wywołaniem narzędzia.

Każdy projekt Studio, każda tabela, ekran, skrypt i trasa w nim, to jeden dokument JSON CouchDB zwany progiem (docType: "studio"). Ta strona to ta sama dokumentacja, którą dostaje agent AI budujący prog, przepisana jako dokumentacja: kształt tego dokumentu, atrybuty, które napędzają jego UI, akcje, które może wykonać przepływ pracy, i błędy, które pojawiają się w prawdziwych budowach.

Jak agent AI dostaje ten przewodnik

Połącz klienta MCP z Xuda, a pierwsza odpowiedź, wywołanie initialize, niesie ten przewodnik jako instructions sesji, scalony na świeżo z własnych żywych reguł platformy, więc nigdy nie opisze czegoś, czego wdrożony checker już nie egzekwuje. Zobacz Łączenie klienta AI przez MCP.

Z wnętrza sesji dwie metody sięgają tego samego materiału bezpośrednio, przez MCP lub zwykłe REST, i nie wymagają niczego poza zwykłym kluczem API:

Zalecana kolejność: przeczytaj temat pasujący do tego, co budujesz, pobierz pasujący przykład, utwórz prog przez fabrykę (create_prog), buduj wewnątrz jego sekcji zawartości, zwaliduj (validate_prog) i napraw wszystko, co zgłosi, zapisz (save_prog), a potem pobierz ponownie, by sprawdzić. Zapis, który zwraca -409, oznacza, że dokument zmienił się od odczytu: pobierz ponownie, nałóż zmiany ponownie, spróbuj jeszcze raz.

Model dokumentu progu

Koperta

Te pola należą do kodu serwera i fabryki; tworzona budowa edytuje zawsze tylko sekcje zawartości 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 ma postać <ostatnie 3 znaki app_id>_<3-literowy skrót typu>_<12 znaków hex>, na przykład 392_cmp_... dla komponentu, 392_tbl_... dla tabeli, 392_jvs_... dla progu javascript, 392_gtd_... / 392_std_... dla get_data / set_data, 392_fld_... dla folderu. Identyfikatory generuje fabryka, budowa nigdy ich nie wymyśla.
  • stat to 3 dla aktywnego, 4 dla miękko usuniętego (to ustawia usunięcie progu). Drzewo Studio pokazuje tylko stat: 3.
  • properties.menuType to jedno z globals, table, get_data, set_data, batch, alert, javascript, folder, route, api, component, ai_agent.
  • studio_meta.parentId umieszcza węzeł w drzewie Studio: albo identyfikator innego progu (zwykle folderu), albo jeden z korzeni typów: programs (logika i komponenty), database (tabele), routes, globals, ai_agents. Nierozpoznany parentId zostawia węzeł niewidocznym w drzewie i jest błędem checkera.

Sekcje zawartości według menuType

Dokument globals

Każdy projekt ma dokładnie jeden dokument global_<app_id> (menuType: "globals"). Jego progFields są czytelne z każdego innego progu jako @field_id. Dwa globale systemowe są w każdym projekcie: @SYS_GLOBAL_OBJ_LOGIN_USER_INFO dla zalogowanego użytkownika i @SYS_GLOBAL_OBJ_REFS dla elementów zarejestrowanych przez xu-ref. Ani dokumentu globals, ani korzenia drzewa nie można usunąć.

Struktury obowiązkowe

  • properties, properties.menuType, properties.menuName, studio_meta i studio_meta.parentId są obowiązkowe w każdym dokumencie.
  • Wpis progFields potrzebuje unikalnego id, data.field_id, data.type równego virtual, table, expression lub datasource oraz props.fieldType równego string, number, boolean, array lub object.
  • Zarezerwowane nazwy zmiennych środowiska, _NULL, _THIS, _FOR_KEY, _FOR_VAL, _ROWNO, _ROWID, _ROWDOC, _KEY, _VAL, nigdy nie są redefiniowane jako identyfikatory pól.
  • Zduplikowane identyfikatory, nieznane menuType i źle sformowane sekcje to twarde błędy, które validate_prog zgłasza bezpośrednio.

Wyrażenia i atrybuty xu-*

Składnia wyrażeń

Wyrażenia działają na własnym zbiorze danych progu. Każde pole, lokalne, związane z tabelą, globalne lub parametr, jest przywoływane przez @: @search_v, @ORD_Total, @SYS_GLOBAL_OBJ_LOGIN_USER_INFO, a wokół zwykły JavaScript, @count_v > 0 ? 'has rows' : 'empty'. Literał obiektu wymaga nawiasów okalających, ({ ORD_Status: @status_v }). Wewnątrz pętli xu-for bieżący element to @_FOR_VAL, a jego klucz lub indeks @_FOR_KEY (można zmienić nazwy przez xu-for-key / xu-for-val). xu-render i inne warunki zwracają wartość prawdziwą lub fałszywą bezpośrednio, nigdy ciąg "Y" / "N" ani dodatkowe porównanie.

xu-bind to jedyny wyjątek

Wszędzie indziej pole przywołuje się przez @. xu-bind bierze zamiast tego sam identyfikator pola: xu-bind="search_v", nigdy xu-bind="@search_v".

Atrybuty xu

Rodziny z przedrostkiem

Rodziny atrybutów, które przyjmują przyrostek. Wartości xu-on to zawsze tablice obiektów obsługi; wartości xu-exp to zawsze ciągi wyrażeń.

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

Wartość atrybutu xu-on:* jest zawsze tablicą obiektów obsługi, a każdy workflow to tablica kroków akcji (pełna dokumentacja akcji jest niżej, w sekcji Programy logiki i przepływy pracy). props.condition kroku go bramkuje; props.async: true odpala go bez czekania.

Krytyczna semantyka

  • xu-exp:class zastępuje statyczny atrybut class, a nie dodaje do niego. Element z obydwoma ma statyczny zignorowany, więc klasy układu należą też do wyrażenia: xu-exp:class="'card p-4 ' + (@active_v ? 'ring' : '')".
  • xu-script bierze samo wyrażenie function (el) { ... }, wykonywane przez eval i wywoływane z elementem DOM, gdy węzeł stanie się widoczny. Zabezpiecz przed ponownym uruchomieniem (if (el.__bound) return; el.__bound = true;) i ogranicz każde zapytanie do el, nigdy do document.
  • xu-style ma automatyczny zakres: każdy selektor jest poprzedzany [xu-ui-id] węzła, więc zwykłe selektory elementów i klas pozostają lokalne i nigdy nie wyciekają.
  • Wartości xu-script ani xu-style nie mogą zawierać cudzysłowu (' lub "), kanwa projektanta serializuje atrybuty bez ucieczki, a jeden cudzysłów psuje komponent. Sekcja Programy JavaScript niżej opisuje techniki bez cudzysłowów.
  • Tekst statyczny należy do właściwości content elementu. xu-exp:xu-content służy tylko do tekstu dynamicznego.

Tagi

Tagi tworzenia poza zwykłym HTML: xu-template, xu-single-view, xu-multi-view, xu-panel, xu-teleport, xu-slot.

  • xu-single-view wyznacza zakres pojedynczego rekordu (korzeń formularza, może też być zagnieżdżony).
  • xu-multi-view powtarza swoje dzieci raz na wiersz związanych danych.
  • xu-panel osadza inny prog (atrybut program plus wejścia xu-exp:<param>). Poza wyrażeniami parametrów mogą na nim być tylko standardowe atrybuty HTML (class, id, style, title, hidden, slot, name, role, tabindex).
  • xu-teleport renderuje swoje dzieci w innym celu DOM (to lub xu-exp:to).
  • Tag z wielką literą (Button, Card) to skompilowany komponent, a nie element HTML, zobacz Osadzanie niżej.

Komponenty

Komponent (menuType: "component") to jednostka UI: drzewo elementów (progUi) związane z lokalnym stanem (progFields), opcjonalnymi danymi (progDataSource), logiką cyklu życia (progEvents) i interfejsem wejścia/wyjścia (properties.progParams).

Właściwości

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 to form dla pojedynczego rekordu (element główny xu-single-view) albo grid / list dla powtarzanego na każdy wiersz danych (element główny xu-multi-view).
  • rwMode to R dla odczytu lub U dla aktualizacji; allowCreate mówi, czy można wstawić nowy wiersz, gdy żaden nie pasuje.
  • Konwencja nazewnictwa progParams: parametry kończą się na _in / _out, lokalne pola wirtualne komponentu kończą się na _v.
  • uiFramework odzwierciedla to, czego już używają istniejące komponenty projektu. Istniejący projekt, który go pomija, powinien dalej go pomijać; ustawienie wtyczki frameworku, której dysk projektu faktycznie nie serwuje, zawiesza podgląd na żywo na pustym ekranie.

Drzewo elementów (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" } }
      ] }
  ]
}

Korzeń root z fabryki zostaje; budowa pracuje wewnątrz jego children. Każdy węzeł potrzebuje unikalnego identyfikatora (nowe węzły używają ui-<uuid>), type: "element" i tagName, bez typów węzłów comment ani text, tekst statyczny żyje zamiast tego w content. Każdy węzeł potrzebuje attributes: {} i children: [], nawet gdy są puste, serializator kanwy projektanta dereferuje oba na każdym węźle, a pominięcie psuje podgląd samego komponentu.

Osadzanie: xu-panel albo skompilowany komponent

Oba montują się przezroczyście, bez elementu opakowującego, i oba są rozstrzygane jednym sygnałem: czy tagName zaczyna się wielką literą.

  • xu-panel, tagName małymi literami plus atrybut program, osadza inny prog, związane z bazą lub stanowe dziecko z własnymi polami i zdarzeniami. program to identyfikator dziecka (lub xu-exp:prog dla dynamicznego), wartości trafiają do jego parametrów _in przez xu-exp:<param>.
  • Tag z wielką literą plus atrybut library montuje skompilowany komponent, element systemu projektowego lub część skompilowaną przez samą aplikację. Każdy zwykły atrybut staje się propem (props.<name>), nigdy atrybutem DOM, ponieważ komponent nie renderuje własnego elementu. Węzeł komponentu nie ma parametrów wyjściowych, w przeciwieństwie do xu-panel nic nie zapisuje wartości z powrotem do Twoich pól.
Decyduje sama wielka litera

Literówka <Buton> nadal jest traktowana jako tag komponentu, nigdy nie wraca do nieznanego elementu HTML i rzuca błąd przy montowaniu, nazywając tag, bibliotekę i każde wypróbowane źródło. validate_prog dziś nie sprawdza tagów komponentów ani wartości library, jedynym sprawdzeniem jest podgląd na żywo.

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 to virtual dla stanu lokalnego, table dla kolumny związanego źródła danych albo expression / datasource. workflow pola uruchamia się przy zmianie. Wartość domyślną ustawia props.fieldValue; pole obliczane ustawia props.fieldComputed: true plus propExpressions.fieldValue.

progDataSource

Pojedynczy rekord po kluczu (formularz): dataSourceFilterModelType: "index" z dataSourceIndexId, który istnieje w własnych tableIndexes tabeli. Przefiltrowana lista (grid lub list): dataSourceFilterModelType: "query" z filterModelMongoFx, ciągiem wyrażenia w stylu Mongo. dataSourceType to table, array, json, csv, none lub puste dla czysto prezentacyjnego komponentu bez żadnego źródła danych.

progEvents i trzy haki cyklu życia

Typy zdarzeń: on_load, on_exit, before_record, after_record, record_not_found, locate_not_found, screen_ready, on_refresh, on_unload, client_interval, user_defined. Zdarzenia user_defined odpalają się skądkolwiek akcją raise_event; screen_ready to zwykły hak montowania.

Trzy wbudowane haki komponentu dzielą pracę, a użycie niewłaściwego to częste źródło błędów:

screen_ready

Odpala się raz na instancję. Tu twórz DOM i widżety.

on_refresh

Odpala się po każdym załadowaniu, także pierwszym, zaraz po screen_ready. Tu przekazuj nowe dane widżetom, które już istnieją. Umieszczenie pracy odświeżania w screen_ready uruchamia kod tworzenia ponownie na DOM, który nadal istnieje, i układa drugi widżet na pierwszym.

on_unload

Odpala się, gdy instancja jest rozbierana. Zniszcz to, co utworzył prog: widżety, timery, nasłuchiwacze document / window, obserwatory. Silnik może zwolnić tylko to, co sam utworzył; nasłuchiwacz podpięty do document inaczej przeżywa panel.

Wzorce

  • Stany ładowania i puste: dodaj xu-ref="myref" na elemencie związanym z danymi, a potem bramkuj elementy szkieletu lub puste przez xu-render na (@SYS_GLOBAL_OBJ_REFS).myref, jego zbiór danych dołącza się, gdy dane dotrą.
  • Okna modalne: zbuduj dialog jako osobny komponent, otwórz go akcją call_modal.
  • Zapis lub usunięcie związanego wiersza: invoke_action z act_save / act_delete albo dedykowany prog set_data dla wszystkiego poza bieżącym wierszem.

Programy logiki i przepływy pracy

Typy progów logiki dzielą z komponentem maszynerię danych (progDataSource, progFields, progEvents, properties.progParams) bez żadnego UI:

Parametry

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

Wywołujący przekazuje wartości przez name.parameters akcji, { "order_id_in": { "value": "", "fx": "@selected_id_v" } }, value dla wartości statycznej, fx dla wyrażenia. Checker sprawdza, czy program docelowy istnieje, a jego menuType pasuje do akcji.

Akcje przepływu pracy

Przepływ pracy to tablica kroków, { "id": "...", "data": { "action": "...", "name": { ... }, "enabled": true }, "props": {} }, wykonywanych po kolei. props.condition bramkuje krok, props.async: true odpala go bez czekania. Przepływy pojawiają się w obsłudze xu-on:*, progEvents[].workflow i własnym workflow pola.

invoke_action akceptuje act_next, act_prev, act_first, act_last, act_reload, act_refresh, act_print, act_save, act_delete (tylko w kontekście komponentu).

Przestarzałe akcje, które checker odrzuca

alter_ui_element, create_ui_element, info_ui_element, remove_ui_element, empty_ui_element, cache_ui_element, load_ui_element. Steruj UI przez pola i xu-exp / xu-render zamiast imperatywnej akcji na elemencie.

call_ai_agent i call_triage_agent to nie prawdziwe akcje

Własny wybór akcji w Studio oferuje Wywołaj agenta AI i Wywołaj agenta triażu obok akcji powyżej. Żadnej z nich nie ma w tej tabeli, bo żadna nie jest prawdziwą akcją: validate_prog nie ma dla nich przypadku i zgłasza invalid trigger type, a silnik przepływu pracy w środowisku też nie ma dla nich obsługi, więc zapisany krok nigdy się nie wykona, nawet jeśli zignorujesz błąd. Aby jeden prog dotarł do opublikowanego agenta, dodaj narzędzie Agent AI do listy narzędzi innego agenta (agentConfig.agent_tools dokumentu menuType: "ai_agent"), a nie krok przepływu pracy w komponencie, get_data ani żadnym innym typie progu.

name.value akcji update przypisuje pola parami @field: expression rozdzielonymi średnikami lub obiektem JSON5, "@saving_v: true; @status_v: 'sent'". Wywołanie innego programu nazywa go w name.prog, dopasowując akcję do typu własnego programu (get_data wymaga progu get_data, call_native_javascript progu javascript i tak dalej).

call_library wywołuje metodę zainstalowanej wtyczki: name.plugin_name musi być zakupiona i zainstalowana w aplikacji, inaczej checker odrzuca krok, name.library_method to jedna z metod eksportowanych przez wtyczkę, name.library_props to jej zadeklarowane pola. Dwie nazwy propów to konwencja między wtyczkami, a nie specyfika którejś z nich: event_name_for_successful_callback wywołuje to zdarzenie z odpowiedzią metody, field_id_to_return_result zapisuje odpowiedź bezpośrednio do tego pola, żadna nie jest wymagana.

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 to zwykły hak inicjalizacji; before_record / after_record / record_not_found / locate_not_found to cykl życia danych, szczególnie dla set_data i batch; client_interval to powtarzający się timer; user_defined odpala się z akcji raise_event.

Tabele

Prog tabeli (menuType: "table") definiuje tabelę bazy danych: jej kolumny (tableFields), indeksy (tableIndexes) i wtyczkę bazy danych, która ją przechowuje (properties.databaseSocket). Rodzic w drzewie: database lub folder pod nim.

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 musi nazywać wtyczkę bazy danych zainstalowaną w projekcie, @xuda.io/xuda-dbs-plugin-xuda to domyślna wtyczka platformy; istniejąca tabela w tym samym projekcie jest wzorcem, którego gniazda użyć ponownie.
  • Wymagane jest co najmniej jedno pole i co najmniej jeden indeks.
  • field_id zaczyna się od litery, potem litery, cyfry, podkreślenie, myślnik, dwukropek lub kropka, i pozostaje unikalny w tabeli.
  • fieldType to string, number, boolean, array, object lub date; mandatory: true czyni pole wymaganym przy zapisie.
  • Każdy indeks potrzebuje niepustych name i keys, a każdy klucz musi być istniejącym field_id.

Konwencja: poprzedzaj kolumny trzyliterowym kodem tabeli, tabela o nazwie „ORD - Orders” dostaje ORD_Id, ORD_Total, ORD_Status. Daj każdej tabeli unikalne pole <TBL>_Id z unikalnym indeksem na nim, wiązanie komponentu z pojedynczym rekordem go potrzebuje.

Tabela jest używana na trzy sposoby: przez progDataSource.dataSourceTableId komponentu lub zapytania, przez prog get_data / set_data / batch do dostępu na poziomie wierszy z przepływów pracy albo przez xu.dbs_create / dbs_read / dbs_update / dbs_delete ze skryptu, omówione dalej.

Programy JavaScript

Prog javascript (menuType: "javascript") trzyma prawdziwy kod źródłowy JS w scriptData.value, kompilowany przy zapisie. save_prog uruchamia tę kompilację i zwraca wynik jako data.compile, { ok: true, dependencies } lub { ok: false, error }. Nieudana kompilacja nadal zapisuje dokument, więc budowa czyta compile.ok i naprawia to, zanim pójdzie dalej.

Kontrakt wykonania

Źródło pisze się jako zwykłe ciało async, bez export, bez wrappera. W czasie działania wykonuje się jako:

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

params to już ewaluowane wejścia wywołującego; xu to API środowiska poniżej; zwracana wartość jest opcjonalna, idiomatyczny sposób zwrotu wyników to xu.set_field_value na polach wywołującego komponentu. Cudzysłowy są tu w porządku, w przeciwieństwie do wartości atrybutu xu-script.

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

Metody dbs_* biorą własny _id progu tabeli, nigdy nazwę. Selektory to obiekty w stylu Mongo na identyfikatorach pól, {} zwraca wszystko (domyślny limit 999). Projekcja fields jest opcjonalna, [] zwraca wszystkie pola, a lista identyfikatorów pól zwraca tylko te pola.

Przekazywanie danych: pola, nie parametry

call_native_javascript nie ewaluuje opakowań parametrów {value, fx}, name.parameters trafia do skryptu surowe. Niezawodny kontrakt: komponent najpierw umieszcza ładunek w polu (krok update lub wejście xu-bind), przepływ pracy wywołuje prog z pustymi parameters: {}, a skrypt czyta go przez xu.get_field_value i zwraca wynik przez xu.set_field_value. Przy wywołaniu z innego skryptu xu.call_javascript(prog_id, {...}) przekazuje parametry bezpośrednio.

Osobliwości podglądu na żywo

  • Zapisy danych trafiają do prawdziwej bazy, ale xu.dbs_read czyta lokalny magazyn roboczy, który może nie zawierać świeżych wierszy z serwera, odczyt zaraz po zapisie może wrócić pusty w podglądzie, mimo że zapis się udał (widać go w karcie Dane tabeli w Studio). Wdrożone aplikacje czytają i zapisują ten sam magazyn.
  • Skompilowane skrypty mocno się cache'ują w podglądach deweloperskich, działający podgląd może dalej wykonywać poprzedni skrypt nawet po przeładowaniach po zapisie, który kompiluje go ponownie. Twarde odświeżenie przeglądarki to czyści.
  • xu.alert z wyświetlaniem modal, toast lub browser może w podglądzie pojawić się jako natywny, blokujący alert(). Bezpieczniejszym sposobem zwrotu informacji jest xu.set_field_value do pola statusu.

prog javascript a atrybut xu-script

Techniki bez cudzysłowów dla xu-script / xu-style

Kanwa projektanta serializuje wartości atrybutów bez ucieczki, więc jeden cudzysłów psuje znaczniki komponentu. Literały szablonowe w ogóle unikają cudzysłowów łańcuchów (el.textContent = `Ready`); sam znak ", na przykład przy budowaniu CSV, pochodzi z String.fromCharCode(34); selektory atrybutów CSS są poprawne bez cudzysłowów (el.querySelector(`[data-role=import-btn]`)); a zabezpieczenie przed ponownym uruchomieniem, if (el.__bound) return; el.__bound = true;, chroni skrypt przed podwójnym powiązaniem przy ponownym renderowaniu.

Pułapki

Każdy poniższy wpis w pewnym momencie zepsuł prawdziwą budowę. validate_prog łapie większość z nich, uruchamiaj go przed każdym zapisem.

Mechanika API

  • Każda odpowiedź to { code, data }, code < 0 oznacza błąd.
  • create_prog zwraca nowy dokument pod data.prog, zapisanie całej odpowiedzi zamiast tego utrwala źle sformowany dokument z properties zakopanym pod prog.
  • save_prog zastępuje cały dokument. Zaczynaj od bieżącego dokumentu, nigdy od ręcznie złożonego szkieletu; -409 oznacza, że zmienił się od ostatniego odczytu, pobierz ponownie, nałóż zmiany ponownie, spróbuj jeszcze raz.
  • Przez MCP prog_json i properties_json są przekazywane jako ciągi, warstwa schematu narzędzi usuwa nieznane klucze z parametru obiektowego i może po cichu gubić całe sekcje.
  • delete_prog to miękkie usunięcie, ustawia stat: 4. Węzła global_<app_id> nie można usunąć.

Zawartość dokumentu

  • Żadnego ' ani " wewnątrz wartości xu-script lub xu-style.
  • Klucze z prefiksem $ ($folded, $childrenClass, $nodeBackClass) oraz path, code, editCode to stan widoku projektanta i nigdy nie należą do zapisanego węzła progUi.
  • Żadnych typów węzłów comment ani text, tylko elementy, tekst statyczny w content.
  • Każdy węzeł elementu potrzebuje attributes: {} i children: [], nawet gdy są puste.
  • xu-exp:class zastępuje statyczny class, każda potrzebna klasa należy do wyrażenia.
  • xu-bind to sam identyfikator pola, bez @, wszędzie indziej pola używają @.
  • Tylko udokumentowane atrybuty xu-* coś robią, wymyślony jest po cichu ignorowany, a validate_prog ostrzega.
  • Korzeniem drzewa progu ai_agent jest ai_agents, zapisz go z studio_meta.parentId: "ai_agents" (lub identyfikatorem folderu pod nim), jeśli checker flaguje parentId.

Środowisko i renderowanie

  • tagName z wielką literą jest zawsze traktowany jako komponent, nawet literówka, i rzuca błąd przy montowaniu, nazywając tag, library i każde wypróbowane źródło, nie ma cichego „nie renderuje się”, jak w xu-panel bez wybranego programu.
  • validate_prog nie sprawdza tagów komponentów ani wartości library, tylko podgląd na żywo wychwytuje błędnie napisane.
  • Żadnego użytkowego CSS (Tailwind ani innego) w czasie działania, chyba że wtyczka uiFramework projektu faktycznie go dostarcza, klasy takie jak p-4 inaczej po cichu nic nie robią. Samodzielne stylowanie to xu-style, automatycznie objęty zakresem [xu-ui-id].
  • xu-script uruchamia się raz na widoczność elementu i może odpalić ponownie przy ponownym renderowaniu, zabezpiecz przez el.__bound i ogranicz zapytania do el.

Dane i skrypty

  • Parametry call_native_javascript nie są ewaluowane, przekazuj dane przez pola (zobacz Przekazywanie danych wyżej).
  • Wiersze dbs_read to {id, value}, pola leżą pod .value, identyfikator wiersza pod .id. Nie podawaj projekcji fields, psuje odczyt po stronie serwera.
  • Wewnątrz xu-for ujmij iterator w nawiasy, (@_FOR_VAL).CNT_Name się ewaluuje, @_FOR_VAL.CNT_Name zawodzi po cichu i renderuje podstawiony tekst źródłowy.
  • Zapisy w podglądzie trafiają do prawdziwej bazy; odczyty w podglądzie pochodzą z lokalnego magazynu roboczego, który zaraz po zapisie może wyglądać na pusty.
  • W podglądach wolij pole statusu od wyświetlania modal lub toast w xu.alert, może się ono pojawić jako natywny, blokujący alert().

Weryfikacja pracy

Pobierz ponownie przez get_prog po zapisie i porównaj z oczekiwaniami. Dla pracy nad UI otwórz komponent w Studio i naciśnij przycisk odtwarzania podglądu albo adres podglądu na żywo projektu, gdy jest dostępny. Dla progu javascript sprawdzaj data.compile.ok przy każdym zapisie. Napraw każdy błąd validate_prog; jego ostrzeżenia, cudzysłowy, klucze $, nieznane atrybuty, traktuj jako rzeczy do naprawy od razu, a nie szum.