Автоматизируйте проверку качества вашей документации!

Представляем вашему вниманию инструмент для поиска битых ссылок в документации репозиториев. Скрипт идеально интегрируется с агентами ИИ, позволяя полностью автоматизировать процесс исправления ссылок.

Этот инструмент разработан в рамках методологии работы с малыми языковыми моделями (Small Language Models, SLM) для AI Engineering Handbook. Он написан исключительно с использованием стандартных библиотек Python и предназначен для проверки документации в формате Markdown (хотя легко адаптируется под любые текстовые файлы).

Это не просто утилита — это профессиональное решение для автоматизации рутинного обслуживания с помощью агентов ИИ, таких как aider.

💡 Решаемая проблема

Документация быстро устаревает: файлы перемещаются, относительные пути нарушаются. Ручная проверка сотен файлов в эпоху автоматизации — непозволительная трата времени инженеров.

⚙️ Решение: md_check_broken_links.py

Скрипт построен на принципах «Самой малой жизнеспособной архитектуры» (Smallest Viable Architecture, SVA) и использует только стандартные библиотеки Python (pathlib, re, argparse), что гарантирует его переносимость на любые платформы с Python 3.x.

Ключевые возможности:

✅ Проверка только локальных ссылок: Внешние ссылки (HTTP/S) игнорируются для повышения скорости и релевантности проверок.

✅ Интеллектуальная фильтрация: Автоматическое исключение внутренних якорей и однословных ссылок (например, часто встречающейся в примерах кода ссылки args), не являющихся путями к файлам.

✅ Структурированная отчётность: Чёткий машинно-читаемый вывод с указанием файла и точного местоположения каждой битой ссылки.

🤖 Рабочий процесс агента: Автоматическое исправление ссылок

Настоящая ценность скрипта раскрывается при его использовании в качестве тестовой обвязки для ИИ-агентов, генерирующих код. Агент обрабатывает вывод скрипта как задачи для выполнения:

1. Запуск скрипта:

python3 md_check_broken_links.py

2. Анализ результатов: Чтение отчётов об ошибках (например: BROKEN LINK: File 'X' contains broken link: Y)

3. Исправление ссылок: Открытие файла X и замена неверной ссылки Y на корректный путь

4. Повторная валидация: Циклический запуск скрипта до получения финального сообщения: ✅ All links are valid!

Примечание: Для корректной работы агенту требуется актуальная структура репозитория. Рекомендуется использовать команду /run tree --gitignore (требуется установка пакета tree).

Такой подход позволяет делегировать ИИ рутинные задачи, освобождая разработчиков для решения нетривиальных инженерных проблем.

🔗 Где взять скрипт

Полный исходный код и инструкции по использованию доступны в разделе helpers/scripts репозитория. Для адаптации под ваш проект достаточно скорректировать параметры --exclude-dirs и --exclude-files в функции main (примечание: скрипт сохраняет работоспособность даже без изменений).

#aider #Python #MLOps #Markdown #ai_engineering_handbook