Книга по программированию → навык AI Agent

Сразу разделите процесс на три слоя: PDF разбирается отдельно, Knowledge Base хранит проверяемые факты и источники, а Agent Skill описывает только порядок выполнения задачи. В течение первой недели сначала классифицируйте страницы, затем соберите небольшой индекс и только после этого оформляйте навык AI Agent. Полный текст книги имеет смысл помещать прямо в Skill лишь тогда, когда материал короткий, стабильный и почти не требует поиска.

Эта схема подходит вам, если вы:

• обрабатываете PDF с кодом, таблицами, схемами и отсканированными страницами;
• сравниваете полный текст внутри Agent Skill с поиском по Knowledge Base;
• планируете поддерживать несколько книг, редакций и версий библиотек;
• хотите, чтобы ответ AI Agent можно было вернуть к главе, странице и конкретному фрагменту.

Архитектура трёх слоёв

Преобразование «книга по программированию в профессиональный навык AI Agent» нельзя надёжно выполнить одной операцией импорта. У каждого слоя своя ответственность.

Слой PDF отвечает за извлечение. Здесь нужно понять, есть ли в документе настоящий текст, где находятся страницы-изображения, как устроены колонки и какие элементы являются кодом или таблицами.

Слой Knowledge Base отвечает за хранение и поиск. Он должен сохранять не только текст, но и происхождение фрагмента: название книги, редакцию, главу, страницу, язык, версию программного окружения и тип содержимого.

Слой Agent Skill отвечает за действие. Он определяет, когда навык активируется, какие знания нужно найти, в каком порядке выполнить шаги и как проверить результат. В спецификации навыков файл SKILL.md содержит метаданные и инструкции, а дополнительные материалы можно вынести в каталоги references/, scripts/ и assets/. (agentskills.io)

Отсюда следует главный принцип: Knowledge отвечает на вопрос «что утверждается в книге и где это написано», Skill — на вопрос «что делать с найденным знанием».

Диагностика PDF перед обработкой

До выбора парсера проверьте документ по страницам. Не определяйте тип книги только по расширению файла.

В текстовом PDF сначала используйте режим, который возвращает блоки и их координаты. Документация по извлечению показывает, что обычный текст не всегда совпадает с естественным порядком чтения, а режим блоков сохраняет ограничивающие прямоугольники и номер блока. Это позволяет обнаружить ситуацию, когда пример из правой колонки оказался раньше объяснения из левой. (pymupdf.readthedocs.io)

Практическая проверка выглядит так:

1. Откройте несколько страниц в исходном просмотрщике.
2. Извлеките текст с сохранением номеров страниц.
3. Сравните заголовки, абзацы и код с оригиналом.
4. Найдите повторяющиеся верхние и нижние колонтитулы.
5. Проверьте символы <, >, {, }, \, кавычки и отступы.
6. Сохраните результат как промежуточный слой, а не сразу как знания для агента.

Для каждой страницы полезно хранить примерно такую запись:

{
  "source_id": "book-001",
  "edition": "2025",
  "page": 148,
  "chapter": "Асинхронное выполнение",
  "content_type": "code",
  "text": "...",
  "extraction_method": "text",
  "review_status": "pending"
}

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

Сканирование и сложная вёрстка

Сканированную книгу не следует полностью отправлять на OCR

Сначала определите страницы, где обычное извлечение возвращает пустой или почти пустой результат. OCR нужен для страниц, которые целиком представлены изображением, не содержат извлекаемого текста или состоят из множества мелких графических объектов. Такой подход прямо рекомендуется в документации к OCR-обработке. (pymupdf.readthedocs.io)

Это важно по двум причинам.

Во-первых, OCR заметно дороже по времени. В официальной документации указано, что распознавание может быть примерно в 1 000 раз медленнее стандартного извлечения текста. Поэтому запуск OCR на всей книге без предварительной классификации создаёт лишнюю очередь обработки. (pymupdf.readthedocs.io)

Во-вторых, распознанный текст не равен исходному тексту. Для кода одна ошибка в символе уже меняет смысл:

• 0 и O;
• 1 и l;
• одинарные и обратные кавычки;
• дефис и длинное тире;
• == и =;
• фигурные скобки и скобки другого типа.

После OCR проверяйте не только читаемость абзацев, но и исполнимость примеров. Страница с кодом должна пройти отдельную проверку, даже если визуально распознанный текст выглядит аккуратно.

Таблицы и две колонки требуют отдельного контроля

Для сложных PDF можно использовать режимы, различающие обычное извлечение, анализ макета и OCR. Документация по обработке PDF описывает варианты auto, fast, hi_res и ocr_only; при этом извлечение таблиц требует режима анализа макета, а режим высокой точности может иметь проблемы с порядком элементов в многостолбцовых документах. (docs.unstructured.io)

Не смешивайте в один текстовый фрагмент:

• заголовок таблицы;
• строки и столбцы;
• сноску под таблицей;
• поясняющий абзац до таблицы;
• код, размещённый рядом с таблицей.

Лучше сохранить таблицу как отдельный элемент с полем text_as_html или эквивалентным структурированным представлением. Затем добавьте ссылку на исходную страницу. Иначе агент сможет найти правильное значение, но не поймёт, к какому столбцу оно относилось.

Трёхуровневая обработка содержимого

Разные части книги нельзя резать одинаковым способом. Объяснение, код и таблица имеют разные границы смысла.

Текстовые разделы

Для обычной прозы границей обычно служит раздел или подраздел. Заголовок должен оставаться вместе с несколькими последующими абзацами. Не отделяйте определение от условия, при котором оно действует.

Механическое разбиение через каждые несколько символов удобно для быстрой демонстрации, но плохо подходит для технических книг. В структурированном разбиении сначала определяются элементы документа, а уже затем слишком длинные элементы делятся на части. Вариант разбиения по заголовкам сохраняет границы разделов и может учитывать границы страниц. (docs.unstructured.io)

Программный код

Для кода минимальная единица должна включать:

1. назначение примера;
2. необходимые импорты;
3. входные данные;
4. сам код;
5. команду запуска;
6. ожидаемый результат;
7. версию языка, фреймворка или библиотеки;
8. ограничения и известные ошибки.

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

Связывайте код и объяснение через общий идентификатор:

{
  "unit_id": "ch04-example-03",
  "content_type": "code_example",
  "language": "python",
  "runtime": "указать подтверждённую версию",
  "source_pages": [148, 149],
  "prerequisites": ["..."],
  "expected_output": "...",
  "verification_command": "..."
}

Если версия не указана в книге, не угадывайте её. Запишите значение как неизвестное и потребуйте подтверждения перед выполнением.

Сравнение вариантов хранения

В середине проекта полезно зафиксировать, что именно вы собираетесь помещать в каждый слой.

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

Knowledge Base и Skill: разделение обязанностей

Knowledge Base должен возвращать не просто ответ, а доказуемый фрагмент. Для каждой единицы храните:

• название книги;
• автора или источник;
• редакцию;
• главу и подглаву;
• физическую страницу;
• тип содержимого;
• язык программирования;
• версию среды;
• метод извлечения;
• статус проверки;
• идентификатор родительского документа.

Документальные узлы в системах индексации обычно наследуют метаданные исходного документа и сохраняют отношения с ним. Это позволяет строить поиск не только по тексту, но и по происхождению фрагмента. (docs.llamaindex.ai)

Часть Skill должна быть короткой и операционной:

1. Определите тип запроса.
2. Найдите в Knowledge Base разделы с подтверждённой версией.
3. Покажите пользователю источник и страницу.
4. Если запрос требует кода, проверьте зависимости.
5. Выполните пример только в разрешённой среде.
6. Сравните фактический результат с ожидаемым.
7. При конфликте редакций остановитесь и запросите выбор версии.

Спецификация Agent Skills рекомендует держать основной файл компактным: для тела SKILL.md приводится ориентир менее 5 000 токенов и менее 500 строк, а подробные материалы предлагается выносить в отдельные файлы. Это ещё один аргумент против помещения туда целой книги. (agentskills.io)

Модель данных для цитирования

Качество ответа проверяется не количеством найденного текста, а способностью вернуть исходный контекст. Для ответа «как настроить очередь задач» агенту может понадобиться не один фрагмент, а связка:

• определение;
• пример;
• версия библиотеки;
• ограничение;
• ожидаемый вывод.

Поэтому храните связи между единицами:

concept → explanation → code_example → prerequisite → test_result

Если пользователь просит объяснение, агент использует первые два элемента. Если просит рабочий пример, добавляет код и зависимости. Если просит исправить ошибку, ищет ограничения и результат проверки.

Схема цитирования должна быть видна в ответе:

Источник: книга «...», глава 4, страницы 148–149,
редакция 2025 года, фрагмент ch04-example-03.

Номер страницы должен соответствовать оригиналу, а не внутреннему номеру массива. Некоторые программные библиотеки используют нумерацию страниц с нуля внутри API, тогда как пользователь видит нумерацию с единицы. Документация обработки PDF отдельно описывает нулевую индексацию страниц, поэтому преобразование нужно делать явно. (pymupdf.readthedocs.io)

Сценарий многоступенчатой сборки

Используйте следующий порядок.

Шаг 1. Зафиксируйте права и границы

Обрабатывайте только PDF, которым вы вправе пользоваться. Не пытайтесь обходить шифрование, ограничения копирования или защиту авторских прав. Если файл недоступен для разрешённой обработки, остановите pipeline и запросите легальный источник.

Шаг 2. Проведите инвентаризацию страниц

Для каждой страницы определите:

• есть ли извлекаемый текст;
• есть ли изображения;
• присутствуют ли таблицы;
• сколько колонок;
• есть ли код;
• требуется ли OCR.

Результат сохраните в машинно читаемом журнале.

Шаг 3. Запустите прямое извлечение

Сначала применяйте текстовый режим. Сохраняйте блоки, координаты, страницу и исходный идентификатор. Отдельно удаляйте повторяющиеся колонтитулы, но не удаляйте их без журнала преобразований.

Шаг 4. Обработайте только проблемные страницы

Для страниц без текста используйте OCR. Для таблиц и сложной вёрстки выбирайте режим анализа макета. Не полагайтесь на автоматический режим без выборочной проверки: он помогает выбрать стратегию, но не заменяет контроль оригинала. (docs.unstructured.io)

Шаг 5. Разметьте структуру

Назначьте элементы категорий title, paragraph, code, table, list, image, caption, warning. Код и таблицы не объединяйте с соседним текстом в один бессвязный фрагмент.

Шаг 6. Сформируйте Knowledge Base

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

Шаг 7. Создайте Skill

Опишите триггеры, последовательность поиска, правила цитирования, условия отказа и проверки. Вынесите длинные справочные материалы в references/, а проверяемые скрипты — в scripts/.

Шаг 8. Добавьте изолированное выполнение

Если агент запускает код, определите:

• допустимые команды;
• доступ к сети;
• лимит времени;
• файловую область;
• переменные окружения;
• разрешённые зависимости;
• способ удаления временных данных.

Права выполнения не должны следовать автоматически из факта, что фрагмент найден в книге.

Шаг 9. Проведите приёмку

Проверьте минимум три класса примеров: обычный текст, сканированную страницу и кодовый раздел. Сравните цитату с оригиналом, выполните код в разрешённой среде и убедитесь, что агент сообщает версию и страницу.

Много книг и обновление редакций

При добавлении второй книги не объединяйте всё в один безымянный индекс. Объединяйте темы, но сохраняйте источники и конфликты.

Для каждой редакции задайте source_id, edition, published_at и статус доверия. Если новое издание затронуло только раздел о сетевом API, не нужно полностью пересобирать знания по базовому синтаксису языка. Но связанный Skill необходимо повторно протестировать, если он вызывает изменённые примеры.

Итоговая проверка перед запуском

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

Практическое решение

Если у вас обычный текстовый PDF на несколько устойчивых разделов, начните с прямого извлечения и структурного индекса. Если в книге много сканов, таблиц или двухколоночных страниц, разделите обработку на классы и не включайте OCR для всего файла. Если в книге много кода, обязательно связывайте пример с зависимостями, версией и тестом.

Для большинства проектов оптимальна следующая формула:

PDF → проверенный набор элементов
Knowledge Base → поиск, версии и цитирование
Agent Skill → триггер, процесс, ограничения и проверка

Текущий подход «загрузить весь PDF в один промпт» быстро упирается в большой контекст, слабую поддержку редакций и отсутствие точных ссылок на страницы. Подход «записать всю книгу в Skill» добавляет ещё одну проблему: инструкции становятся тяжёлыми, а обновление знаний превращается в ручную перепаковку. Если вам нужно временно обработать несколько легально используемых книг, проверить примеры или собрать изолированную среду для запуска кода, аренда вычислительной среды VPSSpark удобнее постоянной настройки локальной машины. Для долгих стабильных нагрузок и задач с обязательным физическим доступом к устройствам собственная инфраструктура останется более подходящим вариантом; для разовой обработки и тестирования важнее быстро получить контролируемое окружение. Начать можно с доступных вариантов среды VPSSpark.