Μπλογκ του Maguyva

Ένα πλαίσιο που ταξιδεύει μαζί σας

Mon, 07 Sep 2026 00:00:00 GMT

Ο μηχανισμός ευρετηρίασης του Cursor είναι εξαιρετικός μέσα στο Cursor. Η αυτόματη συμπλήρωση, η ενσωματωμένη επεξεργασία, η συνομιλία και ο πράκτορας σε εκείνο το παράθυρο στηρίζονται ήδη σε ένα ευρετήριο έργου που διαχειρίζεται το Cursor για τον ανοιχτό χώρο εργασίας. Αν το Cursor είναι η μόνη επιφάνεια όπου γράφετε, και αυτό το ευρετήριο βρίσκει ήδη τα σωστά αρχεία, μείνετε εκεί. Αυτή είναι η ειλικρινής περίπτωση «μείνετε εκεί που είστε», και δικαιολογημένα ανοίγει αυτό το κείμενο.

Αυτό το κείμενο αφορά το άλλο μισό μιας συνηθισμένης εβδομάδας. Το ίδιο αποθετήριο ανοίγει και στο Claude Code, ερωτάται από το Codex CLI, ελέγχεται σε μια δεύτερη μηχανή, ή ρωτιέται από έναν πράκτορα που τρέχει σε CI. Το ερώτημα δεν είναι «ποιος μηχανισμός ευρετηρίασης είναι καλύτερος». Το ερώτημα είναι αν ο χάρτης που εμπιστεύεται ο πράκτορας σε ένα παράθυρο είναι ο ίδιος χάρτης που εμπιστεύεται στο επόμενο.

Το Maguyva είναι αυτός ο χάρτης που ταξιδεύει μαζί σας. Είναι ένα απομακρυσμένο επίπεδο MCP για το context της βάσης κώδικα. Ο πράκτορας το ρωτάει με τον ίδιο τρόπο που ρωτάει οποιοδήποτε άλλο εργαλείο MCP. Τα αποτελέσματα επιστρέφουν ως ταξινομημένες διαδρομές αρχείων με αριθμούς γραμμής. Το Cursor παραμένει ο επεξεργαστής κώδικα. Αυτό που μετακινείται είναι το context.

Σε τι χρησιμεύει ο μηχανισμός ευρετηρίασης του Cursor

Η ενσωματωμένη ευρετηρίαση του Cursor υπάρχει ώστε η συνομιλία, ο πράκτορας και η αναζήτηση μέσα στον επεξεργαστή να μπορούν να ανακτούν σχετικό κώδικα αντί να βασίζονται μόνο σε ό,τι χωράει στο ακατέργαστο παράθυρο συμφραζομένων του μοντέλου. Αυτός είναι ο σωστός σχεδιασμός για ένα IDE. Αυτό το ευρετήριο είναι εγγενές στο Cursor. Δεν είναι διακομιστής MCP και δεν είναι προσβάσιμο από κανένα άλλο πρόγραμμα-πελάτη.

Να πώς λειτουργεί, όπως περιγράφεται στην δημόσια τεκμηρίωση του Cursor και στην ίδια περιγραφή του Cursor τη στιγμή που γράφεται αυτό το κείμενο: η κύρια διαδρομή αναζήτησης δεν είναι πια ένα ευρετήριο στο cloud από διανυσματικές αναπαραστάσεις. Η ομάδα του Cursor δήλωσε στο φόρουμ της κοινότητάς τους ότι η αποκλειστική σημασιολογική αναζήτηση βασισμένη σε διανυσματικές αναπαραστάσεις αποσύρεται σταδιακά υπέρ μιας αναζήτησης βασισμένης σε grep, επειδή τα σημερινά μοντέλα εξερευνούν ήδη αρκετά καλά ένα ζωντανό δέντρο μόνα τους. Στη θέση της βρίσκεται το Instant Grep, ένα τοπικό ευρετήριο αναζήτησης χτισμένο από n-γράμματα, ανεστραμμένες λίστες και φίλτρα Bloom, διατηρημένο σε έναν πίνακα αναζήτησης αντιστοιχισμένο στη μνήμη, ώστε τα ερωτήματα να επιλύονται στο ίδιο το μηχάνημα του προγραμματιστή και όχι σε έναν διακομιστή.

Το ίδιο το ευρετήριο ζει μέσα στον δικό του κατάλογο .git/cursor/ του αποθετηρίου, αγκυρωμένο σε ένα συγκεκριμένο git commit· οι αλλαγές από εκείνο το commit επιστρώνονται πάνω του αντί να προκαλούν νέα σάρωση, και το ευρετήριο ξαναχτίζεται μόνο όταν η τοπική κατάσταση έχει αποκλίνει σημαντικά από αυτό πάνω στο οποίο χτίστηκε. Επειδή βρίσκεται μέσα στο .git, δεν παρακολουθείται ποτέ ούτε αποστέλλεται ποτέ σε απομακρυσμένο αποθετήριο — διέγραψε τον φάκελο, και το ευρετήριο εξαφανίζεται. Το .gitignore τηρείται εξ ορισμού, αφού μόνο περιεχόμενο που παρακολουθείται από το git είναι επιλέξιμο, και το .cursorignore επιβάλλεται στη διαδρομή ανάγνωσης. Δεν υπάρχει πια ούτε βήμα διανυσματικής αναπαράστασης στην πλευρά του διακομιστή ούτε απομακρυσμένη διανυσματική βάση δεδομένων σε αυτή τη διαδρομή. Παλαιότερη τεκμηρίωση περιέγραφε έναν σχεδιασμό υποβοηθούμενο από cloud — κρυπτογράφηση τμημάτων κώδικα, συγχρονισμό μέσω δέντρου Merkle, επαναχρησιμοποίηση ευρετηρίου μεταξύ συναδέλφων ομάδας — και η ίδια η ομάδα του Cursor έχει δηλώσει έκτοτε ότι αυτός ο σχεδιασμός αποσύρεται, οπότε αυτό το κείμενο δεν τον περιγράφει πια ως τρέχοντα.

Ένα χαρακτηριστικό που ξεχωρίζει μέσα στον επεξεργαστή είναι ο βοηθητικός πράκτορας Explore του Cursor. Μπορεί να ξεκινήσει πολλαπλές παράλληλες αναζητήσεις στο δικό του παράθυρο συμφραζομένων με ένα ταχύτερο μοντέλο και να επιστρέψει μόνο τα σχετικά ευρήματα, ώστε η κύρια συνομιλία να μη διογκώνεται από αποτελέσματα αναζήτησης. Αυτή είναι μια πραγματική δύναμη μέσα στον επεξεργαστή. Κρατήστε την.

Οι χώροι εργασίας πολλαπλών ριζών υποστηρίζονται: το context κάθε ανοιχτού φακέλου είναι διαθέσιμο στον Agent. Ορισμένα χαρακτηριστικά που εξαρτώνται από το git, όπως τα πρόσθετα δέντρα εργασίας (git worktree), απενεργοποιούνται σε ρυθμίσεις πολλαπλών ριζών, και τα Cloud Agents δεν υποστηρίζουν καθόλου χώρους εργασίας πολλαπλών ριζών.

Τίποτα από αυτά δεν είναι λόγος να εγκαταλείψετε το Cursor. Είναι μια ακριβής περιγραφή ενός χάρτη που είναι εξαιρετικός εκεί όπου ζει.

Τι σημαίνει πραγματικά «ταξιδεύει μαζί σας»

Ένας χάρτης ταξιδεύει μαζί σας όταν οι ίδιες ερωτήσεις επιστρέφουν το ίδιο είδος απάντησης, με παραπομπές που μπορείτε να ανοίξετε, από περισσότερα από ένα προγράμματα-πελάτες.

Στο Cursor: «Πού ορίζεται το parseConfig και ποιος το καλεί;»
Στο Claude Code, στο ίδιο αποθετήριο: το ίδιο ερώτημα.
Στο Codex CLI, σε ένα μηχάνημα ελέγχου που δεν άνοιξε ποτέ το παράθυρο του Cursor: το ίδιο ερώτημα.
Σε έναν πράκτορα του CI που μιλάει MCP: το ίδιο ερώτημα, στο ίδιο φιλοξενούμενο στιγμιότυπο.

Αν κάθε επιφάνεια χτίζει το δικό της ιδιωτικό ευρετήριο, δεν έχετε έναν χάρτη. Έχετε πολλές κρυφές μνήμες που αποκλίνουν. Το ευρετήριο του επεξεργαστή μπορεί να είναι ενημερωμένο για το δέντρο στον δίσκο. Η συνεδρία CLI μπορεί να καθυστερεί μια μέρα. Η εργασία CI μπορεί να κοιτάζει ένα διαφορετικό αντίγραφο εργασίας. Και ο πράκτορας θα συνεχίσει να ακούγεται σίγουρος.

Ο μηχανισμός ευρετηρίασης του Cursor δεν προορίζεται να το λύσει αυτό. Επειδή ζει μέσα στον επεξεργαστή, το context που χτίζει είναι για εκείνον τον επεξεργαστή. Ένας αναγνώστης που χρειάζεται επίσης ένα CLI, ένα pipeline CI, ή έναν διαφορετικό επεξεργαστή κώδικα χρειάζεται ένα ξεχωριστό εργαλείο για αυτές τις επιφάνειες. Αυτό είναι ένα γεγονός εμβέλειας, όχι ελάττωμα. Το Maguyva είναι αυτό το ξεχωριστό εργαλείο.

Ένας δημοσιευμένος αριθμός γλωσσών για τον μηχανισμό ευρετηρίασης του Cursor δεν αναφέρεται στο υλικό που μπορεί να χρησιμοποιήσει αυτό το κείμενο. Το Maguyva δημοσιεύει υποστήριξη για περισσότερες από 279 γλώσσες και τεχνολογίες βασισμένες σε κείμενο. Η τιμολόγηση του Cursor επίσης δεν αντιγράφεται εδώ· δείτε τη σελίδα τιμών τους. Το Maguyva χρεώνει ανά χώρο εργασίας, όχι ανά θέση, με δημοσιευμένα πλάνα $0, $19, $49 και $149 ανάλογα με την έκταση ευρετηρίασης και το μέγεθος του χώρου εργασίας.

Ένας φιλοξενούμενος χάρτης, κάθε πρόγραμμα-πελάτης MCP

Το Maguyva είναι ένας απομακρυσμένος διακομιστής MCP. Συνδέετε το GitHub, επιλέγετε τα αποθετήρια, και το pipeline στο cloud χτίζει σύμβολα, ακμές γράφου και έναν ταξινομημένο χάρτη. Προσθέτετε ένα κλειδί API στη ρύθμιση MCP του προγράμματος-πελάτη που ήδη χρησιμοποιείτε. Το Maguyva έχει οδηγούς ρύθμισης για 24 τεκμηριωμένα προγράμματα-πελάτες MCP — συμπεριλαμβανομένου του Cursor — και μπορεί να συνδεθεί με άλλα συμβατά με MCP προγράμματα-πελάτες που υποστηρίζουν τυπική ρύθμιση.

Η σελίδα ρύθμισης του Cursor είναι η διαδρομή ειδική για αυτόν τον επεξεργαστή, αν εκεί δουλεύετε. Ο ίδιος διακομιστής απαντά στα Claude Code, VS Code, Windsurf, Codex CLI και τα υπόλοιπα. Δεν αλλάζετε επεξεργαστή κώδικα. Δίνετε σε κάθε πράκτορα την ίδια επιφάνεια εργαλείων: 11 εργαλεία MCP για το πρόγραμμα-πελάτη, που καλύπτουν αναζήτηση, σύμβολα, ανάλυση εξαρτήσεων, ανάκτηση αρχείων, context αποθετηρίου και ντετερμινιστικές ροές εργασίας βοηθητικών εργαλείων. Η σημασιολογική, δομική, γράφου και κειμενική αναζήτηση συγχωνεύονται σε ταξινομημένα αποτελέσματα.

Αυτό είναι το πλεονέκτημα της φορητότητας. Οι παραπομπές που ελέγξατε στο Cursor σήμερα το πρωί έχουν την ίδια μορφή με τις παραπομπές που θα επιστρέψει το Codex CLI απόψε. Διαδρομή αρχείου και αριθμός γραμμής. Ανοίξτε τα. Αν είναι λάθος, το βλέπετε. Αν είναι σωστά, η επόμενη επεξεργασία έχει πού να προσγειωθεί. Ο εγκεκριμένος ισχυρισμός είναι λιγότερες παραισθητικές επεξεργασίες, όχι υπόσχεση ότι κάθε επεξεργασία είναι σωστή.

Η φρεσκάδα δημοσιεύεται. Τα στιγμιότυπα φέρουν χρονοσφραγίδα, ώστε ο πράκτορας να ξέρει ποια έκδοση του δέντρου διαβάζει. Η συχνότητα ανακατασκευής είναι καθημερινή στο δωρεάν πλάνο και ωριαία στα επί πληρωμή. Ο ειλικρινής περιορισμός είναι η μη συγχρονισμένη τοπική εργασία: μια επεξεργασία που υπάρχει μόνο σε ένα τοπικό δέντρο εργασίας δεν έχει μπει ακόμα στον φιλοξενούμενο χάρτη. Αυτός ο περιορισμός είναι ίδιος ανεξαρτήτως από ποιο πρόγραμμα-πελάτη ρωτάτε, και αυτό ακριβώς είναι το νόημα. Η απόκλιση μεταξύ προγραμμάτων-πελατών δεν είναι πια ένας δεύτερος, κρυφός περιορισμός.

Η τεκμηρίωση δίνει τον βρόχο ενεργοποίησης που ισχύει για κάθε πρόγραμμα-πελάτη: ευρετηριάστε ένα αποθετήριο που ήδη γνωρίζετε, συνδέστε το πρόγραμμα-πελάτη, κάντε μία ερώτηση που μπορείτε να επαληθεύσετε. Κάντε το μία φορά στο Cursor. Κάντε το ξανά από το CLI που πραγματικά χρησιμοποιείτε τις μέρες ελέγχου. Αν και οι δύο απαντήσεις παραπέμπουν στον ίδιο χειριστή, ο χάρτης πράγματι ταξίδεψε μαζί σας.

Πώς συνυπάρχουν οι δύο χάρτες

Χρησιμοποιήστε και τους δύο. Δεν είναι εναλλακτικές με την έννοια μιας σελίδας σύγκρισης.

Κρατήστε τον μηχανισμό ευρετηρίασης του Cursor ενεργό για το έργο στον δίσκο. Αφήστε το Explore, το Instant Grep και τον πράκτορα μέσα στον επεξεργαστή να τον χρησιμοποιούν. Αυτός ο βρόχος είναι εγγενής και γρήγορος.
Προσθέστε το Maguyva ως διακομιστή MCP στο Cursor ώστε η ίδια συνεδρία να μπορεί επίσης να ρωτάει τον φιλοξενούμενο χάρτη του χώρου εργασίας. Το Cursor είναι τεκμηριωμένο πρόγραμμα-πελάτης του Maguyva. Δεν επιλέγετε ένα ευρετήριο διαγράφοντας το άλλο.
Προσθέστε τον ίδιο διακομιστή Maguyva στο Claude Code, στο Codex CLI, ή σε οποιοδήποτε άλλο πρόγραμμα-πελάτη MCP που αγγίζει το αποθετήριο. Μία μορφή κλειδιού API. Ένας χώρος εργασίας.
Αν ένας πράκτορας του CI είναι συμβατός με MCP, στρέψτε τον στον ίδιο διακομιστή. Θα διαβάσει το ίδιο στιγμιότυπο με χρονοσφραγίδα που διάβασε ο φορητός υπολογιστής σας.

Το ευρετήριο του επεξεργαστή παραμένει το καλύτερο εργαλείο για το ερώτημα «τι υπάρχει στον δίσκο σε αυτό το παράθυρο, αυτή τη στιγμή». Ο φιλοξενούμενος χάρτης είναι το καλύτερο εργαλείο για το ερώτημα «πώς φαίνεται αυτός ο χώρος εργασίας σε κάθε πράκτορα που θα τον αγγίξει σήμερα». Αυτές οι προτάσεις δεν ανταγωνίζονται.

Τα όρια χώρου εργασίας δημοσιεύονται στη σελίδα τιμών: αποθετήρια, ευρετηριασμένες γραμμές και χρήστες, χρεωμένα ανά χώρο εργασίας. Πράκτορες και άνθρωποι μοιράζονται τον ίδιο μετρητή χρηστών. Ξεκινήστε δωρεάν με ένα αποθετήριο που ήδη ξέρετε να αξιολογείτε. Αυξήστε τον χώρο εργασίας μόνο αφού οι παραπομπές επιβιώσουν την επαφή με το δέντρο.

Τι δεν ισχυρίζεται αυτή η σελίδα

Δεν ισχυρίζεται ότι ο μηχανισμός ευρετηρίασης του Cursor είναι αδύναμος, ελλιπής, ή λόγος για αλλαγή επεξεργαστή κώδικα. Η πρώτη πρόταση αυτού του κειμένου λέει το αντίθετο.

Δεν ισχυρίζεται ότι το Maguyva αντικαθιστά το Instant Grep ή τον βοηθητικό πράκτορα Explore. Αυτά είναι χαρακτηριστικά του Cursor. Παραμένουν στο Cursor.

Δεν επινοεί έναν αριθμό γλωσσών, μια τιμή καθυστέρησης, ή εξοικονόμηση tokens για κανένα από τα δύο προϊόντα. Άγνωστοι αριθμοί παραμένουν αδημοσίευτοι.

Δεν προσποιείται ότι τοπική εργασία που δεν έχει σταλεί ακόμα στο απομακρυσμένο αποθετήριο βρίσκεται στον φιλοξενούμενο χάρτη. Τα στιγμιότυπα με χρονοσφραγίδα κάνουν αυτόν τον περιορισμό ορατό. Δεν τον αφαιρούν.

Το τεστ είναι συνηθισμένο. Ευρετηριάστε ένα αποθετήριο που ήδη γνωρίζετε. Κάντε μία ερώτηση που μπορείτε να επαληθεύσετε, πρώτα στο Cursor, μετά σε ένα δεύτερο πρόγραμμα-πελάτη MCP. Ένα context που ταξιδεύει μαζί σας είναι η ίδια παραπομπή και στα δύο μέρη.

// same map, wherever you opened it.

Πρώτα ο χάρτης, μετά η αξιολόγηση

Mon, 07 Sep 2026 00:00:00 GMT

Δύο διαφορετικές δουλειές κάθονται στις δύο πλευρές ενός αιτήματος συγχώνευσης. Πριν γράψει ο πράκτορας, χρειάζεται έναν χάρτη του δέντρου που πρόκειται να αλλάξει. Αφού ο πράκτορας ανοίξει ένα PR, κάτι θα πρέπει να διαβάσει αυτή την αλλαγή σε σχέση με το υπόλοιπο σύστημα και να αφήσει σχόλια που μπορεί να αξιοποιήσει ένας άνθρωπος.

Αυτές οι δουλειές μοιάζουν από μακριά επειδή και οι δύο περιλαμβάνουν «κατανόηση της βάσης κώδικα». Δεν είναι το ίδιο προϊόν. Η μία απαντά στο «πού θα έπρεπε να προσγειωθεί αυτή η αλλαγή;». Η άλλη απαντά στο «τι έσπασε αυτό το diff που ένα εργαλείο στατικού ελέγχου γραμμή προς γραμμή θα χάσει;». Το να τις μπερδέψετε παράγει ένα χειρότερο πρώτο προσχέδιο και μια πιο θορυβώδη αξιολόγηση.

Αυτό το κείμενο είναι ένας οδηγός κοινής ροής εργασίας. Το Maguyva είναι ο χάρτης που ρωτάει πρώτος ο πράκτορας. Το Greptile είναι ο πράκτορας αξιολόγησης που σχολιάζει το PR μετά. Το δίδυμο είναι συμπληρωματικό εκ κατασκευής: το Maguyva δεν αξιολογεί αιτήματα συγχώνευσης, και το Greptile δεν αντικαθιστά το επίπεδο context που χρησιμοποίησε ο πράκτορας για να τα γράψει.

Γιατί αυτός ο διαχωρισμός είναι χρήσιμος

Ένας πράκτορας προγραμματισμού που ξεκινά από όσα έμαθε στην εκπαίδευσή του συν μερικά επικολλημένα αρχεία θα επινοήσει μια εύλογη διαδρομή αρχείου και θα την επεξεργαστεί. Αυτή είναι η αποτυχία «λάθος αρχείου», και είναι πρόβλημα ανάκτησης. Το Maguyva είναι ένα απομακρυσμένο επίπεδο MCP για το context της βάσης κώδικα: σημασιολογική, δομική (AST), γράφου/εξαρτήσεων και κειμενική ανάκτηση συγχωνεύονται σε ταξινομημένα αποτελέσματα, συν αναζήτηση συμβόλων και ανάκτηση αρχείων. Τεκμηριωμένες απαντήσεις επιστρέφουν ως path/file.ext:line, ώστε να μπορείτε να απορρίψετε ένα λάθος πριν υπάρξει patch. Ο ισχυρισμός παραμένει μετριοπαθής: λιγότερες παραισθητικές επεξεργασίες. Το μοντέλο μπορεί ακόμα να μαντέψει. Απλώς το πρώτο βήμα σταματά να είναι μαντεψιά.

Το Greptile είναι ένας πράκτορας αξιολόγησης κώδικα με AI. Με δικά τους λόγια, αξιολογεί αυτόματα κάθε αίτημα συγχώνευσης με πλήρη κατανόηση της βάσης κώδικα, και το τοποθετεί απέναντι σε παραδοσιακά εργαλεία στατικού ελέγχου που ελέγχουν αρχεία απομονωμένα αντί για ολόκληρο το σύστημα. Η ρύθμιση συνίσταται στην εγκατάσταση της εφαρμογής GitHub ή GitLab και στην επιλογή αποθετηρίων. Δεν υπάρχει τοπικό ευρετήριο που πρέπει να λειτουργείτε. Η φιλοξενία είναι στο Greptile Cloud (δηλώνουν συμμόρφωση SOC 2 Type II, με αναφορά διαθέσιμη κατόπιν αιτήματος), με επιλογή αυτοφιλοξενίας που προσφέρεται σε επιχειρήσεις.

Η δική τους αριθμημένη ροή είναι: σύνδεση και δημιουργία ενός γράφου εξαρτήσεων κάθε συνάρτησης, κλάσης και εξάρτησης· σε κάθε αίτημα συγχώνευσης, ανάλυση της αλλαγής χρησιμοποιώντας αυτόν τον πλήρη γράφο του αποθετηρίου και δημοσίευση ευρημάτων ως σχόλια PR με προτεινόμενες διορθώσεις, σε περίπου τρία λεπτά· κάθε σχόλιο μπορεί να παραδώσει το πρόβλημα σε έναν πράκτορα προγραμματισμού που η ομάδα ήδη χρησιμοποιεί. Δηλώνουν επίσης ότι διαβάζουν προηγούμενα ανθρώπινα σχόλια PR με την πάροδο του χρόνου, για να μάθουν τα πρότυπα κώδικα μιας ομάδας και να μειώσουν θορυβώδεις προτάσεις. Το σύστημα εκμάθησής τους, όπως δηλώνουν, χρειάζεται 2–3 εβδομάδες για να προσαρμοστεί.

Αυτό είναι αξιολόγηση, όχι σύνταξη. Το δυνατό σημείο του Greptile είναι το context πλήρους γράφου του αποθετηρίου πάνω στην αλλαγή που έχει ήδη προσγειωθεί σε ένα PR, και έπειτα ένας κλειστός βρόχος που στέλνει το εύρημα στα Claude Code, Codex, Conductor, Cursor ή Devin. Το δυνατό σημείο του Maguyva είναι ο ταξινομημένος χάρτης που ρώτησε ο πράκτορας πριν γραφτεί αυτή η αλλαγή. Χρησιμοποιήστε και τα δύο. Μη ζητάτε από κανένα να κάνει τη δουλειά του άλλου.

Μια επίσημη ενσωμάτωση προϊόντων Maguyva–Greptile πρώτου μέρους δεν δηλώνεται. Ούτε τη χρειάζεστε. Το Maguyva μιλάει με τον πράκτορα μέσω MCP. Το Greptile μιλάει με το GitHub ή το GitLab μέσω της εφαρμογής τους. Συναντιούνται στο αίτημα συγχώνευσης. Κανένα συνδετικό σενάριο, κανένα cron που συνδέει το ένα εργαλείο με το άλλο. Το δίδυμο δεν χρειάζεται bash επειδή κάθε προϊόν κάθεται ήδη στην επιφάνεια που του ανήκει.

Τι δεν είναι αυτό

Αυτό δεν είναι μια κατεδάφιση του Greptile. Δεν είναι μια σελίδα «αλλάξτε τον αξιολογητή σας». Το Greptile λανσαρίστηκε στο Hacker News στις 5 Μαρτίου 2024 ως εταιρεία Y Combinator W24, και εκείνο το νήμα συζήτησης είναι ο τρόπος που πολλοί άνθρωποι γνώρισαν πρώτη φορά το προϊόν. Αν έτσι τους βρήκατε, κρατήστε τους. Αυτή η σελίδα είναι το μισό που λείπει μπροστά από εκείνον τον βρόχο: να θεμελιώσετε τον πράκτορα εκ των προτέρων ώστε το PR που βλέπει το Greptile να στοχεύει ήδη τα σωστά αρχεία.

Το διαφημιστικό υλικό του Greptile προηγείται με ισχυρισμούς για ταχύτητα αξιολόγησης και εντοπισμό σφαλμάτων. Αντιμετωπίστε τους ως δικούς τους ισχυρισμούς του Greptile, όχι ως ανεξάρτητα επαληθευμένους αριθμούς. Αυτό το κείμενο δεν τους επαναλαμβάνει ως γεγονότα.

Η κάλυψη γλωσσών είναι το ίδιο είδος ειλικρίνειας. Το Greptile πλαισιώνει την υποστήριξη ως κάλυψη όλων των γλωσσών προγραμματισμού αντί για μια απαριθμημένη λίστα· ένας ακριβής αριθμός δεν δηλώνεται. Το Maguyva δημοσιεύει υποστήριξη για περισσότερες από 279 γλώσσες και τεχνολογίες βασισμένες σε κείμενο, με έναν τεχνικό διαχωρισμό (AST μέσω συντακτικού αναλυτή έναντι μόνο κειμένου) στον ιστότοπο όταν το ερώτημα είναι τεχνικό. Είναι διαφορετικά προϊόντα που κάνουν διαφορετικούς ισχυρισμούς. Μην τα ανακατεύετε.

Η τιμολόγηση του Greptile δεν δηλώνεται στο υλικό που μπορεί να χρησιμοποιήσει αυτό το κείμενο. Επί πληρωμή πλάνα υπάρχουν· δείτε τη σελίδα τιμών τους. Το Maguyva χρεώνει ανά χώρο εργασίας, όχι ανά θέση. Τα πλάνα ξεκινούν δωρεάν. Η σελίδα τιμών απαριθμεί τα δημοσιευμένα επίπεδα αν χρειάζεστε τους αριθμούς χώρου εργασίας.

Ροή εργασίας

Τρία επώνυμα στάδια. Εκτελέστε τα με αυτή τη σειρά. Μην παραλείψετε κανένα την πρώτη φορά που δοκιμάζετε αυτό το δίδυμο.

1. Context Maguyva

Ευρετηριάστε ένα αποθετήριο που ήδη γνωρίζετε. Συνδέστε το πρόγραμμα-πελάτη MCP στο οποίο ήδη γράφετε — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, ή ένα άλλο συμβατό με MCP πρόγραμμα-πελάτη. Το Maguyva έχει οδηγούς ρύθμισης για 24 τεκμηριωμένα προγράμματα-πελάτες MCP και μπορεί να συνδεθεί με άλλα προγράμματα-πελάτες που υποστηρίζουν τυπική ρύθμιση MCP.

Κάντε μια ερώτηση που μπορείτε να αξιολογήσετε πριν γράψει κανείς μια γραμμή. «Πού διαχειρίζεται η λήξη συνεδρίας, και τι το καλεί;» είναι μια καλύτερη πρώτη κίνηση από «διόρθωσε το auth». Απαιτήστε παραπομπές. Ανοίξτε τα αποτελέσματα file.ext:line. Ακολουθήστε το σύμβολο. Επιβεβαιώστε την εξάρτηση που πρόκειται να αγγίξετε.

Το Maguyva εκθέτει 11 εργαλεία MCP για το πρόγραμμα-πελάτη, που καλύπτουν αναζήτηση, σύμβολα, ανάλυση εξαρτήσεων, ανάκτηση αρχείων, context αποθετηρίου και ντετερμινιστικές ροές εργασίας βοηθητικών εργαλείων. Τέσσερις τρόποι ανάκτησης συγχωνεύονται σε ταξινομημένα αποτελέσματα· το find_symbol είναι ξεχωριστό εργαλείο όταν ήδη γνωρίζετε το όνομα. Η τεκμηρίωση περιγράφει τη συντομότερη διαδρομή: ξεκινήστε δωρεάν, ευρετηριάστε ένα αποθετήριο που ήδη γνωρίζετε, συνδέστε το πρόγραμμα-πελάτη, μετά κάντε μία ερώτηση που μπορείτε να επαληθεύσετε.

Τα στιγμιότυπα φέρουν χρονοσφραγίδα, ώστε ο πράκτορας να μπορεί να πει ποια έκδοση του δέντρου διαβάζει. Ο ειλικρινής περιορισμός είναι η μη συγχρονισμένη τοπική εργασία. Αν η επεξεργασία υπάρχει μόνο σε ένα τοπικό δέντρο εργασίας και δεν έχει σταλεί στο απομακρυσμένο αποθετήριο, ο φιλοξενούμενος χάρτης δεν την περιέχει ακόμα. Τα αρχεία οδηγιών (CLAUDE.md, AGENTS.md) εξακολουθούν να έχουν τη θέση τους εδώ, για συμβάσεις και για ό,τι δεν πρέπει να αγγίζεται. Δεν είναι ζωντανός χάρτης. Χρησιμοποιήστε τα για συμπεριφορά. Χρησιμοποιήστε το Maguyva για γεγονότα.

Μην αφήνετε τον πράκτορα να ανοίξει PR πριν οι παραπομπές επιβιώσουν την επαφή με το αποθετήριο. Αυτή η πύλη είναι όλο το νόημα αυτού του σταδίου.

2. PR του πράκτορα

Ο ίδιος πράκτορας τώρα γράφει την αλλαγή στο πρόγραμμα-πελάτη για το οποίο ήδη πληρώνετε. Το Maguyva δεν είναι επεξεργαστής κώδικα ούτε αξιολογητής. Ο πράκτορας εξακολουθεί να παράγει το diff. Εσείς εξακολουθείτε να ανοίγετε το αίτημα συγχώνευσης στο GitHub ή στο GitLab με τον τρόπο που ήδη κάνετε.

Αυτό που θα έπρεπε να είναι διαφορετικό είναι το πρώτο αρχείο. Το PR θα πρέπει να ονομάζει τον χειριστή που πράγματι υλοποιεί τη συμπεριφορά, τον καλούντα που θα σπάσει, και τη δοκιμή που θα αποτύχει αν η αλλαγή είναι λάθος. Αν το στάδιο 1 παραλείφθηκε, το στάδιο 3 θα ξοδέψει τα σχόλιά του σε μια αλλαγή που προσγειώθηκε στο λάθος πακέτο. Το Greptile μπορεί ακόμα να βρει συστημικά προβλήματα. Δεν θα έπρεπε επιπλέον να χρειάζεται να ανακάμψει από μια παραισθητική διαδρομή αρχείου.

Κρατήστε το PR περιορισμένο. Ένα τεκμηριωμένο πρώτο αρχείο δεν είναι άδεια να ξαναγράψετε την ενότητα κώδικα. Αυτό το συμπληρωματικό δίδυμο λειτουργεί όταν ο πράκτορας έκανε μια δουλειά με έναν χάρτη, και μετά ζήτησε από έναν αξιολογητή να κάνει μια άλλη δουλειά σε ένα οριοθετημένο diff.

3. Αξιολόγηση Greptile

Το Greptile είναι ήδη συνδεδεμένο με το αποθετήριο μέσω της εφαρμογής GitHub ή GitLab. Στο νέο αίτημα συγχώνευσης αναλύει την αλλαγή χρησιμοποιώντας τον πλήρη γράφο του αποθετηρίου που έχτισε, και δημοσιεύει ευρήματα ως σχόλια με προτεινόμενες διορθώσεις. Το δικό τους υλικό τοποθετεί αυτό το πέρασμα στα περίπου τρία λεπτά.

Διαβάστε τα σχόλια όπως θα διαβάζατε έναν προσεκτικό συνάδελφο ομάδας: ανοίξτε την παραπεμπόμενη τοποθεσία, αποφασίστε αν το εύρημα είναι πραγματικό, μετά ενεργήστε. Εκεί όπου το Greptile προσφέρει «Fix with your Agent», στέλνει το πρόβλημα — διαδρομές αρχείων, αριθμούς γραμμής, προτεινόμενο κώδικα — στα Claude Code, Codex, Conductor, Cursor ή Devin. Το «Fix All» στέλνει όλα τα προβλήματα της αξιολόγησης ταυτόχρονα. Παρέχουν επίσης ένα Greptile MCP και ένα πρόσθετο για το Claude Code για αυτή την παράδοση. Το Maguyva δεν βρίσκεται σε αυτή την επώνυμη λίστα στόχων· αυτή η απουσία δεν είναι πρόβλημα. Το Maguyva έχει ήδη κάνει τη δουλειά του στο στάδιο 1. Ο πράκτορας προγραμματισμού που έγραψε το PR είναι αυτός που θα έπρεπε να λάβει τα δεδομένα της διόρθωσης.

Περιμένετε θόρυβο τις πρώτες 2–3 εβδομάδες όσο το σύστημα εκμάθησης του Greptile προσαρμόζεται στα σχόλια που πραγματικά αφήνει η ομάδα σας. Αυτό είναι το δηλωμένο χρονοδιάγραμμά τους, όχι ελάττωμα του διδύμου. Η ανθρώπινη αξιολόγηση παραμένει στον βρόχο. Το Greptile είναι το αυτοματοποιημένο πρώτο πέρασμα, όχι το κουμπί της συγχώνευσης.

Αν ένα σχόλιο του Greptile δείχνει σε ένα αρχείο που ο πράκτορας δεν ρώτησε ποτέ στο στάδιο 1, αυτό είναι χρήσιμο σήμα. Είτε ο χάρτης έχασε έναν καλούντα, είτε ο πράκτορας παρέλειψε μια παραπομπή. Διορθώστε το προσχέδιο σύμφωνα με το σχόλιο. Μην απενεργοποιείτε τον αξιολογητή.

Πώς να κρατήσετε αυτή τη συμπληρωματικότητα ειλικρινή

Το Maguyva πάντα πρώτο. Μια αξιολόγηση ενός PR με λάθος αρχείο παραμένει αξιολόγηση του λάθος αρχείου.
Το Greptile πάντα μετά. Ένα καλά παραπεμπόμενο προσχέδιο χρειάζεται ακόμα μια ανάγνωση του diff σε επίπεδο ολόκληρου συστήματος.
Μη ζητάτε από το Maguyva να δημοσιεύει σχόλια PR. Δεν το κάνει.
Μη ζητάτε από το Greptile να είναι το πρώτο επίπεδο ανάκτησης του πράκτορα ενώ ακόμα επιλέγει διαδρομή αρχείου. Αυτή δεν είναι η δουλειά για την οποία είναι καλωδιωμένη η εφαρμογή τους GitHub ή GitLab.
Μην επινοείτε μια αλυσίδα σεναρίων bash που τα «συγχρονίζει». Το PR είναι η διεπαφή.
Επαληθεύστε και τις δύο πλευρές ανεξάρτητα. Ευρετηριάστε ένα αποθετήριο που ήδη γνωρίζετε. Κάντε μία ερώτηση που μπορείτε να επαληθεύσετε. Έπειτα ανοίξτε ένα μικρό PR και διαβάστε τι πραγματικά σχολιάζει το Greptile.

Ο βρόχος είναι συνηθισμένος μόλις του δώσετε όνομα. Πρώτα ο χάρτης. Μετά το PR του πράκτορα. Μετά η αξιολόγηση. Κάθε προϊόν μένει στην πλευρά του αιτήματος συγχώνευσης στην οποία είναι καλό.

// map first. review second. in that order.

Δώστε σε πράκτορα AI το πλαίσιο μεγάλου αποθετηρίου χωρίς τοπικό ευρετήριο

Fri, 14 Aug 2026 00:00:00 GMT

Ένα μεγάλο αποθετήριο δεν χωράει σε ένα παράθυρο συμφραζομένων, και αν έχετε ποτέ στρέψει έναν μηχανισμό ευρετηρίασης στον φορητό σας υπολογιστή σε ένα πραγματικό monorepo, ξέρετε ότι δεν χωράει άνετα ούτε εκεί — η RAM εκτοξεύεται, η πρώτη ευρετηρίαση παίρνει μια ώρα, και ο πράκτοράς σας εξακολουθεί να ξεκινάει την επόμενη συνεδρία μαντεύοντας ποια αρχεία έχουν σημασία.

Η συνήθης απάντηση είναι να τρέχετε έναν μηχανισμό ευρετηρίασης δίπλα στον επεξεργαστή κώδικα, και για ένα αποθετήριο που χωράει άνετα σε ένα μηχάνημα, είναι καλή απάντηση. Αν το monorepo σας ήδη ευρετηριάζεται γρήγορα στο Cursor και αυτό είναι το μόνο μέρος όπου χρειάζεστε τον χάρτη, αυτό το κείμενο δεν έχει τίποτα να προσθέσει — προσπεράστε το.

Αυτό το κείμενο αφορά την άλλη περίπτωση — όταν ένας πράκτορας χρειάζεται έναν αναζητήσιμο χάρτη ενός μεγάλου αποθετηρίου, και δεν θέλετε να τρέχετε τοπικό μηχανισμό ευρετηρίασης για να τον αποκτήσετε.

Πότε ένας τοπικός μηχανισμός ευρετηρίασης είναι το λάθος εργαλείο

Ένα τοπικό ευρετήριο υποθέτει ότι ο κώδικας ζει στο μηχάνημα που το ρωτάει, και στην κλίμακα ενός πραγματικού monorepo αυτή η υπόθεση τεντώνεται ακόμα και μέσα σε έναν μόνο επεξεργαστή κώδικα. Το αποθετήριο είναι απλώς μεγαλύτερο από όσο θέλετε να κρατάτε «ζεστό» σε έναν φορητό υπολογιστή: δουλεύετε σε ένα πακέτο ενώ η ακτίνα επίδρασης βρίσκεται τρεις καταλόγους παρακάτω, και μια πρώτη κρύα ευρετηρίαση ενός δέντρου δύο εκατομμυρίων γραμμών δεν είναι κάτι που θέλετε να περάσετε δύο φορές — ούτε στο μηχάνημά σας, ούτε σε έναν εκτελεστή CI που δεν έχει κλωνοποιήσει ποτέ πριν αυτό το δέντρο. Ή ένας συνάδελφος θα έπρεπε να μπορεί να ρωτάει τον ίδιο χάρτη με εσάς, χωρίς να περιμένει το δικό του μηχάνημα να τελειώσει τον ίδιο μόχθο ευρετηρίασης.

Τίποτα από αυτά δεν είναι λόγος να πετάξετε έναν καλό μηχανισμό ευρετηρίασης του επεξεργαστή σας. Είναι λόγος να έχετε επίσης έναν φιλοξενούμενο χάρτη που οποιοσδήποτε από τους πράκτορές σας μπορεί να ρωτήσει μέσω MCP.

Και το πρόβλημα κλίμακας πάει πιο βαθιά από «πάρα πολλά αρχεία για να επικολλήσεις». Σε ένα μεγάλο δέντρο, το ενδιαφέρον ερώτημα σχεδόν ποτέ δεν είναι «δείξε μου αυτό το αρχείο» — είναι ποιο αρχείο, ποιο σύμβολο, ποιοι καλούντες, ποιες δοκιμές. Ένας πράκτορας που ξεκινά καταγράφοντας το src/ και διαβάζοντας τα πρώτα τρία αποτελέσματα θα χάσει ευχαρίστως τον χειριστή στο apps/api και το παραγόμενο πρόγραμμα-πελάτη στο packages/sdk. Αυτό που χρειάζεστε είναι ανάκτηση χτισμένη από ολόκληρο το δέντρο, μετά ταξινομημένη, μετά παραπεμπόμενη.

Τι σημαίνει πραγματικά «context ενός μεγάλου αποθετηρίου»

Το να ρίχνετε αρχεία στην προτροπή του μοντέλου δεν είναι context — είναι ένα μικρότερο, χειρότερο αντίγραφο του δέντρου. Αυτό που πραγματικά χρειάζεται ο πράκτοράς σας είναι να κάνει ερωτήσεις και να παίρνει πίσω παραπεμπόμενες απαντήσεις: πού ορίζεται αυτό το σύμβολο και ποιος το καλεί, τι εξαρτάται από την ενότητα κώδικα που πρόκειται να αλλάξω, ποιο αρχείο δοκιμών καλύπτει αυτή τη συμπεριφορά, και πώς φαίνεται το δέντρο τώρα, όχι το προηγούμενο τρίμηνο.

Αυτές οι απαντήσεις πρέπει να προέρχονται από ένα ευρετήριο χτισμένο από το αποθετήριό σας και όχι από τη μνήμη του μοντέλου για ξένα αποθετήρια, και αυτό το ευρετήριο πρέπει να ζει κάπου έξω από το παράθυρο συμφραζομένων του πράκτορα. Για αυτό το πρόβλημα, θα έπρεπε επίσης να ζει κάπου έξω από τον φορητό υπολογιστή σας.

Ένα ακόμα πράγμα που τα αρχεία οδηγιών δεν μπορούν να κάνουν για εσάς: τα CLAUDE.md και AGENTS.md είναι το σωστό μέρος για συμβάσεις και συμπεριφορά, αλλά δεν είναι ένας ζωντανός, ταξινομημένος, αναζητήσιμος χάρτης ενός δέντρου δύο εκατομμυρίων γραμμών. Χρησιμοποιήστε κανόνες για τη συμπεριφορά· χρησιμοποιήστε ευφυΐα αποθετηρίου για τα γεγονότα.

Χτίζουμε τον χάρτη στο cloud, τον ρωτάμε από οποιοδήποτε πρόγραμμα-πελάτη

Το Maguyva είναι ένα απομακρυσμένο επίπεδο MCP για το context της βάσης κώδικα. Συνδέετε το GitHub, επιλέγετε τα αποθετήριά σας, και μπορείτε να φύγετε όσο οι ροές επεξεργασίας στο cloud αναλύουν το δέντρο, χτίζουν σύμβολα και ακμές γράφου, και διατηρούν έναν ταξινομημένο χάρτη — χωρίς ποτέ τοπικό μηχανισμό ευρετηρίασης.

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

Έπειτα συνδέετε όποιο πρόγραμμα-πελάτη ήδη χρησιμοποιείτε προσθέτοντας ένα κλειδί API στη ρύθμιση MCP του. Υπάρχουν οδηγοί ρύθμισης για 24 τεκμηριωμένα προγράμματα-πελάτες MCP, και οποιοδήποτε άλλο συμβατό με MCP πρόγραμμα-πελάτης που υποστηρίζει τυπική ρύθμιση μπορεί επίσης να συνδεθεί. Αν το Cursor είναι το σπίτι σας, η σελίδα Cursor διανύει αυτή τη διαδρομή· ο ίδιος διακομιστής απαντά στα Claude Code, VS Code, Windsurf, Codex CLI και τα υπόλοιπα.

Δεν αλλάζετε επεξεργαστή κώδικα. Δίνετε στον πράκτορά σας μια επιφάνεια εργαλείων — 11 εργαλεία MCP για αναζήτηση, σύμβολα, ανάλυση εξαρτήσεων, ανάκτηση αρχείων και context αποθετηρίου — με κάλυψη πάνω από 279 γλώσσες και τεχνολογίες βασισμένες σε κείμενο, κάτι που μετράει περισσότερο απ’ όσο νομίζετε σε ένα monorepo που έχει πάψει να είναι μονόγλωσσο εδώ και χρόνια.

Οι απαντήσεις επιστρέφουν τεκμηριωμένες, ως διαδρομές αρχείων με αριθμούς γραμμής. Η σημασιολογική, δομική, γράφου και κειμενική αναζήτηση συγχωνεύονται σε ταξινομημένα αποτελέσματα, ώστε μια ερώτηση όπως «τι εξαρτάται από το parseConfig» να μη σας δίνει ούτε έναν σωρό αποτελεσμάτων grep ούτε ένα μόνο σημασιολογικό απόσπασμα, αλλά τη χούφτα των τοποθεσιών που πραγματικά έχουν σημασία.

Ένας συγκεκριμένος οδηγός

Μην ξεκινάτε ευρετηριάζοντας όλη την εταιρεία. Να η διαδρομή που δουλεύει:

Διαλέξτε ένα αποθετήριο που ήδη γνωρίζετε καλά — ένα πακέτο που μπορείτε να αξιολογήσετε με το χέρι αξίζει περισσότερο από το μεγαλύτερο δέντρο που έχετε.
Ξεκινήστε δωρεάν: 3 αποθετήρια, 50χιλ ευρετηριασμένες γραμμές, όλα τα 11 εργαλεία, χωρίς μηνιαία ποσόστωση ερωτημάτων. Αν το αντιπροσωπευτικό σας αποθετήριο είναι μεγαλύτερο, η σελίδα τιμών απαριθμεί τα επίπεδα χώρου εργασίας ($0, $19, $49, $149) κατά ευρετηριασμένη έκταση — όχι κατά αριθμό θέσεων.
Συνδέστε το GitHub και περιμένετε να ολοκληρωθεί η πρώτη ευρετηρίαση. Δεν μεταγλωττίζετε τίποτα τοπικά.
Συνδέστε το πρόγραμμα-πελάτη MCP — λίγες γραμμές ρύθμισης. Το Maguyva είναι απομακρυσμένος διακομιστής MCP, οπότε δεν υπάρχουν πρόσθετα, δεν υπάρχουν επεκτάσεις, και δεν υπάρχει δεύτερος επεξεργαστής κώδικα να υιοθετήσετε.
Κάντε μία ερώτηση που μπορείτε να επαληθεύσετε. «Τι εξαρτάται από το parseConfig;» ή «Πού διαχειρίζεται η λήξη της συνεδρίας σύνδεσης;» Έπειτα ανοίξτε τα παραπεμπόμενα αποτελέσματα file.ext:line και ελέγξτε τα ως προς το δέντρο μπροστά σας.
Μόνο αφού οι παραπομπές επιβιώσουν αυτή την επαφή, αφήστε τον πράκτορα να επεξεργαστεί.

Αν το πρώτο αποθετήριο ταιριάζει καλά και το δέντρο σας είναι μεγάλο, ανεβάστε τον χώρο εργασίας ώστε να ταιριάζει με τις ευρετηριασμένες γραμμές σας και τον ρυθμό ανακατασκευής. Άνθρωποι και πράκτορες μοιράζονται τον ίδιο μετρητή χρηστών — το Maguyva χρεώνει ανά χώρο εργασίας, όχι ανά θέση — οπότε η προσθήκη ενός τρίτου πράκτορα στον βρόχο δεν σας κοστίζει τίποτα.

Το τεστ ενεργοποίησης είναι το ίδιο που συνιστά η τεκμηρίωση για κάθε πρώτη εκτέλεση: ευρετηριάστε ένα αποθετήριο που ήδη γνωρίζετε, κάντε μία ερώτηση που μπορείτε να επαληθεύσετε. Ένα μεγάλο αποθετήριο δεν αλλάζει το τεστ· απλώς κάνει ένα λάθος πρώτο αρχείο πιο ακριβό.

Τι να προσέχετε αφού συνδεθείτε

Προσέξτε τρία πράγματα. Φρεσκάδα: τα επί πληρωμή πλάνα ξαναχτίζονται ωριαία, τα δωρεάν καθημερινά, και η τοπική εργασία που δεν έχει σταλεί στο απομακρυσμένο αποθετήριο δεν θα βρίσκεται στον χάρτη — αυτό είναι το αντάλλαγμα που αποδέχεστε. Εμβέλεια: ευρετηριάστε ένα αντιπροσωπευτικό σύνολο αποθετηρίων, όχι κάθε αρχειοθετημένο παράγωγο αποθετήριο· το δωρεάν επίπεδο έχει σκόπιμα το μέγεθος που έχει, ώστε να μάθετε αν οι απαντήσεις αξίζουν να διατηρηθούν. Και επαλήθευση: ένας χάρτης μεγάλου αποθετηρίου που δεν μπορεί να παραπέμψει σε διαδρομές αρχείων και αριθμούς γραμμής είναι απλώς μια πιο αργή μηχανή εικασίας, οπότε βάλτε τον πράκτορά σας να δείξει την τοποθεσία πριν παραδώσει το patch.

Έπειτα τρέξτε το ίδιο τεστ που θα τρέχατε σε ένα μικρό αποθετήριο. Ευρετηριάστε ένα αποθετήριο που ήδη γνωρίζετε. Κάντε μία ερώτηση που μπορείτε να επαληθεύσετε. Αν ο χάρτης είναι αληθινός, ο πράκτοράς σας σταματάει να ξεκινά από ένα κρύο δέντρο.

// no laptop got hot building this map.

Γιατί ο πράκτορας προγραμματισμού AI σας επινοεί διαδρομές αρχείων

Fri, 14 Aug 2026 00:00:00 GMT

Το τεκμήριο δεν είναι ένα λάθος σώμα συνάρτησης. Είναι μια σίγουρη επεξεργασία σε ένα αρχείο που δεν υπάρχει, ή σε ένα αρχείο που υπάρχει αλλά δεν είναι αυτό που υλοποιεί τη συμπεριφορά.

Ζητήσατε μια διόρθωση λήξης συνεδρίας. Ο πράκτορας άνοιξε το src/auth/session.ts. Αυτή η διαδρομή είναι εύλογη. Είναι επίσης λάθος. Ο πραγματικός χειριστής ζει στο apps/api/src/middleware/expiry.ts, που μετονομάστηκε πριν από δύο αναδιαμορφώσεις κώδικα. Ο πράκτορας δεν σας είπε ψέματα. Συμπλήρωσε μια συμβολοσειρά σε σχήμα διαδρομής από όσα έμαθε στην εκπαίδευσή του συν ό,τι ήδη υπήρχε στο παράθυρο συμφραζομένων.

Αυτό είναι το συνηθισμένο μοτίβο αποτυχίας σε ένα πραγματικό αποθετήριο. Το μοντέλο ξέρει να γράφει κώδικα. Το λάθος είναι στην επιλογή του λάθος μέρους για να τον γράψει.

Γιατί οι πράκτορες επινοούν διαδρομές αρχείων

Ένας πράκτορας προγραμματισμού είναι ένα μοντέλο πρόβλεψης επόμενου token με εργαλεία. Όταν λέτε «διόρθωσε τη λήξη συνεδρίας», πρέπει να ονομάσει ένα αρχείο πριν μπορέσει να διαβάσει ή να κάνει patch σε οτιδήποτε. Αν δεν έχει ήδη έναν θεμελιωμένο χάρτη, κατασκευάζει μια διαδρομή από:

Συμβάσεις ονομασίας που έχει δει σε άλλα αποθετήρια. Το src/auth/session.ts είναι συχνό σχήμα.
Αρχεία ήδη παρόντα στη συνομιλία, που μπορεί να είναι αυτά που επικολλήσατε την περασμένη εβδομάδα, όχι αυτά που μετράνε τώρα.
Λίστες καταλόγων που έτυχε να τρέξει, ελλιπείς σε ένα μεγάλο δέντρο.
Αρχεία οδηγιών. Τα CLAUDE.md και AGENTS.md λένε στον πράκτορα πώς να συμπεριφέρεται. Δεν είναι ζωντανό ευρετήριο συμβόλων, καλούντων ή τρεχουσών διαδρομών.

Καμία από αυτές τις πηγές δεν είναι χάρτης αυτού του αποθετηρίου, σήμερα. Το μοντέλο γεμίζει το κενό όπως γεμίζει κάθε κενό: με μια συνέχεια υψηλής πιθανότητας. Αυτή η συνέχεια συχνά μοιάζει με πραγματική διαδρομή. Μερικές φορές το αρχείο υπάρχει και βρίσκεται δίπλα στο σωστό. Μερικές φορές υπήρχε σε έναν κλάδο που συγχωνεύθηκε τον περασμένο μήνα. Μερικές φορές δεν υπήρξε ποτέ.

Το grep δεν σας σώζει εδώ αν ο πράκτορας δεν αναζητά καν τη σωστή συμβολοσειρά. Ο πράκτορας μάντεψε μια διαδρομή, μετά διάβασε ό,τι επέστρεψε εκείνη η διαδρομή, μετά το επεξεργάστηκε. Το πρώτο λάθος βήμα ήταν η διαδρομή, όχι το patch.

Το να διαβάζετε αρχεία επίσης δεν είναι το ίδιο με το να βρίσκετε τα σωστά. Τα Claude Code, Cursor, Codex και παρόμοια εργαλεία μπορούν να ανοίξουν οτιδήποτε τους δείξετε. Το ερώτημα είναι αν βρίσκουν αξιόπιστα τα σωστά αρχεία, τα σημαντικά σύμβολα, τις εξαρτήσεις, τις δοκιμές, και την ακτίνα επίδρασης πριν επεξεργαστούν. Η πρόσβαση σε αρχεία χωρίς χάρτη εξακολουθεί να ξεκινά με μαντεψιά.

Η επεξεργασία λάθος αρχείου είναι πρόβλημα ανάκτησης

Αντιμετώπισε την επινοημένη διαδρομή ως λάθος ανάκτησης, όχι ως ελάττωμα χαρακτήρα.

Αν ο πράκτορας έπρεπε να επιστρέψει path/file.ext:line πριν του επιτραπεί να επεξεργαστεί, θα συνέβαιναν δύο πράγματα. Πρώτον, θα μπορούσατε να ανοίξετε την παραπομπή και να απορρίψετε τη δουλειά σε δέκα δευτερόλεπτα. Δεύτερον, ο πράκτορας θα έπρεπε να ρωτήσει κάτι που πράγματι γνωρίζει το δέντρο.

Αυτή είναι η δουλειά ενός επιπέδου context για τη βάση κώδικα. Η σημασιολογική αναζήτηση μόνη της δεν αρκεί. Ένα κομμάτι που «ακούγεται σαν λήξη συνεδρίας» μπορεί ακόμα να προσγειωθεί σε ένα ξεπερασμένο πακέτο. Χρειάζεστε επίσης ακριβές κείμενο όταν ξέρετε τη συμβολοσειρά, αναζήτηση συμβόλων όταν ξέρετε το όνομα, δομική αναζήτηση όταν ξέρετε το σχήμα, και έναν γράφο εξαρτήσεων όταν χρειάζεστε καλούντες και ακτίνα επίδρασης.

Το Maguyva είναι αυτό το επίπεδο για πράκτορες προγραμματισμού συμβατούς με MCP. Δεν είναι επεξεργαστής κώδικα. Τα Claude Code, Cursor, Codex CLI, VS Code, Windsurf και άλλα προγράμματα-πελάτες MCP παραμένουν εκεί που είναι. Ο πράκτορας ρωτά έναν ταξινομημένο χάρτη πριν αγγίξει μια γραμμή.

Ο ισχυρισμός είναι σκόπιμα μετριοπαθής: λιγότερες παραισθητικές επεξεργασίες. Το Maguyva δεν αφαιρεί από το μοντέλο την ικανότητα να μαντεύει. Αλλάζει το προεπιλεγμένο πρώτο βήμα από «επινόησε μια εύλογη διαδρομή» σε «ζήτησε ταξινομημένες, παραπεμπόμενες τοποθεσίες».

Πώς μοιάζει μια θεμελιωμένη απάντηση

Μια χρήσιμη απάντηση στο «πού διαχειρίζεται η λήξη συνεδρίας» δεν είναι μια παράγραφος. Είναι μια σύντομη λίστα τοποθεσιών:

apps/api/src/middleware/expiry.ts:48 - ο χειριστής
apps/web/src/lib/auth-client.ts:112 - ο καλών
apps/api/tests/expiry.test.ts:20 - η δοκιμή που θα αποτύχει αν η αλλαγή είναι λάθος

Μπορείτε να ανοίξετε αυτές τις γραμμές. Αν είναι λάθος, σταματάτε. Αν είναι σωστές, ο πράκτορας μπορεί να επεξεργαστεί. Η επαλήθευση είναι το θέμα, όχι ένα σύνθημα.

Το Maguyva εκθέτει 11 εργαλεία MCP για το πρόγραμμα-πελάτη, που καλύπτουν αναζήτηση, σύμβολα, ανάλυση εξαρτήσεων, ανάκτηση αρχείων, context αποθετηρίου και ντετερμινιστικές ροές εργασίας βοηθητικών εργαλείων. Τέσσερις τρόποι ανάκτησης (σημασιολογικός, δομικός, γράφου/εξαρτήσεων και κειμενικός) συγχωνεύονται σε ταξινομημένα αποτελέσματα· η αναζήτηση συμβόλων είναι ξεχωριστό εργαλείο MCP (find_symbol). Θεμελιωμένες απαντήσεις επιστρέφουν με διαδρομές αρχείων και αριθμούς γραμμής, ώστε να μπορείτε να τις βαθμολογήσετε ως προς το δέντρο μπροστά σας.

Η τεκμηρίωση περιγράφει τη συντομότερη διαδρομή: ξεκινήστε δωρεάν, ευρετηριάστε ένα αποθετήριο που ήδη γνωρίζετε, συνδέστε το πρόγραμμα-πελάτη, μετά κάντε μία ερώτηση που μπορείτε να επαληθεύσετε.

Ένας βρόχος που αλλάζει την πρώτη επεξεργασία

Δεν χρειάζεστε μια νέα θρησκεία ροής εργασίας. Χρειάζεστε ένα επιπλέον βήμα πριν την πρώτη εγγραφή.

Κάντε μια ερώτηση που ήδη μπορείτε να αξιολογήσετε. «Ποιος κώδικας διαχειρίζεται τη σύνδεση και τη λήξη συνεδρίας;» είναι καλύτερο από «διόρθωσε το auth».
Απαιτήστε παραπομπές. Διαδρομή αρχείου και αριθμό γραμμής, όχι μια περίληψη της «ενότητας αυθεντικοποίησης».
Ανοίξτε τα παραπεμπόμενα αρχεία. Ακολουθήστε το σύμβολο. Επιβεβαιώστε την εξάρτηση που πρόκειται να αγγίξετε.
Μόνο τότε αφήστε τον πράκτορα να κάνει patch.

Αν το βήμα 2 δεν επιστρέψει τίποτα χρήσιμο, ο πράκτορας δεν έχει δικαίωμα να αυτοσχεδιάσει μια διαδρομή. Ξαναψάχνει, ή του δείχνετε εσείς. Ακριβώς αυτή η μία πύλη είναι που παράγει λιγότερες παραισθητικές επεξεργασίες. Το μοντέλο είναι το ίδιο μοντέλο. Ο χάρτης είναι αυτό που άλλαξε.

Τα αρχεία οδηγιών εξακολουθούν να έχουν σημασία. Κρατήστε τα. Χρησιμοποιήστε τα για συμβάσεις, κανόνες αξιολόγησης, και για ό,τι δεν πρέπει να αγγίζεται. Μην τους ζητάτε να είναι το ευρετήριο. Ένα CLAUDE.md που απαριθμεί τρεις σημαντικούς καταλόγους θα είναι ξεπερασμένο μια εβδομάδα μετά τη διάσπαση ενός πακέτου. Ένας αναζητήσιμος χάρτης ενημερώνεται όταν ενημερώνεται το αποθετήριο.

Μια συναφής αποτυχία είναι το σχεδόν-σωστό αρχείο: ο πράκτορας ανοίγει το auth.ts ενώ η συμπεριφορά ζει στο auth-client.ts, ή κάνει patch σε ένα παραγόμενο αρχείο αντί για την πηγή, ή επεξεργάζεται το αντίγραφο στο packages/legacy επειδή το όνομα ταίριαξε. Οι παραπομπές δεν κάνουν αυτά τα λάθη αδύνατα. Τα κάνουν ορατά πριν προσγειωθεί το diff.

Τι δεν θα διορθώσει ένας χάρτης για εσάς

Να είστε νηφάλιοι για το τι παίρνετε. Ένας θεμελιωμένος χάρτης δεν θα κάνει κάθε επεξεργασία σωστή — ο πράκτοράς σας μπορεί ακόμα να γράψει ένα κακό patch ακριβώς στο σωστό αρχείο. Αν η βάση κώδικά σας στηρίζεται σε δυναμική αποστολή κλήσεων, ανάκλαση ή μπαλώματα κώδικα κατά την εκτέλεση, κάποιες αναζητήσεις συμβόλων θα επιστρέφουν πιο φτωχές από όσο θα θέλατε, επειδή αυτό ακριβώς κάνει η έμμεση αναφορά κατά τον χρόνο εκτέλεσης σε κάθε στατικό ευρετήριο. Και αν ελπίζετε σε ένα ποσοστό — «παραισθητικές διαδρομές μειωμένες κατά X%» — δεν θα το βρείτε εδώ, επειδή κανείς εκτός από εσάς δεν μπορεί να μετρήσει ειλικρινά αυτόν τον αριθμό για το αποθετήριό σας.

Αυτό που μπορείτε να περιμένετε είναι στενότερο και πιο χρήσιμο: ο πράκτορας σταματά να ξεκινά τις επεξεργασίες του με μια μαντεμένη διαδρομή. Αυτό το πρώτο βήμα θεμελιώνεται σε έναν πραγματικό χάρτη, και από εκεί προέρχονται οι λιγότερες παραισθητικές επεξεργασίες. Όλα μετά την παραπομπή — η ανάγνωση του diff, η κρίση του patch — παραμένουν δουλειά σας, όπως πάντα ήταν.

Το τεστ δεν σας κοστίζει σχεδόν τίποτα: ευρετηριάστε ένα αποθετήριο που ήδη γνωρίζετε και κάντε μία ερώτηση που μπορείτε να επαληθεύσετε. Ξεκινήστε με μια διαδρομή που σας έχει κάψει στο παρελθόν. Αν οι παραπομπές είναι λάθος, θα το δείτε αμέσως. Αν είναι σωστές, η επόμενη επεξεργασία του πράκτορά σας έχει καλύτερο μέρος να προσγειωθεί.

// it doesn't know the file. it knows how to find it.

Γιατί Αναβαθμίσαμε την Αναζήτηση Κώδικα σε voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

Οι βαθμολογίες των benchmarks σε αυτή την ανάρτηση αντικατοπτρίζουν τους πίνακες κατάταξης RTEB κατά τη δημοσίευση (Ιούνιος 2026). Οι πίνακες κατάταξης αλλάζουν· αντιμετωπίστε τις κατατάξεις ως στιγμιότυπο, όχι ως μόνιμο γεγονός.

Η ποιότητα της σημασιολογικής αναζήτησης εξαρτάται από τα ενσωματώματα στα οποία βασίζεται.

Όταν ένας πράκτορας ρωτά το Maguyva «πού χειριζόμαστε τις επαναλήψεις αποτυχημένων προσπαθειών», δεν κάνει grep για τη λέξη «retry». Ζητά το νόημα — τον βρόχο σταδιακής αναμονής μεταξύ προσπαθειών, τον μηχανισμό διακοπής κλήσεων μετά από επανειλημμένες αποτυχίες, το περιτύλιγμα γύρω από μια ασταθή κλήση. Αυτή η ερώτηση απαντιέται από ένα διανυσματικό μοντέλο που μετατρέπει τον κώδικα σε ένα σημείο στον χώρο και βρίσκει τους γείτονές του. Επιλέξτε ένα καλύτερο μοντέλο και κάθε σημασιολογικό ερώτημα στο προϊόν γίνεται σιωπηλά πιο ακριβές.

Έτσι αλλάξαμε το δικό μας. Από τον Ιούνιο του 2026, τα ενσωματώματα κώδικα του Maguyva τρέχουν πάνω στο voyage-4-large, αντικαθιστώντας το voyage-code-3.

Το Benchmark

Δεν πήραμε αυτή την απόφαση με διαίσθηση. Το δημόσιο Benchmark Ενσωματωμάτων Ανάκτησης (RTEB) κατατάσσει μοντέλα ενσωματωμάτων σε πραγματικές εργασίες ανάκτησης, και στον πίνακα κατάταξης Code το voyage-4-large βρίσκεται στην #1 θέση συνολικά (90,86) — μπροστά από το gemini-embedding-2-preview (90,26) και, αξιοσημείωτα, μπροστά από το μοντέλο που ήδη χρησιμοποιούσαμε, το voyage-code-3 (89,73, #3).

Αυτό είναι μια μικρή απόλυτη διαφορά. Όμως είναι μια διαφορά προς τη σωστή κατεύθυνση, σε ένα δημόσιο benchmark, στην ακριβή εργασία που μας ενδιαφέρει: την ανάκτηση κώδικα βάσει νοήματος.

Ο Συμβιβασμός που Αποδεχόμαστε: Δυαδική Κβάντιση

Εδώ είναι το κομμάτι που οι περισσότερες αναρτήσεις τύπου «αναβαθμίσαμε το μοντέλο μας» παραλείπουν.

Το Maguyva δεν αποθηκεύει διανύσματα πλήρους ακρίβειας. Αποθηκεύουμε ενσωματώματα με δυαδική κβάντιση: κάθε διάνυσμα 2048 διαστάσεων συμπτύσσεται σε μια υπογραφή 2048 μπιτ — 256 μπάιτ ανά διάνυσμα. Αυτές οι υπογραφές αναζητούνται με απόσταση Hamming, ευρετηριασμένες και κατατμημένες ανά tenant.

Αυτό είναι ένας σκόπιμος συμβιβασμός. Η δυαδική κβάντιση θυσιάζει κάποια ακρίβεια ανάκτησης σε αντάλλαγμα για δραματικά μικρότερη αποθήκευση και γρήγορους, φθηνούς υπολογισμούς απόστασης χωρίς να χρειάζεται ξεχωριστή βάση δεδομένων διανυσμάτων για λειτουργία. Για ένα προϊόν που ευρετηριάζει ολόκληρα αποθετήρια ανά χώρο εργασίας, αυτή η οικονομία έχει μεγαλύτερη σημασία από το να αποσπάσετε το τελευταίο κλάσμα μιας μονάδας σε ένα benchmark.

Το voyage-4-large ταιριάζει σε αυτόν τον σχεδιασμό χωρίς να επιβάλλει μετάβαση του επιπέδου αποθήκευσης: παράγει έξοδο 2048 διαστάσεων, όπως ακριβώς και το voyage-code-3, οπότε οι στήλες bit(2048) και η διαδρομή αναζήτησης Hamming δεν άλλαξαν. Το μοντέλο έγινε καλύτερο· το σχήμα παρέμεινε ίδιο.

Ο Κώδικας Ήταν Μόνο η Αρχή

Το Maguyva είναι ένα εργαλείο ευφυΐας κώδικα. Όμως είμαστε επίσης ο δικός μας πρώτος πελάτης, και το στρέφουμε και σε κάτι άλλο: το markdown που ζει στα αποθετήριά μας δίπλα στον κώδικα. Αρχεία αρχιτεκτονικών αποφάσεων, οδηγούς λειτουργίας, συμβόλαια, οικονομικά και έγγραφα πολιτικής — όλα υπό έλεγχο εκδόσεων στο Git, όλα πίσω από τον ίδιο διακομιστή MCP, ένα σημασιολογικό ευρετήριο πάνω στα έγγραφα, όχι μόνο στον πηγαίο κώδικα.

Γι’ αυτό ακριβώς έχει σημασία το εύρος του voyage-4-large. Στην ίδια οικογένεια πινάκων κατάταξης RTEB βρίσκεται στην #1 θέση στα οικονομικά, #1 στην υγεία και #1 στη συνολική ανάκτηση κειμένου — μπροστά από το Gemini Embedding της Google, το Embed v4 της Cohere και το text-embedding-3-large της OpenAI. (Η Voyage είναι συνδημιουργός του RTEB, οπότε το διαβάζουμε ως ισχυρό δημόσιο σήμα και όχι ως απόλυτα ουδέτερο διαιτητή — όμως αξιολογείται σε άμεση σύγκριση έναντι κάθε μεγάλου εμπορικού μοντέλου, σε μη δημόσια σύνολα δεδομένων που έχουν κρατηθεί για αξιολόγηση.) Το ίδιο ευρετήριο που βρίσκει τη σωστή συνάρτηση για έναν πράκτορα βρίσκει και τη σωστή ρήτρα σε ένα συμβόλαιο ή τη σωστή γραμμή σε μια πολιτική — και σε αυτούς τους τομείς, το voyage-4-large δεν είναι συμβιβασμός, είναι ο ηγέτης.

Γιατί Πληρώνουμε για Ενσωματώματα Πρέμιουμ

Υπάρχει ένας φθηνότερος τρόπος για να κάνετε αναζήτηση, και μεγάλο μέρος του είναι δωρεάν. Η λεξιλογική αναζήτηση — το BM25 και συγγενικά του — αντιστοιχίζει λέξεις-κλειδιά, τρέχει τοπικά και δεν κοστίζει τίποτα. Ανοιχτού κώδικα μοντέλα ενσωματωμάτων όπως τα BGE, Nomic και embeddinggemma προσφέρουν γνήσια αξιοπρεπή σημασιολογική ανάκτηση, και μπορείτε να τα φιλοξενήσετε μόνοι σας για το κόστος μιας GPU. Το Maguyva χρησιμοποιεί και τη δωρεάν πλευρά: κάθε ερώτημα συγχωνεύει αναζήτηση κειμένου, AST, γράφου και σημασιολογική αναζήτηση. Αυτό στο οποίο δεν τσιγκουνευόμαστε είναι το σημασιολογικό επίπεδο.

Πληρώνουμε ανά token για ενσωματώματα πρέμιουμ — voyage-4-large — αντί να φιλοξενήσουμε μόνοι μας ένα δωρεάν μοντέλο, για δύο λόγους. Πρώτον, η αναζήτηση μόνο με λέξεις-κλειδιά δεν μπορεί να απαντήσει στο «πού χειριζόμαστε τις επαναλήψεις αποτυχημένων προσπαθειών» όταν ο κώδικας λέει backoff και circuit breaker και ποτέ δεν λέει τη λέξη «retry» — η αποτύπωση του νοήματος είναι ο βασικός σκοπός του ενσωματώματος, και στους τομείς που εξυπηρετούμε τα ανοιχτά μοντέλα υστερούν έναντι των πρέμιουμ: μερικές μονάδες πίσω σε γενικό κείμενο, και ακόμη πιο πίσω σε εξειδικευμένους τομείς όπως ο κώδικας, τα συμβόλαια και τα οικονομικά. Δεύτερον, από την εμπειρία μας η ποιότητα ανάκτησης διαμορφώνει την τελική απάντηση περισσότερο από το μοντέλο στην άλλη άκρη — ένας ισχυρός πράκτορας στον οποίο δίνεται λάθος πλαίσιο εξακολουθεί να απαντά λάθος, και ποτέ δεν βλέπει το έγγραφο που ποτέ δεν του δόθηκε.

Έτσι τα ενσωματώματα πρέμιουμ είναι ένας λογαριασμός ανά token που κλιμακώνεται με κάθε αποθετήριο και έγγραφο που ευρετηριάζουμε — και τον πληρώνουμε σκόπιμα. Για το αποτέλεσμα που παίρνουν οι χρήστες μας, τη σωστή συνάρτηση ή τη σωστή ρήτρα, πιστεύουμε ότι αυτός ο συμβιβασμός αξίζει.

Το Ειλικρινές Κομμάτι

Η ίδια η τεκμηρίωση της Voyage εξακολουθεί να χαρακτηρίζει το voyage-code-3 ως το μοντέλο βελτιστοποιημένο για κώδικα. Γιατί λοιπόν να αλλάξουμε;

Επειδή διαβάζουμε το δημόσιο benchmark, όχι μόνο τον πίνακα μοντέλων του προμηθευτή, και το benchmark έβαλε το voyage-4-large στην κορυφή για ανάκτηση κώδικα. Αυτή ήταν μια απόφαση με βλέμμα στο μέλλον: πάρτε το νεότερο, γενικά ισχυρότερο μοντέλο και επικυρώστε το έναντι ενός δημόσιου πίνακα κατάταξης στις εργασίες που έχουν σημασία. Νιώθουμε άνετα να κάνουμε αυτό το στοίχημα επειδή τα στοιχεία είναι ευρεία — το voyage-4-large δεν κερδίζει μόνο στον κώδικα, ηγείται και στα οικονομικά, στην υγεία και στη συνολική ανάκτηση.

Το Σιωπηλό Θεμέλιο

Κάθε εργαλείο που εκθέτουμε — σημασιολογική αναζήτηση, συλλογή πλαισίου εργασίας, τεκμηριωμένες ερωτοαπαντήσεις — βασίζεται στην ανάκτηση. Όταν ο ανακτητής βελτιώνεται, ο πράκτορας στην άλλη άκρη παίρνει καλύτερα στοιχεία, ακολουθεί λιγότερες λανθασμένες κατευθύνσεις και τεκμηριώνει τις απαντήσεις του στον σωστό κώδικα — ή στη σωστή ρήτρα, ή στη σωστή πολιτική. Ένα πιο ακριβές μοντέλο ενσωματωμάτων δεν είναι ένα εντυπωσιακό χαρακτηριστικό. Είναι το θεμέλιο κάτω από όλα τα υπόλοιπα, και μόλις το ενισχύσαμε. Δεν θα το προσέξετε. Αυτό είναι το νόημα.

Αναδρομική Αυτο-βελτίωση Γλωσσών: Βελτιώνοντας Αδιάκοπα την Ευφυΐα Κώδικα σε ~280 Γλώσσες

Tue, 26 May 2026 00:00:00 GMT

Οι αριθμοί σε αυτή την ανάρτηση αντικατοπτρίζουν το σύστημα κατά τη δημοσίευση (Μάιος 2026). Δείτε τη σελίδα ομάδας μας για τα τρέχοντα στοιχεία.

Το Maguyva εξάγει σύμβολα, αναφορές και έναν γράφο εξαρτήσεων από πηγαίο κώδικα σε περίπου 280 γλώσσες. Κάθε γλώσσα είναι ένας προσαρμοσμένος χειριστής tree-sitter — ερωτήματα, ευρετικοί κανόνες, οριακές περιπτώσεις — και κάθε χειριστής μπορεί να κάνει τα δικά του δυσδιάκριτα λάθη. Μια κλήση μεθόδου που καταγράφεται ως ανάγνωση. Μια συνάρτηση που αποδίδεται στο λάθος περιβάλλον εμβέλειας. Μια σχέση που απλώς δεν υπάρχει.

Αυτό δεν μπορείτε να το ελέγξετε χειροκίνητα. Καμία ομάδα δεν μπορεί να διαβάσει έξοδο εξαγωγής σε 280 γραμματικές και να εντοπίσει τις κακές ακμές. Οπότε το ενδιαφέρον ερώτημα δεν είναι «είναι σωστή η εξαγωγή μας» — είναι «πώς ανακαλύπτεις ότι είναι λάθος, σε αυτό το εύρος, χωρίς άνθρωπο σε κάθε βρόχο». Η απάντησή μας είναι η αναδρομική αυτο-βελτίωση γλωσσών: ένας βρόχος ποιότητας που κινείται από πράκτορες γλωσσών, ένα LLM που δρα ως κριτής, και έναν κανόνα που συνεχώς ξαναμαθαίνουμε: το πράσινο δεν είναι το ίδιο με το σωστό.

Το πράσινο δεν είναι σωστό

Κάθε γλώσσα έχει μια σουίτα fixtures, και μια πύλη έκδοσης τη βαθμολογεί σε πέντε διαστάσεις — ακρίβεια, δομική ακεραιότητα, πληρότητα, ποιότητα και απόδοση. Μια γλώσσα γίνεται ΠΡΑΣΙΝΗ μόνο όταν, στα fixtures της, η ακρίβεια ≥ 0,95, η ανάκληση ≥ 0,99, και το F1 ≥ 0,97, με τουλάχιστον 20 αναμενόμενες ακμές για στατιστική εμπιστοσύνη. Κάτω από αυτό είναι ΚΙΤΡΙΝΗ ή ΚΟΚΚΙΝΗ, και δεν κυκλοφορεί.

Αυτή η πύλη είναι αναγκαία αλλά όχι επαρκής. Τα fixtures επικυρώνονται έναντι fixtures που εμείς γράψαμε. Κωδικοποιούν τις περιπτώσεις που ήδη είχαμε σκεφτεί. Ένας χειριστής μπορεί να είναι άψογος στα fixtures του και παρόλα αυτά να παραμορφώνει ένα μοτίβο που εμφανίζεται μόνο σε πραγματικό κώδικα — έναν ιδιωματισμό μακροεντολής, μια μέθοδο με περιορισμούς γενικών τύπων, ένα χαρακτηριστικό γλώσσας για το οποίο κανείς δεν έγραψε fixture. ΠΡΑΣΙΝΟ σημαίνει ότι περνούν τα fixtures. Δεν σημαίνει ότι ένα πραγματικό αποθετήριο εξάγεται καθαρά. Οπότε ο βρόχος πρέπει να αφήσει πίσω τα fixtures και να εξετάσει πραγματικές βάσεις κώδικα.

Ο εσωτερικός βρόχος: δειγματοληπτικός έλεγχος, κρίση, διόρθωση, απόδειξη

Ο πυρήνας του βρόχου τρέχει μία γλώσσα τη φορά:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

Μερικά πράγματα κάνουν αυτό να λειτουργεί αντί να στροβιλίζεται χωρίς αποτέλεσμα.

Ο κριτής είναι ο πράκτορας, όχι μια κλήση API. Όταν λέμε «LLM ως κριτής», εννοούμε ότι ο ίδιος ο πράκτορας γλώσσας διαβάζει κάθε δειγματισμένη ακμή έναντι της πραγματικής πηγής και την ταξινομεί με μια σταθερή κλίμακα πέντε κατηγοριών: είναι αυτή η ακμή σωστή, ένα ψευδώς θετικό, η σωστή σχέση με λάθος τύπο, συνδεδεμένη στη λάθος εμβέλεια, ή φέρει λάθος μεταδεδομένα; Αυτή η κλίμακα είναι όλο το παιχνίδι — το «23% ποσοστό σφάλματος» δεν σημαίνει τίποτα μέχρι να ξέρετε αν πρόκειται για πραγματικά ελαττώματα ή για λάθος μέτρημα του κριτή.

Διορθώστε ένα πράγμα, μετά αποδείξτε το. Κάθε επανάληψη αλλάζει ακριβώς ένα επεξεργάσιμο στοιχείο, μετά ξανατρέχει έναντι ενός σταθερού εργαλείου επικύρωσης και κρατά την αλλαγή μόνο αν το F1 βελτιώνεται και η επανα-ταξινόμηση φαίνεται καλύτερη. Αν όχι, επανέρχεται. Καμία παρτίδα αλλαγών βασισμένων σε εικασίες, κανένα «θα έπρεπε να είναι καλύτερο». Μια αλλαγή κερδίζει τη θέση της ή χάνεται. Και όταν μια διόρθωση αποδεικνύεται επιτυχής και διατηρείται, προάγεται στη σουίτα fixtures — έτσι ώστε το σφάλμα που διόρθωσε να μην μπορεί ποτέ να επιστρέψει σιωπηλά. Αυτό το βήμα προαγωγής είναι αυτό που κάνει τον βρόχο αναδρομικό και όχι απλώς επαναληπτικό: κάθε πέρασμα ενισχύει το σύνολο αναφοράς με το οποίο ελέγχεται το επόμενο πέρασμα.

Το μάθημα που συνεχώς ξαναμαθαίνουμε: οι μετρικές αναφέρουν υπερβολικά πολλά προβλήματα

Να η παγίδα, και πέσαμε κατευθείαν μέσα της. Οι δευτερεύουσες μετρικές του σώματος κειμένων — πόσο συχνά ένας εξαγόμενος στόχος δεν έχει επιλύσιμο σύμβολο, πόσα σύμβολα φαίνονται «ορφανά», και ούτω καθεξής — αναφέρουν πολύ περισσότερα προβλήματα από όσα υπάρχουν. Είναι κυρίως αποτελέσματα του προγραμματιστικού μοντέλου της γλώσσας, όχι σφάλματα.

Το πιο καθαρό παράδειγμα: το llvm κάποτε έδειξε ποσοστό «πηγής χωρίς σύμβολο» 73% και χαρακτηρίστηκε καταστροφικό. Σκάψαμε βαθύτερα. Η πραγματική ακρίβεια ήταν 98,5%. Τα «λείποντα σύμβολα» ήταν σχεδόν όλα έγκυρες εξωτερικές αναφορές — κλήσεις προς την τυπική βιβλιοθήκη, προς πλαίσια εργασίας, προς κώδικα που ζει έξω από το αποθετήριο. Η μετρική μετρούσε μια ιδιότητα της γλώσσας, όχι ένα ελάττωμα στον χειριστή. Γλώσσες όπως η Zig, η COBOL και η Odin εμφανίζουν ποσοστά «ορφάνιας» 65–70% και είναι εντελώς σωστές· η COBOL είχε μηδέν πραγματικά σφάλματα.

Αν είχαμε αφήσει εκείνους τους αριθμούς να καθοδηγήσουν τη δουλειά, θα είχαμε ξοδέψει εβδομάδες «διορθώνοντας» χειριστές που ήταν ήδη σωστοί και αγνοώντας τις γλώσσες με σιωπηλά, πραγματικά σφάλματα. Το συμπέρασμα είναι ξεκάθαρο: οι συγκεντρωτικές μετρικές είναι, στην καλύτερη περίπτωση, ένα χονδρικό σήμα διαλογής. Το πραγματικό σήμα ποιότητας είναι ο δειγματοληπτικός έλεγχος με ταξινόμηση ακμών — το να κοιτάτε πραγματικές ακμές σε πραγματικά αποθετήρια και να τις κρίνετε μία-μία. Δεδομένα πάνω από διαίσθηση, αλλά μόνο όταν ξέρετε ποια δεδομένα λένε την αλήθεια.

Ο εξωτερικός βρόχος: ένας στόλος, όχι ένας μαραθώνιος

Μία γλώσσα τη φορά θα έπαιρνε αιώνες για 280 από αυτές, οπότε ο εσωτερικός βρόχος τυλίγεται σε έναν εξωτερικό που τρέχει πολλές παράλληλα.

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

Κάθε πράκτορας δουλεύει σε ένα αναλώσιμο worktree ώστε να μην πατούν ο ένας τον άλλον. Ο ενορχηστρωτής ενσωματώνει τις διορθώσεις τους μία-μία, καθεμιά πίσω από έναν πλήρη έλεγχο οπισθοδρόμησης σε όλο το μανιφέστο: μια αλλαγή που βοηθά τη δική της γλώσσα αλλά σιωπηλά σπάει τρεις άλλες δεν ενσωματώνεται. Η ενσωμάτωση περνά από πύλη και επιβεβαιώνεται πριν γίνει οποιοδήποτε push — η πύλη οπισθοδρόμησης αποφασίζει τι είναι ασφαλές, ένας άνθρωπος εξακολουθεί να αποφασίζει τι κυκλοφορεί. Έπειτα η ομάδα πρακτόρων περνά στο επόμενο σύνολο γλωσσών και όλη η διαδικασία τρέχει ξανά.

Τι εξακολουθεί να είναι ατελές

Ο κριτής μπορεί να κάνει λάθος, και το λάθος έχει κατεύθυνση: ένας πράκτορας που τρέχει με πολύ λίγο πλαίσιο αναφέρει περισσότερα προβλήματα από όσα υπάρχουν. Σε μία παρτίδα, οκτώ γλώσσες σημειώθηκαν με σφάλμα 5–20%· κατά την επιθεώρηση μόνο μία είχε πραγματικό σφάλμα ειδικό για τη γλώσσα — οι υπόλοιπες ήταν λάθη του κριτή από την παράβλεψη της ιδιαίτερης σημασιολογίας κάθε γλώσσας (μία γραμμή πηγής που ορθά εκπέμπει αρκετές ακμές, δεσμεύσεις παραμέτρων μοντελοποιημένες ως αναθέσεις, γλώσσες με αναφορά-ανά-αναγνωριστικό). Γι’ αυτό δειγματίζουμε με δύο σπόρους (seeds) και κάνουμε διασταύρωση, και γι’ αυτό μια διαφωνία ανάμεσα στον κριτή και τα fixtures αντιμετωπίζεται ως το πιο ενδιαφέρον σήμα, όχι ως τελεσίδικη ετυμηγορία — μερικές φορές το fixture είναι αυτό που είναι λάθος.

Είμαστε επίσης ειλικρινείς για τον στόχο. Ο στόχος είναι μηδέν πραγματικά σφάλματα, τελεία — όμως το «μηδέν» είναι μια κατεύθυνση προς την οποία εργαζόμαστε σταθερά, γλώσσα προς γλώσσα, όχι ένα κουτάκι που τσεκάρεται. Πάντα υπάρχει ένα ακόμη αποθετήριο με ακόμη έναν ιδιωματισμό.

Κερδισμένο, Όχι Διακηρυγμένο

Ό,τι κάνει το Maguyva για έναν πράκτορα — η εύρεση ενός συμβόλου, η ανίχνευση μιας εξάρτησης, η απάντηση σε μια ερώτηση με παραπομπές σε κώδικα — στηρίζεται στο να είναι σωστή η εξαγωγή από κάτω. Σε 280 γλώσσες, το «σωστό» δεν μπορεί απλώς να διακηρυχθεί· πρέπει να κερδίζεται συνεχώς έναντι πραγματικού κώδικα. Ο βρόχος είναι το πώς το κερδίζουμε: ένας αυτόνομος κύκλος δειγματοληπτικού ελέγχου-και-διόρθωσης που αντιμετωπίζει τις δικές του μετρικές με καχυποψία, αποδεικνύει κάθε αλλαγή και μετατρέπει κάθε διόρθωση σε φρουρό ενάντια στην επόμενη οπισθοδρόμηση. Δεν είναι εντυπωσιακό. Είναι η δουλειά που μας επιτρέπει να λέμε «υποστηρίζουμε τη γλώσσα σας» και να το εννοούμε. Το πράσινο είναι εύκολο. Το σωστό κερδίζεται.

Πολυτροπική Συγχωνευμένη Αναζήτηση: Επιλέγοντας τον Σωστό Ανακτητή για Κάθε Ερώτημα

Wed, 15 Apr 2026 00:00:00 GMT

Σημείωση για τον ιστορικό σχεδιασμό: αυτό το άρθρο του Απριλίου 2026 περιγράφει τον τότε σχεδιασμό δρομολόγησης, όχι την τρέχουσα προεπιλεγμένη συμπεριφορά. Η διόρθωση του Σεπτεμβρίου παρακάτω αφορά μόνο έναν ισχυρισμό μέτρησης. Για την τρέχουσα δρομολόγηση, τις προεπιλογές και τον ρητό έλεγχο των τρόπων αναζήτησης, δείτε Πώς λειτουργεί.

Ένα ερώτημα αναζήτησης δεν είναι ένα και μόνο πράγμα.

Το «πού ορίζεται το parseConfig» θέλει ένα ακριβές σύμβολο — μία συγκεκριμένη τοποθεσία, γρήγορα. Το «πώς λειτουργεί η ταυτοποίηση» θέλει νόημα — το εύρος του σχετικού κώδικα που εξηγεί μια έννοια. Το «τι σπάει αν αλλάξω αυτή τη συνάρτηση» θέλει τον γράφο εξαρτήσεων. Το «βρες τη συμβολοσειρά ECONNREFUSED» θέλει μια κυριολεκτική αντιστοίχιση, τίποτα έξυπνο.

Το grep είναι εξαιρετικό για κυριολεκτικές αντιστοιχίσεις και χρήσιμο για κάποιες αναζητήσεις αναφορών, όμως δεν είναι γράφος εξαρτήσεων και δεν κατανοεί το νόημα. Τα ενσωματώματα καλύπτουν τη σημασιολογική πλευρά, όμως είναι το λάθος εργαλείο για ακριβείς συμβολοσειρές και ανάλυση επίδρασης. Τα περισσότερα εργαλεία αναζήτησης κώδικα επιλέγουν μία μηχανή και αναγκάζουν κάθε ερώτημα να ζει με αυτή την επιλογή. Το Maguyva δεν περιορίζεται σε μία μηχανή. Καταλαβαίνει τι είδους ερώτημα κάνατε, και έπειτα συνδυάζει τέσσερις ανακτητές στην αναλογία που αξίζει εκείνο το ερώτημα.

Τέσσερις τρόποι αναζήτησης

Κάτω από την επιφάνεια υπάρχουν τέσσερις ανεξάρτητοι τρόποι για να βρεθεί κώδικας:

σημασιολογικός — διανυσματική αναζήτηση πάνω σε δυαδικά ενσωματώματα Voyage· βρίσκει κώδικα βάσει νοήματος.
κειμενικός — αντιστοίχιση τριγραμμάτων· βρίσκει κυριολεξίες, συμβολοσειρές σφαλμάτων, ακριβή αναγνωριστικά.
δομικός — ερωτήματα AST· βρίσκει ορισμούς, υπογραφές και δομικά στοιχεία της γλώσσας.
γράφου — ο γράφος εξαρτήσεων· βρίσκει καλούντες, καλούμενους και ακτίνα επίδρασης.

Καθένας είναι δυνατός σε διαφορετική κατηγορία ερωτήματος. Το κόλπο είναι να αποφασίσετε πόσο να εμπιστευτείτε τον καθέναν για το ερώτημα που έχετε μπροστά σας.

Ταξινόμηση πρόθεσης

Πριν τρέξει οποιαδήποτε ανάκτηση, ένας ελαφρύς ταξινομητής κατατάσσει το ερώτημα σε μία από έξι προθέσεις, με μια βαθμολογία εμπιστοσύνης. Είναι σκόπιμα φθηνός — διατεταγμένοι ευρετικοί κανόνες, κερδίζει η πρώτη αντιστοίχιση — επειδή τρέχει στο κρίσιμο μονοπάτι και προσθέτει μόλις ένα ή δύο χιλιοστά του δευτερολέπτου:

ξεκινά με def , class , func , import … → find_definition (εμπιστοσύνη 0,95)
«who calls», «usages of», «references to» (ποιος καλεί, χρήσεις του, αναφορές σε) → find_references (0,90)
«impact», «blast radius», «what depends on» (επίδραση, ακτίνα επίδρασης, τι εξαρτάται από) → impact_analysis (0,90)
μια συμβολοσειρά σε εισαγωγικά όπως το "string" ή ένα token σφάλματος όπως το traceback → exact_match (0,85–0,90)
ένα αναγνωριστικό CamelCase ή snake_case → find_definition (0,60–0,80)
«how», «why», «explain», «architecture» (πώς, γιατί, εξήγησε, αρχιτεκτονική) → understand_code (0,75)
τίποτα δεν ταιριάζει → understand_code, χαμηλή εμπιστοσύνη (0,40)

Κάθε πρόθεση κουβαλά ένα προφίλ βαρών στους τέσσερις τρόπους αναζήτησης. Αυτοί είναι οι πραγματικοί αριθμοί:

Πρόθεση	σημασιολογικός	κειμενικός	δομικός (AST)	γράφου
find_definition	0.2	0.1	0.6	0.1
find_references	0.1	0.2	0.2	0.5
understand_code	0.5	0.2	0.2	0.1
find_similar	0.4	0.3	0.2	0.1
impact_analysis	0.1	0.1	0.1	0.7
exact_match	0.0	0.9	0.1	0.0

Έτσι το «πού ορίζεται το parseConfig» στηρίζεται κυρίως στο AST (0,6). Το «πώς λειτουργεί η ταυτοποίηση» στηρίζεται σε σημασιολογικά διανύσματα (0,5). Το «τι εξαρτάται από αυτό» είναι σχεδόν αποκλειστικά γράφος (0,7). Το «βρες ECONNREFUSED» είναι σχεδόν αποκλειστικά τριγράμματα (0,9), με το μοντέλο ενσωματωμάτων εντελώς απενεργοποιημένο — επειδή η σημασιολογική ομοιότητα είναι ακριβώς το λάθος εργαλείο για μια ακριβή συμβολοσειρά.

Το γρήγορο μονοπάτι, και το συγχωνευμένο μονοπάτι

Όταν ο ταξινομητής είναι σίγουρος — βαθμολογία ≥ 0,85 — και το ερώτημα είναι συνηθισμένο, το Maguyva παρακάμπτει εντελώς τη συγχώνευση και δρομολογεί απευθείας στον έναν κυρίαρχο τρόπο αναζήτησης. Το «πού ορίζεται το X» δεν χρειάζεται τέσσερις ανακτητές· χρειάζεται το ευρετήριο AST, τώρα. Αυτό το απευθείας μονοπάτι αναφέρεται πίσω ως fusion_strategy: "direct".

Οτιδήποτε είναι διφορούμενο περνά από συγχώνευση. Οι τέσσερις (ή τρεις, στην προεπιλεγμένη διαμόρφωση) τρόποι αναζήτησης τρέχουν παράλληλα, ο καθένας επιστρέφοντας τη δική του κατατεταγμένη λίστα, και τους συνδυάζουμε.

Σταθμισμένη Reciprocal Rank Fusion

Η συγχώνευση ετερογενών ανακτητών είναι πιο δύσκολη απ’ όσο ακούγεται: μια ομοιότητα συνημιτόνου 0,82 και μια βαθμολογία τριγράμματος 137 και μια κεντρικότητα γράφου 0,004 δεν βρίσκονται στην ίδια κλίμακα, οπότε δεν μπορείτε απλώς να τις προσθέσετε. Η Reciprocal Rank Fusion παρακάμπτει το πρόβλημα πετώντας τις ακατέργαστες βαθμολογίες και κρατώντας μόνο την κατάταξη που έδωσε κάθε μηχανή. Η συνεισφορά ενός αποτελέσματος από έναν τρόπο αναζήτησης είναι:

contribution = weight × 1 / (k + rank + 1)

όπου το rank είναι η θέση του στη λίστα εκείνου του τρόπου αναζήτησης και το k είναι μια σταθερά εξομάλυνσης. Οι συνεισφορές αθροίζονται σε όλους τους τρόπους αναζήτησης για κάθε αποτέλεσμα που βρήκε περισσότερη από μία μηχανή — η συμφωνία μεταξύ ανακτητών φυσικά ανεβαίνει στην κορυφή. Χρησιμοποιούμε k = 40 στην προεπιλεγμένη διαμόρφωση και 60 στο thorough (quick τρέχει μόνο σημασιολογικά, οπότε η συγχώνευση δεν ενεργοποιείται ποτέ εκεί). Η αρχική εργασία για το RRF κατέληξε σε k = 60 για γενικού σκοπού ανάκτηση· η δική μας προεπιλογή δίνει λίγο περισσότερο βάρος στα αποτελέσματα που κατατάσσονται ψηλά σε πολλούς τρόπους αναζήτησης — και δεν συνιστούμε χειροκίνητη ρύθμιση.

Επιπλέον, τα αποτελέσματα φέρουν μια ενίσχυση σπουδαιότητας γράφου. Ένας κεντρικός κόμβος — μια συνάρτηση στην οποία στηρίζεται ολόκληρη η βάση κώδικα — πρέπει να κατατάσσεται πάνω από έναν λιγότερο γνωστό κόμβο-φύλλο ακόμη και με την ίδια κειμενική σχετικότητα, οπότε πολλαπλασιάζουμε κάθε συνεισφορά με:

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

Η κεντρικότητα προέρχεται από τις προϋπολογισμένες μετρικές PageRank/βαθμού του pipeline, και η ενίσχυση είναι περιορισμένη στο 1,5× ώστε μια δημοφιλής συνάρτηση να μην μπορεί να θάψει εντελώς μια πιο σχετική αλλά λιγότερο γνωστή συνάρτηση. Τέλος υποβιβάζουμε αποτελέσματα από διαδρομές προμηθευτών, κατασκευής και αρχειοθέτησης, και αφαιρούμε διπλότυπα κρατώντας το καλύτερο τμήμα ανά αρχείο.

Τι εξακολουθεί να είναι ατελές

Ο ταξινομητής πρόθεσης είναι μια σειρά κανονικών εκφράσεων, όχι ένα εκπαιδευμένο μοντέλο. Χειρίζεται συνήθεις μορφές ερωτημάτων με ευρετικούς κανόνες, ενώ ένα αμφίσημο ερώτημα καταλήγει στο understand_code και σε ένα μείγμα με έμφαση στη σημασιολογία. Μια προηγούμενη έκδοση αυτού του άρθρου περιέγραφε τη μείωση του ποσοστού ερωτημάτων χωρίς αποτελέσματα από περίπου 15% σε κάτω από 5% ως επιτευχθείσα. Στην πραγματικότητα, η πρόταση του Δεκεμβρίου 2025 παρέθετε μια εκτιμώμενη αρχική τιμή και έναν στόχο· δεν παρέχεται υποστηρικτικό σύνολο ερωτημάτων ή αρχείο μέτρησης. Αποσύρουμε τον ισχυρισμό περί επιτευχθείσας βελτίωσης· δείτε τα τεκμήρια πηγής και τη διόρθωση. Δεν έχουμε αντικαταστήσει τον ταξινομητή με εκπαιδευμένο μοντέλο, επειδή η οικονομική έκδοση είναι γρήγορη και επαρκής για τον προβλεπόμενο ρόλο δρομολόγησης, και επειδή ένας λανθασμένος αλλά βέβαιος ταξινομητής είναι χειρότερος από μια ειλικρινή εναλλακτική επιλογή. Τα ίδια τα βάρη είναι χειροκίνητα επιλεγμένες αρχικές παραδοχές, όχι τιμές που μαθαίνονται από δεδομένα κλικ, τα οποία δεν συλλέγουμε.

Κάντε την ερώτησή σας χωρίς να επιλέγετε εργαλείο

Ένας πράκτορας δεν θα έπρεπε να χρειάζεται να ξέρει αν πρέπει να καταφύγει στο grep, στα ενσωματώματα ή στον γράφο κλήσεων — θα έπρεπε να κάνει την ερώτησή του με απλά λόγια και να πάρει τη σωστή απάντηση. Η πολυτροπική συγχώνευση είναι αυτό που επιτρέπει στο find_symbol, στη σημασιολογική αναζήτηση και στην ανάλυση εξαρτήσεων να βρίσκονται πίσω από μία ενιαία διεπαφή ερωτημάτων: το σύστημα διαβάζει το σχήμα της ερώτησης και συναρμολογεί σιωπηλά τον σωστό ανακτητή γι’ αυτήν. Το μοντέλο που βαθμολογεί τα ενσωματώματα έχει σημασία, όμως έχει σημασία και το να ξέρετε πότε να μην τα χρησιμοποιήσετε. Η επιλογή του σωστού εργαλείου για κάθε ερώτημα είναι ένα δικό της είδος ποιότητας, και είναι ένα που προτιμούμε να αναλαμβάνουμε εμείς παρά να το μεταθέτουμε στον καλούντα.

// you bring the question. it brings the tools.

Παρατηρησιμότητα Πρακτόρων: Hooks, Alloy και Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Τα συστήματα πρακτόρων αποτυγχάνουν με περίεργους τρόπους.

Μερικές φορές το μοντέλο είναι το πρόβλημα. Μερικές φορές το εργαλείο είναι το πρόβλημα. Μερικές φορές ο διακομιστής σας MCP είναι εντάξει, όμως ο πράκτορας επέλεξε τον λάθος ειδικό, ή πέρασε τον μισό χρόνο της συνεδρίας κάνοντας εργασία shell που δεν περιμένατε, ή αύξησε σιωπηλά το κόστος σε έναν βρόχο που φαινόταν παραγωγικός απ’ έξω.

Αν δεν μπορείτε να δείτε τη διαφορά, δεν λειτουργείτε πραγματικά ένα σύστημα πρακτόρων. Μαντεύετε.

Έτσι χτίσαμε μια στοίβα παρατηρησιμότητας για τη δική μας ροή εργασίας: Claude Code, Codex, συμβάντα hook του Claude, συμβάντα notify του Codex, εγγενές OpenTelemetry, Grafana Alloy και Grafana Cloud στην άλλη άκρη.

Το ενδιαφέρον κομμάτι δεν είναι «φτιάξαμε έναν πίνακα ελέγχου». Το ενδιαφέρον κομμάτι είναι ότι χρειάστηκε να χωρίσουμε την τηλεμετρία σε δύο διαφορετικές ροές επειδή καμία μεμονωμένη τροφοδοσία δεν μας έδινε την πλήρη εικόνα.

Το Πρόβλημα: Η Τηλεμετρία Πρακτόρων Είναι Κατακερματισμένη

Οι σύγχρονοι πράκτορες κώδικα ήδη εκπέμπουν κάποια τηλεμετρία. Αυτό βοηθά, όμως δεν αρκεί.

Το εγγενές OTEL είναι καλό στο να απαντά ερωτήματα όπως:

Πόσα αιτήματα κάναμε;
Πόσο κόστισε μια συνεδρία;
Πού βρίσκονται τα spans και τα traces;
Υπήρξε αιχμή στην καθυστέρηση;

Είναι πολύ χειρότερο στο να απαντά ερωτήματα όπως:

Σε ποιον διακομιστή MCP στηρίχθηκε ο πράκτορας;
Ήταν αυτή η αστοχία στο Bash, σε ένα ενσωματωμένο εργαλείο αρχείων, ή σε μια κλήση MCP;
Ποια δεξιότητα πράγματι ενεργοποιήθηκε;
Ποιος τύπος υπο-πράκτορα δρομολογήθηκε;
Έκανε η συνεδρία χρήσιμη δουλειά, ή απλώς στροβιλιζόταν χωρίς αποτέλεσμα;

Αυτή η δεύτερη κατηγορία ερωτημάτων ζει πιο κοντά στα hooks παρά στα traces.

Όμως ισχύει και το αντίστροφο: μερικά από τα πιο σημαντικά ερωτήματα απόδοσης ζουν πιο κοντά στα traces παρά στα hooks.

Αν θέλετε να ξέρετε πού πραγματικά συσσωρεύτηκε η καθυστέρηση, ποια spans ήταν αργά, ή αν η συνεδρία κατανάλωσε χρόνο σε κλήσεις μοντέλου έναντι εκτέλεσης εργαλείων, χρειάζεστε δεδομένα traces εξίσου με σημασιολογικά συμβάντα.

Η Αρχιτεκτονική στην Οποία Καταλήξαμε

Τρέχουμε δύο μονοπάτια τηλεμετρίας παράλληλα.

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

Αυτός ο διαχωρισμός είναι σκόπιμος.

Είναι επίσης ασύμμετρος. Το Claude Code μας δίνει μια πολύ πλουσιότερη διεπαφή hooks κύκλου ζωής. Το Codex μας δίνει εγγενές OTEL συν μια διεπαφή notify, οπότε κανονικοποιούμε τα συμβάντα ολοκλήρωσης γύρου με λιγότερα δεδομένα στο ίδιο σχήμα καταγραφής αντί να προσποιούμαστε ότι και τα δύο περιβάλλοντα εκτέλεσης εκθέτουν τους ίδιους ελέγχους.

Το εγγενές OTEL μας δίνει τη βασική ροή: αρχεία καταγραφής και traces από το ίδιο το περιβάλλον εκτέλεσης, συν μετρικές όπου το περιβάλλον εκτέλεσης όντως τις εκπέμπει.

Τα συμβάντα hook και notify μας δίνουν το σημασιολογικό επίπεδο: πράγματα όπως τα PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, και τα ταξινομημένα μεταδεδομένα που πραγματικά μας ενδιαφέρουν όταν αποσφαλματώνουμε τη συμπεριφορά πρακτόρων. Το Claude Code συνεισφέρει την πλουσιότερη ροή συμβάντων εδώ. Το Codex συνεισφέρει μια κανονικοποιημένη ροή με λιγότερα δεδομένα αλλά ακόμη χρήσιμη.

Γιατί Υπάρχουν Καν τα Hooks

Ο αγωγός hooks μας εμπλουτίζει τα συμβάντα πριν φτάσουν στο Loki.

Αντί να λέμε απλώς «έτρεξε ένα εργαλείο», ταξινομούμε το συμβάν σε πεδία όπως:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: ποιος υποκείμενος διακομιστής MCP χειρίστηκε την κλήση
bash_cli: η οικογένεια εντολών shell
subagent_type: τι είδους ειδικός δρομολογήθηκε
agent_tool: αν η πηγή ήταν Claude Code ή Codex

Αυτό σημαίνει ότι μπορούμε να κάνουμε ερωτήματα που έχουν λειτουργική σημασία:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

Αυτά δεν είναι πεδία επίδειξης. Είναι η διαφορά ανάμεσα στο «ο πράκτορας φάνηκε αργός» και στο «ο πράκτορας πέρασε τα τελευταία δέκα λεπτά σε βαριές λειτουργίες git μέσω shell με υψηλό ποσοστό αποτυχίας εργαλείων».

Μια λεπτομέρεια υλοποίησης που φαίνεται πιο περίεργη απ’ όσο είναι: η κοινόχρηστη ροή Loki εξακολουθεί να χρησιμοποιεί το service_name="claude-code-hooks" ως ετικέτα ακόμη και όταν το συμβάν προήλθε από το Codex. Ο πραγματικός διαχωρισμός ανάμεσα στα περιβάλλοντα εκτέλεσης συμβαίνει στο agent_tool.

Γιατί το Alloy Βρίσκεται στη Μέση

Το Grafana Alloy δεν είναι απλώς ένας προωθητής σε αυτή τη ρύθμιση. Είναι το όριο πολιτικής.

Στρέφουμε την εγγενή ροή OTEL από το Claude Code και το Codex σε έναν τοπικό διαμεσολαβητή Alloy στο localhost:4318, και έπειτα αφήνουμε το Alloy να καθαρίσει το ωφέλιμο φορτίο πριν το προωθήσει στο Grafana Cloud.

Αυτό έχει σημασία επειδή η ακατέργαστη τηλεμετρία πρακτόρων είναι γεμάτη πεδία υψηλής πληθικότητας που είναι χρήσιμα για ανάλυση αλλά απαίσια ως ευρετηριασμένες ετικέτες:

session_id
prompt_id
αριθμοί tokens
διάρκειες
δέσμες παραμέτρων εργαλείων

Αν ευρετηριάσετε τα πάντα, ο αριθμός των ετικετών εκτοξεύεται και δημιουργεί λειτουργικά προβλήματα.

Οπότε το Alloy κάνει τρία πράγματα για εμάς:

Κρατά ευρετηριασμένο ένα πολύ μικρό σύνολο ετικετών χαμηλής πληθικότητας.
Μετακινεί θορυβώδη αλλά χρήσιμα πεδία σε δομημένα μεταδεδομένα.
Απορρίπτει εντελώς τον καθαρό θόρυβο.

Η σημαντική ιδέα είναι απλή: παρατηρήστε περισσότερα, ευρετηριάστε λιγότερα.

Γιατί η Ροή Hook Παρακάμπτει το Alloy

Η ροή hook είναι ήδη διαμορφωμένη για το Loki.

Μέχρι τη στιγμή που το send_event.py σπρώχνει ένα συμβάν, έχουμε ήδη αποφασίσει ποια πεδία αξίζουν μεταχείριση ετικέτας και ποια ανήκουν στο δομημένο σώμα JSON. Εκείνη η ροή πηγαίνει κατευθείαν στην πύλη OTLP του Grafana Cloud αντί να περάσει ξανά από το Alloy.

Οπότε το σύστημα έχει σαφή καταμερισμό εργασίας:

Το Alloy δαμάζει την ακατέργαστη εγγενή ροή OTEL.
Ο εμπλουτισμός hook κάνει τα σημασιολογικά συμβάντα αναζητήσιμα.

Αυτό κρατά την αρχιτεκτονική απλούστερη από το να προσπαθείτε να περάσετε τα πάντα από ένα μονοπάτι.

Τι Δείχνει Πραγματικά ο Πίνακας Ελέγχου

Το στιγμιότυπο οθόνης παρακάτω προέρχεται από έναν από τους πίνακες ελέγχου παρατηρησιμότητας πίσω από τη ροή εργασίας πρακτόρων μας. Δεν είναι benchmark, και οι αριθμοί είναι απλώς ένα στιγμιότυπο μιας συγκεκριμένης χρονικής στιγμής. Το θέμα είναι το σχήμα των δεδομένων: ροή δραστηριότητας, κλήσεις εργαλείων, αστοχίες, προτροπές, και αναλύσεις ανά πράκτορα, ενσωματωμένα εργαλεία, χρήση MCP, εντολές shell και δεξιότητες.

Το χρήσιμο κομμάτι είναι ότι αυτός ο πίνακας ελέγχου ζει στην ίδια στοίβα Grafana με την υπόλοιπη τηλεμετρία πρακτόρων. Μπορούμε να φιλτράρουμε κατά πράκτορα-πηγή και οικογένεια εργαλείων και να εξετάσουμε δεδομένα από όλα τα περιβάλλοντα εκτέλεσης χωρίς να επινοήσουμε μια διαφορετική ιστορία παρατηρησιμότητας για κάθε σύστημα.

Ένας από τους ζωντανούς πίνακες ελέγχου πίσω από τη ροή εργασίας πρακτόρων μας. Αυτό το στιγμιότυπο οθόνης είναι μόνο μία τομή μιας κοινόχρηστης στοίβας Grafana που δέχεται επίσης τηλεμετρία από τα άλλα περιβάλλοντα εκτέλεσης πρακτόρων και συστήματά μας. Κάντε κλικ στην εικόνα για την έκδοση πλήρους ανάλυσης.

Γιατί τα Traces Έχουν Περισσότερη Σημασία Απ’ Όσο Φαίνεται Αρχικά

Τα αρχεία καταγραφής μας λένε τι κατηγορία εργασίας συνέβη. Τα traces μας λένε πώς εξελίχθηκε η εργασία με τον χρόνο.

Αυτή η διάκριση έχει σημασία σε συστήματα πρακτόρων επειδή το «αργό» είναι πολύ γενικό για να είναι χρήσιμο.

Ένα trace μπορεί να μας πει αν το πρόβλημα προήλθε από:

καθυστέρηση μοντέλου
χρόνο εκτέλεσης εργαλείου
επαναλαμβανόμενες επαναπροσπάθειες
μία ιδιαίτερα δαπανηρή αλληλεπίδραση MCP
μια μακριά ουρά μικρών λειτουργιών που φαίνονταν ακίνδυνες μεμονωμένα

Στην πράξη χρησιμοποιούμε τη ροή hook και τα traces του Tempo μαζί.

Τα αρχεία καταγραφής hook απαντούν: τι είδους πράγμα συνέβη;
Τα traces απαντούν: πού πήγε ο χρόνος;

Ο συνδυασμός είναι αυτό που μετατρέπει την παρατηρησιμότητα από πίνακα ελέγχου σε εξήγηση.

Πού Χωράει το Codex

Το Codex είναι μέρος της ίδιας στοίβας, όμως δεν είναι ταυτόσημο με το Claude Code.

Για το Codex συνδέουμε δύο κομμάτια:

Εγγενές OTEL από το Codex στο Alloy
Ένα notify webhook στο codex_notify.py, που αντιστοιχίζει τις ολοκληρώσεις γύρων στο ίδιο σχήμα Loki που χρησιμοποιούμε για συμβάντα hook

Αυτό μας δίνει ένα ενοποιημένο φίλτρο όπως το agent_tool="codex-cli" μέσα στην ίδια ροή καταγραφής.

Η ειλικρινής επιφύλαξη: το ωφέλιμο φορτίο notify του Codex περιέχει προς το παρόν λιγότερα δεδομένα από το ωφέλιμο φορτίο hook του Claude Code επειδή δεν είναι το ίδιο είδος διεπαφής ενσωμάτωσης. Στη σημερινή μας ρύθμιση, οι ολοκληρώσεις γύρων του Codex μπορούν να κανονικοποιηθούν στο κοινό σχήμα, όμως η εξαγωγή αναλυτικών δεδομένων ανά εργαλείο εξακολουθεί να είναι καλύτερη στην εγγενή ροή OTEL παρά στη γέφυρα notify.

Δεν παρουσιάζουμε αυτόν τον περιορισμό ως δικαιολογία. Είναι το νόημα της ανάρτησης. Τα πραγματικά συστήματα παρατηρησιμότητας συναρμολογούνται από ατελή σήματα.

Το Grafana Πάνω από MCP Αλλάζει το Παιχνίδι

Η μεγαλύτερη αλλαγή είναι ότι το Grafana δεν είναι μόνο ένα μέρος που επισκέπτονται άνθρωποι σε ένα πρόγραμμα περιήγησης.

Σε αυτό το αποθετήριο εκθέτουμε επίσης το Grafana μέσω MCP. Αυτό σημαίνει ότι ένας πράκτορας μπορεί να θέσει ερωτήματα απευθείας στο Loki, στο Prometheus και στο Tempo αντί να περιμένει έναν άνθρωπο να επιθεωρήσει χειροκίνητα τους πίνακες ελέγχου πρώτα.

Αυτό μετατρέπει την παρατηρησιμότητα σε ενεργή είσοδο στη ροή εργασίας.

Ένας πράκτορας μπορεί να ρωτήσει:

Ποιες οικογένειες εργαλείων απέτυχαν περισσότερο την τελευταία ώρα;
Ποιος διακομιστής MCP κυριάρχησε σε μια συνεδρία;
Οι πρόσφατες αλλαγές μείωσαν τις αστοχίες εργαλείων ή απλώς μετέφεραν την εργασία σε πιο βαριές διαδρομές shell με τα ίδια λάθη;
Ποια traces δείχνουν την υψηλότερη καθυστέρηση ή επαναλαμβανόμενες επαναπροσπάθειες;

Μόλις το έχετε αυτό, είστε πολύ κοντά σε έναν βρόχο αυτο-βελτίωσης.

Από τον Πίνακα Ελέγχου στον Βρόχο Ανάδρασης

Αυτό είναι το κομμάτι που βρίσκουμε πιο ενδιαφέρον.

Μόλις η στοίβα παρατηρησιμότητας γίνει αναζητήσιμη από το επίπεδο πρακτόρων, η τηλεμετρία σταματά να είναι ένα παθητικό μέσο αναφοράς και γίνεται σήμα ελέγχου.

Ο βρόχος μοιάζει ως εξής:

Η δραστηριότητα πρακτόρων εκπέμπει traces, μετρικές και εμπλουτισμένα αρχεία καταγραφής hook.
Το Grafana αποθηκεύει τα στοιχεία στο Loki, στο Tempo και στο Prometheus όπου υπάρχουν μετρικές.
Οι πράκτορες θέτουν ερωτήματα σε αυτά τα στοιχεία μέσω του Grafana MCP.
Το σύστημα εντοπίζει κακό μείγμα εργαλείων, εύθραυστες δεξιότητες, αδύναμη δρομολόγηση, ή ροές εργασίας βαριές σε shell που συνεχίζουν να παράγουν αποφεύξιμα λάθη.
Οι πράκτορες ή οι χειριστές προσαρμόζουν προτροπές, διαμορφώσεις πρακτόρων, περιγραφές δεξιοτήτων, κανόνες δρομολόγησης ή πρόσβαση σε εργαλεία.
Η επόμενη συνεδρία παράγει ένα νέο σχήμα τηλεμετρίας, και ο κύκλος επαναλαμβάνεται.

Έτσι μετακινείστε από «ενδιαφέρων πίνακας ελέγχου» σε «μετρήσιμο σύστημα βελτίωσης».

Ο στόχος δεν είναι να μεγιστοποιήσετε μία κατηγορία εργαλείων. Είναι να καταλήξετε στο σωστό μείγμα CLI, ενσωματωμένων εργαλείων, κλήσεων MCP και δεξιοτήτων για την εργασία που πράγματι γίνεται.

Τι Μας Επιτρέπει να Απαντήσουμε

Μόλις και τα δύο περιβάλλοντα εκτέλεσης καταλήξουν στην ίδια στοίβα Grafana, μπορούμε να απαντήσουμε λειτουργικά ερωτήματα πολύ πιο γρήγορα:

Είναι οι αστοχίες συγκεντρωμένες σε μία οικογένεια εργαλείων;
Δημιουργούν οι ροές εργασίας βαριές σε shell αποφεύξιμα λάθη εκεί όπου θα έπρεπε να υπάρχει ένα εργαλείο υψηλότερου επιπέδου;
Ποιοι διακομιστές MCP κουβαλούν το φορτίο εργασίας;
Πληρώνουμε για δραστηριότητα πρακτόρων που δεν παράγει ουσιαστική πρόοδο;
Είναι μια συνεδρία προβληματική εξαιτίας του μοντέλου, των εργαλείων ή του επιπέδου ενορχήστρωσης;

Αυτό είναι ιδιαίτερα χρήσιμο σε ροές εργασίας πολλαπλών πρακτόρων, όπου το «ο πράκτορας ήταν απασχολημένος» δεν σας λέει σχεδόν τίποτα.

Αν ένας ειδικός συνεχίζει να δρομολογείται και να παράγει υψηλά ποσοστά αποτυχίας, αυτό είναι πρόβλημα δρομολόγησης ή διαμόρφωσης προτροπής.

Αν ένας διακομιστής MCP κυριαρχεί σε όλες τις κλήσεις, αυτό μπορεί να είναι καλή αρχιτεκτονική ή σημάδι ότι όλα τα υπόλοιπα είναι νεκρό βάρος.

Αν οι αστοχίες εργαλείων εκτοξεύονται ενώ το κόστος παραμένει υψηλό, έχετε λειτουργικό πρόβλημα, όχι πρόβλημα ποιότητας.

Αν η εργασία shell συνεχίζει να αποτυγχάνει με προβλέψιμους, αποφεύξιμους τρόπους εκεί όπου θα έπρεπε να υπάρχει ένα εργαλείο υψηλότερου επιπέδου, αυτό είναι σήμα προϊόντος.

Αν μία δεξιότητα ενεργοποιείται συνεχώς αλλά δεν βελτιώνει τα αποτελέσματα, αυτό είναι σήμα προτροπής ή δρομολόγησης.

Το Πραγματικό Μάθημα

Το βαθύτερο μάθημα εδώ είναι ότι η παρατηρησιμότητα πρακτόρων χρειάζεται τόσο τηλεμετρία χρόνου εκτέλεσης όσο και τηλεμετρία ροής εργασίας.

Η τηλεμετρία χρόνου εκτέλεσης σας λέει τι έκανε το σύστημα.

Η τηλεμετρία ροής εργασίας σας λέει τι νόμιζε ο πράκτορας ότι έκανε.

Χρειαζόμαστε και τα δύο.

Αν κρατάτε μόνο traces και μετρητές, χάνετε το σημασιολογικό επίπεδο. Αν κρατάτε μόνο συμβάντα hook, χάνετε την καθυστέρηση, τα spans και την ευρύτερη εικόνα χρόνου εκτέλεσης.

Και αν κρατάτε και τα δύο αλλά ποτέ δεν τα τροφοδοτείτε πίσω στο επίπεδο πρακτόρων, έχετε παρακολούθηση, όχι προσαρμογή.

Ο συνδυασμός είναι αυτό που κάνει το σύστημα αρκετά επεξηγήσιμο για να λειτουργεί και αρκετά ρυθμίσιμο για να βελτιώνεται.

Τι Εξακολουθεί να Είναι Ατελές

Υπάρχουν ακόμη σημεία που χρειάζονται βελτίωση.

Δεν περιλαμβάνει κάθε συμβάν hook τα δεδομένα διάρκειας και tokens που θα θέλαμε.
Μερικές από τις καλύτερες όψεις χρονισμού εξακολουθούν να προέρχονται από traces του Tempo, όχι από τα αρχεία καταγραφής hook.
Το Codex σήμερα είναι λιγότερο σημασιολογικά πλούσιο από το Claude Code στην εμπλουτισμένη ροή συμβάντων.
Το στιγμιότυπο οθόνης του πίνακα ελέγχου είναι μια οθόνη που χρησιμοποιείται στην καθημερινή λειτουργία, όχι ένα στιλβωμένο τεχνούργημα μάρκετινγκ.

Αυτό το τελευταίο σημείο είναι σκόπιμο. Προτιμούμε να δείξουμε τον πραγματικό πίνακα οργάνων παρά να προσποιηθούμε ότι τα συστήματα πρακτόρων είναι μαγικά αυτο-επεξηγούμενα.

Γιατί Αυτό Έχει Σημασία για το Maguyva

Το Maguyva αφορά το να δίνει στους πράκτορες καλύτερη ευφυΐα κώδικα. Όμως μόλις οι πράκτορες κάνουν πραγματικά χρήσιμη δουλειά, εμφανίζεται αμέσως μια νέα απαίτηση: χρειάζεται να δείτε πώς συμπεριφέρονται.

Η ποιότητα αναζήτησης, η ποιότητα δρομολόγησης, η επιλογή εργαλείων και η αποδοτικότητα πλαισίου γίνονται όλα παρατηρήσιμα προβλήματα.

Γι’ αυτό πιστεύουμε ότι αξίζει να γράψουμε γι’ αυτό. Η μελλοντική στοίβα πρακτόρων δεν είναι μόνο προτροπές και εργαλεία. Είναι προτροπές, εργαλεία, και το επίπεδο καταγραφής και μέτρησης που σας λέει αν όλο αυτό λειτουργεί.

Αν χτίζετε σοβαρές ροές εργασίας πρακτόρων, η παρατηρησιμότητα δεν είναι προαιρετική υποδομή. Είναι μέρος του προϊόντος.

Εξόρυξη και Κλείσιμο του Βρόχου: Πώς οι Αλλαγές Γίνονται Θεσμική Μνήμη

Tue, 03 Feb 2026 00:00:00 GMT

Οι αριθμοί σε αυτή την ανάρτηση αντικατοπτρίζουν το σύστημα κατά τη δημοσίευση (Φεβρουάριος 2026). Δείτε τη σελίδα ομάδας μας για τα τρέχοντα στοιχεία.

Κάθε ομάδα μηχανικών αντιμετωπίζει την ίδια πρόκληση: οι αλλαγές συμβαίνουν συνεχώς, όμως το γιατί πίσω από αυτές τις αλλαγές εξαφανίζεται. Έξι μήνες αργότερα, κάποιος ρωτά «γιατί υιοθετήσαμε το DuckDB για τα στάδια του αγωγού;» και η απάντηση ζει μόνο στο μυαλό όποιου πήρε εκείνη την απόφαση — αν εξακολουθεί να εργάζεται στην ομάδα.

Χτίσαμε μια ροή εργασίας εξόρυξης που κλείνει αυτόν τον βρόχο. Οι αλλαγές ρέουν μέσα από υποβολές git, επεξεργάζονται από τον αγωγό εξόρυξής μας, γίνονται δομημένες καταχωρίσεις ιστορικού αλλαγών και αρχεία αρχιτεκτονικών αποφάσεων, και έπειτα τροφοδοτούν πίσω τους πράκτορές μας AI μέσω ερωτημάτων CLI. Το αποτέλεσμα: θεσμική μνήμη στην οποία μπορούν να έχουν πρόσβαση τόσο άνθρωποι όσο και AI.

Το Πρόβλημα: Οι Αποφάσεις Εξατμίζονται

Σκεφτείτε ένα τυπικό σενάριο. Ένας προγραμματιστής κάνει μια υποβολή (commit):

feat(canonical): add DuckDB runtime for pipeline stages

Αυτή η υποβολή αντιπροσωπεύει μια σημαντική αρχιτεκτονική επιλογή. Η ομάδα αξιολόγησε επιλογές, εξέτασε συμβιβασμούς και κατέληξε στο DuckDB για συγκεκριμένους λόγους. Όμως όλο αυτό το πλαίσιο ζει σε:

Ένα νήμα Slack (πιθανώς διαγραμμένο)
Τη μνήμη κάποιου (σίγουρα ξεθωριάζει)
Ένα σχόλιο στον κώδικα (ίσως, αν είστε τυχεροί)

Τρεις μήνες αργότερα, ένα νέο μέλος της ομάδας ρωτά: «Πρέπει να χρησιμοποιήσω DuckDB ή SQLite για αυτό το νέο στάδιο;». Χωρίς θεσμική μνήμη, είτε ανακαλύπτουν ξανά τον τροχό είτε κάνουν ασυνεπείς επιλογές.

Ο Βρόχος: Από τις Υποβολές στο Πλαίσιο

Η ροή εργασίας εξόρυξής μας μετατρέπει το ιστορικό git σε αναζητήσιμη γνώση:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

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

Πώς Λειτουργεί η Εξόρυξη

Βήμα 1: Συγχρονισμός του Ευρετηρίου

uv run orkestra mine sync

Αυτή η εντολή σαρώνει το ιστορικό git και χτίζει ένα ευρετήριο όλων των υποβολών. Εξάγει δομημένα σήματα από κάθε υποβολή:

Τύπος βάσει του προτύπου Conventional Commits (feat, fix, chore, docs)
Εμβέλεια (ποιο πακέτο ή περιοχή)
Δείκτες ασύμβατων αλλαγών
Αρχεία που επηρεάστηκαν και μετρικές πολυπλοκότητας

Βήμα 2: Έλεγχος Κατάστασης Κάλυψης

uv run orkestra mine status

Να πώς μοιάζει η τρέχουσα κατάστασή μας:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15.637 υποβολές έχουν υποβληθεί σε επεξεργασία. 476 έγιναν αρχιτεκτονικές αποφάσεις. 6.799 έγιναν καταχωρίσεις ιστορικού αλλαγών. Κάθε υποβολή έχει ταξινομηθεί.

Βήμα 3: Λήψη Υποψηφίων για Επισκόπηση

uv run orkestra mine candidates --limit 50 --full

Αυτό αναδεικνύει υποβολές που δεν έχουν επεξεργαστεί ακόμη, με πλήρες πλαίσιο για ταξινόμηση:

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

Τα σήματα βοηθούν να καθοδηγηθεί η ταξινόμηση: το is_releasable_type: true υποδεικνύει ότι αυτό πρέπει να εμφανιστεί στο ιστορικό αλλαγών. Ο μεγάλος αριθμός προστιθέμενων γραμμών και τα αρχεία υποδομής υποδεικνύουν ότι μπορεί επίσης να είναι αρχιτεκτονική απόφαση.

Βήμα 4: Ταξινόμηση Υποβολών

Δύο διαδρομές αποκλίνουν εδώ: καταχωρίσεις ιστορικού αλλαγών και αρχιτεκτονικές αποφάσεις.

Για καταχωρίσεις ιστορικού αλλαγών:

uv run orkestra mine classify abc123 --changelog added

Αυτό καταγράφει ότι η υποβολή abc123 πρέπει να εμφανιστεί στο ιστορικό αλλαγών κάτω από την κατηγορία «Added».

Για αρχιτεκτονικές αποφάσεις:

Πρώτα, πάρτε ένα πραγματικό ID απόφασης:

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

Έπειτα ταξινομήστε με το ID απόφασης:

uv run orkestra mine classify abc123 --decision DEC-PL-143

Αυτό συνδέει την υποβολή με ένα αρχείο απόφασης που θα δημιουργηθεί ή θα ενημερωθεί.

Για μαζική επεξεργασία (αυτό που κάνουμε στην πράξη):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

Η μορφή JSONL υποστηρίζει και τους δύο τομείς σε ένα πέρασμα:

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

Βήμα 5: Απόδοση Εξόδων

uv run orkestra registry changelog render --package <pkg>

Αυτό παράγει αρχεία CHANGELOG.md ανά πακέτο από το καθολικό. Τα ιστορικά αλλαγών είναι παράγωγα τεχνουργήματα — διαγράψτε τα και αναδημιουργούνται τέλεια από το πηγαίο καθολικό.

Η Δομή του Αρχείου Απόφασης

Οι εξαγόμενες αποφάσεις γίνονται αρχεία YAML με πλούσια μεταδεδομένα:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

Κάθε απόφαση συνδέεται πίσω με τις πηγαίες της υποβολές. Κάθε απόφαση προσδιορίζει ποια αρχεία επηρεάζει. Οι σχέσεις ανάμεσα σε αποφάσεις είναι ρητές.

Ενσωμάτωση CLI: Ερωτήματα στη Θεσμική Μνήμη

Εδώ είναι όπου κλείνει ο βρόχος. Οι πράκτορες μπορούν να θέτουν ερωτήματα σε αποφάσεις μέσω του CLI:

# Search by topic
uv run orkestra registry decisions search --query "retry"

Επιστρέφει αποφάσεις σχετικά με λογική επανάληψης αποτυχημένων προσπαθειών, χειρισμό σφαλμάτων, μοτίβα ανάκαμψης.

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

Επιστρέφει το πλήρες αρχείο απόφασης με πλαίσιο, αιτιολόγηση και επίδραση.

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

Δείχνει ποιες αρχιτεκτονικές επιλογές έγιναν πρόσφατα.

Πώς οι Πράκτορες το Χρησιμοποιούν

Οι βασικές οδηγίες του ενορχηστρωτή μας περιλαμβάνουν:

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

Όταν ζητείται από έναν πράκτορα να υλοποιήσει κάτι σχετικό με το DuckDB, μπορεί πρώτα να ελέγξει:

uv run orkestra registry decisions search --query "DuckDB"

Και να ανακαλύψει το DEC-PL-142, μαθαίνοντας:

Γιατί επιλέξαμε το DuckDB (πλαίσιο)
Πώς να το χρησιμοποιήσει σωστά (agent_guidance)
Ποια αρχεία να κοιτάξει (files)
Ποιες σχετικές αποφάσεις υπάρχουν (related)

Ο πράκτορας δεν ανακαλύπτει ξανά τον τροχό. Χτίζει πάνω σε καθιερωμένα μοτίβα.

Το Τεστ των Τριών Ερωτημάτων

Δεν αξίζει κάθε υποβολή ένα αρχείο απόφασης. Χρησιμοποιούμε το Τεστ των Τριών Ερωτημάτων για να φιλτράρουμε:

Ήταν δύσκολο να ληφθεί; Απαίτησε σημαντική ανάλυση, αξιολόγηση συμβιβασμών ή συζήτηση;
Είναι δαπανηρό να αλλάξει; Θα απαιτούσε η αντιστροφή αυτής της απόφασης σημαντική επανεργασία;
Έχει επίδραση σε όλο το σύστημα; Επηρεάζει πολλαπλά πακέτα ή θεσπίζει μοτίβα που θα ακολουθήσουν άλλοι;

Αν μια υποβολή απαντά «ναι» σε τουλάχιστον ένα από αυτά τα ερωτήματα, είναι υποψήφια για εξαγωγή απόφασης. Ο τυπικός μας ρυθμός: 1-4 αποφάσεις ανά 100 υποβολές (περίπου 1-4%).

Για καταχωρίσεις ιστορικού αλλαγών, ο πήχης είναι χαμηλότερος: κάθε αλλαγή ορατή στον χρήστη (χαρακτηριστικά, διορθώσεις, βελτιώσεις) καταγράφεται. Εσωτερικές δουλειές συντήρησης, ενημερώσεις τεκμηρίωσης και αναδιαμορφώσεις συνήθως παραλείπονται. Ο τυπικός μας ρυθμός: 30-50 καταχωρίσεις ιστορικού αλλαγών ανά 100 υποβολές.

Αποθήκευση Δεδομένων: Καθολικά Μόνο-για-Προσθήκη

Το σύστημα εξόρυξης χρησιμοποιεί καθολικά JSONL μόνο-για-προσθήκη για λειτουργία χωρίς συγκρούσεις με πολλούς πράκτορες:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

Η μορφή JSONL με το merge=union στο .gitattributes σημαίνει ότι πολλοί πράκτορες μπορούν να ταξινομούν υποβολές ταυτόχρονα χωρίς συγκρούσεις συγχώνευσης. Κάθε γραμμή είναι ανεξάρτητη.

Πύλες Επικύρωσης

Πριν από κάθε συνεδρία εξόρυξης, τρέχουμε επικύρωση:

uv run orkestra mine validate --quick

Αυτό ελέγχει:

Εγκυρότητα μορφής SHA
Συμμόρφωση μορφής ID απόφασης
Καμία διπλή καταχώριση για το ίδιο SHA
Ότι οι αναφερόμενες αποφάσεις όντως υπάρχουν

Μετά την ταξινόμηση, επικυρώνουμε ξανά πριν υποβάλουμε τις αλλαγές.

Γιατί Έχει Σημασία

Ο βρόχος ανάδρασης που χτίσαμε λύνει αρκετά προβλήματα:

Για νέα μέλη της ομάδας: Αντί να ρωτούν «γιατί κάναμε το X;», μπορούν να αναζητήσουν στο μητρώο αποφάσεων. Το πλαίσιο διατηρείται.

Για πράκτορες AI: Δεν λειτουργούν σε κενό. Μπορούν να θέτουν ερωτήματα στη θεσμική γνώση πριν κάνουν συστάσεις. Όταν τους ζητηθεί να προσθέσουν ένα νέο στάδιο αγωγού, μπορούν να ανακαλύψουν το μοτίβο DuckDB και να το ακολουθήσουν.

Για αρχιτεκτονική συνέπεια: Οι αποφάσεις είναι ρητές και αναζητήσιμες. Όταν κάποιος προτείνει μια προσέγγιση που έρχεται σε αντίθεση με μια υπάρχουσα απόφαση, το σύστημα μπορεί να αναδείξει τη σύγκρουση.

Για δημιουργία ιστορικού αλλαγών: Οι σημειώσεις έκδοσης δεν είναι μια πανικόβλητη εργασία της τελευταίας στιγμής. Είναι παραπροϊόν συνεχούς ταξινόμησης κατά την ανάπτυξη.

Για ένταξη νέων μελών: Οι νέοι πράκτορες κληρονομούν το πλήρες πλαίσιο της βάσης κώδικα. Δεν βλέπουν απλώς τον κώδικα — βλέπουν τις αποφάσεις που τον διαμόρφωσαν.

Τρέχουσα Κατάσταση

Έως σήμερα:

15.637 υποβολές έχουν υποβληθεί σε επεξεργασία μέσω του αγωγού
476 αρχιτεκτονικές αποφάσεις εξήχθησαν και τεκμηριώθηκαν
6.799 καταχωρίσεις ιστορικού αλλαγών καταγράφηκαν
100% κάλυψη και στους δύο τομείς

Κάθε υποβολή από τότε που ξεκινήσαμε έχει ταξινομηθεί. Η θεσμική μνήμη είναι πλήρης και αναζητήσιμη.

Ξεκινώντας

Αν θέλετε να υλοποιήσετε κάτι παρόμοιο:

Ξεκινήστε με το πρότυπο Conventional Commits. Ο αγωγός εξόρυξης λειτουργεί καλύτερα όταν οι υποβολές έχουν δομημένα προθέματα (feat:, fix:, chore:).
Ορίστε τους τομείς σας. Χρησιμοποιούμε τομείς όπως pipeline, agent-design, observability, data-modeling. Αυτοί οργανώνουν τις αποφάσεις κατά περιοχή.
Χτίστε τη συνήθεια ταξινόμησης. Η εξόρυξη λειτουργεί όταν οι ομάδες ταξινομούν τακτικά υποβολές. Η μαζική επεξεργασία με βοήθεια LLM βοηθά στην κλιμάκωση.
Κάντε τις αποφάσεις αναζητήσιμες. Η αξία πολλαπλασιάζεται όταν οι πράκτορες μπορούν να αναζητήσουν αποφάσεις μέσω CLI. Δομήστε την έξοδό σας για κατανάλωση από μηχανή.
Κλείστε τον βρόχο. Οι αποφάσεις πρέπει να επηρεάζουν τη μελλοντική εργασία. Συμπεριλάβετε αναφορές αποφάσεων σε οδηγίες πρακτόρων και λίστες ελέγχου επισκόπησης κώδικα.

Ο στόχος δεν είναι τέλεια τεκμηρίωση. Είναι να γίνει το γιατί πίσω από τις αλλαγές προσβάσιμο τόσο σε ανθρώπους όσο και σε AI, σήμερα και έξι μήνες από τώρα. Όταν οι αλλαγές γίνονται θεσμική μνήμη, οι ομάδες χτίζουν πάνω σε καθιερωμένα μοτίβα αντί να τα ανακαλύπτουν ξανά.

Η ροή εργασίας εξόρυξης είναι μέρος της μηχανής ενορχήστρωσής μας, συγκεκριμένα του αρθρώματος μηχανής πλαισίου στο πακέτο ενορχήστρωσής μας.

Εξόρυξη Δεξιοτήτων: Από 3.500 Υποψήφιες σε 466 Ικανότητες

Tue, 27 Jan 2026 00:00:00 GMT

Οι αριθμοί σε αυτή την ανάρτηση αντικατοπτρίζουν το σύστημα κατά τη δημοσίευση (Ιανουάριος 2026). Δείτε τη σελίδα ομάδας μας για τα τρέχοντα στοιχεία.

Το Πρόβλημα των 3.500 Δεξιοτήτων

Όταν ξεκινήσαμε να χτίζουμε ένα σύστημα ενορχήστρωσης πρακτόρων, αντιμετωπίσαμε μια ενδιαφέρουσα πρόκληση: υπάρχουν χιλιάδες πιθανές δεξιότητες διάσπαρτες σε όλο το οικοσύστημα AI. Αποθετήρια GitHub, τεκμηρίωση προμηθευτών, έργα κοινότητας, εσωτερικά μοτίβα — οι δεξιότητες υπάρχουν παντού. Όμως ποιες έχουν σημασία; Ποιες λειτουργούν; Και πώς διατηρείτε μια συνεκτική βιβλιοθήκη δεξιοτήτων που οι πράκτορες μπορούν πράγματι να χρησιμοποιήσουν;

Η απάντησή μας: ένας συστηματικός βρόχος εξόρυξης και ενσωμάτωσης.

Οι Αριθμοί Σήμερα

Μόλις λίγο πάνω από τρεις μήνες αφότου η Anthropic κυκλοφόρησε τα Agent Skills στις 16 Οκτωβρίου 2025, να πού βρισκόμασταν όταν δημοσιεύτηκε αυτή η ανάρτηση, στις 27 Ιανουαρίου 2026:

Μετρική	Αριθμός
Υποψήφιες εντοπισμένες	3.500+
Δεξιότητες υιοθετημένες	466
Δεξιότητες προμηθευτών	373
Εσωτερικές δεξιότητες	93
Ενεργοί προμηθευτές	25+
Μέσος όρος tokens ανά δεξιότητα	2.834
Εργαλεία που αναφέρονται	89
Μοναδικές ετικέτες	635

Έχουμε επισκοπήσει πάνω από 3.500 υποψήφιες δεξιότητες. Έχουμε υιοθετήσει 466. Αυτό είναι ποσοστό υιοθέτησης 13% — και αυτή η επιλεκτικότητα είναι σκόπιμη.

Το Σύστημα Επιπέδων Γνώσης

Δεν είναι όλες οι δεξιότητες ίδιες. Τις οργανώνουμε σε πέντε επίπεδα γνώσης (K0-K4), καθένα από τα οποία αντιπροσωπεύει διαφορετικό πεδίο εφαρμογής:

K0: Θεμέλια (Καθολικά)

Δεξιότητες που κάθε πράκτορας πρέπει να έχει. Αντιπροσωπεύουν ικανότητες τύπου «καλός στοχαστής» που λειτουργούν παντού.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

Οι δεξιότητες K0 είναι φορητές σε οποιοδήποτε έργο, οποιονδήποτε τομέα, οποιαδήποτε στοίβα. Κωδικοποιούν καθολικά γνωστικά μοτίβα.

K1: Ταυτότητες (Επαγγελματικός Κλάδος)

Δεξιότητες τύπου «καλός μηχανικός» ή «καλός ερευνητής» που εφαρμόζονται σε όλα τα έργα μέσα σε έναν επαγγελματικό κλάδο.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: Τομείς (Εξειδίκευση Θέματος)

Δεξιότητες τύπου «καλός ειδικός βάσεων δεδομένων» ή «καλός μηχανικός ασφάλειας» φορητές μέσα σε ένα πεδίο.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: Στοίβες (Τεχνολογία)

Δεξιότητες τύπου «καλός χρήστης Supabase» ή «καλός προγραμματιστής Cloudflare» για συγκεκριμένες στοίβες τεχνολογίας.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: Έργο (Οργανισμός)

Δεξιότητες ειδικές για τον οργανισμό και τις ροές εργασίας μας.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

Ο Βρόχος Εξόρυξης

Φάση 1: Ανακάλυψη

Οι δεξιότητες προέρχονται από παντού:

Αποθετήρια Προμηθευτών: Η AWS, η Anthropic, η Cloudflare, η Supabase και συνεισφέροντες της κοινότητας δημοσιεύουν συλλογές δεξιοτήτων. Παρακολουθούμε 25+ ρίζες προμηθευτών.

Έργα Κοινότητας: Το GitHub είναι γεμάτο πρότυπα Claude Code, μοτίβα πρακτόρων και ορισμούς ροών εργασίας.

Εσωτερικά Μοτίβα: Καθώς η ομάδα μας λύνει προβλήματα, αναδύονται μοτίβα. Αυτά τυποποιούνται σε δεξιότητες.

Εξόρυξη Τεκμηρίωσης: Η τεχνική τεκμηρίωση συχνά περιέχει σιωπηρές δεξιότητες — διαδικασίες, λίστες ελέγχου, δέντρα αποφάσεων.

Η ανακάλυψη είναι συνεχής. Χρησιμοποιούμε μια λίστα εκκρεμοτήτων δεξιοτήτων για να παρακολουθούμε υποψήφιες πριν από την επίσημη αξιολόγηση.

Φάση 2: Αξιολόγηση

Κάθε υποψήφια αξιολογείται με τα ίδια κριτήρια:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

Πρέπει να πληρούνται και τα πέντε κριτήρια προϊόντος. Γι’ αυτό το 87% των υποψηφίων απορρίπτεται.

Έπειτα κάθε υποψήφια περνά από ξεχωριστή επισκόπηση εμπιστοσύνης. Δεν αντιμετωπίζουμε ένα επίσημο αποθετήριο προμηθευτή, έναν γνωστό συντηρητή κοινότητας και ένα τυχαίο αποθετήριο GitHub ως ισοδύναμες πηγές αλήθειας.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

Οι έμπιστοι προμηθευτές παίρνουν μια ελαφρύτερη επισκόπηση προέλευσης, όχι όμως αυτόματη έγκριση. Οι μη έμπιστες ή άγνωστες πηγές παίρνουν έναν βαθύτερο χειροκίνητο έλεγχο, και δεν εκτελούμε συνοδευτικά σενάρια μέχρι να διαβαστούν, να οριοθετηθούν και να ταξινομηθούν ως ασφαλή.

Ανάλυση Κενού: Πριν την υιοθέτηση, αναζητούμε στο μητρώο μας:

uv run orkestra skills search "<capability>"

Αν το έχουμε ήδη, δεν το χρειαζόμαστε. Αν έχουμε κάτι κοντινό, μπορεί να συγχωνεύσουμε αντί να υιοθετήσουμε.

Βαθμολόγηση Βάθους και Προτύπων: Βαθμολογούμε επίσης πόσο πλήρως χρησιμοποιεί μια υποψήφια το μοντέλο δεξιότητας πράκτορα. Ένα μοναχικό SKILL.md μπορεί ακόμη να είναι χρήσιμο, όμως οι βαθύτερες δεξιότητες είναι πιο πολύτιμες όταν διαχωρίζουν οδηγίες από υλικό αναφοράς, σενάρια και πόρους με τον τρόπο που ενθαρρύνει το agentskills.io.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

Τα αστέρια GitHub μπορούν να ανεβάσουν λίγο μια βαθμολογία αξιοπιστίας, όμως ποτέ δεν σώζουν μια ρηχή ή ανασφαλή δεξιότητα. Ένα αποθετήριο με πολλά αστέρια αλλά με ένα ασαφές SKILL.md και αδιαφανή σενάρια βαθμολογείται χαμηλότερα από ένα μικρότερο αποθετήριο με ακριβή περιγραφή, επιμελημένα references/ και μικρά βοηθητικά προγράμματα με μία συγκεκριμένη λειτουργία που πράγματι αξιοποιούν την πλήρη ικανότητα της δεξιότητας.

Δομική Ανάλυση: Ελέγχουμε την ποιότητα της δεξιότητας:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

Αν μια υποψήφια περιλαμβάνει σενάρια, αυτή η επισκόπηση γίνεται πιο αυστηρή. Μια καλή δεξιότητα δεν είναι απλώς χρήσιμη· πρέπει να είναι ευανάγνωστη, οριοθετημένη και ασφαλής να δοθεί σε έναν πράκτορα. Αυτό το φίλτρο ασφάλειας από μόνο του αποκλείει ένα σημαντικό κομμάτι από κατά τα άλλα ενδιαφέρουσες υποψήφιες.

Φάση 3: Ενσωμάτωση

Όταν μια δεξιότητα περνά την αξιολόγηση, εισέρχεται στο μητρώο. Όμως οι δεξιότητες δεν υιοθετούνται ποτέ αναλλοίωτες. Τροποποιούνται ώστε να ταιριάζουν στο σύστημά μας.

Τροποποιήσεις κατά την Υιοθέτηση:

Κανονικοποίηση Μεταδεδομένων: Κάθε δεξιότητα παίρνει το δικό μας σχήμα frontmatter
Ανάθεση Επιπέδου K: Οι δεξιότητες τοποθετούνται στο κατάλληλο επίπεδο γνώσης
Εμπλουτισμός Ετικετών: Προστίθενται ετικέτες για ανακάλυψη
Δήλωση Εργαλείων: Τα επιτρεπόμενα εργαλεία δηλώνονται ρητά
Ευθυγράμμιση Ενοτήτων: Το περιεχόμενο αναδιαρθρώνεται ώστε να ταιριάζει στο πρότυπό μας

Ένα τυπικό YAML δεξιότητας μετά την ενσωμάτωση:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

Φάση 4: Ανάθεση Εμβέλειας

Οι δεξιότητες ανατίθενται σε εμβέλειες — κατηγορίες που καθορίζουν ποιοι πράκτορες φορτώνουν ποιες δεξιότητες:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

Οι πράκτορες δηλώνουν τις εμβέλειές τους, και οι δεξιότητες ανατίθενται αυτόματα:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

Φάση 5: Παραγωγή Αρχείων

Οι δεξιότητες δεν ζουν ως YAML στην παραγωγή. Αποδίδονται σε αρχεία SKILL.md που το Claude Code μπορεί να φορτώσει:

uv run orkestra sync

Αυτή η εντολή:

Διαβάζει όλους τους ορισμούς YAML δεξιοτήτων
Τους αποδίδει μέσω προτύπων Jinja
Γράφει αρχεία SKILL.md στο .claude/skills/
Οργανώνει κατά επίπεδο K (foundations/, identities/, domains/, stacks/, project/)

Η τελική δομή εξόδου:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

Το Μοτίβο της Αδρανούς Εμβέλειας

Ένα από τα πιο ισχυρά μοτίβα μας είναι δεξιότητες «υιοθετημένες-αλλά-όχι-φορτωμένες». Τις ονομάζουμε αδρανείς εμβέλειες.

Σκεφτείτε δεξιότητες επιστημονικής υπολογιστικής από το αποθετήριο k-dense-scientific. Έχουμε υιοθετήσει 120+ δεξιότητες που καλύπτουν βιοπληροφορική, χημεία, κβαντικούς υπολογιστές και κλινική πληροφορική. Όμως οι περισσότεροι πράκτορές μας δεν χρειάζονται μοριακή προσάρτηση ή ανάλυση γονιδιακής έκφρασης.

Αντί να φορτώνουμε και τις 120 δεξιότητες σε κάθε πράκτορα (φουσκώνοντας τα παράθυρα πλαισίου), εμείς:

Υιοθετούμε τις δεξιότητες με μια συγκεκριμένη εμβέλεια (π.χ. bioinformatics)
Τις κρατάμε αδρανείς — καταχωρημένες αλλά όχι φορτωμένες
Τις ενεργοποιούμε μόνο όταν ένας πράκτορας δηλώνει εκείνη την εμβέλεια

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

Αυτό το μοτίβο μας επιτρέπει να έχουμε 466 δεξιότητες στο μητρώο ενώ οι τυπικοί πράκτορες φορτώνουν μόνο 40-60 σχετικές.

Τύποι Δεξιοτήτων

Οι δεξιότητες έρχονται σε τρία γνωστικά μοτίβα:

Ροή Εργασίας

Διατεταγμένα διαδικαστικά βήματα: «1. Κάνε X, 2. Μετά Y, 3. Τέλος Z»

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

Πειθαρχία

Όρια συμπεριφοράς: «Πάντα X», «Ποτέ Y», «Προτίμησε Z»

type: discipline
# Examples: test-first-discipline, evidence-based-completion

Λίστα Ελέγχου

Κριτήρια επαλήθευσης: «Επιβεβαίωσε X», «Επαλήθευσε Y», «Έλεγξε Z»

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

Πύλες Ποιότητας

Κάθε δεξιότητα πρέπει να περάσει επικύρωση πριν κυκλοφορήσει:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

Οι περιγραφές πρέπει να είναι 50-400 χαρακτήρες με φράσεις ενεργοποίησης («Χρησιμοποίησε όταν…», «Όταν χρειάζεσαι…»), ώστε το Claude Code να ξέρει πότε να τις προτείνει.

Επικυρώνουμε συνεχώς:

uv run orkestra validate --show-warnings

Το Οικοσύστημα Προμηθευτών

Οι 373 δεξιότητες προμηθευτών μας προέρχονται από:

Προμηθευτής	Δεξιότητες	Τομέας
AWS Agent	19	Υπηρεσίες cloud
Anthropic	12	Δημιουργία εγγράφων
Cloudflare	8	Υπολογιστική άκρης δικτύου
Supabase	5	Βάση δεδομένων
k-dense	100+	Επιστημονική υπολογιστική
silvainfm	4	Επιστήμη δεδομένων
Java Developer Kit	45+	Spring/Java
Vercel	1	Αυτοματισμός προγράμματος περιήγησης

Κάθε ρίζα προμηθευτή δηλώνεται στο metadata.yaml:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

Όταν τρέχει το orkestra sync, οι δεξιότητες προμηθευτών γίνονται symlink στο .claude/skills/vendor/ με το namespace του προμηθευτή τους.

Τι Μάθαμε

Η επιλεκτικότητα αποδίδει. Είναι δελεαστικό να υιοθετείτε οτιδήποτε φαίνεται χρήσιμο. Όμως κάθε δεξιότητα κοστίζει tokens. Με μέσο όρο 2.834 tokens ανά δεξιότητα, το περιττό περιεχόμενο γεμίζει γρήγορα το πλαίσιο. Το ποσοστό υιοθέτησής μας 13% κρατά τους πράκτορες ευέλικτους.

Η δομή επιτρέπει ανακάλυψη. Το σύστημα επιπέδων K δεν είναι απλώς οργάνωση — αφορά τη φορητότητα. Οι δεξιότητες K0 μπορούν να επαναχρησιμοποιηθούν οπουδήποτε. Οι δεξιότητες K4 είναι σκόπιμα ειδικές για το έργο. Αυτή η σαφήνεια βοηθά τόσο τους ανθρώπους όσο και τους πράκτορες να βρουν αυτό που χρειάζονται.

Οι αδρανείς εμβέλειες κλιμακώνονται. Μπορείτε να υιοθετήσετε εκατοντάδες δεξιότητες χωρίς να τις φορτώσετε όλες. Οι εμβέλειες σας επιτρέπουν να χτίσετε ένα εκτενές μητρώο διατηρώντας παράλληλα διαχειρίσιμα τα παράθυρα πλαισίου κάθε πράκτορα.

Η τροποποίηση κατά την υιοθέτηση είναι απαραίτητη. Οι ακατέργαστες δεξιότητες προμηθευτών σπάνια ταιριάζουν στο σύστημά σας. Η διαδικασία ενσωμάτωσης — προσθήκη μεταδεδομένων, ανάθεση επιπέδων, εμπλουτισμός ετικετών — κάνει τις εξωτερικές δεξιότητες να λειτουργούν εσωτερικά.

Η εξόρυξη είναι συνεχής. Ο αριθμός 3.500 συνεχίζει να μεγαλώνει. Νέα αποθετήρια προμηθευτών εμφανίζονται. Μοτίβα κοινότητας αναδύονται. Εσωτερικές ροές εργασίας σταθεροποιούνται. Ο βρόχος ποτέ δεν σταματά.

Τι Ακολουθεί

Δουλεύουμε σε αρκετές βελτιώσεις:

Αυτοματοποιημένος εντοπισμός κενών: Ειδοποίηση όταν συνηθισμένες αστοχίες πρακτόρων θα μπορούσαν να αντιμετωπιστούν από μια μη υιοθετημένη δεξιότητα
Ροές εργασίας κατάργησης δεξιοτήτων: Επίσημη διαδικασία για την απόσυρση δεξιοτήτων που έχουν αντικατασταθεί ή δεν χρησιμοποιούνται
Εξαρτήσεις μεταξύ δεξιοτήτων: Ρητή δήλωση προαπαιτούμενων δεξιοτήτων
Αναλυτικά χρήσης: Παρακολούθηση του ποιες δεξιότητες πράγματι καλούν οι πράκτορες και ποιες απλώς φορτώνουν

Ο βρόχος εξόρυξης δεξιοτήτων είναι υποδομή. Δεν είναι εντυπωσιακός. Όμως είναι αυτό που κάνει 41 πράκτορες να λειτουργούν συνεκτικά με 466 ικανότητες, παραμένοντας μέσα στα όρια πλαισίου.

Αυτή είναι η ιστορία του πώς το 3.500 γίνεται 466. Όχι αγνοώντας τα 3.000 — αξιολογώντας τα συστηματικά και υιοθετώντας μόνο ό,τι λειτουργεί.

Θέλετε να δείτε το σύστημα δεξιοτήτων σε δράση; Δείτε το uv run orkestra skills list για να εξερευνήσετε το τρέχον μητρώο μας.

Προοδευτική Αποκάλυψη: Παράθυρα CLI στα Συστήματα Πρακτόρων

Tue, 20 Jan 2026 00:00:00 GMT

Οι αριθμοί σε αυτή την ανάρτηση αντικατοπτρίζουν το σύστημα κατά τη δημοσίευση (Ιανουάριος 2026). Δείτε τη σελίδα ομάδας μας για τα τρέχοντα στοιχεία.

Τα συστήματα πρακτόρων είναι αδιαφανή εκ σχεδιασμού. Λαμβάνουν αποφάσεις, καλούν εργαλεία και συντονίζουν εργασία σε δεκάδες ειδικούς. Όμως όταν κάτι πάει στραβά — ή όταν απλώς θέλετε να καταλάβετε τι συμβαίνει — πού κοιτάτε;

Η απάντηση είναι η προοδευτική αποκάλυψη: μια διαστρωματωμένη διεπαφή που αποκαλύπτει ακριβώς όση πολυπλοκότητα χρειάζεστε, ακριβώς όταν τη χρειάζεστε.

Το Πρόβλημα της Αδιαφάνειας

Ένα σύγχρονο σύστημα ενορχήστρωσης πρακτόρων μπορεί να έχει:

40+ εξειδικευμένους πράκτορες, καθέναν με διακριτές ικανότητες
700+ δεξιότητες που καλύπτουν εσωτερικό αυτοματισμό και ενσωματώσεις προμηθευτών
470+ αρχιτεκτονικές αποφάσεις που διαμορφώνουν τη συμπεριφορά
Δεκάδες διακομιστές εργαλείων MCP που παρέχουν εξωτερικές δυνατότητες

Αυτή η πολυπλοκότητα είναι σκόπιμη. Οι πράκτορες χρειάζονται πρόσβαση σε πλούσιο πλαίσιο — γνώση τομέα, ευφυΐα κώδικα, σχήματα βάσεων δεδομένων — για να λαμβάνουν καλές αποφάσεις. Όμως αυτός ο ίδιος πλούτος δημιουργεί ένα πρόβλημα ορατότητας.

Πώς ξέρετε ποιος πράκτορας χειρίζεται τις μεταβολές σχήματος βάσεων δεδομένων; Ποιες αποφάσεις διαμόρφωσαν τη συμπεριφορά κατάταξης του συστήματος αναζήτησης; Σε ποια εργαλεία έχει πρόσβαση ο σύμβουλος αρχιτεκτονικής;

Χωρίς δομημένη πρόσβαση, καταλήγετε να διαβάζετε τον πηγαίο κώδικα ή να ελπίζετε ότι η τεκμηρίωση είναι ενημερωμένη.

Η Προοδευτική Αποκάλυψη ως Αρχιτεκτονική

Η προοδευτική αποκάλυψη δεν είναι απλώς ένα μοτίβο διεπαφής χρήστη. Είναι μια αρχιτεκτονική αρχή: οργάνωσε την πληροφορία σε επίπεδα, το καθένα βαθύτερο από το προηγούμενο, ώστε οι χρήστες να μπορούν να σταματήσουν στο επίπεδο που απαντά στην ερώτησή τους.

Για συστήματα πρακτόρων, αυτό μεταφράζεται σε εντολές CLI σε αυξανόμενα βάθη:

Επίπεδο	Εντολή	Ερώτημα που Απαντιέται
1	`orkestra system status`	Είναι όλα υγιή;
2	`orkestra agents list`	Ποιοι πράκτορες υπάρχουν;
3	`orkestra agents info <name>`	Τι κάνει αυτός ο πράκτορας;
4	`orkestra decisions search`	Γιατί λειτουργεί έτσι;
5	Εργαλεία MCP του Maguyva	Δείξτε μου τον κώδικα.

Κάθε επίπεδο απαντά σε ένα φυσικό επόμενο ερώτημα. Σπάνια χρειάζεται να πηδήξετε κατευθείαν στο επίπεδο 5.

Επίπεδο 1: Υγεία Συστήματος

Το πρώτο ερώτημα είναι πάντα: λειτουργούν όλα;

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

Μία εντολή. Τέσσερις αριθμοί. Αρκετό για να ξέρετε ότι το σύστημα είναι διαμορφωμένο και τα μητρώα είναι γεμάτα.

Αν ο αριθμός πρακτόρων πέσει απρόσμενα ή αν οι δεξιότητες αποτύχουν να φορτωθούν, το βλέπετε εδώ πρώτα. Δεν χρειάζεται βουτιά σε αρχεία καταγραφής.

Επίπεδο 2: Απογραφή Πρακτόρων

Μόλις ξέρετε ότι το σύστημα είναι υγιές, το επόμενο ερώτημα είναι: τι είναι διαθέσιμο;

$ orkestra agents list

Αυτό επιστρέφει δομημένα δεδομένα — ονόματα πρακτόρων, περιγραφές, προτιμήσεις μοντέλου, κάλυψη τομέα. Η έξοδος είναι JSON από προεπιλογή, κάνοντάς την εύκολη να περάσει μέσω σωλήνωσης στο jq για φιλτράρισμα:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

Θέλετε πράκτορες που χειρίζονται εργασία βάσης δεδομένων; Η εντολή αναζήτησης το περιορίζει:

$ orkestra agents search "database"

Αυτό σαρώνει ονόματα, περιγραφές και δυνατότητες. Βρίσκετε τον σωστό ειδικό χωρίς να διαβάσετε 40 ορισμούς πρακτόρων.

Επίπεδο 3: Βαθιά Εξέταση Πράκτορα

Βρήκατε έναν πράκτορα που φαίνεται σχετικός; Η εντολή info αποκαλύπτει τα πάντα:

$ orkestra agents info architecture-advisor

Η έξοδος περιλαμβάνει:

Μεταδεδομένα: Όνομα, κατηγορία, προτίμηση μοντέλου, περιγραφή
Τομείς: Ποιες περιοχές γνώσης καλύπτει αυτός ο πράκτορας
Ταυτότητα: Χαρακτηριστικά προσωπικότητας (αρχιτέκτονας, στρατηγικός σχεδιαστής, αρχιτέκτονας γνώσης)
Οδηγοί εργαλείων: Ποια τεκμηρίωση εργαλείων προστίθεται στο πλαίσιο
Εργαλεία: Η πλήρης λίστα εργαλείων MCP διαθέσιμων σε αυτόν τον πράκτορα

Ένα δείγμα του τι βλέπετε:

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

Αυτό σας λέει ακριβώς τι μπορεί να κάνει ο πράκτορας. Δεν χρειάζεται πηγαίος κώδικας.

Επίπεδο 4: Αρχαιολογία Αποφάσεων

Οι πράκτορες συμπεριφέρονται σύμφωνα με τεκμηριωμένες αποφάσεις. Όταν χρειάζεται να καταλάβετε γιατί κάτι λειτουργεί με έναν συγκεκριμένο τρόπο, το μητρώο αποφάσεων είναι η πηγή αλήθειας.

$ orkestra decisions search "agent"

Αυτό επιστρέφει αντίστοιχες αρχιτεκτονικές αποφάσεις:

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

Κάθε απόφαση έχει πλήρη προέλευση — πότε λήφθηκε, γιατί, ποιοι συμβιβασμοί εξετάστηκαν, ποιες υποβολές την υλοποίησαν:

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

Αυτή είναι αρχιτεκτονική τεκμηρίωση που παραμένει ενημερωμένη επειδή εξορύσσεται από υποβολές, όχι επειδή συντηρείται χειροκίνητα.

Επίπεδο 5: Άμεση Ευφυΐα Κώδικα

Όταν χρειάζεται να δείτε την πραγματική υλοποίηση — όχι μεταδεδομένα γι’ αυτήν — τα εργαλεία MCP του Maguyva παρέχουν άμεση πρόσβαση.

Μέσα από μια συνεδρία πράκτορα:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Αυτό δρομολογεί αυτόματα σε σημασιολογική, κειμενική και αναζήτηση AST για να βρει σχετικό κώδικα. Για συγκεκριμένα σύμβολα:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Για ανάλυση εξαρτήσεων:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

Αυτά δεν είναι απλώς αντικαταστάτες του grep. Αξιοποιούν τον γράφο, διαθέτουν σημασιολογικό ευρετήριο και ενσωματώνονται στην ίδια ευφυΐα κώδικα που τροφοδοτεί τους ίδιους τους πράκτορες.

Ενοποιημένη Αναζήτηση σε Όλα τα Μητρώα

Μερικές φορές δεν ξέρετε ποιο μητρώο κρατά την απάντηση. Η ενοποιημένη αναζήτηση καλύπτει τα πάντα:

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 αντιστοιχίσεις σε πέντε μητρώα. Η περίληψη σας λέει πού να εμβαθύνετε. Αφαιρέστε το --summary για λεπτομερή αποτελέσματα, ή προσθέστε το --limit 5 για να κρατήσετε την έξοδο διαχειρίσιμη.

Γιατί Έχει Σημασία

Η προοδευτική αποκάλυψη δεν αφορά μόνο την ευκολία. Αλλάζει το πώς αλληλεπιδράτε με πολύπλοκα συστήματα.

Η αποσφαλμάτωση γίνεται διαχειρίσιμη. Όταν ένας πράκτορας λαμβάνει μια απρόσμενη απόφαση, δεν κάνετε grep σε αρχεία καταγραφής. Ελέγχετε σε ποια εργαλεία έχει πρόσβαση (agents info), ποιες αποφάσεις διαμορφώνουν τη συμπεριφορά του (decisions search), και ανιχνεύετε την υλοποίηση αν χρειάζεται (intelligent_search).

Η ένταξη νέων μελών επιταχύνεται. Τα νέα μέλη της ομάδας δεν χρειάζεται να διαβάσουν ολόκληρη τη βάση κώδικα. Ξεκινούν με το system status, εξερευνούν με το agents list, και εμβαθύνουν μόνο όταν συναντήσουν κάτι που δεν καταλαβαίνουν.

Η τεκμηρίωση παραμένει ενημερωμένη. Επειδή το CLI διαβάζει από τα ίδια μητρώα που διαμορφώνουν τους πράκτορες, η έξοδος είναι πάντα ακριβής. Δεν υπάρχει απόκλιση ανάμεσα σε αυτό που λένε τα έγγραφα και σε αυτό που κάνει το σύστημα.

Το CLI ως Διεπαφή

Θα μπορούσαμε να είχαμε χτίσει έναν πίνακα ελέγχου web. Θα μπορούσαμε να είχαμε γράψει εκτενή τεκμηρίωση. Αντ’ αυτού, χτίσαμε ένα CLI που διαβάζει από την πηγή αλήθειας.

Το CLI έχει πλεονεκτήματα:

Συνθέσιμο: Περάστε την έξοδο μέσω σωλήνωσης στο jq, ενσωματώστε με σενάρια
Προγραμματιζόμενο: Αυτοματοποιήστε ελέγχους, δημιουργήστε αναφορές
Γρήγορο: Χωρίς φορτώσεις σελίδων, χωρίς ροές ταυτοποίησης
Ακριβές: Διαβάζει την πραγματική διαμόρφωση, όχι μια αποθηκευμένη αναπαράσταση σε κρυφή μνήμη

Για συστήματα όπου η ορθότητα έχει μεγαλύτερη σημασία από την αισθητική, το CLI κερδίζει.

Χτίζοντας τη Δική σας Προοδευτική Αποκάλυψη

Αν χτίζετε συστήματα πρακτόρων, σκεφτείτε πώς θα τα επιθεωρούν οι χρήστες:

Ξεκινήστε με ελέγχους υγείας. Μία εντολή που σας λέει αν τα πράγματα λειτουργούν.
Παρέχετε όψεις απογραφής. Καταγράψτε τι υπάρχει πριν εξηγήσετε τι κάνει.
Ενεργοποιήστε στοχευμένα ερωτήματα. Η αναζήτηση κερδίζει την περιήγηση σε κλίμακα.
Εκθέστε την προέλευση. Αφήστε τους χρήστες να ανιχνεύουν αποφάσεις μέχρι τις ρίζες τους.
Συνδεθείτε με την ευφυΐα κώδικα. Τελικά, οι χρήστες χρειάζεται να δουν την υλοποίηση.

Κάθε επίπεδο απαντά σε ένα επόμενο ερώτημα. Χτίστε τα με σειρά συχνότητας — οι περισσότεροι χρήστες σταματούν στο επίπεδο 2 ή 3. Μόνο οι προχωρημένοι χρήστες φτάνουν στο επίπεδο 5.

Ο στόχος δεν είναι να εκθέσετε τα πάντα. Είναι να εκθέσετε ακριβώς ό,τι χρειάζεται, ακριβώς όταν χρειάζεται. Αυτό είναι η προοδευτική αποκάλυψη εφαρμοσμένη στην αρχιτεκτονική πρακτόρων.

Ground Truths: Αγκυρώνοντας τους Πράκτορες AI στην Πραγματικότητα

Tue, 13 Jan 2026 00:00:00 GMT

Οι αριθμοί σε αυτή την ανάρτηση αντικατοπτρίζουν το σύστημα κατά τη δημοσίευση (Ιανουάριος 2026). Δείτε τη σελίδα ομάδας μας για τα τρέχοντα στοιχεία.

Οι πράκτορες AI είναι εντυπωσιακά ικανοί. Μπορούν να συλλογίζονται, να συνθέτουν και να παράγουν. Όμως έχουν μια θεμελιώδη αδυναμία: επινοούν πράγματα. Όχι κακόβουλα, αλλά με αυτοπεποίθηση. Ένας πράκτορας μπορεί να εφεύρει παραμέτρους API που δεν υπάρχουν, να αναφερθεί σε διαμορφώσεις που ποτέ δεν ορίστηκαν, ή να εφαρμόσει μοτίβα από τα δεδομένα εκπαίδευσής του που έρχονται σε αντίθεση με την πραγματική σας αρχιτεκτονική.

Ο τυπικός τρόπος αντιμετώπισης είναι «δώσε στον πράκτορα περισσότερο πλαίσιο». Όμως το πλαίσιο μπορεί να είναι αντιφατικό. Η τεκμηρίωση αποκλίνει από την υλοποίηση. Τα σχόλια λένε ψέματα. Ακόμη και ο κώδικας μπορεί να παραπλανήσει όταν διαβάζεται χωρίς κατανόηση της πρόθεσης.

Χρειαζόμασταν κάτι πιο ρητό. Κάτι που δεν θα μπορούσε να αγνοηθεί ή να παρερμηνευτεί. Κάτι που θα αγκύρωνε τους πράκτορες σε επαληθεύσιμη πραγματικότητα.

Τα ονομάζουμε Ground Truths.

Τι Είναι ένα Ground Truth;

Ένα ground truth είναι μια ρητή δήλωση γεγονότος με διαχείριση εκδόσεων που οι πράκτορες πρέπει να σέβονται. Δεν είναι τεκμηρίωση. Δεν είναι σχόλιο. Είναι μια οντότητα πρώτης τάξης στο σύστημα με:

Ένα μοναδικό αναγνωριστικό (όπως το GT-MAG-015 ή το GT-MAG-036)
Μια κατάσταση κύκλου ζωής (τρέχουσα, υπό εξέταση, ή απαρχαιωμένη)
Μια εμβέλεια (για ολόκληρη την πλατφόρμα, για συγκεκριμένο πακέτο ή για συγκεκριμένο τομέα)
Αποδεικτικά στοιχεία (διαδρομές αρχείων, URLs, ή αναφορές που αποδεικνύουν τη δήλωση)
Καθοδήγηση πράκτορα (ρητές οδηγίες τι να κάνει/τι να αποφύγει)

Ορίστε ένα παράδειγμα από την πλατφόρμα ευφυΐας κώδικα Maguyva μας:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

Αυτό δεν είναι πεζός λόγος. Είναι συμβόλαιο. Όταν ένας πράκτορας συναντά αυτό το ground truth, ξέρει:

Η προεπιλογή είναι ντετερμινιστική (κενά αποτελέσματα, όχι εικασίες από προσεγγιστική αντιστοίχιση)
Υπάρχουν συγκεκριμένες παράμετροι (find_similar, exact_match) με ορισμένες συμπεριφορές
Υπάρχουν αποδεικτικά στοιχεία σε συγκεκριμένα αρχεία που μπορούν να επαληθευτούν
Η δήλωση επαληθεύτηκε σε συγκεκριμένη ημερομηνία

Η Ανατομία ενός Μητρώου Ground Truth

Τα ground truths ζουν σε μητρώα YAML κάτω από το ai_assets/reference/ground_truths.yaml. Κάθε πακέτο ή τομέας μπορεί να έχει το δικό του μητρώο. Η δομή είναι:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

Το μητρώο περιλαμβάνει μεταδεδομένα για την ίδια τη συλλογή, διαμόρφωση απόδοσης για τη δημιουργία τεκμηρίωσης, και τις ίδιες τις δηλώσεις. Κάθε δήλωση ακολουθεί ένα αυστηρό σχήμα επικυρωμένο από μοντέλα Pydantic:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Πώς οι Πράκτορες Έχουν Πρόσβαση στα Ground Truths

Τα ground truths εκτίθενται μέσα από πολλαπλά κανάλια:

1. Αποδοσμένη Τεκμηρίωση

Η εντολή orkestra sync μετατρέπει μητρώα YAML σε αναγνώσιμο markdown:

uv run orkestra sync

Αυτό δημιουργεί αρχεία GROUND_TRUTHS.md που περιλαμβάνονται στο πλαίσιο του πράκτορα. Η αποδοσμένη έξοδος ομαδοποιεί τις δηλώσεις κατά κατάσταση και κατηγορία:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. Αναζήτηση CLI

Πράκτορες με πρόσβαση shell μπορούν να αναζητήσουν ground truths προγραμματιστικά:

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

Η συνάρτηση αναζήτησης βαθμολογεί αντιστοιχίσεις σε πολλαπλά πεδία με σταθμισμένη σχετικότητα:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. Σύνθεση Πλαισίου

Όταν οι πράκτορες αποδίδονται από ορισμούς YAML, το πλαίσιό τους μπορεί να αναφέρεται σε μητρώα ground truth:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

Αυτό εξασφαλίζει ότι τα σχετικά ground truths φορτώνονται πριν ο πράκτορας ξεκινήσει την εργασία.

Κατηγορίες Ground Truths

Κοιτάζοντας σε όλα τα μητρώα μας, τα ground truths συγκεντρώνονται σε αρκετά μοτίβα:

Αρχές Προϊόντος

Περιορισμοί για το τι είναι και τι δεν είναι το προϊόν:

«Το Maguyva είναι μόνο-για-ανάγνωση ως προς τα αποθετήρια χρηστών· το μόνο μη-ανακατασκευάσιμο στοιχείο είναι η πληρωμένη κρυφή μνήμη ενσωματωμάτων.» (GT-MAG-001)

Όρια Αρχιτεκτονικής

Πού ζουν οι ευθύνες και γιατί:

«Τα όρια ανάμεσα στο pipeline και το Maguyva είναι σκόπιμα: το pipeline είναι επαναχρησιμοποιήσιμο, το Maguyva κρατά τη λογική ειδική για κώδικα, και το CQRS διαχωρίζει τις εγγραφές σταδίου από τις αναγνώσεις διακομιστή.» (GT-MAG-006)

Κανόνες Κατά της Παραίσθησης

Ρητές εντολές που κρατούν τα συμβόλαια εργαλείων ντετερμινιστικά αντί για συναγόμενα:

«Η προσεγγιστική αντιστοίχιση συμβόλων είναι προαιρετική μέσω του find_similar=true. Η προεπιλεγμένη συμπεριφορά επιστρέφει κενά αποτελέσματα για ανύπαρκτα σύμβολα· το exact_match=true επιβάλλει αυστηρή αντιστοίχιση και απενεργοποιεί όλες τις εναλλακτικές προσεγγιστικής αντιστοίχισης.» (GT-MAG-015)

Πύλες Ποιότητας

Πρότυπα που πρέπει να διατηρούνται:

«Αλλαγές στην κοινόχρηστη υποδομή (post_filters.py, εξαγωγείς σχέσεων, κοινόχρηστοι χειριστές) ΠΡΕΠΕΙ να επικυρώνονται έναντι ΟΛΩΝ των υποστηριζόμενων γλωσσών μέσω πλήρους δημιουργίας μανιφέστου πριν από το commit. Μια επικύρωση μίας μόνο γλώσσας δεν επαρκεί για κοινόχρηστο κώδικα.» (GT-MAG-036)

Μοτίβα Κώδικα

Απαιτήσεις υλοποίησης:

«Χρησιμοποιήστε το asyncio.to_thread() για εργασία με έντονη χρήση CPU σε ασύγχρονα πλαίσια· το απαρχαιωμένο μοτίβο loop.run_in_executor() δεν πρέπει να χρησιμοποιείται σε νέο κώδικα.» (GT-MAG-018)

Ο Κύκλος Ζωής ενός Ground Truth

Τα ground truths δεν είναι στατικά. Εξελίσσονται μέσα από έναν ορισμένο κύκλο ζωής:

Υπό Εξέταση

Μια προτεινόμενη αλήθεια υπό αξιολόγηση. Η δήλωση καταγράφεται αλλά μπορεί να αλλάξει:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Τρέχουσα

Μια επαληθευμένη αλήθεια που οι πράκτορες πρέπει να σέβονται. Τα αποδεικτικά στοιχεία έχουν επικυρωθεί:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Απαρχαιωμένη

Μια αλήθεια που δεν ισχύει πλέον. Διατηρείται για ιστορική αναφορά με έναν δείκτη προς αυτό που την αντικατέστησε:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

Γιατί Όχι Απλώς Τεκμηρίωση;

Η τεκμηρίωση εξυπηρετεί διαφορετικό σκοπό. Εξηγεί. Διδάσκει. Μπορεί να είναι ασαφής, μπορεί να χρησιμοποιεί προσδιοριστικά όπως «γενικά» ή «συνήθως».

Τα ground truths δεν μπορούν να είναι ασαφή. Είναι διαβεβαιώσεις. Είτε ισχύουν είτε όχι.

Σκεφτείτε τη διαφορά:

Τεκμηρίωση: «Το API γενικά επιστρέφει κενά αποτελέσματα όταν δεν βρεθεί ένα σύμβολο, αν και η προσεγγιστική αντιστοίχιση μπορεί να είναι ενεργοποιημένη σε ορισμένες διαμορφώσεις.»

Ground Truth: «Η προεπιλεγμένη συμπεριφορά επιστρέφει κενά αποτελέσματα για ανύπαρκτα σύμβολα· το exact_match=true επιβάλλει αυστηρή αντιστοίχιση και απενεργοποιεί όλες τις εναλλακτικές προσεγγιστικής αντιστοίχισης.»

Το πρώτο είναι χρήσιμο για ανθρώπους που μαθαίνουν το σύστημα. Το δεύτερο είναι εφαρμόσιμο για πράκτορες που λαμβάνουν αποφάσεις.

Καθοδήγηση Πράκτορα: Κάντε και Αποφύγετε

Μερικά ground truths περιλαμβάνουν ρητή καθοδήγηση πράκτορα:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

Αυτό αφαιρεί την ασάφεια. Ένας πράκτορας που το διαβάζει ξέρει όχι μόνο τι είναι αληθές, αλλά και ποιες ενέργειες συνεπάγεται αυτή η αλήθεια.

Επαλήθευση και Συντήρηση

Τα ground truths χρειάζονται συντήρηση. Παρακολουθούμε:

last_verified: Πότε κάποιος επιβεβαίωσε ότι η δήλωση εξακολουθεί να ισχύει
evidence: Αρχεία που αποδεικνύουν τη δήλωση (μπορούν να ελεγχθούν για ύπαρξη)
source: Από πού προήλθε η αλήθεια (επιθεώρηση CLI, επισκόπηση αρχιτεκτονικής, μάθηση μετά από περιστατικό)

Ένα ground truth με παλιές ημερομηνίες επαλήθευσης ή σπασμένους συνδέσμους αποδεικτικών στοιχείων είναι ένα σήμα για διερεύνηση. Είτε η αλήθεια εξακολουθεί να ισχύει και χρειάζεται επανεπαλήθευση, είτε η πραγματικότητα άλλαξε και η αλήθεια χρειάζεται ενημέρωση.

Πραγματικά Παραδείγματα από την Παραγωγή

Όριο Ασφάλειας

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

Αυτό το ground truth αποτρέπει μια κατηγορία παραπλανημένων «βελτιώσεων ασφάλειας» που θα έσπαγαν το προϊόν.

Ακρίβεια Κατά τη Στιγμή της Εξαγωγής

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

Αυτό προήλθε από επώδυνη εμπειρία. Οι πράκτορες μπαλώνανε αποτυχημένα πακέτα γλωσσών προσθέτοντας φίλτρα που λειτουργούν μόνο στον επικυρωτή και έκαναν τα αποτελέσματα των δοκιμών να φαίνονται καλύτερα, ενώ ο ζωντανός εξαγωγέας Maguyva εξακολουθούσε να παράγει τις λάθος ακμές. Ο κανόνας αναγκάζει τις διορθώσεις πίσω στο πραγματικό μονοπάτι: διαμόρφωση YAML, ερωτήματα, ή χειριστές.

Πολυεπίπεδο Φιλτράρισμα

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

Αυτό εμποδίζει τους πράκτορες από το να προσθέτουν φίλτρα στο λάθος σημείο, ένα συνηθισμένο λάθος που προκάλεσε οπισθοδρομήσεις ακρίβειας.

Ενσωμάτωση με το Σύστημα Ενορχήστρωσης

Τα ground truths είναι ένα επίπεδο ενός ευρύτερου συστήματος πλαισίου:

Αρχιτεκτονικές Αποφάσεις (ADRs) - Καταγράφουν γιατί επιλέξαμε την προσέγγιση Α αντί της Β
Ground Truths - Δηλώνουν τι είναι οριστικά αληθές αυτή τη στιγμή
Μοτίβα Τομέα - Περιγράφουν πώς να κάνετε τα πράγματα σωστά
Αντι-Μοτίβα - Περιγράφουν τι να αποφύγετε και γιατί

Ένας πράκτορας που δουλεύει στο σύστημα έχει πρόσβαση και στα τέσσερα. Τα ground truths παρέχουν την πραγματολογική άγκυρα, ενώ οι αποφάσεις εξηγούν την ιστορία, τα μοτίβα καθοδηγούν την υλοποίηση, και τα αντι-μοτίβα προειδοποιούν για παγίδες.

Μέτρηση Επίδρασης

Από τότε που εισαγάγαμε τα ground truths, έχουμε παρατηρήσει:

Λιγότερους κύκλους «διόρθωσε τη λανθασμένη διόρθωση»
Πιο σίγουρη λήψη αποφάσεων από πράκτορες όταν τα γεγονότα είναι σαφή
Καλύτερες επισκοπήσεις PR επειδή οι προσδοκίες είναι ρητές
Μειωμένο χρόνο ένταξης για νέους πράκτορες (και ανθρώπους)

Η επένδυση στη συντήρηση των ground truths αποδίδει σε μειωμένη αποσφαλμάτωση και σαφέστερα όρια συστήματος.

Ξεκινώντας

Για να προσθέσετε ένα ground truth στο σύστημά σας:

Δημιουργήστε ένα ground_truths.yaml στον κατάλογο ai_assets/reference/ του πακέτου σας
Ορίστε μεταδεδομένα και διαμόρφωση απόδοσης
Προσθέστε δηλώσεις ακολουθώντας το σχήμα
Τρέξτε το uv run orkestra sync για να δημιουργήσετε τεκμηρίωση
Συμπεριλάβετε το μητρώο στη σύνθεση πλαισίου του πράκτορα

Ξεκινήστε με τα γεγονότα που προκαλούν τη μεγαλύτερη σύγχυση ή τους περιορισμούς που παραβιάζονται πιο συχνά. Αυτά είναι τα ground truths υψηλότερης αξίας σας.

Συμπέρασμα

Οι πράκτορες AI θα επινοούν ανακριβείς πληροφορίες. Αυτή είναι η φύση τους. Όμως μπορούμε να δημιουργήσουμε περιβάλλοντα όπου η παραίσθηση περιορίζεται, όπου ορισμένα γεγονότα δεν είναι διαπραγματεύσιμα, όπου οι πράκτορες μπορούν να ελέγχουν τις υποθέσεις τους έναντι επαληθευμένης πραγματικότητας.

Τα ground truths δεν είναι μια πλήρης λύση. Χρειάζονται συντήρηση. Μπορούν να παλιώσουν. Προσθέτουν επιβάρυνση στη διαδικασία ανάπτυξης.

Όμως προσφέρουν κάτι πολύτιμο: ένα κοινό λεξιλόγιο γεγονότων που τόσο άνθρωποι όσο και πράκτορες μπορούν να εμπιστευτούν. Σε έναν κόσμο όπου οι πράκτορες συμμετέχουν όλο και περισσότερο στην ανάπτυξη λογισμικού, αυτό το κοινό θεμέλιο γίνεται απαραίτητο.

Η εναλλακτική είναι ατέλειωτοι κύκλοι πρακτόρων που κάνουν λάθη με αυτοπεποίθηση και ανθρώπων που τα διορθώνουν. Τα ground truths σπάνε αυτόν τον κύκλο κάνοντας τις διορθώσεις ρητές και διαρκείς.

Οι πράκτορές σας αξίζουν να ξέρουν τι είναι αληθές. Πείτε τους το.

Orkestra: Ενορχηστρώνοντας Πράκτορες AI σε Κλίμακα

Tue, 06 Jan 2026 00:00:00 GMT

Οι αριθμοί σε αυτή την ανάρτηση αντικατοπτρίζουν το σύστημα κατά τη δημοσίευση (Ιανουάριος 2026). Δείτε τη σελίδα ομάδας μας για τα τρέχοντα στοιχεία.

Όταν ξεκινήσαμε να χτίζουμε με το Claude Code, πέσαμε πάνω σε ένα πρόβλημα που κάθε ομάδα που χρησιμοποιεί βοηθούς κώδικα AI αντιμετωπίζει τελικά: ένας μεμονωμένος πράκτορας δεν μπορεί να κάνει τα πάντα καλά.

Μπορείτε να προτρέψετε έναν πράκτορα να είναι ειδικός βάσεων δεδομένων. Ή ελεγκτής ασφάλειας. Ή μηχανικός της πλευράς χρήστη. Όμως τη στιγμή που του ζητάτε να είναι και τα τρία ταυτόχρονα, η ποιότητα υποφέρει. Το πλαίσιο αραιώνει. Οι οδηγίες συγκρούονται. Ο πράκτορας γίνεται ένας γενικολόγος που είναι μέτριος σε όλα.

Έτσι χτίσαμε το Orkestra.

Τι Είναι το Orkestra;

Το Orkestra είναι ένα σύστημα ενορχήστρωσης πρακτόρων για το Claude Code και παρόμοια εργαλεία κώδικα AI. Συντονίζει πολλαπλούς εξειδικευμένους πράκτορες, καθέναν με διαφορετική εξειδίκευση, κάτω από έναν μοναδικό ενορχηστρωτή που δρομολογεί εργασία στον σωστό ειδικό.

Σκεφτείτε το ως ένα γραφείο στελέχωσης για πράκτορες AI. Ο ενορχηστρωτής λαμβάνει μια εργασία, εντοπίζει ποιος ειδικός πρέπει να τη χειριστεί, και την αναθέτει με το σωστό πλαίσιο. Όταν η εργασία ολοκληρωθεί, τα αποτελέσματα ρέουν πίσω στον ενορχηστρωτή για σύνθεση.

Οι αριθμοί λένε την ιστορία:

Στοιχείο	Αριθμός
Εξειδικευμένοι πράκτορες	46
Επαναχρησιμοποιήσιμες δεξιότητες	466
Αρχέτυπα ταυτότητας	27
Νοοτροπίες	11
Στυλ επικοινωνίας	10
Τομείς γνώσης	21

Το Σύστημα Χαρακτήρων: D&D για Πράκτορες

Η βασική διορατικότητα πίσω από το Orkestra είναι ότι η συμπεριφορά ενός πράκτορα αναδύεται από τρία συνθέσιμα δομικά στοιχεία:

Η Ταυτότητα ορίζει τι είναι ο πράκτορας. Ένας αρχιτέκτονας σχεδιάζει δομές συστημάτων. Ένας αποσφαλματωτής ανιχνεύει αστοχίες μέχρι τη ρίζα τους. Ένας φύλακας επιβάλλει συμμόρφωση και όρια ασφάλειας. Έχουμε 27 αρχέτυπα ταυτότητας που μπορούν να συνδυαστούν.

Η Νοοτροπία ορίζει πώς σκέφτεται ο πράκτορας. Μια αναλυτική νοοτροπία θεμελιώνει τους ισχυρισμούς σε στοιχεία και ποσοτικοποιεί την αβεβαιότητα. Μια σκεπτικιστική νοοτροπία αμφισβητεί τις υποθέσεις και αναζητά στοιχεία που τις διαψεύδουν. Μια εξερευνητική νοοτροπία αγκαλιάζει την ασάφεια και δοκιμάζει πολλαπλές προσεγγίσεις.

Το Στυλ ορίζει πώς επικοινωνεί ο πράκτορας. Ένα τεχνικό στυλ περιλαμβάνει ακριβείς τιμές και αναφέρεται σε συγκεκριμένα αρχεία. Ένα συνοπτικό στυλ κόβει το περιττό και ξεκινά με την απάντηση. Ένα διπλωματικό στυλ ισορροπεί την ειλικρίνεια με το τακτ.

Ένας πράκτορας συνδυάζει αυτά τα δομικά στοιχεία:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Αυτή η σύνθεση δημιουργεί έναν πράκτορα που σχεδιάζει συστήματα (αρχιτέκτονας), συνδέει γνώση σε διάφορους τομείς (αρχιτέκτονας γνώσης), θέτει στρατηγική κατεύθυνση (στρατηγικός σχεδιαστής), σκέφτεται με στοιχεία και δεδομένα (αναλυτικός), και επικοινωνεί χωρίς περιττά (συνοπτικός).

Η δύναμη βρίσκεται στη συνδυαστική έκρηξη. 27 ταυτότητες επί 11 νοοτροπίες επί 10 στυλ αποδίδουν σχεδόν 3.000 πιθανές προσωπικότητες πρακτόρων. Όμως ορίζετε μόνο τους συνδυασμούς που έχουν σημασία για τη δουλειά σας.

Δεξιότητες: Επαναχρησιμοποιήσιμα Αρθρώματα Ικανοτήτων

Οι δεξιότητες είναι η γνώση και οι ροές εργασίας που μπορούν να επικαλεστούν οι πράκτορες. Ακολουθούν ένα διαβαθμισμένο σύστημα βασισμένο στην εμβέλεια:

Επίπεδο	Όνομα	Εμβέλεια	Παράδειγμα
K0	Θεμέλια	Καθολική μεθοδολογία	Πειθαρχία πρώτα-το-τεστ, ολοκλήρωση βασισμένη σε στοιχεία
K1	Ταυτότητες	Ροές εργασίας βασισμένες σε ρόλο	Πρότυπα διεπαφής CLI, εγχειρίδιο απόδοσης
K2	Τομείς	Γνώση ειδική για τομέα	Μοτίβα μετάβασης βάσεων δεδομένων, επικύρωση ταυτοποίησης
K3	Στοίβες	Ειδικές για τεχνολογία	Ανάπτυξη Cloudflare, λειτουργίες Supabase
K4	Έργο	Μόνο αυτή η βάση κώδικα	Ροές εργασίας και συμβάσεις ειδικές για το έργο

Οι δεξιότητες φορτώνονται μόνο όταν χρειάζονται. Ένας πράκτορας βλέπει ονόματα και περιγραφές δεξιοτήτων κατά την εκκίνηση, όμως το πλήρες περιεχόμενο μιας δεξιότητας φορτώνεται μόνο όταν ενεργοποιείται. Αυτό κρατά το πλαίσιο ελαφρύ ενώ κάνει εκατοντάδες δεξιότητες ανακαλύψιμες.

Κάθε δεξιότητα περιλαμβάνει:

Σαφείς συνθήκες ενεργοποίησης («Χρησιμοποίησε όταν μεταβάλλεις σχήματα βάσεων δεδομένων»)
Καθοδήγηση βήμα-προς-βήμα
Επιτρεπόμενα εργαλεία για τη ροή εργασίας
Κριτήρια επιτυχίας και διαδρομές ανάκαμψης από αποτυχία

Οι 466 δεξιότητες στο μητρώο μας καλύπτουν τα πάντα, από την απομόνωση git worktree έως ροές εργασίας διαδικτυακής έρευνας έως έλεγχο σωστής λειτουργίας μετά την εγκατάσταση.

Γιατί Έχει Σημασία η Ενορχήστρωση

Οι αρχιτεκτονικές ενός-πράκτορα προσκρούουν γρήγορα σε τοίχους:

Αραίωση πλαισίου. Ένα παράθυρο πλαισίου 200 χιλιάδων tokens ακούγεται μεγάλο μέχρι να φορτώσετε σχήματα βάσεων δεδομένων, τεκμηρίωση API, fixtures δοκιμών και γνώση τομέα. Οι ειδικοί μπορούν να δουλέψουν με στοχευμένο πλαίσιο.

Συγκρούσεις οδηγιών. Το να λέτε σε έναν πράκτορα να είναι «διεξοδικός αλλά γρήγορος» και να «επαληθεύει τα πάντα αλλά να μην υπερμηχανικοποιεί» δημιουργεί ένταση. Οι ειδικοί το λύνουν αυτό έχοντας σαφή εμβέλεια.

Βάθος εξειδίκευσης. Ένας γενικολόγος πράκτορας ξέρει λίγα για τα πάντα. Ένας εξειδικευμένος πράκτορας, συντεθειμένος με τη σωστή ταυτότητα και δεξιότητες, γνωρίζει τον τομέα του σε βάθος.

Το Orkestra υλοποιεί επίπεδη ενορχήστρωση: ένας ενορχηστρωτής συντονίζει πολλαπλούς ειδικούς. Οι ειδικοί δεν μπορούν να γεννήσουν υπο-ειδικούς. Αυτό αποτρέπει την έκρηξη πολυπλοκότητας ενώ επιτρέπει παράλληλη εργασία.

Ο ενορχηστρωτής έχει πρόσβαση σε 2,2 εκατομμύρια tokens ενεργής χωρητικότητας: το δικό του παράθυρο 200 χιλιάδων συν 10 ταυτόχρονους υπο-πράκτορες με από 200 χιλιάδες τον καθένα. Εργασία που θα εξαντλούσε έναν μεμονωμένο πράκτορα τρέχει άνετα σε όλο τον στόλο.

Το Pipeline Παραγωγής Αρχείων

Οι ορισμοί πρακτόρων ζουν σε YAML. Το Claude Code διαβάζει Markdown. Το Orkestra γεφυρώνει αυτό το χάσμα με έναν ντετερμινιστικό pipeline παραγωγής αρχείων:

YAML Registries → Jinja Templates → .claude/agents/*.md

Οι χειριστές επεξεργάζονται πηγή YAML. Τρέχουν το orkestra sync. Το αποδοσμένο Markdown εμφανίζεται στο .claude/agents/. Το Claude Code παίρνει τις αλλαγές.

Αυτός ο διαχωρισμός εξυπηρετεί διαφορετικά ακροατήρια:

Η πηγή YAML περιλαμβάνει μεταδεδομένα κύκλου ζωής, ετικέτες, κανόνες επικύρωσης και σημειώσεις κατάργησης για τα εργαλεία
Το αποδοσμένο Markdown περιλαμβάνει μόνο ό,τι χρειάζεται το μοντέλο: περιγραφή, εργαλεία, δεξιότητες και συμπεριφορική καθοδήγηση

Ο αγωγός συνθέτει ταυτότητες, νοοτροπίες, στυλ και δεξιότητες σε μία ενιαία συνεκτική προτροπή. Ένας πράκτορας αρχιτέκτονας-αναλυτικός-συνοπτικός παίρνει μια πολύ διαφορετική προτροπή συστήματος από έναν πράκτορα αποσφαλματωτής-σκεπτικιστής-τεχνικός, ακόμη και αν μοιράζονται κάποιες υποκείμενες δεξιότητες.

Γνώση Τομέα: Το Μοτίβο Τεσσάρων Αρχείων

Κάθε τομέας γνώσης ακολουθεί μια συνεπή δομή:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Αυτή η δομή εξυπηρετεί τη φόρτωση πλαισίου πράκτορα. Ένας πράκτορας που δουλεύει σε ταυτοποίηση φορτώνει το authentication/patterns.md για καθοδήγηση και το authentication/anti-patterns.md για να αποφύγει γνωστές παγίδες. Τα αρχεία έχουν μέγεθος για αποδοτική φόρτωση πλαισίου: αρκετά εστιασμένα για να είναι χρήσιμα, αρκετά εκτενή για να είναι έγκυρα.

Διατηρούμε 21 τομείς ανώτατου επιπέδου, συμπεριλαμβανομένων αναλυτικών, ταυτοποίησης, επιστήμης δεδομένων, υποδομής, μηχανικής μάθησης, απόδοσης, ασφάλειας και άλλων. Κάθε τομέας μπορεί να έχει υπο-τομείς για μεγαλύτερη εξειδίκευση.

Αξίες: Το Λειτουργικό Σύστημα

Όλοι οι πράκτορες μοιράζονται ένα βασικό επίπεδο αξιών που ορίζουν πώς λειτουργούν:

Απλότητα πρώτα. Χρησιμοποίησε την απλούστερη λύση που λειτουργεί. Πρόσθεσε πολυπλοκότητα μόνο όταν δικαιολογείται.

Διόρθωσε τις βασικές αιτίες. Ποτέ μην μπαλώνεις γύρω από αστοχίες. Αν ένας αγωγός αποτυγχάνει, αποσφαλμάτωσε τον αγωγό. Αν ένα τεστ αποτυγχάνει, διόρθωσε τον κώδικα ή το τεστ.

Βασισμένο σε στοιχεία. Χαρακτήρισε τους ισχυρισμούς ως «επαληθευμένους» (με benchmarks) ή «εκτιμώμενους» (με υποθέσεις). Ένα μοτίβο που εντοπίστηκε δεν ισοδυναμεί με πρόβλημα που επιβεβαιώθηκε.

Οικονομικά πλαισίου. Τα εργαλεία MCP κοστίζουν 0,1% του πλαισίου. Οι αναγνώσεις αρχείων κοστίζουν 2% η καθεμία. Εφάρμοσε εξειδίκευση τομέα πριν εξερευνήσεις τον κώδικα.

Αυτές οι αξίες διαχέονται σε κάθε ειδικό μέσω του pipeline παραγωγής αρχείων. Ο τρόπος σύνθεσης του πράκτορα δεν του επιτρέπει να τις παρακάμψει.

CLI: Το Επίπεδο Ελέγχου

Το Orkestra διανέμεται με ένα CLI για τη διαχείριση του οικοσυστήματος πρακτόρων:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

Το CLI είναι η πηγή αλήθειας για το ποιοι πράκτορες υπάρχουν, ποιες δεξιότητες έχουν, και αν το σύστημα είναι υγιές. Τρέχει επικύρωση πριν από τον συγχρονισμό για να πιάσει προβλήματα νωρίς.

Σκέψεις για Ανοιχτό Κώδικα

Χτίσαμε το Orkestra για να λύσουμε το δικό μας πρόβλημα: τον συντονισμό πρακτόρων AI σε κλίμακα για μια πολύπλοκη βάση κώδικα. Τα μοτίβα που ανακαλύψαμε δεν είναι ειδικά για τον δικό μας τομέα.

Το σύστημα σύνθεσης χαρακτήρα (ταυτότητα + νοοτροπία + στυλ) εφαρμόζεται σε κάθε ομάδα που ορίζει προσωπικότητες πρακτόρων.

Το σύστημα επιπέδων δεξιοτήτων (K0-K4) παρέχει ένα νοητικό μοντέλο για την οργάνωση επαναχρησιμοποιήσιμων ικανοτήτων κατά εμβέλεια.

Το μοτίβο pipeline παραγωγής αρχείων (πηγή YAML + πρότυπα + παραγόμενα τεχνουργήματα) διαχωρίζει τις ανάγκες των εργαλείων από τις ανάγκες χρήσης του περιεχομένου από το μοντέλο.

Το μοντέλο επίπεδης ενορχήστρωσης (ένας συντονιστής, πολλοί ειδικοί) αποφεύγει την πολυπλοκότητα ενώ επιτρέπει παραλληλισμό.

Το αν το Orkestra θα γίνει ανοιχτού κώδικα εξαρτάται από το αν αυτά τα μοτίβα έχουν αξία για άλλους που χτίζουν με το Claude Code. Αν προσκρούετε στους τοίχους που περιγράψαμε, η αρχιτεκτονική μπορεί να βοηθήσει.

Τι Μάθαμε

Το χτίσιμο του Orkestra μας δίδαξε ότι η ενορχήστρωση δεν αφορά το να κάνετε τους πράκτορες πιο έξυπνους. Αφορά το να τους κάνετε πιο εστιασμένους.

Ένας μεμονωμένος πράκτορας με τέλειες οδηγίες εξακολουθεί να εξαντλεί το πλαίσιο. Ένας μεμονωμένος πράκτορας με όλες τις δεξιότητες εξακολουθεί να μπερδεύεται για το ποια να εφαρμόσει. Ένας μεμονωμένος πράκτορας που προσπαθεί να είναι τα πάντα παράγει μέτρια αποτελέσματα παντού.

Σαράντα ειδικοί, καθένας εξαιρετικός στον τομέα του, συντονισμένοι από έναν ενορχηστρωτή που ξέρει πότε να αναθέσει: έτσι παραδίδουμε.

Οι αριθμοί έχουν λιγότερη σημασία από την αρχιτεκτονική. Μπορεί να χρειαστείτε πέντε πράκτορες ή πενήντα. Η αρχή παραμένει: σύνθεση αντί ικανότητας, εξειδίκευση αντί γενίκευσης, συντονισμός αντί ατομικών κατορθωμάτων.

Το Orkestra τροφοδοτεί το οικοσύστημα πρακτόρων πίσω από το Maguyva, την πλατφόρμα ευφυΐας κώδικα μας. Θέλετε να μάθετε περισσότερα; Επικοινωνήστε με την ομάδα.