Что я сделал за две недели...
Введение
MacsArt GPT — это полностью локальная платформа с искусственным интеллектом, которая работает на вашем компьютере и хранит все данные только у вас. Проект сочетает в себе:
- Простоту и безопасность для конечного пользователя.
- Масштабируемую микросервисную архитектуру, гибкую CLI‑оболочку и готовность к будущему web‑интерфейсу.
1. Что это и зачем
Для «чайника»
- Вы запускаете программу на своём Mac (или другом компьютере) — и получаете «умного ассистента», который:Отвечает на вопросы.Хранит и ищет ваши документы.Делает заметки и запоминает информацию.Позволяет подключать дополнительные «плагины» для любых задач.
- Преимущество: никакой сторонней «облака» или передачи данных в интернет — всё остаётся дома, у вас.
Для технаря
- Локально запускаемые LLM (Large Language Models).
- Микросервисная архитектура: каждый функциональный блок — свой сервис, общение по HTTP/gRPC.
- CLI‑клиент почти на 100 % покрывает весь API (95,5 %), есть задумка про web‑UI.
- Полное логирование с цветами, эмодзи, прогресс‑барами и таймстемпами.
2. История развития
MVP (первые 2 недели)
- Запуск: примерно 2 недели назад.
- Что было: базовый чат с LLM, загрузка файлов, минимальный CLI.
- Ограничения: почти без тестов, монолитная структура, мало API‑эндпоинтов.
Пост‑MVP (нынешний этап)
- Рефакторинг: разбили монолит на микросервисы по доменам (чаты, документы, память и др.).
- CLI: реализовали полноценное меню, сценарии, обработку ошибок, UX‑улучшения.
- API‑расширение: добавили эндпоинты для памяти, RAG (retrieval‑augmented generation), плагинов, ролей, инструкций.
- Тестирование: появились e2e‑, интеграционные и модульные тесты, Test‑центр для их запуска.
- Документация: подробные мануалы по каждому модулю и API.
3. Архитектура и модули
Основные модули и что они делают
🔹 Chat API
Простыми словами: Общение с ИИ
Технически: Сессии, генерация ответа LLM, кеширование
🔹 Files API
Простыми словами: Загрузка и поиск документов
Технически: Версионирование, full-text и семантический поиск
🔹 Memory API
Простыми словами: Долговременное хранение знаний
Технически: Векторная база, статистика, семантический поиск
🔹 Notes API
Простыми словами: Личные заметки
Технически: CRUD-операции, архивирование, теги
🔹 Roles API
Простыми словами: Управление правами пользователейТехнически: RBAC, ACL (роль- и политика-основанный доступ)
🔹 Instructions API
Простыми словами: Пользовательские инструкции и подсказки
Технически: Шаблоны, версионирование, управление контекстами
🔹 Plugins API
Простыми словами: Подключение внешних расширений
Технически: Загрузка, sandbox-исполнение, интерфейс управления
🔹 RAG API
Простыми словами: Подтягивание контекста из документов
Технически: Ингестинг, поиск по базе, генерация ответа с учётом внешнего знания
🔹 Cognitive Router
Простыми словами: Умный выбор модели или сервиса под задачу
Технически: Анализ намерений пользователя, роутинг запросов
🔹 Cognitive Traces
Простыми словами: Трассировка «мыслей» ИИ
Технически: Логика рассуждения, сбор метрик, цепочка вызовов
Вспомогательные сервисы
🔸 Логирование
Простыми словами: Запись всего, что происходит в системе
Технически: Цветные логи, эмодзи, прогресс-бары, таймстемпы
🔸 Test-центр
Простыми словами: Централизованный запуск всех тестов
Технически: E2E, интеграционные и модульные тесты, отчёты, CLI-интерфейс
🔸 Генератор тестовых данных
Простыми словами: Наполнение базы фейковыми данными
Технически: Python-скрипты, фикстуры, генерация под разные сценарии
4. Тестирование
Для пользователя
- Одной командой можно проверить, что все функции работают.
- Получаете понятный отчёт — «всё зелёное» или «где сломалось».
Для технаря
- E2E‑тесты: от CLI до LLM и обратно, покрывают полный сценарий.
- Интеграционные: проверяем взаимодействие микросервисов.
- Модульные: юнит‑тесты утилит и библиотек.
- Test‑центр: запускается через CLI, выводит цифры покрытия, логи и метрики.
5. Документация и стандарты
- README.md — быстрый старт и обзор проекта.
- API_INTEGRATION_AUDIT.md — отчёт по покрытию CLI (95,5 %).
- ARCHITECTURE_AUDIT.md — эволюция архитектурных решений.
- BACKEND_DEVELOPMENT_PLAN.md — дорожная карта.
- ASSISTANT_CONTROL.md — правила и чек‑листы для разработки ассистента.
- CHANGELOG.md — история изменений в шаблоне «дата – что сделано».
- IDEAS_AND_TASKS.md — бэклог и новые фичи.
6. Ключевые достижения
- Переход от монолита к микросервисам.
- CLI‑клиент с почти 100 % API‑покрытием.
- Настройка расширенного логирования.
- Создание Test‑центра с автоматическим запуском e2e‑ и интеграционных тестов.
- Добавление RAG, плагинов, когнитивных трасс и ролей.
- Документирование каждой детали.
7. Статистика кода
- Файлов: ~500+
- Строк кода (приблизительно):
- Backend (Python): 25 000
- Frontend (TS/React): 5 000
- Тесты: 7 000
- Документация: 6 000
- Скрипты/утилиты: 2 000— Итого: ≈ 45 000 строк
- Покрытие тестами: > 90 % ключевых сценариев.
8. Сложности и уроки
- Рефакторинг: разбиение монолита, миграция данных.
- CLI ↔ API: унификация, UX‑улучшения, обработка ошибок.
- Продвинутое логирование: кастомные форматтеры, emoji, прогресс‑бары.
- Тестирование «в реальности»: генерация и управление фикстурами.
- Документирование: держать всё в актуальном состоянии.
9. Текущее состояние и планы
Сейчас
- CLI готовится к production, все модули протестированы. Пилю ошибки.
- Документация и тесты актуальны.
В планах
- Доработать оставшиеся эндпоинты (2 в Files API, 1 в Chat API).
- «Chunked upload» для больших файлов.
- Улучшить отправку сообщений через отдельный endpoint.
- Новый web‑интерфейс.
- Интеграция с внешними LLM и сервисами.
- Оптимизация производительности и UX.
10. Интересные факты
- За 2 недели написано и протестировано более 40 000 строк кода.
- В системе 89+ эндпоинтов, почти все доступны через CLI.
- 100+ e2e и интеграционных тестов гарантируют надёжность.
- Логирование — одно из самых «живых» среди локальных AI‑платформ (цвета, эмодзи, прогресс‑бары).
- Полная приватность: никакого облака, всё локально.
MacsArt GPT — ваш надёжный AI‑помощник: понятный «чайнику» и гибкий «под капотом» для технаря. И он только начинает свой путь!
Оставайтесь на связи, дальше будет интересней.