這個技能的作用
將簡報視為一個「建置」過程,而非文件:
| 成品 | 角色 |
|---|---|
template.pptx | 工具鏈 — 其投影片是原型目錄。永遠必要。 |
deck.mdx | 原始檔 — 唯一會編輯的檔案 |
assets/*.svg | 生成的圖稿,也是原始檔 — 僅含內容,不包含設計 |
deck.pptx | 建置成品 — 每次都會完整重新產生 |
deck.pdf + 頁面預覽 | 實際供人檢視的內容 — 唯一能確認版面配置的地方 |
每個輸出的投影片都是範本投影片的複製品,並替換其內容,因此範本的設計會逐位元組保留。沒有任何內容是從頭開始排版。
引擎:scripts/deck.py(使用絕對路徑呼叫)。
重新著色(適用任何 pptx;對於已建置的簡報,重新著色 template.pptx 並重新建置):scripts/ppt_keycolor_changer.py,步驟與預設值請參考 references/recolor.md — 探索、依亮度對應、確認、取代、驗證。
固定原則
- 沒有參考範本絕不建置。 沒有內建的簡報設計,也沒有備用方案。如果使用者沒有提供
.pptx,請停止並要求提供 — 不要以其他方式組合投影片,不要提供通用簡報,不要憑空捏造範本。引擎本身也會拒絕,但要求範本是你的責任,在任何工作開始之前。 - 原始檔是
deck.mdx,絕不是deck.md。 它會被編譯,而非直接讀取。引擎會拒絕任何其他副檔名。 - 先盤點再撰寫。 絕不憑猜測範本來撰寫
deck.mdx。請執行catalog,並根據它列出的插槽 ID 來撰寫。 - 絕不手動編輯輸出的 pptx。 下次建置時它會被重新產生。修正應寫入
deck.mdx。 - 在
build之前執行check,並向使用者顯示警告。 溢出警告是區分文字擁擠與投影片無法閱讀的關鍵。 - 可見性決定透明度,而非美觀。 當圖片的內容在投影片上仍然清晰可辨時,
| transparent是正確的選擇;check會指出何時不該使用,此時在圖片後面加上一個面板是更好的解決方案。不要因為聽起來比較乾淨就使用透明度。 - 未經告知絕不裁剪內容。
check會回報裁切百分比;請向使用者複述此資訊,並提供| fit選項。一張圖片失去一半內容,就像表格行掉出投影片一樣是缺陷。 - 絕不手動以二進位檔製作圖片插槽的圖稿。 撰寫 SVG,以便簡報能從文字重現。別人貼入的 PNG 無法重新產生、重新著色或進行差異比對。
- 簡報是給人看的,所以要實際檢視。 當可用的渲染器時,請以
render而非build結束 — 佈局審核和頁面預覽是唯一能發現文字衝突的地方。如果沒有可用的渲染器,請在報告中明確說明,不要暗示已檢查過佈局。 - 絕不發明原型。 如果沒有範本投影片能容納該內容,請提出並詢問是要調整內容還是擴充範本 — 不要試圖近似。
- 回報你選擇忽略的警告。 一個你覺得無關緊要的溢出警告,仍然應該出現在最終報告中 — 真正會看到那張投影片的是使用者。
- 圖表是唯讀的。 當所選的原型包含圖表時,請明確說明這一點;除非使用者在 PowerPoint 中編輯圖表,否則範本中的數字會保持不變。
流程
步驟 0 · 取得參考範本
如果你還沒有 .pptx,請在其他任何事情之前要求提供:
「레퍼런스 템플릿 pptx를 주세요. deck-builder는 템플릿 슬라이드를 복제하는 방식이라, 템플릿 없이는 만들 수 있는 슬라이드가 없습니다.」
請不要僅憑範本的描述、看起來相似的簡報或稍後再提供的承諾就繼續進行。
步驟 1 · 盤點範本
python3 /abs/path/scripts/deck.py catalog \
--template "template.pptx" --output "deck.catalog.md"
這會將每個原型印為 @s1…@sN,包含其插槽、範本目前顯示的內容以及容量估計。在任何其他事情之前,請先閱讀此輸出。
步驟 2 · 將內容對應到原型
如果你還沒有內容,請向使用者要求。然後,在撰寫任何 md 之前,請提出一個每張投影片一行的計畫:
1. @s1 표지 — 제목 + 부제
2. @s3 요약 — 불릿 3개 + 한 줄 결론
3. @s7 숫자 — 표 4행
獲得對計畫的確認。選擇錯誤的原型是代價高昂的錯誤,而非選錯措辭。
步驟 3 · 撰寫 deck.mdx
---
template: template.pptx
template_hash: 5f84440a3521 # 來自 catalog — 將簡報固定在範本的結構上
output: deck.pptx
---
## @s3
title: 분기 요약
text1:
- 응답 p99 **2.1s → 340ms**
- 배포 실패율 12% → 0.4%
table1:
| 지표 | 이전 | 이후 |
| p99 | 2.1s | 340ms |
pic1: assets/arch.svg
notes: 숫자의 출처를 먼저 말할 것
text5: !drop
圖片採用適應模式 — | fit 保留完整圖片,預設的 fill 會進行裁切 — 而 | transparent 會去除 PNG 的背景。你省略的插槽會保留範本的內容。
完整的語法 — 插槽形式、!drop、notes:、行內強調、大綱層級以及 template_hash 的保護作用 — 請參考 references/mdx-syntax.md。在撰寫第一張投影片之前,請先閱讀。
步驟 3b · 產生簡報所需的圖稿
將圖片插槽的圖稿撰寫為 .svg,使用範本的顏色,並符合 catalog 印出的框架精確 pt 尺寸。它會像簡報的其他部分一樣成為原始檔,並在建置時柵格化為 PNG。
規則、原理及實際範例:references/generated-art.md。
步驟 4 · 檢查
python3 /abs/path/scripts/deck.py check --deck deck.mdx
錯誤必須修正。警告則需要判斷 — 請逐一列出每一項,包括你決定忽略的那些。
| 測量項目 | 比對基準 |
|---|---|
| 表格或文字跑出投影片邊緣 | 投影片邊緣 — 錯誤,需指出遺失的行 |
| 一行對於範本保持單行的插槽來說太寬 | 該插槽自身的框架(以 em 為單位),因此韓文不會被算作拉丁文 |
| 一個插槽容納的內容遠少於範本放入的量 | 範本自身的容量 — 框架是為該容量繪製的,投影片會形成空洞 |
| 文字低於設計放置的位置 | 範本自身的行數及其下方的內容 |
| 裁切損失、有效 dpi、色板偏差、貼上框線 | 框架、螢幕及範本色板 |
| 文字覆蓋在圖片上 | 實際位於文字後方的像素:大型文字 3:1,內文 4.5:1 |
在先有文字後繪製圖片的投影片屬於錯誤 — 文字最終會被圖片遮蓋。
此處的每項估計都是根據範本自身的內容校準,而非絕對標準,因為大多數框架都是為了容納已經換行的文字而繪製的。約小於一行的邊距超出靜態估計的解析能力:只有步驟 6 能解決這些問題。
步驟 5 · 建置
python3 /abs/path/scripts/deck.py build --deck deck.mdx [--output out.pptx] [--strict]
相同的 deck.mdx 總是會產生位元組完全相同的 pptx。
步驟 6 · 渲染與檢視
python3 /abs/path/scripts/deck.py render --deck deck.mdx
建置、透過 LibreOffice 轉換、寫入每頁的 PNG 預覽,並審核渲染後的幾何 — overlap(兩個文字框衝突)、bunched(單一框內的行距比該框自身的標準更窄,表示文字已超出其容器)、off-slide(渲染器將其裁切)。乾淨就是乾淨:審核會跨框架進行比較,並根據每個框架的中位數測量行距,因此字元框超出 100% 行高的 CJK 字型不會觸發誤報。
render 會先告知渲染器缺少範本中的哪些字型。替換的字型會導致每一行重新換行,因此在安裝這些字型之前,預覽的換行是替換字型的結果,而非簡報本身的 — 解決方法是安裝字型,而不是縮短文句。pptx 本身總是指定正確的字型名稱。
請閱讀預覽以檢查佈局,而非間距。LibreOffice 預設會在 CJK 與拉丁字元之間加入間距,因此 평균 42분 在預覽中會呈現為 평균 42 분,而 pptx 中保留的是原始字串。在將間距視為缺陷之前,請檢查建置檔案中的 <a:t>。
渲染器為 PATH 上的 soffice 或 DECK_RENDER_DOCKER=<image>。兩者皆無時,render 會拒絕執行,而不是假裝已檢查過佈局 — 請如實告知,並退而使用 build。
輸出範本
建置後的報告:
빌드 완료 — <출력 경로>
슬라이드 <N>개 · 템플릿 <이름> · 이미지 <M>개 삽입
렌더 검사 — 겹침 0건 (또는: 3페이지 제목이 본문과 겹칩니다)
아키타입 사용
@s1 ×1 표지
@s3 ×4 본문
확인 필요
· 3번 슬라이드 title 58자 (프레임 ~39자/줄) — 두 줄로 넘어갑니다
· 5번 슬라이드 chart1 — 차트 수치는 템플릿 값 그대로입니다
다음 수정은 deck.mdx만 고치고 다시 build 하세요. 출력 pptx는 손대면 날아갑니다.
Claude 負責 / 你負責
| Claude | 你 |
|---|---|
| 要求提供參考 pptx,若無則拒絕繼續 | 提供範本 — 必備 — 以及原始內容 |
執行 catalog,讀取插槽對應表 | 審查原型列表 |
| 提出每張投影片的原型計畫 | 批准或重新安排計畫 |
撰寫和修改 deck.mdx | 在你喜歡的時候直接編輯 deck.mdx |
執行 check,回報所有警告 | 決定溢出警告是否重要 |
執行 render,檢視預覽,回報衝突 | 開啟 pptx,如有需要則編輯圖表 |
限制
以下六點會改變你能承諾的事:
| 限制 | 後果 |
|---|---|
| 沒有新的版面配置 | 每張投影片都是複製品。沒有對應原型的內容需要在 PowerPoint 中擴充範本 — 請如實告知,不要嘗試近似。 |
| 範本是強制性的 | 沒有內建設計,沒有備用方案。 |
| 圖表不可寫入 | build 會保留範本的數字。請在圖片插槽中使用 SVG。 |
| 框架永不移動 | 文字寫得短,間距依然存在;check 會回報,只有範本可以關閉它。 |
| 佈局真相需要渲染器 | check 進行估計,且無法解析小於一行的邊距。只有 render 能看到哪些東西衝突了。 |
| 可讀性僅限 PNG | 在 JPEG 或 SVG 背景上的文字不會被評分;繼承的文字顏色則保持不變。 |
完整表格,以及每個限制在哪個步驟被發現:references/limits.md。
相關技能
write:plans(文件目的) — 在將內容對應到投影片之前,先發展內容think:untangle-thoughts— 將零散的筆記轉化為步驟 2 所需的逐張投影片結構