/docx-from-sample - новый документ в оформлении образца

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

Когда применять

• "сделай такой же документ, но по другой теме", "в формате как в примере"
• заказчик прислал образец отчета, ТЗ, ПМИ, регламента - нужен свой документ в том же виде
• документов несколько и они должны выглядеть одинаково
• документ уже сделан, но оформление не совпадает с эталоном - пересобрать

Не для этого скила: правка существующего документа без смены оформления (штатные средства работы с DOCX), markdown в DOCX без образца (скил md-to-docx), таблицы и презентации (xlsx, pptx).

Зависимости

python -m pip install python-docx pymupdf

pymupdf нужен для картинок страниц, Word - для сборки оглавления и экспорта в PDF (на Windows через COM). Без Word документ соберется, но оглавление останется незаполненным.

Образец не зашит в скил

Скил глобальный и не привязан ни к одному шаблону. Образец задается профилем: ключ sample в JSON либо флаг --sample при запуске. Для каждого нового шаблона делается свой профиль, старые не трогаются.

Ситуация	Что делать
Первый документ по этому шаблону	inspect_sample.py на образце, довести профиль, собрать
Еще один документ по тому же шаблону	взять готовый профиль, поменять только материал
Другой заказчик, другой бланк	новый профиль на новый образец
Профиль есть, образец переехал	--sample с новым путем либо поправить sample в профиле

Путь к образцу может быть относительным: он ищется рядом с профилем, потом в текущей папке. Так профиль и образец переносятся между машинами вместе.

Где хранить профили - profiles/README.md. Коротко: профиль конкретного проекта живет рядом с документами проекта или в ~/.claude/plans/<проект>/, а профиль шаблона, нужного из разных проектов, кладется в profiles/ внутри скила.

Порядок работы

1. Снять оформление с образца

python scripts/inspect_sample.py "образец.docx" --json profile.json

Печатает секции с ориентацией и колонтитулами, реально используемые стили абзацев с примерами текста, разбор каждой таблицы (стиль, ширины, заливка шапки, границы, повтор шапки, стили абзацев в ячейках) и порядок блоков документа. Заодно пишет черновой профиль сборки.

Читать отчет ОБЯЗАТЕЛЬНО: черновой профиль угадывает уровни заголовков по кеглю, и это часто неверно. Сверить с отчетом: какой стиль стоит на разделах верхнего уровня, какой на подразделах, чем размечены подзаголовки внутри разделов.

2. Довести профиль

Профиль - это карта "роль в документе -> оформление образца". Формат и все ключи: references/profile-format.md. Минимум, что правится руками:

• styles.h1/h2/h3 - уровни заголовков (из отчета, а не из догадки скрипта);
• tables.default_style_id и grid_style_id - идентификаторы стилей таблиц;
• headings_map - какие тексты являются заголовками какого уровня в НОВОМ документе;
• footer.template - текст подвала, {title} подставляется.

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

3. Подготовить содержание

Два пути.

Markdown - когда документ линейный (заголовки, абзацы, таблицы). Материал пишется в .md, таблицы обычным markdown, секции переключаются маркерами <!-- landscape --> и <!-- portrait -->. Сборка:

python scripts/md_to_docx_sample.py "материал.md" --profile profile.json --out "новый.docx" --title "Название" --author "Имя Ф."

Свой сценарий на python - когда документов несколько и они собираются из данных (словарь, таблица, выгрузка). Тогда данные и сборка разделяются: модуль с данными плюс вызовы SampleDoc. Так шесть однотипных документов правятся в одном месте и не разъезжаются. Пример: references/build-example.py.

4. Проверить

python scripts/verify_result.py "новый.docx" --md "материал.md" --update-fields --png 1,2,9

Скрипт сверяет число таблиц и строк с исходником (ловит потерю строк и склейку таблиц), показывает секции и полосу набора, ищет таблицы шире полосы, считает шапки с заливкой и повтором, обновляет поле оглавления через Word и рендерит указанные страницы в PNG.

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

Рендер образца для сравнения:

python scripts/verify_result.py "образец.docx" --png 1,2,9 --outdir preview_sample

Что переносится из образца

Элемент	Как
Стили абзацев и знаков, темы, шрифты	наследуются вместе с файлом образца
Автонумерация заголовков (1., 1.1., 1.1.1.)	из стиля образца; снимается точечно там, где номер не нужен
Стили таблиц	по идентификатору стиля из образца
Ширины столбцов	из профиля явно либо по содержимому: колонка-счетчик узкая, остальные делят полосу
Заливка шапки, границы, повтор шапки при переносе	из профиля, значения снимаются с образца
Колонтитулы	собираются заново по шаблону из профиля
Книжные и альбомные секции, поля	из профиля

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

Обязательные проверки перед сдачей

• число таблиц и строк совпадает с исходником;
• ни одна таблица не шире полосы набора;
• в каждой секции есть подвал (кроме титульной, если так в образце);
• стили в документе те же, что в образце (скрипт покажет чужие);
• поле оглавления собрано, а не оставлено заглушкой;
• страницы просмотрены глазами хотя бы выборочно: титул, первая страница с таблицей, страница с переносом таблицы через страницу.

Грабли

Полный разбор с симптомами: references/ooxml-pitfalls.md. Коротко, самое дорогое:

1. Две таблицы подряд склеиваются в одну. Между таблицами обязателен пустой абзац, иначе Word объединит их, и число таблиц молча уменьшится.
2. Подвал пропадает на первой странице каждой секции. Свойство "первая страница отдельно" наследуется новой секцией от предыдущей, его надо сбрасывать.
3. Ориентация. В python-docx смена ориентации не меняет ширину и высоту страницы, их надо менять самому. В javascript-библиотеке docx наоборот: она меняет их сама, и ручная перестановка дает двойной переворот.
4. Заливка шапки не появляется сама даже когда стиль таблицы ее рисует: в образцах она обычно задана явно на ячейках. Ставить явно.
5. Узкая колонка-счетчик рвет свой заголовок по буквам. Ширина такой колонки должна считаться по длине заголовка: "№ п/п" уже, чем "Номер версии".
6. Строки-разделители таблицы ("От Заказчика" на всю ширину) в markdown выглядят как повтор текста по всем колонкам - в DOCX их надо объединять в одну ячейку.

Ограничения

• Скил не переносит картинки, диаграммы и фигуры из образца - только текстовое оформление.
• Профиль под жанр документа делается один раз и потом переиспользуется; на новый жанр нужен новый профиль.
• Автоопределение уровней заголовков в черновом профиле - подсказка, а не результат.
• Сборка оглавления и экспорт в PDF требуют установленного Word.