Knowledge Compiler

knowledge-compiler

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

Позиция

1. Личный контур по умолчанию — скилл собирается для индивидуальной работы с правомерно доступным источником. Публикационные режимы, юридические анкеты и сложные разрешения не входят в основной путь.
2. Компиляция, а не републикация — в результат идут понятия, эвристики, вопросы, решающие правила, плейбуки и анти-паттерны. Длинные цитаты, таблицы, листинги и схемы не копируй по умолчанию.
3. Карта источников обязательна — у каждого значимого тезиса должен быть указатель: сегмент, глава/заголовок, строки или символы, уверенность.
4. Вывод переносимый — готовый навык создаётся в выбранной папке, обычно dist/<skill-name>/. Установка в конкретную среду отдельным шагом.
5. Кеш бережёт контекст — полный текст и сегменты лежат в cache/jobs/<job-id>/; в ответ пользователю не выводи большие фрагменты.

Когда запускать

Запускай, если пользователь говорит: "сделай скилл из книги", "преврати PDF/EPUB в навык", "собери карту знаний", "хочу применять идеи автора", "сделай личного советника по материалу", "извлеки фреймворки из документа".

Не запускай для публичной публикации чужой коммерческой книги без отдельного обсуждения прав. Не обходи DRM, защиту доступа, paywall или технические ограничения файла.

Быстрый маршрут

1. Проверь окружение

   sh scripts/doctor.sh

2. Извлеки источник

   sh scripts/prepare_source.sh --input "/path/to/source.pdf" --mode auto

   Скрипт создаст cache/jobs/<job-id>/source.txt и metadata.json. Для EPUB он читает OPF-метаданные (title, creator) и оглавление из toc.ncx/nav.xhtml, даже если файл пришёл с расширением .zip, но внутри является EPUB.

3. Сделай разведку структуры

   uv run --script scripts/outline_scout.py \
     --input cache/jobs/<job-id>/source.txt \
     --out cache/jobs/<job-id>/outline-scout.json

   Передай модели или субагенту metadata.json, outline-scout.json, outline-head.txt, outline-tail.txt и outline-candidates.txt. Его задача — определить, как в источнике обозначены оглавление, части, главы, приложения и хвостовые материалы. Не отправляй весь source.txt на этом шаге. Если outline-scout.json уже содержит script_observations.epub_toc_items, считай это главным кандидатом на структуру: EPUB сам хранит оглавление точнее, чем регулярки по тексту.

4. Разбей на сегменты

   uv run --script scripts/segment_text.py \
     --input cache/jobs/<job-id>/source.txt \
     --out cache/jobs/<job-id>/segments \
     --decision cache/jobs/<job-id>/outline-scout.json

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

5. Создай заготовку будущего навыка

   sh scripts/build_skill_skeleton.sh \
     --name my-source-skill \
     --title "Название источника" \
     --author "Автор" \
     --job-dir cache/jobs/<job-id> \
     --output-dir dist

6. Скомпилируй содержание Прочитай metadata.json, segments/outline.json и нужные файлы из segments/chunks/. Заполни:

   • SKILL.md — короткий рабочий протокол, до 2000 слов;
   • references/concepts.md — ключевые понятия;
   • references/decision-rules.md — решающие правила "если X, делай Y";
   • references/playbooks.md — прикладные сценарии;
   • references/anti-patterns.md — ошибки и признаки риска;
   • references/glossary.md — термины;
   • references/source-map.json — связь тезисов с сегментами;
   • references/knowledge-manifest.json — источник, хеш, способ извлечения, ограничения.

   Соблюдай соглашение о claim_id, заголовках и ссылках из references/OUTPUT_SCHEMA.md. Не копируй исходный текст или сегменты в готовый навык: они остаются в кеше.

7. Проверь качество и создай указатель источников

   uv run --script scripts/quality_gate.py \
     --source cache/jobs/<job-id>/source.txt \
     --skill-dir dist/my-source-skill \
     --write-source-index

   После успешных проверок команда создаст references/source-index.md из заполненной карты источников. Для проверки без изменений запускай её без --write-source-index; после изменения карты пересоздай указатель тем же флагом.