pptx-html-fidelity-audit

PPTX ↔ HTML Fidelity Audit

一套可重複執行的工作流程，用於捕捉 python-pptx 匯出時相較於 HTML 來源檔靜悄悄產生的版面偏離，並透過嚴謹的排版規範進行修復，防止下一次匯出時重蹈覆轍。

何時適用此 Skill

當使用者符合以下條件時：

• 擁有一份 HTML 來源簡報檔（通常是包含 <section class="slide"> 區塊的單一檔案）：

  <section class="slide light">
    <div class="chrome">2026 · Q2 review</div>
    <span class="kicker">Pillar 03</span>
    <h2 class="h-xl">Shipping <em>velocity</em> doubled</h2>
    <p class="lead">…</p>
    <div class="foot">page 5 / 14</div>
  </section>
  

• 擁有透過 python-pptx（或類似工具）從該 HTML 簡報檔生成的 PPTX 檔案。

• 懷疑（或已有視覺證據）PPTX 與 HTML 不符——文字重疊到頁尾、斜體字變成正體、Hero 主頁沒有居中、章節被裁切、標籤樣式遺失等。

如果使用者只提供上述 其中一種 檔案，則此 Skill 尚不適用——請先生成缺失的檔案，或請使用者提供。

為什麼這很困難（以及 Skill 能提供什麼協助）

PPTX 是固定畫布、絕對定位的介質；HTML 則是流式、流向為主的介質。天真的 python-pptx 匯出腳本會把每個區塊釘在人工挑選的 (top, left) 座標上，這在 第一張測試的投影片 上看起來很完美，但遇到其他內容高度不同的投影片時就會默默失敗。這會導致最常見的幾種偏離模式：

1. 頁尾溢出（Footer overflow） — 內容的 top + height 踩進了頁尾列。
2. 超出畫布（Off-canvas content） — 最後一個區塊的底部超過了 7.5"（16:9 畫布極限）。
3. 斜體遺失（Italic loss） — HTML 中的 <em> 從未被套用 run.font.italic = True。
4. Hero 頁面未居中（Hero slides not centered） — 垂直堆疊的頁面使用了 MARGIN_TOP 而不是動態計算中央位置。
5. 區塊外框侵入（Box bounds intruding） — 文字本身沒超出，但 文字框外框（bounding box） 過大，視覺上跨越了安全軌道。
6. 標籤/樣式遺失（Tag/styling loss） — 著色的頂部欄、小標題大寫字距（kicker uppercase tracking）、等寬/襯線字型的指定默默退回到預設值。

以上每一項都是 排版紀律（layout discipline） 問題，而不是內容本身的問題。只要建立起排版紀律，這些問題就不會再發生。

---

工作流程

稽核共分為五個步驟。請勿跳過任何一步——唯有稽核產出真實的問題清單來指導重新匯出，排版紀律才能發揮作用。未經稽核就直接修復，通常會遺漏一半以上的排版缺陷。

步驟 1 — 從 PPTX 提取真實資料（Ground Truth）

執行 scripts/extract_pptx.py <path-to.pptx> > pptx_dump.json。腳本會巡覽每張投影片上的每一個形狀（shape），並 dump 出文字、位置（top / left）、尺寸（width / height）以及每個 Run 的字體排印資訊（字型名稱、字型大小 pt、粗體、斜體、顏色）。這才是匯出結果的 真實 狀態——不要相信匯出腳本的原意，請相信 dump 出來的數據。

以 14 頁的簡報檔為例，dump 出來的 JSON 大約為 30–60 KB，且人類可讀。

步驟 2 — 梳理 HTML 結構

讀取 HTML 來源檔並枚舉 <section class="slide"> 區塊。針對每一頁記錄：

• 投影片的主題（light / dark / hero light / hero dark）。
• chrome 列的文字（頂部中元資訊/頁首）。
• kicker（標題上方的大寫小標題）。
• 主標題（h-hero / h-xl 等）與副標題。
• 正文內容與結構化區塊（流水線步驟、卡片、支柱區塊、觀察卡片）。
• foot 列（頁尾中元資訊）。
• 任何 <em> 或斜體樣式的 span — 斜體是最容易被忽略的退化點。

將每個 HTML 投影片對映到 PPTX 投影片索引。對於遵循「投影片 1 = 封面，投影片 N = 結尾」規範的簡報，此對映為按順序一一對應。

步驟 3 — 建立稽核表格（Audit Table）

針對每張投影片，對照 dump 中的形狀並檢查是否符合預期版面規則。請嚴格採用以下表格格式——嚴重程度（severity）欄位將決定修復的優先順序：

| Slide | Issue | Severity |
|---|---|---|
| 1 cover | meta-row 底端 6.95" 蓋過 footer (6.7") | 🔴 |
| 5 checklist | row B 步驟描述底端 7.2" 切到 footer | 🔴 |
| 8 3E | 收束段落直接坐在 footer 起點 | 🔴 |
| 9 on-day | step 描述底端剛好碰 footer，無安全距 | 🟠 |
| 多處 | em (Playfair italic) 未保留 | 🟡 |

嚴重程度分級判定標準：

• 🔴 critical — 內容被裁切、文字不可見、頁尾重疊、超出畫布。必須修復。
• 🟠 high — 內容可見但視覺層級錯亂、缺乏呼吸感、Hero 主頁未居中。應當修復。
• 🟡 medium — 遺失斜體/em、字型退化錯誤、顏色偏離。本次修復一併處理。
• 🟢 low — 微小的間距/對齊問題、次像素位移。記錄但不安裝為阻礙項。

表格下方請附上一段簡短的根本原因分析（Root Cause）：90% 的問題通常來自 2–3 個系統性原因（例如：「未強制執行頁尾安全軌道」、「Hero 垂直堆疊直接釘在 MARGIN_TOP 而非置中」、「斜體樣式從未傳遞」）。找出系統性原因能讓重新匯出的腳本更加精簡且精準。

步驟 4 — 依循頁尾軌道 + 游標流向排版規範重新匯出

這是最核心的技術。完整規則請參閱 references/layout-discipline.md；概要如下：

在最前端為整份簡報統一定義邊界軌道：

from pptx.util import Inches

CANVAS_W       = Inches(13.333)   # 16:9
CANVAS_H       = Inches(7.5)
MARGIN_X       = Inches(0.6)
MARGIN_TOP     = Inches(0.5)
CONTENT_MAX_Y  = Inches(6.70)     # 內容區域的任何物件皆不可越過此界線
FOOTER_TOP     = Inches(6.85)     # 頁尾列固定於此，滿版延伸

自訂軌道參數： 上述預設值適用於帶有精簡頁尾的 16:9 畫布。若你的設計系統採用較寬的頁尾或 4:3 畫布，請在匯出腳本中覆寫這些常數，並透過 --content-max-y / --canvas-h / --canvas-w 將相同數值傳遞給 verify_layout.py。詳情請參見 references/layout-discipline.md §1 常數對照表。

針對內容區塊採用游標（Cursor）計算位置，而非直接指定絕對 y 座標：

class Cursor:
    """沿投影片向下推進；拒絕跨越頁尾安全軌道。"""
    def __init__(self, y_start, cap=CONTENT_MAX_Y):
        self.y = y_start
        self.cap = cap
    def take(self, h, gap=Inches(0.12)):  # ~14pt 字型下的 1 行留白；可依設計系統微調
        top = self.y
        self.y = top + h + gap
        if self.y > self.cap:
            raise OverflowError(
                f"cursor at {self.y} exceeds footer rail {self.cap}; "
                f"reduce block height or split slide"
            )
        return top

每張投影片皆實例化 Cursor(MARGIN_TOP)，並按閱讀順序呼叫 take(height) 取得各區塊位置。任何區塊若會越過軌道，投影片就會直接拒絕渲染，使版面溢出變成顯眼的建置錯誤（build error），而非靜悄悄的視覺 bug。

Hero（垂直置中）頁面使用預算制（Budget）而非游標制：

def hero_layout(blocks):
    """blocks = 依閱讀順序排列的 (height, gap_after) 元組清單。"""
    total = sum(h + g for h, g in blocks)
    y_start = (CANVAS_H - total) / 2
    return Cursor(y_start)

這項改動可徹底解決最常見的 Hero 頁面瑕疵——「Hero 頁面內容黏在頂部」。

收緊文字框高度，僅保留文字 + 極小 padding。 當形狀重疊時 PowerPoint 會顯露區塊邊界（選取光暈、Z 軸順序衝突），過大的文字框即使內部文字沒超出，視覺上也可能跨越頁尾軌道。請根據文字度量 + 約 0.05" 的 padding 計算框高，而非使用過於寬鬆的外包覆層。

明確保留斜體 / em：

def add_run(p, text, font, size_pt, italic=False, bold=False, color=None):
    r = p.add_run()
    r.text = text
    r.font.name = font
    r.font.size = Pt(size_pt)
    r.font.italic = italic
    r.font.bold = bold
    if color:
        r.font.color.rgb = color
    return r

遍歷 HTML 時，偵測 <em> / <i> / 內聯樣式 font-style: italic 並傳入 italic=True。對於斜體展示文案，請使用英文襯線字型（Playfair Display、Source Serif 或備用 Georgia）——中日韓（CJK）襯線字型通常沒有斜體，硬套斜體樣式會顯得破綻百出。

對於版面安全軌道無法捕捉到的更深層字型問題——例如 PowerPoint 默默替換為 Calibri / Microsoft JhengHei（微軟正黑體）的可變字型陷阱、缺少 <a:ea> 欄位導致中日韓字元退回預設字型、漢字偽斜體等——請閱讀 references/font-discipline.md。當中的五層檢查法涵蓋了 verify_layout.py 無法檢測到的一切問題。

步驟 5 — 匯出後驗證（Post-export verification）

寫入新的 .pptx 之後，執行 scripts/verify_layout.py <path-to.pptx>。該腳本會：

• 巡覽每張投影片上的每一個形狀。
• 斷言內容形狀滿足 top + height ≤ CONTENT_MAX_Y（允許頁尾/頁碼形狀位於軌道下方）。
• 斷言所有形狀滿足 top + height ≤ CANVAS_H（無超出畫布）。
• 斷言 left + width ≤ CANVAS_W 且 left ≥ 0。
• 以單一區塊回報違規項目：投影片索引、形狀名稱、實測底端、軌道界線。

零違規是「該重新匯出的檔案可供交付」的必要關卡。切勿在未執行驗證腳本前宣稱修復完成——肉眼在縮小檢視時容易忽略 1–2 mm 的溢出，但腳本不會。

---

交付給使用者的輸出內容

步驟 5 通過後，請回報以下內容：

1. 稽核表格 — 步驟 3 中產出的表格。
2. 根本原因 — 一段話說明系統性原因。
3. 修復清單 — 簡潔說明修復了什麼及原因（例如：「Hero 頁面改用預算制置中」、「所有內容區塊皆改經由 Cursor 處理」、「em 區段明確設定斜體」）。
4. 驗證結果 — 「跨 N 頁投影片 0 次違規，檔案大小 X KB」。
5. 檔案路徑 — 重新匯出的 .pptx 絕對路徑。

使用者閱讀報告的理由有二：確認可見的 bug 已修復，以及相信系統性修復是正確的。兩者皆需涵蓋。

---

隨附資源（Bundled resources）

• scripts/extract_pptx.py — 將每張投影片上的每個形狀 dump 為 JSON。在稽核前執行。重要： 亦需在 原始 匯出檔與 重新匯出 的檔案上執行以進行比對與確認。
• scripts/verify_layout.py — 匯出後的軌道檢查器。發現違規時返回非零 Exit Code，便於整合至 CI 流程中。
• references/layout-discipline.md — 完整的頁尾軌道 + 游標流向規則集，包含常見投影片類型（Hero、內容頁、流水線、雙欄、觀察網格）的程式碼片段。
• references/font-discipline.md — 五層字型稽核法：對映、存在性、可變 vs 靜態字型陷阱、三個 XML 語言欄位（latin / ea / cs）、中日韓 + 拉丁斜體互動。
• references/audit-table-template.md — 可直接複製貼上的稽核表格範本（含嚴重程度圖例）。

在以下情況時閱讀 reference 文件：

• 簡報包含了 SKILL.md 涵蓋範圍之外的投影片類型（多欄 Dashboard、內嵌圖片、圖表）→ layout-discipline.md。
• 稽核顯示有 🟡 字體排印問題 — 遺失斜體、中日韓字型退級、XML 中出現意料之外的 Calibri / Microsoft JhengHei → font-discipline.md。
• 想要直接將稽核表格貼入報告或 Markdown 交付文件中 → audit-table-template.md。

---

應避免的反模式（Anti-patterns to avoid）

• 僅修改個別投影片而未指出系統性原因。 如果你透過將第 5 頁的區塊下移 0.2" 來修復它，你接下來很快又得回頭修復第 9、11 與 14 頁。請找出產生這四個問題的通用規則。
• 相信...