Γέφυρα Cordis
Η γέφυρα ενσωματώνει το DeepSeek Harness (DSH) στο backend του Libre WebUI. Το DSH λειτουργεί ως δέντρο plugins σε runtime Cordis που φιλοξενεί το LWUI· οι δυνατότητες παρέχονται ως υπηρεσίες Cordis, όχι εισαγόμενα modules.
Η γέφυρα είναι ανενεργή από προεπιλογή. Τίποτε από τα παρακάτω δεν εκτελείται πριν την ενεργοποίηση από operator· δείτε Ρύθμιση Cordis.
Γιατί γέφυρα αντί άμεσης ενσωμάτωσης
Η άμεση εισαγωγή πακέτων DSH θα ήταν συντομότερη αλλά χειρότερη: η μηχανή θα γινόταν εξάρτηση μεταγλώττισης. Αλλαγή adapter μοντέλου, βρόχου agent ή αφαίρεση μηχανής θα απαιτούσε αλλαγή και νέα εγκατάσταση LWUI.
Η γέφυρα αντιστρέφει τη σχέση. Το Libre WebUI εξαρτάται από μία αφηρημένη σύμβαση και το έγγραφο σύνθεσης επιλέγει την υλοποίηση:
- Άλλος προορισμός χωρίς build. Η σύνθεση YAML επιτρέπει αλλαγή παρόχου ως ρύθμιση.
- Ρύθμιση δυνατοτήτων. Κάθε δυνατότητα είναι εγγραφή Loader· αλλαγές εφαρμόζονται στην επόμενη εκκίνηση host.
- Καθαρή αφαίρεση. Το root fiber κατέχει υπηρεσίες, listeners και effects. Η αποδέσμευσή του αναιρεί όλα, χωρίς επανεκκίνηση Libre WebUI.
Επίπεδα
Οι συγκεκριμένες εξαρτήσεις DSH μένουν στο backend/src/cordis/dsh/. Routes και υπηρεσίες εφαρμογής χρησιμοποιούν τις συμβάσεις. Ο οδηγός Work έχει χωριστή σύνθεση στη μνήμη και δεν φορτώνει ποτέ host filesystem plugins.
Συμβάσεις
Το backend/src/cordis/contracts.ts περιορίζεται στις μορφές που χρειάζεται το API LWUI, χωρίς εσωτερική ορολογία μηχανής.
| Σύμβαση | Σκοπός |
|---|---|
DshEngine.status() | Κύκλος ζωής υπηρεσιών (pending / ready / failed) |
DshEngine.modelConfiguration() | Προεπιλογές μοντέλου και παρόχου ενεργής σύνθεσης |
DshEngine.listSessions() | Σύνοψη συνεδριών, νεότερες πρώτα |
DshEngine.getSession(id) | Συνεδρία με προβολή μηνυμάτων |
DshEngine.createSession(opts) | Δέσμευση ID και καταλόγου εργασίας |
DshEngine.updateSessionSettings(id, settings) | Αποθήκευση πραγματικού μοντέλου και εγγενών δικαιωμάτων σε αδράνεια |
DshEngine.decideApproval(id, approvalId, decision) | Απόφαση εγγενούς έγκρισης για τη σωστή συνεδρία |
DshEngine.deleteSession(id) | Λήξη συνεδρίας και αποδέσμευση agent |
DshEngine.listAgents() | Ενεργοί agents, ρίζα ή παιδιά |
DshEngine.listTools() | Καταχωρισμένα εργαλεία ορατά στο μοντέλο |
DshEngine.sendMessage(id, txt) | Έναρξη γύρου και επιστροφή stream handle |
DshEngine.cancel(id) | Ακύρωση ενεργού γύρου |
Η σύμβαση δημοσιεύεται ως libreDshEngine: ο καταναλωτής τη διαβάζει με ctx.get('libreDshEngine'), χωρίς import του module γέφυρας.
Το EngineStreamChunk μεταφέρει text, reasoning, tool-call, tool-result, approval-request, approval-decision, error και done. Τα live frames ακολουθούν τον ιδιοκτήτη agent και τη συνεδρία· το μόνιμο αντίστοιχο μήνυμα δεν εκπέμπεται δεύτερη φορά. Το sendMessage επιστρέφει handle όπου το subscribe επαναλαμβάνει ήδη εκπεμφθέν περιεχόμενο, ώστε γρήγορο πρώτο token να μη χαθεί πριν συνδεθεί ο HTTP listener.
Ακολουθία ενός γύρου chat
Χρησιμοποιείται NDJSON, επειδή ο γύρος είναι μία ακολουθία server προς client μετά το αίτημα. Το POST αποφεύγει δεύτερο handshake, ticket και πρωτόκολλο επανασύνδεσης και κρατά τον γύρο σε ένα αυθεντικοποιημένο αίτημα.
DONE και PENDING
Το Cordis ενεργοποιεί plugins όταν υπάρχουν οι δηλωμένες υπηρεσίες. Άρα μια εγγραφή περνά από προγενέστερες καταστάσεις. Η σύγχυση των δύο παρακάτω εννοιών προκαλεί συχνά σιωπηλή μηχανή.
Κατάσταση εγγραφής Loader. Κάθε εγγραφή περνά PENDING → LOADING → ACTIVE ή FAILED. Ελλείπουσες υπηρεσίες σημαίνουν απεριόριστη αναμονή αντί σφάλματος· ελλιπής σύνθεση μπορεί να ξεκινήσει χωρίς να εξυπηρετεί.
Διαθεσιμότητα υπηρεσίας. Ο host αναφέρει τις αναμενόμενες υπηρεσίες ως:
| Κατάσταση | Σημασία | Αιτία |
|---|---|---|
pending | Δεν έχει καταχωριστεί στο context | Η παρέχουσα εγγραφή δεν ενεργοποιήθηκε ή είναι ανενεργή |
ready | Καταχωρισμένη και λειτουργική | Η παρέχουσα εγγραφή ενεργοποιήθηκε |
failed | Δηλωμένη αλλά μη λειτουργική | Συνοδεύεται από κείμενο detail |
Το host.status() δίνει διαθεσιμότητα και απαιτούμενες ελλείψεις· το GET /api/cordis/health εκθέτει τα ίδια. Ελλιπής απαιτούμενη υπηρεσία προκαλεί αποτυχία εκκίνησης, όχι μηχανή με κενές απαντήσεις.
Δύο αλυσίδες που συχνά ρυθμίζονται λάθος:
- Το
dsh-toolsαπαιτείsystemPrompt. - Το
dsh-agent-loopαπαιτείagents,sessions,llm,tools,systemPromptκαιsessionProjections.
Απουσία ενός μπορεί να αφήσει λειτουργική αποθήκη συνεδριών χωρίς καμία απάντηση μηνύματος.
Ρύθμιση παρόχου
Το παρεχόμενο libre-webui-llm-adapter εξυπηρετεί τους παρόχους LWUI. Ο επιλογέας Engine διαλέγει μοντέλο ανά συνεδρία χωρίς αντικατάσταση της εγγραφής.
Αλλαγές σύνθεσης εφαρμόζονται στην επόμενη εκκίνηση. Επανεκκινήστε backend ή απενεργοποιήστε/ενεργοποιήστε Cordis αν ο διακόπτης δεν είναι κλειδωμένος. Οι μόνιμες συνεδρίες μένουν στην αποθήκη και συνεχίζουν μέσω της τρέχουσας σύνθεσης.
Έμπιστος κώδικας ενσωμάτωσης μπορεί να καλεί απευθείας τα lifecycle API του Loader. Η γέφυρα δεν παρέχει endpoint ανταλλαγής adapter ούτε επαναφέρει αυτόματα προηγούμενον όταν η αντικατάσταση αποτυγχάνει.
Αναίρεση
Η αποδέσμευση του root fiber αφαιρεί όλα όσα εγκατέστησε η μηχανή. Η σχέση ιδιοκτησίας είναι η εγγύηση:
- Υπηρεσίες καταχωρισμένες από plugins αποσύρονται μαζί με το fiber.
- Συνδρομές
session/eventδημιουργούνται στον constructor της γέφυρας και ανήκουν στο fiber της εγγραφής της. - Η γέφυρα παρακολουθεί agent handles και τα αποδεσμεύει στο teardown effect.
- Ο host αποδεσμεύει το root context που κατέχει όλες τις εγγραφές.
Το stopCordisHost() είναι idempotent και ενταγμένο στη διακοπή backend· timers και file handles ελευθερώνονται αντί να περιμένουν την έξοδο process.
Ταυτότητα και αποθήκευση συνεδριών
Το Engine δεσμεύει αδιαφανές ID κατά τη δημιουργία. Με ενεργή αποθήκευση, το header γράφεται αμέσως, οπότε επιζεί ακόμη και άδεια συνεδρία. Η γέφυρα απαριθμεί ενεργές και αποθηκευμένες, διαβάζει logs από το επικυρωμένο API DSH και συνεχίζει στο ίδιο ID. Νέα μηνύματα χρήστη χρησιμοποιούν τον κατασκευαστή αναγνωρισμένων μηνυμάτων DSH.
Η διαγραφή ακυρώνει και αποδεσμεύει τον agent πριν αφαιρέσει το αρχείο. Ο τοπικός JSONL adapter ελέγχει αποθήκη και διαδρομές και απορρίπτει symlinks. Προσαρμοσμένη αποθήκευση χωρίς δυνατότητα διαγραφής δίνει σφάλμα, όχι ψευδή επιτυχία.
Η ακύρωση φτάνει σε native agent, αίτημα μοντέλου και εργαλεία. Η αποσύνδεση client ακυρώνει τον γύρο· ολοκληρωμένα μηνύματα παραμένουν αναγνώσιμα. Ο περιορισμένος replay buffer διατηρεί γρήγορη απάντηση πριν την προσάρτηση αναγνώστη.
Η host μηχανή είναι λειτουργία solo με ένα αντίγραφο. Team εγκαταστάσεις δεν φορτώνουν το τοπικό JSONL runtime. Το sandboxed Work χρησιμοποιεί τα υπάρχοντα SQL repositories για εργασίες, εκτελέσεις, μηνύματα, εγκρίσεις και events.
Επιφάνεια HTTP
| Μέθοδος | Διαδρομή | Σκοπός |
|---|---|---|
GET | /api/cordis/health | Κατάσταση γέφυρας, χωρίς αυθεντικοποίηση |
GET | /api/cordis/sessions | Λίστα συνεδριών |
POST | /api/cordis/sessions | Δημιουργία συνεδρίας |
GET | /api/cordis/sessions/:id | Ανάγνωση συνεδρίας και μηνυμάτων |
DELETE | /api/cordis/sessions/:id | Τερματισμός συνεδρίας |
POST | /api/cordis/sessions/:id/messages | Αποστολή μηνύματος, ροή NDJSON |
POST | /api/cordis/sessions/:id/cancel | Ακύρωση ενεργού γύρου |
GET | /api/cordis/agents | Λίστα ενεργών agents |
GET | /api/cordis/tools | Λίστα καταχωρισμένων εργαλείων |
Όλα εκτός /health απαιτούν αυθεντικοποιημένη συνεδρία διαχειριστή. Όταν η γέφυρα δεν εξυπηρετεί, επιστρέφουν 503 με code CORDIS_DISABLED, CORDIS_STARTING ή CORDIS_UNAVAILABLE.
Η σελίδα frontend/src/pages/CordisPage.tsx ανοίγει στο /cordis από την πλαϊνή στήλη. Δείχνει και δημιουργεί συνεδρίες, απαριθμεί εργαλεία και μεταφέρει τον γύρο στη συνομιλία. Αν η γέφυρα είναι κλειστή ή δεν ξεκινά, δείχνει λόγο αντί κενής λίστας· αλλιώς «χωρίς συνεδρίες» και «χωρίς μηχανή» φαίνονται ίδια.
Ο client frontend/src/utils/api/cordisApi.ts καλεί μόνο αυτό το API χωρίς backend τύπους ή @deepseek-ai/*. Έτσι η μηχανή αντικαθίσταται χωρίς frontend αλλαγή. Το sendMessage(sessionId, text, { onChunk }) καταναλώνει τον γύρο· ο client αναλύει JSON ανά γραμμή και δέχεται frames χωρισμένα μεταξύ δικτυακών αναγνώσεων.
Χειρισμός συνομιλίας Engine
Η σελίδα εμφανίζει Markdown, πίνακες και χρωματισμένο κώδικα με αντιγραφή απαντήσεων και κώδικα. System prompts και runtime context βρίσκονται σε κλειστό Session context, όχι σαν μηνύματα χρήστη. Το διαθέσιμο reasoning και η δραστηριότητα εργαλείων έχουν χωριστές αναπτύξεις· τα αποτελέσματα συνδέονται με τη σωστή πράξη μετά τη φόρτωση.
Επιλέξτε πραγματικό μοντέλο παρόχου από τα διαθέσιμα τοπικά/plugin μοντέλα του διαχειριστή, μαζί με ταυτότητα παρόχου. Persona και agent του Chat δεν είναι model IDs ούτε εισάγουν οδηγίες σε Engine συνομιλία. Παλιά εσφαλμένα persona-model headers αγνοούνται ως προεπιλογή χωρίς αλλαγή log.
Κάθε συνεδρία έχει Read-only ή Workspace write, επιβαλλόμενα από πολιτική DSH και κανονικοποιημένο όριο workspace. Ο composer δείχνει το εύρος. Οι ρυθμίσεις αποθηκεύονται ως native events και επιζούν επανεκκίνησης· αλλαγές σε ενεργό γύρο αρνούνται.
Native αίτημα αυξημένων δικαιωμάτων εμφανίζεται στην πράξη ως Allow once / Deny. Η έγκριση είναι μόνο γι’ αυτό και δεν αλλάζει μόνιμα δικαιώματα. Παλιές ή ακυρωμένες αιτήσεις δεν εγκρίνονται· headless Chat απορρίπτει ερωτήσεις που δεν μπορεί να δείξει. Η γέφυρα δεν δίνει απεριόριστη host πρόσβαση.
Επιπλέον endpoints διαχειριστή:
| Μέθοδος | Διαδρομή | Σκοπός |
|---|---|---|
GET | /api/cordis/models | Διαθέσιμα μοντέλα και τρέχουσα πραγματική προεπιλογή |
PATCH | /api/cordis/sessions/:id/settings | Ορισμός μοντέλου ή δικαιωμάτων συνεδρίας |
POST | /api/cordis/sessions/:id/approvals/:approvalId | Απόφαση με allowed-once ή rejected |
Χρήση της μηχανής στο Chat
Ενεργοποιήστε Access & policies → Agent CLI models και Cordis Engine. Ο διαχειριστής επιλέγει DeepSeek Harness στο Chat. Κάθε αίτημα παίρνει νέα προσωρινή συνεδρία με το δοσμένο ιστορικό. Η κανονική βάση Chat παραμένει αυθεντική· ανεξάρτητες συνομιλίες, διακλαδώσεις και επαναλήψεις δεν μοιράζονται κρυφό ιστορικό. Το προσωρινό log διαγράφεται στην ολοκλήρωση/ακύρωση και δεν εμφανίζεται στη σελίδα Engine.
Η τυπική σύνθεση δίνει και DeepSeek Harness · model (provider) στο Agents. Τα αποθηκευμένα ID τυλίγουν τις ίδιες πλήρεις διαδρομές: dsh:lwui:ollama:<model> ή dsh:lwui:plugin:<plugin>:<model>, με percent encoding ανά στοιχείο. Η προαιρετική τοπική native DSH σύνδεση προσθέτει dsh:native:<provider>:<model> από τον ζωντανό κατάλογο, με τις native ρυθμίσεις και διαπιστευτήρια.
Εγκαταστήστε το ανεξάρτητο πακέτο Apache-2.0 από libre-webui/dsh-native-provider ή ετοιμάστε bundle από LWUI. Και τα δύο χρησιμοποιούν @libre-webui/dsh-native-provider και κρατούν κλειδιά στο DSH. Απαιτούν ίδιο Unix host και OS account, με ιδιωτικό Unix socket· δεν απομονώνουν εφαρμογές του ίδιου account. Εκθέτουν μόνο inference, όχι native agent sessions ή εργαλεία. Η ρύθμιση περιγράφει εγκατάσταση, restart προφίλ, αναβάθμιση και αφαίρεση. Χαμένη σύνδεση ή μοντέλο αποτυγχάνει χωρίς άλλον πάροχο. Native κλήσεις εμφανίζονται στο Provider Usage με μοντέλο, δηλωμένα tokens, latency και αποτέλεσμα.
Το βασικό dsh κρατά την προεπιλογή της ενεργής σύνθεσης. Προσαρμοσμένοι adapters εκθέτουν μόνο αυτή τη βάση, χωρίς μη υποστηριζόμενες αντικαταστάσεις παρόχων LWUI.
Τίτλοι και περιλήψεις σκέψης επιλύουν DSH στον υποκείμενο πάροχο και ζητούν απευθείας κείμενο χωρίς εργαλεία ή συνεδρία agent. Η βάση διαβάζει τις τρέχουσες ρυθμίσεις μαζί με overrides της γέφυρας, όχι εικασίες καταλόγου. Custom adapters χρειάζονται ρητό Ollama ή plugin task model. Μη διαθέσιμος πάροχος δίνει το κανονικό σφάλμα ή τοπική προεπισκόπηση τίτλου, όχι αίτημα σε άλλον πάροχο.
Χρησιμοποιούνται ρυθμίσεις και διαπιστευτήρια του συνδεδεμένου διαχειριστή, όχι άλλου σιωπηρά. Το διαμορφωμένο workspace Cordis μένει προεπιλογή· το Chat δεν το αντικαθιστά με το home του χρήστη server.
Work σε sandbox
Με ενεργό Cordis, το Work έχει χωριστό Engine με Libre WebUI ή DeepSeek Harness. Ονόματα μοντέλων και πάροχοι διατηρούνται. Για LWUI αποθηκεύεται dsh:<model>· native επιλογές κρατούν providerType: dsh, ακριβές provider ID και αρχικό model ID. Έλεγχοι εργαλείων και πρόσβασης ισχύουν· native διαπιστευτήρια απαιτούν ενεργό διαχειριστή.
Κάθε εκτέλεση φτιάχνει απομονωμένο DSH loop μνήμης. Ο adapter δέχεται τρέχον ιστορικό Work, metadata, εικόνες και schemas. Τα σώματα εργαλείων μόνο περιμένουν αποτελέσματα Work, χωρίς ανάγνωση host αρχείων ή εκκίνηση host διεργασιών.
Το Work επικυρώνει ορίσματα, ζητά εγκρίσεις, εκτελεί στο workspace runtime, καταγράφει αποτελέσματα και replay state σε SQL, εφαρμόζει budgets και δημοσιεύει events. Άρνηση εργαλείου δίνει κανονικό αποτέλεσμα άρνησης. Ακύρωση αποδεσμεύει DSH και ακολουθεί τον καθαρισμό container. Μετά την ανάκτηση worker, νέος οδηγός παίρνει το αποκατεστημένο πλαίσιο χωρίς επανάληψη τελειωμένων ενεργειών.
Δεν απαιτείται host σύνθεση ή JSONL. Ισχύουν οι κανόνες Work Docker/Kubernetes και εγκατάστασης, μαζί με κοινή αποθήκευση team.
Όριο ασφαλείας
Engine και host agent Chat είναι μόνο για διαχειριστές. Οι συνεδρίες είναι κοινή κονσόλα, μαζί με system prompts, όχι χώροι ανά χρήστη. Κανονικά accounts δεν μπορούν να τις διαβάζουν, δημιουργούν, αλλάζουν ή ακυρώνουν από API.
Τα παρεχόμενα εργαλεία περιορίζουν ανάγνωση/γραφή στο workspace με canonical στόχους και επίλυση symlinks. Εναλλακτικός κατάλογος συνεδρίας πρέπει να μένει εντός. Ισχύουν πολιτική αλλαγών DSH και εφάπαξ approvals. Operator plugins είναι έμπιστος κώδικας server και μπορούν να προσθέσουν δυνατότητες. Οι εγκρίσεις Engine είναι διαφορετικές από του Work και τους containers του.
Ο οδηγός Work είναι χωριστός: δεν φορτώνει host filesystem, shell ή persistence plugins και εκτελεί μόνο μέσω εξουσιοδότησης και sandbox Work. Απομακρυσμένοι πάροχοι παραμένουν προαιρετικοί και χρησιμοποιούν τη ρυθμισμένη διαδρομή του επιλεγμένου λογαριασμού.