该技能的作用
将演示文稿视为一个构建产物,而非文档:
| 工件 | 职责 |
|---|---|
template.pptx | 工具链——其幻灯片是原型目录。始终必需。 |
deck.mdx | 源文件——唯一需要编辑的文件 |
assets/*.svg | 生成的图形,也是源文件——仅内容,无设计 |
deck.pptx | 构建产物——每次完全重新生成 |
deck.pdf + 页面预览 | 人实际查看的内容——唯一存在布局的地方 |
每张输出幻灯片都是模板幻灯片的克隆,并替换其内容,因此模板的设计得以逐字节保留。无需从头开始布局。
引擎:scripts/deck.py(使用绝对路径调用)。
重新着色(任何pptx;对于已构建的deck,重新着色 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 — 将deck固定到模板的结构
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 · 生成deck所需的图形
将图片插槽的图形编写为 .svg,使用模板的颜色和框架的确切pt大小——两者均由 catalog 打印。它像deck的其余部分一样成为源文件,并在构建时被栅格化为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(渲染器裁剪了它)。干净意味着干净:审计跨框架比较并测量每个框架中位数的间距,因此em框超过100%行高的CJK字体不会触发误报。
render 首先会说明渲染器缺少模板的哪些字体。替换的字体重新包裹每一行,因此在这些字体安装之前,预览中的换行是替换字体的,不是deck的——解决方法是安装字体,而不是缩短单词。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所需的逐张幻灯片结构