name: ppt-craft-editable description: >- 端到端 PPT 全流程，單技能自包含。使用者首次觸發本 skill 時，agent 必須默默跑 scripts/preflight.py 做環境自檢 + 自動安裝缺失的 Python 包；FAIL 才打斷使用者。 環境通過後走 conversation-first + image-first 工作流：多階段對話、內容補強、風格預覽、規劃鎖定、出每頁定稿圖，並在使用者驅動下做影像級 retouch（去水印 / 去瑕疵，內建 IOPaint 自動安裝）。最終交付高完成度圖片型 PPTX。 Phase A 結束後必須主動詢問使用者是否要可編輯文字版（Phase C）；若同意，進入 Phase C：以 Phase A 定稿圖作為視覺參考，重新生成"帶裝飾、留白文字區"的無字背景圖 + HTML 編輯器調文字 → 一鍵渲染原生可編輯 PPTX。 使用者明確要求"只做可編輯版 / 只跑 Phase C / 跳過圖片版"時，直接進入 Phase C-only 模式，不執行 Phase A 的任何生成、預覽、review、retouch。 ★ Phase D - PDF PPT編輯分支：使用者上傳 PDF 幻燈片時，自動判斷每頁是向量文本還是圖片型，用多模態模型抽取文案結構，在 HTML 預覽頁讓使用者確認後，生成無字背景 + 可編輯文字框，最終輸出原生可編輯 PPTX。 ★ 當對話中出現 ===PPT-CRAFT-EDITABLE / DECK FROM EDITOR===、===PHASE-D / CONTENT EXTRACTION CONFIRMED===、舊標記 ===PPT-IMAGE-FIRST-EDITABLE / DECK FROM EDITOR=== 或 ===DECK JSON BEGIN/END=== 標記時，agent 必須立刻把標記之間的 JSON 原樣寫入對應檔案並跑相應指令碼，不解讀不修改不追問。 當用戶需要做彙報 / 答辯 / 路演 / 提案 PPT，或只丟一個主題想要完整成品，或上傳 PDF 想轉可編輯版時使用。

ppt-craft-editable — 一條龍 PPT 技能（自包含）

★★★ Stage 0 — 使用者首次觸發本 skill，agent 預設自動跑環境自檢 + 自動修復 ★★★

這是本 skill 最高優先順序的規則，覆蓋一切其他規則。

使用者首次說要做 PPT、首次觸發本 skill 時，agent 不需要問使用者，直接默默跑：

python3 scripts/preflight.py

preflight.py 會： 1. 檢查 Python 版本（不夠則停，讓使用者處理） 2. 檢查 4 個必備 Python 包，缺的自動 pip install（含 --user fallback；首次可能 2-5 分鐘，OpenCV 較大） 3. 裝完後自動調 doctor.py 做完整體檢（字型 / 磁碟 / 網路 / IOPaint 狀態 / skill 完整性） 4. 全部通過 → 退碼 0 → agent 進入 Stage 1 5. 仍有阻塞 → 退碼 1 → agent 把缺什麼和怎麼修念給使用者聽，等使用者處理

preflight 自動會做的事 vs 不會做的事

磁碟空間的三檔處理

preflight 在裝任何東西之前就先查磁碟。這一項很重要——磁碟滿會導致 pip 裝包到一半失敗、生成圖片時寫盤失敗、IOPaint 模型下載失敗，錯誤資訊往往很難懂。

如果 agent 在 Phase A / Phase C 跑到一半看到 No space left on device、OSError: [Errno 28]、Could not write file 這類錯誤，立刻停下告訴使用者磁碟滿了，別重試浪費 imagegen 呼叫。

agent 的行為對照表

跑 preflight 的反模式（不要做）

• ❌ 不跑 preflight 直接進 Stage 1
• ❌ 跑 preflight 之前先問使用者"要不要裝 Python 包"——使用者不一定知道答案；自動裝是預設行為
• ❌ preflight 報 FAIL 還硬著頭皮走下去（遲早卡在 Stage 2 或 Phase C 渲染）
• ❌ 把 preflight 當成"每輪都要跑一次"（只在使用者首次觸發或環境變更後跑）

何時算"首次觸發"

• 使用者在當前對話裡第一次說要做 PPT
• 或者使用者明說"換了機器 / 重灌了環境 / 重跑一次自檢"
• 或者上次跑 preflight 後已經過了很長時間（agent 自行判斷）

後續輪次只要環境沒變，不需要重跑——浪費時間。

給使用者的"我在裝東西"提示

如果 preflight 真的在裝包（首次場景，可能 2-5 分鐘），agent 在等待之前應當告訴使用者：

第一次使用，正在自動安裝 4 個 Python 依賴包（python-pptx / Pillow / numpy / opencv-python）。 首次安裝可能需要 2-5 分鐘，OpenCV 單獨就 ~100MB，期間終端會看起來在卡，請稍等。 裝完會自動繼續，您不用做任何操作。

這樣使用者不會以為卡死了去 Ctrl+C。

imagegen 通道的額外驗證

preflight 和 doctor 都無法直接探測 agent harness 的 imagegen 通道。所以在 Stage 2 出第一張真實預覽之前，agent 還要再做一次"出圖通道可用性測試"：用最小 prompt 出一張極小尺寸的圖，確認通道通。這一步失敗不算 preflight 失敗，但必須停在 Stage 2 之前，告訴使用者出圖通道不可用、不能繼續。

★★★ Phase A HTML 硬門禁（agent 必須自檢，不可跳過）★★★

Phase A 流程中必須有兩次讓使用者在瀏覽器裡看 HTML——這是這條 skill 區別於"只在對話裡貼圖說說"的根本動作。 agent 在長對話裡很容易忘記開啟殼子，所以下面這兩個動作是硬門禁，跑漏了視同 Phase A 沒做完：

每個門禁的最小自檢（agent 跑完必須勾選）

• [ ] *_filled.html 已生成在上表列的精確路徑
• [ ] 已經嘗試用 open / xdg-open / start 主動為使用者開啟它（失敗再退路徑）
• [ ] 在對話裡顯式告訴使用者"已在瀏覽器開啟 <filename>，請在裡面確認 / 選圖 / 給反饋"
• [ ] 等使用者反饋（確認 / 複製貼上回 JSON / 選圖編號）後才進入下一 Stage

反模式（一旦發生立刻自我糾正）

• ❌ 出完圖直接在對話裡貼幾張縮圖、問"喜歡哪套？" —— 跳過了 G-Preview，不算過門禁
• ❌ "我已經生成了 9 張預覽圖在 phaseA/previews/，請檢視" —— 使用者不會開啟原圖；必須開殼子
• ❌ 出完終圖直接說"以下是 N 頁定稿，您看看？" —— 跳過了 G-Review
• ❌ 打開了 assets/preview_shell/index.html 或 assets/review_shell/index.html（裸殼，裡面是佔位 SVG / 示例資料）—— 必須開啟 *_filled.html
• ❌ 跑了 build_*.py 當成"已經注入" —— build_*.py 只還原模板不注入資料，跑完圖還是佔位
• ❌ G-Preview 還沒過就跳到 Stage 3 寫 design_spec.md —— 風格沒經過瀏覽器確認，規劃檔案作廢
• ❌ G-Review 還沒過就匯出圖片型 PPTX 或主動詢問 Phase C —— 終圖沒經過瀏覽器評審，交付作廢

如果環境真的打不開瀏覽器

只在三件事都成立時才允許跳過"自動開啟"動作： 1. agent 真的試過 open / xdg-open / start 都報錯 2. 已經在對話裡明確說明為什麼打不開 3. 已經把 *_filled.html 的絕對路徑給到使用者，提示他自己雙擊開啟

即使瀏覽器打不開，注入步驟本身不能跳（*_filled.html 仍然必須生成）。

Phase C-only 入口

當用戶明確說出以下任一意圖時，預設進入 Phase C-only：

• 只做可編輯版
• 只跑 Phase C
• 跳過圖片版
• 直接給我文字可編輯 PPTX

Phase C-only 必守

• 不執行 Phase A：不跑 Stage 1-5，不做風格預覽，不做圖片型 PPTX
• 優先複用現有成果：如果使用者已經給了 Phase A 產物，直接拿來用
• 必須先過頁大綱確認門禁：不管有無 Phase A 產物，C-only 路徑也必須先寫 slide_outline.md，並同步寫一份同內容的 ppt大綱.md 方便使用者查詢；等使用者確認後才進 C0/C1。若使用者已有完整內容稿且頁面結構清晰，可由 agent 直接梳理給使用者確認，不需要反覆追問細節
• 缺輸入先補最小集：如果缺 design_spec.md / slide_blueprint.md / deck.json，先收齊再進 C1-C6
• 必須先過 C0 輕量預覽門禁：沒有 Phase A 圖作為視覺證據時，先做 1-2 頁”重新生成的無字背景 + 可編輯文字預覽”，並落地 phaseC/c0/deck.json、phaseC/c0/editor.html、phaseC/c0/preview/slide_*.png；讓使用者確認視覺基準後再批次生成全套背景
• 不再主動詢問 Phase C：因為當前會話已經在 Phase C 路徑裡
• Phase C 完成即終態：拿到可編輯 PPTX 後結束，不折返到其他路徑

Phase C-only 的最小輸入

• 主題或已有報告稿
• 頁數 / 受眾 / 目的
• 可複用的內容稿或頁面結構
• 如已存在，優先直接使用 design_spec.md、slide_blueprint.md、spec_lock.md

Phase C-only 的視覺基準

• design_spec.md 是視覺基準，不依賴 Phase A 成品圖；它必須鎖定明暗、色彩角色、字型氣質、背景材質、裝飾語言、留白規則和頁面型別語法
• slide_blueprint.md 決定每頁哪些元素進入背景、哪些內容必須保持為可編輯 TextBox
• spec_lock.md 必須寫清：背景只承載氛圍、結構、裝飾和非編輯性視覺元素；標題、正文、數字、日期、署名等後期可能改的內容必須進入 deck.json.text_boxes
• C0 預覽只用於確認視覺基準，不產出圖片型 PPTX，也不折返 Phase A；使用者確認 C0 前，slide_outline.md / ppt大綱.md 以及 phaseC/c0/ 三類預覽產物必須真實存在

把三套互補能力融成一個 skill：

• Phase A — 對話式定稿 + retouch（預設主路徑） Conversation-first + image-first 工作流：多階段對話 → 內容基底 → 風格預覽 → 風格反演確認 → 規劃檔案 → 每頁定稿圖 → 使用者驅動的影像級 retouch（去水印 / 去瑕疵）。
• Phase C — 分層生成 + HTML 文字編輯（可編輯路徑） Phase A 完成後主動詢問使用者是否要可編輯文字版。若使用者同意，Phase C 會以 Phase A 定稿圖作為視覺參考，重新生成不含可編輯文字的背景層，再把文字作為外掛圖層在 HTML 編輯器裡調整 → 一鍵渲染成原生可編輯 PPTX。注意這不是從 Phase A 圖片中精確摳掉文字，背景可能與 Phase A 定稿有細微差異；若直接編輯不乾淨，再回退到重生成背景 + 擦字稿。文字始終是真 TextBox（PPT 裡可改）。 如果使用者一開始就明確要求只做可編輯版，則直接走 Phase C-only，不進入 Phase A。
• Phase D — PDF PPT 編輯分支（PDF 匯入路徑） 使用者上傳 PDF 幻燈片時，自動判斷每頁是向量文本（可直接提取）還是圖片型（需多模態理解）。用多模態模型抽取文案結構、角色、位置，生成 extraction.json 並在 HTML 預覽頁讓使用者確認。確認後按背景策略（clean 擦字 / rebuild 重建）生成無字背景，寫入 phaseC/deck.json，接入 Phase C 編輯器（C4-C6）最終輸出可編輯 PPTX。

[使用者的模糊需求]
        │
        ▼
┌── Phase A（預設主路徑）─────────────────┐
│  Stage 1     Intake + 需求確認           │
│  Stage 1.25  content_report.md          │
│  Stage 1.4   ★ 頁大綱確認門禁           │
│              slide_outline.md → 使用者確認 │
│  Stage 1.5   風格邊界（3 個短問題）       │
│  Stage 2     多套風格預覽（首/目/正）     │
│  Stage 2.5   風格 refinement             │
│  Stage 2.75  風格反演 + 風格確認          │
│  Stage 3     design_spec /              │
│              slide_blueprint /          │
│              spec_lock + 生成前確認       │
│  Stage 4     全頁定稿圖                  │
│  Stage 5     review + 使用者批准           │
│  Stage 5.5   ★ retouch（可選，使用者驅動）  │
└──────────────┬──────────────────────────┘
               │
               ▼   交付：圖片型 PPTX + 全頁定稿圖 + 規劃文件
               │
   ┌───────────┴───────────┐
   │ ★ 必須主動詢問使用者 ★    │
   │ "PPT 已交付。是否需要   │
   │  可編輯文字版（Phase C）│
   │  ——文字能在 PPT 裡直接   │
   │  改？這會參考定稿圖重生  │
   │  成無字背景，可能有細微 │
   │  差異；                 │
   │  每頁約 2 張 imagegen。" │
   └─────────┬─────────────┘
             │
        使用者同意 → 進 Phase C
             │
             ▼
┌── Phase C（可編輯文字版）─────────────────┐
│  C0  Phase C-only 輕量預覽門禁（條件觸發）│
│  C1  雙軌生成背景                         │
│      (完整稿 → imagegen 擦字稿)           │
│  C2  detect_reserved_zones 校驗           │
│  C3  寫 deck.json                         │
│  C4  inject_editor_deck.py 注入編輯器     │
│  C5 ★ 統一編輯 + 背景反饋門禁（必跑）     │
│      文字模式 改字 / 拖框 / 調樣式         │
│      背景反饋模式 矩形/畫筆/註釋點 + 意見  │
│      → 匯出包貼回（含可選 BG REVIEW 段）   │
│      → 有 BG REVIEW: 修背景 → 重出編輯器   │
│      → 無 BG REVIEW: 進 C6                 │
│  C6  校驗 deck.json → 渲染 PPTX           │
└──────────────┬──────────────────────────┘
               ▼
[追加交付：文字可編輯 PPTX + deck.json + backgrounds/]

I/O Contract

Phase A 必交付（預設）

• content_report.md（使用者沒給完整內容稿時）
• slide_outline.md（Stage 1.4 頁大綱確認，使用者已批准）
• design_spec.md / slide_blueprint.md / spec_lock.md
• 每頁定稿圖 phaseA/slides/NN-*.png
• 圖片型 .pptx（高完成度視覺稿，用於彙報/展示——這是預設終交付物）
• phaseA/imagegen-manifest.json

Phase C 追加交付（使用者同意走可編輯路徑時）

• 每頁背景圖 phaseC/backgrounds/NN.png（+ 第 1 稿 NN-full.png 備查）
• phaseC/deck.json（單一真相源，編輯器 / 渲染器共同消費）
• 每頁 phaseC/NN-zones.json + phaseC/NN-zones.report.json
• 文字可編輯 .pptx（背景 = Picture，文字 = 真 TextBox，跨平臺穩定）
• 可選 phaseC/preview/slide_NN.png 近似對照圖

Phase D 交付（PDF 匯入路徑）

• phaseD/extraction.json（初版抽取結果）
• phaseD/extraction_review.html（HTML 預覽頁）
• phaseD/extraction_confirmed.json（使用者確認後的版本）
• 每頁背景圖 phaseC/backgrounds/NN.png（clean 擦字或 rebuild 重建）
• phaseC/deck.json（從 extraction 轉換而來）
• 文字可編輯 .pptx（最終產物，接入 Phase C 渲染管道）

輸入

PPT 主題 / 粗略目標 / 零散材料 / 已有報告稿 / PDF 幻燈片；可選錨點（受眾、頁數、身份錨點、用途場景、參考圖、風格傾向）。

確認門禁

• 5 個必有門禁（Phase A）：需求確認 → 頁大綱確認 → 風格確認 → 生成前確認 → 終圖評審
• 第 4 個門禁（強制主動詢問）：Phase A 終圖交付後必須主動問使用者是否需要 Phase C 可編輯文字版
• Phase C 內的門禁：使用者在 HTML 編輯器裡點 "匯出 deck.json" 表示滿意
• Phase D 內的門禁（G-D-ContentConfirm）：使用者在 extraction_review.html 裡確認/修改文案後點"匯出確認"

比例

預設 16:9。Phase A/C/D 全程必須同一比例，禁止中途切換。

★ 主動詢問 Phase C 的規則（最關鍵的行為）

Phase A 全部交付完成後，必須主動詢問一次使用者是否要走 Phase C。這是這條 skill 的硬約束。

詢問時機

• Phase A Stage 5（review）通過 + Stage 5.5 retouch 處理完（如果跑了）
• 已經把圖片型 PPTX 和所有定稿圖給到使用者
• 在結束對話前

詢問話術（參考，可調措辭）

圖片版 PPT 已經做好了： - 圖片型 PPTX：<path> - 全 N 頁定稿圖：<path> - 規劃文件：<paths>

現在的成品是圖片版，每頁是一整張圖——好處是視覺密度最高、跨平臺不會跑版；缺點是文字不能在 PowerPoint 裡直接改。

如果您後續可能要改文字（比如換日期、換名字、換關鍵數字、改標題措辭），我可以繼續走 Phase C 給您出一份文字可編輯版： - 參考當前定稿圖重新生成無字背景（保留整體風格和裝飾，預留文字區；不是從原圖裡精確摳字，可能有細微差異） - 文字作為獨立圖層，在瀏覽器編輯器裡調 - 一鍵渲染成原生可編輯 PPTX - 大致成本：每頁約 2 張 imagegen（背景完整稿 + 擦字稿），N 頁約 X 次呼叫

要不要進 Phase C？（不需要也可以，圖片版本身就能直接拿去彙報）

詢問後的分支

• 使用者說要 / 好 / 進 Phase C / 我後期還要改字 → 按 references/phaseC/workflow.md 跑 C1-C6
• 使用者說不用 / 這樣就夠了 / 先這樣 → 結束對話，不要再追問
• 使用者沒正面回答（比如繼續聊別的） → 不要打斷，等使用者自己提

反模式（不要這樣做）

• ❌ 不詢問就直接進入 Phase C
• ❌ 不詢問就直接結束對話（使用者可能不知道有可編輯選項）
• ❌ 反覆追問、施壓讓使用者走 Phase C
• ❌ 把"是否進 Phase C"作為 confirmation gate 強卡使用者（它是一個開放問題，不是必跨門禁）

★ 使用者從編輯器貼回內容時的處理規則（極重要）

Phase C editor.html 裡使用者點”匯出 / 繼續生成”後會得到一段帶 sentinel 的”指令包”，現在有兩種格式：

格式 A（只有文字改動，沒有背景反饋）

===PPT-CRAFT-EDITABLE / DECK FROM EDITOR===
...
===DECK JSON BEGIN===
{ ... 完整 deck.json ... }
===DECK JSON END===

格式 B（文字改動 + 背景反饋，同一次匯出）

===PPT-CRAFT-EDITABLE / DECK FROM EDITOR===
...
===DECK JSON BEGIN===
{ ... 完整 deck.json ... }
===DECK JSON END===

===PHASEC BACKGROUND REVIEW BEGIN===
{ ... phasec-background-review-v1 ... }
===PHASEC BACKGROUND REVIEW END===

當 agent 在對話裡看到這兩種標記時，必須：

格式 A（只有 DECK JSON）→ 直接渲染 1. 把 ===DECK JSON BEGIN/END=== 之間內容原樣寫入 phaseC/deck.json（覆蓋舊版） 2. 跑 python3 scripts/json_to_pptx.py phaseC/deck.json -o phaseC/edited.pptx --preview-dir phaseC/preview 3. 把 phaseC/edited.pptx 路徑告訴使用者，結束

格式 B（還有 PHASEC BACKGROUND REVIEW）→ 先修背景，再重開編輯器 1. 同樣先把 ===DECK JSON BEGIN/END=== 之間內容寫入 phaseC/deck.json（保留文字改動） 2. 讀取 ===PHASEC BACKGROUND REVIEW BEGIN/END=== 裡的 pages[]，按 requested_action + page_comment / markup 修 phaseC/backgrounds/*.png： - retouch-local → IOPaint 區域性修補當前背景 - regenerate-background → 以反饋為依據重生成該頁背景 - adjust-text-zones → 調整背景留白區，必要時同步 phaseC/*-zones.json；文字框位置等後續在編輯器裡調 - approved → 該頁背景通過，不修 3. 背景修完後，重新注入編輯器：scripts/inject_editor_deck.py（用剛儲存的 deck.json + 新背景） 4. 開啟新的 editor.html 讓使用者再確認一次，不要直接渲染 PPTX

不變的規則（格式 A / B 共同遵守） - 不要”解讀” / “總結” / “評論” JSON 內容——資料已定稿，只搬運 - 不要修改 deck.json 任何欄位——不改字號字色不重排版 - 以這一份 deck.json 為最新真相源——不用舊版本

反模式（不要做）

• ❌ 格式 B 有背景反饋卻直接渲染 PPTX —— 使用者的修背景意見會被丟掉
• ❌ 格式 A 收到又去問”要不要渲染” —— sentinel 已寫明，直接渲染
• ❌ 用之前生成的 deck.json 老版本渲染 —— 必須用貼回來的這一份
• ❌ 把 phasec-background-review-v1 段當成 Phase A review 去跑 render_review_markup.py
• ❌ 用背景反饋的意見直接改 deck.json.text_boxes（繞過背景問題）

使用者行為提示（agent 該告訴使用者的）

當 Phase C 編輯器開啟時，agent 應明確告訴使用者：

編輯器已開啟。 - 改完文字後：點右上角 ”匯出 / 繼續生成” → 複製整段（帶 === 標記）→ 貼上回對話方塊，我會直接渲染 PPTX - 發現背景要改：點 ”🖊 背景反饋” 切換到標註模式，對背景框選/畫筆/寫意見，然後同樣匯出整段貼回來，我會先修背景再重新開啟編輯器給你確認

兩件事可以同時做：先在文字模式調好字，再切到背景反饋模式標註，最後統一匯出一次即可。

失敗兜底

• 使用者只粘了裸 JSON（無 sentinel）→ 仍儲存為 phaseC/deck.json 並渲染，但提醒下次複製整段
• 使用者粘了 sentinel 但 JSON 有錯（缺 slides 等）→ 報錯，讓使用者回編輯器修後重新匯出，不自動猜補

何時使用本技能 / 何時只走 Phase A / 何時上 Phase C / 何時走 Phase D

★ Phase D 入口與 Sentinel 處理規則

觸發條件

當用戶滿足以下任一條件時，進入 Phase D： - 上傳或提供 PDF 檔案路徑，並提到"轉成可編輯" / "想改文字" / "PPT 編輯" - 明確說"把 PDF 轉成 PPTX" / "PDF 轉可編輯 PPT" - 提供 PDF 並詢問能否編輯其中內容

Phase D Sentinel 標記

當對話中出現以下標記時：

===PHASE-D / CONTENT EXTRACTION CONFIRMED===

本次從 PDF 提取了 N 頁內容，已在預覽頁確認。

===EXTRACTION JSON BEGIN===
{ ... }
===EXTRACTION JSON END===

agent 必須： 1. 把 ===EXTRACTION JSON BEGIN/END=== 之間的內容原樣寫入 phaseD/extraction_confirmed.json 2. 不解讀、不修改、不追問 JSON 內容 3. 直接進入 D3 背景處理： - 簡單頁（strategy: "clean"）→ 擦字保留原背景 - 複雜頁（strategy: "rebuild"）→ 仿照重建背景 4. 生成 phaseC/backgrounds/*.png 5. 把 extraction.json 轉成 phaseC/deck.json 6. 接入 Phase C 編輯器（C4-C6）

Phase D 不做的事

• ❌ 不主動詢問是否進入 Phase C（Phase D 本身就是為可編輯而生）
• ❌ 不跑 Phase A 的任何階段（風格預覽、規劃檔案、定稿圖）
• ❌ 不生成圖片型 PPTX（Phase D 直接輸出可編輯版）

Progressive Loading

按需讀，不要一上來全讀：

內建工作流殼子（assets/）

Phase A 必須使用以下 3 個本技能自帶的 HTML 殼子，不要替換或自造同類頁面：

• assets/preview_shell/index.html — 風格預覽比較（Stage 2）
• assets/candidate_picker_shell/index.html — 多候選選圖（Stage 4 多候選模式）
• assets/review_shell/index.html — 評審與返修（Stage 5）

Phase C 增加一個：

• assets/editor_shell/index.html — 文字編輯器（C4-C5）

⚠️ 四個殼子的 index.html 預設是空架子 / 示例資料：preview_shell 的 9 張圖是寫死的 SVG 佔位圖；candidate / review / editor 都帶示例資料。真正使用之前必須顯式注入真實資料，否則使用者開啟頁面看到的會是佔位。

統一注入命令（強制）：

```bash

Stage 2 風格預覽

python3 scripts/inject_shell_images.py preview \ --shell assets/preview_shell/index.html \ --data preview_data.json \ --out phaseA/previews/preview_filled.html

Stage 4 多候選選圖

python3 scripts/inject_shell_images.py candidate \ --shell assets/candidate_picker_shell/index.html \ --data candidate_data.json \ --out phaseA/candidates/picker_filled.html

Stage 5 評審

python3 scripts/inject_shell_images.py review \ --shell assets/review_shell/index.html \ --data review_data.json \ --out phaseA/review/review_filled.html

Phase C 文字編輯器

python3 scripts/inject_editor_deck.py \ --shell assets/editor_shell/index.html \ --deck phaseC/deck.json \ --out phaseC/editor.html ```

• 各 data JSON 的 schema 見對應指令碼頂部 docstring。
• 開啟時必須開啟 *_filled.html / editor.html，不要開啟 assets/.../index.html 原模板。
• 預設保留相對路徑，配合 HTML 與背景圖同目錄使用；要打包分發再加 --inline 把圖片 base64 嵌入 HTML，或加 --file-url 改成絕對 file://。
• editor.html 預設應與 phaseC/backgrounds/ 旁置，避免把背景內嵌成 7MB+ 的單檔案。
• build_*.py 三個指令碼只是把殼子從內嵌 base64 還原成 index.html，它們不注入真實資料，不要把 build 和 inject 搞混。

Phase A 規則（Conversation-first + Image-first）

按 references/phaseA/workflow.md 跑完所有 Stage。這裡只列死規則。

Working Principles

• 把使用者當成甲方，本技能當作提出方向的設計側。
• 不強迫使用者填一堆設計引數；把自然語言意圖翻譯成設計決策。
• 預設展示 baseline judgment / proposal cards / 預覽 / review 介面；規劃檔案原文按需出示。
• 標註 user_provided / inferred / needs_confirmation；不擅自編造未授權事實、資料、引用、機構結論。

Hard Rules（Phase A 必守）

• Preview-first：最終風格確認必須基於真實生成的「首頁 + 目錄頁 + 正文頁」預覽，不能用文字 mockup / ASCII 草圖 / 佔位殼代替。
• Shells are mandatory：必須使用 assets/preview_shell/index.html、assets/candidate_picker_shell/index.html、assets/review_shell/index.html。開啟前必須先用 scripts/inject_shell_images.py 把真實圖注入到 *_filled.html，不要直接開啟殼子原模板。
• Image-first 不退化：定稿出圖必須 image-first，不允許悄悄退化到"用 PPT shape 拼頁面"或"程式碼畫圖"兜底。
• 使用者要"加字 / 改字 / 補字"也仍然屬於影像生成/編輯任務；不要預設用 PIL / Canvas / SVG / HTML 截圖 / PPT 原生文本框去後期補字（除非使用者明確要求這種 workaround）。
• 生成 ID 不入 prompt：slide id / candidate code / 檔名 / 批次標籤等可以出現在規劃檔案、檔名、對映表、review UI、對話裡，但不要拼進發給影像模型的 prompt 文本。
• 不要在第一輪就匯出最終 PPT；只有 review 通過後才匯出。
• slide_blueprint.md 不能在風格反演確認之前寫。
• 生成前必須問：單圖直出 / 多候選 picker。
• Phase A 交付後必須主動詢問 Phase C（見上面"主動詢問"段）。

內建工作流的 5+ 個 Stage（極簡版索引）

1. Stage 1 — Intake + baseline judgment → 需求確認
2. Stage 1.25 — 風格前內容研究 → content_report.md（除非使用者已給完整稿）
3. Stage 1.4 ★ — 頁大綱確認門禁：寫 slide_outline.md，逐頁列出將要出現在 PPT 上的可見文字 + claim_status，貼摘要給使用者，等使用者確認後才進 Stage 1.5
4. Stage 1.5 — 風格邊界對齊（3 個短問題）
5. Stage 2 — 風格提案與真實預覽（首頁 / 目錄頁 / 正文頁），開啟 preview_shell；可選 Stage 2.5 refinement；必跑 Stage 2.75 風格反演確認 → 風格確認
6. Stage 3 — 順序寫 design_spec.md → slide_blueprint.md → spec_lock.md → 生成前確認
7. Stage 4 — 單圖直出 / 多候選 picker（若多候選先開啟 candidate_picker_shell）出齊全頁定稿圖
8. Stage 5 — 開啟 review_shell 做評審；不通過則用 scripts/render_review_markup.py 渲染標註圖 + 文本反饋再喂回去返修
9. Stage 5.5 — ★ 影像級 retouch（使用者驅動，可選）：詳見 references/phaseA/retouch.md
10. 交付 + 主動詢問 Phase C — 把圖片型 PPTX + 定稿圖 + 規劃文件交給使用者，主動問是否要可編輯文字版

Stage 5.5 Retouch（預設提供，按需使用）

Phase A 出圖被疊加了工具水印（典型如 Qoder 的 "Qoder AI生成"）、或某頁角落有想擦掉的小瑕疵時，預設提供以下兩個工具：

小蔥技能7w4.net持續更新中。

# 工具 1：批次去固定位置的角落水印（最省事，適合工具水印）
python3 scripts/remove_corner_watermark.py phaseA/slides/ -o phaseA/slides_clean/ --batch

# 工具 2：IOPaint 手工 inpaint（任意位置 / 複雜背景；效果最強）
# 首次自動調 setup_iopaint.py 裝 IOPaint + LaMa（約 5–10 分鐘、~3GB）
python3 scripts/launch_iopaint.py --slides-dir phaseA/slides

關鍵性質（agent 必須遵守）： - 絕不在使用者沒要求時強制啟動 IOPaint。Phase A 走完先告訴使用者圖在哪、PPTX 在哪、有沒有發現水印 / 瑕疵，再問要不要進 Stage 5.5。 - 首次啟動 IOPaint 會等待 5–10 分鐘裝環境 + 下模型，這點必須事先告訴使用者。 - 安裝完全冪等：標記檔案在 ~/.cache/ppt-craft-editable/.lama-installed，二次啟動秒開。 - 裝失敗不阻塞 Phase A 主路徑：launch_iopaint.py / setup_iopaint.py 都內建失敗兜底（重試 / remove_corner_watermark.py / ImageMagick 矩形遮罩）。 - retouch 不替代 review：實質內容 / 視覺改動應回 Stage 5 重出圖；Stage 5.5 只解決"圖整體沒問題，那一小塊要擦掉"。 - IOPaint 在 Phase C 裡也能用——擦字稿不合規時區域性塗抹擦乾淨比讓 imagegen 重出整頁省錢：python3 scripts/launch_iopaint.py --slides-dir phaseC/backgrounds。

完整工具說明、操作流程、何時該用 / 不該用，詳見 references/phaseA/retouch.md。

Phase C 規則（可編輯文字路徑）

僅當用戶在 Phase A 交付後的"主動詢問"中同意進入時才執行。完整流程在 references/phaseC/workflow.md，這裡只列死規則。

Hard Rules（Phase C 必守）

• 沿用 Phase A 的 Stage 1-3：需求 / 內容 / 風格 / 規劃檔案全部走 Phase A 已經做好的成果，不要重做。
• 以 Phase A 定稿作視覺參考：Phase C 的使用者承諾是參考 Phase A 結果重新生成無字背景，再疊加可編輯文字；不要把對外描述寫成“從 A 圖裡精確摳掉文字”。背景可能與 Phase A 定稿有細微差異。
• 優先直編 Phase A 成品圖：內部執行上仍預設先把 Phase A 定稿圖作為 imagegen edit target 去字；如果去字後不乾淨或留白不合規，再回退到重生成背景 + 擦字稿。對使用者說明時強調“參考定稿重新生成無字背景”，避免誤解為畫素級摳字。
• 回退時再走兩稿：只有在直編失敗時，才先出"完整稿"再以完整稿為 edit target 出"擦字稿"。不要把兩稿邏輯當成預設必走。
• edit target 先看 Phase A 圖：預設先 view_image Phase A 定稿圖，再調 imagegen，prompt 寫"以剛剛顯示的這張圖片作為唯一編輯目標"。不要只寫本地路徑。
• detect_reserved_zones 不可跳：每頁擦字稿必須用 scripts/detect_reserved_zones.py 校驗。不合規 → 重出 / IOPaint 區域性擦。
• 統一編輯器門禁不可跳：deck.json 寫好後，必須先注入編輯器開啟給使用者確認，再等使用者把匯出包貼回才能渲染 PPTX。不能跳過編輯器直接渲染。編輯器同時支援文字編輯和背景框選反饋，使用者做了背景反饋 → agent 先修背景 → 重出編輯器，不能直接渲染。
• 不要再插入獨立背景審計門禁：背景圖反饋統一在 C5 編輯器的 🖊 背景反饋 模式裡完成；本 skill 不再提供獨立背景審計殼子。
• deck.json 是單一真相源：編輯器 / 渲染器都消費 deck.json。不要在 PPTX 渲染後再單獨改 PPTX——回到 deck.json 改，重出 PPTX。
• 渲染前必須校驗 deck.json：json_to_pptx.py 會自動呼叫 scripts/validate_deck_json.py；若缺 background、座標越界、顏色格式錯誤或背景路徑不可訪問，必須先修 deck.json，不要猜補。
• 字型限定 SAFE_FONT_SET：見 scripts/json_to_pptx.py 頂部。不在集合裡會有警告，跨平臺可能掉 fallback。可用：PingFang SC / Microsoft YaHei / Hiragino Sans GB / Arial / Helvetica 等系統字型。
• 座標用 fraction：所有 x/y/w/h 都是 0-1，跟 HTML 編輯器和 PPTX 渲染器同語義。
• 字號用 pt：直接寫 font_size_pt，不要算畫素。
• 背景引用可為相對路徑 / 絕對路徑 / file:// / data:：編輯器匯出的 deck 可能帶這些形式，json_to_pptx.py 必須直接相容。
• 編輯器預設走旁置檔案模式：inject_editor_deck.py 預設保留相對路徑，editor.html 與 phaseC/backgrounds/ 放同一目錄；只有明確需要時才用 --inline。
• 背景圖固化、文字外掛：背景一旦生成就不再改（除非重出該頁）；文字始終是外掛層。
• 編輯器是單檔案 HTML：關閉瀏覽器不會自動儲存。改完一定要先點"匯出 deck.json"再關。
• Phase C 完成 = 終態：拿到可編輯 PPTX 後不要再追問 / 折返到其他路徑。

Phase C 流程極簡版（C1-C6）

1. C1 以 Phase A 定稿作視覺參考生成無字背景；內部先嚐試直編，不乾淨再回退到完整稿 → imagegen 擦字稿
2. C2 scripts/detect_reserved_zones.py 校驗預留區
3. C3 寫 phaseC/deck.json（每頁 background + text_boxes 初稿）
4. C4 scripts/inject_editor_deck.py 注入編輯器，生成 editor.html
5. C5 ★ 必跑 開啟 editor.html，使用者在統一編輯器裡完成：
6. 文字編輯模式：改字 / 拖框 / 調樣式
7. 背景反饋模式（按 🖊 背景反饋 切換）：矩形/畫筆/註釋點標註背景要改的位置
8. 匯出完整指令包貼回對話方塊
9. 若有 BG REVIEW 段 → agent 修背景 → 重出 editor.html → 使用者再確認
10. 無 BG REVIEW 段 → 進 C6 渲染
11. C6 scripts/json_to_pptx.py 渲染 → 可編輯 PPTX

關鍵命令（指令碼都在 scripts/）

# ─── Stage 0：使用者首次觸發，agent 默默跑（無需問使用者）──────

python3 scripts/preflight.py
# 自動安裝缺失的 4 個 pip 包（首次 2-5 分鐘），裝完調 doctor
# 退出碼 0 = 可繼續；退出碼 1 = 有不可自動修的專案，讓使用者處理

# 單純想看環境狀態（不動使用者系統）
python3 scripts/doctor.py

# ─── 基礎依賴（preflight 失敗時手動裝的兜底方案）─────────
pip3 install python-pptx pillow numpy opencv-python

# ─── Phase A ───────────────────────────────────────────────

# 把真實圖注入工作流殼子（每個 Stage 出圖後必跑）
python3 scripts/inject_shell_images.py preview   --shell assets/preview_shell/index.html           --data preview_data.json   --out phaseA/previews/preview_filled.html
python3 scripts/inject_shell_images.py candidate --shell assets/candidate_picker_shell/index.html  --data candidate_data.json --out phaseA/candidates/picker_filled.html
python3 scripts/inject_shell_images.py review    --shell assets/review_shell/index.html            --data review_data.json    --out phaseA/review/review_filled.html

# review markup 渲染（使用者在 review_shell 給的座標標註 → 標註圖）
python3 scripts/render_review_markup.py <review.json> --out-dir <dir>

# ─── Stage 5.5 Retouch（使用者驅動，可選）────────────────────

# 批次去角落水印
python3 scripts/remove_corner_watermark.py phaseA/slides/ -o phaseA/slides_clean/ --batch

# IOPaint：首次自動裝環境 + 下 LaMa（5–10 分鐘、~3GB），之後秒開
python3 scripts/launch_iopaint.py --slides-dir phaseA/slides
# Phase C 也可以用（擦字稿不合規時區域性塗抹）
python3 scripts/launch_iopaint.py --slides-dir phaseC/backgrounds

# 單獨管理 IOPaint
python3 scripts/setup_iopaint.py --check-only     # 檢查
python3 scripts/setup_iopaint.py                  # 裝
python3 scripts/setup_iopaint.py --reinstall      # 強制重灌

# ─── Phase C（使用者同意可編輯後才跑）─────────────────────────

# C2 校驗擦字稿的預留區是否真的留白
python3 scripts/detect_reserved_zones.py phaseC/backgrounds/01.png phaseC/01-zones.json --report phaseC/01-zones.report.json

# C4 把 deck.json 注入編輯器殼子（C5 使用者在裡面調文字 + 提背景反饋）
python3 scripts/inject_editor_deck.py \
    --shell assets/editor_shell/index.html \
    --deck  phaseC/deck.json \
    --out   phaseC/editor.html

# C6 deck.json → 可編輯 PPTX（+ 可選 PIL 近似預覽圖）
python3 scripts/validate_deck_json.py phaseC/deck.json
python3 scripts/json_to_pptx.py phaseC/deck.json -o phaseC/<topic>.pptx --preview-dir phaseC/preview

輸出目錄結構（建議）

<topic-slug>/
├── content_report.md                    # 僅當 Stage 1.25 生成
├── slide_outline.md                     # Stage 1.4 頁大綱確認門禁（必有）
├── design_spec.md
├── slide_blueprint.md
├── spec_lock.md
│
├── phaseA/                              # Phase A 產物（預設交付）
│   ├── previews/                        # 各階段風格預覽（保留備查）
│   ├── candidates/                      # 多候選模式時使用
│   ├── slides/NN-*.png                  # 評審通過的終圖
│   ├── slides_clean/                    # Stage 5.5 retouch 後的圖（可選）
│   ├── review/                          # 評審產物
│   ├── imagegen-manifest.json
│   └── <topic>-image-deck.pptx          # 圖片型 PPTX
│
└── phaseC/                              # Phase C 產物（使用者同意才出現）
    ├── backgrounds/
    │   ├── NN-full.png                  # 第 1 稿（完整稿，備查）
    │   └── NN.png                       # 第 2 稿（擦字稿，實際背景）
    ├── NN-zones.json                    # 每頁預留區宣告
    ├── NN-zones.report.json             # 校驗報告
    ├── deck.json                        # 單一真相源
    ├── editor.html                      # 注入後的編輯器
    ├── preview/slide_NN.png             # PIL 近似預覽圖（可選）
    └── <topic>-editable.pptx            # 文字可編輯 PPTX

外接快取（IOPaint 用，不在本目錄裡）：

~/.cache/ppt-craft-editable/
├── venv/                                # IOPaint 專屬 venv
├── .lama-installed                      # 安裝標記 + 後設資料
└── setup.log                            # 安裝日誌

安裝 / 依賴

把整個 ppt-craft-editable/ 複製到 agent 的 skills 目錄即可。完全自包含，不依賴其他外部 skill。

# Codex
cp -R ppt-craft-editable "${CODEX_HOME:-$HOME/.codex}/skills/ppt-craft-editable"

Python 依賴（基礎）：

pip3 install python-pptx pillow numpy opencv-python

Stage 5.5 IOPaint 是使用者首次觸發時自動安裝：

• 裝到專屬 venv ~/.cache/ppt-craft-editable/venv/，不汙染系統
• 自動 + 預下 LaMa 模型
• 國內預設走 hf-mirror 映象
• 首次約 5–10 分鐘、~3GB 磁碟；之後秒啟
• 裝失敗有明確兜底（remove_corner_watermark.py / ImageMagick）

影像生成路徑：依賴執行環境內可用的 imagegen 通道（Codex 用內建 imagegen / GPT Image 2）。如果執行時不可用，必須停在該 Stage 並向用戶說明阻塞原因，不允許用 PIL/SVG/Canvas/PPT shapes 兜底。

致謝

本技能起源於： - ppt-image-first（Phase A 工作流、references、templates、assets 部分原型） — Linux.do 社群

編排層、Stage 5.5 retouch 工具鏈、IOPaint 自動安裝與啟動器、Phase C 全套（雙軌生成 + detect_reserved_zones + HTML 編輯器 + json_to_pptx 渲染器）—— 本 skill 自有。商用時請同時標明上述來源。

這個 PPT 製作工具質量不錯，整體體驗流暢可靠。它的最大優點是自動化程度高——首次使用會自動檢查和安裝需要的環境，不用自己折騰。製作過程中有多次確認環節，確保每一步都符合你的預期。缺點是流程環節較多，有時需要等待生成和確認，整體花費時間可能偏長。另外文件對普通使用者來說稍顯專業，部分說明不夠通俗易懂。總體來說值得推薦，尤其是需要做高質量簡報的場景。