Agent Server

Τι είναι ο PocketHook Agent Server;

#

Ο agent server μετατρέπει το PocketHook σε πλήρη AI βοηθό. Αντί να γράφετε τη λογική απαντήσεων μόνοι σας, συνδέετε ένα LLM (Claude, GPT, Gemini κ.λπ.) που επεξεργάζεται μηνύματα, καλεί εργαλεία και επιστρέφει δομημένες απαντήσεις PocketHook — συμπεριλαμβανομένων triggers Shortcuts.

Ο server τρέχει στο δικό σας μηχάνημα. Τα δεδομένα σας μένουν σε εσάς.

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

Χαρακτηριστικά

#

• Πολλαπλοί πάροχοι LLM — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (τοπικά), LM Studio (τοπικά)
• Αυθεντικοποίηση OAuth — GitHub Copilot και OpenAI Codex μέσω device code / ροής browser
• Εργαλεία agent — Εντολές κελύφους, ανάγνωση/εγγραφή αρχείων, λίστα καταλόγων, αναζήτηση ιστού, web scraping, διαχείριση dev servers
• Διαχωρισμός framework / χρήστη — Τα αρχεία του framework (skills/, custom-tools/, config/) παραμένουν μόνο για ανάγνωση. Οι προσαρμογές σας ζουν κάτω από το data/user/ (δεξιότητες, προσαρμοσμένα εργαλεία, οδηγίες, τυποποιημένες προτιμήσεις). Οι ενημερώσεις framework κατεβαίνουν καθαρά χωρίς να σβήνουν τη δουλειά σας
• Τυποποιημένες προτιμήσεις χρήστη — Αποθηκεύστε τιμές όπως την προτιμώμενη εφαρμογή χαρτών ή το domain του tunnel στο data/user/prefs.json. Αναφερθείτε σε αυτές στις δεξιότητες ως {{prefs.key}} και ο server τις αντικαθιστά κατά τη φόρτωση
• Εργασίες προγραμματισμού σε μία κλήση — Το μετα-εργαλείο run_code_job δημιουργεί μια εργασία παρασκηνίου τύπου prompt (που εκτελείται από το LLM που έχετε ρυθμίσει) και στέλνει στον χρήστη την επιβεβαίωση σε ένα βήμα, αντικαθιστώντας το επιρρεπές σε σφάλματα μοτίβο “respond + create-job”
• Τυποποιημένα εργαλεία πρωτοκόλλου — Έξι αποκλειστικά εργαλεία respond_* (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), συν τυποποιημένα εργαλεία εργασιών (create_once_job, create_cron_job) και τυποποιημένα εργαλεία χώρου εργασίας (create_project, list_projects, delete_project). Τα schemas απορρίπτουν λανθασμένα URL, σύνταξη κουμπιών και συνδυασμούς type/schedule πριν φτάσουν στη συσκευή
• Τυποποιημένοι writers για προσαρμογή — Τα create_user_skill και create_custom_tool δημιουργούν το markdown της user-layer με σωστό frontmatter, ώστε ο loader να τα αναλύει πάντα και ο agent να μη γράφει ποτέ αυτά τα αρχεία στο χέρι
• Εργασίες παρασκηνίου — Μεμονωμένες ή επαναλαμβανόμενες εργασίες με εκφράσεις cron ή απλά διαστήματα
• Δυναμικές δεξιότητες — Ορίστε συντομεύσεις και κανόνες συμπεριφοράς ως αρχεία .md. Μόνο ένα συμπαγές ευρετήριο φορτώνεται στο prompt· το πλήρες περιεχόμενο ανακτάται κατ’ απαίτηση μέσω του εργαλείου load_skill
• Αυτοδιαχειριζόμενες δεξιότητες — Ο agent μπορεί να δημιουργεί, να επεξεργάζεται και να διαγράφει ορισμούς δεξιοτήτων (οι εγγραφές καταλήγουν πάντα στο επίπεδο χρήστη)
• Σημασιολογική μνήμη — Αναζήτηση βάσει διανυσμάτων με embeddings (Ollama, LM Studio ή OpenAI). Οι μνήμες ταξινομούνται αυτόματα από το LLM σε διαστάσεις wing/room/hall/status
• Γράφος γνώσεων — Χρονικό αποθετήριο τριπλετών για ανθεκτικά γεγονότα με αυτόματη ακύρωση. Πολλαπλές τιμές συνυπάρχουν· μονές τιμές αντικαθίστανται αυτόματα
• Μέθοδος PARA με αλυσίδα λήξης έργου — Κάθε μνήμη σημαίνεται με κατάσταση (Έργο, Τομέας, Πόρος, Αρχείο). Όταν ένα έργο τελειώνει, μια μοναδική κλήση complete_project αρχειοθετεί τα διανύσματά του, ακυρώνει κάθε τριπλέτα σχεδιασμού που συνδέεται με το slug του και καταγράφει την ολοκλήρωση — μία κλήση αντί για τρεις
• Υβριδική ανάκληση — Συνδυάζει αναζήτηση λέξεων-κλειδιών FTS5 με σημασιολογική αναζήτηση διανυσμάτων χρησιμοποιώντας reciprocal rank fusion
• Μακροπρόθεσμη μνήμη — SQLite + FTS5 πλήρης αναζήτηση κειμένου ως εναλλακτική όταν η σημασιολογική μνήμη είναι απενεργοποιημένη
• Διαχείριση dev servers με συμβόλαιο tunnel — Εκκίνηση, διακοπή και λίστα dev servers. Όταν ζητείται tunnel: true, ο server το επιβάλλει πριν την εκκίνηση και μετά τη δημιουργία διεργασίας — ένας μη προσβάσιμος localhost server δεν αφήνεται ποτέ να τρέχει σιωπηλά
• Αυτόματη εξυγίανση URL — Αν ο agent αφήσει ένα URL localhost σε απάντηση, τα εργαλεία respond_* το επανεγγράφουν στο αντίστοιχο URL tunnel ώστε το τηλέφωνό σας να λαμβάνει πάντα έναν προσβάσιμο σύνδεσμο
• Προσαρμοσμένα εργαλεία — Ο agent μπορεί να εγκαταστήσει CLI εργαλεία και να τα καταχωρήσει ως νέες δυνατότητες
• Εκδοσιοποίηση — Αυτόματη εκδοσιοποίηση git για αρχεία χώρου εργασίας· αντίγραφα ασφαλείας ρυθμίσεων για δεξιότητες και δικαιώματα
• Πάνελ ιστού — Ζωντανή επισκόπηση εργασιών παρασκηνίου, προσαρμόσιμη ανά χρήστη. Τα /dashboard και /api/jobs δεν έχουν εξ ορισμού αυθεντικοποίηση — περιορίστε την πρόσβαση στο επίπεδο δικτύου (Tailscale ACL, firewall, reverse proxy με basic auth) ή ορίστε DASHBOARD=false αν δεν το χρειάζεστε
• HTTPS tunneling — Ενσωματωμένη υποστήριξη για Tailscale, ngrok και Cloudflare Tunnel
• Υπηρεσία συστήματος — Εγκατάσταση ως μόνιμη υπηρεσία σε macOS, Linux ή Windows
• Περιορισμός αιτημάτων — Όρια αιτημάτων ανά token με ρυθμιζόμενα κατώφλια

Απαιτήσεις

#

• Περιβάλλον εκτέλεσης Bun
• Κλειδί API ή OAuth διαπιστευτήρια για τον πάροχο LLM σας
• (Προαιρετικά) Tailscale, ngrok ή cloudflared για HTTPS tunneling

Γρήγορη εκκίνηση

#

git clone https://github.com/pockethook-app/pockethook-agent-server.git
cd pockethook-agent-server
bun install

# Διαδραστική ρύθμιση — επιλογή παρόχου, μοντέλου, token αυθεντικοποίησης, θύρας
bun run setup

# Εκκίνηση server + HTTPS tunnel
bun run dev:tunnel

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

Μόλις τρέχει, αντιγράψτε τα εμφανιζόμενα URL στις ρυθμίσεις PocketHook:

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

#

1. Στέλνετε ένα μήνυμα στο PocketHook
2. Ο server το προωθεί στο επιλεγμένο LLM σας με ιστορικό συνομιλίας, ανακτημένες μνήμες και διαθέσιμα εργαλεία
3. Το LLM επεξεργάζεται το μήνυμα — μπορεί να τρέξει εντολές κελύφους, να διαβάσει/γράψει αρχεία, να ψάξει στο web, να προγραμματίσει εργασίες παρασκηνίου, να θυμηθεί γεγονότα ή να εκκινήσει dev servers
4. Η απάντηση επιστρέφεται σε μορφή PocketHook (msg + shortcut + data + url)
5. Το PocketHook εμφανίζει το μήνυμα και εκτελεί τυχόν Shortcuts στη συσκευή σας

Υποστηριζόμενοι πάροχοι LLM

#

Αλλάξτε πάροχο οποιαδήποτε στιγμή με bun run switch. Τα Ollama και LM Studio τρέχουν εξ ολοκλήρου στο μηχάνημά σας — χωρίς κλειδί API, χωρίς δεδομένα να φεύγουν από το δίκτυό σας.

Μνήμη

#

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

Ο σχεδιασμός σημασιολογικής μνήμης συνδυάζει ιδέες από το MemPalace (αρχιτεκτονική παλατιού μνήμης που οργανώνει μνήμες σε wings, halls και rooms) και τη μέθοδο PARA του Tiago Forte (Έργα, Τομείς, Πόροι, Αρχείο) για διαχείριση κύκλου ζωής γνώσεων.

Μνήμη συνομιλίας

#

SQLite με πλήρη αναζήτηση κειμένου FTS5. Όλα τα μηνύματα αποθηκεύονται με χρονοσημάνσεις και αναγνωριστικά συνεδρίας.

• Βραχυπρόθεσμη — Τα τελευταία MAX_HISTORY μηνύματα διατηρούνται στη μνήμη ανά συνεδρία
• Μακροπρόθεσμη — Όλα τα μηνύματα αποθηκεύονται στο SQLite, αναζητήσιμα μέσω FTS5
• Ανάκληση ανά γύρο — Όταν η σημασιολογική μνήμη είναι ενεργή, το MAX_RECALL ελέγχει πόσες σχετικές μνήμες εισάγονται στο prompt σε κάθε γύρο
• Οι συνεδρίες λήγουν μετά από SESSION_TTL_MINUTES, αλλά η μακροπρόθεσμη μνήμη παραμένει για πάντα

Ρυθμίστε τα διαδραστικά με bun run memory.

Σημασιολογική μνήμη

#

Απαιτεί VECTOR_MEMORY=true και πάροχο embeddings (Ollama, LM Studio ή OpenAI).

Κάθε μνήμη μετατρέπεται σε διάνυσμα και ταξινομείται αυτόματα από το LLM σε τέσσερις διαστάσεις:

• Wing — Η οντότητα: user, person:john, project:blog, place:london
• Room — Ο τύπος: facts, preferences, events, decisions, requests
• Hall — Το θέμα: personal, tech, health, travel, food, work
• Status — Ταξινόμηση PARA: project, area, resource, archive

Όταν κάνετε μια ερώτηση, η εξαγωγή οντοτήτων εστιάζει τη διανυσματική αναζήτηση στα πιο σχετικά wings. Τα αποτελέσματα συγχωνεύονται με τα αποτελέσματα FTS5 χρησιμοποιώντας reciprocal rank fusion — ώστε να παίρνετε το καλύτερο και από τους δύο τύπους αναζήτησης.

Γράφος γνώσεων

#

Χρονικό αποθετήριο τριπλετών για δομημένα, ανθεκτικά γεγονότα:

• Τριπλέτες: (subject, predicate, object) με valid_from / valid_until χρονοσημάνσεις
• Μονότιμα κατηγορήματα (lives_in, partner) ακυρώνουν αυτόματα την παλιά τιμή κατά την ενημέρωση
• Πολύτιμα κατηγορήματα (child, friend, hobby) συνυπάρχουν χωρίς ακύρωση
• Τα γεγονότα του γράφου γνώσεων εισάγονται μαζί με τις ανακτημένες μνήμες σε κάθε συνομιλία

Όταν λέτε στον agent «Μετακόμισα στο Βερολίνο», ακυρώνει το παλιό τριπλέτο lives_in και δημιουργεί ένα νέο — αυτόματα.

Κύκλος ζωής PARA

#

Κάθε μνήμη σημαίνεται με κατάσταση PARA:

• Έργο — Ενεργή, χρονικά περιορισμένη εργασία
• Τομέας — Συνεχείς ευθύνες
• Πόρος — Υλικό αναφοράς (λίστες, συστάσεις, οδηγίες)
• Αρχείο — Ολοκληρωμένα ή ακυρωμένα έργα

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

Αλυσίδα λήξης έργου

#

Πείτε «Ακυρώνω το ταξίδι μου στη Βαρκελώνη» και μία μόνο κλήση εργαλείου τα χειρίζεται όλα:

1. Αρχειοθετεί τα διανύσματα του έργου (συμβάντα, αποφάσεις, αιτήματα συνδεδεμένα με τη Βαρκελώνη).
2. Ακυρώνει κάθε ενεργή τριπλέτα του γράφου γνώσεων της οποίας το κατηγόρημα ταιριάζει με το slug του έργου (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Καταγράφει την ολοκλήρωση ως νέα τριπλέτα: (user, "cancelled_visit_barcelona", "2026-04-15").

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

Αν το VECTOR_MEMORY είναι απενεργοποιημένο ή ο πάροχος embeddings δεν είναι προσβάσιμος, το σύστημα επιστρέφει σε FTS5 χωρίς σφάλματα.

Δεξιότητες

#

Οι δεξιότητες είναι αρχεία .md στο skills/ που ορίζουν iOS Shortcuts που ο agent μπορεί να ενεργοποιήσει ή/και κανόνες συμπεριφοράς. Χρησιμοποιούν δυναμική φόρτωση: μόνο ένα συμπαγές ευρετήριο (τίτλος, περιγραφή, λίστα Shortcuts) εισάγεται στο system prompt. Ο agent φορτώνει πλήρες περιεχόμενο κατ’ απαίτηση μέσω του εργαλείου load_skill, διατηρώντας χαμηλή κατανάλωση tokens καθώς προσθέτετε περισσότερες δεξιότητες.

Κάθε αρχείο δεξιότητας χρησιμοποιεί YAML frontmatter:

---
title: Notes
description: Create notes on the user's device with a title and body
shortcuts: [newNote]
target: mac
sync_app: Notes
---

### New Note

Shortcut name: `newNote`

Creates a new note on the user's device.

Data fields:
- title (string, required): Note title
- content (string, required): Note body

Πεδία frontmatter

#

Οι δεξιότητες μπορούν επίσης να είναι κανόνες συμπεριφοράς χωρίς Shortcuts (π.χ., «πώς να σχεδιάσετε ένα οικογενειακό ταξίδι»). Χρησιμοποιήστε shortcuts: [] για αυτές.

Ο agent μπορεί να δημιουργεί και να διαχειρίζεται δεξιότητες όταν τον ρωτήσετε — ζητήστε του «δημιούργησε μια δεξιότητα για τον έλεγχο των φώτων μου» και θα γράψει το αρχείο .md για εσάς. Οι νέες και οι επεξεργασμένες δεξιότητες καταλήγουν πάντα στο επίπεδο χρήστη σας (data/user/skills/), ώστε οι ενημερώσεις framework να μην τις σβήνουν ποτέ. Δείτε την ενότητα Customizing your agent παρακάτω.

Εκτέλεση Shortcuts στον Mac server

#

Όταν μια δεξιότητα έχει target: mac, τα Shortcuts εκτελούνται σιωπηλά στον Mac server μέσω του CLI shortcuts run αντί να αποστέλλονται στη συσκευή iOS. Αυτό είναι ιδανικό για ενέργειες που δημιουργούν περιεχόμενο συγχρονισμένο με iCloud — σημειώσεις, υπενθυμίσεις, συμβάντα ημερολογίου — επειδή το αποτέλεσμα συγχρονίζεται αυτόματα σε όλες τις συσκευές σας χωρίς να χρειάζεται να κάνει κάτι η εφαρμογή PocketHook.

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

1. Ο agent αποφασίζει ότι ένα Shortcut πρέπει να εκτελεστεί (π.χ. «δημιούργησε μια σημείωση με τις σημερινές σημειώσεις συνάντησης»)
2. Ο server καλεί shortcuts run "shortcutName" με τα δεδομένα να μεταβιβάζονται ως JSON στο stdin, χρησιμοποιώντας την ίδια μορφή wrapper που χρησιμοποιεί το PocketHook iOS
3. Αν το sync_app έχει οριστεί, ο server ανοίγει στιγμιαία αυτή την εφαρμογή στο παρασκήνιο (open -gj -a Notes) για να επιβάλει συγχρονισμό iCloud, και στη συνέχεια την κλείνει μετά από 5 δευτερόλεπτα
4. Ο χρήστης λαμβάνει ένα μήνυμα επιβεβαίωσης στη συνομιλία· το ίδιο το Shortcut δεν αποστέλλεται στη συσκευή

Απαιτήσεις:

• Ο server πρέπει να τρέχει σε macOS — το shortcuts run είναι αποκλειστικά για macOS. Σε άλλες πλατφόρμες, ο server καταγράφει μια προειδοποίηση και επιστρέφει σε εκτέλεση στη συσκευή
• Το Shortcut πρέπει να είναι εγκατεστημένο στην εφαρμογή Shortcuts.app στον Mac του server
• Το Shortcut θα πρέπει να αναμένει ένα Dictionary ως είσοδο (το PocketHook τυλίγει τα δεδομένα σε { context, timestamp, app, data })

Πότε να χρησιμοποιήσετε target: mac:

• Ενέργειες συγχρονισμένες με iCloud (Notes, Reminders, Calendar) — το αποτέλεσμα φτάνει έτσι κι αλλιώς σε κάθε συσκευή
• Μακροχρόνια επεξεργασία που θέλετε να κρατήσετε μακριά από τη συσκευή iOS
• Οποιοδήποτε Shortcut δεν χρειάζεται να αλληλεπιδράσει με το UI του iPhone

Πότε να κρατήσετε target: device (προεπιλογή):

• Shortcuts που χρειάζονται λειτουργίες αποκλειστικά του iPhone (κάμερα, ακριβής τοποθεσία, τοπικές αυτοματοποιήσεις εφαρμογών)
• Shortcuts που ζητούν διαδραστική είσοδο από τον χρήστη
• Shortcuts που χρησιμοποιούν App Intents από εφαρμογές αποκλειστικές για iOS

Εργασίες παρασκηνίου

#

Ζητήστε από τον agent να προγραμματίσει εργασίες και θα τα χειριστεί:

• «Έλεγξε τον καιρό κάθε πρωί στις 8 και δημιούργησε μια σημείωση»
• «Τρέξε αυτό το script κάθε ώρα»
• «Θύμισέ μου να ελέγξω τα email μου σε 30 λεπτά»

Οι εργασίες υποστηρίζουν εκφράσεις cron (0 8 * * *) και απλά διαστήματα (30m, 1h, 2d). Τα αποτελέσματα παραδίδονται στο PocketHook όταν γίνεται polling στο endpoint /jobs.

Δύο τύποι εκτέλεσης:

• Shell — Εκτελεί μια εντολή bash, καταγράφει την έξοδο. Μπορεί να ενεργοποιήσει ένα Shortcut κατά την ολοκλήρωση
• Prompt — Επεξεργάζεται από τον AI agent με πλήρη πρόσβαση σε εργαλεία, αποθηκεύει την πλήρη απάντηση PocketHook

Dev Servers

#

Όταν ο agent δημιουργεί ένα web project στον χώρο εργασίας (Hugo, Astro, Next.js, Flask, Go κ.λπ.), προσφέρεται προληπτικά να το εξυπηρετήσει:

• Προεπισκόπηση — Εκκινεί τοπικό dev server σε αυτόματα εκχωρημένη θύρα για γρήγορη προβολή
• Δημόσιο — Εκκινεί τον server και τον εκθέτει μέσω HTTPS tunnel ώστε να είναι προσβάσιμος από παντού

Ο agent διαχειρίζεται τον κύκλο ζωής: εκκίνηση, διακοπή και λίστα τρεχόντων servers. Όλοι οι servers καθαρίζονται όταν σταματήσει ο κύριος server.

Συμβόλαιο tunnel

#

Όταν ο agent εκκινεί έναν server με αιτούμενη έκθεση μέσω tunnel, ο runtime το επιβάλλει: αν δεν είναι εγκατεστημένο κανένα εργαλείο tunnel (Tailscale, ngrok, cloudflared), ο server αρνείται να ξεκινήσει. Αν η ρύθμιση του tunnel αποτύχει μετά τη δημιουργία της διεργασίας, η ορφανή διεργασία σταματά και ο agent ενημερώνεται ρητά — ώστε να μπορεί να γυρίσει σε λειτουργία προεπισκόπησης ή να σας ζητήσει να εγκαταστήσετε tunnel. Το επιστρεφόμενο URL είναι πάντα το URL του tunnel όταν το tunneling είναι ενεργό, με σημείωση ότι το τοπικό URL είναι μόνο για τον host.

Ως δίχτυ ασφαλείας, κάθε εργαλείο respond_* επεξεργάζεται το μήνυμά του εκ των υστέρων: οποιοδήποτε URL localhost ή 127.0.0.1 που τρυπώνει σε μια απάντηση επανεγγράφεται αυτόματα στο αντίστοιχο URL tunnel όταν ένας διαχειριζόμενος server έχει ένα. Όταν δεν μπορεί να επανεγγράψει, λαμβάνετε μια προειδοποίηση στα logs αντί για σπασμένο σύνδεσμο στο τηλέφωνό σας.

Dashboard

#

Το ενσωματωμένο web dashboard στο /dashboard δείχνει ζωντανή επισκόπηση εργασιών παρασκηνίου.

Χωρίς αυθεντικοποίηση εξ ορισμού. Τόσο το /dashboard όσο και το /api/jobs είναι ανοιχτά endpoints GET — οποιοσδήποτε μπορεί να φτάσει στον host μπορεί να εμφανίσει τη λίστα εργασιών. Περιορίστε την πρόσβαση στο επίπεδο δικτύου (Tailscale ACL, firewall, reverse proxy με basic auth) ή ορίστε DASHBOARD=false αν δεν το χρειάζεστε. Η εφαρμογή PocketHook iOS δεν χρησιμοποιεί αυτά τα endpoints.

Είναι πλήρως προσαρμόσιμο:

• Γρήγορη επεξεργασία — Τοποθετήστε ένα dashboard.html στο workspace/dashboard/ για απλές προσαρμογές
• Πλήρες project — Δημιουργήστε ένα framework project (Svelte, React, Vue κ.λπ.) στο workspace/dashboard/ με έξοδο build στο dist/

Ζητήστε από τον agent να προσαρμόσει το dashboard σας και θα τα χειριστεί — κάθε χρήστης παίρνει ένα μοναδικό, εξατομικευμένο dashboard.

Προσαρμοσμένα εργαλεία

#

Ο agent μπορεί να εγκαταστήσει CLI εργαλεία και να τα καταχωρήσει ως νέες δυνατότητες — επεκτείνοντας τον εαυτό του χωρίς τροποποίηση του κώδικα server.

Για παράδειγμα, πείτε «εγκατάστησε Playwright και χρησιμοποίησέ το για λήψη screenshots». Ο agent θα:

1. Εγκαταστήσει την εξάρτηση
2. Δημιουργήσει ορισμό εργαλείου (ένα απλό αρχείο .md)
3. Χρησιμοποιήσει το νέο εργαλείο σε μελλοντικές συνομιλίες

Τα προσαρμοσμένα εργαλεία επαναφορτώνονται αμέσως — δεν χρειάζεται επανεκκίνηση. Διαγράψτε το αρχείο .md για να αφαιρέσετε ένα εργαλείο.

Εκδοσιοποίηση

#

Όλα τα δεδομένα χρήστη εκδοσιοποιούνται αυτόματα:

• Αρχεία χώρου εργασίας — Παρακολουθούνται με τοπικό git repo μέσα στο workspace/. Κάθε εγγραφή δημιουργεί auto-commit. Ζητήστε από τον agent «αναίρεσε την τελευταία αλλαγή» ή χρησιμοποιήστε git revert HEAD χειροκίνητα
• Αρχεία ρυθμίσεων — config/agent-instructions.md, config/personality.md, skills/ και permissions.json δημιουργούν αντίγραφο ασφαλείας πριν από κάθε τροποποίηση. Μέχρι 20 εκδόσεις ανά αρχείο

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

Προσαρμογή του agent σας

#

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

Framework έναντι χρήστη

#

pockethook-agent-server/
├── skills/                      # δεξιότητες που παραδίδονται με το framework (μόνο ανάγνωση)
├── custom-tools/                # δεσμευμένο για εργαλεία που παραδίδονται με το framework (μόνο ανάγνωση)
├── config/
│   ├── agent-instructions.md    # οδηγίες agent του framework (μόνο ανάγνωση)
│   └── personality.md           # προσωπικότητα framework (μόνο ανάγνωση)
└── data/user/                   # Η δική ΣΑΣ προσαρμογή ζει εδώ (αγνοείται από το git)
    ├── skills/                  # οι δικές σας δεξιότητες (παρακάμπτουν τη βάση με βάση το όνομα αρχείου)
    ├── custom-tools/            # τα προσαρμοσμένα εργαλεία που έχετε εγκαταστήσει
    ├── instructions.md          # οι προσθήκες σας στις οδηγίες agent
    └── prefs.json               # τυποποιημένες τιμές που αναφέρονται ως {{prefs.key}}

Η προσαρμογή χρήστη γράφεται μέσω αποκλειστικών τυποποιημένων εργαλείων (create_user_skill, create_custom_tool) ώστε τα αρχεία που προκύπτουν να ταιριάζουν πάντα με τη μορφή του loader. Το εργαλείο write απορρίπτει επίσης οποιαδήποτε διαδρομή κάτω από skills/, custom-tools/ ή config/ και ανακατευθύνει τον agent στο data/user/* — ώστε ακόμη και οι άμεσες επεξεργασίες αρχείων να καταλήγουν στο επίπεδο χρήστη.

Σημείωση σχετικά με τον βασικό κατάλογο custom-tools/. Σήμερα περιέχει μόνο ένα template (_example.md) που ο loader αγνοεί — κάθε εργαλείο που εγκαθιστά για εσάς ο agent πηγαίνει στο data/user/custom-tools/. Ο κατάλογος είναι δεσμευμένος ώστε μελλοντικές εκδόσεις framework να μπορούν να παραδώσουν προαιρετικά ενσωματωμένα εργαλεία χωρίς να καταστρέφουν τις εγκαταστάσεις σας. Όταν συμβεί αυτό, τα αρχεία του επιπέδου χρήστη εξακολουθούν να υπερισχύουν σε περίπτωση σύγκρουσης ονόματος εργαλείου, επομένως δεν υπάρχει τίποτα να μεταφερθεί.

Τέσσερις τρόποι προσαρμογής

#

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

Τυποποιημένες προτιμήσεις με {{prefs.*}}

#

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

- **Αφετηρία**: {{prefs.routeOrigin}}, εκτός αν ο χρήστης καθορίσει διαφορετική αφετηρία.

Και αποθηκεύστε την τιμή στο data/user/prefs.json:

{
  "routeOrigin": "Madrid, Spain",
  "preferredMapsApp": "apple",
  "tunnel": { "domain": "my-host.ts.net" }
}

Ο server αντικαθιστά τους placeholders όταν η δεξιότητα φορτώνεται. Τα ένθετα κλειδιά ({{prefs.tunnel.domain}}) λειτουργούν επίσης. Τα άγνωστα κλειδιά μένουν ανέγγιχτα ώστε τα τυπογραφικά λάθη να παραμένουν ορατά.

Απευθείας επεξεργασία της βάσης framework

#

Αν φιλοξενείτε μόνοι σας και θέλετε να τροποποιήσετε το ίδιο το framework, μπορείτε να επεξεργαστείτε απευθείας τα config/agent-instructions.md, config/personality.md, skills/ ή custom-tools/ — ο server δεν σας σταματά όταν χρησιμοποιείτε έναν επεξεργαστή αρχείων. Αλλά ο agent δεν θα γράψει σε αυτά τα paths μέσα από συνομιλία. Και οι ενημερώσεις framework θα γράψουν πάνω από τις επεξεργασίες σας. Προτιμήστε το επίπεδο χρήστη για ο,τιδήποτε θέλετε να κρατήσετε.

Επέκταση του server

#

• Προσαρμοσμένα εργαλεία — Ζητήστε από τον agent να εγκαταστήσει CLI εργαλεία· καταλήγουν αυτόματα στο data/user/custom-tools/
• Προσθήκη δεξιοτήτων — Ζητήστε από τον agent να δημιουργήσει μια δεξιότητα· το αρχείο πηγαίνει στο data/user/skills/
• Αλλαγή συμπεριφοράς — Ζητήστε από τον agent να εφαρμόσει έναν καθολικό κανόνα· τον προσθέτει στο data/user/instructions.md
• Ρύθμιση δικαιωμάτων — Τρέξτε bun run permissions για έλεγχο ποια εργαλεία μπορεί να χρησιμοποιεί ο agent
• Προσθήκη ενσωματωμένων εργαλείων — Υλοποιήστε νέες συναρτήσεις εργαλείων στο src/tools.ts για βαθύτερες ενσωματώσεις (απαιτεί fork του server)

Ρύθμιση

#

Όλες οι ρυθμίσεις αποθηκεύονται στο .env (δημιουργείται από bun run setup). Βασικές επιλογές:

Δείτε την πλήρη αναφορά ρυθμίσεων στο αποθετήριο GitHub.

Εκτέλεση ως υπηρεσία

#

Εγκαταστήστε ως μόνιμη υπηρεσία που ξεκινά αυτόματα:

bun run service install

Το INSTANCE_NAME ορίζεται εξ ορισμού ως το όνομα φακέλου project με αφαίρεση του προθέματος pockethook- (π.χ., ένα checkout στο pockethook-agent-server/ γίνεται agent-server). Ορίστε το ρητά για να εκτελείτε πολλαπλά checkouts στο ίδιο μηχάνημα χωρίς συγκρούσεις — κάθε instance διατηρεί τα δικά του data/ και logs.

Διαχειριστείτε με bun run service status, restart, stop ή uninstall.

Ασφάλεια

#

• Απαιτείται HTTPS — Το PocketHook επιβάλλει HTTPS για όλα τα URL
• Αυθεντικοποίηση Bearer token — Κοινό μυστικό μεταξύ εφαρμογής και server
• Περιορισμός αιτημάτων — Όρια ανά token αποτρέπουν κατάχρηση
• Απομονωμένα εργαλεία — Εντολές κελύφους και πρόσβαση αρχείων περιορίζονται από δικαιώματα
• Αποκλεισμένα μοτίβα — Επικίνδυνες εντολές (sudo, rm -rf /) αποκλείονται από προεπιλογή
• Όριο καταλόγου εργασίας — Ο agent δεν μπορεί να δραπετεύσει από τον καθορισμένο κατάλογό του
• Προστασία ευαίσθητων αρχείων — .env, .git, *.key, *.pem αποκλείονται από πρόσβαση agent
• Αυτόματη εκδοσιοποίηση — Όλες οι αλλαγές χώρου εργασίας παρακολουθούνται μέσω git για εύκολη επαναφορά