Документы

anthropics/pptx

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

← Все навыки

Оцените навык первым

SKILL.md

Перевод инструкции, которую получает агент при подключении навыка. Агент всегда использует оригинал.

Создание, редактирование и анализ PPTX

.pptx — это ZIP-архив XML-файлов. Выбирайте подход в зависимости от задачи:

Задача Подход
Создать новый дек Написать скрипт на pptxgenjs — см. предупреждения ниже
Редактировать существующий дек или создать из шаблона распаковать → редактировать ppt/slides/slideN.xml → запаковать
Прочитать содержимое markitdown deck.pptx (один блок на слайд под маркерами <!-- Slide number: N -->); визуальная сетка: python scripts/thumbnail.py deck.pptx

Скрипты

Пути относительно каталога этого навыка. Всё остальное — обычный Python, node или shell.

Скрипт Что делает
scripts/thumbnail.py deck.pptx [prefix] Размеченная сетка каждого слайда для выбора макетов шаблона. Только .pptx. Передайте prefix — по умолчанию thumbnails, который перезаписывает сетки других деков в той же папке
scripts/add_slide.py unpacked/ slide2.xml [--after slideN.xml] Дублирует слайд (или slideLayoutN.xml) со всей необходимой регистрацией в пакете. Также принимает .pptx напрямую с -o out.pptx
scripts/clean.py unpacked/ Удаляет слайды, медиа и rels, на которые больше нет ссылок. Запускайте после финализации <p:sldIdLst>
scripts/office/validate.py deck.pptx [--original src.pptx] Проверка схемы, связей, типов контента, диаграмм и слайдов; каждая ошибка сопровождается указанием исправления. Передайте --original для деков, созданных из шаблона — это сравнивает схему с шаблоном, чтобы ошибки XSD шаблона не считались вашими
scripts/office/soffice.py --headless --convert-to pdf deck.pptx Обёртка LibreOffice — обычный soffice зависает в этой песочнице

Создание с pptxgenjs — предупреждения

pptxgenjs предустановлен — не запускайте npm install сначала; пишите скрипт и require('pptxgenjs') напрямую. Только если require не сработал: npm install pptxgenjs. Модель знает API; вот подводные камни:

  • Устанавливайте pres.layout до добавления слайдов. По умолчанию холст LAYOUT_16x9 = 10" × 5.625", а не 13.3" в ширину. Координаты за пределами записываются, но не ограничиваются — фигура просто не отображается на слайде. (LAYOUT_WIDE — 13.3" × 7.5".)
  • Шестнадцатеричные цвета: никогда не с #, никогда не 8 цифр. color: "FF0000". И "#FF0000", и альфа в hex ("00000020") повреждают файл. Для прозрачности: transparency: 0-100 для заливок и изображений, opacity: 0.0-1.0 для теней — каждый параметр игнорируется в другом контексте.
  • pptxgenjs изменяет объекты опций на месте (преобразует значения в EMU при первом использовании). Никогда не используйте один и тот же объект shadow/опций в двух вызовах add* — создавайте новый объект каждый раз.
  • Смещение тени offset должно быть ≥ 0 — отрицательное смещение повреждает файл. Чтобы отбрасывать тень вверх, используйте angle: 270 с положительным смещением.
  • letterSpacing игнорируется без предупреждения — правильный параметр charSpacing.
  • Списки: bullet: true на каждом элементе, никогда не вставляйте символ • напрямую (будет двойной маркер). Устанавливайте breakLine: true на каждом элементе массива, кроме последнего. Отступы между абзацами с маркерами задавайте через paraSpaceAfter, а не lineSpacing (иначе большие промежутки).
  • Один new pptxgen() на выходной файл — не переиспользуйте экземпляр.
  • rectRadius работает только с ROUNDED_RECTANGLE, не с RECTANGLE.
  • Градиентные заливки не поддерживаются — используйте градиентное изображение как фон.
  • Текстовые блоки имеют внутренние отступы — ставьте margin: 0, если текст должен выравниваться по форме, линии или иконке по одной оси X.
  • Заметки докладчика идут в slide.addNotes("...") (простой текст, один раз на слайд), не в текстовом блоке на слайде.
  • Сохраняйте диаграммы нативными. Используйте addChart() для всего, что PowerPoint умеет строить (передавайте массив {type, data, options} для комбинированных). Для функций PowerPoint, не поддерживаемых библиотекой (трендовые линии, погрешности), вычисляйте дополнительные серии сами или постобрабатывайте сгенерированный OOXML — не используйте изображение. Только диаграммы без нативной поддержки (Sankey, network, chord) вставляйте как изображения.
  • Диаграммы по умолчанию рендерятся без оформления — без заголовка, без подписей данных, с устаревшей палитрой. Устанавливайте showTitle + title, showValue: true + dataLabelPosition, chartColors: [...] из вашей палитры и отключайте рамку (catAxisLabelColor/valAxisLabelColor, valGridLine: { color, size }, catGridLine: { style: "none" }, showLegend: false для одной серии).
  • Для сложенных столбчатых диаграмм dataLabelPosition должен быть ctr, inEnd или inBase. outEnd повреждает файл.
  • Комбинированная серия с secondaryValAxis/secondaryCatAxis требует и valAxes, и catAxes в опциях диаграммы, по два элемента в каждом. Без этого pptxgenjs записывает ID осей, которые не объявлены, и PowerPoint отбрасывает диаграмму и считает файл повреждённым. Только valAxes недостаточно.
  • После writeFile() запускайте python scripts/office/validate.py deck.pptx. Он сообщает о двух ошибках диаграмм выше и дефектах XML слайдов, которые PowerPoint не принимает, и указывает исправления. Исправляйте в генераторе, не вручную в XML.
  • Никогда не меняйте порядок дочерних элементов <p:presentation>. pptxgenjs пишет <p:notesMasterIdLst> сразу после <p:sldIdLst> и указывает оба мастера на одну тему. PowerPoint читает это нормально — если переместить элемент, тот же дек становится неоткрываемым.
  • Иконки: рендерьте react-icons в SVG (ReactDOMServer.renderToStaticMarkup), растрируйте с sharp с разрешением ≥256px и вставляйте через addImage({ data: "image/png;base64," + buf.toString("base64") }) — префикс image/png;base64, обязателен (react-icons, react, react-dom и sharp предустановлены — npm install react-icons react react-dom sharp только если require не сработал).

Редактирование существующих деков и шаблонов

Сначала выберите макеты: python scripts/thumbnail.py template.pptx template-thumbs создаст размеченную сетку каждого слайда и выведет созданные файлы — template-thumbs.jpg, разделённый на template-thumbs-N.jpg после 12 слайдов. Всегда передавайте второй аргумент, названный по деку. По умолчанию thumbnails, так что два дека в одной папке перезапишут друг друга — слайды первого просто исчезнут (только анализ шаблона — визуальный контроль нужен с полноразмерными рендерами из Конвертация в изображения; принимает только .pptx, так что скопируйте .potx в .pptx перед этим). Используйте вместе с markitdown для сопоставления каждого раздела контента с шаблонным слайдом и варьируйте макеты — не кладите все разделы на один слайд с заголовком и маркерами.

python3 -c "import sys,zipfile; zipfile.ZipFile(sys.argv[1]).extractall('unpacked')" deck.pptx
python scripts/add_slide.py unpacked/ slide2.xml --after slide2.xml   # дублировать слайд (или slideLayoutN.xml); выводит путь нового слайда
# изменить порядок / удалить слайды = редактировать <p:sldIdLst> в ppt/presentation.xml
python scripts/clean.py unpacked/                                     # после удаления: удаляет сиротские слайды, медиа, rels
# редактировать содержимое слайда в ppt/slides/slideN.xml
(cd unpacked && rm -f ../out.pptx && zip -Xr ../out.pptx .)           # архивировать ИЗНУТРИ папки; удалите старый файл, иначе удалённые части сохранятся
python scripts/office/validate.py out.pptx --original deck.pptx
  • Выполняйте все структурные операции — добавление, удаление, изменение порядка — до редактирования содержимого слайдов. add_slide.py копирует файл слайда дословно, так что дублирование после редактирования клонирует изменённый контент; а clean.py удаляет любой слайд, отсутствующий в <p:sldIdLst>, включая только что записанный.
  • Никогда не копируйте файл слайда вручную — add_slide.py делает всю регистрацию нового слайда и сообщает, что создал (Created ppt/slides/slide17.xml from slide2.xml). Он также работает напрямую с файлом: add_slide.py deck.pptx slide2.xml -o out.pptx — обязательно передавайте -o, иначе исходный дек перезапишется на месте. Дублированный слайд всё ещё ссылается на части диаграмм/SmartArt/встроенных объектов исходника, а не клонирует их, так что изменение диаграммы в одном слайде меняет и другой.
  • Если используете python-pptx, он не умеет: дублировать слайд (есть только add_slide(layout)), сохранять форматирование при text_frame.text = "..." (это сворачивает абзац в один неформатированный фрагмент — присваивайте run.text), или читать SVG/EMF, которые используют шаблоны (add_picture выдаёт UnidentifiedImageError).
  • Старые .ppt сначала конвертируйте: python scripts/office/soffice.py --headless --convert-to pptx file.ppt. .potx шаблоны распаковываются и упаковываются одинаково — сохраняйте расширение .potx на выходе.
  • Чтобы повторно использовать иконку или изображение из шаблона, дублируйте слайд или макет, где оно уже есть.

При заполнении шаблона:

  • Если пишете XML-трансформацию, парсите через defusedxml.minidom — проход через xml.etree.ElementTree переписывает префиксы пространств имён и портит дек.
  • Слоты шаблона ≠ элементы источника. Если в шаблоне 4 участника команды, а у вас 3, удалите всю группу четвёртого (изображение + текстовые блоки), а не только текст — затем проверьте визуальные сироты на QA.
  • Один <a:p> на элемент списка — никогда не объединяйте элементы в один абзац. Копируйте соседний <a:pPr>, чтобы сохранить отступы, и ставьте b="1" на <a:rPr> заголовков, секций и встроенных меток (Status:, Owner:).
  • Пусть маркеры наследуются от макета; добавляйте <a:buChar>, <a:buAutoNum> (нумерованные) или <a:buNone>, чтобы переопределить — никогда не вставляйте символ • напрямую.
  • Текст с ведущими или завершающими пробелами требует xml:space="preserve" на <a:t>.

Идеи дизайна

Не создавайте скучные слайды. Простые маркеры на белом фоне никого не впечатлят. Рассмотрите идеи из этого списка для каждого слайда.

Перед началом

  • Выберите смелую, тематически подходящую палитру цветов: Палитра должна выглядеть созданной именно для ЭТОЙ темы. Если замена цветов в совершенно другой презентации всё ещё «работает», значит, выбор недостаточно специфичен.
  • Доминирование над равенством: Один цвет должен доминировать (60-70% визуального веса), с 1-2 поддерживающими тонами и одним ярким акцентом. Никогда не давайте всем цветам равный вес.
  • Контраст тёмного и светлого: Тёмные фоны для титульных и заключительных слайдов, светлые для основного контента («сэндвич»-структура). Или выберите тёмный стиль для всего, чтобы создать премиальный вид.
  • Выберите визуальный мотив: Один отличительный элемент и повторяйте его — округлённые рамки изображений, иконки в цветных кругах. Используйте на каждом слайде. Не используйте цветную полосу или акцентную линию как мотив (см. список избегаемого).

Палитры цветов

Выбирайте цвета, соответствующие теме — не берите стандартный синий. Используйте эти палитры как вдохновение:

Тема Основной Вторичный Акцент
Midnight Executive 1E2761 (тёмно-синий) CADCFC (ледяной голубой) FFFFFF (белый)
Forest & Moss 2C5F2D (лесной зелёный) 97BC62 (моховой) F5F5F5 (кремовый)
Coral Energy F96167 (коралловый) F9E795 (золотой) 2F3C7E (тёмно-синий)
Warm Terracotta B85042 (терракотовый) E7E8D1 (песочный) A7BEAE (шалфей)
Ocean Gradient 065A82 (глубокий синий) 1C7293 (бирюзовый) 21295C (полуночный)
Charcoal Minimal 36454F (угольный) F2F2F2 (слегка белый) 212121 (чёрный)
Teal Trust 028090 (бирюзовый) 00A896 (морская пена) 02C39A (мятный)
Berry & Cream 6D2E46 (ягодный) A26769 (пыльная роза) ECE2D0 (кремовый)
Sage Calm 84B59F (шалфей) 69A297 (эвкалипт) 50808E (сланец)
Cherry Bold 990011 (вишнёвый) FCF6F5 (слегка белый) 2F3C7E (тёмно-синий)

Для каждого слайда

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

Варианты макетов:

  • Два столбца (текст слева, иллюстрация справа)
  • Ряды иконок + текста (иконка в цветном круге, жирный заголовок, описание ниже)
  • Сетка 2x2 или 2x3 (изображение с одной стороны, сетка контент-блоков с другой)
  • Изображение на половину слайда (слева или справа) с наложением контента

Отображение данных:

  • Крупные статистические вызовы (большие цифры 60-72pt с маленькими подписями)
  • Колонки сравнения (до/после, плюсы/минусы, варианты рядом)
  • Таймлайн или процесс (нумерованные шаги, стрелки)

Визуальная отделка:

  • Иконки в маленьких цветных кругах рядом с заголовками разделов
  • Курсивный акцентный текст для ключевых статистик или слоганов

Типографика

Названия шрифтов, которые вы вписываете в .pptx, рендерятся PowerPoint пользователя, а не этой средой. Ваш визуальный QA рендерится через LibreOffice, который подставляет шрифты, которых нет — и для некоторых шрифтов подстановка меняет ширину, так что превью может показывать переполнение (или наоборот) не так, как в реальном деке. Чтобы QA был надёжным:

  • Безопасные шрифты (рендерятся точно по ширине в QA и входят в Office): Arial, Calibri, Cambria, Times New Roman, Courier New, Bookman Old Style, Century Schoolbook. Используйте для основного текста и всего, где важна подгонка.
  • Заголовки с характером и нулевым риском QA: сочетайте безопасный засечковый заголовок (Cambria, Bookman Old Style, Century Schoolbook) с безопасным беззасечным телом (Calibri или Arial). Получаете визуальный контраст без риска ошибок переполнения.
  • Если пользователь просит шрифт вне безопасного списка (например, Georgia или Trebuchet MS): используйте там, где попросил, но делайте контейнеры с запасом (~10%) и не доверяйте QA по подгонке текста — превью приблизительно. Если не указано, предпочитайте безопасные шрифты для тела.
  • Ненадёжные для QA шрифты (подстановка меняет ширину — проверки переполнения могут быть неверны): Georgia, Trebuchet MS, Impact, Arial Black, Garamond, Consolas, Palatino Linotype. Calibri Light зависит от среды; считайте его ненадёжным для QA. Подходят для заголовков/акцентов с запасом; не доверяйте QA по подгонке.
  • Никогда не используйте Aptos по умолчанию — новый стандарт Office после 2023 не имеет совместимой замены здесь и отсутствует в старых версиях Office, так что ненадёжен с обеих сторон.
Элемент Размер
Заголовок слайда 36-44pt жирный
Заголовок раздела 20-24pt жирный
Основной текст 14-16pt
Подписи 10-12pt приглушённый

Отступы

  • Минимум 0.5" полей
  • 0.3-0.5" между блоками контента
  • Оставляйте пространство для дыхания — не заполняйте всё до краёв

Избегайте (частые ошибки)

  • Не повторяйте один и тот же макет — варьируйте колонки, карточки и вызовы на слайдах
  • Не центрируйте основной текст — выравнивайте абзацы и списки по левому краю; центрируйте только заголовки
  • Не экономьте на контрасте размеров — заголовки должны быть 36pt+ чтобы выделяться на фоне 14-16pt тела
  • Не берите синий по умолчанию — выбирайте цвета, отражающие конкретную тему
  • Не смешивайте отступы случайно — выберите 0.3" или 0.5" и используйте последовательно
  • Не оформляйте один слайд, а остальные оставляйте простыми — либо оформляйте все, либо держите всё просто
  • Не делайте текстовые слайды без визуальных элементов — добавляйте изображения, иконки, диаграммы; избегайте простого заголовка + маркеров
  • Не забывайте про отступы в текстовых блоках — при выравнивании линий или фигур с краями текста ставьте margin: 0 в текстовом блоке или смещайте фигуру с учётом отступов
  • Не используйте элементы с низким контрастом — иконки И текст должны иметь сильный контраст с фоном; избегайте светлого текста на светлом фоне или тёмного на тёмном
  • НИКОГДА не используйте акцентные линии под заголовками — это признак слайдов, сгенерированных ИИ; используйте пустое пространство или цвет фона
  • НИКОГДА не добавляйте декоративные цветные полосы или акцентные линии — это включает: полосы в шапке/подвале на всю ширину слайда, вертикальные боковые полосы по краю слайда, тонкие акцентные линии по краю карточки или блока, и «односторонние» рамки на прямоугольниках. Они выглядят как заполнители, сгенерированные ИИ. Чтобы выделить карточку, используйте тонкий фон, тень или иконку — не полоску по краю.
  • Не используйте кремовые/бежевые фоны по умолчанию — если фон не указан, используйте белый (FFFFFF) или палитру бренда пользователя; избегайте тёплых нейтральных по умолчанию вроде F5F5DC, FAF0E6, FAEBD7, FFF8E1
  • Не оставляйте текст, выходящий за границы фигуры — если текст не помещается, уменьшите размер шрифта, разбейте на слайды или увеличьте контейнер; не оставляйте обрезанный или выходящий за пределы контент

QA (обязательно)

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

Контентный QA

markitdown output.pptx

Проверьте отсутствие контента, опечатки, порядок.

При использовании шаблонов проверьте остатки плейсхолдеров:

markitdown output.pptx | grep -iE "\bx{3,}\b|lorem|ipsum|\bTODO|\[insert|this.*(page|slide).*layout"

Если grep что-то вернёт, исправьте до объявления успеха.

Проверка файла (обязательно)

python scripts/office/validate.py output.pptx                      # создан с нуля
python scripts/office/validate.py output.pptx --original src.pptx  # создан из шаблона

Если дек из шаблона, всегда передавайте --original. Шаблон может содержать части, которые XSD отвергает, так что обычный запуск покажет ошибки, которые вы не вызвали — и настоящая регрессия может скрыться среди них. --original сравнивает схему и слайды с шаблоном, подавляя уже существующие ошибки. Структурные проверки — связи, типы контента, диаграммы — игнорируют --original и сообщают о проблемах, унаследованных от шаблона, так что читайте их по существу.

pptxgenjs генерирует XML диаграмм, которые PowerPoint не открывает, а все остальные инструменты принимают: python-pptx открывает такие деки, LibreOffice их рендерит, XSD проходит. Каждая ошибка сопровождается указанием исправления. Исправляйте в генераторе и пересобирайте.

Визуальный QA

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

  • Переполнение текста или обрезка текста по границе блока или слайда — проверяйте в первую очередь. Это самая частая и всегда заметная ошибка. (Для шрифтов, которые превью рендерит ненадёжно по Типографике, превью приблизительно: доверяйте ~10% запасу, а не видимому подгону.)
  • Наложение элементов (текст поверх фигур, линии через слова, наложенные элементы)
  • Источники или колонтитулы, пересекающиеся с контентом сверху
  • Элементы слишком близко (< 0.3" промежутка) или карточки/секции почти соприкасаются
  • Неровные промежутки (большое пустое место в одном месте, теснота в другом)
  • Недостаточные поля от краёв слайда (< 0.5")
  • Колонки или похожие элементы не выровнены по одной линии
  • Текст с низким контрастом (например, светло-серый на кремовом фоне)
  • Украшения шаблона смещены после замены текста — например, подчеркивание заголовка рассчитано на одну строку, а заголовок развернулся на две
  • Иконки с низким контрастом (например, тёмные иконки на тёмном фоне без контрастного круга)
  • Слишком узкие текстовые блоки вызывают чрезмерный перенос
  • Остатки плейсхолдеров

Конвертация в изображения

Конвертируйте презентации в отдельные изображения слайдов для визуального осмотра:

python scripts/office/soffice.py --headless --convert-to pdf output.pptx
rm -f slide-*.jpg
pdftoppm -jpeg -r 150 output.pdf slide
ls -1 "$PWD"/slide-*.jpg

Передавайте абсолютные пути, выведенные выше, напрямую в средство просмотра. rm удаляет устаревшие изображения от предыдущих запусков. pdftoppm нумерует слайды с нуля, добавляя нули в зависимости от количества страниц: slide-1.jpg для деков до 10 страниц, slide-01.jpg для 10-99, slide-001.jpg для 100+.

После исправлений повторите все четыре команды выше — PDF должен быть пересоздан из отредактированного .pptx перед запуском pdftoppm, чтобы изменения отразились.

Зависимости

pptxgenjs (npm, предустановлен — устанавливайте только если require('pptxgenjs') не сработал) · markitdown[pptx], Pillow, defusedxml, lxml (pip — дамп текста, миниатюры, очистка, проверка) · LibreOffice (soffice, автонастройка для песочниц через scripts/office/soffice.py) · pdftoppm (Poppler)