ppt-master

PPT Master Skill

AI 驅動的多格式 SVG 內容生成系統。透過多角色協作將原始文件轉化為高品質 SVG 頁面，並匯出為 PPTX。

核心流程: 原始文件 → 建立專案 → [範本] → 策略師結構化規劃 → [圖像生成器] → 執行者即時預覽 → 品質檢查 → 後處理 → 匯出

SVG 頁面設計邊界

範圍	規範契約
任何透過 SVG 創作或重新生成簡報視覺效果的路線	svg_output/ 是完整的頁面設計來源：匯出的投影片上應出現的所有可見文字、圖片、形狀、圖表/表格備用方案以及版面配置元素，均已存在於該頁面 SVG 中或被其引用。
範本、design_spec.md 與 spec_lock.md	創作與控制輸入。它們引導 SVG 的建立，但「絕對不能」提供在匯出時完成的 SVG 中所缺失的可見投影片內容。
語義 SVG 標記	僅在考量了現有的 Layout/Layer/Placeholder/Native 元資料後才使用的最小化渲染中立編譯器提示。它們絕不會取代原生的 SVG 幾何圖形、文字、樣式、分組或資產引用。
svg_final/	必要的衍生、自包含 SVG 視覺預覽。它可以直接開啟或作為 SVG 圖片插入 PowerPoint 中，但它不是受支援的 PPTX 來源，也不具備手動「轉換為形狀」的相容性契約。
SVG 到 PPTX 匯出	唯一受支援的生成式 PPTX 路線，其會讀取 svg_output/ 並透過專案轉換器將其內容對映至 DrawingML/原生物件。它可以將所呈現的內容重組為母片/版面配置/投影片結構，但「絕對不能」憑空捏造新的可見頁面內容。
直接 PPTX 及簡報行為工作流程	保持獨立。template-fill-pptx、native-enhance-pptx、動畫、切換、講者備忘錄、旁白以及套件關聯性不需要透過 SVG 進行雙向轉換。

MUST — 頁面設計封閉性: 對於 SVG 創作路線，請檢查最終的頁面 SVG 以確定匯出的投影片外觀。請勿將「SVG 是頁面設計語言」誤解為「SVG 是完整的 PPTX 套件描述語言」。

[!CAUTION]

🚨 全局執行紀律（強制執行）

本工作流程為嚴格的串列流程。以下規則具有最高優先級 — 違反其中任何一條即視為執行失敗：

1. 串列執行（SERIAL EXECUTION） — 步驟「必須」按順序執行；每一步的輸出即為下一步的輸入。非 BLOCKING 的相鄰步驟在滿足前置條件後可連續進行，無需等待使用者提示「繼續」
2. 阻塞即停（BLOCKING = HARD STOP） — 標記為 ⛔ BLOCKING 的步驟需要完全停止；AI 在繼續前「必須」等待使用者的明確回覆，且「絕對不能」代表使用者做出任何決定
3. 禁止跨階段打包（NO CROSS-PHASE BUNDLING） — 嚴禁跨階段打包。（注意：第 4 步中的策略師確認階段為 ⛔ BLOCKING — AI「必須」提出建議並等待使用者的明確確認後方可繼續。一旦使用者確認，所有後續的非 BLOCKING 步驟 — 設計規範輸出、SVG 生成、講者備忘錄和後處理 — 均可自動進行，無需使用者再次確認）
4. 進入前檢查關卡（GATE BEFORE ENTRY） — 每個步驟頂部均列出了前置條件（🚧 GATE）；在開始該步驟前「必須」驗證這些條件
5. 禁止推測性執行（NO SPECULATIVE EXECUTION） — 嚴禁為後續步驟「預先準備」內容（例如在策略師階段編寫 SVG 程式碼）
6. 禁止由子 Agent 生成 SVG（NO SUB-AGENT SVG GENERATION） — 執行者第 6 步的 SVG 生成依賴上下文，「必須」由當前主 Agent 端到端完成。嚴禁將頁面 SVG 的生成委派給子 Agent
7. 僅限順序逐頁生成（SEQUENTIAL PAGE GENERATION ONLY） — 在執行者第 6 步中，確認全局設計上下文後，頁面 SVG「必須」在一次連續流程中逐頁順序生成。嚴禁分組批量生成頁面（例如一次生成 5 頁）
8. 每頁重新讀取 SPEC_LOCK（SPEC_LOCK RE-READ PER PAGE） — 在生成每個 SVG 頁面之前，執行者「必須」執行 read_file <project_path>/spec_lock.md。所有顏色 / 字型 / 圖示 / 圖片「必須」來自此檔案 — 不得使用記憶中的數值或臨時捏造。執行者還「必須」讀取 pptx_structure.mode、當前頁面的 page_rhythm（anchor / dense / breathing）以及 page_charts。只有簡報組/版面配置範本路線（mode: structured）才需要查詢 page_layouts（輸入範本 SVG）、page_pptx_layouts（頁面分配）、pptx_masters、pptx_layouts（可重複使用的名冊）以及 template_adherence；自由設計與純品牌路線使用 mode: flat 並省略這些區段。此規則旨在防止長簡報中的上下文壓縮漂移，並打破預設的統一「每頁都是卡片網格」模式
9. SVG 必須手寫，禁止腳本生成（SVG MUST BE HAND-WRITTEN, NOT SCRIPT-GENERATED） — 每個 SVG 頁面均由主 Agent 直接編寫，一次編寫一頁（參見規則 6 與 7）。編寫或執行 Python / Node / shell 腳本來批量生成 SVG 檔案（例如在頁面上迴圈、透過資料套用範本或透過生成器輸出）是「嚴格禁止」的，包括以「節省 Token」、「快速草稿」或「使用者趕時間」為藉口。腳本生成路線曾在大功能分支上嘗試過但已廢棄：跨頁視覺一致性取決於包含完整上游上下文的單頁創作，而生成器腳本無法重現這一點。狹義例外：preset_shape_svg.py 可以在主 Agent 選定其語義角色、圖框和著色後，將一個確定性的預設圖形片段輸出至 stdout。它不能寫入 svg_output/、選擇版面配置、批量處理圖形或生成頁面；主 Agent 讀取該片段並透過正常的手工頁面編輯將其插入
10. 遵循確定性路由規則（FOLLOW DETERMINISTIC ROUTING RULES） — 當此 Skill 已定義路線時，請勿新增阻塞式的路由詢問。如果使用者請求違反了路線的前置條件，請說明所需的前置條件並停止該路線，而不是要求使用者繞過規則進行選擇。一般的有限選項、風格偏好和可修復的細節，應在下一個現有的確認關卡中提供建議值及備選方案。

[!IMPORTANT]

🌐 語言與溝通規則（Language & Communication Rule）

• 回覆語言：需匹配使用者的輸入和來源材料。使用者的明確指定（例如「請用英文回答」）具有優先權。
• 面向使用者的選項標籤：在呈現確認、簡短提案、選擇或有限選項集時，標籤與說明請使用使用者的語言。英文的 enum ID / 檔案欄位名稱可以在括弧中標註以求精準，但絕不能僅依賴英文標籤（如 deck、layout、mirror 或 fidelity）而沒有在地化說明。
• 範本格式：無論對話語言為何，design_spec.md「必須」遵循其原始的英文範本結構（章節標題、欄位名稱）。內容數值可以使用使用者的語言。

[!IMPORTANT]

🔌 與通用程式碼編寫 Skill 的相容性

• ppt-master 是一個特定於儲存庫的工作流程，而不是通用的應用程式架構
• 預設「切勿」建立 .worktrees/、tests/、分支工作流程或通用的工程結構
• 與通用程式碼編寫 Skill 衝突時，除非使用者另有明確說明，否則請遵循本 Skill

規則強度標籤

標籤	含義
MUST	要求的行為；違反即為工作流程失敗
MUST NOT	禁止的行為
DEFAULT	使用者未另作說明時使用的預設行為
OPTIONAL	僅在明確觸發或路線要求時執行
FALLBACK	主路線失敗後的復原路徑
GATE	進入下一步前必須通過的檢查點

跨領域管理權限

關注點	管理權限來源	規範契約
主流程順序	本 SKILL.md	擁有第 1-7 步的順序、關卡、角色切換及強制命令
路線選擇	workflows/routing.md	在主流程或獨立工作流程之前擁有確定性的路線選擇權
工作流程註冊表	workflows/index.md	擁有獨立工作流程的觸發條件/前置條件/輸出清冊
產出物所有權	references/artifact-ownership.md	擁有事實通道、原始/衍生產出物邊界及重新生成規則
失敗復原	workflows/failure-recovery.md	擁有常見失敗的停止/繼續決策權
確認介面細節	scripts/docs/confirm_ui.md	擁有 Schema、啟動器行為、通訊埠策略及聊天備用方案細節

主流程腳本

腳本	用途
${SKILL_DIR}/scripts/source_to_md.py	統一的來源轉 Markdown 分發器 — 指定檔案或 URL 值的預設第 1 步進入點
${SKILL_DIR}/scripts/pptx_intake.py	標準 PPTX 攝取強化 — 畫布 / 識別 / 投影片幾何圖形 / 表格 / 原生圖表資料 / SmartArt 結構
${SKILL_DIR}/scripts/project_manager.py	專案初始化 / 驗證 / 管理
${SKILL_DIR}/scripts/icon_sync.py	在選定時將所選圖庫圖示複製至 <project>/icons/；遺失的名稱回報 + 非零退出碼（重新選擇關卡）
${SKILL_DIR}/scripts/analyze_images.py	圖片分析
${SKILL_DIR}/scripts/latex_render.py	LaTeX 公式渲染（Manifest 驅動的 PNG 資產）
${SKILL_DIR}/scripts/image_gen.py	AI 圖片生成（多提供者）
${SKILL_DIR}/scripts/slice_images.py	將一張 AI 插圖圖集切片為獨立的局部插圖元素
${SKILL_DIR}/scripts/svg_authoring_view.py	建立 PPTX 匯入之 SVG 的輕量級非破壞性檢查投影；絕非發佈來源
${SKILL_DIR}/scripts/svg_quality_checker.py	SVG 品質檢查
${SKILL_DIR}/scripts/preset_shape_svg.py	印出一個由註冊表支援的原生 PowerPoint 預設圖形片段至 stdout，以供手動創作 SVG 時插入
${SKILL_DIR}/scripts/total_md_split.py	講者備忘錄拆分
${SKILL_DIR}/scripts/finalize_svg.py	SVG 後處理（統一進入點）
${SKILL_DIR}/scripts/svg_to_pptx.py	匯出至 PPTX
${SKILL_DIR}/scripts/native_enhance_pptx.py	現有 PPTX 增強專案初始化 / 驗證 / 直接 OOXML 補丁匯出
${SKILL_DIR}/scripts/native_narration_pptx.py	現有 PPTX 備忘錄 / 旁白增強的向下相容進入點
${SKILL_DIR}/scripts/update_spec.py	將 spec_lock.md 的顏色 / font_family 變更同步至所有生成的 SVG

完整的工具說明文件請參閱 ${SKILL_DIR}/scripts/README.md。

Windows 注意事項：若 python3 ... 命令失敗（常見於 python.org 的安裝，其提供 python.exe 但不提供 python3.exe），請改用 python 重新執行相同的命令。

範本索引

索引	路徑	用途
版面配置範本	${SKILL_DIR}/templates/layouts/layouts_index.json	查詢可用的頁面版面配置範本
品牌預設	${SKILL_DIR}/templates/brands/brands_index.json	查詢可用的品牌識別預設（色彩 / 排版 / 標誌 / 語調）
視覺化範本	${SKILL_DIR}/templates/charts/charts_index.json	查詢可用的視覺化 SVG 範本（圖表、資訊圖表、圖解、框架）
圖示庫	${SKILL_DIR}/templates/icons/	請參閱 ${SKILL_DIR}/templates/icons/README.md；按需使用 ls templates/icons/<library>/ | grep <keyword> 搜尋圖示

獨立工作流程

路線管理權限：使用 [`workflows/