Skip to content
bigtaed-sysPublic

About

Персональный AI-агент: ядро на своей машине, клиенты подключаются к нему

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Axon

Персональный AI-агент, у которого ядро живёт на твоей машине или сервере, а приложения подключаются к нему и синхронизируются.

Идея

Ядро (core) владеет всем: историей, памятью, инструментами, контекстом, вызовами моделей. Клиенты — тонкие: рисуют и вводят. Из этого следует главное свойство — сколько бы устройств ни было подключено, контекст один, кэш промпта один, и расход токенов не умножается на число экранов.

        ┌──────────────── ЯДРО (демон) ───────────────────────────────┐
        │  агент-рантайм · память · инструменты · планировщик         │
        │  журнал событий (append-only, seq) · API: WS + REST         │
        └──────┬──────────────────┬───────────────────┬───────────────┘
               │                  │                   │
          десктоп            мобильное           Telegram
                              приложение         (адаптер)

Пакеты

Пакет Назначение Статус
packages/protocol Контракт ядро ↔ клиент: журнал, команды, кадры готов
packages/core Headless-рантайм: хранилище, журнал, провайдеры, инструменты, оркестратор готов
packages/daemon Обвязка ядра: HTTP + WS, пейринг, блобы, CLI готов
packages/client-sdk Клиентская библиотека: подключение, синк, стрим готов
packages/plugin-sdk Типы для авторов плагинов готов
apps/desktop Electron-клиент работает
examples/hello-plugin Пример плагина со всеми точками расширения —

Три решения, на которых всё держится

Журнал вместо синхронизации состояний. Всё, что меняет состояние, дописывается в append-only журнал с монотонным seq. Клиент помнит последний применённый seq и при подключении просит «дай всё после N». Оффлайн, переподключение, несколько устройств сразу — один механизм, а не три. Писатель по сути один (ядро), поэтому CRDT здесь не нужен.

Журнал и эфемерика разделены. Поток токенов, фазы работы, счётчик расхода — это сигналы: не нумеруются, не хранятся, не досылаются. Правило: если потеря не ломает состояние — это сигнал. Иначе журнал распух бы в тысячу раз и синк на слабом канале умер бы.

Расход токенов виден на уровне протокола. Usage отделяет cachedInputTokens от обычных, вывод инструмента обрезается до preview со ссылкой на полный blob, у прогона есть budgetTokens и stopReason: 'budget_exhausted'. Это не «не забудьте оптимизировать», а форма контракта.

И это видно пользователю: в заголовке чата есть разбор «во что обходится контекст» — сколько токенов стоит системный промпт, память, оглавление скиллов, схемы инструментов и история, и какая часть попадёт в кэш. Обычно расход показывают постфактум одной цифрой, с которой ничего нельзя сделать; здесь — до отправки и по частям, каждую из которых можно уменьшить.

Рутины

То, что агент делает сам, без человека рядом. Человек описывает задачу словами — «каждое утро посмотри, что изменилось в папке проекта, и, если есть что сказать, напиши сводку», — а Axon один раз компилирует описание в явный список шагов. Дальше рутина исполняется детерминированно.

Компиляция, а не «запускать агента каждый раз», выигрывает по трём статьям:

  • Цена. Рутина «каждые полчаса» — это сорок восемь прогонов в сутки. Цикл агента везёт с собой контекст и схемы всех инструментов; скомпилированные шаги не стоят почти ничего, а часто и вовсе не обращаются к модели.
  • Предсказуемость. Фоновая задача, каждый раз заново решающая, что делать, — самая пугающая разновидность автоматизации. Шаги видно до включения.
  • Ошибки. Компилятор сверяет каждый шаг с настоящими схемами инструментов: несуществующий инструмент, забытый обязательный аргумент или выдуманное имя поля всплывают при создании, а не в три часа ночи на первом прогоне.

Жёсткий конвейер при этом не умеет главного — решать по обстановке. Поэтому есть шаг agent: один шаг с собственным бюджетом там, где нужно суждение, вместо агента на каждом шагу.

Всего шагов двенадцать: вызов инструмента, вопрос модели, разбор текста на поля, агент, ветвление, повтор по списку, переменная, уведомление, сообщение в переписку, запись в память, пауза и досрочная остановка. Каждый прогон записывается пошагово — видно, на чём именно рутина споткнулась.

Опасные инструменты рутина получает только поимённо: рядом нет человека, который подтвердит действие, и подтверждать его молча нельзя.

Время следующего запуска считается наперёд и хранится в базе, а не держится таймером: ядро на личной машине выключают и усыпляют. Проснувшись, оно видит, что момент прошёл, и отрабатывает пропущенное.

Личность

Агент без личности — модель с инструментами: отвечает корректно, узнать его невозможно, каждый разговор начинается со знакомства заново. Личность здесь собрана из трёх вещей, и только первая про текст.

Характер задаётся структурой, а не полем для системного промпта: пресет плюс ручки (юмор, длина ответов, инициатива в разговоре, эмодзи) плюс свободный текст поверх. Свободное поле выглядит гибким, но перекладывает работу на человека — написать себе хороший промпт умеет один из ста, остальные оставляют его пустым. Тексты характеров живут в ядре, поэтому во всех каналах голос один.

Имени по умолчанию нет. Любое умолчание агент назвал бы в первом же разговоре, то есть ответил бы на вопрос «как тебя зовут» раньше человека — а имя, которое человек мог бы дать, оказалось бы занято. При знакомстве он спрашивает сам: спокойно, по одному вопросу за раз, и не вместо дела, если человек пришёл с делом.

Память об отношениях — отдельная от фактов сущность. Факт отвечает на «что верно» и живёт, пока его не отменят; наблюдение отвечает на «как оно с этим человеком» и выцветает само, с разной скоростью для привычки и для настроения. Без выцветания «занят переездом», записанное в марте, въезжало бы в промпт и в декабре. Подтверждение считается от выцветшего веса, а не от записанного: то, что подтвердилось спустя полгода, начинает почти с нуля.

Инициатива — право заговорить первым. Раз в несколько минут дешёвый запрос без истории отвечает «нет» или «да: повод»; полный контекст тратится только на втором шаге, когда повод нашёлся. Что поводом не считается — дежурное «как дела», желание напомнить о себе — перечислено в задании явно, иначе модель находит повод всегда. Выключена по умолчанию, с дневной нормой и тихими часами.

Подробнее — docs/личность.md.

Плагины

Плагин — единица установки. Внутри может лежать что угодно из трёх: свои инструменты на JS, подключения к MCP-серверам и скиллы (инструкции текстом). Плагин без кода — законная и частая вещь: манифест из десяти строк, поднимающий чужой MCP-сервер.

Каждый плагин работает отдельным процессом. Бесконечный цикл, утечка памяти или process.exit() внутри плагина убивают только его: ядро видит падение, снимает регистрацию его инструментов и продолжает работать.

Главный способ поставить что-то — вставить конфигурацию любого MCP-сервера в том виде, в каком она написана в его README. Своего формата у Axon нет намеренно: человек приходит с готовым куском JSON для Claude Desktop или VS Code, и заставлять его переписывать это в наши поля — верный способ сделать установку тем, чем никто не пользуется.

{ "mcpServers": { "everything": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-everything"] } } }

Каталог — это закладки на проверенные плагины и серверы, а не граница возможного. Он лежит в отдельном репозитории и пополняется без новой версии приложения; копия едет и в сборке, поэтому раздел не пустует без интернета.

axon plugin catalog              # что есть в каталоге
axon plugin add github           # поставить из каталога
axon plugin add-mcp конфиг.json  # свой MCP-сервер (или конфиг на stdin)
axon plugin add https://…        # поставить из репозитория
axon plugin link ./my-plugin     # подключить папку как есть (разработка)
axon plugin logs my-plugin       # что он печатает

Как написать свой — packages/plugin-sdk/README.md, рабочий пример — examples/hello-plugin.

Картинки

Зрение — свойство модели, а не провайдера: у одного провайдера одновременно бывают и обычные модели, и vision. Поэтому таблицы «этот провайдер умеет картинки» в Axon нет — она была бы и неверной, и протухающей: модели выходят чаще, чем обновляется ядро.

Вместо неё — отдельная модель для распознавания, которую выбирают в настройках. Она описывает вложение один раз, описание остаётся в переписке текстом, и дальше с ним работает основная модель — любая, включая текстовую.

Побочный выигрыш важнее удобства: картинка стоит токенов один раз, а не переотправляется на каждом следующем ходу до конца разговора.

Скиллы и бюджет токенов

Скилл — инструкция текстом, и раскрывается она в два шага. В контексте постоянно висит только строка «есть скилл X, он про Y» — десяток токенов. Тело, которое может быть на пять страниц, модель забирает сама инструментом read_skill, и только когда оно правда понадобилось.

Разница на практике: двадцать поставленных скиллов стоят ~300 токенов в каждом запросе вместо ~20 000. Тот же приём, что и deferred у инструментов, — применённый к знаниям вместо действий. По той же причине инструменты MCP-серверов регистрируются deferred: их схемы длинные, а серверов бывает несколько.

Установка ядра

Ядро — самостоятельная программа. Ставится на любую машину с Node 22.5+, нативных модулей нет, компилятор не нужен.

npm install -g @axon-assistant/core
axon start                      # слушает 127.0.0.1:8787, фоном
axon start --host 0.0.0.0       # ещё и для устройств из сети

--host — это интерфейс, который ядро слушает, а не список разрешённых гостей. По умолчанию 127.0.0.1: снаружи такое ядро не видно вовсе. Указали конкретный адрес — работать будет только он; чтобы пускать всех, слушают 0.0.0.0. Ядро само напечатает, по каким адресам оно видно с других машин.

Ядро уходит в фон само: печатает адрес и код, отдаёт терминал и работает дальше. Закрытая сессия SSH его не убьёт. Вывод уходит в axon.log рядом с данными, остановить — axon stop, посмотреть — axon status.

Чтобы ядро поднималось после перезагрузки, на Linux достаточно юнита systemd:

# /etc/systemd/system/axon.service
[Unit]
Description=Axon
After=network.target

[Service]
ExecStart=/usr/bin/axon start --host 0.0.0.0 --foreground
Environment=AXON_DATA_DIR=/var/lib/axon
User=axon
Restart=on-failure

[Install]
WantedBy=multi-user.target

--foreground здесь обязателен: фоном процесс держит systemd, и уход в фон он воспримет как падение сразу после запуска.

При первом запуске ядро печатает код для подключения первого устройства и кладёт его в bootstrap.code рядом с данными — код сгорает после первого использования. Дальше вводите его в приложении.

Код одноразовый и сгорает даже от неудачной попытки, поэтому новый берут командой на самой машине:

axon code                  # полные права, живёт пять минут
axon code --chat --ttl 60  # только переписка, на минуту

Право спросить доказывается доступом к файлу control.token рядом с базой: тот, кто может прочитать его, и так может прочитать саму базу с ключом шифрования секретов.

axon doctor                                     # осмотр: что настроено и что сломано
axon status                                     # запущено ли и где
axon secret set provider.anthropic.apiKey sk-…  # ключ провайдера
axon secret list                                # что задано (значения не показываются)
axon devices                                    # подключённые устройства
axon stop

Папка данных задаётся переменной AXON_DATA_DIR; по умолчанию — стандартная папка приложений вашей ОС. Внутри лежит всё: база, блобы и ключ шифрования секретов. Переносится копированием.

Через интернет ядро стоит выставлять только за туннелем или обратным прокси с TLS: своего шифрования у него нет намеренно — это работа отдельного слоя.

Разработка ядра из репозитория

npm install && npm run build
node packages/daemon/dist/cli.js start

Десктоп

Установщик для Windows — на странице релизов. Ставить ядро отдельно не нужно: оно уложено внутрь и запускается само.

Установщик не подписан — сертификат стоит денег и требует юридического лица. Windows покажет синее окно SmartScreen: «Подробнее» → «Выполнить в любом случае». Это не обход защиты, а то, что она делает с любой программой без подписи.

Приложение поднимает ядро дочерним процессом на свободном порту и подключается к нему как обычное устройство — по тому же протоколу, что и любой другой клиент. Токен сохраняется в device.json в папке приложения. Ядро переживает выход приложения: рутины и Telegram продолжают работать с закрытым окном.

Из репозитория:

cd apps/desktop
npm run dev        # рендерер на vite + electron
npm run dist       # установщик в apps/desktop/release

Разработка

npm install
npm run build       # tsc --build по всем пакетам
npm run typecheck
npm test

Нужен Node 22+.

Документация

Лицензия

MIT — см. LICENSE.

About

Персональный AI-агент: ядро на своей машине, клиенты подключаются к нему

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages