Otiđi na glavni sadržaj
  1. Dokumentacija/

Agentski poslužitelj

Š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 pod data/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_job stvara 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 kombinacije type/schedule prije nego što stignu do uređaja
  • Tipizirani zapisivači za prilagodbucreate_user_skill i create_custom_tool grade 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 .md datoteke. U prompt se učitava samo kompaktni indeks; puni sadržaj se dohvaća na zahtjev putem alata load_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_project arhivira 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 localhost URL, alati respond_* 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. /dashboard i /api/jobs su namjerno neautenticirani — ograničite pristup na razini mreže (Tailscale ACL, vatrozid, reverse proxy s basic auth) ili postavite DASHBOARD=false ako 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
#

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 PostavkaURL
Server URLhttps://your-host
Health Check URLhttps://your-host/health
Polling URLhttps://your-host/jobs

Kako radi
#

  1. Pošaljete poruku u PocketHook
  2. Poslužitelj je prosljeđuje vašem odabranom LLM-u s poviješću razgovora, dozvanim sjećanjima i dostupnim alatima
  3. 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
  4. Odgovor se vraća u PocketHook formatu (msg + shortcut + data + url)
  5. PocketHook prikazuje poruku i izvršava sve Shortcuts na vašem uređaju

Podržani LLM pružatelji
#

PružateljAutentifikacijaZadani model
AnthropicAPI ključclaude-sonnet-4-20250514
OpenAIAPI ključgpt-4.1-mini
OpenAI CodexOAuthgpt-5.1-codex-mini
GitHub CopilotOAuthclaude-sonnet-4
Google (Gemini)API ključgemini-2.5-flash
MistralAPI ključmistral-medium-latest
GroqAPI ključllama-3.3-70b-versatile
xAI (Grok)API ključgrok-3-mini-fast
OpenRouterAPI ključanthropic/claude-sonnet-4
Ollama (lokalno)Nemallama3.2
LM Studio (lokalno)Nemaqwen3.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_HISTORY poruka 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_RECALL kontrolira 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 oznakama valid_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:

  1. Arhivira vektore projekta (događaje, odluke, zahtjeve vezane uz Barcelonu).
  2. Invalidira svaku aktivnu trojku grafa znanja čiji predikat odgovara slugu projekta (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
  3. 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
#

PoljeObaveznoOpis
titleDaČitljivo ime
descriptionDaJedna rečenica korištena u indeksu vještina koji se prikazuje agentu
shortcutsDaNiz imena shortcuts definiranih u datoteci. Za vještine koje sadrže samo pravila ponašanja koristite []
targetNeGdje se shortcuts izvršavaju: device (zadano, šalje se na iOS) ili mac (pokreće se na poslužitelju)
sync_appNeAplikacija 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:

  1. Agent odlučuje da se shortcut mora pokrenuti (npr. „stvori bilješku s današnjim zabilješkama sa sastanka")
  2. Poslužitelj poziva shortcuts run "imeShortcuta" s podacima proslijeđenim kao JSON na stdin, koristeći isti wrapper format koji koristi PocketHook iOS
  3. Ako je sync_app postavljen, poslužitelj nakratko otvara tu aplikaciju u pozadini (open -gj -a Notes) kako bi prisilio iCloud sinkronizaciju, a zatim je zatvara nakon 5 sekundi
  4. Korisnik dobiva potvrdnu poruku u chatu; sam shortcut se ne šalje na uređaj

Zahtjevi:

  • Poslužitelj mora raditi na macOS-ushortcuts run postoji 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 /dashboard i /api/jobs su otvoreni GET endpointi — 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 postavite DASHBOARD=false ako vam ne trebaju. PocketHook iOS aplikacija ne koristi te endpointe.

Potpuno je prilagodljiva:

  • Brza uredba — Stavite datoteku dashboard.html u workspace/dashboard/ za jednostavne prilagodbe
  • Puni projekt — Stvorite framework projekt (Svelte, React, Vue itd.) u workspace/dashboard/ s izlazom gradnje u dist/

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:

  1. Instalirati ovisnost
  2. Stvoriti definiciju alata (jednostavna .md datoteka)
  3. 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 koristite git revert HEAD ručno
  • Konfiguracijske datotekeconfig/agent-instructions.md, config/personality.md, skills/ i permissions.json se 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 u data/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 promijenitiKamo idePrimjer
Vještina sa shortcutom ili pravilom ponašanjadata/user/skills/<ime>.md„Stvori vještinu za bilježenje mojih treninga"
CLI alat omotan kao agentska sposobnostdata/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štinedata/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 permissions za kontrolu koje alate agent može koristiti
  • Dodajte ugrađene alate — Implementirajte nove funkcije alata u src/tools.ts za dublje integracije (zahtijeva forkanje poslužitelja)

Konfiguracija
#

Sve postavke su pohranjene u .env (stvorenom pomoću bun run setup). Ključne opcije:

VarijablaZadanoOpis
AUTH_TOKEN(obavezno)Dijeljeni tajni ključ s PocketHook
LLM_API_KEY(obavezno)API ključ LLM pružatelja
LLM_PROVIDERanthropicNaziv pružatelja
LLM_MODELclaude-sonnet-4-20250514ID modela
LLM_REASONINGoffRazina 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
PORT3000Port poslužitelja
AGENT_NAMEPocketHook AssistantPrikazano ime agenta
MAX_HISTORY50Poruke u kratkoročnoj memoriji
MAX_RECALL5Sjećanja vraćena po potezu semantičkim doživljavanjem (samo kada VECTOR_MEMORY=true)
SESSION_TTL_MINUTES60Istjecanje sesije
VECTOR_MEMORYfalseOmogući semantičku memoriju (zahtijeva pružatelja embeddinga)
EMBEDDING_PROVIDERollamaPružatelj embeddinga: ollama, lm-studio ili openai
EMBEDDING_MODELnomic-embed-textNaziv modela embeddinga
EMBEDDING_URL(auto)URL API-ja embeddinga
EMBEDDING_API_KEYAPI ključ za OpenAI embeddinge
LOG_LEVELinfoRazina logiranja: debug, info, warn, error
RATE_LIMIT_MAX30Maksimalan broj zahtjeva po prozoru
DASHBOARDtrueOmoguć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_MODEListo kao glavniPružatelj/model za brzi model (unutarnji pomoćni zadaci)
SAFARI_PERMISSION_LEVELconfirmPolitika klikanja Safari proširenja: confirm, autonomous ili readonly
SAFARI_CAPTURES_BASE_URLsamo lokalnoJavni 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
PlatformaBackendLokacija usluge
macOSlaunchd~/Library/LaunchAgents/com.pockethook.${INSTANCE_NAME}.plist
Linuxsystemd (user)~/.config/systemd/user/pockethook-${INSTANCE_NAME}.service
WindowsNSSMPocketHook-${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, *.pem blokirane od pristupa agenta
  • Automatsko verzioniranje — Sve promjene workspace-a prate se gitom za lako vraćanje