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í)
• 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ů.

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