Što je PocketHook Agent Server?#
Agentski poslužitelj pretvara PocketHook u potpunog AI asistenta. Umjesto da sami pišete logiku odgovora, povezujete LLM (Claude, GPT, Gemini itd.) koji obrađuje poruke, poziva alate i vraća strukturirane PocketHook odgovore — uključujući pokretače Shortcuts.
Poslužitelj radi na vašem vlastitom računalu. Vaši podaci ostaju kod vas.
Ovo je polazna točka. Poslužitelj dolazi s osnovnim skupom alata i dizajniran je da ga proširujete. Dodajte vlastite integracije — e-pošta, kalendari, dokumenti, API-ji — i prilagodite ga sebi.
Značajke#
- Više LLM pružatelja — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (lokalno), LM Studio (lokalno)
- Brzi model — Pokrenite lagani sekundarni model za unutarnje pomoćne zadatke (klasifikacija memorije, ekstrakcija entiteta) uz vaš glavni chat model — potpuna kontrola nad troškom i latencijom
- Safari proširenje — Uparite notarizirano Safari proširenje za macOS kako bi agent mogao otvarati kartice, pregledavati stranice, klikati, ispunjavati obrasce i snimati zaslone u vašoj pravoj sesiji preglednika, na razini dozvola koju odaberete
- OAuth autentifikacija — GitHub Copilot i OpenAI Codex putem device code / browser flow
- Agentski alati — Shell naredbe, čitanje/pisanje datoteka, popis direktorija, web pretraga, web scraping, upravljanje razvojnim poslužiteljima
- Podjela framework / korisnik — Datoteke frameworka (
skills/,custom-tools/,config/) ostaju samo za čitanje. Vaše prilagodbe žive poddata/user/(vještine, prilagođeni alati, upute, tipizirane preferencije). Ažuriranja frameworka dolaze čisto, bez prebrisavanja vašeg rada - Tipizirane korisničke preferencije — Pohranite vrijednosti poput omiljene aplikacije za karte ili tunelske domene u
data/user/prefs.json. Referencirajte ih u vještinama kao{{prefs.key}}i poslužitelj ih zamjenjuje pri učitavanju - Programerski zadaci u jednom pozivu — Meta-alat
run_code_jobstvara pozadinski posao tipa prompt (pokreće ga vaš konfigurirani LLM) i šalje korisniku potvrdu u jednom koraku, zamjenjujući pogreškama sklon obrazac „respond + create-job" - Tipizirani protokolski alati — Šest namjenskih
respond_*alata (respond_text,respond_image,respond_buttons,respond_shortcut,respond_html,respond_sequence), plus tipizirani alati za poslove (create_once_job,create_cron_job) i tipizirani alati za radni prostor (create_project,list_projects,delete_project). Sheme odbijaju neispravno formatirane URL-ove, sintaksu gumba i kombinacijetype/scheduleprije nego što stignu do uređaja - Tipizirani zapisivači za prilagodbu —
create_user_skillicreate_custom_toolgrade markdown korisničkog sloja s ispravnim frontmatterom, tako da ga učitavač uvijek parsira, a agent nikad ne piše te datoteke ručno - Pozadinski zadaci — Jednokratni ili ponavljajući zadaci s cron izrazima ili jednostavnim intervalima
- Dinamičke vještine — Definirajte shortcuts i pravila ponašanja kao
.mddatoteke. U prompt se učitava samo kompaktni indeks; puni sadržaj se dohvaća na zahtjev putem alataload_skill - Samoupravne vještine — Agent može stvarati, uređivati i brisati definicije vještina (zapisi uvijek završavaju u korisničkom sloju)
- Semantička memorija — Vektorsko pretraživanje s embeddingima (Ollama, LM Studio ili OpenAI). Sjećanja se automatski klasificiraju od strane LLM-a u dimenzije wing/room/hall/status
- Graf znanja — Temporalno spremište trojki za trajne činjenice s automatskom invalidacijom. Viševrijednosni odnosi koegzistiraju; jednovrijednosne činjenice se automatski zamjenjuju
- PARA metoda s kaskadom na završetku projekta — Svako sjećanje je označeno statusom (Projekt, Područje, Resurs, Arhiv). Kada projekt završi, jedan poziv
complete_projectarhivira njegove vektore, invalidira svaku planersku trojku vezanu za slug projekta i bilježi završetak — jedan poziv umjesto tri - Hibridno doživljavanje — Kombinira FTS5 pretraživanje po ključnim riječima s vektorskim semantičkim pretraživanjem koristeći reciprocal rank fusion
- Dugotrajna memorija — SQLite + FTS5 punotekstno pretraživanje kao rezervna opcija kada je semantička memorija isključena
- Upravljanje razvojnim poslužiteljima s tunelskim ugovorom — Pokretanje, zaustavljanje i popis razvojnih poslužitelja. Kada se zatraži
tunnel: true, poslužitelj to provjerava prije i nakon pokretanja — nedostupni localhost poslužitelj nikada ne ostaje tiho raditi - Automatsko sanitiziranje URL-ova — Ako agent u odgovoru ostavi
localhostURL, alatirespond_*ga prepisuju u odgovarajući tunelski URL tako da vaš telefon uvijek dobije dostupan link - Prilagođeni alati — Agent može instalirati CLI alate i registrirati ih kao nove sposobnosti
- Verzioniranje — Automatsko git verzioniranje za datoteke workspace-a; sigurnosne kopije konfiguracije za vještine i dozvole
- Web nadzorna ploča — Pregled pozadinskih zadataka uživo, prilagodljiv po korisniku.
/dashboardi/api/jobssu namjerno neautenticirani — ograničite pristup na razini mreže (Tailscale ACL, vatrozid, reverse proxy s basic auth) ili postaviteDASHBOARD=falseako vam ne trebaju - HTTPS tuneliranje — Ugrađena podrška za Tailscale, ngrok i Cloudflare Tunnel
- Sistemska usluga — Instalacija kao trajna usluga na macOS, Linux ili Windows
- Ograničavanje zahtjeva — Limiti po tokenu s konfigurabilnim pragovima
Zahtjevi#
- Bun runtime
- API ključ ili OAuth vjerodajnice za vašeg LLM pružatelja
- (Opcionalno) Tailscale, ngrok ili cloudflared za HTTPS tuneliranje
Brzi početak#
git clone https://github.com/pockethook-app/pockethook-agent-server.git
cd pockethook-agent-server
bun install
# Interaktivno postavljanje — odaberite pruzatelja, model, autentifikacijski token, port
bun run setup
# Pokrenite posluzitelj + HTTPS tunel
bun run dev:tunnel
Čarobnjak za postavljanje vodit će vas kroz odabir LLM pružatelja, konfiguraciju autentifikacije i postavljanje dozvola alata — uključujući odabir hoćete li instalirati Safari proširenje (opcionalno, može se preskočiti, samo za macOS).
Pokrenite bun run help bilo kada za potpuni popis naredbi, ili bun run config da biste na brzinu vidjeli trenutnu konfiguraciju (tajne vrijednosti su maskirane).
Nakon pokretanja, kopirajte prikazane URL-ove u PocketHook Postavke:
| PocketHook Postavka | URL |
|---|---|
| Server URL | https://your-host |
| Health Check URL | https://your-host/health |
| Polling URL | https://your-host/jobs |
Kako radi#
- Pošaljete poruku u PocketHook
- Poslužitelj je prosljeđuje vašem odabranom LLM-u s poviješću razgovora, dozvanim sjećanjima i dostupnim alatima
- LLM obrađuje poruku — može pokretati shell naredbe, čitati/pisati datoteke, pretraživati web, planirati pozadinske zadatke, pamtiti činjenice ili pokretati razvojne poslužitelje
- Odgovor se vraća u PocketHook formatu (
msg+shortcut+data+url) - PocketHook prikazuje poruku i izvršava sve Shortcuts na vašem uređaju
Podržani LLM pružatelji#
| Pružatelj | Autentifikacija | Zadani model |
|---|---|---|
| Anthropic | API ključ | claude-sonnet-4-20250514 |
| OpenAI | API ključ | gpt-4.1-mini |
| OpenAI Codex | OAuth | gpt-5.1-codex-mini |
| GitHub Copilot | OAuth | claude-sonnet-4 |
| Google (Gemini) | API ključ | gemini-2.5-flash |
| Mistral | API ključ | mistral-medium-latest |
| Groq | API ključ | llama-3.3-70b-versatile |
| xAI (Grok) | API ključ | grok-3-mini-fast |
| OpenRouter | API ključ | anthropic/claude-sonnet-4 |
| Ollama (lokalno) | Nema | llama3.2 |
| LM Studio (lokalno) | Nema | qwen3.5-4b-mlx |
Promijenite pružatelja bilo kada pomoću bun run switch. Ollama i LM Studio rade u potpunosti na vašem računalu — nije potreban API ključ, nikakvi podaci ne napuštaju vašu mrežu.
Memorija#
Sustav memorije ima tri sloja, od kojih svaki služi različitoj svrsi.
Dizajn semantičke memorije kombinira ideje iz MemPalace (arhitektura memorijskog dvorca koja organizira sjećanja u krila, hodnike i sobe) i PARA metode Tiaga Fortea (Projekti, Područja, Resursi, Arhiv) za upravljanje životnim ciklusom znanja.
Konverzacijska memorija#
SQLite s FTS5 punotekstnim pretraživanjem. Sve poruke se pohranjuju s vremenskim oznakama i identifikatorima sesija.
- Kratkoročna — Zadnjih
MAX_HISTORYporuka držanih u memoriji po sesiji - Dugoročna — Sve poruke pohranjene u SQLite, pretražive putem FTS5 podudaranja ključnih riječi
- Doživljavanje po potezu — Kada je semantička memorija uključena,
MAX_RECALLkontrolira koliko se relevantnih sjećanja ubacuje u prompt po svakom potezu - Sesije istječu nakon
SESSION_TTL_MINUTES, ali dugoročna memorija traje zauvijek
Ove vrijednosti interaktivno podesite naredbom bun run memory.
Semantička memorija#
Zahtijeva VECTOR_MEMORY=true i pružatelja embeddinga (Ollama, LM Studio ili OpenAI).
Svako sjećanje je umetnuto kao vektor i automatski klasificirano od strane LLM-a u četiri dimenzije:
- Wing — Entitet:
user,person:john,project:blog,place:london - Room — Tip:
facts,preferences,events,decisions,requests - Hall — Tema:
personal,tech,health,travel,food,work - Status — PARA klasifikacija:
project,area,resource,archive
Kada postavite pitanje, ekstrakcija entiteta usmjerava vektorsko pretraživanje na najrelevantnije krilo. Rezultati se spajaju s FTS5 rezultatima ključnih riječi koristeći reciprocal rank fusion — tako dobivate najbolje od oba pristupa.
Graf znanja#
Temporalno spremište trojki za strukturirane, trajne činjenice:
- Trojke:
(subjekt, predikat, objekt)s vremenskim oznakamavalid_from/valid_until - Jednovrijednosni predikati (
lives_in,partner) automatski invalidiraju staru vrijednost pri ažuriranju - Viševrijednosni predikati (
child,friend,hobby) koegzistiraju bez invalidacije - Činjenice iz grafa znanja se ubacuju zajedno s dozvanim sjećanjima u svaki razgovor
Kada agentu kažete „Preselio sam se u Berlin", invalidira staru trojku lives_in i stvara novu — automatski.
PARA životni ciklus#
Svako sjećanje je označeno PARA statusom:
- Projekt — Aktivni, vremenski ograničeni rad
- Područje — Tekuće odgovornosti
- Resurs — Referentni materijal (popisi, preporuke, upute)
- Arhiv — Završeni ili otkazani projekti
Kada se projekt završi, agent koristi semantičku sličnost za arhiviranje samo sjećanja tog projekta uz očuvanje referentnog materijala za buduću upotrebu.
Kaskada na završetku projekta#
Recite „Otkazujem put u Barcelonu" i jedan poziv alata obavlja sve:
- Arhivira vektore projekta (događaje, odluke, zahtjeve vezane uz Barcelonu).
- Invalidira svaku aktivnu trojku grafa znanja čiji predikat odgovara slugu projekta (
scheduled_visit_barcelona,planning_visit_barcelona,confirmed_visit_barcelona). - Bilježi završetak kao novu trojku:
(user, "cancelled_visit_barcelona", "2026-04-15").
Podudaranje poštuje granice — drugi projekt zvan revisit_barcelona ostaje netaknut. Agent više ne mora orkestrirati tri odvojena poziva u pravom redoslijedu, pa i manji modeli to ispravno obave.
Ako je VECTOR_MEMORY isključen ili je pružatelj embeddinga nedostupan, sustav se vraća na FTS5 bez grešaka.
Vještine#
Vještine su .md datoteke u direktoriju skills/ koje definiraju iOS Shortcuts koje agent može pokrenuti i/ili pravila ponašanja. Koriste dinamičko učitavanje: u sistemski prompt se ubacuje samo kompaktni indeks (naslov, opis, popis shortcuts). Agent učitava puni sadržaj na zahtjev putem alata load_skill, održavajući nisku potrošnju tokena kako dodajete više vještina.
Svaka datoteka vještine koristi 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
Polja frontmattera#
| Polje | Obavezno | Opis |
|---|---|---|
title | Da | Čitljivo ime |
description | Da | Jedna rečenica korištena u indeksu vještina koji se prikazuje agentu |
shortcuts | Da | Niz imena shortcuts definiranih u datoteci. Za vještine koje sadrže samo pravila ponašanja koristite [] |
target | Ne | Gdje se shortcuts izvršavaju: device (zadano, šalje se na iOS) ili mac (pokreće se na poslužitelju) |
sync_app | Ne | Aplikacija koja se nakratko otvara u pozadini nakon izvršavanja na poslužitelju kako bi se pokrenula iCloud sinkronizacija (npr. Notes, Calendar, Reminders). Izostavite ili koristite none za preskakanje |
Vještine također mogu biti pravila ponašanja bez shortcuts (npr. „kako planirati obiteljsko putovanje"). Koristite shortcuts: [] za takve.
Agent može stvarati i upravljati vještinama na zahtjev — zamolite ga da „stvori vještinu za upravljanje mojim svjetlima" i napisat će .md datoteku za vas. Nove i uređene vještine uvijek završavaju u vašem korisničkom sloju (data/user/skills/), pa ih ažuriranja frameworka nikada ne prebrisuju. Pogledajte odjeljak Prilagodba vašeg agenta niže.
Izvršavanje shortcuts na Mac poslužitelju#
Kada vještina ima target: mac, shortcuts se tiho pokreću na Mac poslužitelju putem CLI alata shortcuts run, umjesto da se šalju na iOS uređaj. Ovo je idealno za akcije koje stvaraju sadržaj sinkroniziran s iCloud-om — bilješke, podsjetnike, kalendarske događaje — jer se rezultat automatski sinkronizira na sve vaše uređaje bez potrebe da PocketHook aplikacija bilo što radi.
Kako radi:
- Agent odlučuje da se shortcut mora pokrenuti (npr. „stvori bilješku s današnjim zabilješkama sa sastanka")
- Poslužitelj poziva
shortcuts run "imeShortcuta"s podacima proslijeđenim kao JSON na stdin, koristeći isti wrapper format koji koristi PocketHook iOS - Ako je
sync_apppostavljen, poslužitelj nakratko otvara tu aplikaciju u pozadini (open -gj -a Notes) kako bi prisilio iCloud sinkronizaciju, a zatim je zatvara nakon 5 sekundi - Korisnik dobiva potvrdnu poruku u chatu; sam shortcut se ne šalje na uređaj
Zahtjevi:
- Poslužitelj mora raditi na macOS-u —
shortcuts runpostoji samo na macOS-u. Na drugim platformama poslužitelj bilježi upozorenje i vraća se na izvršavanje na uređaju - Shortcut mora biti instaliran u Shortcuts.app na Mac poslužitelju
- Shortcut bi trebao očekivati Dictionary kao ulaz (PocketHook omata podatke u
{ context, timestamp, app, data })
Kada koristiti target: mac:
- iCloud-sinkronizirane akcije (Notes, Reminders, Calendar) — rezultat svejedno dolazi do svakog uređaja
- Dugotrajna obrada koju želite držati izvan iOS uređaja
- Bilo koji shortcut koji ne treba interakciju s iPhone sučeljem
Kada zadržati target: device (zadano):
- Shortcuts koji trebaju značajke dostupne samo na iPhone-u (kamera, precizna lokacija, lokalne automatizacije aplikacija)
- Shortcuts koji od korisnika traže interaktivni unos
- Shortcuts koji koriste App Intents iz aplikacija dostupnih samo na iOS-u
Pozadinski zadaci#
Zamolite agenta da planira zadatke i ostatak će riješiti sam:
- „Provjeri vrijeme svako jutro u 8 i stvori bilješku"
- „Pokreni ovu skriptu svaki sat"
- „Podsjeti me da provjerim e-poštu za 30 minuta"
Zadaci podržavaju cron izraze (0 8 * * *) i jednostavne intervale (30m, 1h, 2d). Rezultati se isporučuju u PocketHook kada upituje krajnju točku /jobs.
Dva tipa izvršavanja:
- Shell — Pokreće bash naredbu, hvata izlaz. Može pokrenuti Shortcut po završetku
- Prompt — Obrađuje AI agent s punim pristupom alatima, pohranjuje kompletan PocketHook odgovor
Razvojni poslužitelji#
Kada agent stvori web projekt u workspace-u (Hugo, Astro, Next.js, Flask, Go itd.), proaktivno nudi njegovo posluživanje:
- Pregled — Pokreće lokalni razvojni poslužitelj na automatski dodijeljenom portu za brzo pregledavanje
- Javni — Pokreće poslužitelj i izlaže ga putem HTTPS tunela tako da je dostupan s bilo kojeg mjesta
Agent upravlja životnim ciklusom: pokretanje, zaustavljanje i popis pokrenutih poslužitelja. Svi poslužitelji se čiste kada se glavni poslužitelj zaustavi.
Tunelski ugovor#
Kada agent pokrene poslužitelj sa zatraženim izlaganjem kroz tunel, runtime to provodi: ako nije instaliran nijedan tunelski alat (Tailscale, ngrok, cloudflared), poslužitelj odbija startati. Ako postavljanje tunela ne uspije nakon pokretanja, proces-sirot se zaustavlja i agent se o tome eksplicitno obavještava — tako da može prijeći u način pregleda ili vas pitati da instalirate tunel. Vraćeni URL je uvijek tunelski URL kada je tuneliranje uključeno, uz napomenu da je lokalni URL dostupan samo na računalu-domaćinu.
Kao sigurnosna mreža, svaki respond_* alat naknadno obrađuje svoju poruku: svaki localhost ili 127.0.0.1 URL koji se provuče u odgovor automatski se prepisuje u odgovarajući tunelski URL kada upravljani poslužitelj ima takav. Kada prepisivanje nije moguće, dobivate upozorenje u logovima umjesto pokvarenog linka na telefonu.
Nadzorna ploča#
Ugrađena web nadzorna ploča na /dashboard prikazuje pregled pozadinskih zadataka uživo.
Namjerno neautenticirano. I
/dashboardi/api/jobssu otvoreniGETendpointi — svatko tko može doći do hosta može ispisati zadatke. Ograničite pristup na razini mreže (Tailscale ACL, vatrozid, reverse proxy s basic auth) ili postaviteDASHBOARD=falseako vam ne trebaju. PocketHook iOS aplikacija ne koristi te endpointe.
Potpuno je prilagodljiva:
- Brza uredba — Stavite datoteku
dashboard.htmluworkspace/dashboard/za jednostavne prilagodbe - Puni projekt — Stvorite framework projekt (Svelte, React, Vue itd.) u
workspace/dashboard/s izlazom gradnje udist/
Zamolite agenta da prilagodi vašu nadzornu ploču i ostatak će riješiti sam — svaki korisnik dobiva jedinstvenu, personaliziranu nadzornu ploču.
Prilagođeni alati#
Agent može instalirati CLI alate i registrirati ih kao nove sposobnosti — proširujući se bez mijenjanja koda poslužitelja.
Na primjer, recite „instaliraj Playwright i koristi ga za snimanje zaslona". Agent će:
- Instalirati ovisnost
- Stvoriti definiciju alata (jednostavna
.mddatoteka) - Koristiti novi alat u budućim razgovorima
Prilagođeni alati se vruće učitavaju — restart nije potreban. Obrišite .md datoteku za uklanjanje alata.
Verzioniranje#
Svi korisnički podaci se automatski verzioniraju:
- Datoteke workspace-a — Praćene lokalnim git repozitorijem unutar
workspace/. Svaki zapis stvara auto-commit. Zamolite agenta da „poništi zadnju promjenu" ili koristitegit revert HEADručno - Konfiguracijske datoteke —
config/agent-instructions.md,config/personality.md,skills/ipermissions.jsonse kopiraju prije svake izmjene. Do 20 verzija po datoteci
Git je opcionalan — ako nije instaliran, promjene workspace-a nisu verzionirane. Sigurnosne kopije konfiguracije uvijek rade.
Prilagodba vašeg agenta#
Agentski poslužitelj dolazi s minimalnom bazom frameworka i očekuje da vlastite prilagodbe dodate iznad nje. Runtime drži to dvoje odvojeno kako ažuriranja frameworka nikad ne bi uništila vaš rad.
Framework nasuprot korisnika#
pockethook-agent-server/
├── skills/ # vjestine isporucene s frameworkom (samo za citanje)
├── custom-tools/ # rezervirano za alate isporucene s frameworkom (samo za citanje)
├── config/
│ ├── agent-instructions.md # upute agenta iz frameworka (samo za citanje)
│ └── personality.md # osobnost iz frameworka (samo za citanje)
└── data/user/ # VASE prilagodbe zive ovdje (ignorirano u gitu)
├── skills/ # vase vlastite vjestine (nadjacavaju bazu po imenu datoteke)
├── custom-tools/ # vasi instalirani prilagodeni alati
├── instructions.md # vasi dodaci uputama agenta
└── prefs.json # tipizirane vrijednosti referencirane kao {{prefs.key}}
Korisničke prilagodbe pišu se preko namjenskih tipiziranih alata (create_user_skill, create_custom_tool) tako da rezultirajuće datoteke uvijek odgovaraju formatu učitavača. Alat write također odbija svaku putanju pod skills/, custom-tools/ ili config/ i preusmjerava agenta u data/user/* — pa čak i izravne izmjene datoteka završavaju u korisničkom sloju.
Napomena o osnovnom direktoriju
custom-tools/. Danas on sadrži samo predložak (_example.md) koji učitavač ignorira — svaki alat koji agent instalira za vas ide udata/user/custom-tools/. Direktorij je rezerviran kako bi buduće verzije frameworka mogle isporučiti opcionalne ugrađene alate bez prebrisavanja vaših instalacija. Kada se to dogodi, vaše datoteke u korisničkom sloju i dalje pobjeđuju pri sudaru imena alata, pa nema što migrirati.
Četiri načina prilagodbe#
| Što želite promijeniti | Kamo ide | Primjer |
|---|---|---|
| Vještina sa shortcutom ili pravilom ponašanja | data/user/skills/<ime>.md | „Stvori vještinu za bilježenje mojih treninga" |
| CLI alat omotan kao agentska sposobnost | data/user/custom-tools/<ime>.md | „Instaliraj ffmpeg i daj mi ga koristiti za konverzije" |
| Globalno pravilo („uvijek odgovaraj na engleskom", „nikad ne koristi tablice") | data/user/instructions.md | „Od sada uvijek sažimaj članke u 3 natuknice" |
| Tipizirana zadana vrijednost na koju se pozivaju vještine | data/user/prefs.json | „Moje zadano polazište rute je Madrid" → {"routeOrigin": "Madrid"} |
Ove datoteke nikada ne morate pisati ručno. Samo recite agentu što želite i on automatski bira pravi sloj.
Tipizirane preferencije s {{prefs.*}}#
Recimo da pišete vještinu planera ruta kojoj treba znati vaše zadano polazište. Umjesto da „Madrid" ukodirate u vještinu, referencirajte preferenciju:
- **Polaziste**: {{prefs.routeOrigin}}, osim ako korisnik navede drugo polaziste.
I pohranite vrijednost u data/user/prefs.json:
{
"routeOrigin": "Madrid, Spain",
"preferredMapsApp": "apple",
"tunnel": { "domain": "my-host.ts.net" }
}
Poslužitelj zamjenjuje rezervirana mjesta pri učitavanju vještine. Ugniježđeni ključevi ({{prefs.tunnel.domain}}) također rade. Nepoznati ključevi ostaju netaknuti kako bi tipografske pogreške ostale vidljive.
Izravno uređivanje baze frameworka#
Ako se sami hostate i želite ugoditi sam framework, možete izravno urediti config/agent-instructions.md, config/personality.md, skills/ ili custom-tools/ — poslužitelj vas ne zaustavlja kada koristite uređivač datoteka. Ali agent neće pisati na te putanje iz razgovora. A ažuriranja frameworka prepisat će vaše izmjene. Za sve što želite zadržati radije koristite korisnički sloj.
Proširenje poslužitelja#
- Prilagođeni alati — Zamolite agenta da instalira CLI alate; završavaju u
data/user/custom-tools/automatski - Dodajte vještine — Zamolite agenta da stvori vještinu; datoteka ide u
data/user/skills/ - Promijenite ponašanje — Zamolite agenta da primijeni globalno pravilo; ono se dodaje u
data/user/instructions.md - Konfigurirajte dozvole — Pokrenite
bun run permissionsza kontrolu koje alate agent može koristiti - Dodajte ugrađene alate — Implementirajte nove funkcije alata u
src/tools.tsza dublje integracije (zahtijeva forkanje poslužitelja)
Konfiguracija#
Sve postavke su pohranjene u .env (stvorenom pomoću bun run setup). Ključne opcije:
| Varijabla | Zadano | Opis |
|---|---|---|
AUTH_TOKEN | (obavezno) | Dijeljeni tajni ključ s PocketHook |
LLM_API_KEY | (obavezno) | API ključ LLM pružatelja |
LLM_PROVIDER | anthropic | Naziv pružatelja |
LLM_MODEL | claude-sonnet-4-20250514 | ID modela |
LLM_REASONING | off | Razina rezoniranja: off, minimal, low, medium, high, xhigh. Više razine dodaju skrivene tokene razmišljanja (sporije + skuplje). Modeli koji to ne podržavaju to ignoriraju |
PORT | 3000 | Port poslužitelja |
AGENT_NAME | PocketHook Assistant | Prikazano ime agenta |
MAX_HISTORY | 50 | Poruke u kratkoročnoj memoriji |
MAX_RECALL | 5 | Sjećanja vraćena po potezu semantičkim doživljavanjem (samo kada VECTOR_MEMORY=true) |
SESSION_TTL_MINUTES | 60 | Istjecanje sesije |
VECTOR_MEMORY | false | Omogući semantičku memoriju (zahtijeva pružatelja embeddinga) |
EMBEDDING_PROVIDER | ollama | Pružatelj embeddinga: ollama, lm-studio ili openai |
EMBEDDING_MODEL | nomic-embed-text | Naziv modela embeddinga |
EMBEDDING_URL | (auto) | URL API-ja embeddinga |
EMBEDDING_API_KEY | — | API ključ za OpenAI embeddinge |
LOG_LEVEL | info | Razina logiranja: debug, info, warn, error |
RATE_LIMIT_MAX | 30 | Maksimalan broj zahtjeva po prozoru |
DASHBOARD | true | Omogući web nadzornu ploču (ruta /dashboard) |
INSTANCE_NAME | (osnovno ime direktorija projekta, s uklonjenim prefiksom pockethook-) | Sufiks korišten za oznaku sistemske usluge, direktorij logova i podudaranje procesa. Postavite eksplicitno kada na istom računalu radi više kopija |
LLM_QUICK_PROVIDER / LLM_QUICK_MODEL | isto kao glavni | Pružatelj/model za brzi model (unutarnji pomoćni zadaci) |
SAFARI_PERMISSION_LEVEL | confirm | Politika klikanja Safari proširenja: confirm, autonomous ili readonly |
SAFARI_CAPTURES_BASE_URL | samo lokalno | Javni osnovni URL za posluživanje Safari snimki stranica aplikaciji |
Potpunu referencu konfiguracije pogledajte u GitHub repozitoriju.
Pokretanje kao usluga#
Instalirajte kao trajnu uslugu koja se automatski pokreće:
bun run service install
| Platforma | Backend | Lokacija usluge |
|---|---|---|
| macOS | launchd | ~/Library/LaunchAgents/com.pockethook.${INSTANCE_NAME}.plist |
| Linux | systemd (user) | ~/.config/systemd/user/pockethook-${INSTANCE_NAME}.service |
| Windows | NSSM | PocketHook-${PascalCase(INSTANCE_NAME)} u Upravitelju usluga sustava Windows |
INSTANCE_NAME se po zadanom postavlja na osnovno ime direktorija projekta s uklonjenim prefiksom pockethook- (npr. kopija u pockethook-agent-server/ postaje agent-server). Postavite ga eksplicitno za pokretanje više kopija na istom računalu bez sudara — svaka instanca čuva vlastite data/ i logove.
Upravljajte pomoću bun run service status, restart, stop ili uninstall.
Sigurnost#
- Obavezan HTTPS — PocketHook zahtijeva HTTPS za sve URL-ove
- Bearer token autentifikacija — Dijeljeni tajni ključ između aplikacije i poslužitelja
- Ograničavanje zahtjeva — Limiti po tokenu sprječavaju zloporabu
- Izolirani alati — Shell naredbe i pristup datotekama ograničeni dozvolama
- Blokirani obrasci — Opasne naredbe (
sudo,rm -rf /) blokirane prema zadanom - Granica radnog direktorija — Agent ne može napustiti svoj određeni direktorij
- Zaštićene osjetljive datoteke —
.env,.git,*.key,*.pemblokirane od pristupa agenta - Automatsko verzioniranje — Sve promjene workspace-a prate se gitom za lako vraćanje