artwist-polyakov/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 — источник, хеш, способ извлечения, ограничения.

7. Проверь качество

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

Фокус сборки

Если пользователь не уточнил цель, спроси одним вопросом: "Для чего будет скилл: применять идеи в работе, учиться по материалу, быстро справляться по терминам или принимать решения?" Не превращай это в сложный выбор режимов.

Ориентиры:

• прикладной советник — больше плейбуков, диагностических вопросов и анти-паттернов;
• карта решений — больше decision-rules.md, развилок и критериев выбора;
• справочник — сильнее concepts.md и glossary.md;
• учебный конспект — допускает больше объяснений, но всё равно без замены книги.

Домены

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

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

Работа с большими источниками

Для длинных книг разбирай сегменты постепенно. Если среда позволяет дочерние сессии, можно параллелить анализ независимых сегментов, но не запускай модели ниже уровня текущего оркестратора. Дочерним агентам давай только их сегмент и требуй структурированный вывод: понятия, правила, плейбуки, анти-паттерны, source pointers.

Что читать по необходимости

• references/OUTPUT_SCHEMA.md — точная структура готового навыка и полей карты источников.
• references/COMPILATION_PLAYBOOK.md — как превращать текст в применимые карты, а не в пересказ.
• references/QUALITY_GATE.md — что проверяет quality_gate.py и как чинить провалы.
• references/BACKLOG.md — отложенные механики: OCR, Go-ускоритель, публикационный профиль, сравнение переработки.

Ограничения

• Python-скрипты запускай через uv run --script; зависимости объявлены прямо в заголовках скриптов.
• OCR пока в бэклоге. Сканированные PDF могут дать пустой или плохой текст.
• Проверка похожести сейчас лексическая: n-граммы по словам. Семантическую близость и оценку степени переработки лучше добавлять отдельной задачей.
• Go-бинарник пока не нужен: текущие операции запускаются один раз на источник. Если появится частый многократный прогон по большим текстам, горячий путь для разметки/сравнения можно вынести в Go.