PPTskills

中文说明见下方，English version follows right after.

中文

PPTskills 是一个面向 Codex 的 PPT 生成工具仓库，核心目标是把“生成 PPT”这件事做得更稳定、更可编辑、更适合持续迭代。

这个仓库目前提供两条主要路线：

• HTML/CSS -> PPTX 适合追求视觉还原度、复杂排版、网页式设计感。
• Schema JSON -> PPTX 适合追求 PowerPoint 原生可编辑性、文字清晰度和版式稳定性。

仓库里还带了一个本地 Python 编辑器，以及一个可复用的 Codex skill，方便让 Codex 按统一规范产出 deck。

仓库结构

• html2ppt/html2ppt/SKILL.md Codex skill 说明，负责告诉 Codex 什么时候走 HTML 路线，什么时候走 schema 路线。
• html2ppt/html2ppt/scripts/html2ppt.py HTML 导出 PPTX 的脚本，使用 Playwright 渲染并做导出前校验。
• html2ppt/html2ppt/scripts/schema2ppt.py Schema 导出 PPTX 的脚本，生成 PowerPoint 原生文本框、形状、线条、图片。
• html2ppt/html2ppt/scripts/deck_editor.py 本地编辑器，支持 HTML deck 的预览、校验、保存和导出。
• html2ppt/html2ppt/scripts/searxng_research.py 可选研究脚本，用于搜集事实、图片线索和研究素材。
• qin-unifies-six-states.html 示例 HTML deck 源文件。
• qin-unifies-six-states.schema.json 示例 schema deck 源文件。

为什么要分两条路线

1. HTML 路线

适合这些情况：

• 需要高度还原设计稿
• 依赖复杂 CSS、SVG、网页式布局
• 最终更关注“交付效果”，而不是 PowerPoint 内部二次编辑

代价：

• 导出的 PPT 主要是图片化幻灯片，文本和图形不是原生可编辑对象

2. Schema 路线

适合这些情况：

• 需要在 PowerPoint 里继续修改文案或布局
• 需要更清晰的文本和更稳定的模板结构
• 需要把标题、卡片、时间线、图形块做成原生对象

代价：

• 表现力会比纯 HTML/CSS 受限一些，但稳定性和可编辑性更好

比例与稳定性规范

当前支持的比例预设：

比例	HTML 画布	PPT 尺寸
16:9	1280x720	13.333 x 7.5 in
4:3	1024x768	10 x 7.5 in
16:10	1280x800	12 x 7.5 in
3:2	1200x800	11.25 x 7.5 in
1:1	1080x1080	7.5 x 7.5 in

默认使用 16:9。

为了让生成更稳定，HTML deck 建议始终遵守这些规则：

• 一页幻灯片对应一个 section.slide
• 每一页都按最终导出尺寸进行设计
• 明确设置 width、height、overflow: hidden
• 使用统一的颜色、字号、间距 token
• 正文字号尽量保持在 22px 到 28px
• 内容拥挤时拆页，不要强行塞进一页

详细规范见：

• html2ppt/html2ppt/references/html-slide-contract.md
• html2ppt/html2ppt/references/schema-slide-contract.md

安装

建议使用 Python 3.11 或更高版本。

安装依赖：

python3 -m pip install -r requirements.txt

安装 Playwright Chromium：

python3 -m playwright install chromium

快速开始

1. 校验 HTML deck

python3 html2ppt/html2ppt/scripts/html2ppt.py qin-unifies-six-states.html --ratio 16:9 --validate-only --strict

2. 导出 HTML -> PPTX

python3 html2ppt/html2ppt/scripts/html2ppt.py qin-unifies-six-states.html --out qin-unifies-six-states.pptx --ratio 16:9 --strict --render-scale 2

如果你更在意清晰度，可以把 --render-scale 提高到 3，但文件会更大。

3. 导出可编辑 schema -> PPTX

python3 html2ppt/html2ppt/scripts/schema2ppt.py qin-unifies-six-states.schema.json --out qin-unifies-six-states-native.pptx

4. 打开本地编辑器

python3 html2ppt/html2ppt/scripts/deck_editor.py qin-unifies-six-states.html --ratio 16:9

这个编辑器适合：

• 边写 HTML/CSS 边预览
• 在导出前做规范校验
• 用统一模板快速起新 deck

Codex Skill

可复用的 skill 位于：

html2ppt/html2ppt

它的作用包括：

• 根据需求自动选择 HTML 或 schema 工作流
• 统一管理幻灯片比例
• 约束 HTML/CSS 的设计规范
• 在需要可编辑 PPT 时优先走 schema 路线
• 在需要迭代时调用本地编辑器

提交策略

这个仓库默认只提交“源文件”和“工具代码”，尽量不提交生成产物。

默认不建议提交的内容：

• 导出的 .pptx
• 研究中间结果 research/*.json
• 本地缓存和 Python 编译产物

这样仓库会更干净，也更适合作为工具库长期维护。

English

PPTskills is a Codex-oriented toolkit for generating PowerPoint decks in a way that is more stable, more editable, and easier to iterate on.

The repository currently supports two main workflows:

• HTML/CSS -> PPTX Best when visual fidelity and expressive layout matter most.
• Schema JSON -> PPTX Best when native PowerPoint editability and layout stability matter most.

It also includes a lightweight local Python editor and a reusable Codex skill so Codex can generate decks under a consistent contract.

Repository Layout

• html2ppt/html2ppt/SKILL.md Codex skill instructions for choosing between the HTML and schema workflows.
• html2ppt/html2ppt/scripts/html2ppt.py HTML-to-PPTX exporter with Playwright rendering and pre-export validation.
• html2ppt/html2ppt/scripts/schema2ppt.py Schema-to-PPTX exporter that creates native PowerPoint text boxes, shapes, lines, and images.
• html2ppt/html2ppt/scripts/deck_editor.py Local editor for previewing, validating, saving, and exporting HTML decks.
• html2ppt/html2ppt/scripts/searxng_research.py Optional research helper for collecting facts, references, and image leads.
• qin-unifies-six-states.html Example HTML deck source.
• qin-unifies-six-states.schema.json Example editable schema source.

Why Two Workflows

1. HTML workflow

Use this when you want:

• high visual fidelity
• expressive CSS, SVG, and web-style composition
• delivery-focused slides that look exactly as designed

Tradeoff:

• the exported PPT is mostly image-based, so text and shapes are not natively editable

2. Schema workflow

Use this when you want:

• editable text and shapes inside PowerPoint
• crisp typography and stronger structural stability
• reusable presentation templates built from native objects

Tradeoff:

• the visual language is more constrained than free-form HTML/CSS

Ratio And Stability Rules

Supported ratio presets:

Ratio	HTML canvas	PPT size
16:9	1280x720	13.333 x 7.5 in
4:3	1024x768	10 x 7.5 in
16:10	1280x800	12 x 7.5 in
3:2	1200x800	11.25 x 7.5 in
1:1	1080x1080	7.5 x 7.5 in

Default is 16:9.

For stable HTML deck generation, follow these rules:

• one slide per section.slide
• author every slide at final export size
• set explicit width, height, and overflow: hidden
• use tokens for spacing, color, radius, and typography
• keep body text around 22px to 28px
• split crowded slides instead of compressing them

Detailed contracts:

• html2ppt/html2ppt/references/html-slide-contract.md
• html2ppt/html2ppt/references/schema-slide-contract.md

Setup

Python 3.11+ is recommended.

Install dependencies:

python3 -m pip install -r requirements.txt

Install the Playwright Chromium runtime:

python3 -m playwright install chromium

Quick Start

1. Validate an HTML deck

python3 html2ppt/html2ppt/scripts/html2ppt.py qin-unifies-six-states.html --ratio 16:9 --validate-only --strict

2. Export HTML -> PPTX

python3 html2ppt/html2ppt/scripts/html2ppt.py qin-unifies-six-states.html --out qin-unifies-six-states.pptx --ratio 16:9 --strict --render-scale 2

Raise --render-scale to 3 if you want sharper screenshot-based output and accept a larger file.

3. Export editable schema -> PPTX

python3 html2ppt/html2ppt/scripts/schema2ppt.py qin-unifies-six-states.schema.json --out qin-unifies-six-states-native.pptx

4. Launch the local editor

python3 html2ppt/html2ppt/scripts/deck_editor.py qin-unifies-six-states.html --ratio 16:9

The editor is useful for:

• live HTML/CSS preview while editing
• contract validation before export
• bootstrapping new decks from a controlled template

Codex Skill

The reusable skill lives at:

html2ppt/html2ppt

It helps Codex:

• choose the right workflow for the request
• keep slide ratios consistent
• enforce HTML/CSS design guardrails
• prefer the schema route when editability matters
• use the local editor for iterative deck work

Commit Policy

This repository is intended to track source files and tooling, not generated artifacts.

By default, it should avoid committing:

• exported .pptx files
• intermediate research outputs in research/*.json
• local caches and Python build artifacts

That keeps the repository leaner and makes it easier to maintain as a toolkit.