Книга → навыки: курс по skills-book-digitizer

Знакомься: Мира, участница harness-мастерской. Ставить пакеты навыков она умеет, фичу через конвейер уже проводила. Сегодня у неё на столе инженерная книга на 600 страниц и один неудобный вопрос: как сделать, чтобы ассистент проектировал по ЭТОЙ книге, а не по усреднённому мнению интернета, на котором его обучили?

Привычный путь — пересказать книгу в чат — разваливается на второй неделе. Контекст очищается, пересказ исчезает, и ассистент снова отвечает так, будто книги не было. Пакет @dzhechkov/skills-book-digitizer подходит к задаче с другой стороны.

Оцифровка книги в навыки — это превращение PDF в устанавливаемый набор навыков, каждый из которых срабатывает ровно в тот момент, когда ассистент принимает решение, о котором книга и написана. Не конспект, а поведение.

Пример вместо определения. Книгу о высоконагруженных системах пакет превращает в навыки вроде ddia-replication-topology-choice. Ты обсуждаешь схему репликации — навык поднимается сам и приносит методику из книги вместе с номером страницы.

После прогона у Миры остаются три долговечных артефакта:
1. пак навыков skills-book-<slug> — поведение, которое ставится в любой агент;
2. база знаний проекта — по ней ищут словами, прямо в том проекте, где книгу оцифровали;
3. путь в машинный мозг (~/.dz/brain/) — общее хранилище, куда книгу можно продвинуть, чтобы она отвечала во всех проектах сразу.

Живой пример: The Twelve-Factor App оцифрован в двенадцать навыков и опубликован открыто — @dzhechkov/skills-12factor. Исходники пакета и зеркало: github.com/djd1m/dz-harness.

Компромиссы: оцифровка книги в навыки даёт агенту методику, проверяемую по страницам, но она не бесплатна — книга на 640 страниц стоит примерно 2,5–4 миллиона токенов и требует твоих решений на шести остановках.

💬 Просто попроси.
- «Оцифруй вот эту книгу — хочу, чтобы агент проектировал по её методикам» → ассистент запустит навык digitize-book и начнёт с разбора PDF.
- «Что мне даст оцифровка книги в навыки?» → ассистент назовёт три артефакта и покажет оценку стоимости прогона.

Мира начинает не с книги, а с одной команды. Установка digitize-book ставит в проект оркестратор — навык, который сам подтянет остальные семь навыков пакета и дальше будет вести прогон по стадиям.

dz init --target claude-code --select digitize-book

Разберём по частям, чтобы команда не выглядела заклинанием:
- dz init — команда, которая раскладывает навыки в формат конкретного агента;
- --target claude-code — для какого агента компилировать; поддерживаются шесть целей, среди них codex, opencode, copilot;
- --select digitize-book — какие навыки взять. Достаточно назвать оркестратор: стадии ставятся вместе с ним.

Два условия, без которых прогон встанет:
1. poppler-utils — системный набор утилит для PDF (pdftotext, pdfinfo, pdfimages). Именно он читает книгу; проверяется командой pdftotext -v.
2. dz setup --memory agentdb — установка хранилищ для базы знаний (agentdb и better-sqlite3). Без неё стадии до сборки пака отработают, а база знаний собраться не сможет.

После установки Мира просто говорит ассистенту человеческим языком: «оцифруй вот эту книгу — хочу, чтобы агент проектировал по её методикам». Дальше запускается конвейер, и первая остановка наступает быстро — на разборе структуры PDF.

Компромиссы: установка digitize-book занимает одну команду и не тянет тяжёлых зависимостей в проект, но системный poppler-utils и хранилища ставятся отдельно — на чистой машине это ещё два шага, и забыть их легко.

💬 Просто попроси.
- «Поставь мне оцифровщик книг» → ассистент выполнит dz init --target claude-code --select digitize-book и проверит наличие poppler.
- «Проверь, готова ли машина к оцифровке» → ассистент прогонит pdftotext -v и подскажет, нужен ли dz setup --memory agentdb.

Мира открывает пакет и видит восемь навыков. Пугаться нечего: семь из них — это конвейер стадий, где у каждой стадии свой навык, свой вход и свой проверяемый выход, а восьмой навык вообще про другое.

Общая картина одной строкой:

book.pdf → корпус → единицы знания → навыки → пак → база знаний → (по желанию) машинный мозг

Теперь по стадиям, в порядке прохождения:
1. book-ingest — PDF превращается в нарезанный по кускам корпус с привязкой к страницам. Никакой языковой модели: только poppler и правила.
2. book-knowledge-extract — из корпуса добываются проверенные единицы знания: методики, схемы принятия решений, формулы, чек-листы.
3. book-skill-distill — единицы знания перегоняются в навыки моментов решения, с проверкой того, что навык поднимается на правильном вопросе.
4. book-pack-assemble — навыки собираются в устанавливаемый пак вместе со справочником и срезом базы знаний.
5. book-kb-index — единицы знания раскладываются по двум хранилищам проекта: словесному поиску и векторному.
6. book-brain-register — необязательная последняя стадия: продвинуть книгу в общий машинный мозг на все проекты.

Восьмой навык, source-brain-ingest, — не стадия книги, а её ближайший родственник: он так же глубоко обходит репозиторий или каталог кода и складывает те же самые единицы знания в тот же самый мозг. Один мозг, два входа: книги и код.

Оркестратор digitize-book — это дирижёр: сам он ничего не извлекает, он вызывает стадии по очереди и останавливается там, где нужно твоё решение.

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

💬 Просто попроси.
- «Покажи, на какой стадии сейчас оцифровка» → ассистент назовёт последнюю завершённую стадию и её выход на диске.
- «Продолжи оцифровку с того места, где мы остановились» → ассистент подхватит конвейер стадий с ближайшей незавершённой остановки.

Оцифровка книги — управляемая операция, а не фоновая задача. Оркестратор никогда не проходит книгу целиком без человека, и это осознанное решение: контрольная точка — это место, где конвейер останавливается и ждёт твоего суждения, потому что ошибку дешевле поймать здесь, чем через два миллиона токенов.

Мира проходит шесть таких остановок:
- CP1, после разбора PDF. Ты подтверждаешь охват (вся книга или главы), тип структуры, пропущенные предисловия, распознанный язык корпуса — и видишь оценку стоимости в токенах.
- CP2, после пробных глав. Извлечены единицы знания из одной-двух глав. Ты смотришь на их качество и правишь курс. Массовое извлечение жёстко закрыто этой остановкой, и это самая ценная точка во всём прогоне.
- CP3, после отбора навыков. Ты утверждаешь список кандидатов: какие моменты решений вообще заслуживают навыка.
- CP3.5, после проверок срабатывания. Отчёт показывает, поднимается ли навык на своём вопросе и не крадёт ли он вопросы соседей.
- CP4, после сборки пака. Результат машинных проверок пака и пробной установки.
- CP5, раздача. Что делать с паком: оставить закрытым (по умолчанию) или записать явное решение о публикации.
- CP6, продвижение. Необязательная последняя остановка: пускать ли книгу в общий машинный мозг.

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

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

💬 Просто попроси.
- «Останови оцифровку и покажи оценку стоимости» → ассистент вернёт тебя на первую контрольную точку с расчётом токенов.
- «Мне не нравится качество примеров — переделай извлечение» → ассистент останется на второй остановке и поправит извлечение до массового прогона.

Первую стадию Мира запускает без единого обращения к языковой модели — и это не экономия, а требование конструкции.

Детерминированный корпус — это нарезанный на куски текст книги, который при повторном прогоне получается ровно таким же, байт в байт. Инструменты здесь простые: pdftotext из poppler плюс правила разбора. Никакой модели, никакой случайности.

Зачем нужна именно повторяемость. Всё, что идёт дальше по конвейеру, ссылается на куски корпуса и на его версию. Если бы разбор давал каждый раз чуть разный результат, то:
- возобновление прогона после перерыва ломалось бы — ссылки указывали бы в пустоту;
- повторный прогон нельзя было бы сравнить с предыдущим;
- постраничные ссылки в единицах знания перестали бы что-то доказывать.

Что стадия кладёт на диск, кроме текста:
1. манифест — опись глав и кусков, которой доверяют все следующие стадии;
2. матрица качества по страницам — где страница пустая, где текст плохо связан, где много формул, где две колонки;
3. опись рисунков и таблиц — чтобы потери не остались незаметными;
4. версия корпуса и отпечаток каждого куска — те самые якоря повторяемости.

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

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

💬 Просто попроси.
- «Разбери книгу и покажи структуру, ничего не извлекая» → ассистент выполнит стадию разбора и покажет манифест с матрицей качества.
- «Проверь, есть ли в этом PDF текстовый слой» → ассистент прогонит poppler и скажет, годится ли книга для детерминированного корпуса.

Дальше книга перестаёт быть текстом и становится набором атомов. Единица знания (в командах и файлах — KU, от knowledge unit) — это один самодостаточный кусок ноу-хау книги, привязанный к странице: методика, схема принятия решения, формула, эвристика, чек-лист, таблица компромиссов, разбор случая или определение.

У каждой единицы знания есть устойчивый идентификатор — например ai-apps-ch09-p238-ku05. Читается он слева направо: короткое имя книги, глава, страница, номер единицы. Именно по нему потом достают полный текст записи.

Стадия извлечения работает в два прохода:
1. Разбор и сборка. Главы обрабатываются по частям, потом похожие единицы схлопываются в одну, чтобы одна и та же методика не размножилась на десять записей.
2. Проверка следования. Отдельный проход перечитывает процитированные страницы и спрашивает: действительно ли эта страница подтверждает то, что записано? Единицы, которые не проходят, дальше не идут.

Отдельно живёт правило верности источнику: факты — дословно, изложение — своими словами. Числа, названия и формулы переносятся точно, а объяснения переписываются, потому что пак не должен быть перепечаткой книги. Здесь Мира и улавливает главное: пакет производит ноу-хау книги, а не её текст.

Живая цифра для масштаба: одна книга о высоконагруженных приложениях дала 116 единиц знания.

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

💬 Просто попроси.
- «Покажи единицу знания ai-apps-ch09-p238-ku05 целиком» → ассистент выполнит dz brain expand и вернёт полную запись с якорями страниц.
- «Сколько единиц знания извлеклось из этой книги?» → ассистент посчитает записи и покажет разбивку по главам.

Вот место, где Мира впервые спорит с самой собой. Кажется естественным сделать по навыку на главу: глава про репликацию — навык про репликацию. Стадия перегонки настаивает на другом.

Навык момента решения — это навык, названный по развилке, на которой инженер стоит, а не по разделу книги, из которого он вырос. Не «глава 5», а ddia-replication-topology-choice — выбор схемы репликации. Разница практическая: ассистент решает, поднимать навык или нет, по совпадению с тем, что происходит прямо сейчас в разговоре. У развилки есть узнаваемые признаки, у главы — нет.

У каждого навыка есть два обязательных дополнения:
1. Проверки срабатывания. Набор вопросов, на которых навык обязан подняться, и вопросов, на которых он обязан промолчать. Отчёт по ним показывают на остановке CP3.5: ориентир — не меньше 80% верных срабатываний и не больше 10% случаев, когда навык перехватывает вопрос соседа.
2. Прослеживаемость до источника. Каждое утверждение навыка ведёт к единицам знания, из которых оно собрано, а те — к страницам.

И ещё одно честное признание, которое стоит запомнить сразу: сгенерированные навыки выходят с низким уровнем доверия — «сделано машиной, человеком не проверено». Поднять уровень можно двумя путями: человек сверяет навык с процитированными страницами, либо навык проходит проверки срабатывания.

Компромиссы: навык момента решения срабатывает точно и не засоряет разговор, но требует, чтобы книга вообще содержала развилки. Справочник или сборник фактов перегоняется в навыки плохо — там просто нет моментов решения.

💬 Просто попроси.
- «Покажи список навыков-кандидатов и объясни, какому решению соответствует каждый» → ассистент выведет отбор перед третьей остановкой.
- «Этот навык перехватывает чужие вопросы — сузь его» → ассистент перепишет условия срабатывания и перезапустит проверки.

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

Приватность по умолчанию означает, что собранный пак выходит закрытым: в его описании стоит признак «не публиковать», настройки публикации ограничены, и в общие наборы навыков он автоматически не попадает. Публикация — твоё явное решение на остановке CP5, а не побочный эффект сборки.

Почему так строго. Пак несёт ноу-хау из книги, у которой есть правообладатель. Если бы приватность по умолчанию не была вшита в сборку, достаточно было бы одной невнимательной команды публикации, чтобы отправить производное от защищённой книги в открытый реестр. Здесь это невозможно механически, а не «по договорённости».

Что кладётся внутрь пака:
1. навыки — по файлу на момент решения;
2. справочник для углублённого просмотра — тексты, к которым навык отсылает, когда короткого ответа мало;
3. срез базы знаний книги — чтобы пак был самодостаточным на новой машине;
4. опись источников без внешних ссылок на исходник и белый список файлов — в пак попадает только перечисленное.

Перед тем как пак признают собранным, срабатывают заставы: проверка на дословные совпадения, проверка столкновений имён с уже существующими навыками и пробная установка. Для цели copilot дополнительно считают суммарный объём инструкций — там есть жёсткий предел.

Отдельно про раздачу. Готовый пак ставят командой dz init --select <идентификаторы навыков> с любой машины, где он есть. Если нужен самодостаточный комплект без dz на стороне получателя — dz bundle собирает переносимый каталог. Правила о правах на книгу действуют и там.

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

💬 Просто попроси.
- «Собери пак и покажи, что попало внутрь» → ассистент выполнит стадию сборки и перечислит содержимое белого списка.
- «Поставь мне из этого пака два навыка про репликацию» → ассистент выполнит dz init --select с их идентификаторами.

Мира задаёт неудобный вопрос: «Правило „изложение своими словами“ — красивое. А кто-нибудь его вообще проверяет?»

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

Исключение ровно одно и оформлено явно: цитата длиной до двадцати пяти слов, у которой указана страница-источник. То есть цитировать можно — нельзя цитировать тайком.

Зачем такой странный порог. Восемь слов подряд — это уже не совпадение терминов, а перенос авторской формулировки. Ниже порога вылезли бы ложные срабатывания на устойчивых оборотах; выше — сквозь заставу проскакивали бы целые предложения.

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

Компромиссы: проверка дословных совпадений даёт настоящую механическую гарантию непереписывания, но она проверяет только форму. Изложение своими словами, которое исказило смысл книги, эта застава пропустит с чистой совестью — за смысл отвечает проход проверки следования, а он агентский.

💬 Просто попроси.
- «Прогони проверку дословных совпадений по собранному паку» → ассистент выполнит заставу и покажет найденные отрезки с их местом.
- «Оставь эту цитату, но по правилам» → ассистент сократит её до допустимой длины и проставит страницу-источник.

Самая дорогая по нервам ошибка во всём пакете стоит ноль строк кода и полчаса жизни. Мира наступила на неё первой, теперь очередь твоя — но с предупреждением.

Ловушка двух хранилищ состоит в том, что баз знаний две, команды к ним разные, и запрос не в ту базу отвечает «0 совпадений» и завершается успешно. Никакой ошибки. Просто пусто.

Вот они, обе:
- База знаний проекта — живёт в самом проекте, содержит только книги, оцифрованные ЗДЕСЬ. Запрос: dz recall --books --book <имя-книги> "вопрос".
- Машинный мозг — общий на всю машину (~/.dz/brain/), содержит только то, что туда явно продвинули на остановке CP6 или командой dz brain add. Запросы: dz brain query, dz brain ground, dz brain expand.

Правило, которое стоит запомнить дословно: ответ нужен в другом проекте — иди в мозг; ответ нужен внутри проекта, где книгу оцифровали, — иди в базу проекта. Сомневаешься — сначала dz brain list: она честно перечислит, что в мозге вообще лежит.

Почему пустой ответ не считается ошибкой: с точки зрения команды всё в порядке — она поискала и не нашла. Отличить «в этой базе такого нет» от «ты спрашиваешь не ту базу» команда не может, потому и не пытается притворяться.

Продвижение в мозг делается двумя способами. Внутри конвейера — навыком book-brain-register на остановке CP6, он сам выполнит dz brain add --project . --source <имя-книги>. Вручную — той же командой, запущенной позже из проекта, где книга уже проиндексирована. Мозг накапливается сам, и чтобы искать по нему, ставить ничего не нужно.

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

💬 Просто попроси.
- «Покажи, что лежит в машинном мозге» → ассистент выполнит dz brain list с именами книг и числом единиц знания.
- «Найди про схемы репликации в книге, которую мы тут оцифровали» → ассистент пойдёт в базу знаний проекта, а не в мозг.

Оцифровка — это половина петли. Вторая половина: как сделать, чтобы методика книги действительно влияла на работу. Мира пробует четыре способа применения книги — они выстроены от разового к постоянному, и выбирать надо по тому, как часто тебе это нужно.

Способ первый — один ответ, обоснованный книгой. Ничего не настраиваешь, просто спрашиваешь:

dz brain query 'как оценивать агента' --source ai-apps
dz brain expand ai-apps-ch09-p238-ku05
dz brain ground 'как оценивать агента' --source ai-apps --budget 800 --text

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

Способ второй — один прогон конвейера. Обязанность вписывается прямо в описание задачи: «дизайн обязан свериться с книгой через dz brain query; ключевые решения цитируют идентификаторы единиц знания; расхождение с книгой допустимо только с названной причиной». Ничего устанавливать не надо, действует ровно на этот прогон.

Способ третий — весь проект, пока стоит перехватчик. Команда dz brain init --project <каталог> --k 5 встраивает перехват отправки запроса: если запрос достаточно пересекается по словам с мозгом, в разговор механически подмешиваются подходящие единицы знания с цитатами. По умолчанию перехватчик выключен, а снять его можно, удалив его запись из настроек проекта.

Способ четвёртый — один конвейер, но навсегда. Строка-застава дописывается в файл правил, который этот конвейер и так читает: «стадия дизайна проходит, только если цитирует результаты dz brain query или называет причину расхождения». Без установки, но действует постоянно.

Ещё одна граница честности — она про третий способ. Перехватчик механически заставляет знание попасть в контекст — этого агент избежать не может. А вот ответить именно по нему — уже дисциплина агента. Перехватчик управляет входом, а не выводом.

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

💬 Просто попроси.
- «Обоснуй это решение по книге ai-apps» → ассистент выполнит dz brain query и приведёт цитаты со страницами.
- «Сделай, чтобы весь этот проект отвечал по книге» → ассистент предложит третий способ и выполнит dz brain init с твоего согласия.

Последний раздел — самый полезный, потому что он про то, чего пакет НЕ делает. Мира усвоила главное: инструмент, который честно называет свои границы, дороже инструмента, который обещает всё.

Честные ограничения этого пакета разложены по двум полкам, и разница между полками принципиальна.

Полка первая — гарантии, вшитые в код и упаковку. Они держатся сами, без чьей-либо добросовестности:
1. пак выходит закрытым и не может опубликоваться сам;
2. в пак попадает только то, что перечислено в белом списке, а опись источников не ведёт наружу;
3. разбор PDF детерминированный и повторяемый;
4. база знаний книги — отдельное пространство имён, она не подмешивается в общие рекомендации;
5. проверка дословных совпадений — работающий скрипт на сборке.

Полка вторая — то, что держится на дисциплине агента и ломается тихо. Происхождение единиц знания проверяется перечитыванием страниц, а не криптографией; правило «факты дословно, изложение своими словами» и прослеживаемость до источника — это поведение, которому агенты следуют. Поэтому сгенерированные навыки и выходят с низким уровнем доверия и описанным путём его повышения.

Цена. Книга на 640 страниц — примерно 2,5–4 миллиона токенов от начала до конца. Оценку показывают на первой остановке, а массовое извлечение закрыто второй, чтобы плохое качество не превратилось в дорогое плохое качество.

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

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

Зеркало исходников и место для вопросов: github.com/djd1m/dz-harness. Пакет: @dzhechkov/skills-book-digitizer.

💬 Просто попроси.
- «Что здесь гарантировано машиной, а что дисциплиной агента?» → ассистент разложит честные ограничения по двум полкам с примерами.
- «Стоит ли гнать эту книгу через конвейер?» → ассистент оценит текстовый слой, объём и стоимость и честно скажет, если овчинка не стоит выделки.