PPT 渲染引擎 (数据模型 → 可编辑PPT · 模板克隆 / 尺寸锚定)

原命名 html2ppt 已不准确 —— 本技能并非"解析 HTML 转 PPT", 已正式更名 pptx-craft。它从一份数据模型渲染可编辑 PPT; HTML / 画布只是用户在过程中可选的"可视化预览兄弟产物", 不参与引擎输入。引擎只认数据。

Positioning (价值观: 数据模型→PPT, 模板为锚点)

• 单一真相源 = 数据模型, 不是 HTML、不是画布。三者(画布/HTML/PPT)都从同一份数据长出来。
• PPT 模板是尺寸锚点。收到请求第一步就确认"有没有专用模板"; 有模板则内容以模板真实可用区为准原生生成, 画布/HTML/PPT 尺寸天然一致。
• "尺寸不匹配能不能自适应"是个伪问题: 当模板作锚点、内容原生生成时, 没有第二个尺寸需要去匹配 —— 自适应 = 以模板为准直接生成, 而非事后缩放去凑。
• HTML 是可选的: 用户可以用 HTML 快速预览版面(尤其技术用户), 也可以直接用画布/表单, 都不影响引擎。引擎吃的是数据。

Overview

Generate editable, pixel-precise PowerPoint files without hand-computing absolute coordinates. The root cause of "PPT 永远做不好排版、永远元素重复、永远没气口" is that PPT / pptxgenjs is an absolute-positioning engine: 50+ elements = 200+ hand-written (x,y,w,h), and one miscalculation cascades into overlap/truncation. Worse, even when coordinates are correct, the gaps (气口) between elements end up too tight because the layout is a single sequential pass that packs elements to "minimal fit".

This skill replaces hand coordinates with a text-first multi-pass layout that simulates how a human actually builds a slide:

人类工作流                        引擎对应 Pass
─────────────────────────────    ──────────────────────────────
1. 按尺寸/比例画区域边框          Pass0   flex 容器(区域框)
2. 先放文字(占地最大),四周留白;    Pass1   文本优先放置(字体度量测高 + pad 气口)
   放不下则缩字号(不删内容)        Pass2   字号自适应(溢出按比例缩,保最小字号)
3. 再放装饰(条/图)填空余空间       Pass3   装饰按"文字块底部+气口"定位(填空者)
4. 初稿→QA→二稿→QA→终稿           Pass4-5 QA 迭代(留白不足全局缩字号重排,最多3轮)

Key guarantee: no overlap, no truncation, and measured breathing room (气口) — the validator refuses to write the file unless every element is in-bounds, non-overlapping across groups, and cross-group gaps meet a MIN_BREATH floor.

When to use

• User needs an editable PPT (not a screenshot image) with high layout fidelity + 气口.
• User explicitly wants "方法3" (text-first flex engine + validator) over "方法1" (screenshot).
• User has a dashboard / report / data page — designed in HTML, a design canvas, OR just a data model / spreadsheet — and wants it re-rendered as a clean editable slide with proper spacing.
• 模板克隆场景: 用户有现成 PPT 模板(公司汇报模板等), 要把内容填进去且继承主题/页脚/logo。
• Do NOT use for one-off quick mockups where a screenshot (方法1) is acceptable — that is faster and lower-cost.

Architecture (6 layers)

① 输入层   : 数据模型(真相源) + 设计令牌(TOKENS) + 间距令牌(SP) + 密度(DENSITY)
             —— HTML/画布是可选的可视化兄弟产物, 不进引擎输入
② 虚拟画布 : 1440×680 px 抽象坐标空间(可随目标比例重设 VW/VH), 均匀缩放+居中 映射目标可用区
③ 容器系统 : Row/Column + flex 权重, 仅用于"区域框"层级(区域内部改文本优先)
④ 组件库   : KpiCard / CompareCard / build_chart / build_progress  —— 内部文本优先, 装饰填空
⑤ 文本优先布局 : layout_texts() 字体度量测高 + 上下左右 pad 气口 + 字号自适应(保最小,不删内容)
⑥ 校验层   : 写文件前强制 越界 + 跨组重叠 + 留白下限(防拥挤) 检测; 不过则拒绝产出(终稿轮)
⑦ QA迭代器 : 初稿→二稿→终稿, 用留白提示驱动全局字号缩放(G_TS)

气口(呼吸感)是怎么解决的 (v3 三条杠杆):

1. 文本优先 + 字体度量: 文字先"占地"，上下左右按 pad 留气口、多文字间按 breath 留气口， 尺寸由字体度量真实估算（宁多勿少，文字绝不裁切），不再"塞满即止"。
2. 间距令牌 + 密度系数: 所有 gap/padding 取自 SP 阶梯表，由 DENSITY 整体缩放 （1.0 紧凑 / 1.2 舒适 / 1.4 宽松）—— 调一个旋钮即可整体松紧，不用逐块挪。
3. QA 迭代器: 若终稿仍有留白提示，全局缩小字号 G_TS（每轮 -0.06）重排，最多 3 轮， 用"规则+迭代"替代"人眼反复截图调"。

Workflow

⚠️ Step 0 — 确认有无专用 PPT 模板 (MANDATORY, 任何技能请求的第一步)

收到技能请求时, 第一件事就是问用户: "你有没有专用 PPT 模板？" 不要先谈 HTML 尺寸、不要先问画布比例 —— 模板才是唯一锚点。这个回答决定整个输入契约与引擎首动作。

为什么先问模板 (尺寸一致性的根因): PPT 翻车第一因是"生成物与目标模板尺寸/比例不一致 → 复制进去变小/错位"。当模板作锚点, 内容永远按模板本身的真实可用区原生生成, 不存在"另一个尺寸去匹配"的对象 —— 于是"HTML尺寸和PPT尺寸不匹配、能不能自适应"这个伪问题从根上消失: 自适应不是去匹配, 而是以模板为准直接生成。

Branch A — 无专用模板 (use_generic: true)

• WB 自行设计/加载内置通用模板(默认标准16:9, 33.87×19.05cm, 含内置主题token)。
• 引擎动作: 新建 Presentation + 设尺寸 + 文本优先多遍 + QA。
• 仅需确认输出比例(默认16:9), 无需路径。

Branch B — 有专用模板 (has_template: true) — 用户只需提供:

1. template_path (必填): 真实 .pptx 模板路径。
2. start_page (可选, 默认自动探测首个"正文页"): 内容从这一页开始生成; 模板封面/目录/结构页(P1-3等)一律不动。

• 可用区由 WB 自动测量, 用户无需画框、无需报尺寸: 引擎加载模板 → 扫描目标页及其版式(layout)/母版(master)的已有形状 → 按规则算可用区:
  • 左右: 按 PPT 模板尺寸各留 MARGIN_CM(默认1cm) → x∈[M, W-M]。
  • 上下: 在模板已有元素基础上算(内容不得压已有元素), 各留 MARGIN_CM:
    • 排除面积≈整页的形状(全屏背景图), 避免误判为障碍物;
    • 形状中心在上半=页眉区取 max(页眉底)+M, 在下半=页脚区取 min(页脚顶)-M;
    • 无页脚页 bottom 回退 H-M; 溢出续页时对后续页用同规则重算。
  • 必须同时扫描 slide.shapes + slide.slide_layout.shapes(页眉页脚通常在版式上, 漏扫会压页脚)。
• 引擎动作: Presentation(template_path) → 克隆 → 在算出的可用区原生生成内容(直接 add 进 spTree, 零复制粘贴)。主题/字体/页脚/logo 全继承。
• (可选硬覆盖) 极少数模板自动测量不准时, 才退化为用户在模板里标命名形状 CONTENT_AREA 或手填包围盒 (x_cm,y_cm,w_cm,h_cm)。

经验: 曾用「缩放粘贴」(整页生成→×0.796缩放进可用区) 导致"整体小一圈"; 正确范式是虚拟画布直接映射到可用区 + 原生生成, 字号走 px→pt 不随区域缩小。

Reference sizes (used by Branch A default or as sanity check):

Step 1 — Define tokens and data (single source)

Set TOKENS (colors/fonts/radii) and a DASHBOARD_DATA-style model. This is the single source of truth — keep it consistent with any HTML/canvas sibling so all outputs stay aligned (but HTML/canvas are optional previews, not inputs). If the data is "live", pass a snapshot at export time (PPT is a period snapshot, not realtime).

Step 2 — Build the virtual canvas + coordinate mapper

Use VW,VH as the virtual pixel canvas. VW/VH should be derived from the target available area's aspect ratio (not hardcoded to one size) so the layout re-flows natively:

• Branch A (generic): VW,VH → slide size aspect; SCALE = min(SLIDE_W/VW, SLIDE_H/VH), OFFX centers.
• Branch B (template clone): set VW=1440, VH=round(area_h/area_w*1440), SCALE=area_w/VW, and OFFX/OFFY = available-area top-left EMU — content placed inside the frame, natively. Map with uniform scale + area anchoring (no vertical squeeze). Helpers X/Y/W_/H_/FS convert virtual px → EMU/pt. Slide size: prs.slide_width = Emu(target_cm * 360000) (Branch A only; Branch B reuses template size).

Step 3 — Lay out regions with flex containers (never raw coordinates)

Use hbox(deck, box, items, gap, pad) and vbox(deck, box, items, gap, pad) to carve region frames only. Each item is {"flex": n, "size": px, "group": "g", "build": fn}. The engine computes child positions from weights — change a parent's height and children reflow. Note: flex is used for the region level; inside each card the layout switches to text-first (Step 4).

Step 4 — Compose with the component library (TEXT-FIRST inside)

Call KpiCard, CompareCard, build_progress, build_chart. Each card:

1. draws its background rect,
2. calls layout_texts(deck, items, box, pad, breath, ...) which:
   • measures each text block height via text_h() (font metrics, CJK-aware),
   • places text top-down with pad (outer) + breath (between) 气口,
   • if total exceeds box height, binary-searches a uniform scale to shrink all fonts (each keeps its min_fs — content never deleted),
   • returns the leftover space below the text,
3. draws decorative elements (bars/chips/legend) into that leftover space — decorations are "fillers", never the cause of overlap.

This is the core fix for "标题贴边 / 标签没气口 / 批次条拥挤": text owns the space first, decorations fill what's left.

Step 5 — Run the validator BEFORE saving

validate(deck.recs) returns (errors, warnings) and checks three things:

1. 越界 — every element within the target area bounds;
2. 跨组重叠 — any two elements of different groups that geometrically intersect (same-group = text nested in its card, which is allowed);
3. 留白下限 (防拥挤) — any two adjacent cross-group elements whose edge-to-edge gap is < MIN_BREATH (default 10px) is reported as a warning.

If errors non-empty → raise, do not write the file. Warnings do not block (tuning hints for DENSITY/G_TS) but a clean run reports "留白校验通过".

Step 5b — Tune 气口 (no coordinate edits)

Three knobs, in increasing strength:

• SP_RAW ladder + DENSITY (1.0/1.2/1.4) — global spacing scale; sp(k) = SP_RAW[k]*DENSITY.
• pad / breath args inside layout_texts — per-card inner 气口.
• G_TS (driven by QA iterator) — global font-size scale when gaps still too tight.

The engine also emits preview.svg (virtual-coord 1:1) so you can eyeball 气口 without opening PowerPoint.

Step 6 — Render and save

deck.render(slide) iterates recorded ops into python-pptx shapes. Set slide background fill, then prs.save(out).

• Branch A: save as a new standalone file.
• Branch B: save the cloned template (content already inside the available area) — the output file is the user's template, filled.

The bundled engine

scripts/pptx_flex_engine.py is a complete, runnable reference implementation (the switch-migration dashboard case) using the v3 text-first multi-pass architecture.

• Run directly: python scripts/pptx_flex_engine.py → produces migration-dashboard-m3-v4.pptx
  • migration-dashboard-m3-preview.svg (standard 16:9, 33.87×19.05cm single-page editable deck).
• Before running, resolve Step 0:
  • Branch A (no template): the script's defaults already target standard 16:9 — just run.
  • Branch B (has template): pass template_path (+ optional start_page); the engine auto-measures the template's available area (scans slide + layout shapes) and fills it natively — no CONTENT_AREA box or manual dimensions needed.
• Adapt: replace KPI / CMP / BATCHES / DAYS data + build_* functions with target content; keep TOKENS, hbox/vbox, layout_texts, Deck, and validate unchanged.
• Prereqs: python-pptx (pip install python-pptx). Uses Microsoft YaHei for editable Chinese text on Windows.

Key rules (non-obvious, learned from real failures)

• 🔴 Step 0 is mandatory — 第一件事就问"有专用模板吗?": 模板是尺寸锚点。Branch A 自设计通用16:9; Branch B 用户给 template_path(+可选 start_page), WB 自动扫描模板算可用区(无需画框/报尺寸), 原生生成进 spTree。模板克隆让 PowerPoint 复制粘贴过时(无坐标漂移, 风格自动继承)。 → 因此"画布/HTML/PPT 尺寸一致性"由模板锚点天然保证, "尺寸不匹配"伪问题消失。
• 可用区自动测量规则: 扫描 slide.shapes + slide.slide_layout.shapes + (必要时) slide.master.shapes; 排除全屏背景; 上下按已有元素留 MARGIN_CM; 漏扫 layout 会压页脚(页眉页脚多在版式上)。
• content_area 是盒不是尺寸(仅当自动测量不准时作硬覆盖): 手填须问左上偏移。
• Never hand-write (x,y,w,h) for leaf elements — declare structure, let the engine compute.
• Text-first, not decoration-first: always place text (with 气口) before bars/chips; decorations fill leftover space. This is what killed the "标题贴边/标签没气口" bugs.
• Font metrics over eyeballing: text_h() estimates CJK-aware line height; tune the 0.98/0.55/0.30 width factors if a font renders differently, but keep them conservative (prefer slightly-too-tall over clipping).
• Auto-shrink but never delete: min_fs per text item guarantees content survives even when the frame is tight — the QA iterator then relaxes spacing globally.
• Always give each card a distinct group so the validator can tell nested-text from real overlap. Forgetting this yields false overlap errors or missed collisions.
• Uniform scale + area anchoring (not non-uniform): prevents the vertical squeeze that makes PPT feel tighter than the HTML source.
• Method 1 vs 3 split: method 1 (screenshot) for urgent/low-stakes reporting; method 3 (this engine) for anything where the user must edit text in PowerPoint or demands zero-drift layout with proper 气口.

产品命名体系 (上传 WB 用, 2026-07-22 定稿)

为把"个人孵化 → 多场景覆盖 → 产品/专家化"这条路径固化, 命名分三层, 彼此解耦:

• 技能 pptx-craft 是地基: 不挑使用者, 只吃结构化数据 (人格无关)。
• 专家团 ppt-studio 是人格封装: 同一引擎, 不同上车点 ——
  • 技术流专家 (吃 HTML / 数据模型, 适合你本人)
  • 零代码专家 (吃画布 / 表单, 适合非技术同事)
• 子专家 = 把"文本优先多遍"的每一遍拆成独立角色, 由 ppt-studio 编排专家串起来:
  • 版式专家 (布局/flex/气口) · 数据专家 (源适配器: HTML/画布/表单→数据模型) · QA专家 (校验/迭代) · 主题专家 (美化/模板主题 token)。

命名原则: 名称落到"能力本质"(数据驱动 / 可编辑 / 工艺感), 而非"输入介质"(HTML); 因此强烈建议不要回退到 html2ppt 这类介质名, 以免重新埋下"引擎解析 HTML"的预期坑。