ppt — 程式碼生成專業簡報
程式碼畫 PPT，不拖範本：可重複執行（改資料重跑腳本）、可進 git、座標精確到 0.01 英吋；無所見即所得，靠 Step 4 渲染核查兜底。
Step 1 · 取材與文案（禁止編造）
先回答受眾三問再動筆：給誰看（外行 / 內行 / 客戶）？觀眾對專案已知道什麼？看完要能複述哪三句話？答案寫在文案稿頭部，之後所有取捨用它裁決。
素材只取專案真實資料（README / CLAUDE.md / docs / 資料後台，按類型選源）。沒有出處的數字不進 PPT；觀眾不需要的事實不進正文——內部指標（函數數、API 常數、內部代號）預設出局，受眾是內行才留。
挖掘內容，不摘名詞：光收集數字和功能名不算取材。按 PPT 類型挖掘，技術/產品：設計決策 + 效果對比；作品集：作品細節與取捨；數據報告：口徑與基線；敘事品牌：人物、場景、轉折。
大綱先於逐頁：挖掘完先寫敘事大綱——一條主線（整份 PPT 只論證一件事）+ 開篇三答（是什麼 / 給誰 / 解決什麼）+ 每頁在論證鏈裡的角色（承接上頁什麼、鋪墊下頁什麼）。概念先解釋後使用，禁止前向引用；連續兩頁互不承接 = 重新排列。逐頁文案稿（標題 + 要點 + 口播稿；口播稿生成時放進 notes() 演講者備註，是介紹成片工作流程的文案來源與現場講稿）附在大綱下撰寫，標題要參與遞進，而不是各自成立的口號。
兩遍成稿：第一遍寫足——完整敘述體，假設觀眾零基礎，把是什麼、給誰、解決什麼講透，允許長；第二遍才打磨——先 humanizer 去味、再按下面四條修剪。humanizer 是打磨器不是初稿範本，初稿就按它的標準寫只會又瘦又跳、沒講清楚就開喊口號。
- 不許空轉：要點帶細節（功能帶設計理由或效果、數據帶口徑），裸名詞陳列刪掉
- 數字帶語境：數值 + 口徑 + 構成或對比，且是觀眾在乎的數字；挖不到語境的數字不當主視覺
- 每頁 ≥3 件可溯源的具體事實；遮住排版只讀文字，是在『講』不是『列清單』
- 槽位規則：大字槽（封面主標題 / 尾頁大字 / 章節名）只放主張句或身份句（有觀點、唸出來像口號）；網域名稱、版本號、日期、統計數字一律退至副題 / 元資訊位
風格行話零容忍，分兩層：商業八股（賦能 / 閉環 / 沉澱 / 矩陣 / 生態 / 一站式 / 端到端）直接刪；技術行話（API 常數 / 內部函數名 / 體系代號 / 實作細節）按受眾過濾，外行 PPT 要嘛刪除，要嘛在該頁用人話解釋。數字優先於形容詞；標題寫觀點不寫名詞短語；破折號中英雙禁。重要專案文案稿先給使用者過目再排版。
Step 2 · 設計系統（寫程式碼前定案，全程不改）
| 維度 | 規則 |
|---|---|
| 色板 | 從專案設計語言提取（README 視覺節 / 站點主色 / 品牌 VI）；無則 use_theme('warm' / 'tech' / 'forest')。7+1 封閉系統（7 角色 + 紙白），中途禁止加色；小字對底色 ≥4.5:1 |
| 網格 | 16:9（13.333 × 7.5 in）· 邊距 0.55 · 頁碼 (12.35, 7.02) · 頂部 coral 短槓 + 章節 label |
| 字號 | 54 封面 / 40 大數字 / 30 頁標題 / 19 卡片題 / 13 正文 / 11 次要 / 9 註釋，禁用中間值 |
| 字體 | 中文雅黑；程式碼 / 網域名稱 / 數字 / 版本號一律 Consolas |
| 密度 | 每頁一個論點；文字超過 3 行拆頁，表格超過 6 行砍行 |
Step 3 · 生成
pip install python-pptx -i https://pypi.tuna.tsinghua.edu.cn/simple（首次）- 複製
templates/primitives.py+animate.py到目標專案scripts/，撰寫gen-<name>-deck.py - 座標用表達式計算（如
Inches(0.55 + i * 3.13)），不寫魔法數字；塞文字前check_fit()預檢，[FIT-WARN]即拆行 / 拆頁
動畫（可選；Windows + MS Office + pywin32）。預設 auto_deck() 全權代勞（封面級聯 / 卡片 float_up / 數字 zoom / 鏈路 wipe / 表格行 0.06s 快級聯 / 章節序號 wipe up），手動只做微調：
anim = Anim(prs)
Anim.auto_deck() # 整份 PPT 自動編排
Anim.fx(footer, 'fade', dur=0.4) # 特殊元素補一槍
Anim.chart(gf, 'series') # 原生圖表按系列擦入
P.set_transition(prs, 'fade') # 統一轉場（morph 頁自動跳過）
P.auto_show(prs) # 口播稿估時自動換頁：整份 PPT 自動播完，錄影即粗片
prs.save('deck.pptx')
Anim.apply('deck.pptx') # 必須在 save 後；COM 寫入 + 讀回自驗證
# 微調：Anim.stagger(P.shape_groups(s, 'card'), 'float_up', step=0.12)
# 增長敘事（morph 真補間，佔連續兩頁，auto 自動跳過；生效驗證 EntryEffect==3954；2019+，WPS 降級 fade）：
P.growth_chart(prs, 6, 'Growth', '標題', cats, vals, highlight=2) # 柱/條
P.growth_line(prs, 8, 'Trend', '標題', cats, vals, highlight=5) # 折線
P.growth_donut(prs, 10, 'Mix', '標題', cats, vals) # 佔比環
效果詞表（COM 實測）：fade / wipe / appear / float_up / float_down / zoom / grow_turn / ease_in / split / wheel / stretch；90 年代花招不收。節奏 > 花招：時長 0.40.6s、級聯間隔 0.10.2s、一頁 ≤2 種效果、頁面固定裝飾（頂部短槓 / 頁碼 / 底線）不進動畫；數據圖表一律 growth_*，原生 chart 僅交付後要在 PowerPoint 改數據時使用。
修改現有 pptx（腳本修改，禁止手動修改，save 到新檔案名稱）：P.deck_replace(prs, {'舊名': '新名'}) 全文替換（含備註）；P.deck_recolor(prs, dict(zip(P.THEMES['warm'].values(), P.THEMES['tech'].values()))) 整份 PPT 換主題。
頁面範式（字典非 checklist：按 Step 1 敘事大綱選範式，不為湊範式造內容；同一範式重複使用沒關係，一份 PPT 集郵式 9 種範式各來一次是能力巡展不是敘事；密度靠 Step 1 餵飽，不靠範式本身）：
| 範式 | 函式 | 用途 |
|---|---|---|
| 封面 | slide_cover | 開場：大標題 54 + 右豎色塊 |
| 章節頁 | slide_section | 12+ 頁長稿導航，雜誌風（框架線 + 暗紋序號 + 條目） |
| 時間軸 | slide_timeline | 演進 / 路線圖，hi 高亮當前位置 |
| 對比頁 | slide_versus | A/B、前後對比，中縫 VS 圓標 |
| 金句頁 | slide_quote | 一句值得整頁的話（12+ 頁 PPT） |
| 卡片陣 | slide_cards | 並列職能 / 模組，自動換行 |
| 數字牆 | slide_numbers | 等權指標一覽 |
| 圖文頁 | slide_media | 截圖 + 要點；sidebar= 大圖六成 + 圈註 + 腳註 |
| 高密度分區 | slide_dense | 一頁講透子系統：主區 60% + 側區分組清單 |
| 真表格 | slide_table | API / 模型 / 清單對照，6~9 行，列寬層級 |
| 鏈路圖 | slide_chain | 架構流向，hi 反色強調 + subs 卡 |
| 雙欄清單 | slide_rows | 技術棧 / 配置 |
| 增長圖 | growth_chart / line / donut | 數據增長 morph 真補間 |
| 原生圖表 | bar / line / donut_chart | 交付後要在 PowerPoint 改數據 |
| 尾頁 | slide_closing | 聯絡方式；slogan= 自訂大字（主張句） |
Step 4 · 渲染核查（必做，不可跳）
三級管線，自動化優先，人工只看終稿：
① 程式初篩：Office COM 轉 PDF（Presentations.Open 後 SaveAs("<輸出>.pdf", 32)）→ python <本skill>/templates/verify.py <輸出>.pdf。檢查頁級溢出、佔位符、對比度 WCAG（≥72pt 裝飾大字豁免）；退出碼 1 = 有問題，修改腳本重新執行。
② 視覺盲看：pymupdf 渲染 PNG（fitz + get_pixmap(dpi=100)）→ 交給無生成上下文的子代理兩問：其一逐頁檢查四項（溢出 / 亂碼 / 對齊 / 對比度）；其二觀眾複述測試——只給它前 1/3 頁，問「這是什麼、給誰用、解決什麼問題」，答不出 = Step 1 受眾或開篇沒做對，打回重寫文案再生成。盲看提示裡不要預設豁免（不說『這是故意的』）：被頁緣裁切的元素、超大低對比裝飾字這類可疑形態，同樣交給新鮮眼光當疑點回報。發現問題修改腳本重新執行，禁止手動修改 pptx。
視覺核查使用實際圖片的絕對路徑，複查核對當前版本或哈希；遇到具體工具的路徑限制時再選相容路徑，不固定要求複製目錄。
③ 使用者終審：前兩級清零機械問題後，使用者只看成稿。
Step 5 · 交付
報告：頁數 + 頁面清單 / 檔案路徑與大小 / 三級核查結論 / 口播稿頁數 / 自動放映總時長 / 生成腳本位置（可重複執行）。git 倉庫內提交腳本（pptx 產物不進 git）。
邊界與陷阱
- 無 MS Office → Step 4 降級 LibreOffice
soffice --convert-to pdf；兩者都無 → 明確報告「未做視覺核查」 - GBK 主控台：print 禁用非 ASCII 字元，用
OK - pptx 原生表格列寬失控 → 一律自繪表格行（box + text 逐行拼）
- 中文缺字形 → run 級設雅黑（primitives 已處理）
- shape_id 每頁獨立編號不唯一，animate.py 已按 XML 樹定位，二次開發勿全域搜尋 id；pywin32：
pip install pywin32 -i https://pypi.tuna.tsinghua.edu.cn/simple - docx / xlsx 可複用 primitives 思路，但頁面範式表僅適用 pptx
目前工作流程與歸檔
content-director 負責受眾、材料出處和敘事草案，PPT 保留可編輯投影片的交付目標。設計確認後再生成；影片靜幀規則不套用到 PPT。生成腳本、輸入數據、必要素材及其雜湊值隨 recipe 保留，交付清單聲明 PPT/PDF/封面；歸檔恢復校驗前不清場。視覺核查與使用者終審分別報告。