nodebb-plugin-integration 0.4.2 → 0.5.0

package/README.ru.md

@@ -1,347 +1,199 @@
-# NodeBB Integration Layer
-
-AI-слой интеграции для форумов NodeBB с поддержкой MCP, семантического поиска, RAG pipeline и векторного хранилища Qdrant.
-
-## Возможности
-
-* Интеграция с NodeBB
-* MCP (Model Context Protocol) сервер
-* Семантический поиск по содержимому форума
-* RAG pipeline (Retrieval Augmented Generation)
-* Поддержка Qdrant Vector Database
-* Поддержка OpenAI Embeddings
-* Локальный режим с fake embeddings
-* Работа без NodeBB для разработки
-* Автоматические тесты через GitHub Actions
-
-# Архитектура
-
-```
-                 NodeBB
-
-                   |
-                   |
-
-          Integration Layer
-
-                   |
-
-      +------------+------------+
-
-      |                         |
-
-     MCP                       AI
-
-      |                         |
-
-   Tools API              Embeddings
-
-                                  |
-
-                                Qdrant
-
-                                  |
-
-                           Knowledge Base
-```
-
-# Требования
-
-Минимально:
-
-* Node.js >= 20
-* npm >= 10
-
-Опционально:
-
-* NodeBB
-* Redis
-* Qdrant
-* OpenAI API
-
-# Установка
-
-Клонирование:
-
-```bash
-git clone https://github.com/Sergey-ek/nodebb-plugin-integration.git
-
-cd nodebb-plugin-integration
-```
-
-Установка зависимостей:
-
-```bash
-npm install
-```
-
-Создание конфигурации:
-
-```bash
-cp .env.example .env
-```
-
-# Режим разработки
-
-По умолчанию используется локальный генератор векторов:
-
-```
-AI_PROVIDER=fake
-```
-
-Этот режим позволяет запускать проект без:
-
-* OpenAI API
-* Qdrant
-* NodeBB
-
-Проверка конфигурации:
-
-```bash
-npm run diagnose
-```
-
-Пример:
-
-```
-{
- environment: "development",
-
- embeddings:
- {
-   provider: "fake",
-   size: 1536
- }
-}
-```
-
-# Тестирование
-
-Проверка синтаксиса:
-
-```bash
-npm run check
-```
-
-Запуск тестов:
-
-```bash
-npm test
-```
-
-Ожидаемый результат:
-
-```
-8 passing
-```
-
-# Интеграция с NodeBB
-
-Настройка:
-
-```
-NODEBB_URL=http://localhost:4567
-
-NODEBB_API_KEY=your_token
-```
-
-При работе внутри NodeBB используются оригинальные модули NodeBB.
-
-В standalone режиме используются безопасные адаптеры:
-
-```
-NodeBB отсутствует
-
-        |
-
-Fallback adapter
-
-        |
-
-Тесты продолжают работать
-```
-
-# AI Pipeline
-
-Полный поток:
-
-```
-Сообщение форума
-
-        |
-
-Создание embedding
-
-        |
-
-Сохранение vector
-
-        |
-
-Qdrant similarity search
-
-        |
-
-Получение контекста
-
-        |
-
-AI ответ
-```
-
-# Embeddings
-
-## Fake режим
-
-Для разработки:
-
-```
-AI_PROVIDER=fake
-```
-
-Плюсы:
-
-* бесплатно;
-* быстро;
-* не требует сети;
-* используется в тестах.
-
-## OpenAI режим
-
-Настройка:
-
-```
-AI_PROVIDER=openai
-
-OPENAI_API_KEY=your_key
-```
-
-# Qdrant
-
-Конфигурация:
-
-```
-QDRANT_URL=http://localhost:6333
-
-QDRANT_COLLECTION=nodebb_knowledge
-```
-
-Автоматически выполняется:
-
-* проверка коллекции;
-* создание коллекции;
-* загрузка векторов;
-* поиск похожих документов.
-
-# MCP сервер
-
-Запуск:
-
-```bash
-npm run mcp
-```
-
-Доступные инструменты:
-
-```
-get_forum_info
-
-get_post
-
-get_topic
-
-get_user
-
-search_knowledge
-```
-
-Пример поиска:
-
-```
-search_knowledge
-
-{
- "query": "как установить NodeBB",
- "limit": 5
-}
-```
-
-# Структура проекта
-
-```
-.
-
-├── library.js
-
-├── package.json
-
-├── plugin.json
-
-
-├── src
-
-│
-
-├── ai
-
-│   ├── embeddings.js
-
-│   ├── openai.js
-
-│   ├── qdrant.js
-
-│   ├── indexer.js
-
-│   └── search.js
-
-
-│
-
-├── mcp
-
-│   ├── server.js
-
-│   └── tools.js
-
-
-│
-
-├── nodebb
-
-│   ├── meta.js
-
-│   ├── posts.js
-
-│   ├── topics.js
-
-│   └── users.js
-
-
-│
-
-└── config
-
-    └── index.js
-
-
-└── test
-
-    └── plugin.test.js
-```
-
-# Безопасность
-
-Не добавлять в Git:
-
-```
-.env
-
-OPENAI_API_KEY
-
-NODEBB_API_KEY
-
-```
-
-# Лицензия
-
-MIT
+# NodeBB Integration Layer
+
+Плагин интеграции с форумами NodeBB, предоставляющий MCP (Model Context Protocol), семантический поиск на базе AI, RAG-поиск и хранение векторов в Qdrant.
+
+## Возможности
+
+- Интеграция с NodeBB
+- MCP-сервер с транспортом Streamable HTTP
+- Отдельный дочерний процесс MCP под управлением NodeBB
+- Аутентификация MCP-клиентов по Bearer Token
+- Внутренняя аутентификация API между MCP и NodeBB
+- Генерация embeddings через OpenAI
+- Хранение векторов и семантический поиск в Qdrant
+- RAG-поиск с проверкой прав доступа NodeBB
+- Индексация каждого сообщения отдельно, включая ответы
+- Настройка исключённых категорий
+- Режимы AI-провайдера OpenAI и Fake
+- Интерфейс настройки в ACP
+- Автоматизированные тесты
+
+## Архитектура
+
+NodeBB → Integration Plugin → MCP / AI
+
+MCP: Streamable HTTP → MCP Child Process → Internal NodeBB API → NodeBB Access Control
+
+AI: OpenAI → Embeddings → Qdrant → Vector Search → Knowledge Retrieval
+
+## Требования
+
+- Node.js >= 20
+- npm >= 10
+- NodeBB 4.x
+
+Для работы AI необходимы API-ключ OpenAI и сервер Qdrant. Для работы MCP необходим запущенный экземпляр NodeBB.
+
+## Установка
+
+Установите плагин через интерфейс управления плагинами NodeBB или используйте обычную процедуру установки плагинов.
+
+Установите зависимости командой npm install в каталоге плагина.
+
+Перезапустите NodeBB и откройте настройки плагина: ACP → Plugins → NodeBB Integration.
+
+## Настройка
+
+Плагин настраивается через интерфейс ACP NodeBB.
+
+### AI-провайдер
+
+Доступны два режима.
+
+**OpenAI**
+
+Включает:
+- Генерацию embeddings через OpenAI
+- Хранение векторов в Qdrant
+- Индексацию сообщений
+- Семантический поиск
+- RAG-поиск
+
+Настраиваются API-ключ OpenAI, модель и размерность embeddings, URL Qdrant и имя коллекции.
+
+**Fake**
+
+Полностью отключает функциональность AI:
+- API OpenAI не вызывается.
+- Qdrant не используется.
+- Embeddings не создаются.
+- Индексация сообщений отключена.
+- Семантический поиск отключён.
+
+Интеграция с NodeBB и MCP продолжают работать.
+
+Настройки OpenAI и Qdrant сохраняются при переключении провайдеров. Повторный выбор OpenAI снова включает AI-конвейер.
+
+Режим Fake предназначен для разработки и тестирования интеграции NodeBB и MCP без внешних AI-сервисов.
+
+### Исключённые категории
+
+Категории, выбранные в ACP, исключаются из AI-индексации и семантического поиска.
+
+## AI-конвейер
+
+При включённом OpenAI обработка выполняется следующим образом:
+
+Сообщение форума → Генерация Embeddings → Сохранение векторов в Qdrant → Семантический поиск → Проверка прав доступа NodeBB → Получение содержимого сообщений
+
+Каждое сообщение индексируется отдельно, включая ответы.
+
+Результаты поиска проверяются на соответствие правам NodeBB до получения содержимого сообщений. Сообщения и темы, недоступные сервисному пользователю, исключаются из результатов.
+
+Qdrant хранит только векторы и метаданные. Текст сообщений извлекается из NodeBB после проверки прав доступа.
+
+## Qdrant
+
+Через ACP задаются URL Qdrant, имя коллекции и размерность векторов.
+
+Плагин проверяет наличие коллекции и создаёт её при необходимости.
+
+При выборе Fake обращения к Qdrant не выполняются.
+
+## MCP-сервер
+
+MCP-сервер управляется плагином NodeBB и работает в отдельном дочернем процессе.
+
+Транспорт:
+- Streamable HTTP
+- Аутентификация Bearer Token
+
+MCP-сервер взаимодействует с NodeBB через защищённый внутренний API. Для него используется отдельный секрет, управляемый плагином.
+
+В ACP настраиваются:
+- Включение и отключение MCP
+- Адрес привязки
+- Порт
+- URL NodeBB
+- Bearer Token
+- UID сервисного пользователя
+
+UID сервисного пользователя задаётся администратором. MCP-клиенты не могут его переопределять.
+
+### Доступные инструменты
+
+- get_forum_info — Получение общедоступной информации о форуме.
+- get_post — Получение сообщения после проверки прав доступа.
+- get_topic — Получение темы после проверки прав доступа.
+- get_user — Получение общедоступной информации о пользователе.
+- search_knowledge — Поиск по проиндексированным данным форума.
+
+Для search_knowledge необходим провайдер OpenAI. В режиме Fake инструмент возвращает явную ошибку о выключенном AI.
+
+## Безопасность
+
+- MCP-клиенты проходят аутентификацию по Bearer Token.
+- Внутренние API-запросы используют отдельный секрет.
+- Секреты не возвращаются в интерфейс ACP.
+- Пустые поля секретов сохраняют ранее заданные значения.
+- Идентификаторам пользователей, переданным MCP-клиентами, не доверяют.
+- Для проверки прав используется настроенный сервисный пользователь.
+- Права на сообщения и темы проверяются до возврата содержимого.
+- При ошибке проверки доступа доступ запрещается.
+- Payload Qdrant содержит идентификаторы и метаданные, но не текст сообщений.
+
+Не добавляйте API-ключи, токены и другие секреты в систему контроля версий.
+
+## Разработка и тестирование
+
+Установка зависимостей: npm install
+
+Проверка синтаксиса: npm run check
+
+Запуск тестов: npm test
+
+
+Тесты проверяют конфигурацию, аргументы MCP-инструментов и другие компоненты плагина.
+
+## Структура проекта
+
+library.js
+package.json
+plugin.json
+public/
+  js/admin.js
+  templates/admin/plugins/integration.tpl
+src/
+  ai/
+    embeddings.js
+    indexer.js
+    openai.js
+    qdrant.js
+    search.js
+  config/
+    index.js
+    validation.js
+  events/
+    index.js
+  mcp/
+    manager.js
+    server.js
+    tools.js
+  nodebb/
+    categories.js
+    index.js
+    meta.js
+    posts.js
+    privileges.js
+    topics.js
+    users.js
+  routes/
+    api.js
+    index.js
+test/
+  config-validation.test.js
+  mcp-tools.test.js
+
+## Лицензия
+
+MIT