LearnPrompt/humanize-ppt

Humanize PPT

當使用者想要將原始素材、筆記、語音轉錄、文件或連結轉換為可進行簡報的大綱和各頁媒體決策，然後再將其委派給下游技能進行渲染時，請使用此技能。不直接讀取舊的 PPT/PPTX 檔案：請先提取其文字內容（參見 scripts/pptx_qa.py 的 dump/inspect 輸出），然後將該文字作為 --source 餵入。對於 Humanize PPT 已經渲染過的 deck，則改用 --qa-from <rendered.pptx> 執行——這是「演講體檢」模式，而非摘要模式。

定位

Humanize PPT 是一個為實際演講而生的簡報系統：它是一個大綱導演（AST 聽眾狀態轉移——每翻一頁就推動聽眾前進一步）、一個逐頁視覺增強導演（真實圖片 / SVG 圖表 / Remotion 影片）、一個生產摘要編排器、一個演講體檢執行器（演講體檢；舊稱 QA 循環，CLI 參數仍為 --qa-from），以及一個講者模式交接器。動機：HTML-簡報範本技能擅長呈現概念，但會把一個簡單的想法擴充成十幾張漂亮的投影片，而一場真正的 90 分鐘演講大約只有 30 張——華麗的外殼超過了內容密度。Humanize 縮小了這個差距：它保留了美感（由下游範本技能原生渲染），並使其變得可演講——一條你站起來就能夠傳達的路線。下游範本技能負責「渲染得漂亮」；Humanize 則負責「這是一場演講，而且有人檢查過它了」。

用一句話來總結演講體檢：它不評分美感，它評分大綱。它將每個渲染後的頁面與其大綱頁面進行比較，找出那些只能觀看但無法講述的頁面，然後持續進行，直到每個頁面都成為講者可以站起來進行演講的頁面。一句話說明失敗的頁面：一個只包含幾個單詞且從未完成其觀點的頁面，或者一個未能實現其承諾的聽眾狀態轉移（聽眾在該頁面結束時與進入時的狀態相同）的頁面。這樣的頁面不應該存在；體檢會將其挑出並生成修正指示。

Humanize 與能夠消費純 markdown + JSON 的下游渲染器大致相容。已驗證的路線包括：中文 HTML → guizang-ppt-skill；英文 HTML → frontend-slides / beautiful-html-templates；原生可編輯 PowerPoint → ppt-master。其他下游渲染器仍然是可熱插拔的；支援等級記錄在 registry/renderer_registry.json 中，並且僅根據實際輸出進行調整。

它在下游 PPT / HTML 投影片技能之前以及渲染後的演講體檢前後執行。它擁有 AST 合約、逐頁媒體決策（這個頁面需要照片、系統圖表、10 秒流程短片，還是都不需要？）、下一個代理程式將使用的生產摘要，以及對已渲染 HTML/PPTX 的體檢通關。它不擁有渲染後的 deck 本身。

在渲染之前有兩個人類審查關卡：大綱預覽和渲染器的樣式關卡。HTML 路線使用 Humanize 的≥4 個真實封面的 --style-gallery。PPT Master 已經擁有自己的強制性三階段確認 UI，並附有原生視覺預覽，因此 --renderer ppt-master --style-gallery 會委派給該關卡，並寫入 style_gallery_plan.json + commands/style-gallery/ppt-master-confirm-ui.md，而不是重複該目錄。

使用者先調用一次 Humanize PPT 來產生摘要，將摘要交給下游技能進行原生渲染，然後再次調用 Humanize，使用 --qa-from <rendered.html|native.pptx> 來執行 3 次迭代的演講體檢。每次迭代都會寫入 qa_report.md、fix_prompt.md 和 qa_iteration.json。在 3 輪之後仍有殘留失敗項時，狀態會變更為 needs-human。

Humanize PPT 絕不複製下游技能的範本，絕不向其注入自訂章節，也絕不對渲染後的 HTML 或 PPTX 進行後處理。修正會回到下游的作者來源。請參閱 references/guizang-production-brief-orchestrator.md 和 adapters/ppt-master-bridge-notes.md。

對於公開定位，請將 Humanize PPT 描述為一個與原生下游渲染器配對的摘要編排器。不要將其定位為渲染器本身，也不要將其描述為為使用者挑選最佳視覺風格的「路由器」——那個決定存在於摘要、下游技能自己的範本以及人類的審查中。當使用者只需要一個漂亮的範本頁面時，那是渲染技能的工作，而不是 Humanize 的工作：陳述選擇，而不是禁止。

AST 理論

AST 代表「聽眾狀態轉移」（Audience-State-Transfer）。

• 聽眾 (Audience)：誰在聽，他們知道什麼，他們抗拒什麼，以及他們為什麼會繼續聽。
• 狀態 (State)：deck 之前和之後的聽眾狀態，以及阻止轉變的核心張力。
• 轉移 (Transfer)：逐張投影片的路徑，將聽眾從初始狀態移動到期望狀態。

核心句子：

投影片不是一個資訊容器。投影片是一個聽眾狀態轉移的產物。

必要的輸出合約

對於每次 Humanize PPT 執行，請產生：

1. deck_brief.md — 聽眾、目標、張力、成功標準。
2. ast_outline.md — AST 地圖和敘事弧線。
3. slide_plan.json — 逐張投影片的計畫，包含每個頁面的 media: {image, diagram, video} 決策和 layout_hint。
4. speaker_intent.md — 講者在每張投影片上應該做什麼。下游技能將其作為原生講者備註和簡報外殼的來源。
5. asset_manifest.md — Humanize 的每個頁面素材決策：哪個頁面需要哪種資產（圖片 / 圖表 / 影片）以及用途。
6. video_slots.json — 可選的 Remotion / HyperFrames / 原生影片插入計畫。
7. style_brief.md — 下游製作的視覺原則。
8. renderer_registry.json — 本次執行的渲染器能力快照。
9. router_plan.json — 選擇的主要渲染器和分階段的路由計畫。
10. commands/*.md — 為每個下游專家代理程式提供的有限指令。
11. run_manifest.json — 最終檔案清單、路由狀態和 QA 狀態。
12. <renderer>-production-prompt.md — 下游的進入點。除了 HTML 路線之外，ppt-master 還會產生 ppt-master-production-prompt.md + 自包含的 ppt-master-source.md 和可丟棄的 outputs/ppt-master-handoff/ 副本。
13. outputs/qa/qa_report.md — 首次 QA 關卡（摘要模式）或每次迭代的 QA 發現（QA 模式）。

QA 模式（渲染後）會為每次迭代額外產生：

14. outputs/qa/fix_prompt.md — 下游技能可操作的修正指示。
15. outputs/qa/qa_iteration.json — 輪次編號、狀態 (iterate / pass / needs-human)、未解決的發現項、歷史記錄。

樣式畫廊模式（--style-gallery，預覽大綱前的關卡）則會產生並停止：

16. HTML 路線：style_gallery.html 加上 ≥4 個封面條目。PPT Master：不產生虛假的畫廊 HTML；樣式選擇保留在其原生的確認 UI 中。
17. style_gallery_plan.json — HTML 的封面候選項，或 PPT Master 的 mode: downstream-confirm-ui。
18. commands/style-gallery/<id>.md — HTML 的封面指令，或原生關卡的 ppt-master-confirm-ui.md。

推薦的 OPC 工作流程 (v0.6.4)

O — 大綱 + 逐頁媒體導向
  Humanize PPT: 原始素材 → AST 大綱 + 逐頁媒體決策
  (deck_brief.md, ast_outline.md, slide_plan.json, speaker_intent.md,
   asset_manifest.md, video_slots.json, style_brief.md)

P — 原生渲染器調用 (100% 下游)
  zh  → guizang-ppt-skill        (樣式 A 或 B，原生；推薦)
  en  → frontend-slides / beautiful-html-templates (原生；推薦)
  pptx → ppt-master (原生 DrawingML；明確使用 --renderer ppt-master)
  其他 HTML-PPT 技能 → 可熱插拔，使用相同的摘要合約
  Humanize 產生生產提示並停止。下游技能渲染 deck。Humanize 不複製範本、不注入 SLIDES_HERE / [必填] 替換、不向渲染後的 HTML 添加 postMessage 橋接。

Q — 對渲染產物的演講體檢
  Humanize --qa-from <rendered.html|native.pptx> 讀取 P 的輸出，
  將頁面與大綱進行比較，掃描失敗模式
  (references/qa-failure-modes.md)，寫入 qa_report.md 和
  fix_prompt.md，在 qa_iteration.json 中追蹤迭代。
  限制：3 輪。輪次上限後若仍有殘留發現項，狀態變更為 needs-human。

C — 完成 / 控制
  下游技能原生的講者備註 + 簡報外殼 + 部署
  (v0.6.4 中 Humanize 不擁有這些——摘要告訴下一個代理程式
  以該下游技能自己的格式產生它們)

規則

v0.6.4 不變項（這些是硬性規則；如果你違反任何一條，你就脫離了 v0.6.4 的邊界）

1. Humanize 僅是摘要提供者。 它撰寫渲染器生產合約然後停止。它不打開、複製或後處理下游範本或最終的 HTML/PPTX。
2. 下游渲染器是 100% 原生的。 下一個代理程式遵循該下游技能自己的 SKILL.md。摘要告訴下一個代理程式要載入哪個技能、使用哪個樣式（A/B）、從哪些版面配置中挑選、以及哪些 QA 關卡必須通過——但它不攜帶範本內部細節。
3. 演講體檢限制為 3 次迭代。 第 4 輪若仍有殘留失敗發現項則為 needs-human。迴圈不會永遠運行；它會將決策權交回給人類。
4. 講者備註和簡報外殼 — Humanize 產生一個 baseline presenter-shell.html；下游擁有完整的舞台。 Humanize 擁有語義來源 (speaker_intent.md)，現在也直接從 slide_plan.json + speaker_intent.md 寫入 outputs/presenter/presenter-shell.html（即使在下游 deck 存在之前即可獨立使用）。下游技能產生原生的講者備註和更完整的講者控制台。Humanize 不會向渲染後的 HTML 注入 postMessage 橋接或 ?slide= 網址參數。
5. 生產提示是下游的進入點。 它指定了渲染器必須讀取的每個支援產物。PPT Master 還會讀取 ppt-master-source.md，它在不重複 PPT Master 視覺合約的情況下凍結 Humanize 的頁面故事和備註意圖。

工作規則

6. 當 Humanize PPT 可以先生成 AST 合約時，不要讓投影片渲染器直接消費原始素材。
7. 保持下游技能作為完整舞台視圖的所有者；Humanize 的 presenter-shell.html 是一個功能性 baseline，而不是原生控制台的替代品。
8. 從人性化工具中吸收 AI 撰寫清理原則，但不要將 Humanize PPT 簡化為文字潤飾。
9. 優先選擇一個經過驗證的小型工作流程，而不是一個廣泛而未經證實的承諾。
10. 對於公開的 Skill 版本，請創建/推送儲存庫，從 GitHub 本地安裝，運行一個安全完整的範例，在驗證過的已知良好檢查點 (examples/03-codex-guizang-native-ink-classic/) 上驗證摘要 + 演講體檢，然後才修飾 README 細節。
11. 對於 Agent Teams 開發，在連接實際下游 Skills 之前，請先發出 router_plan.json、run_manifest.json、有界指令的 commands/*.md 以及每個渲染器的生產提示。
12. 對於 WorkBuddy/CodeBuddy 團隊上傳套件，不要將 demo 或渲染後的 HTML 輸出打包成團隊 zip。上傳的 zip 必須鏡像像 trading-team 這樣的團隊插件結構：根目錄下的 .codebuddy-plugin/plugin.json、agents/、skills/、rules/ 和 setting.json（以及可選的 avatars/、.workbuddy-plugin/、README.md、settings.json）。rules/ 目錄應包含一個情境規則檔案，例如 rules/<plugin-name>_rules.md，其中包含 frontmatter（description、alwaysApply、enabled、updatedAt、provider）和一個描述可用代理程式、技能、SOP 和使用要求的 <system_reminder> 區塊。使用 unzip -l 驗證根目錄不是 index.html/assets/screenshots/source，也不是被資料夾包裹，除非目標上傳器明確需要包裹目錄。
13. 不要將 HyperFrames/Remotion 影片視為一個取代 PPT 內容的單一嵌入式播放器。對於 Humanize PPT 的可交付成果，影片工具是素材生產者：轉場、解釋短片、前後對比、談話素材插入、社交預覽，以及填充特定投影片需求的替代靜態圖片。每個頁面的 media.video 決策（請參閱 slide_plan.json 結構）告訴下游技能哪些頁面需要 Remotion 剪輯、用途以及持續時間。

操作參考文件

• references/guizang-production-brief-orchestrator.md — 標準摘要規範：<renderer>-production-prompt.md 必須包含和不包含的內容。
• references/qa-failure-modes.md (+ 英文鏡像 references/qa-failure-modes.en.md) — 演講體檢的失敗模式目錄；程式碼端的來源是 scripts/humanize_ppt_v2.py 中的 FAILURE_MODES。
• references/style-gallery-spec.md — --style-gallery 封面樣式關卡。
• references/renderer-guidance.md — 每個渲染器的建議路徑和已知良好的檢查點規則。
• references/renderer-verification.md — frontmatter 單行描述背後的每個渲染器驗證證據。
• adapters/ppt-master-bridge-notes.md — 原生 PPTX 路線邊界和 OOXML 體檢合約。
• SPEC.md — 引擎技術規範：CLI 界面、資料流程、輸出合約、樣式畫廊、體檢、媒體模型、渲染器註冊表。
• 所有參考文件、轉接器、版本說明的完整註釋索引：docs/index.md。

本地演示

推薦的穩定進入點是 scripts/humanize_ppt.py（版本化的腳本保留作為相容性墊片）。完整的 CLI 範例——摘要模式、演講體檢、原生 PPTX、大綱預覽、舊版進入點——均位於 docs/local-demo.md。

--out 警告： 將 --out 指向一個專用的運行目錄。摘要模式每次運行都會從頭重建它，但僅在該目錄不存在、為空或已經是先前的 Humanize PPT 運行（根目錄下包含 run_manifest.json / style_gallery_plan.json / outline-preview.md / preview-confirmed.json）時才會自動清除它——否則它會拒絕並要求使用 --force。