Docx From Sample

---
name: docx-from-sample
description: "Создать новый DOCX в оформлении готового образца: взять чужой документ как шаблон стилей и наполнить своими данными, сохранив титул, заголовки с нумерацией, стили таблиц, ширины столбцов, заливку шапок, колонтитулы, книжные и альбомные секции. Используй когда просят сделать документ по образцу, в том же формате, как в примере, по шаблону заказчика, сохранить оформление существующего документа"
argument-hint: "<образец.docx> [материал.md] [--profile profile.json]"
allowed-tools:
  - Bash
  - PowerShell
  - Read
  - Write
  - Edit
  - Glob
---

# /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.