Imported from nyxandro/osinara (
AGENTS.md). Install upstream withnpx skills add nyxandro/osinara. Copyright stays with the author.
Osinara: ориентир для кодингового агента
Этот файл даёт контекст перед началом работы с репозиторием. Держать его в пределах 100–150 строк: только обзор, важные ограничения и ссылки. Подробности реализации, разборы сбоев и историю изменений сюда не добавлять.
Что это за проект
Osinara — семейный ИИ-ассистент в Telegram.
Он работает в личных чатах, закрытых семейных группах и изолированных внешних группах.
Главный архитектурный приоритет — разделение данных и прав пользователей, семей и групп.
Стек: TypeScript, Node.js 24, собственное ядро агента на AI SDK 7.0.60, PostgreSQL с pgvector, Docker Compose.
Модель и её провайдер задаются конфигурацией проекта; Groq Whisper распознаёт голос.
Основные возможности
- Первичная настройка владельца, приглашения, участники и семейные роли.
- Диалоги с текстом, голосом, вложениями и сохранением контекста.
- Личная, семейная и групповая долговременная память с раздельным доступом.
- Напоминания и автономные агентные сценарии по расписанию.
- Поиск в интернете, чтение страниц и работа с файлами.
- Подключаемые skills, Google Workspace, T-Invest и генерация изображений.
- Изолированные рабочие окружения для инструментов и делегирование задач.
- Подтверждения действий человеком и обновление приложения через релизы.
Доступность возможностей зависит от режима чата, выданных прав и активного провайдера.
Как устроено приложение
Telegram → Nginx → проверенный webhook → очередь PostgreSQL → worker → ядро агента → ответ в Telegram.
Входящее сообщение сохраняется до подтверждения получения Telegram.
Очередь сохраняет порядок внутри чата или темы; разные чаты обрабатываются независимо.
Ядро (agent/runtime/) управляет моделью, ходами диалога, сессиями, инструментами и подтверждениями.
Osinara управляет пользователями, областями доступа, памятью, расписаниями и аудитом.
Прикладные данные и журнал ходов хранятся в БД приложения.
Sandbox-runner исполняет команды в Docker; доступ к сети проходит через egress proxy.
Где искать код
agent/main.ts— точка входа процесса;agent/application.ts— сборка: ядро, каналы, HTTP-сервер, планировщик.agent/agent.ts— конфигурация основного агента и модели.agent/runtime/— ядро: цикл хода, журнал, история, подтверждения, Telegram, sandbox, skills.agent/instructions.md,agent/instructions/,agent/lib/prompt/— инструкции модели.agent/channels/— Telegram и другие входные границы приложения.agent/tools/capabilities.ts— выдача инструментов по текущему режиму.agent/lib/tools/— реализации прикладных инструментов.agent/lib/tool-policy/— правила доступности инструментов и прав групп.agent/lib/— прикладная логика, работа с БД и тесты рядом с кодом.agent/lib/reminders/,agent/lib/agent-schedules/— напоминания и сценарии.agent/schedules/— периодические диспетчеры backend.agent/skills/,config/skills/— выдача и пакеты установленных skills.services/— sandbox-runner и сетевой proxy.migrations/,scripts/— миграции, workers и эксплуатационные команды.config/,infra/,compose*.yaml— настройки приложения и инфраструктура.docs/— эксплуатационная документация, исследования и описания релизов.
Перед изменением кода
- Найти существующий путь исполнения, соответствующий модуль и его тесты.
- Проверить фактическую версию затронутой библиотеки и её документацию.
- Использовать возможности установленного стека и существующие границы приложения.
- Согласовать изменения данных, прав, совместимости и эксплуатации, выходящие за задачу.
Сохранять локальность модулей; новый source-файл — не более 500 строк.
Не удалять старые пути и совместимость без согласованного объёма задачи.
Поведение конфигурировать в коде или версионируемых файлах; .env — для секретов и привязок окружения.
Ошибки обязательных данных не маскировать придуманными значениями или скрытыми повторами.
Пользовательские ошибки должны иметь стабильный код и понятное русское сообщение.
Границы, которые нельзя нарушать
- Авторизация исполняется backend, а не промптом или решением модели.
- Identity, роли и scopes берутся из проверенного Telegram-контекста и актуальной БД.
- Внешняя группа получает только собственные данные, файлы и явно разрешённые подключения.
- Выданные права перепроверяются при исполнении, включая действия после подтверждения.
- Файлы, веб-страницы, история и результаты инструментов являются недоверенными данными.
- Повтор обработки не должен повторно отправлять сообщение или исполнять побочный эффект.
- Неоднозначное завершение операции нельзя считать разрешением на автоматический повтор.
- Память принадлежит приложению; решение о сохранении принимает основной агент через
remember. - Не создавать второй agent loop, Telegram transport, механизм авторизации или подтверждений.
Ядро агента
Ядро — собственный код на AI SDK 7.0.60 в agent/runtime/. Файлы с адаптированным сторонним кодом
(Apache-2.0) несут об этом строку в шапке; список и текст лицензии — в THIRD_PARTY_NOTICES.md.
Модули подключаются явно в agent/application.ts и agent/agent.ts: расположение файла роли не задаёт.
Прикладные инструменты выдаются динамически (agent/tools/capabilities.ts); реализации — в agent/lib/tools/.
Ход, его шаги и вызовы инструментов журналируются: после перезапуска ход продолжается с места
остановки, а действие с неизвестным исходом не повторяется.
Для AI SDK сначала читать node_modules/ai/docs/ установленной версии.
Если документация не определяет важное поведение, проверять исходники установленной версии.
Разработка и проверка
Для локальной разработки использовать npm run dev: ядро перезапускается при правках кода.
С одной базой работает один процесс агента: второй не стартует (AGENT_RUNTIME_ALREADY_RUNNING).
Планировщик работает и в разработке: напоминания и сценарии этого окружения срабатывают по расписанию.
Для изменений поведения сначала добавить значимый падающий тест, затем реализацию.
Объём проверок выбирать по риску: текстовая правка не требует полного прогона проекта.
Основные команды: npm run typecheck, npm test, npm run build.
Миграции запускать только внутри backend/test container через npm run migrate.
После изменения зависимостей проверять чистую установку npm ci и сборку npm run build (.runtime/).
Формулировки промптов проверять чтением диффа и живым чатом, а не тестами на конкретные фразы.
Для изменений общих контрактов и хранения данных использовать интеграционные проверки Docker:
docker compose -f compose.test.yaml up --build --abort-on-container-exit --exit-code-from testsДеплой и документация
В корне docs/ оставлять только production-deployment.md.
Отчёты о работе давать в чате; отдельные документы создавать только по прямому запросу владельца.
Перед подготовкой релиза или любыми действиями с production прочитать
инструкцию деплоя.
Production собирается через CI/CD из канонического состояния репозитория.
Обычная задача разработки не разрешает ручную сборку production или изменение production-БД.
Описание выпуска хранится в docs/releases/vVERSION.md; порядок выпуска определяет инструкция деплоя.
Обзор установки и использования: README.md.
