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

Что такое 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 доступен только на хосте.

В качестве страховки каждый инструмент 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 для лёгкого отката