menu
languageΕλληνικά
save_alt Λήψη

Gatekeeper

SQL με ανθρώπινη έγκριση για AI agents: ένας agent προτείνει ένα query, εσύ το εγκρίνεις στο Beekeeper Studio πριν εκτελεστεί, μόνο ανάγνωση από προεπιλογή.

από Gldywn Community plugin

Readme

Αυτό το κείμενο γράφτηκε από τρίτους και μεταφράστηκε αυτόματα. Διάβασε το πρωτότυπο στα αγγλικά

Gatekeeper

Gatekeeper

Οι agents σου προτείνουν το SQL. Εσύ εγκρίνεις τι εκτελείται.

CI Έκδοση Άδεια

Λειτουργεί με Claude Code Λειτουργεί με Codex CLI Λειτουργεί με OpenCode

Το Gatekeeper είναι μια γέφυρα με ανθρώπινη έγκριση ανάμεσα σε AI agents και τη βάση δεδομένων σου. Ένας agent προτείνει ένα query μέσω MCP· από προεπιλογή, τίποτα δεν εκτελείται μέχρι να το εγκρίνεις στο Beekeeper Studio, πάνω στο κείμενο SQL, πριν την εκτέλεση. Το query εκτελείται στη σύνδεση που ήδη έχει το Beekeeper και οι γραμμές επιστρέφουν στον agent.

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

Μουσική από #Uppbeat Shine by Swoop: https://uppbeat.io/t/swoop/shine

Συμβουλή

Auto mode beta: ενεργοποίησε ρητά την αυτόματη έγκριση για ένα περιορισμένο υποσύνολο αναγνώσεων PostgreSQL. Πρέπει να περάσουν και οι τοπικοί έλεγχοι και ο Jev. Δες το Auto mode για ρύθμιση, κοινή χρήση provider και περιορισμούς.

Τα τρία κομμάτια

Κομμάτι Τι κάνει Πού εκτελείται
Plugin του Beekeeper Studio Εμφανίζει κάθε προτεινόμενο query, κατατάσσει τον κίνδυνό του και το εκτελεί στη σύνδεσή σου μόλις το εγκρίνεις Μέσα στο Beekeeper Studio
MCP server Η πλευρά προς τον agent: τα εργαλεία που καλεί ένας agent για να προτείνει ένα query και να πάρει το αποτέλεσμα Στον υπολογιστή σου, ξεκινά από τον agent σου
Agent skill Μαθαίνει σε οποιονδήποτε agent να χειρίζεται σωστά αυτά τα εργαλεία Στον φάκελο skills του agent σου

Κυκλοφορούν μαζί με μία κοινή έκδοση και είναι χρήσιμα μαζί: το plugin χωρίς τον server δεν έχει τίποτα να εγκρίνει, ο server χωρίς το plugin δεν έχει κανέναν να ρωτήσει.

Γιατί

  • Χειροκίνητη έγκριση από προεπιλογή. Το Auto mode είναι προαιρετικό και προσωρινό. Καταγράφονται η πηγή της έγκρισης και, όπου υπάρχει, ο αξιολογητής.
  • Κανένα διαπιστευτήριο βάσης δεδομένων δεν φεύγει από το Beekeeper. Τα queries εκτελούνται μέσω της ήδη πιστοποιημένης σύνδεσής του. Σύνδεσε το Beekeeper σε read replica ή σε ρόλο μόνο ανάγνωσης για ένα σίγουρο δίχτυ ασφαλείας.
  • Ο κίνδυνος κατατάσσεται, δεν υποτίθεται. Ένας parser που γνωρίζει τη διάλεκτο κατατάσσει κάθε query σε ανάγνωση, εγγραφή ή καταστροφική ενέργεια, και το κουμπί Έγκριση μένει μπλοκαρισμένο μέχρι να ενεργοποιηθεί η αντίστοιχη λειτουργία.

Πώς λειτουργεί

  MCP client                     Gatekeeper server (127.0.0.1)          Beekeeper Studio
 ┌────────────────────┐   MCP    ┌───────────────────────────┐  fetch   ┌────────────────────┐
 │ submit_query(sql)  │ ───────► │ MCP server + HTTP broker  │ ◄─────── │ Plugin (iframe)    │
 │ get_query_result() │ ◄─────── │ SQLite lease queue + audit│  poll    │ 1. show SQL        │
 │ cancel_query()     │          │ /pending /executing       │ ───────► │ 2. human approves  │
 │                    │          │ /result  /lease/renew     │  result  │ 3. runQuery()      │
 └────────────────────┘          └───────────────────────────┘          │ 4. post result     │
                                                                        └────────────────────┘
  1. Ο agent υποβάλλει μια πρόταση και παίρνει αμέσως πίσω ένα request id. Τίποτα δεν μπλοκάρει.
  2. Το plugin κάνει polling στον τοπικό broker, δεσμεύει την πρόταση με lease και εμφανίζει το SQL.
  3. Εγκρίνεις ή απορρίπτεις. Με την έγκριση, το Beekeeper εκτελεί το query στη σύνδεσή σου.
  4. Το plugin στέλνει πίσω το αποτέλεσμα και ο agent το παραλαμβάνει όταν είναι έτοιμο.

Το plugin τρέχει σε sandboxed iframe, οπότε δεν μπορεί ποτέ να δεχτεί εισερχόμενη σύνδεση: αντί γι' αυτό κάνει polling στον broker. Αυτός ο ένας περιορισμός εξηγεί όλη τη δομή. Όλες οι λεπτομέρειες στο Architecture.

Ξεκινώντας

Προαπαιτούμενα: Beekeeper Studio >= 5.4 και Node >= 22. Αν χρησιμοποιείς Claude Code ή Codex CLI, έχεις ήδη Node. Δεν υπάρχει υπηρεσία παρασκηνίου για εγκατάσταση: ο agent σου ξεκινά τον server όταν ανοίγει η συνεδρία του και αυτός τερματίζεται όταν η συνεδρία κλείσει.

Προειδοποίηση

Μόνο macOS, προς το παρόν. Το Gatekeeper αναπτύσσεται και δοκιμάζεται σε macOS. Windows και Linux δεν έχουν δοκιμαστεί ακόμα, οπότε θεώρησέ τα μη υποστηριζόμενα μέχρι να αναφέρει κάποιος. Τίποτα στον κώδικα δεν είναι ειδικό για macOS (ο server βρίσκει τις διαδρομές από τον αρχικό σου φάκελο, το plugin είναι ένα τυπικό webview του Beekeeper), οπότε αναμένεται να λειτουργούν και τα δύο, αλλά αναμενόμενο δεν σημαίνει επιβεβαιωμένο. Αναφορές από οποιαδήποτε από τις δύο πλατφόρμες είναι πολύ ευπρόσδεκτες.

Γρήγορη εγκατάσταση

Ένα ειδικό skill τα ρυθμίζει όλα για σένα: το plugin, τον MCP server, το συνοδευτικό skill και τη σύζευξη. Πρόσθεσε τα skills στον agent σου:

npx skills add Gldywn/gatekeeper

Μετά ζήτα από τον agent σου να εγκαταστήσει το Gatekeeper ή τρέξε απευθείας το skill:

/install-gatekeeper

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

Χειροκίνητη εγκατάσταση

Προτιμάς να το κάνεις με το χέρι ή θέλεις να δεις ακριβώς τι συμβαίνει;

Σημαντικό

Δεν βρίσκεται ακόμα στο μητρώο plugins του Beekeeper. Μια υποβολή είναι σε εξέλιξη με τους maintainers του Beekeeper. Μέχρι να γίνει merge, το Manage Plugins δεν θα εμφανίζει το Gatekeeper και η εγκατάσταση με ένα κλικ δεν είναι διαθέσιμη, οπότε το βήμα 1 παρακάτω είναι η χειροκίνητη οδός. Τίποτα άλλο δεν αλλάζει.

1. Εγκατάστησε το plugin στο Beekeeper Studio. Κατέβασε το gatekeeper-<version>.zip από την τελευταία έκδοση, αποσυμπίεσέ το στον φάκελο plugins του Beekeeper και κάνε επανεκκίνηση του Beekeeper:

OS Φάκελος plugins
macOS ~/Library/Application Support/beekeeper-studio/plugins/
Linux ~/.config/beekeeper-studio/plugins/
Windows %APPDATA%\beekeeper-studio\plugins\

Ο φάκελος που αποσυμπιέζεις πρέπει να λέγεται ακριβώς gatekeeper. Το zip ανοίγει ως gatekeeper-<version>/, οπότε μετονόμασέ τον μετά την αποσυμπίεση. Το Beekeeper συγκρίνει το όνομα του φακέλου με το id του plugin και παραλείπει κάθε φάκελο που δεν ταιριάζει χωρίς να πει λέξη: κανένα σφάλμα, καμία καταχώριση στο Manage Plugins, τίποτα για κλικ. Αυτός είναι ο πιο συνηθισμένος λόγος που μια χειροκίνητη εγκατάσταση φαίνεται να μην κάνει τίποτα.

2. Καταχώρισε τον MCP server στον agent σου. Αυτή είναι και η εγκατάσταση του server: το npx τον κατεβάζει και τον αποθηκεύει στην cache στην πρώτη εκκίνηση.

# Claude Code
claude mcp add gatekeeper --scope user -- npx -y @gldywn/gatekeeper-mcp-server

# Codex CLI, in ~/.codex/config.toml
[mcp_servers.gatekeeper]
command = "npx"
args = ["-y", "@gldywn/gatekeeper-mcp-server"]

Προτιμάς pnpm; Το pnpm dlx @gldywn/gatekeeper-mcp-server είναι το άμεσο ισοδύναμο της γραμμής npx. Για να γίνεται resolve του πακέτου μία φορά αντί σε κάθε εκκίνηση του agent, εγκατάστησέ το με pnpm add -g @gldywn/gatekeeper-mcp-server και στρέψε τον client σου στο binary gatekeeper-mcp-server που προσθέτει στο PATH σου.

Κάθε client που διαβάζει .mcp.json μπορεί να χρησιμοποιήσει το .mcp.json.example ως έχει. Κλείδωσε την έκδοση (@gldywn/gatekeeper-mcp-server@<version>) αν προτιμάς να ελέγχεις τις αναβαθμίσεις αντί να τις δέχεσαι: χωρίς κλείδωμα, το npx βρίσκει ξανά την τελευταία έκδοση σε κάθε εκκίνηση του agent, κάτι που σε κρατά ενημερωμένο αλλά σημαίνει ότι μια διεργασία με πρόσβαση στη βάση δεδομένων σου αλλάζει χωρίς να το καταλάβεις.

3. Εγκατάστησε το agent skill.

npx skills add Gldywn/gatekeeper

Το CLI είναι διαδραστικό: ρωτά για ποιους agents να γίνει η εγκατάσταση και αν θα είναι global. Λειτουργεί με Claude Code, Codex, Cursor και τους υπόλοιπους.

4. Κάνε σύζευξη του plugin, μία φορά ανά υπολογιστή. Ξεκίνα τον agent σου και ζήτα του οτιδήποτε χρειάζεται τη βάση δεδομένων. Μέχρι να γίνει η σύζευξη, κάθε εργαλείο του Gatekeeper απαντά με έναν 6ψήφιο κωδικό: πληκτρολόγησέ τον στο plugin (Tools -> Gatekeeper). Ο κωδικός είναι μίας χρήσης και διαρκεί περίπου πέντε λεπτά, και το http://127.0.0.1:9999/pair δείχνει πάντα τον τρέχοντα. Το capability token που μεταφέρεται φυλάσσεται στον κρυπτογραφημένο χώρο αποθήκευσης του Beekeeper.

Τίποτα δεν απαντά σε αυτή τη θύρα μέχρι ο agent σου να έχει ξεκινήσει τον server τουλάχιστον μία φορά. Αν ανοίξεις το plugin πριν από αυτό, θα σου το πει, αντί να δείξει ένα πεδίο σύζευξης που δεν μπορεί να εξυπηρετήσει.

5. Χρησιμοποίησέ το. Ζήτα από τον agent σου κάτι που χρειάζεται τη βάση δεδομένων. Προτείνει SQL, το query εμφανίζεται στο plugin, το εγκρίνεις και οι γραμμές επιστρέφουν στον agent. Οι αναγνώσεις λειτουργούν αμέσως· μια εγγραφή εκτελείται μόνο αφού ενεργοποιήσεις τη λειτουργία Write ή Destructive.

Το build από τον πηγαίο κώδικα περιγράφεται στο Development.

Αν το plugin δεν εμφανίζεται ποτέ

Το Beekeeper έρχεται με κλειδωμένο το σύστημα plugins, οπότε μια νέα εγκατάσταση μπορεί να αγνοήσει εντελώς ένα plugin τρίτου. Τρία πράγματα να ελέγξεις, με τη σειρά:

1. Το όνομα του φακέλου. Ακριβώς gatekeeper, όχι gatekeeper-0.1.1. Μια ασυμφωνία παραλείπεται σιωπηλά, όπως παραπάνω.

2. Το σύστημα plugins είναι ενεργό. Οι προεπιλογές του Beekeeper ορίζουν pluginSystem.disabled = true, με allowlist που περιέχει μόνο τα δύο δικά του plugins. Πρόσθεσε αυτό στο user config σου και κάνε επανεκκίνηση:

[pluginSystem]
disabled = false

3. Τα community plugins είναι ενεργά. Το communityDisabled = true είναι επίσης προεπιλογή και απενεργοποιεί κάθε plugin που το Beekeeper χαρακτηρίζει community. Αν ο διαχειριστής plugins δείχνει “Community plugins are disabled via configuration”, πρόσθεσε communityDisabled = false στο ίδιο block.

OS Αρχείο user config
macOS ~/Library/Application Support/beekeeper-studio/user.config.ini
Linux ~/.config/beekeeper-studio/user.config.ini
Windows %APPDATA%\beekeeper-studio\user.config.ini

Λειτουργίες πρόσβασης

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

Λειτουργία Εγκρίνει Ενεργοποιείται από
Read (προεπιλογή) SELECT και παρόμοια Δεν χρειάζεται τίποτα
Write INSERT, UPDATE Εσένα, στο plugin, με δεύτερη επιβεβαίωση
Destructive DELETE, DROP, TRUNCATE, ALTER Εσένα, στο plugin, με δεύτερη επιβεβαίωση

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

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

Κάτω από το SQL, μια σημείωση αναφέρει τους πίνακες που διαβάζει το query και τις ευαίσθητες στήλες τους: προσωπικά δεδομένα με ένα χρώμα, εταιρικά και εμπορικά δεδομένα με άλλο, μια ευαίσθητη τιμή επισημαίνεται ακόμα κι όταν εμφανίζεται μόνο σε φίλτρο WHERE, και ένα SELECT * αναπτύσσεται στις πραγματικές στήλες ώστε τίποτα να μην κρύβεται πίσω από το αστεράκι. Μια κουκκίδα στο εικονίδιο βάσης δεδομένων της κεφαλίδας δείχνει αν πέρασε ο τελευταίος έλεγχος σύνδεσης, και το εικονίδιο ανοίγει τις λεπτομέρειες: αυτόν τον έλεγχο και μετά τα τρία επίπεδα μόνο ανάγνωσης (η ενεργή λειτουργία, η σύνδεση του Beekeeper και το endpoint της βάσης δεδομένων). Το ρομπότ δίπλα του δείχνει τη σύνδεση με τον server του Gatekeeper στον οποίο οι agents σου στέλνουν τα queries τους. Είναι πράσινο όσο ο server απαντά, πορτοκαλί κατά τη σύνδεση και διαγραμμένο με κόκκινο όταν δεν είναι προσβάσιμος, και αν περάσεις το ποντίκι από πάνω δείχνει πότε απάντησε τελευταία φορά ο server.

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

Ασφάλεια

  • Η πύλη βρίσκεται εκεί που γίνεται η εκτέλεση. Το plugin είναι το μόνο στοιχείο που μπορεί να εκτελέσει ένα query, γι' αυτό εκεί βρίσκονται ο ταξινομητής και ο έλεγχος λειτουργίας.
  • Capability token σε κάθε αίτημα. Χωρίς αυτό, ο broker απαντά 401. Δημιουργείται στην πρώτη εκτέλεση, αποθηκεύεται με 0600 στο ~/.gatekeeper και το plugin το κρατά στον κρυπτογραφημένο χώρο αποθήκευσης του Beekeeper.
  • Σύζευξη με κωδικό. Ο broker δεν μπορεί να ξεχωρίσει το plugin από οποιαδήποτε ιστοσελίδα επισκέπτεσαι, οπότε το token περνά από ένα κανάλι που μια σελίδα δεν μπορεί να παρακολουθήσει: έναν 6ψήφιο κωδικό μίας χρήσης που διαβάζεις με τα μάτια σου, έγκυρο για πέντε λεπτά, που ακυρώνεται μετά από πέντε λάθος προσπάθειες.
  • Μόνο loopback. Ο broker δεσμεύεται στο 127.0.0.1 και απορρίπτει απρόσμενα headers Host, οπότε μια σελίδα DNS-rebinding παίρνει 421.
  • Περιορισμένα αποτελέσματα, ελάχιστο audit. Οι γραμμές που προωθούνται περιορίζονται σε πλήθος και bytes, ώστε μια μαζική ανάγνωση να μην πλημμυρίζει ποτέ το context του agent. Το audit προς τον agent κρατά την απόφαση και ένα digest του SQL, ποτέ το ακατέργαστο SQL και ποτέ γραμμές.

Η ανάγνωση δεν εγγυάται μηδενικές παρενέργειες: ένα SELECT μπορεί να καλέσει volatile function, και ακριβώς γι' αυτό η έγκριση γίνεται πάνω στο ορατό SQL. Το SECURITY.md περιέχει το μοντέλο απειλών, το όριο εμπιστοσύνης του ίδιου χρήστη, τα χρονικά περιθώρια διατήρησης και την πολιτική supply chain.

Τεκμηρίωση

Έγγραφο Τι περιέχει
Architecture Τα δύο κανάλια, ο κύκλος έγκρισης, η ουρά lease, τα όρια αποτελεσμάτων
MCP tools Κάθε εργαλείο που μπορεί να καλέσει ένας agent, η μορφή του ticket, το συμβόλαιο αναμονής
Configuration Μεταβλητές περιβάλλοντος και ειδοποιήσεις επιφάνειας εργασίας
Ασφάλεια Μοντέλο απειλών, όριο εμπιστοσύνης, διατήρηση, supply chain
Development Build από πηγαίο κώδικα, ρύθμιση dev, δομή repo, tech stack
Releasing Πώς ένα commit γίνεται έκδοση plugin και πακέτο npm

Development

pnpm install
pnpm build     # both packages
pnpm ci        # typecheck + build + test

Το pnpm dev:link στρέφει το Beekeeper στο checkout σου και το pnpm dev ξεκινά το UI του plugin με hot reload. Η πλήρης ρύθμιση, μαζί με τις δοκιμαστικές βάσεις δεδομένων, βρίσκεται στο Development.

Άδεια

MIT