Μετάβαση στο περιεχόμενο
Επαληθεύτηκε

Ο οδηγός 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 κατέχει αυτά τα πεδία· μια συγγραφική κατασκευή επεξεργάζεται μόνο τις ενότητες περιεχομένου από κάτω τους.

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 ακολουθεί το <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 παίρνει το γυμνό αναγνωριστικό πεδίου: xu-bind="search_v", ποτέ xu-bind="@search_v".

Τα attributes xu

Οικογένειες προθεμάτων

Οικογένειες attributes που παίρνουν επίθημα. Οι τιμές xu-on είναι πάντα πίνακες αντικειμένων handler· οι τιμές xu-exp είναι πάντα συμβολοσειρές εκφράσεων.

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

Η τιμή ενός attribute xu-on:* είναι πάντα ένας πίνακας αντικειμένων handler, και κάθε workflow είναι ένας πίνακας βημάτων ενεργειών (η πλήρης αναφορά ενεργειών βρίσκεται παρακάτω, στο Προγράμματα λογικής και ροές εργασίας). Το props.condition ενός βήματος το περιορίζει· το props.async: true το εκτελεί χωρίς αναμονή.

Κρίσιμη σημασιολογία

  • Το xu-exp:class αντικαθιστά το στατικό attribute class αντί να προσθέτει σε αυτό. Ένα στοιχείο που έχει και τα δύο έχει το στατικό αγνοημένο, οπότε οι κλάσεις διάταξης ανήκουν και μέσα στην έκφραση: 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 (attribute program συν είσοδοι 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).

Ιδιότητες

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 είναι form για μία εγγραφή (ριζικό στοιχείο xu-single-view) ή grid / list για επανάληψη ανά γραμμή δεδομένων (ριζικό στοιχείο xu-multi-view).
  • Το rwMode είναι R για ανάγνωση ή U για ενημέρωση· το allowCreate λέει αν μπορεί να εισαχθεί νέα γραμμή όταν καμία δεν ταιριάζει.
  • Συμβατική ονομασία progParams: οι παράμετροι τελειώνουν σε _in / _out, τα τοπικά εικονικά πεδία του στοιχείου τελειώνουν σε _v.
  • Το uiFramework αντανακλά ό,τι χρησιμοποιούν ήδη τα υπάρχοντα στοιχεία του έργου. Ένα υπάρχον έργο που το παραλείπει πρέπει να συνεχίσει να το παραλείπει, η ρύθμιση ενός πρόσθετου framework που το drive του έργου δεν σερβίρει πραγματικά κολλάει τη ζωντανή προεπισκόπηση σε λευκή οθόνη.

Το δέντρο στοιχείων (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" } }
      ] }
  ]
}

Ο κόμβος root του factory μένει· μια κατασκευή δουλεύει μέσα στα children του. Κάθε κόμβος χρειάζεται μοναδικό id (οι νέοι κόμβοι χρησιμοποιούν ui-<uuid>), type: "element" και ένα tagName, χωρίς τύπους κόμβων comment ή text, το στατικό κείμενο ζει στο content. Κάθε κόμβος χρειάζεται attributes: {} και children: [] ακόμη και όταν είναι κενά, ο σειριοποιητής του καμβά σχεδίασης αποαναφέρεται και στα δύο σε κάθε κόμβο και μια παράλειψη χαλάει την προεπισκόπηση του ίδιου του στοιχείου.

Ενσωμάτωση: xu-panel ή μεταγλωττισμένο στοιχείο

Και τα δύο προσαρτώνται διαφανώς, χωρίς στοιχείο περιτύλιξης, και και τα δύο αποφασίζονται από ένα σήμα: αν το tagName αρχίζει με κεφαλαίο γράμμα.

  • xu-panel, tagName με πεζά συν ένα attribute program, ενσωματώνει ένα άλλο 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

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 είναι 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, ή ένα ειδικό prog set_data για οτιδήποτε πέρα από την τρέχουσα γραμμή.

Προγράμματα λογικής και ροές εργασίας

Οι τύποι prog λογικής μοιράζονται τη μηχανή δεδομένων ενός στοιχείου (progDataSource, progFields, progEvents, properties.progParams) χωρίς κανένα UI:

Παράμετροι

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

Ο καλών περνά τιμές μέσω του 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 (μόνο σε πλαίσιο στοιχείου).

Καταργημένες ενέργειες που ο checker απορρίπτει

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 αντί για προστακτική ενέργεια στοιχείου.

Τα call_ai_agent και call_triage_agent δεν είναι πραγματικές ενέργειες

Ο δικός του επιλογέας ενεργειών του 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, ή ένας φάκελος κάτω από αυτόν.

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 πρέπει να ονομάζει ένα πρόσθετο βάσης δεδομένων εγκατεστημένο στο έργο, το @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, χωρίς περιτύλιγμα. Κατά την εκτέλεση εκτελείται ως:

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

Τα params είναι οι ήδη αξιολογημένες είσοδοι του καλούντος· το xu είναι το API εκτέλεσης παρακάτω· η τιμή επιστροφής είναι προαιρετική, ο ιδιωματικός τρόπος να επιστρέψετε αποτελέσματα είναι το xu.set_field_value στα πεδία του στοιχείου που κάλεσε. Τα εισαγωγικά είναι εντάξει εδώ, σε αντίθεση με την τιμή attribute xu-script.

Το API εκτέλεσης 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`);

Οι μέθοδοι 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, ως στοιχεία για άμεση διόρθωση και όχι ως θόρυβο.