Агентський сервер

Що таке PocketHook Agent Server?

#

Агентський сервер перетворює PocketHook на повноцінного AI асистента. Замість написання логіки відповідей самостійно, ви підключаєте LLM (Claude, GPT, Gemini тощо), яка обробляє повідомлення, викликає інструменти та повертає структуровані відповіді PocketHook — включно з тригерами Shortcuts.

Сервер працює на вашій власній машині. Ваші дані залишаються у вас.

Це відправна точка. Сервер постачається з базовим набором інструментів і призначений для розширення вами. Додавайте власні інтеграції — електронна пошта, календарі, документи, API — і робіть його своїм.

Можливості

#

• Мультипровайдерна LLM — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (локально), LM Studio (локально)
• OAuth автентифікація — GitHub Copilot та OpenAI Codex через device code / браузерний потік
• Інструменти агента — Команди оболонки, читання/запис файлів, перегляд каталогів, веб-пошук, веб-скрейпінг, керування dev-серверами
• Розділення framework / користувач — Файли фреймворку (skills/, custom-tools/, config/) залишаються лише для читання. Ваші налаштування живуть під data/user/ (навички, користувацькі інструменти, інструкції, типізовані налаштування). Оновлення фреймворку надходять чисто, не перезаписуючи вашу роботу
• Типізовані користувацькі налаштування — Зберігайте значення, такі як улюблений застосунок мап або домен тунеля у data/user/prefs.json. Посилайтеся на них у навичках як {{prefs.key}}, і сервер підставить їх при завантаженні
• Програмні завдання одним викликом — Мета-інструмент run_code_job створює фонове завдання типу prompt (виконуване вашою налаштованою LLM) і надсилає користувачу підтвердження за один крок, замінюючи схильний до помилок шаблон «respond + create-job»
• Типізовані протокольні інструменти — Шість виділених інструментів respond_* (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), плюс типізовані інструменти завдань (create_once_job, create_cron_job) та типізовані інструменти робочого простору (create_project, list_projects, delete_project). Схеми відхиляють некоректні URL, синтаксис кнопок і комбінації type/schedule ще до того, як вони досягнуть пристрою
• Типізовані записувачі для налаштування — create_user_skill і create_custom_tool будують markdown користувацького шару з правильним frontmatter, тож завантажувач завжди їх парсить, а агент ніколи не пише ці файли вручну
• Фонові завдання — Одноразові або повторювані завдання з cron-виразами або простими інтервалами
• Динамічні навички — Визначайте швидкі команди та правила поведінки як файли .md. У промпт завантажується лише компактний індекс; повний вміст підвантажується на вимогу через інструмент load_skill
• Самокеровані навички — Агент може створювати, редагувати та видаляти визначення навичок (записи завжди потрапляють у користувацький шар)
• Семантична пам’ять — Векторний пошук з ембедингами (Ollama, LM Studio або OpenAI). Спогади автоматично класифікуються LLM за вимірами wing/room/hall/status
• Граф знань — Темпоральне сховище триплетів для стійких фактів з автоматичною інвалідацією. Множинні значення співіснують; одиничні значення автозамінюються
• Метод PARA з каскадом завершення проекту — Кожен спогад позначається статусом (Проект, Область, Ресурс, Архів). Коли проект завершується, один виклик complete_project архівує його вектори, інвалідує кожен триплет планування, прив’язаний до slug проекту, та записує завершення — один виклик замість трьох
• Гібридний пошук — Поєднує повнотекстовий пошук FTS5 з векторним семантичним пошуком за допомогою reciprocal rank fusion
• Довготривала пам’ять — SQLite + FTS5 повнотекстовий пошук як запасний варіант при вимкненій семантичній пам’яті
• Керування dev-серверами з контрактом тунеля — Запуск, зупинка та список dev-серверів. Коли запитується tunnel: true, сервер перевіряє це до та після запуску — недоступний localhost-сервер ніколи не залишається тихо працювати
• Автоматична санітизація URL — Якщо агент залишає localhost URL у відповіді, інструменти respond_* переписують його на відповідний тунельний URL, щоб ваш телефон завжди отримував доступне посилання
• Користувацькі інструменти — Агент може встановлювати CLI інструменти та реєструвати їх як нові можливості
• Версіонування — Автоматичне git-версіонування файлів робочого простору; бекапи конфігурації для навичок та дозволів
• Веб-панель — Живий огляд фонових завдань, налаштовуваний для кожного користувача. /dashboard та /api/jobs за задумом неавтентифіковані — обмежте доступ на мережевому рівні (Tailscale ACL, фаєрвол, reverse proxy з basic auth) або встановіть DASHBOARD=false, якщо вони вам не потрібні
• HTTPS тунелювання — Вбудована підтримка Tailscale, ngrok та Cloudflare Tunnel
• Системна служба — Встановлення як постійний сервіс на macOS, Linux або Windows
• Обмеження запитів — Ліміти запитів на токен з налаштовуваними порогами

Вимоги

#

• Середовище виконання Bun
• API ключ або OAuth облікові дані для вашого LLM провайдера
• (Опціонально) Tailscale, ngrok або cloudflared для HTTPS тунелювання

Швидкий старт

#

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

# Інтерактивне налаштування — вибір провайдера, моделі, токена авторизації, порту
bun run setup

# Запуск сервера + HTTPS тунель
bun run dev:tunnel

Майстер налаштування проведе вас через вибір LLM провайдера, налаштування автентифікації та встановлення дозволів інструментів.

Після запуску скопіюйте відображені URL у налаштування PocketHook:

Як це працює

#

1. Ви надсилаєте повідомлення в PocketHook
2. Сервер пересилає його обраній LLM з історією розмови, витягнутими спогадами та доступними інструментами
3. LLM обробляє повідомлення — може виконувати команди оболонки, читати/записувати файли, шукати в вебі, планувати фонові завдання, запам’ятовувати факти або запускати dev-сервери
4. Відповідь повертається у форматі PocketHook (msg + shortcut + data + url)
5. PocketHook відображає повідомлення та виконує всі Shortcuts на вашому пристрої

Підтримувані LLM провайдери

#

Перемикайте провайдерів у будь-який час за допомогою bun run switch. Ollama та LM Studio працюють повністю на вашій машині — без API ключа, дані не залишають вашу мережу.

Пам’ять

#

Система пам’яті має три рівні, кожен з яких служить певній меті.

Дизайн семантичної пам’яті поєднує ідеї MemPalace (архітектура палацу пам’яті, що організовує спогади у wings, halls та rooms) та методу PARA Тьяго Форте (Проекти, Області, Ресурси, Архів) для управління життєвим циклом знань.

Пам’ять розмови

#

SQLite з повнотекстовим пошуком FTS5. Усі повідомлення зберігаються з мітками часу та ідентифікаторами сесій.

• Короткострокова — Останні MAX_HISTORY повідомлень зберігаються в пам’яті на сесію
• Довгострокова — Усі повідомлення зберігаються в SQLite, доступні для пошуку через FTS5
• Витягання за хід — Коли семантична пам’ять увімкнена, MAX_RECALL контролює, скільки релевантних спогадів вставляється в промпт у кожному ході
• Сесії закінчуються після SESSION_TTL_MINUTES, але довгострокова пам’ять зберігається назавжди

Налаштовуйте ці значення інтерактивно за допомогою bun run memory.

Семантична пам’ять

#

Вимагає VECTOR_MEMORY=true та провайдера ембедингів (Ollama, LM Studio або OpenAI).

Кожен спогад перетворюється на вектор та автоматично класифікується LLM за чотирма вимірами:

• Wing — Сутність: user, person:john, project:blog, place:london
• Room — Тип: facts, preferences, events, decisions, requests
• Hall — Тема: personal, tech, health, travel, food, work
• Status — Класифікація PARA: project, area, resource, archive

Коли ви ставите запитання, витягування сутностей фокусує векторний пошук на найбільш релевантних wings. Результати об’єднуються з результатами FTS5 за допомогою reciprocal rank fusion — так ви отримуєте найкраще від обох видів пошуку.

Граф знань

#

Темпоральне сховище триплетів для структурованих, стійких фактів:

• Триплети: (subject, predicate, object) з мітками valid_from / valid_until
• Одиничні предикати (lives_in, partner) автоматично інвалідують старе значення при оновленні
• Множинні предикати (child, friend, hobby) співіснують без інвалідації
• Факти графу знань впроваджуються разом із витягнутими спогадами у кожну розмову

Коли ви кажете агенту «Я переїхав до Берліна», він інвалідує старий триплет lives_in та створює новий — автоматично.

Життєвий цикл PARA

#

Кожен спогад позначається статусом PARA:

• Проект — Активна, обмежена в часі робота
• Область — Постійні обов’язки
• Ресурс — Довідкові матеріали (списки, рекомендації, інструкції)
• Архів — Завершені або скасовані проекти

Коли проект завершується, агент використовує семантичну подібність для архівації лише спогадів цього проекту, зберігаючи довідкові матеріали для майбутнього використання.

Каскад завершення проекту

#

Скажіть «Я скасовую поїздку до Барселони», і один виклик інструменту зробить усе:

1. Архівує вектори проекту (події, рішення, запити, пов’язані з Барселоною).
2. Інвалідує кожен активний триплет графа знань, чий предикат відповідає slug проекту (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Записує завершення як новий триплет: (user, "cancelled_visit_barcelona", "2026-04-15").

Зіставлення враховує межі — інший проект із назвою revisit_barcelona залишається недоторканим. Агенту більше не потрібно оркеструвати три окремих виклики в правильному порядку, тож навіть менші моделі справляються правильно.

Якщо VECTOR_MEMORY вимкнений або провайдер ембедингів недоступний, система перемикається на FTS5 без помилок.

Навички

#

Навички — це файли .md у skills/, які визначають iOS Shortcuts, які агент може запускати, та/або правила поведінки. Вони використовують динамічне завантаження: у системний промпт впроваджується лише компактний індекс (заголовок, опис, список швидких команд). Агент завантажує повний вміст на вимогу через інструмент load_skill, зберігаючи низьке споживання токенів при додаванні нових навичок.

Кожен файл навички використовує YAML frontmatter:

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

### New Note

Shortcut name: `newNote`

Creates a new note on the user's device.

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

Поля frontmatter

#

Навички також можуть бути правилами поведінки без швидких команд (наприклад, «як планувати сімейну подорож»). Використовуйте shortcuts: [] для таких випадків.

Агент може створювати та керувати навичками за запитом — попросіть його «створи навичку для керування моїми лампочками», і він напише файл .md за вас. Нові та відредаговані навички завжди потрапляють у ваш користувацький шар (data/user/skills/), тож оновлення фреймворку ніколи їх не перезаписують. Див. нижче розділ Customizing your agent.

Виконання Shortcuts на Mac-сервері

#

Коли у навички вказано target: mac, Shortcuts виконуються тихо на Mac-сервері через CLI shortcuts run, а не надсилаються на пристрій iOS. Це ідеально підходить для дій, що створюють контент, синхронізований через iCloud — нотатки, нагадування, події календаря — оскільки результат автоматично синхронізується з усіма вашими пристроями без жодних дій з боку застосунку PocketHook.

Як це працює:

1. Агент вирішує, що Shortcut слід запустити (наприклад, «створи нотатку із сьогоднішніми записами зустрічі»)
2. Сервер викликає shortcuts run "shortcutName" з даними, що передаються як JSON через stdin, використовуючи той самий формат-обгортку, що й PocketHook iOS
3. Якщо задано sync_app, сервер короткочасно відкриває цей застосунок у фоні (open -gj -a Notes), щоб примусово запустити синхронізацію iCloud, а потім закриває його через 5 секунд
4. Користувач отримує підтверджувальне повідомлення в чаті; сам Shortcut на пристрій не надсилається

Вимоги:

• Сервер має працювати на macOS — shortcuts run доступний лише для macOS. На інших платформах сервер записує попередження та повертається до виконання на пристрої
• Shortcut має бути встановлений у Shortcuts.app на сервері Mac
• Shortcut має очікувати Dictionary на вході (PocketHook загортає дані у { context, timestamp, app, data })

Коли використовувати target: mac:

• Дії з синхронізацією через iCloud (Notes, Reminders, Calendar) — результат і так потрапляє на кожен пристрій
• Тривала обробка, яку ви хочете тримати подалі від iOS-пристрою
• Будь-який Shortcut, якому не потрібна взаємодія з інтерфейсом iPhone

Коли залишати target: device (за замовчуванням):

• Shortcuts, що використовують функції, доступні лише на iPhone (камера, точна геолокація, локальні автоматизації застосунків)
• Shortcuts, які запитують у користувача інтерактивне введення
• Shortcuts, що використовують App Intents із застосунків лише для iOS

Фонові завдання

#

Попросіть агента запланувати завдання, і він все зробить:

• «Перевіряй погоду кожного ранку о 8 годині та створюй нотатку»
• «Запускай цей скрипт кожну годину»
• «Нагадай мені перевірити пошту через 30 хвилин»

Завдання підтримують cron-вирази (0 8 * * *) та прості інтервали (30m, 1h, 2d). Результати доставляються в PocketHook при опитуванні ендпоінту /jobs.

Два типи виконання:

• Shell — Виконує команду bash, захоплює вивід. Може запускати Shortcut після завершення
• Prompt — Обробляється AI агентом з повним доступом до інструментів, зберігає повну відповідь PocketHook

Dev-сервери

#

Коли агент створює веб-проект у робочому просторі (Hugo, Astro, Next.js, Flask, Go тощо), він завчасно пропонує його обслуговувати:

• Попередній перегляд — Запускає локальний dev-сервер на автоматично призначеному порті для швидкого перегляду
• Публічний — Запускає сервер та відкриває його через HTTPS тунель для доступу з будь-якого місця

Агент керує життєвим циклом: запуск, зупинка та список працюючих серверів. Усі сервери очищаються при зупинці основного сервера.

Контракт тунеля

#

Коли агент запускає сервер із запитаним відкриттям через тунель, середовище виконання забезпечує це: якщо не встановлено жодного тунельного інструменту (Tailscale, ngrok, cloudflared), сервер відмовляється запускатися. Якщо налаштування тунеля зазнає невдачі після запуску, осиротілий процес зупиняється, і агент отримує явне повідомлення — тож він може повернутися в режим попереднього перегляду або попросити вас встановити тунель. Повернутий URL завжди є тунельним URL, коли тунелювання увімкнене, з приміткою, що локальний URL доступний лише на хості.

Як запобіжник, кожен інструмент respond_* постобробляє своє повідомлення: будь-який localhost або 127.0.0.1 URL, що пролізає у відповідь, автоматично переписується на відповідний тунельний URL, коли керований сервер має такий. Коли переписати неможливо, ви отримуєте попередження в логах замість зламаного посилання на телефоні.

Панель керування

#

Вбудована веб-панель за адресою /dashboard показує живий огляд фонових завдань.

За задумом неавтентифікована. І /dashboard, і /api/jobs — це відкриті GET ендпоінти; будь-хто, хто може дістатися до хоста, може переглянути список завдань. Обмежте доступ на мережевому рівні (Tailscale ACL, фаєрвол, reverse proxy з basic auth) або встановіть DASHBOARD=false, якщо вони вам не потрібні. iOS-застосунок PocketHook не використовує ці ендпоінти.

Вона повністю налаштовувана:

• Швидке редагування — Розмістіть dashboard.html у workspace/dashboard/ для простих налаштувань
• Повний проект — Створіть проект на фреймворку (Svelte, React, Vue тощо) у workspace/dashboard/ з виводом збірки у dist/

Попросіть агента налаштувати вашу панель, і він все зробить — кожен користувач отримує унікальну, персоналізовану панель.

Користувацькі інструменти

#

Агент може встановлювати CLI інструменти та реєструвати їх як нові можливості — розширюючи себе без модифікації коду сервера.

Наприклад, скажіть «встанови Playwright та використовуй його для створення скріншотів». Агент:

1. Встановить залежність
2. Створить визначення інструменту (простий файл .md)
3. Використовуватиме новий інструмент у майбутніх розмовах

Користувацькі інструменти перезавантажуються на льоту — перезапуск не потрібен. Видаліть файл .md, щоб прибрати інструмент.

Версіонування

#

Усі користувацькі дані версіонуються автоматично:

• Файли робочого простору — Відстежуються через локальний git-репозиторій всередині workspace/. Кожен запис створює автокоміт. Попросіть агента «скасувати останню зміну» або використовуйте git revert HEAD вручну
• Файли конфігурації — config/agent-instructions.md, config/personality.md, skills/ та permissions.json зберігаються перед кожною модифікацією. До 20 версій на файл

Git опціональний — якщо не встановлений, зміни робочого простору не версіонуються. Бекапи конфігурації працюють завжди.

Customizing your agent

#

Агентський сервер постачається з мінімальною базою фреймворку і очікує, що ви нашаруєте власні налаштування зверху. Середовище виконання тримає ці дві речі окремо, щоб оновлення фреймворку ніколи не псували вашу роботу.

Framework проти користувача

#

pockethook-agent-server/
├── skills/                      # навички, що постачаються з фреймворком (лише для читання)
├── custom-tools/                # зарезервовано для інструментів фреймворку (лише для читання)
├── config/
│   ├── agent-instructions.md    # інструкції агента з фреймворку (лише для читання)
│   └── personality.md           # особистість з фреймворку (лише для читання)
└── data/user/                   # ВАШІ налаштування живуть тут (ігноруються git)
    ├── skills/                  # ваші власні навички (переважають над базою за ім'ям файлу)
    ├── custom-tools/            # ваші встановлені користувацькі інструменти
    ├── instructions.md          # ваші доповнення до інструкцій агента
    └── prefs.json               # типізовані значення, на які посилаються як {{prefs.key}}

Користувацькі налаштування записуються через виділені типізовані інструменти (create_user_skill, create_custom_tool), тож отримані файли завжди відповідають формату завантажувача. Інструмент write також відхиляє будь-який шлях під skills/, custom-tools/ чи config/ і перенаправляє агента до data/user/* — тож навіть прямі редагування файлів потрапляють у користувацький шар.

Примітка про базовий каталог custom-tools/. Сьогодні він містить лише шаблон (_example.md), який завантажувач ігнорує — кожен інструмент, який агент встановлює для вас, потрапляє в data/user/custom-tools/. Каталог зарезервовано, щоб майбутні релізи фреймворку могли постачати опціональні вбудовані інструменти, не перезаписуючи ваших установок. Коли це станеться, ваші файли в користувацькому шарі все одно переможуть при конфлікті імен інструментів, тож нічого мігрувати не доведеться.

Чотири способи налаштування

#

Вам ніколи не треба писати ці файли вручну. Просто скажіть агенту, чого ви хочете, і він автоматично обере правильний шар.

Типізовані налаштування з {{prefs.*}}

#

Припустимо, ви пишете навичку-планувальник маршрутів, якій потрібно знати ваш типовий пункт відправлення. Замість того щоб зашивати «Мадрид» у навичку, посилайтеся на налаштування:

- **Пункт відправлення**: {{prefs.routeOrigin}}, якщо користувач не вказав інший початок.

І збережіть значення у data/user/prefs.json:

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

Сервер підставляє плейсхолдери при завантаженні навички. Вкладені ключі ({{prefs.tunnel.domain}}) також працюють. Невідомі ключі залишаються недоторканими, щоб помилки написання залишалися видимими.

Пряме редагування бази фреймворку

#

Якщо ви хостите самостійно і хочете налаштувати сам фреймворк, ви можете напряму редагувати config/agent-instructions.md, config/personality.md, skills/ або custom-tools/ — сервер не зупиняє вас, коли ви використовуєте редактор файлів. Але агент не буде писати в ці шляхи з розмови. А оновлення фреймворку перезапишуть ваші правки. Для всього, що хочете зберегти, віддавайте перевагу користувацькому шару.

Розширення сервера

#

• Користувацькі інструменти — Попросіть агента встановити CLI інструменти; вони автоматично потрапляють у data/user/custom-tools/
• Додавання навичок — Попросіть агента створити навичку; файл потрапляє в data/user/skills/
• Зміна поведінки — Попросіть агента застосувати глобальне правило; воно додається до data/user/instructions.md
• Налаштування дозволів — Запустіть bun run permissions для керування доступними інструментами агента
• Додавання вбудованих інструментів — Реалізуйте нові функції інструментів у src/tools.ts для глибших інтеграцій (вимагає форку сервера)

Конфігурація

#

Усі налаштування зберігаються у .env (створюється через bun run setup). Основні параметри:

Повну довідку з конфігурації дивіться у GitHub репозиторії.

Запуск як служба

#

Встановіть як постійну службу, яка запускається автоматично:

bun run service install

INSTANCE_NAME за замовчуванням — це базова назва каталогу проекту з відрізаним префіксом pockethook- (наприклад, копія в pockethook-agent-server/ стає agent-server). Встановіть його явно, щоб запустити кілька копій на одній машині без колізій — кожен екземпляр зберігає власні data/ та логи.

Керуйте за допомогою bun run service status, restart, stop або uninstall.

Безпека

#

• Обов’язковий HTTPS — PocketHook вимагає HTTPS для всіх URL
• Авторизація Bearer токеном — Спільний секрет між додатком та сервером
• Обмеження запитів — Ліміти на токен запобігають зловживанням
• Ізольовані інструменти — Команди оболонки та доступ до файлів обмежені дозволами
• Заблоковані шаблони — Небезпечні команди (sudo, rm -rf /) заблоковані за замовчуванням
• Межа робочого каталогу — Агент не може вийти за межі призначеного каталогу
• Захист конфіденційних файлів — .env, .git, *.key, *.pem заблоковані для доступу агента
• Автоматичне версіонування — Усі зміни робочого простору відстежуються через git для легкого відкату