Docx

Создание, чтение, правка, заполнение шаблонов и рецензирование Word .docx.

Метаданные навыка

Справочник: полный SKILL.md

Навык Docx

Создание, чтение, правка и заполнение шаблонов Microsoft Word .docx через python-docx — компактными скриптами командной строки. Навык работает с текстом, стилями, списками, таблицами, изображениями, колонтитулами, шаблонизацией через {{token}}, отслеживаемыми правками (список/принять/ отклонить), комментариями (список/добавить/удалить), полями оглавления и номеров страниц, а также проверкой целостности пакета. Сам документы не рендерит (для PDF нужен LibreOffice — см. «Конвертация в PDF») и не редактирует старые .doc.

Когда использовать

• Пользователь просит создать документ Word: отчёт, письмо, договор.
• Нужно получить текст, структуру, стили или встроенные изображения из .docx.
• Нужно изменить существующий .docx: заменить текст, отредактировать ячейки таблицы, вставить или удалить абзацы, применить стиль, объединить раздробленные прогоны.
• Есть шаблон .docx с {{плейсхолдерами}}, который нужно заполнить данными.
• В документе есть отслеживаемые правки, которые нужно просмотреть, принять или отклонить.
• Нужно прочитать комментарии рецензентов либо добавить/удалить комментарий.
• .docx не открывается или ведёт себя странно, и нужно разобраться, не повреждён ли файл.
• Документу нужно оглавление или колонтитул вида «Страница X из Y».
• Не для: старых .doc, .odt и WYSIWYG-вёрстки.

Что должно быть установлено

• Python 3.10+ с установленным python-docx: pip install python-docx (имя модуля при импорте — docx; lxml ставится вместе с ним).
• Добавление комментариев (add) использует нативный API в python-docx

  = 1.2 и XML-фолбэк в более старых версиях — переключение происходит автоматически.

• Для блоков с изображениями: файлы картинок (PNG/JPEG) должны существовать локально.

Как запускать

Все вспомогательные скрипты лежат в scripts/ рядом с этим файлом. Запускай их инструментом terminal; каждый поддерживает --help и печатает JSON в stdout.

python scripts/docx_create.py spec.json out.docx
python scripts/docx_read.py out.docx --text
python scripts/docx_edit.py replace out.docx --find old --replace new
python scripts/docx_template.py tpl.docx values.json filled.docx
python scripts/docx_revisions.py list out.docx
python scripts/docx_comments.py list out.docx
python scripts/docx_validate.py out.docx

Краткая шпаргалка

Порядок действий

1. Создание. Напиши JSON-спецификацию через write_file, затем запусти scripts/docx_create.py. Спецификация поддерживает: page (размер и поля в мм), строки header/footer, footer_page_numbers (добавляет колонтитул с полем «Страница X из Y»), styles (пользовательские стили абзацев — шрифт, размер, bold/italic, hex-цвет color) и blocks — heading (уровень 1–9), paragraph (либо text, либо список runs, где у каждого прогона можно задать bold/italic/underline), bullet_list, numbered_list, table (строка header выводится жирным, rows, опциональный встроенный стиль таблицы style, например Table Grid), image (path, опционально width_mm), toc (поле оглавления) и page_break. Полный формат спецификации описан в начале scripts/docx_create.py.
2. Чтение. Используй scripts/docx_read.py ровно с одним флагом режима. --text возвращает абзацы тела, текст всех ячеек таблиц и текст колонтитулов в виде JSON. --structure возвращает структуру заголовков и количество абзацев/таблиц/секций. --images DIR копирует из пакета все файлы из word/media/.
3. Правка. Используй scripts/docx_edit.py. Команда replace проходит по телу документа, таблицам (включая вложенные), колонтитулам и сохраняет форматирование прогонов; добавь --body-only, чтобы пропустить колонтитулы. Передай -o out.docx, чтобы сохранить оригинал; без этого флага правка идёт на месте. Индексы абзацев для insert/delete/style/toc соответствуют порядку тела документа из --structure/--text. Запускай normalize первым делом на документах, которые прошли через тяжёлое редактирование в Word — эта команда объединяет соседние прогоны с одинаковым форматированием, чтобы последующий поиск и замена срабатывал надёжно.
4. Просмотр правок. docx_revisions.py list показывает каждый w:ins и w:del (id, автор, дата, затронутый текст) — в теле документа, таблицах, колонтитулах, где угодно. accept-all / reject-all разрешают их разом; accept/reject --id N работает с одной правкой. Accept оставляет вставки и убирает удалённый текст; reject делает наоборот.
5. Комментарии. docx_comments.py list возвращает id, автора, дату, текст каждого комментария и текст документа, к которому он привязан. add --target "фраза" привязывает новый комментарий к первому вхождению этой фразы (прогоны при необходимости разбиваются; форматирование сохраняется). delete --id N удаляет комментарий и его маркеры, не трогая текст документа.
6. Шаблон. Размести в документе токены вида {{name}}. Запусти scripts/docx_template.py с JSON-объектом значений. Флаг --strict завершает работу с ошибкой, если остались незаполненные токены; в любом случае JSON-вывод содержит счётчик filled и список unfilled_tokens.
7. Проверка (обязательна): перечитай результат через --text или --structure, а для всего, что получено хирургией над правками или комментариями, запусти docx_validate.py.

Конвертация в PDF

Отдельный скрипт не нужен. Если установлен LibreOffice, конвертируй без графического интерфейса:

soffice --headless --convert-to pdf --outdir outdir/ file.docx

Сначала проверь доступность (command -v soffice || command -v libreoffice). Если ни того, ни другого нет, скажи пользователю, что конвертация в PDF недоступна в этом окружении, вместо того чтобы изобретать обходной путь — python-docx не умеет рендерить PDF, а для точной передачи вёрстки нужен настоящий рендерер.

Грабли

• Токены дробятся на прогоны. Word часто разбивает текст на несколько прогонов. Хелперы замены схлопывают совпавшие прогоны (замена наследует форматирование первого прогона); если сначала запустить docx_edit.py normalize, фрагментация для всех последующих правок снижается.
• Полнота обработки правок. docx_revisions.py разрешает вставки и удаления на уровне прогонов (подавляющее большинство случаев). Правки на уровне маркера абзаца и строки таблицы, записи об изменении форматирования и перемещения --revisions только обнаруживает, но не разрешает автоматически — см. references/revisions-and-comments.md и передавай такие случаи в Word.
• Ветвление комментариев. Ответы и статус «решено» хранятся в commentsExtended.xml, который навык не трогает; комментарии, которые он добавляет, — обычные комментарии верхнего уровня, без ветвления.
• Результаты полей вычисляет Word. toc, page-numbers и опции спецификации toc/footer_page_numbers записывают коды полей. Реальные записи и номера подставляет Word/LibreOffice при открытии файла (Word может предложить обновить поля); python-docx их не вычисляет, поэтому до этого момента виден текст-заполнитель.
• Проверка — это health-check, а не валидация схемы. docx_validate.py проверяет zip-архив, обязательные части, относительные ссылки, магические байты изображений и используемые стили. Это НЕ XSD-валидация — файл может пройти проверку и всё равно содержать XML, который не понравится Word.
• Имя стиля должно существовать. Применение стиля, которого нет в документе, вызывает KeyError. Встроенные стили вроде Heading 1, List Bullet, List Number, Table Grid есть в шаблоне по умолчанию; пользовательские стили нужно сперва объявить в спецификации создания.
• Нумерованные списки не всегда начинаются заново. List Number опирается на нумерацию Word по умолчанию; отдельные списки в одном документе могут продолжать нумерацию, а не начинать её заново. Предупреждай пользователей, которым нужна точная нумерация нескольких списков.
• Запись в ячейку сбрасывает форматирование. set-cell использует cell.text = ..., что сбрасывает прогоны в ячейке к обычному форматированию.
• Кодировка. Все файлы спецификаций и значений JSON читаются явно как UTF-8; не полагайся на локаль по умолчанию, если пишешь собственный связующий код.
• Не распаковывай .docx и не редактируй XML напрямую. Правь через скрипты (или python-docx); текстовая замена «в лоб» в document.xml легко ломает файл. patch/write_file используй только для JSON-входных данных, но не для самого .docx.

Проверка

• После создания, правки или заполнения шаблона запусти docx_read.py out.docx --text и проверь, что ожидаемые строки появились (а старые исчезли).
• После accept/reject docx_revisions.py list должен вернуть [] (или только те id, что оставлены намеренно); после хирургии над комментариями docx_comments.py list должен отражать изменение, а вывод --text — остаться прежним.
• docx_validate.py out.docx завершается с кодом 0 и "ok": true на здоровом пакете — запускай его после любой манипуляции с правками, комментариями или полями.
• Для шаблонов запускай с --strict либо проверяй, что unfilled_tokens == [].
• Проверка структуры: --structure должен показывать ожидаемую структуру заголовков и форму таблиц; --styles подтверждает, что пользовательские стили применились.