This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

CI/CD и автоматизация

В проекте MinerU MCP Server настроен полноценный цикл непрерывной интеграции и доставки (CI/CD), включающий линтинг кода, сборку Docker-образов с автотестами и автоматическую генерацию технической документации (Wiki) с использованием AI.

Ниже описаны три основных этапа автоматизации: статический анализ, сборка артефактов и генерация знаний.

1. Линтинг и статический анализ

Процесс линтинга запускается автоматически при создании Pull Request в ветку main. Он гарантирует соблюдение стандартов кодирования (PEP 8, ruff) и предотвращает попадание ошибок в основной код.

Конфигурация: .forgejo/workflows/lint.yml

Как это работает:

1. Триггер: событие pull_request на ветку main.
2. Среда: легкий контейнер python-3.11-slim.
3. Инструмент: Ruff — быстрый линтер и форматер Python.
4. Выход: отчет в формате GitHub Annotations (ошибки подсвечиваются прямо в PR).

# Пример команды из workflow
run: ruff check . --output-format=github

2. Сборка и публикация Docker-образа

Сборка Docker-образа является центральным элементом CI/CD. Она не только создает исполняемый контейнер, но и выполняет unit-тесты непосредственно внутри образа перед его публикацией.

Конфигурация: .forgejo/workflows/ci-cd.yml Dockerfile: Dockerfile

Триггеры запуска

• Push в main: Автоматическая сборка образа с тегом latest.
• Push тега v*: Сборка релизного образа с версией из тега (например, v0.2.5).
• Workflow Dispatch: Ручной запуск с возможностью указать кастомный тег.

Этапы пайплайна

1. Checkout: Получение исходного кода.
2. Docker Buildx: Настройка мультиплатформенной сборки и кэширования.
3. Registry Login: Авторизация в Forgejo Container Registry с помощью секрета REGISTRY_TOKEN.
4. Version Extraction: Извлечение версии приложения из pyproject.toml с помощью встроенного модуля tomllib.
5. Metadata Generation: Формирование тегов и OCI-лейблов через docker/metadata-action.
6. Build & Push:
   • Перед сборкой образа выполняется шаг RUN python -m pytest tests/ -v внутри Dockerfile.
   • Если тесты падают (см. раздел Тестирование), сборка прерывается, и образ не публикуется.
   • Успешный образ пушится в реестр git.maydayoffice.kz/maydayoffice/mineru-mcp-server.

3. Генерация Wiki через AI

Уникальная особенность проекта — автоматическое создание и обновление технической документации на основе актуального кода. Этот процесс использует инструменты из отдельного репозитория .ai-tools.

Конфигурация Workflow: .forgejo/workflows/wiki-gen.yml Скрипт генерации: .ai-tools/wiki-gen/generate_wiki.py

Архитектура процесса

Процесс состоит из трех ключевых этапов, выполняемых последовательно:

Шаг 1: Упаковка репозитория (Repomix)

Скрипт использует инструмент Repomix для создания единого сжатого XML-файла, содержащего структуру директорий и содержимое всех файлов репозитория.

• Это позволяет передать LLM полный контекст проекта без превышения лимитов токенов, связанных с чтением множества отдельных файлов.
• Команда запуска: npx -y repomix --style xml --compress ...

Шаг 2: Генерация структуры и контента (LiteLLM + LLM)

Используя локальную или облачную LLM (по умолчанию Qwen3.6-27B через прокси LiteLLM), скрипт выполняет два действия:

1. Генерация TOC (Table of Contents): LLM анализирует упакованный код и предлагает структуру документации (список страниц, их slug и фокус).
2. Параллельная генерация страниц: Для каждой страницы из TOC запускается отдельный запрос к LLM.
   • Контекст: Полный XML репозитория + список других страниц для формирования перекрёстных ссылок.
   • Инструкция: Написать страницу в Markdown, используя правила оформления ссылок (см. ниже).
   • Параллелизм: Используется threading.Semaphore для ограничения одновременных запросов (по умолчанию 4), чтобы не перегрузить LLM-прокси.

Шаг 3: Синхронизация с Forgejo Wiki

Сгенерированные Markdown-файлы копируются в локальный клон Wiki-репозитория и пушатся обратно в Forgejo.

• Проактивная проверка: Перед клонированием скрипт проверяет существование Wiki-репозитория через git ls-remote. Если Wiki не инициализирована, процесс останавливается с понятной ошибкой (см. test_wiki_init.py).
• Git Operations: Клонирование -> Копирование файлов -> git add -> git commit -> git push.

Правила генерации контента

Чтобы документация оставалась связанной и полезной, LLM инструктируется следовать строгим правилам при написании Markdown:

1. Перекрёстные ссылки:

   • При упоминании темы из другого раздела, необходимо использовать ссылку в формате [Название](slug).
   • Доступные слуги жестко заданы в промпте (например, overview, quick-start, architecture).

2. Ссылки на код:

   • При упоминании конкретного файла или функции, необходимо создавать активную ссылку на GitLab/Forgejo.
   • Формат файла: [путь/к/файлу.py](https://git.maydayoffice.kz/maydayoffice/mineru-mcp-server/src/branch/main/путь/к/файлу.py)
   • Формат функции: [func_name()](https://git.maydayoffice.kz/maydayoffice/mineru-mcp-server/src/branch/main/путь/к/файлу.py#L42-L58)

3. Запреты:

   • Не ссылаться на несуществующие файлы.
   • Не галлюнировать номера строк, если они не очевидны из контекста (лучше ссылаться на весь файл или функцию целиком).

Переменные окружения для Wiki-генерации

Для работы пайплайна требуются следующие секреты и переменные (настраиваются в Forgejo Project Settings):

Переменная	Описание	Источник
WIKI_LLM_MODEL	Название модели в LiteLLM	Qwen3.6-27B
WIKI_LITELLM_BASE	URL LiteLLM API	Секрет CI/CD
WIKI_LITELLM_API_KEY	Ключ доступа к LiteLLM	Секрет CI/CD
WIKI_TOKEN	Access Token с правами на запись в Wiki	Секрет CI/CD
AI_TOOLS_TOKEN	Токен для доступа к репозиторию .ai-tools	Секрет CI/CD

Интеграция с другими модулями

• Архитектура: CI/CD пайплайн напрямую зависит от структуры проекта (src layout) и наличия тестов в директории tests/.
• Тестирование: Результаты выполнения unit-тестов являются блокирующим условием для публикации Docker-образа.
• Конфигурация: Версия приложения, используемая в Docker-лейблах, берется из тех же источников, что и при локальном запуске (pyproject.toml).
• Руководство разработчика: Локальная разработка может имитировать шаги CI (запуск линтера и тестов), но генерация Wiki обычно выполняется только на сервере CI из-за необходимости доступа к LLM и Git-репозиториям.

Устранение неполадок CI/CD

Если пайплайн падает, проверьте следующие аспекты:

1. Ошибка линтинга: Посмотрите детали шага Lint Code. Обычно требуется запустить ruff check . --fix локально.
2. Падение тестов при сборке: Ошибка в коде или отсутствии зависимостей. См. раздел Устранение неполадок для частых ошибок (ImportError, Session ID).
3. Ошибка авторизации в Registry: Проверьте секрет REGISTRY_TOKEN в настройках репозитория.
4. Ошибка генерации Wiki:
   • Wiki not initialized: Выполните ручной запуск workflow Test Wiki Initialization из репозитория .ai-tools или инициализируйте Wiki вручную через интерфейс Forgejo.
   • LLM Timeout: Увеличьте таймауты в конфигурации LiteLLM или выберите более быструю модель.