Ενσωματωμένα εργαλεία πράκτορα

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

Κάθε εργαλείο εδώ καταχωρίζεται μόνο όταν ο πόρος που το στηρίζει είναι συνδεδεμένος για την εκτέλεση — ένας επόπτης διακομιστή γλώσσας ή αποσφαλμάτωσης, ένας αναλυτής tree-sitter, ένα εργοστάσιο πυρήνων, μια θύρα ερωτήσεων, ένας κατάλογος vibe. Η ανίχνευση διακομιστή γλώσσας ή προσαρμογέα αποσφαλμάτωσης για αυτό το checkout είναι ξεχωριστός, μεταγενέστερος έλεγχος (status / adapters): αυτά τα εργαλεία παραμένουν στην επιφάνεια, ώστε ο πράκτορας να μπορεί να ρωτήσει γιατί τίποτα δεν είναι αξιοποιήσιμο, αντί να μαντεύει.

Βαθμίδες έγκρισης

Κάθε εργαλείο δηλώνει μια βαθμίδα, και η βαθμίδα αποφασίζει ποιες επιφάνειες το βλέπουν — όχι απλώς αν ζητά έγκριση. Η λειτουργία σχεδίου και οι υποπράκτορες μόνο για ανάγνωση περιορίζονται στο read, οπότε ένα εργαλείο βαθμίδας write ή exec απουσιάζει εντελώς από το σχήμα τους.

Βαθμίδα	Σημασία	Εργαλεία εδώ
read	Χωρίς παρενέργειες	lsp, ast_grep, ask_user, τα πέντε vibe_*
write	Αλλάζει αρχεία	lsp_rename, ast_edit, resolve
exec	Ξεκινά ή ελέγχει μια διεργασία	debug, eval

---

lsp — ερωτήματα διακομιστή γλώσσας

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

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

Ενέργεια	Ορίσματα	Επιστρέφει
diagnostics	file (ή "*")	Σφάλματα και προειδοποιήσεις· το "*" εκτελεί αντ’ αυτού τον ελεγκτή έργου
definition	file, line, symbol	Πού δηλώνεται το σύμβολο
type_definition	file, line, symbol	Πού δηλώνεται ο τύπος του
implementation	file, line, symbol	Συγκεκριμένες υλοποιήσεις
references	file, line, symbol	Κάθε χρήση, με όριο 50
hover	file, line, symbol	Υπογραφή και σχόλιο τεκμηρίωσης
symbols	query ή file	Αναζήτηση στον χώρο εργασίας με query (όριο 100)· σύμβολα εγγράφου με file (όριο 200)
code_actions	file, line, symbol	Γρήγορες διορθώσεις που προσφέρει ο διακομιστής
status	—	Ποιοι διακομιστές εκτελούνται, και για ποιες ρίζες
reload	—	Επανεκκινεί τον διακομιστή για αυτή τη ρίζα

Διαγνωστικά κατά την εγγραφή

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

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

lsp_rename — μετονομασία σε όλο το έργο

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

Όρισμα	Σημασία
file	Πού βρίσκεται το σύμβολο
line	Γραμμή με δείκτη από το 1
symbol	Υποσυμβολοσειρά που το αναγνωρίζει σε αυτή τη γραμμή
new_name	Πώς θα ονομαστεί

---

ast_grep — δομική αναζήτηση

Βρίσκει κώδικα με βάση το σχήμα και όχι το κείμενο. Το $NAME αντιστοιχίζει οποιονδήποτε κόμβο, το $$$NAME αντιστοιχίζει μια σειρά από αδέλφια, και το $_ είναι ένας μπαλαντέρ που δεν δεσμεύει τίποτα.

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

ast_grep(pattern: "if ($X != null) $X.dispose()", language: "dart")

αντιστοιχίζει έναν φρουρό που κάνει dispose σε αυτό που έλεγξε, και δεν αντιστοιχίζει έναν που κάνει dispose σε κάτι άλλο.

Όρισμα	Σημασία
pattern	Ένα απόσπασμα κώδικα με μεταβλητές μοτίβου
path	Αρχείο ή φάκελος προς αναζήτηση· από προεπιλογή ολόκληρος ο χώρος εργασίας
language	Ένα αναγνωριστικό γραμματικής που διανέμεται (dart, python, rust, c, …). Συμπεραίνεται όταν το path ονομάζει αρχείο
max_results	Προεπιλογή 50

Το μοτίβο αναλύεται από την ίδια γραμματική με το αρχείο

Έτσι, το dispose(x) αντιστοιχίζει την κλήση όπως κι αν είναι αραιωμένη με κενά, τυλιγμένη ή σχολιασμένη — και δεν αντιστοιχίζει ποτέ τους ίδιους χαρακτήρες μέσα σε ένα string literal ή ένα σχόλιο.

Ένα απόσπασμα αναλύεται μέσα σε ένα ικρίωμα, όχι σκέτο

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

ast_edit — δομική αναδιατύπωση, σε στάδιο

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

ast_edit(pattern: "dispose($X)", rewrite: "$X.dispose()", language: "dart")
→ (proposed) 12 replacements in 4 files … call resolve with edit_id "edit_1"

Όρισμα	Σημασία
pattern	Τι να αντιστοιχιστεί
rewrite	Τι να μπει εκεί, με αντικατάσταση του $NAME
path	Εμβέλεια· από προεπιλογή ολόκληρος ο χώρος εργασίας
language	Αναγνωριστικό γλώσσας

resolve — υποβολή ή απόρριψη μιας αλλαγής σε στάδιο

Όρισμα	Σημασία
edit_id	Από το αποτέλεσμα (proposed)
action	accept ή discard

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

---

debug — οδήγηση αποσφαλματωτή

Καταχωρίζεται όταν η εκτέλεση έχει έναν επόπτη συνεδρίας αποσφαλμάτωσης, έναν κατάλογο εργασίας και ένα αναγνωριστικό συνομιλίας. Το αν ένας προσαρμογέας μπορεί όντως να ξεκινήσει ανιχνεύεται τη στιγμή της κλήσης, με τον ίδιο κανόνα τομής όπως για τον διακομιστή γλώσσας (δείκτης ρίζας και εκτελέσιμο). Βαθμίδα exec· όχι ασφαλές για παραλληλισμό (μια συνεδρία είναι κατάσταση που διαρκεί μεταξύ κλήσεων, οπότε ένα continue που προσπερνά το stack θα διάβαζε ένα frame που έχει ήδη μετακινηθεί).

Μία συνεδρία ανά συνομιλία, με αυστηρό TTL (30 λεπτά). Ένα δεύτερο launch απορρίπτεται, αντί να αντικαθιστά σιωπηλά το πρώτο.

Λειτουργία	Ορίσματα	Σημειώσεις
adapters	—	Ποιοι προσαρμογείς είναι αξιοποιήσιμοι εδώ, και γιατί όχι
status	—	Αν εκτελείται μια συνεδρία, και πού σταμάτησε
breakpoints	file, lines[]	Κενό lines καθαρίζει το αρχείο. Μπορούν να οριστούν πριν την εκκίνηση
launch	program, args[]	Ξεκινά το πρόγραμμα σταματημένο στα σημεία διακοπής σας
attach	port	Συνδέεται σε ένα αποσφαλματωμένο πρόγραμμα που εκτελείται ήδη
continue	thread_id?	Εκτελείται μέχρι την επόμενη διακοπή
pause	thread_id?	Το σταματά εκεί που βρίσκεται
step_over / step_in / step_out	thread_id?	Μετακινεί ένα βήμα
threads	—	Αναγνωριστικά και ονόματα νημάτων
stack	thread_id?	Frames, με όριο 30
scopes	frame_id	Πεδία εμβέλειας σε ένα frame, καθένα με ένα reference
variables	reference	Παιδιά, με όριο 50, τιμές με όριο 400 χαρακτήρες
evaluate	expression, frame_id?	Αξιολογείται στην εμβέλεια του ίδιου του frame
output	—	Το stdout/stderr του αποσφαλματωμένου προγράμματος, με όριο
terminate	—	Τερματίζει τη συνεδρία και σκοτώνει τον προσαρμογέα

Προσαρμογείς

Id	Εντολή	Δείκτες ρίζας
dart	dart debug_adapter	pubspec.yaml
debugpy	python3 -m debugpy.adapter	pyproject.toml, setup.py, requirements.txt
lldb	lldb-dap	Cargo.toml, CMakeLists.txt
delve	dlv dap	go.mod

Το debugpy προτιμά ένα .venv/bin ή venv/bin τοπικό στο έργο από το $PATH: μια python του $PATH είναι διαφορετικό περιβάλλον, και η σύνδεση από το λάθος περιβάλλον αποτυγχάνει με τρόπο που διαβάζεται σαν σπασμένος κώδικας.

---

eval — μόνιμοι διερμηνείς

Ένα κελί Python ή JavaScript του οποίου οι μεταβλητές, τα imports και τα δεδομένα που φορτώθηκαν επιβιώνουν μεταξύ κλήσεων. Βαθμίδα exec· όχι ασφαλές για παραλληλισμό.

Όρισμα	Σημασία
code	Το κελί
description	Απαιτείται. 5–10 λέξεις για την ετικέτα της απομαγνητοφώνησης
language	python (προεπιλογή) ή javascript
reset	Απορρίπτει τον διερμηνέα και ξεκινά από καθαρή κατάσταση πρώτα

• Η τελευταία έκφραση επιστρέφεται όπως σε ένα notebook.
• Το display() λειτουργεί, ένα frame της pandas αποδίδεται ως πίνακας, και ένα σχήμα της matplotlib επιστρέφει ως εικόνα που εμφανίζει η απομαγνητοφώνηση.
• Τα ιδιώματα της IPython που πληκτρολογεί κανείς αντανακλαστικά — %pip, %cd, !cmd, %%bash, %%timeit — ξαναγράφονται σε απλό κώδικα. Το %pip καθαρίζει επίσης το sys.modules, ώστε το επόμενο import να βλέπει αυτό που μόλις εγκαταστάθηκε.

Κλήση των δικών σας εργαλείων μέσα από ένα κελί

contents = tool("read", {"path": "lib/auth.dart"})

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

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

Πού εκτελείται ο πυρήνας

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

---

ask_user — ερώτηση προς τον άνθρωπο

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

Όρισμα	Σημασία
question	Τι να ρωτηθεί
context	Προαιρετικό: γιατί ρωτάτε και τι κρέμεται από την απάντηση
options[]	Επιλογές, καθεμία {label, description?}
allow_free_text	Αν γίνεται δεκτή πληκτρολογημένη απάντηση
multi_select	Αν μπορούν να επιλεγούν πολλές επιλογές

Μια παράλειψη είναι επιτυχία: προχωρήστε με βάση μια δηλωμένη παραδοχή και μην ξαναρωτήσετε. Η λήξη του χρονικού ορίου είναι σφάλμα με την ίδια οδηγία. Οι προτροπές άδειας («επιτρέπεται να το κάνω αυτό;») είναι ξεχωριστή πύλη και αποδίδονται ως η ίδια κάρτα στη συνομιλία.

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

---

vibe_* — κατεύθυνση εργατών παρασκηνίου

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

Εργαλείο	Ορίσματα	Σημειώσεις
vibe_spawn	brief, label, tier?	Επιστρέφει αμέσως· ο εργάτης συνεχίζει να εκτελείται
vibe_send	worker_id, message	Προσθέτει στην ανάθεση και επανεκτελεί
vibe_wait	worker_id, timeout_seconds?	Αποκλείει μέχρι να κατασταλάξει
vibe_kill	worker_id	Τον σταματά
vibe_list	—	Βαθμίδα, κατάσταση, χρόνος που πέρασε και τελευταίο αποτέλεσμα

Το tier είναι fast (μηχανική εργασία με σαφή προδιαγραφή) ή good (σχεδιασμός, κρίση ή έλεγχος της εξόδου ενός εργάτη fast).