html-to-pptx
何時觸發
用戶說出下列任一意圖:
- "把這個 HTML / 網頁 deck 轉成 PPT / pptx"
- "做了 HTML 幻燈片,要給同事一份 ppt"
- "彙報現場不方便放瀏覽器,想要 ppt 檔案"
- 已有 HTML 檔案路徑 + 提到 ppt / pptx / 簡報 / 幻燈片
調用
<skill_dir> 是這個 skill 安裝路徑(通常 ~/.claude/skills/html-to-pptx/,Windows 上是 %USERPROFILE%\.claude\skills\html-to-pptx\)。下面命令裡的 <skill_dir> 替換成實際路徑,或者先 cd <skill_dir> 再直接 python convert.py …。
python <skill_dir>/convert.py <input.html>
- 預設輸出到與輸入同目錄的
<input>.pptx - 字體完全按需:HTML 用到的字體在 convert 時從 Google Fonts 拉取並 subset 嵌入,快取到
%LOCALAPPDATA%\html-to-pptx\fonts\或~/.cache/html-to-pptx/fonts/,下次同名同體秒復用 - HTML 包含 CJK 字元會自動種子 Noto Sans SC + Noto Serif SC(首次約 40 MB / ~30s 下載並 instance 靜態 Regular/Bold,之後命中 cache)
- GF 沒有的家族會回退到 viewer 系統字體並列印 warning
| 選項 | 含義 |
|---|---|
--out <path> | 自訂輸出 .pptx 路徑 |
--keep-screenshots | 同時保留每頁 HTML 參考截圖 + preflight.json |
--no-embed-fonts | 跳過字體嵌入。檔案更小但換機會回退到系統字體 |
--no-preflight | 關閉 Stage 1 風險預掃 |
--no-verify | 關閉 Stage 5a 結構化自檢 |
--no-visual-audit | 關閉 Stage 5b 視覺 audit 物料產出。日常不要關 |
--install-user-fonts | 把自動解析到的非 CJK 字體裝到用戶字體目錄(讓 WPS 能正確渲染)。Win/macOS/Linux 都支援。必須先問用戶,見下方"配置確認"章節 |
--only-slides N,N,N | 增量重跑。逗號分隔的頁號(1-based)。measure 只跑指定頁 + 與上輪 cached measurement 合併;assemble/embed 仍全量;Stage 5a 只渲指定頁;Stage 5b 只重建指定頁的 compare 圖——其它頁全部復用上輪快取。audit 迭代輪專用,詳見下方"增量重跑"章節 |
--cleanup | 不做轉換。刪 input.pptx 旁的 audit / measurement / preflight 工作物,只保留 .pptx 和 audited.html。最終交付前用,見下方"工作流"末步 |
工作副本(原 HTML 不動)
第一次 python convert.py <input>.html 跑完,convert.py 自動 cp 一份 <input>.audited.html 到源 HTML 同目錄。機制:
- 所有 audit 修復改
audited.html,不改源 HTML - 後續輪 convert(含
--only-slides)input 用<input>.audited.html,輸出仍是<input>.pptx(自動去掉.audited後綴) audited.html已存在 → 復用,不覆蓋(保留上輪修復)- agent 誤傳源 HTML 當 input → convert.py 內部檢測後切到 audited.html 兜底
- cleanup 不刪 audited.html(視為可交付副產物,跟
.pptx一組交付) - 想從頭開始 → 手動刪 audited.html 後重跑
配置(.config.local.toml)
skill 根目錄下可選的本機偏好檔案,gitignored,每用戶一份。當前有三類偏好:
[fonts]
auto_install = "ask" # "yes" 自動裝、"no" 永不裝、"ask" 由 agent 詢問
[cleanup]
default = "clean" # "clean" 工作流末步自動 cleanup、"keep" 保留 audit 產物
[audit]
mode = "ask" # "triage" / "page" / "manual" / "ask" 由 agent 詢問
- 檔案 / key 缺失 → 走預設(同上)
- 模板:
<skill_dir>/.config.local.toml.example fonts.auto_install由 convert.py 強制讀取並應用(=yes 自動加--install-user-fonts、=no 自動忽略)cleanup.default由 agent 在工作流末步讀取決定行為audit.mode由 agent 在第一次 convert 前確認;Stage 5b 後按該值執行審查:"triage"→ 主 agent 自己看audit_contact_*.png總覽分流,再派 sub-agent 看入圍頁單圖,節省 token"page"→ 每個目標頁都派 sub-agent 看單頁slide_NN_compare.png,覆蓋最嚴"manual"→ 只生成審查物料,交給用戶人工核查;用戶反饋問題後再修"ask"或缺失 → agent 透過 AskUserQuestion 收集偏好後改寫此項(預設)
- 首次使用:agent 透過 AskUserQuestion 收集
fonts.auto_install和audit.mode後自己 Write 這個檔案——用戶不用手動建
配置確認(第一次 convert 之前完成)
兩條偏好要在第一次 convert 之前確認:fonts.auto_install 和 audit.mode。流程相同,差別只在觸發條件和問法。
通用流程
每條偏好獨立按下面順序判定:
- Read
<skill_dir>/.config.local.toml,看對應欄位:- 合法非
ask值 → 按該值走,工作階段內不再問 ask或檔案 / 欄位缺失 → 走"觸發判定 + ask"
- 合法非
- CLAUDE.md / 全域指令寫明等同值的,按寫明值走,並補寫 config(保持單一事實源)
觸發後 AskUserQuestion 問一次,兩條都要做:
- 寫入
<skill_dir>/.config.local.toml對應欄位為用戶答覆(不寫ask,否則下次工作階段還會再問) - 本次工作階段同時按答覆走
寫 config 時:檔案不存在 → Write 整檔案落盤([fonts] [cleanup] [audit] 三段模板);檔案已存在 → 用 Edit 做單行 replace(只改這一個欄位),不要 Write 重寫整檔案,否則會吞掉用戶其它自訂 key。
同一工作階段兩條都觸發 → 合併到同一條 AskUserQuestion 裡一次問完。
fonts.auto_install —— 字型安裝
PowerPoint COM slide.Export() 和 WPS Office 都不讀 pptx 內嵌的裸 TTF——audit 渲染和 WPS 都回退到系統字體。裝到用戶字體目錄後兩者都按系統字體走。目錄(均為用戶級,可手工刪):
- Windows:
%LOCALAPPDATA%\Microsoft\Windows\Fonts\+ HKCU 註冊 - macOS:
~/Library/Fonts/ - Linux:
~/.local/share/fonts/+fc-cache -f
觸發判定:看 HTML <head> 的 <link href="...fonts.googleapis.com/..."> / @import url(https://fonts.googleapis.com/...) / <style> 裡 font-family: 出現的字體名:
- 觸發:任何 GF / 自託管字體(Bricolage Grotesque、DM Sans、Inter、Space Grotesk、Caveat 等)
- 不觸發:只用系統字體白名單(Arial、Times New Roman、Helvetica、Helvetica Neue、Courier、system-ui、-apple-system、BlinkMacSystemFont、SF Pro、Microsoft YaHei、SimSun、PingFang、Hiragino)
按答覆:同意 → 加 --install-user-fonts;拒絕 → 不加。
audit.mode —— 視覺審查模式
三種模式 triage / page / manual(含義見上方 "配置" 章節)。每次工作階段第一次 convert 之前都判定(不依賴 HTML 內容觸發)。AskUserQuestion 用單選題,選項即三種模式。
工作流(強制)
convert.py 跑完不等於交付完成。完整流程:
convert.py(首輪自動 cp <input>.audited.html,所有修復改這個副本)
→ Stage 5a 結構化自檢(OOXML 掃描,給提示)
→ Stage 5b 視覺 audit 物料 — 需要 PowerPoint COM 或 LibreOffice 渲染器
→ 讀 `audit.mode` 決定審查方式:triage / page / manual
→ 【agent audit】
triage 模式:主 agent 讀 contact sheet 分流 → sub-agent 看入圍頁單圖 → 合併寫 audit_findings.md
page 模式:全量 sub-agent 看單頁 → 合併寫 audit_findings.md
manual 模式:把 audit 物料交給用戶,等待用戶人工反饋
→ 按 finding 逐項做最小區域修改,目標是 audited.html(見下"修復紀律")
→ 一批 finding 改完後 `convert.py <input>.audited.html --only-slides <被改頁號>` + 只對 fresh 頁重審(見下"增量重跑")
→ 所有頁 OK 或僅剩 LOW
→ 【若撞到 HTML 反模式 / 新 OOXML 邊界】沉澱到 lessons-learned,見下方"沉澱 HTML 問題與 OOXML 邊界"
→ 讀 `<skill_dir>/.config.local.toml` 的 `cleanup.default`:
"clean"(缺省)→ 直接 `python convert.py <out>.pptx --cleanup`,不問用戶
清完目錄剩:<input>.html(源,未動)+ <input>.audited.html(修復版)+ <out>.pptx
"keep" → 跳過 cleanup,audit 產物全部保留
→ 把 .pptx 路徑交付給用戶(audited.html 作為修復版 HTML 一同交付)
向量優先原則(強制)
能用 PPT 原生 text / shape / line 表達的內容,優先保持可編輯:普通背景色、普通四邊框、單邊線、簡單矩形/橢圓、簡單 ::before / ::after 線框都應走 PPT shape。
deco_snapshot 只兜底 OOXML 難表達的裝飾(命中條件 + 完整檔位定義 + 截圖/向量層協同機制見 references/supported-css.md)。不要為了省事把普通線條、圖表軸線、簡單邊框統一截圖——這會犧牲 PPT 可編輯性,也會讓後續區域修復變難。
渲染器要求(Stage 5b 前置條件)
Stage 5b 視覺 audit 需要把 .pptx 渲染成 PNG,依賴:
- PowerPoint COM(Windows + Office +
pywin32),或 - LibreOffice(跨平台,配
pip install pdf2image)
任一可用就能跑 audit。convert 輸出裡看到 [self-check] 跳過:找不到可用的 pptx 渲染器,說明兩個都沒裝——此時 audit 不會產出 compare 圖,Stage 5b 直接跳過。
這種情況下 agent 必須 ask 用戶(不要靜默交付未審計的 pptx):
"你機器上沒裝 PowerPoint 也沒裝 LibreOffice,視覺 audit 跑不了,PPT 可能有看不出來的視覺 bug。三個選擇:
- 裝 LibreOffice(推薦,跨平台,2-3 分鐘):
winget install LibreOffice.LibreOffice(Windows)/brew install --cask libreoffice(mac)/apt install libreoffice(Linux),然後pip install pdf2image,重跑 convert- 跳過 audit 直接交付(接受 PPT 可能有視覺 bug 的風險)
- 在已經裝了 Office 的另一台機器上重跑"
用戶選 1 → 等他裝完重跑;選 2 → 加 --no-visual-audit 跑一遍,把告知風險後交付;選 3 → 把當前目錄 + HTML 發給他。
視覺 audit 模式(config,前提:5b 跑起來了)
執行視覺審查前讀取 <skill_dir>/.config.local.toml 的 [audit].mode。正常應在第一次 convert 前透過上方 "配置確認" 完成詢問;如果到這裡 mode 還是 "ask"(說明 agent 漏問了),立刻按 "配置確認" 章節詢問用戶再繼續。
每個 mode 的具體含義見上方 "配置" 章節;這裡只列適用場景:
| mode | 適用 |
|---|---|
triage | 預設,節省 token |
page | 最終交付前、關鍵客戶、用戶要求最嚴 |
manual | 用戶想自己看 |
triage 的分工很明確:第 1 輪 contact pass = 主 agent 自己看縮圖分流(廉價,上下文已含源 HTML / Stage 5a / preflight);第 2 輪 detail pass = 把入圍頁派 sub-agent 看單頁 compare 圖。不能只憑縮圖判 HIGH/MID finding;要報 finding 必須經第 2 輪 sub-agent 單頁確認。
audit 分發與 compare 圖讀取規則
page 模式所有頁都走 Claude Agent(...) sub-agent 並行 dispatch。triage 模式只有第 2 輪入圍頁走 sub-agent;第 1 輪 contact sheet 由主 agent 自己 Read,不派 sub-agent。
主 agent 主動讀 compare 圖的場景僅限以下五種:
triage第 1 輪讀audit_contact_*.png總覽分流- 針對性修復的驗證輪:本輪 fresh 頁 ≤ 2 且改動未涉及全域 CSS → 主 agent 直讀 fresh 頁單圖複查已知 finding + 掃該頁新回歸,不派 sub-agent(sub-agent 一輪 2-3 分鐘,直讀只要幾秒)。fresh 頁更多或有全域變更仍走 sub-agent
- finding 描述含糊 / 與原始碼衝突無法定位時,讀對應單頁
slide_NN_compare.png - sticky 命中前確認讀單頁
- 用戶點名反饋某一頁讀單頁
除此之外不逐頁 Read compare 圖。
batch 按 wall-clock 優化拆小並行(sub-agent 串行讀大圖是延遲主因,多個小 batch 並行發滿比一個大 batch 快一倍以上):
| slide 數 | 策略 |
|---|---|
| ≤ 2 | 1 個 batch |
| 3-20 | 每 batch 2 頁,全部並行發 |
| > 20 | 每 batch 3 頁(控制 agent 總數) |
完整 sub-agent 調用模板 + 檢查清單 + findings 格式見 <out>_audit/audit_prompt.md。多個 Agent(..., run_in_background: true, subagent_type: "general-purpose") 調用塞在主 agent 同一條 message 裡才並行。
sub-agent 只返回 findings 文字(page 模式含每個目標頁的 ## page NN 塊;triage 細看批次含每個被放大複查頁的塊),主 agent 統一合併寫 audit_findings.md——並行寫會互相覆蓋。
每條 finding 必須點名穩定元素短名,並描述"HTML 半圖實際狀態;PPT 半圖差異"。只報告 PPT 相對 HTML 新增或放大的視覺問題;HTML 半圖本身已有的問題不算轉換 finding。
與 sub-agent 並行的主 agent 準備(強制)
發起 page 模式或 triage 第 2 輪 detail sub-agent 時,Agent 調用用 run_in_background: true,並在同一條 message 裡同時發:
Agent(run_in_background: true, subagent_type: "general-purpose", description: "Audit slides 1-4", prompt: ...)
Agent(run_in_background: true, subagent_type: "general-purpose", description: "Audit slides 5-9", prompt: ...)
Read(file_path: "<deck>/template.html")
Read(file_path: "<skill_dir>/references/lessons-learned.md")
Grep(pattern: "class=\"slide |data-slide=", path: "<deck>/template.html",
output_mode: "content", -n: true)
每個 sub-agent prompt 裡必須直接寫入本批 slide_NN_compare.png 絕對路徑、deck HTML 路徑、lessons-learned.md 路徑(適用範圍見上方"視覺 audit 模式"章節);不要假設主 agent 的 Read / Grep 輸出會自動傳給 sub-agent。
只發"無論 findings 是什麼都用得上"的準備——不要預測 findings 提前改 HTML。
修復紀律(針對 finding,不追根因)
收到 audit_findings.md 之後,一輪裡把本輪所有 finding 都改完,再一次性重跑 convert + audit——不是改一個跑一次。一輪 = 一批 HTML 編輯 + 一次 convert + 一次 audit。
拿到 findings 之後:
- 不常規自己 Read compare 圖(findings 已經把症狀寫明);三種例外讀單頁複查見上方 "audit 分發與 compare 圖讀取規則" 章節
- 不讀
measure.py/assemble.py/ 任何 skill 內程式碼找根因 - 直接打開
audited.html按 finding 逐條改
每個 finding 內部做最小區域 HTML 修改:
-
每個 finding 只改"讓它消失"的那一處,改完進下一個 finding(繼續改 HTML,不是重跑 convert)
-
不追溯"為什麼字體回退 / 為什麼佈局偏移"的深層根因
-
不做"我順手把 .footer 也改成絕對定位"這種 finding 列表外的優化
-
不跨 finding 做結構性重構("統一把所有 slide 的 font-family 顯式宣告"≠ 單個 finding 的最小修復)
-
同一 finding 在連續兩輪(上一輪 + 本輪)都出現 → sticky 命中,停下來告訴用戶,不要繼續擴大改動面。判定 key =
(頁號, 視覺元素短名):- 措辭 / 嚴重度 / HIGH↔MID 切換都不重置判定。例:
(page 5, take 字型大小)在 round 6 被描述成"偏小"、round 7 被描述成"嚴重不足" → 同一 sticky key,round 7 即命中 - 只有"頁號 + 元素"都不重合才算新 sticky key
- 隔輪恢復:若 round 6 出現、round 7 消失、round 8 又出現 → 不算 sticky(round 7 缺席視為問題已修,round 8 是新回歸)
- 命中 = 本輪不修該 finding、列入 skill 邊界候選告訴用戶,本輪其他 finding 照修
實施:每輪合併完
audit_findings.md、動 Edit 之前,必須先 Read 上一輪audit_findings.md(首輪無)做兩兩比對——本輪和上輪都出現的 key 即命中。命中的 finding 單獨列出來交給用戶判斷,不再進本輪編輯佇列。 - 措辭 / 嚴重度 / HIGH↔MID 切換都不重置判定。例:
本批 finding 改完一次性 python convert.py <input>.audited.html --only-slides <被改過的頁號>。
判定標準:你的 diff 行數 ≤ findings 數 × 3 行。超過這個量級說明在"亂發揮"。
增量重跑(--only-slides)
audit 第 2 輪起用,首輪全量。
python convert.py <input>.audited.html --only-slides 2,7,12
增量覆蓋 measure / Stage 5a 渲染 / Stage 5b compare 圖,僅對列出的頁 + 快取缺失的頁執行;assemble / embed_fonts 仍全量。audit_index.json 標 incremental_mode: true、fresh_indices、cached_indices、每頁 fresh: true/false。
增量輪的 audit 目標頁只取 fresh_indices。page 模式直接分發這些頁;triage 模式先在這些頁範圍內分流,再把入圍頁發給 sub-agent。
前提:上輪的 <out>_audit/ 目錄還在。cache 缺失自動回退全量;HTML 頁數變化自動檢測並回退全量 measure。
不能用 --only-slides 的情況(視覺溢出列出的頁,快取假陰性):
- 全域 CSS(
<style>、根選擇器、.slide通用樣式)變更 - 新增 / 刪除字體(@import、font-family 宣告變更)
- deck-level token(背景、主題色、間距)變更
- 任何影響其它頁佈局的全域變數變更
這幾類不帶 flag 全量重跑。判斷不準 → 全量重跑總是安全的。
沉澱 HTML 問題與 OOXML 邊界(強制)
你的角色是調用 + 用法沉澱,不是修 skill。發現 skill 內部 bug 時不要原地改 measure.py / assemble.py。
只沉澱兩類:
1. HTML 寫法問題(用戶的 HTML 讓轉換失真)
| 類別 | 判定 | 做什麼 |
|---|---|---|
| 單次 case(只在這個 deck 出現,改一兩行 HTML 就好) | 單頁特例 | 直接改 HTML 源;不沉,不通報 |
| 通用 HTML 反模式(任何人寫類似 HTML 都會踩) | 跨 deck | 改 HTML + 沉到 references/lessons-learned.md 的 "HTML 寫法規避" 區 |
2. OOXML 表達力邊界(PowerPoint / OOXML 天然不支援)
絕大多數裝飾類 CSS(backdrop-filter / filter / mix-blend-mode / skew / box-shadow / gradient / ::before ::after 裝飾用法——空 content + bg-image / box-shadow 等)已經被"覆蓋策略"裡的 hasComplexDecoration 自動捕獲走 deco_snapshot——HTML 不用改。::before ::after string content(content: "↑" 等)走文字通道,詳見 references/supported-css.md 第 1 檔。
仍需 HTML workaround 的真邊界(OOXML 文字層原生表達不了的):
| 邊界 | 替代通路 |
|---|---|
| 彩色 emoji(COLR/CPAL 字體) | Twemoji SVG <img>,走 img 通道嵌入 |
background-clip: text 文字漸層 | inline <svg><text fill="url(#grad)">,走 SVG 通道 |
撞到這兩類 → 改 HTML 走替代通路 + 沉到 references/lessons-learned.md 的 "OOXML 邊界" 區。
撞到不在上表的新 CSS 不支援 → 先看 hasComplexDecoration 是不是漏觸發(加一行觸發條件即可),而不是改 HTML。詳見 references/supported-css.md 的"加新支援的標準做法"。
看似 skill 內 bug 怎麼處理(不修不沉)
發現某症狀用同一種 CSS 模式換 deck 還會撞、且不在已知 OOXML 邊界內 → 這是 skill 抽象不到位。不要原地改 skill 程式碼。做這兩件事:
- 當前 deck 走 HTML 端 workaround 把 finding 修掉,讓用戶拿到能交付的 PPT
- 明確告知用戶:"發現一個看起來是 skill 內的通用 bug:[症狀 + 觸發 CSS 模式 + 當前 workaround]。建議作者按 issue 收錄,讓 skill 在 measure/assemble 裡更通用地處理這種模式"
沉澱寫到哪:本地副本 + 上游模板
references/lessons-learned.md 是每用戶獨立的本地工作副本(gitignored)。首次跑 convert.py 時 local_config.seed_lessons_learned() 自動從模板 lessons-learned.md.example(committed)拷貝一份。機制和 .config.local.toml 一樣。
- agent 排查 / 沉澱都讀寫本地
lessons-learned.md——自由加 / 改 / 整理,無 git 雜訊 - 本地副本永不讓上游覆蓋——
git pull拉的是.example模板,不動你的工作副本 - 想把某條沉澱上游:作者手動把 entry 複製回
lessons-learned.md.example再 commit;選擇性 curate,不是全推 - 本地業務 / 特定客戶專有寫法 → 直接寫在本地副本裡就行,不會上游
- lessons 條目只寫可復用的症狀、觸發模式、規避規則;不要寫具體本地檔案名、模板名、頁面號、客戶名或原始碼檔名。具體實作位置、命令和程式碼細節留在 commit / issue / 主 skill 文件裡
觸發:撞到通用 HTML 反模式 / OOXML 邊界 → 加到本地 lessons-learned.md 對應表。每次 convert 都重讀,立即生效。
覆蓋策略(一句話)
skill 內部所有 CSS 翻譯成四檔輸出:矢量文字 → 矢量形狀 → 柵格裝飾(deco_snapshot)→ 媒體直傳。簡單 bg-color / border / border-radius 走前兩檔(可編輯可搜尋),box-shadow / gradient / filter / backdrop-filter / mix-blend-mode / 不對稱圓角 / 裁切容器 + 旋轉子 等命中 hasComplexDecoration 走第三檔(柵格只裁裝飾像素,文字始終保留矢量畫在截圖之上)。
完整檔位定義 / 觸發條件 / 加新支援指南(矢量優先 → 截圖兜底)→ references/supported-css.md。
流水線
[1 輸入識別/預掃] → [2 測量] → [3 組裝] → [4 字型嵌入] → [5a 結構化自檢] → [5b 視覺 audit]
preflight.py measure.py assemble.py embed_fonts.py self_check.py visual_audit.py
各階段動作 / 反假設規則 / 退出斷言 / 新模板 checklist → references/methodology.md。
Stage 5b 產出 <out>_audit/(compare 圖 + contact sheet + audit_index.json + audit_prompt.md)。不做像素 diff — 數字對局部 bug 不敏感、給假信心;視覺判斷按 audit.mode 走 triage / page / manual。無渲染器時 5b 跳過,按上面"渲染器要求"小節 ask 用戶。
調用前
…