Перенос документации ИКС в Gramax

трудозатраты	экономический эффект
10 часов работы над оптимизацией скриптов и отладкой промптов и приемкой результата	вместо примерно полутора месяцев работы специалистов технической поддержки по ручному переносу статей.
примерно 25 часов работы агента с локальной моделью	результат нуждается в ручной проверке и небольших корректировках, примерно на 8 часов рабочего времени

Документация межсетевого экрана ИКС раньше хранилась в Wiki, но руководство компании поставило задачу по переносу ее в инструмент Gramax. Основная цель - работа с версиями документов, хранение их в git, и самое главное ИИ поиск по документам.

Что было сделано

развернут локальный Gramax docportal.
с помощью алгоритмической части и использования агента OpenClaw выполнен перенос документов с сохранением структуры, внутренних ссылок, иллюстраций.
выполнена верификация полученной структуры

Как переносилась документация

Сначала с помощью большого Qwen 3.7 Plus был разработан скрипт, который алгоритмически изучает всю ветку документации на существующем сервере и строит ее карту для агента.В нашем конкретном случае, большому квену была показана структура документации, чтобы парсер ее мог быстрее и без ошибок построить карту. Парсер на Python + BeautifulSoup. Работает в два этапа:

Рекурсивный обход <ul>/<li>/<details> для построения дерева категорий
Сканирование каждой категории для поиска всех статей через универсальный поиск ссылок ?article=N

Фрагмент карты выглядит так:

    {
      "id": "article_277",
      "type": "article",
      "title": "Выход из веб-интерфейса",
      "url": "https://doc.a-real.ru/index.php?article=277",
      "parent_id": "category_16",
      "level": 2,
      "order": 7,
      "children_ids": []
    },
    {
      "id": "category_29",
      "type": "category",
      "title": "Пользователи",
      "url": "https://doc.a-real.ru/index.php?category=29",
      "parent_id": "category_18",
      "level": 2,
      "order": 1,
      "children_ids": [
        "article_124",
        "article_130",
        "article_131",
        "article_132",
        "article_137",
        "article_142"
      ]
    },

То есть были определены все компоненты документации, их родительские и подчиненные элементы, представляющие собой полную структуру. Структура я проверил отдельным скриптом и выборочно руками. После этого можно было работать дальше. (Хотя один раз пришлось вернуться обратно и перестроить карту, чтобы поле order было локальным - внутри родительской категории, а не глобальным. Это обнаружилось на следующем этапе.

Дальше был разработан скрипт orchestrator.py, который перебирает все компоненты карты документации, категории создает сам, делая под каждую каталог нужного уровня вложенности и создавая файл _index.md, а в случае статьи вызывает агента OpenClaw, который уже загружает html код каждой статьи и превращает ее в md файл, расположенный в нужном каталоге.

Пришлось вручную поэкспериментировать со структурой и содержанием репозитория Gramax, поскольку документация по нему пока не полная. Это для того, чтобы в статьях и _index.md был размещен корректный frontmatter.

Принципы обработки статей были описаны для агента в файле SKILL.md.

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

 I'll start by reading the SKILL.md to understand the exact process, then fetch the article 
HTML.Good, HTML downloaded (65250 bytes). Now let me parse the content.The content is in 
`<div class="ticket ticket--article">`. Let me extract the body content properly.Good, I 
have the full body. Now let me process everything: extract content, download images, create 
the markdown file.All images are valid PNGs. Now let me compute the relative path for images. 
SECTION_PATH = `telefoniya` has 1 `/`, so N = 1+1 = 2 levels up: `../../images/article_101/`. 
Now create the markdown file.```json
{
 "status": "success",
 "id": "article_101",
 "type": "article",
 "file_path": "telefoniya/xphone.md",
 "images_downloaded": 21,
 "content_length": 11404,
 "warnings": []
}

Дальше мы занялись постобработкой

После первого прогона оркестратора возникли проблемы, которые потребовали отдельного этапа.

Для диагностики создали скрипт: audit.py. Он находит 7 типов проблем (которые перед этим пришлось скрупулезно описать большому Квену):

Недостающие файлы – по id в frontmatter (а не по пути, потому что файлы уже были переименованы в нормальный вид, не article_204.md, а nastroyka-autentifikacii-polzovatelej.md)
Дублирующиеся заголовки – если Title совпадает с title из frontmatter
Некорректные ссылки – внешние URL на doc.a-real.ru и битые внутренние
Дублирующийся текст – повторение абзацев в начале статьи
Блоки “Источник” со ссылкой на внешний ресурс, которые были явно лишние
Битые пути к изображениям
Отсутствие саммари в _index.md

Работа над ошибками

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

Алгоритмические исправления:

Удаление дублей заголовков (регулярки)
Удаление блоков “Источник”
Замена внешних ссылок на относительные пути к .md-файлам
Исправление путей к картинкам
Добавление списка дочерних статей в _index.md
Удаление дублирующегося текста

А вот для создания недостающих статей и генерации саммари во все _index.md снова использовался агент.

Статистика результата:

~270 объектов в структуре (категории + статьи)
~220 Markdown-файлов
~150 каталогов
~ 450 изображений
Все внутренние ссылки – относительные, ведут на локальные .md-файлы
Все _index.md содержат саммари и список дочерних элементов
Все статьи имеют корректный frontmatter с id, title, section, parent_id, level, order

Разработанная система полностью автоматизирована и может быть применена к другим источникам документации – достаточно адаптировать парсер HTML и шаблоны промптов.