Ο οδηγός LLM του Studio
Το μοντέλο εγγράφων prog, η αναφορά attributes xu-*, και οι κανόνες ροής εργασίας που διδάσκονται σε έναν πράκτορα AI πριν από την πρώτη του κλήση εργαλείου.
Κάθε έργο Studio, και κάθε πίνακας, οθόνη, script και διαδρομή μέσα του, είναι ένα έγγραφο JSON του CouchDB
που ονομάζεται prog (docType: "studio"). Αυτή η σελίδα είναι η ίδια αναφορά που λαμβάνει ένας πράκτορας AI όταν
χτίζει ένα, ξαναγραμμένη ως τεκμηρίωση: το σχήμα αυτού του εγγράφου, τα attributes που καθοδηγούν
το UI του, οι ενέργειες που μπορεί να κάνει μια ροή εργασίας, και τα λάθη που εμφανίζονται σε πραγματικές κατασκευές.
Πώς παίρνει έναν οδηγό ένας πράκτορας AI
Συνδέστε έναν client MCP στο Xuda και η πρώτη απάντηση, η κλήση initialize, μεταφέρει αυτόν τον οδηγό ως τα
instructions της συνεδρίας, συγχωνευμένα φρέσκα από τους ζωντανούς κανόνες της ίδιας της πλατφόρμας ώστε να μην μπορεί ποτέ να
περιγράψει κάτι που ο αναπτυγμένος checker δεν επιβάλλει πια. Δείτε
Σύνδεση ενός client AI μέσω MCP.
Μέσα από μια συνεδρία, δύο μέθοδοι φτάνουν απευθείας στο ίδιο υλικό, μέσω MCP ή απλού REST, και δεν απαιτούν τίποτα πέρα από ένα κανονικό κλειδί API:
Η προβλεπόμενη σειρά: διαβάστε το θέμα που ταιριάζει με αυτό που χτίζετε, φέρτε ένα αντίστοιχο παράδειγμα,
δημιουργήστε το prog μέσω του factory (create_prog), χτίστε μέσα στις ενότητες περιεχομένου του, επικυρώστε
(validate_prog) και διορθώστε ό,τι αναφέρει, αποθηκεύστε (save_prog), και μετά ξαναφέρτε το για επαλήθευση. Μια
αποθήκευση που επιστρέφει -409 σημαίνει ότι το έγγραφο άλλαξε από τότε που διαβάστηκε: ξαναφέρτε, εφαρμόστε ξανά, δοκιμάστε ξανά.
Το μοντέλο εγγράφου prog
Το περίβλημα
Ο κώδικας του διακομιστή και του factory κατέχει αυτά τα πεδία· μια συγγραφική κατασκευή επεξεργάζεται μόνο τις ενότητες περιεχομένου από κάτω τους.
- Το
_idακολουθεί το<last 3 chars of app_id>_<3-letter type abbreviation>_<12 hex>, για παράδειγμα392_cmp_...για ένα στοιχείο,392_tbl_...για έναν πίνακα,392_jvs_...για ένα prog javascript,392_gtd_.../392_std_...για get_data / set_data,392_fld_...για έναν φάκελο. Το factory παράγει τα ids, μια κατασκευή δεν επινοεί ποτέ κάποιο. - Το
statείναι 3 για ενεργό, 4 για διαγραμμένο με μαλακή διαγραφή (αυτό που ορίζει η διαγραφή ενός prog). Το δέντρο του Studio δείχνει μόνοstat: 3. - Το
properties.menuTypeείναι ένα απόglobals,table,get_data,set_data,batch,alert,javascript,folder,route,api,component,ai_agent. - Το
studio_meta.parentIdτοποθετεί τον κόμβο στο δέντρο του Studio: είτε το id ενός άλλου prog (συνήθως ένας φάκελος) είτε μία από τις ρίζες τύπων,programs(λογική και στοιχεία),database(πίνακες),routes,globals,ai_agents. Ένα μη αναγνωρισμένοparentIdαφήνει τον κόμβο αόρατο στο δέντρο και είναι σφάλμα του checker.
Ενότητες περιεχομένου ανά menuType
Το έγγραφο globals
Κάθε έργο έχει ακριβώς ένα έγγραφο global_<app_id> (menuType: "globals"). Τα progFields του
διαβάζονται από κάθε άλλο prog ως @field_id. Δύο καθολικά συστήματος διατίθενται σε κάθε έργο:
@SYS_GLOBAL_OBJ_LOGIN_USER_INFO για τον συνδεδεμένο χρήστη, και @SYS_GLOBAL_OBJ_REFS για τα στοιχεία
που καταχωρίζονται με xu-ref. Ούτε το έγγραφο globals ούτε η ρίζα του δέντρου μπορούν να διαγραφούν.
Δομικά υποχρεωτικά
- Τα
properties,properties.menuType,properties.menuName,studio_metaκαιstudio_meta.parentIdείναι υποχρεωτικά σε κάθε έγγραφο. - Μια καταχώριση
progFieldsχρειάζεται ένα μοναδικόid,data.field_id, έναdata.typeαπόvirtual,table,expressionήdatasource, και έναprops.fieldTypeαπόstring,number,boolean,arrayήobject. - Τα δεσμευμένα ονόματα μεταβλητών εκτέλεσης,
_NULL,_THIS,_FOR_KEY,_FOR_VAL,_ROWNO,_ROWID,_ROWDOC,_KEY,_VAL, δεν επαναορίζονται ποτέ ως ids πεδίων. - Τα διπλά ids, τα άγνωστα
menuTypeκαι οι κακοσχηματισμένες ενότητες είναι όλα σοβαρά σφάλματα που αναφέρει απευθείας τοvalidate_prog.
Εκφράσεις και attributes xu-*
Σύνταξη εκφράσεων
Οι εκφράσεις εκτελούνται πάνω στο δικό του σύνολο δεδομένων του prog. Κάθε πεδίο, τοπικό, δεμένο σε πίνακα, καθολικό ή
παράμετρος, αναφέρεται με @: @search_v, @ORD_Total, @SYS_GLOBAL_OBJ_LOGIN_USER_INFO,
απλό JavaScript γύρω του, @count_v > 0 ? 'has rows' : 'empty'. Ένα literal αντικειμένου χρειάζεται παρενθέσεις περιτύλιξης,
({ ORD_Status: @status_v }). Μέσα σε έναν βρόχο xu-for, το τρέχον στοιχείο είναι @_FOR_VAL και
το κλειδί ή ο δείκτης του @_FOR_KEY (μετονομάζονται με xu-for-key / xu-for-val). Το xu-render και άλλες
συνθήκες επιστρέφουν απευθείας την αληθή ή ψευδή τιμή, ποτέ συμβολοσειρά "Y" / "N" ή επιπλέον σύγκριση.
Παντού αλλού ένα πεδίο αναφέρεται με @. Το xu-bind παίρνει το γυμνό αναγνωριστικό πεδίου:
xu-bind="search_v", ποτέ xu-bind="@search_v".
Τα attributes xu
Οικογένειες προθεμάτων
Οικογένειες attributes που παίρνουν επίθημα. Οι τιμές xu-on είναι πάντα πίνακες αντικειμένων handler·
οι τιμές xu-exp είναι πάντα συμβολοσειρές εκφράσεων.
Η τιμή ενός attribute xu-on:* είναι πάντα ένας πίνακας αντικειμένων handler, και κάθε workflow είναι
ένας πίνακας βημάτων ενεργειών (η πλήρης αναφορά ενεργειών βρίσκεται παρακάτω, στο Προγράμματα λογικής και
ροές εργασίας). Το props.condition ενός βήματος το περιορίζει· το props.async: true το εκτελεί χωρίς αναμονή.
Κρίσιμη σημασιολογία
- Το
xu-exp:classαντικαθιστά το στατικό attributeclassαντί να προσθέτει σε αυτό. Ένα στοιχείο που έχει και τα δύο έχει το στατικό αγνοημένο, οπότε οι κλάσεις διάταξης ανήκουν και μέσα στην έκφραση:xu-exp:class="'card p-4 ' + (@active_v ? 'ring' : '')". - Το
xu-scriptπαίρνει μια γυμνή έκφρασηfunction (el) { ... }, που εκτελείται μεevalκαι καλείται με το στοιχείο DOM μόλις ο κόμβος γίνει ορατός. Προστατευτείτε από επανεκτελέσεις (if (el.__bound) return; el.__bound = true;) και περιορίστε κάθε ερώτημα στοel, ποτέ στοdocument. - Το
xu-styleέχει αυτόματο εύρος: κάθε επιλογέας προθέτεται με το[xu-ui-id]του κόμβου, οπότε οι απλοί επιλογείς στοιχείων και κλάσεων μένουν τοπικοί και δεν διαρρέουν ποτέ. - Ούτε οι τιμές
xu-scriptούτε οι τιμέςxu-styleμπορούν να περιέχουν χαρακτήρα εισαγωγικού ('ή"), ο καμβάς σχεδίασης σειριοποιεί τα attributes χωρίς escape και ένα εισαγωγικό καταστρέφει το στοιχείο. Η ενότητα για τα προγράμματα JavaScript παρακάτω καλύπτει τεχνικές χωρίς εισαγωγικά. - Το στατικό κείμενο ανήκει στην ιδιότητα
contentενός στοιχείου. Τοxu-exp:xu-contentείναι μόνο για δυναμικό κείμενο.
Tags
Tags συγγραφής εκτός από το απλό HTML: xu-template, xu-single-view, xu-multi-view, xu-panel,
xu-teleport, xu-slot.
- Το
xu-single-viewορίζει εύρος μίας εγγραφής (ρίζα φόρμας, χρησιμοποιείται και ένθετο). - Το
xu-multi-viewεπαναλαμβάνει τα παιδιά του μία φορά ανά γραμμή των δεμένων δεδομένων. - Το
xu-panelενσωματώνει ένα άλλο prog (attributeprogramσυν είσοδοιxu-exp:<param>). Μόνο τυπικά attributes HTML (class,id,style,title,hidden,slot,name,role,tabindex) ανήκουν σε αυτό εκτός από τις εκφράσεις παραμέτρων. - Το
xu-teleportαποδίδει τα παιδιά του σε άλλο στόχο DOM (toήxu-exp:to). - Ένα όνομα tag με κεφαλαίο πρώτο γράμμα (
Button,Card) είναι μεταγλωττισμένο στοιχείο, όχι στοιχείο HTML, δείτε Ενσωμάτωση παρακάτω.
Στοιχεία
Ένα στοιχείο (menuType: "component") είναι μια μονάδα UI: ένα δέντρο στοιχείων (progUi) δεμένο με τοπική
κατάσταση (progFields), προαιρετικά δεδομένα (progDataSource), λογική κύκλου ζωής (progEvents) και μια διεπαφή
εισόδου/εξόδου (properties.progParams).
Ιδιότητες
- Το
renderTypeείναιformγια μία εγγραφή (ριζικό στοιχείοxu-single-view) ήgrid/listγια επανάληψη ανά γραμμή δεδομένων (ριζικό στοιχείοxu-multi-view). - Το
rwModeείναιRγια ανάγνωση ήUγια ενημέρωση· τοallowCreateλέει αν μπορεί να εισαχθεί νέα γραμμή όταν καμία δεν ταιριάζει. - Συμβατική ονομασία
progParams: οι παράμετροι τελειώνουν σε_in/_out, τα τοπικά εικονικά πεδία του στοιχείου τελειώνουν σε_v. - Το
uiFrameworkαντανακλά ό,τι χρησιμοποιούν ήδη τα υπάρχοντα στοιχεία του έργου. Ένα υπάρχον έργο που το παραλείπει πρέπει να συνεχίσει να το παραλείπει, η ρύθμιση ενός πρόσθετου framework που το drive του έργου δεν σερβίρει πραγματικά κολλάει τη ζωντανή προεπισκόπηση σε λευκή οθόνη.
Το δέντρο στοιχείων (progUi)
Ο κόμβος root του factory μένει· μια κατασκευή δουλεύει μέσα στα children του. Κάθε κόμβος χρειάζεται μοναδικό id
(οι νέοι κόμβοι χρησιμοποιούν ui-<uuid>), type: "element" και ένα tagName, χωρίς τύπους κόμβων comment ή text,
το στατικό κείμενο ζει στο content. Κάθε κόμβος χρειάζεται attributes: {} και children: []
ακόμη και όταν είναι κενά, ο σειριοποιητής του καμβά σχεδίασης αποαναφέρεται και στα δύο σε κάθε κόμβο και μια παράλειψη
χαλάει την προεπισκόπηση του ίδιου του στοιχείου.
Ενσωμάτωση: xu-panel ή μεταγλωττισμένο στοιχείο
Και τα δύο προσαρτώνται διαφανώς, χωρίς στοιχείο περιτύλιξης, και και τα δύο αποφασίζονται από ένα σήμα: αν
το tagName αρχίζει με κεφαλαίο γράμμα.
xu-panel,tagNameμε πεζά συν ένα attributeprogram, ενσωματώνει ένα άλλο prog, ένα παιδί δεμένο με βάση δεδομένων ή με κατάσταση, με δικά του πεδία και συμβάντα. Τοprogramείναι το id του παιδιού (ήxu-exp:progγια δυναμικό), οι τιμές φτάνουν στις παραμέτρους_inτου μέσωxu-exp:<param>.- Ένα tag με κεφαλαίο συν ένα attribute
libraryπροσαρτά ένα μεταγλωττισμένο στοιχείο, ένα πρωτογενές στοιχείο συστήματος σχεδίασης ή ένα κομμάτι που μεταγλώττισε η ίδια η εφαρμογή. Κάθε απλό attribute γίνεται prop (props.<name>), ποτέ attribute DOM, αφού το στοιχείο δεν αποδίδει δικό του στοιχείο DOM. Ένας κόμβος στοιχείου δεν έχει παραμέτρους εξόδου, σε αντίθεση με τοxu-panelτίποτα δεν γράφει τιμή πίσω στα πεδία σας.
Ένα <Buton> με τυπογραφικό λάθος διεκδικείται ακόμη ως tag στοιχείου, δεν επιστρέφει ποτέ σε άγνωστο στοιχείο
HTML, και ρίχνει σφάλμα κατά την προσάρτηση κατονομάζοντας το tag, τη βιβλιοθήκη και κάθε πηγή που δοκιμάστηκε. Το validate_prog
δεν ελέγχει σήμερα tags στοιχείων ή τιμές library, η ζωντανή προεπισκόπηση είναι ο μόνος έλεγχος.
progFields
Το data.type είναι virtual για τοπική κατάσταση, table για μια στήλη της δεμένης πηγής δεδομένων, ή
expression / datasource. Το workflow ενός πεδίου εκτελείται κατά την αλλαγή. Μια προεπιλογή ορίζει
props.fieldValue· ένα υπολογιζόμενο πεδίο ορίζει props.fieldComputed: true συν
propExpressions.fieldValue.
progDataSource
Μία εγγραφή με κλειδί (φόρμα): dataSourceFilterModelType: "index" με ένα dataSourceIndexId
που υπάρχει στα δικά του tableIndexes του πίνακα. Μια φιλτραρισμένη λίστα (grid ή list):
dataSourceFilterModelType: "query" με filterModelMongoFx, μια συμβολοσειρά έκφρασης τύπου Mongo.
Το dataSourceType είναι table, array, json, csv, none, ή κενό για ένα καθαρά παρουσιαστικό
στοιχείο χωρίς καμία πηγή δεδομένων.
progEvents και τα τρία hooks κύκλου ζωής
Τύποι συμβάντων: on_load, on_exit, before_record, after_record, record_not_found,
locate_not_found, screen_ready, on_refresh, on_unload, client_interval, user_defined.
Τα συμβάντα user_defined ενεργοποιούνται από παντού με την
ενέργεια raise_event· το screen_ready είναι το συνηθισμένο hook προσάρτησης.
Τα τρία ενσωματωμένα hooks ενός στοιχείου μοιράζουν τη δουλειά, η χρήση του λάθους είναι συχνή πηγή σφαλμάτων:
screen_ready
Εκτελείται μία φορά ανά στιγμιότυπο. Δημιουργήστε εδώ DOM και widgets.
on_refresh
Εκτελείται μετά από κάθε φόρτωση, συμπεριλαμβανομένης της πρώτης, αμέσως μετά το screen_ready. Δώστε νέα δεδομένα σε widgets
που υπάρχουν ήδη. Αν βάλετε δουλειά ανανέωσης στο screen_ready, ο κώδικας δημιουργίας εκτελείται ξανά πάνω σε DOM
που υπάρχει ακόμη και στοιβάζεται ένα δεύτερο widget.
on_unload
Εκτελείται όταν το στιγμιότυπο διαλύεται. Καταστρέψτε ό,τι δημιούργησε το prog, widgets, χρονόμετρα,
ακροατές document / window, παρατηρητές. Η μηχανή μπορεί να ελευθερώσει μόνο ό,τι δημιούργησε, ένας ακροατής
δεμένος στο document διαφορετικά ζει περισσότερο από το panel.
Μοτίβα
- Καταστάσεις φόρτωσης και κενού: βάλτε
xu-ref="myref"στο στοιχείο που είναι δεμένο με δεδομένα, και μετά περιορίστε τα στοιχεία skeleton ή κενού μεxu-renderπάνω στο(@SYS_GLOBAL_OBJ_REFS).myref, το σύνολο δεδομένων του προσαρτάται μόλις φτάσουν δεδομένα. - Modals: χτίστε τον διάλογο ως δικό του στοιχείο, ανοίξτε τον με την ενέργεια
call_modal. - Αποθήκευση ή διαγραφή δεμένης γραμμής:
invoke_actionμεact_save/act_delete, ή ένα ειδικό progset_dataγια οτιδήποτε πέρα από την τρέχουσα γραμμή.
Προγράμματα λογικής και ροές εργασίας
Οι τύποι prog λογικής μοιράζονται τη μηχανή δεδομένων ενός στοιχείου (progDataSource, progFields,
progEvents, properties.progParams) χωρίς κανένα UI:
Παράμετροι
Ο καλών περνά τιμές μέσω του name.parameters της ενέργειας,
{ "order_id_in": { "value": "", "fx": "@selected_id_v" } }, το value για στατική τιμή, το fx για
έκφραση. Ο checker επαληθεύει ότι το πρόγραμμα-στόχος υπάρχει και ότι το menuType του ταιριάζει με
την ενέργεια.
Ενέργειες ροής εργασίας
Μια ροή εργασίας είναι ένας πίνακας βημάτων, { "id": "...", "data": { "action": "...", "name": { ... }, "enabled": true }, "props": {} }, που εκτελούνται με τη σειρά. Το props.condition περιορίζει ένα βήμα, το props.async: true το εκτελεί χωρίς αναμονή. Οι ροές εργασίας εμφανίζονται σε handlers xu-on:*, στο progEvents[].workflow,
και στο δικό του workflow ενός πεδίου.
Το invoke_action δέχεται act_next, act_prev, act_first, act_last, act_reload,
act_refresh, act_print, act_save, act_delete (μόνο σε πλαίσιο στοιχείου).
alter_ui_element, create_ui_element, info_ui_element, remove_ui_element,
empty_ui_element, cache_ui_element, load_ui_element. Οδηγήστε το UI μέσω πεδίων και xu-exp /
xu-render αντί για προστακτική ενέργεια στοιχείου.
Ο δικός του επιλογέας ενεργειών του Studio προσφέρει Κλήση πράκτορα AI και Κλήση πράκτορα διαλογής δίπλα στις ενέργειες
παραπάνω. Καμία δεν βρίσκεται σε αυτόν τον πίνακα επειδή καμία δεν είναι τέτοια: το validate_prog δεν έχει περίπτωση γι' αυτές
και αναφέρει invalid trigger type, και η μηχανή ροών εργασίας εκτέλεσης δεν έχει ούτε αυτή handler γι' αυτές, οπότε
ένα αποθηκευμένο βήμα δεν εκτελείται ποτέ ακόμη κι αν αγνοηθεί το σφάλμα. Για να φτάσει ένα prog σε έναν δημοσιευμένο πράκτορα, προσθέστε
ένα εργαλείο Πράκτορας AI στη δική του λίστα εργαλείων ενός άλλου πράκτορα (το agentConfig.agent_tools ενός εγγράφου
menuType: "ai_agent"), όχι ένα βήμα ροής εργασίας σε στοιχείο, get_data ή οποιονδήποτε άλλο τύπο prog.
Το name.value του update αναθέτει πεδία με ζεύγη @field: expression χωρισμένα με ερωτηματικό, ή ένα
αντικείμενο JSON5, "@saving_v: true; @status_v: 'sent'". Η κλήση άλλου προγράμματος το ονομάζει κάτω από το name.prog,
αντιστοιχίζοντας την ενέργεια με τον δικό του τύπο του προγράμματος
(το get_data χρειάζεται prog get_data, το call_native_javascript prog javascript, και ούτω καθεξής).
Το call_library καλεί μια μέθοδο εγκατεστημένου πρόσθετου: το name.plugin_name πρέπει να έχει αγοραστεί και να είναι
εγκατεστημένο στην εφαρμογή αλλιώς ο checker απορρίπτει το βήμα, το name.library_method μία από τις μεθόδους που
εξάγει το πρόσθετο, το name.library_props τα δηλωμένα πεδία του. Δύο ονόματα props είναι σύμβαση σε όλα τα
πρόσθετα και όχι ειδικά για κάποιο: το event_name_for_successful_callback εγείρει αυτό το συμβάν με την απάντηση της μεθόδου,
το field_id_to_return_result γράφει την απάντηση απευθείας σε αυτό το πεδίο, κανένα δεν είναι υποχρεωτικό.
Τύποι 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 είναι
το συνηθισμένο hook αρχικοποίησης· τα before_record / after_record /
record_not_found / locate_not_found είναι κύκλος ζωής δεδομένων, ειδικά για set_data και batch·
το client_interval είναι επαναλαμβανόμενο χρονόμετρο· το user_defined ενεργοποιείται από την ενέργεια raise_event.
Πίνακες
Ένα prog πίνακα (menuType: "table") ορίζει έναν πίνακα βάσης δεδομένων: τις στήλες του (tableFields), τα
ευρετήριά του (tableIndexes) και το πρόσθετο βάσης δεδομένων που τον αποθηκεύει (properties.databaseSocket). Γονέας
δέντρου: database, ή ένας φάκελος κάτω από αυτόν.
- Το
databaseSocketπρέπει να ονομάζει ένα πρόσθετο βάσης δεδομένων εγκατεστημένο στο έργο, το@xuda.io/xuda-dbs-plugin-xudaείναι η προεπιλογή της πλατφόρμας· ένας υπάρχων πίνακας στο ίδιο έργο είναι η αναφορά για το ποιο socket να επαναχρησιμοποιήσετε. - Απαιτείται τουλάχιστον ένα πεδίο και τουλάχιστον ένα ευρετήριο.
- Το
field_idαρχίζει με γράμμα, μετά γράμματα, ψηφία, κάτω παύλα, παύλα, άνω και κάτω τελεία ή τελεία, και μένει μοναδικό μέσα στον πίνακα. - Το
fieldTypeείναιstring,number,boolean,array,objectήdate· τοmandatory: trueτο κάνει υποχρεωτικό κατά την αποθήκευση. - Κάθε ευρετήριο χρειάζεται μη κενά
nameκαιkeys, και κάθε κλειδί πρέπει να είναι υπάρχονfield_id.
Σύμβαση: προθέστε τις στήλες με έναν τριγράμματο κωδικό πίνακα, ένας πίνακας με όνομα "ORD - Orders" παίρνει
ORD_Id, ORD_Total, ORD_Status. Δώστε σε κάθε πίνακα ένα μοναδικό πεδίο <TBL>_Id με μοναδικό ευρετήριο
πάνω του, η σύνδεση στοιχείου μίας εγγραφής το χρειάζεται.
Ένας πίνακας χρησιμοποιείται με τρεις τρόπους: το progDataSource.dataSourceTableId ενός στοιχείου ή ερωτήματος, ένα
prog get_data / set_data / batch για πρόσβαση σε επίπεδο γραμμής από ροές εργασίας, ή τα xu.dbs_create /
dbs_read / dbs_update / dbs_delete από ένα script, που καλύπτονται παρακάτω.
Προγράμματα JavaScript
Ένα prog javascript (menuType: "javascript") κρατά πραγματικό πηγαίο κώδικα JS στο scriptData.value, μεταγλωττισμένο
κατά την αποθήκευση. Το save_prog ενεργοποιεί αυτό το build και επιστρέφει το αποτέλεσμα ως data.compile, { ok: true, dependencies } ή { ok: false, error }. Μια αποτυχημένη μεταγλώττιση αποθηκεύει παρ' όλα αυτά το έγγραφο, οπότε μια κατασκευή διαβάζει
το compile.ok και το διορθώνει πριν προχωρήσει.
Το συμβόλαιο εκτέλεσης
Ο πηγαίος κώδικας γράφεται ως απλό async σώμα, χωρίς export, χωρίς περιτύλιγμα. Κατά την εκτέλεση εκτελείται ως:
Τα params είναι οι ήδη αξιολογημένες είσοδοι του καλούντος· το xu είναι το API εκτέλεσης παρακάτω· η τιμή επιστροφής
είναι προαιρετική, ο ιδιωματικός τρόπος να επιστρέψετε αποτελέσματα είναι το xu.set_field_value στα πεδία του στοιχείου
που κάλεσε. Τα εισαγωγικά είναι εντάξει εδώ, σε αντίθεση με την τιμή attribute xu-script.
Το API εκτέλεσης xu
Οι μέθοδοι dbs_* παίρνουν το δικό του _id του prog πίνακα, ποτέ όνομα. Οι επιλογείς είναι αντικείμενα τύπου Mongo πάνω στα
ids πεδίων, το {} επιστρέφει τα πάντα (προεπιλεγμένο όριο 999). Η προβολή fields είναι προαιρετική,
το [] επιστρέφει κάθε πεδίο και μια λίστα ids πεδίων επιστρέφει μόνο αυτά.
Μεταφορά δεδομένων: πεδία, όχι παράμετροι
Το call_native_javascript δεν αξιολογεί περιτυλίγματα παραμέτρων {value, fx}, το name.parameters
φτάνει ακατέργαστο στο script. Το αξιόπιστο συμβόλαιο: το στοιχείο βάζει πρώτα το payload σε ένα πεδίο (ένα
βήμα update ή ένα input xu-bind), η ροή εργασίας καλεί το prog με κενό parameters: {}, και
το script το διαβάζει με xu.get_field_value και αναφέρει πίσω με xu.set_field_value. Αν καλείτε
από άλλο script, το xu.call_javascript(prog_id, {...}) περνά πράγματι παραμέτρους απευθείας.
Ιδιομορφίες ζωντανής προεπισκόπησης
- Οι εγγραφές δεδομένων φτάνουν στην πραγματική βάση δεδομένων, αλλά το
xu.dbs_readδιαβάζει ένα τοπικό αποθετήριο πρόχειρων που μπορεί να μην περιέχει φρέσκες γραμμές διακομιστή, μια ανάγνωση αμέσως μετά από εγγραφή μπορεί να επιστρέψει κενή στην προεπισκόπηση παρότι η εγγραφή έγινε (ορατή στην καρτέλα Data του πίνακα στο Studio). Οι αναπτυγμένες εφαρμογές διαβάζουν και γράφουν στο ίδιο αποθετήριο. - Τα μεταγλωττισμένα scripts αποθηκεύονται σκληρά στην κρυφή μνήμη στις προεπισκοπήσεις ανάπτυξης, μια τρέχουσα προεπισκόπηση μπορεί να συνεχίσει να εκτελεί το προηγούμενο script ακόμη και μετά από επαναφορτώσεις αφού μια αποθήκευση το μεταγλωττίσει ξανά. Μια σκληρή ανανέωση του browser το καθαρίζει.
- Το
xu.alertμε εμφάνισηmodal,toastήbrowserμπορεί να εμφανιστεί ως εγγενές, αποκλείονalert()στην προεπισκόπηση. Τοxu.set_field_valueσε ένα πεδίο κατάστασης είναι ο ασφαλέστερος τρόπος να αναφέρετε πίσω.
Prog javascript ή attribute xu-script
Τεχνικές χωρίς εισαγωγικά για xu-script / xu-style
Ο καμβάς σχεδίασης σειριοποιεί τις τιμές attributes χωρίς escape, οπότε ένα μόνο εισαγωγικό καταστρέφει το
markup του στοιχείου. Τα template literals αποφεύγουν εντελώς τα εισαγωγικά συμβολοσειρών
(el.textContent = `Ready`)· ο χαρακτήρας ", για παράδειγμα κατά τη δημιουργία CSV, προέρχεται
από το String.fromCharCode(34)· οι επιλογείς attributes CSS είναι έγκυροι χωρίς εισαγωγικά
(el.querySelector(`[data-role=import-btn]`))· και ένας φρουρός επανεκτέλεσης,
if (el.__bound) return; el.__bound = true;, εμποδίζει ένα script να δεθεί διπλά σε νέα απόδοση.
Παγίδες
Κάθε καταχώριση παρακάτω χάλασε κάποια στιγμή μια πραγματική κατασκευή. Το validate_prog πιάνει τις περισσότερες, εκτελέστε το
πριν από κάθε αποθήκευση.
Μηχανική του API
- Κάθε απάντηση είναι
{ code, data }, τοcode < 0είναι σφάλμα. - Το
create_progεπιστρέφει το νέο έγγραφο κάτω από τοdata.prog, η αποθήκευση ολόκληρης της απάντησης αντί γι' αυτό διατηρεί ένα κακοσχηματισμένο έγγραφο με τοpropertiesθαμμένο κάτω από τοprog. - Το
save_progαντικαθιστά ολόκληρο το έγγραφο. Ξεκινήστε από το τρέχον έγγραφο, ποτέ από έναν συναρμολογημένο με το χέρι σκελετό· ένα-409σημαίνει ότι άλλαξε από την τελευταία ανάγνωση, ξαναφέρτε, εφαρμόστε ξανά, δοκιμάστε ξανά. - Μέσω MCP, τα
prog_jsonκαιproperties_jsonπερνούν ως συμβολοσειρές, το επίπεδο σχήματος εργαλείου αφαιρεί άγνωστα κλειδιά από μια παράμετρο αντικειμένου και μπορεί σιωπηλά να πετάξει ολόκληρες ενότητες. - Το
delete_progείναι μαλακή διαγραφή, ορίζειstat: 4. Ο κόμβοςglobal_<app_id>δεν μπορεί να διαγραφεί.
Περιεχόμενο εγγράφου
- Κανένα
'ή"μέσα σε τιμέςxu-scriptήxu-style. - Τα κλειδιά με πρόθεμα
$($folded,$childrenClass,$nodeBackClass), καθώς και ταpath,code,editCode, είναι κατάσταση προβολής του σχεδιαστή και δεν ανήκουν ποτέ σε αποθηκευμένο κόμβοprogUi. - Κανένας τύπος κόμβου
commentήtext, μόνο στοιχεία, στατικό κείμενο στοcontent. - Κάθε κόμβος στοιχείου χρειάζεται
attributes: {}καιchildren: []ακόμη και όταν είναι κενά. - Το
xu-exp:classαντικαθιστά το στατικόclass, κάθε απαραίτητη κλάση ανήκει μέσα στην έκφραση. - Το
xu-bindείναι γυμνό αναγνωριστικό πεδίου, χωρίς@, παντού αλλού τα πεδία χρησιμοποιούν@. - Μόνο τα τεκμηριωμένα attributes
xu-*κάνουν κάτι, ένα επινοημένο αγνοείται σιωπηλά και τοvalidate_progπροειδοποιεί. - Η ρίζα δέντρου ενός prog
ai_agentείναιai_agents, αποθηκεύστε το μεstudio_meta.parentId: "ai_agents"(ή id φακέλου κάτω από αυτό) αν ο checker επισημάνει τοparentId.
Εκτέλεση και απόδοση
- Ένα
tagNameμε κεφαλαίο διεκδικείται πάντα ως στοιχείο, ακόμη και με τυπογραφικό λάθος, και ρίχνει σφάλμα κατά την προσάρτηση κατονομάζοντας το tag, τοlibraryκαι κάθε πηγή που δοκιμάστηκε, δεν υπάρχει σιωπηλό "δεν αποδίδεται" όπως συμβαίνει με έναxu-panelχωρίς επιλεγμένο πρόγραμμα. - Το
validate_progδεν ελέγχει tags στοιχείων ή τιμέςlibrary, μόνο η ζωντανή προεπισκόπηση πιάνει ένα λάθος γραμμένο. - Καμία κλάση utility CSS (Tailwind ή άλλο) στην εκτέλεση εκτός αν το πρόσθετο
uiFrameworkτου έργου την παρέχει πραγματικά, κλάσεις όπως τοp-4δεν κάνουν σιωπηλά τίποτα διαφορετικά. Η αυτόνομη μορφοποίηση είναι τοxu-style, με αυτόματο εύρος από το[xu-ui-id]. - Το
xu-scriptεκτελείται μία φορά ανά ορατότητα στοιχείου και μπορεί να ενεργοποιηθεί ξανά σε νέα απόδοση, προστατευτείτε μεel.__boundκαι περιορίστε τα ερωτήματα στοel.
Δεδομένα και scripts
- Οι παράμετροι του
call_native_javascriptδεν αξιολογούνται, περάστε τα δεδομένα μέσω πεδίων (δείτε Μεταφορά δεδομένων παραπάνω). - Οι γραμμές του
dbs_readείναι{id, value}, τα πεδία ζουν κάτω από το.value, το id της γραμμής στο.id. Μην περνάτε προβολήfields, χαλά την ανάγνωση από τον διακομιστή. - Μέσα στο
xu-for, τυλίξτε τον επαναλήπτη σε παρενθέσεις, το(@_FOR_VAL).CNT_Nameαξιολογείται, το@_FOR_VAL.CNT_Nameαποτυγχάνει σιωπηλά και αποδίδει αντί γι' αυτό το αντικατεστημένο κείμενο πηγής. - Οι εγγραφές της προεπισκόπησης φτάνουν στην πραγματική βάση δεδομένων· οι αναγνώσεις της προεπισκόπησης προέρχονται από τοπικό αποθετήριο πρόχειρων που μπορεί να φαίνεται κενό αμέσως μετά από εγγραφή.
- Προτιμήστε ένα πεδίο κατάστασης αντί για την εμφάνιση modal ή toast του
xu.alertστις προεπισκοπήσεις, μπορεί να αποδοθεί ως εγγενές, αποκλείονalert().
Επαλήθευση της δουλειάς σας
Ξαναφέρτε με get_prog μετά την αποθήκευση και συγκρίνετε με ό,τι αναμενόταν. Για δουλειά UI, ανοίξτε το στοιχείο
στο Studio και πατήστε το κουμπί αναπαραγωγής προεπισκόπησης, ή το URL ζωντανής προεπισκόπησης του έργου όταν
είναι διαθέσιμο. Για ένα prog javascript, ελέγξτε το data.compile.ok σε κάθε αποθήκευση. Διορθώστε κάθε
σφάλμα του validate_prog· αντιμετωπίστε τις προειδοποιήσεις του, εισαγωγικά, κλειδιά $, άγνωστα attributes, ως στοιχεία για άμεση διόρθωση
και όχι ως θόρυβο.