Agentní server

Co je PocketHook Agent Server?

#

Agentní server promění PocketHook v plnohodnotného AI asistenta. Místo toho, abyste sami psali logiku odpovědí, připojíte LLM (Claude, GPT, Gemini atd.), který zpracovává zprávy, volá nástroje a vrací strukturované odpovědi PocketHook — včetně spouštěčů Zkratek.

Server běží na vašem vlastním počítači. Vaše data zůstávají u vás.

Toto je výchozí bod. Server se dodává se základní sadou nástrojů a je navržen tak, abyste ho rozšiřovali. Přidejte vlastní integrace — e-mail, kalendáře, dokumenty, API — a přizpůsobte si ho.

Funkce

#

• Více poskytovatelů LLM — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (lokální), LM Studio (lokální)
• Rychlý model — Spusťte odlehčený sekundární model pro interní pomocné úlohy (klasifikace paměti, extrakce entit) souběžně s vaším hlavním modelem pro chat — plná kontrola nad náklady a latencí
• Rozšíření Safari — Spárujte notarizované rozšíření Safari pro macOS, aby agent mohl otevírat panely, prohlížet stránky, klikat, vyplňovat formuláře a pořizovat snímky obrazovky ve vaší skutečné relaci prohlížeče, na úrovni oprávnění, kterou zvolíte
• OAuth autentizace — GitHub Copilot a OpenAI Codex přes device code / browser flow
• Agentní nástroje — Příkazy shellu, čtení/zápis souborů, výpis adresářů, webové vyhledávání, web scraping, správa vývojových serverů
• Rozdělení framework / uživatel — Soubory frameworku (skills/, custom-tools/, config/) zůstávají pouze pro čtení. Vaše úpravy žijí v data/user/ (dovednosti, vlastní nástroje, instrukce, typované preference). Aktualizace frameworku se instalují čistě, aniž by přepisovaly vaši práci
• Typované uživatelské preference — Ukládejte hodnoty jako preferovanou mapovou aplikaci nebo doménu tunelu do data/user/prefs.json. Odkazujte na ně v dovednostech jako {{prefs.key}} a server je při načtení nahradí
• Programovací úlohy jedním voláním — Meta-nástroj run_code_job vytvoří úlohu na pozadí typu prompt (spouštěnou vaším nakonfigurovaným LLM) a jedním krokem pošle uživateli potvrzení, čímž nahrazuje chybový vzor „respond + create-job"
• Typované protokolové nástroje — Šest dedikovaných nástrojů respond_* (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), plus typované nástroje úloh (create_once_job, create_cron_job) a typované nástroje pracovního prostoru (create_project, list_projects, delete_project). Schémata odmítají špatně formátované URL, syntaxi tlačítek a kombinace type/schedule dříve, než se dostanou na zařízení
• Typované zapisovače pro přizpůsobení — create_user_skill a create_custom_tool sestavují markdown uživatelské vrstvy se správným frontmatterem, takže loader je vždy parsuje a agent tyto soubory nikdy nepíše ručně
• Úlohy na pozadí — Jednorázové nebo opakované úlohy s cron výrazy nebo jednoduchými intervaly
• Dynamické dovednosti — Definujte zkratky a pravidla chování jako .md soubory. Do promptu se načte pouze kompaktní index; plný obsah se načítá na vyžádání přes nástroj load_skill
• Samosprávné dovednosti — Agent může vytvářet, upravovat a mazat definice dovedností (zápisy vždy míří do uživatelské vrstvy)
• Sémantická paměť — Vektorové vyhledávání s embeddingy (Ollama, LM Studio nebo OpenAI). Vzpomínky jsou automaticky klasifikovány LLM do dimenzí wing/room/hall/status
• Znalostní graf — Temporální úložiště trojic pro trvalé fakty s automatickou invalidací. Vícehodnotové vztahy koexistují; jednohodnotové fakty se automaticky nahrazují
• Metoda PARA s kaskádou ukončení projektu — Každá vzpomínka je označena statusem (Projekt, Oblast, Zdroj, Archiv). Když projekt skončí, jediné volání complete_project archivuje jeho vektory, invaliduje všechny plánovací trojice spojené s jeho slugem a zaznamená dokončení — jedno volání místo tří
• Hybridní vybavování — Kombinuje klíčové slovo vyhledávání FTS5 s vektorovým sémantickým vyhledáváním pomocí reciprocal rank fusion
• Dlouhodobá paměť — SQLite + fulltextové vyhledávání FTS5 jako záložní řešení, když je sémantická paměť vypnuta
• Správa vývojových serverů s kontraktem tunelu — Spouštění, zastavování a výpis vývojových serverů. Když je požadováno tunnel: true, server to vynucuje před startem i po spawnu — nedostupný localhost server nikdy neběží potichu
• Automatická sanitizace URL — Pokud agent nechá v odpovědi URL localhost, nástroje respond_* ji přepíšou na odpovídající URL tunelu, aby váš telefon vždy dostal dostupný odkaz
• Vlastní nástroje — Agent může instalovat CLI nástroje a registrovat je jako nové schopnosti
• Verzování — Automatické git verzování pro soubory workspace; zálohy konfigurace pro dovednosti a oprávnění
• Webový dashboard — Živý přehled úloh na pozadí, přizpůsobitelný pro každého uživatele. /dashboard a /api/jobs jsou záměrně neautentizované — omezte přístup na úrovni sítě (Tailscale ACL, firewall, reverse proxy s basic auth) nebo nastavte DASHBOARD=false, pokud je nepotřebujete
• HTTPS tunelování — Vestavěná podpora pro Tailscale, ngrok a Cloudflare Tunnel
• Systémová služba — Instalace jako trvalá služba na macOS, Linux nebo Windows
• Omezování požadavků — Limity na token s konfigurovatelnými prahy

Požadavky

#

• Runtime Bun
• API klíč nebo OAuth přihlašovací údaje pro vašeho poskytovatele LLM
• (Volitelně) Tailscale, ngrok nebo cloudflared pro HTTPS tunelování

Rychlý start

#

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

# Interaktivní nastavení — volba poskytovatele, modelu, autentizačního tokenu, portu
bun run setup

# Spuštění serveru + HTTPS tunelu
bun run dev:tunnel

Průvodce nastavením vás provede výběrem poskytovatele LLM, konfigurací autentizace a nastavením oprávnění nástrojů — včetně volby, zda nainstalovat rozšíření Safari (volitelné, lze přeskočit, pouze macOS).

Kdykoli spusťte bun run help pro úplný seznam příkazů, nebo bun run config pro rychlý přehled aktuální konfigurace (citlivé údaje jsou skryté).

Po spuštění zkopírujte zobrazené URL do Nastavení PocketHook:

Jak to funguje

#

1. Odešlete zprávu v PocketHook
2. Server ji přepošle vašemu zvolenému LLM s historií konverzace, vybavenými vzpomínkami a dostupnými nástroji
3. LLM zprávu zpracuje — může spouštět příkazy shellu, číst/zapisovat soubory, prohledávat web, plánovat úlohy na pozadí, pamatovat si fakty nebo spouštět vývojové servery
4. Odpověď je vrácena ve formátu PocketHook (msg + shortcut + data + url)
5. PocketHook zobrazí zprávu a provede případné Zkratky na vašem zařízení

Podporovaní poskytovatelé LLM

#

Přepněte poskytovatele kdykoli pomocí bun run switch. Ollama a LM Studio běží zcela na vašem počítači — nepotřebujete API klíč, žádná data neopustí vaši síť.

Paměť

#

Systém paměti má tři vrstvy, z nichž každá slouží jinému účelu.

Design sémantické paměti kombinuje myšlenky z MemPalace (architektura paměťového paláce, která organizuje vzpomínky do křídel, chodeb a pokojů) a metody PARA od Tiaga Forte (Projekty, Oblasti, Zdroje, Archiv) pro správu životního cyklu znalostí.

Konverzační paměť

#

SQLite s fulltextovým vyhledáváním FTS5. Všechny zprávy jsou ukládány s časovými razítky a identifikátory relací.

• Krátkodobá — Posledních MAX_HISTORY zpráv uchovávaných v paměti na relaci
• Dlouhodobá — Všechny zprávy uložené v SQLite, prohledávatelné přes FTS5 párování klíčových slov
• Vybavování za tah — Když je sémantická paměť zapnuta, MAX_RECALL určuje, kolik relevantních vzpomínek se vkládá do promptu při každém tahu
• Relace vyprší po SESSION_TTL_MINUTES, ale dlouhodobá paměť přetrvává navždy

Tyto hodnoty laďte interaktivně příkazem bun run memory.

Sémantická paměť

#

Vyžaduje VECTOR_MEMORY=true a poskytovatele embeddingů (Ollama, LM Studio nebo OpenAI).

Každá vzpomínka je vložena jako vektor a automaticky klasifikována LLM do čtyř dimenzí:

• Wing — Entita: user, person:john, project:blog, place:london
• Room — Typ: facts, preferences, events, decisions, requests
• Hall — Téma: personal, tech, health, travel, food, work
• Status — PARA klasifikace: project, area, resource, archive

Když položíte otázku, extrakce entit zaměří vektorové vyhledávání na nejrelevantnější křídla. Výsledky jsou sloučeny s FTS5 výsledky klíčových slov pomocí reciprocal rank fusion — takže získáte to nejlepší z obou přístupů.

Znalostní graf

#

Temporální úložiště trojic pro strukturované, trvalé fakty:

• Trojice: (subjekt, predikát, objekt) s časovými razítky valid_from / valid_until
• Jednohodnotové predikáty (lives_in, partner) automaticky invalidují starou hodnotu při aktualizaci
• Vícehodnotové predikáty (child, friend, hobby) koexistují bez invalidace
• Fakty ze znalostního grafu jsou vkládány společně s vybavenými vzpomínkami do každé konverzace

Když agentovi řeknete „Přestěhoval jsem se do Berlína", invaliduje starou trojici lives_in a vytvoří novou — automaticky.

PARA životní cyklus

#

Každá vzpomínka je označena PARA statusem:

• Projekt — Aktivní, časově omezená práce
• Oblast — Probíhající odpovědnosti
• Zdroj — Referenční materiál (seznamy, doporučení, návody)
• Archiv — Dokončené nebo zrušené projekty

Když je projekt dokončen, agent použije sémantickou podobnost k archivaci pouze vzpomínek daného projektu, přičemž zachová referenční materiál pro budoucí použití.

Kaskáda ukončení projektu

#

Řekněte „Ruším cestu do Barcelony" a jediné volání nástroje zařídí vše:

1. Archivuje vektory projektu (události, rozhodnutí, požadavky spojené s Barcelonou).
2. Invaliduje každou aktivní trojici znalostního grafu, jejíž predikát odpovídá slugu projektu (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Zaznamená dokončení jako novou trojici: (user, "cancelled_visit_barcelona", "2026-04-15").

Porovnávání respektuje hranice slov — jiný projekt s názvem revisit_barcelona zůstane nedotčený. Agent již nemusí orchestrovat tři oddělená volání ve správném pořadí, takže to zvládnou i menší modely.

Pokud je VECTOR_MEMORY vypnuto nebo je poskytovatel embeddingů nedostupný, systém se přepne na FTS5 bez chyb.

Dovednosti

#

Dovednosti jsou .md soubory v adresáři skills/, které definují iOS Zkratky, které agent může spouštět, a/nebo pravidla chování. Používají dynamické načítání: do systémového promptu se vkládá pouze kompaktní index (název, popis, seznam zkratek). Agent načítá plný obsah na vyžádání přes nástroj load_skill, čímž udržuje nízkou spotřebu tokenů při přidávání dalších dovedností.

Každý soubor dovednosti používá 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

Pole frontmatteru

#

Dovednosti mohou být také pravidla chování bez zkratek (např. „jak naplánovat rodinný výlet"). Pro tyto použijte shortcuts: [].

Agent může vytvářet a spravovat dovednosti na vyžádání — požádejte ho o „vytvoř dovednost pro ovládání mých světel" a napíše .md soubor za vás. Nové a upravené dovednosti vždy míří do vaší uživatelské vrstvy (data/user/skills/), takže aktualizace frameworku je nikdy nepřepíší. Viz sekci Customizing your agent níže.

Spouštění zkratek na Mac serveru

#

Když má dovednost target: mac, zkratky běží tiše na Mac serveru přes CLI shortcuts run, místo aby byly odesílány na zařízení iOS. To je ideální pro akce, které vytvářejí obsah synchronizovaný s iCloud — poznámky, připomenutí, události kalendáře — protože výsledek se automaticky synchronizuje na všechna vaše zařízení, aniž by aplikace PocketHook musela cokoli dělat.

Jak to funguje:

1. Agent rozhodne, že se má zkratka spustit (např. „vytvoř poznámku s dnešními poznámkami ze schůzky")
2. Server zavolá shortcuts run "názevZkratky" s daty předanými jako JSON na stdin, ve stejném obalovém formátu, jaký používá PocketHook iOS
3. Pokud je sync_app nastaveno, server na chvíli otevře tuto aplikaci na pozadí (open -gj -a Notes), aby vynutil synchronizaci iCloud, a po 5 sekundách ji zavře
4. Uživatel obdrží potvrzovací zprávu v chatu; samotná zkratka není odeslána na zařízení

Požadavky:

• Server musí běžet na macOS — shortcuts run je pouze pro macOS. Na jiných platformách server zaloguje varování a vrátí se k vykonání na zařízení
• Zkratka musí být nainstalovaná v Shortcuts.app na Mac serveru
• Zkratka by měla očekávat Dictionary jako vstup (PocketHook zabalí data do { context, timestamp, app, data })

Kdy použít target: mac:

• Akce synchronizované s iCloud (Notes, Reminders, Calendar) — výsledek se stejně dostane na každé zařízení
• Dlouhotrvající zpracování, které chcete držet mimo iOS zařízení
• Jakákoli zkratka, která nepotřebuje interagovat s uživatelským rozhraním iPhonu

Kdy ponechat target: device (výchozí):

• Zkratky, které potřebují funkce dostupné pouze na iPhonu (kamera, přesná poloha, lokální automatizace aplikací)
• Zkratky, které žádají uživatele o interaktivní vstup
• Zkratky používající App Intents z aplikací dostupných pouze na iOS

Úlohy na pozadí

#

Požádejte agenta o naplánování úloh a zbytek zvládne sám:

• „Kontroluj počasí každé ráno v 8 a vytvoř poznámku"
• „Spouštěj tento skript každou hodinu"
• „Připomeň mi zkontrolovat e-mail za 30 minut"

Úlohy podporují cron výrazy (0 8 * * *) a jednoduché intervaly (30m, 1h, 2d). Výsledky jsou doručeny do PocketHook, když dotazuje koncový bod /jobs.

Dva typy provádění:

• Shell — Spustí bash příkaz, zachytí výstup. Může spustit Zkratku po dokončení
• Prompt — Zpracován AI agentem s plným přístupem k nástrojům, uloží kompletní odpověď PocketHook

Vývojové servery

#

Když agent vytvoří webový projekt v workspace (Hugo, Astro, Next.js, Flask, Go atd.), proaktivně nabídne jeho servírování:

• Náhled — Spustí lokální vývojový server na automaticky přiděleném portu pro rychlé zobrazení
• Veřejný — Spustí server a vystaví ho přes HTTPS tunel, aby byl přístupný odkudkoli

Agent spravuje životní cyklus: spouštění, zastavování a výpis běžících serverů. Všechny servery se uklidí při zastavení hlavního serveru.

Kontrakt tunelu

#

Když agent spouští server s požadavkem na expozici přes tunel, runtime to vynucuje: pokud není nainstalovaný žádný tunelovací nástroj (Tailscale, ngrok, cloudflared), server odmítne start. Pokud nastavení tunelu selže po spawnu, osiřelý proces je zastaven a agent dostane explicitní informaci — tak, aby se mohl vrátit do režimu náhledu nebo vás požádat o instalaci tunelu. Vrácené URL je vždy URL tunelu, když je tunelování zapnuto, s poznámkou, že lokální URL je dostupné pouze hostiteli.

Jako pojistka každý nástroj respond_* zpětně zpracovává svou zprávu: jakékoli URL localhost nebo 127.0.0.1, které se do odpovědi vkrade, je automaticky přepsáno na odpovídající URL tunelu, když spravovaný server nějaké má. Když přepsat nejde, dostanete varování v logu namísto rozbitého odkazu na telefonu.

Dashboard

#

Vestavěný webový dashboard na /dashboard zobrazuje živý přehled úloh na pozadí.

Záměrně neautentizovaný. /dashboard i /api/jobs jsou otevřené GET endpointy — kdokoli, kdo se dostane na hostitele, může vypsat úlohy. Omezte přístup na úrovni sítě (Tailscale ACL, firewall, reverse proxy s basic auth) nebo nastavte DASHBOARD=false, pokud je nepotřebujete. iOS aplikace PocketHook tyto endpointy nepoužívá.

Je plně přizpůsobitelný:

• Rychlá úprava — Umístěte soubor dashboard.html do workspace/dashboard/ pro jednoduché úpravy
• Plný projekt — Vytvořte projekt s frameworkem (Svelte, React, Vue atd.) ve workspace/dashboard/ s výstupem sestavení do dist/

Požádejte agenta o přizpůsobení vašeho dashboardu a zbytek zvládne sám — každý uživatel dostane unikátní, personalizovaný dashboard.

Vlastní nástroje

#

Agent může instalovat CLI nástroje a registrovat je jako nové schopnosti — rozšiřuje se sám bez úpravy kódu serveru.

Například řekněte „nainstaluj Playwright a použij ho k pořizování snímků obrazovky". Agent:

1. Nainstaluje závislost
2. Vytvoří definici nástroje (jednoduchý .md soubor)
3. Použije nový nástroj v budoucích konverzacích

Vlastní nástroje se načítají za běhu — restart není potřeba. Smažte .md soubor pro odebrání nástroje.

Verzování

#

Všechna uživatelská data jsou automaticky verzována:

• Soubory workspace — Sledovány lokálním git repozitářem uvnitř workspace/. Každý zápis vytvoří auto-commit. Požádejte agenta o „vrať zpět poslední změnu" nebo použijte git revert HEAD ručně
• Konfigurační soubory — config/agent-instructions.md, config/personality.md, skills/ a permissions.json jsou zálohovány před každou úpravou. Až 20 verzí na soubor

Git je volitelný — pokud není nainstalován, změny workspace nejsou verzovány. Zálohy konfigurace fungují vždy.

Customizing your agent

#

Agentní server se dodává s minimální základnou frameworku a očekává, že si na ni navrstvíte vlastní úpravy. Runtime udržuje obě vrstvy oddělené, aby aktualizace frameworku nikdy nepřepsaly vaši práci.

Framework vs uživatel

#

pockethook-agent-server/
├── skills/                      # dovednosti dodávané frameworkem (pouze pro čtení)
├── custom-tools/                # rezervováno pro nástroje dodávané frameworkem (pouze pro čtení)
├── config/
│   ├── agent-instructions.md    # instrukce agenta z frameworku (pouze pro čtení)
│   └── personality.md           # osobnost z frameworku (pouze pro čtení)
└── data/user/                   # VAŠE úpravy žijí zde (ignorováno gitem)
    ├── skills/                  # vaše vlastní dovednosti (přepíší základ podle názvu souboru)
    ├── custom-tools/            # vaše nainstalované vlastní nástroje
    ├── instructions.md          # vaše doplňky k instrukcím agenta
    └── prefs.json               # typované hodnoty referencované jako {{prefs.key}}

Uživatelské úpravy se zapisují přes dedikované typované nástroje (create_user_skill, create_custom_tool), takže výsledné soubory vždy odpovídají formátu loaderu. Nástroj write také odmítá jakoukoli cestu pod skills/, custom-tools/ nebo config/ a přesměrovává agenta do data/user/* — takže i přímé úpravy souborů končí v uživatelské vrstvě.

Poznámka k základnímu adresáři custom-tools/. Dnes obsahuje pouze šablonu (_example.md), kterou loader ignoruje — každý nástroj, který agent nainstaluje, míří do data/user/custom-tools/. Adresář je rezervován, aby budoucí verze frameworku mohly dodávat volitelné vestavěné nástroje bez přepsání vašich instalací. Až k tomu dojde, vaše soubory v uživatelské vrstvě stále vyhrávají při kolizi názvů, takže není co migrovat.

Čtyři způsoby přizpůsobení

#

Tyto soubory nikdy nemusíte psát ručně. Stačí říct agentovi, co chcete, a on sám vybere správnou vrstvu.

Typované preference s {{prefs.*}}

#

Dejme tomu, že píšete dovednost plánovače trasy, která potřebuje znát váš výchozí bod. Místo abyste do dovednosti natvrdo napsali „Madrid", odkažte na preferenci:

- **Výchozí bod**: {{prefs.routeOrigin}}, pokud uživatel neurčí jiný počátek.

A uložte hodnotu do data/user/prefs.json:

{
  "routeOrigin": "Madrid, Španělsko",
  "preferredMapsApp": "apple",
  "tunnel": { "domain": "my-host.ts.net" }
}

Server nahrazuje placeholdery při načtení dovednosti. Vnořené klíče ({{prefs.tunnel.domain}}) fungují také. Neznámé klíče zůstanou nedotčené, aby překlepy zůstaly viditelné.

Úprava základny frameworku přímo

#

Pokud si server hostujete sami a chcete upravit samotný framework, můžete editovat config/agent-instructions.md, config/personality.md, skills/ nebo custom-tools/ přímo — server vás nezastaví, když použijete editor souborů. Ale agent do těchto cest z konverzace nezapíše. A aktualizace frameworku vaše úpravy přepíšou. Pro cokoli, co chcete zachovat, preferujte uživatelskou vrstvu.

Rozšíření serveru

#

• Vlastní nástroje — Požádejte agenta o instalaci CLI nástrojů; automaticky míří do data/user/custom-tools/
• Přidejte dovednosti — Požádejte agenta o vytvoření dovednosti; soubor míří do data/user/skills/
• Změňte chování — Požádejte agenta o aplikaci globálního pravidla; připojí ho do data/user/instructions.md
• Konfigurujte oprávnění — Spusťte bun run permissions pro kontrolu, které nástroje agent může používat
• Přidejte vestavěné nástroje — Implementujte nové funkce nástrojů v src/tools.ts pro hlubší integrace (vyžaduje fork serveru)

Konfigurace

#

Všechna nastavení jsou uložena v .env (vytvořeno pomocí bun run setup). Klíčové možnosti:

Kompletní referenci konfigurace najdete v GitHub repozitáři.

Spuštění jako služba

#

Nainstalujte jako trvalou službu, která se spouští automaticky:

bun run service install

INSTANCE_NAME se ve výchozím nastavení odvozuje z názvu adresáře projektu s odstraněným prefixem pockethook- (např. kopie v pockethook-agent-server/ se stane agent-server). Nastavte ho explicitně pro spuštění více kopií na stejném počítači bez kolizí — každá instance si zachovává vlastní data/ a logy.

Spravujte pomocí bun run service status, restart, stop nebo uninstall.

Bezpečnost

#

• Vyžadováno HTTPS — PocketHook vyžaduje HTTPS pro všechny URL
• Bearer token autentizace — Sdílený tajný klíč mezi aplikací a serverem
• Omezování požadavků — Limity na token brání zneužití
• Izolované nástroje — Příkazy shellu a přístup k souborům omezeny oprávněními
• Blokované vzory — Nebezpečné příkazy (sudo, rm -rf /) blokované ve výchozím nastavení
• Hranice pracovního adresáře — Agent nemůže opustit svůj určený adresář
• Chráněné citlivé soubory — .env, .git, *.key, *.pem blokovány před přístupem agenta
• Automatické verzování — Všechny změny workspace jsou sledovány gitem pro snadný návrat