| name | ppt-creation |
| description | 当任务要求创建、读取、解析、提取、编辑、修改、合并、拆分、转换或检查 PPT / 幻灯片 / 演示文稿 / deck / slides / presentation / .pptx 文件时使用。本 skill 以内置模板为版面底座，让 Agent 在内容区自由设计；支持原生 PptxGenJS 绘制、可选组件、用户素材、论文原图和合规网络素材。 |
PPT Creation
核心模型
本 skill 生成的 PPT 由三层组成：
- 模板母版底座：画布、主题、字体、页脚及框架页。必须遵守。
- Agent 自主设计的内容区：按内容关系、叙事目的和证据形态自由构图。
- 参考与组件工具箱：帮助判断或加速实现，但不规定页面必须长什么样。
始终遵循：
slide = template shell + agent-designed content + optional references/components
不要把内容组件配方误认为模板。模板的空白内容区有意保持自由。但标准内容页的底部框架固定：一条主题色一句话总结条、左下页码（密级文字可选）。图文分栏、卡片和系统图等内容结构仍不强制。
新建 deck 默认走 template-master：先在 10×5.625 兼容坐标中创作可编辑内容，再用 scripts/finalize_deck.py 一条命令合并进模板（内部完成解包、等比放大、挂 slideLayout7.xml、清理与打包，无需手工操作拆包目录）。页脚和页码由母版继承，生成代码不得再画第二份；只有明确的兼容场景才使用独立 10×5.625 文件。
开始前必须读取
根据任务读取以下文件：
只在确定要使用某类组件后读取 components/index.md 和对应实现说明。先完成页面设计判断，再选择工具。
不可违反的边界
品牌与模板
- 以 references/template.pptx 为模板事实来源。它是中性白板模板，由
scripts/make_blank_template.py 生成。
- 保持主题色、字体层级、页脚和页码语义。
- 每张标准内容页必须且只能出现一次固定底部框架：主题色一句话总结条与左下页码。模板不含 Logo，不得自行添加。
- 封面主标题必须是主题色
#4472C4 且保持单行。自绘或复刻封面时同样适用，不得退回模板占位符的深色默认值。
- 封面、目录、空白内容页、结束页应继承模板语言；若用户提供自己的模板，以用户模板为准。
template-master 输出必须保留模板自身的 Master / Layout 数量；finalize_deck.py 以模板为基线校验，丢失即判失败。
内容与证据
- 不得编造事实、数据、引用、产品能力或论文结论。
- 数字、图表和外部判断要能回溯到用户材料或可靠来源。
- 论文原图保持原意和比例；不得为了统一风格篡改图内颜色或内容。
- 网络素材要记录来源和使用权；无法确认时使用占位或自绘，不假装已验证。
- "可回溯"指记录在
evidence-plan.json 和交付时的来源说明里，不指在幻灯片上画来源行。 默认不在页面上放来源文字（论文原图页同样如此），只有用户明确要求时才画。
工程质量
- 输出必须可打开、可编辑、无重叠、无越界、无截断、无拉伸图片和占位残留。
- 文字必须可读；不得用极小字号解决内容过载。
- 原生 PptxGenJS 形状、图表和表格优先保持可编辑性。
明确不是硬规则的事项
以下都由内容决定，不得写成 deck 级默认门禁：
- 默认左图右文或固定 60/40 比例；
- 每页至少两个区域；
- 所有内容页套用同一种固定版式；
- 所有结构内容必须使用
addSystemDiagram；
- 默认至少 10 页；
- 固定组件使用比例或组件调用次数；
- 固定字数、卡片数量或系统图节点数量；
- 一律禁止或一律要求分节页。
新建 deck 的主流程
1. 理解内容
优先读取用户材料。只有用户没有提供足够事实且任务允许外部调研时才联网补充。
明确：
- 目标受众；
- 使用场景；
- 核心结论；
- 交付用途：阅读型、平衡型或演讲型；
- 是否需要严格沿用用户结构；
- 页数或时长约束。
2. Strategist：先设计叙事，再设计页面
选择一个主叙事模式：
executive-report：结论先行，证据与建议支撑；technical-explainer：概念拆解、机制、边界与实现；research-review：问题、方法、证据、局限与启示；showcase：一页一个重点，视觉主导；briefing：中性、完整、便于扫描。
用户给定的页面顺序和标题优先。模式是组织建议，不得覆盖用户明确结构。
为每页规划：
page: P03
role: content
title: 页面标题
core_message: 本页唯一必须记住的结论
summary: 放入固定红色总结条的一句话结论
rhythm: anchor | navigation | dense
content_blocks:
- 完整事实或论证块
visual_strategy:
primary: template | user-material | paper | web | native-drawing | component | svg | hybrid | none
reason: 为什么这种表达最适合本页
fallback: 首选失败后的替代路径
component_policy: optional | preferred | avoid
layout: 从 references/index.yaml 选定的骨架 name
layout_id: 该骨架的 id
layout_ref: <skill>/references/<id>.<ext>
rhythm 只控制页面节奏，不绑定版式：
anchor：封面、转折、重大结论或核心视觉；navigation：目录、路线或结构导航；dense：数据、架构、对比、研究证据。
3. 生成设计契约
在工作目录保存：
design-spec.md：受众、叙事、页面计划、设计理由和素材计划；每 deck 恰好标记 1-2 页 Hero: yes，选最核心的论证页；evidence-plan.json：逐项记录图片/图表/截图要证明什么、怎样获取、审核状态和回退；execution-lock.json：机器可校验的执行契约，记录模板、品牌固定层、逐页节奏/视觉策略，并通过 asset_ids 只允许使用 evidence plan 中的证据。
从 base/execution-lock-reference.json 开始，并使用 base/execution-lock.schema.json。不要锁定单页坐标、固定布局比例或强制组件名；component_policy 只表达组件是否适合，不指定必须调用哪个函数。
从 base/evidence-plan.json 和对应 schema 开始。写完后立即运行：
node scripts/validate-evidence-plan.js <project>/evidence-plan.json --phase design
node scripts/validate-execution-lock.js <project>/execution-lock.json --phase design
校验未通过时不得开始页面生成。不要把 JSON 改写成 YAML 或 Markdown。
4. 获取视觉素材
按 workflows/acquire-visuals.md 逐项处理 evidence plan。优先级不是固定排名，而是证据价值、真实性、可编辑性和表达效率的综合判断。
论文 paper-figure 路线必须复用 scripts/extract_arxiv_visuals_v2_2.py：准备脚本会读取其 manifest，按 Figure/Table 标签和 Caption 关键词选择；选择不唯一时查看论文 contact sheet 后再批准。不得重新实现一套论文裁图器。
素材状态只使用 planned / acquiring / ready / used / needs-manual / skipped。运行 prepare_evidence.py 后必须查看 analysis/evidence-contact-sheet.jpg 或论文专属 contact sheet，再用 --approve <id> 将项目置为 ready。素材实际进入 PPT 后用 --used <id> 记录使用状态。视觉方案发生变化时同步修改 design-spec.md、evidence-plan.json 与 execution-lock.json，不允许资源仍标记为 planned 而页面静默改走其他路径。
5. Executor：在空白内容母版内逐页生成
- 先实现模板外壳，再设计内容区。
- 标准内容页完成内容后，调用
Brand.addContentChrome(...) 一次性添加固定总结条与页脚；内容必须结束在总结条上方。
- 逐页顺序生成，保持同一主 Agent 的上下文和跨页一致性。
- 每页先读取
execution-lock.json 中对应的 core_message、rhythm、visual_strategy、component_policy、素材状态和候选参考，再决定构图。
- 写每页代码前，先打开该页
Layout ref 指向的参考图，并对照 references/index.yaml 中该骨架的 skeleton 与 rules，理解它的分区、比例和填满方式。只看骨架名不看图，等于没有版面信息。参考图用来建立版面直觉，不要求逐像素复刻。
- 骨架给出分区、比例和区域数量的参考方案；
composition 决定这一页实际怎么摆。两者冲突时以 composition 为准——它更贴近本页内容；但要同步更新 design-spec.md 里的骨架选择，别让声明的 layout id 和实际产出长期不符。
- 每页只允许引用
evidence_visual.asset_ids 列出的证据；AI 插画只能作为 hero/support/background/inline，不能声明为事实 evidence。
composition 必须明确主视觉、次证据和阅读顺序；evidence_visual 必须说明真实截图/论文图/数据图/原生关系图承担什么作用。密集或锚点内容页若不使用参考图，必须写具体 waiver，不能让整套 reference_ids 默认为空。- 可以使用裸 PptxGenJS、自定义 SVG、原生图表/表格、可选组件或图片组合。
- 不使用预制小图标库；卡片/列表的识别锚点用
initial 首字母徽标或自绘 SVG，不引入装饰性图标。
- 组件与内容不匹配时立即放弃组件，自己绘制。
- 每个卡片、区域、节点里写完整陈述句，不是术语加半行注释。 单词式短语只当表头或标签用，正文要把机制/条件/量级/边界说透——一张卡两三行、一节两三句。参照量级：标准内容页视觉字量 400-700（真实内部 deck 的密度锚点），容器画得足却只填几个词，交付前
qa_density.py 会判 EMPTY 硬错误。宁可少放一个空盒子，也不要让盒子半空。内容量达标后若版面仍显空，再靠放大字号/行距（多数组件已内置稀疏时自动放大）、拉开区域间距或补小图铺满——但先过字量，别用大字号给稀薄内容撑门面。
推荐先生成封面和一张最具代表性的复杂内容页，合并到官方模板并渲染验证后再继续整套 deck，避免系统性错误复制到所有页面。通过目录、章节和锚点结论改变阅读节奏，而不是机械插空页。
生成前运行 --phase generate；交付前运行 --phase deliver。必要素材未就绪时可以按设计稿中的 fallback 更新方案，但必须同步契约后重新校验。
6. Hero 页精修
全 deck 构建通过、几何硬错误清零后，对 design-spec 中标记 Hero: yes 的 1-2 页按 workflows/create-deck.md 第 8 步做单页升格精修：打开该页渲染图与 references/complex-slide.jpg 及骨架参考图并排对比，列出差距后重构主区域，至多迭代两轮；改动同步回 design-spec.md 的该页 Composition。精修只动 hero 页，不回头重排其他页面。
7. QA 与交付
按 base/quality-gates.md 区分硬错误和软建议。硬错误必须清零；软建议由 Agent 结合设计意图判断，不得自动把页面改回固定组件配方。
交付前必须运行 python3 scripts/qa_geometry.py <output.pptx> 并清零全部 error。它机械判定重叠、遮挡、重复底部框架和越界——这些缺陷普遍在 0.1 英寸量级，在缩略图总览上根本看不见，只靠人眼 QA 会反复漏掉。
版式库使用方式
references/index.yaml 是版面骨架库，每一项是一种可复用的版面骨架。它是选型参考，不是强制模板：用它避免从零构图和自创劣质版面，但页面最终长什么样由内容决定。
建议动作：
- 通读全部
name，先建立"有哪些骨架可选"的认识。整份文件一次读完，不要只挑几项看。
- 阅读
common_rules，它对所有版式生效。
- 按内容形态为每页选一个骨架，在
design-spec.md 中同时记录 name、id 和 image 的完整路径。只记名字不记路径，Executor 阶段就拿不到版面信息。
- 打开该项的
image 确认细节，再对照 skeleton 和 rules 理解它的分区与比例意图。
- 内容与骨架不完全吻合时，先看
variants 有没有现成变化；仍不吻合就换骨架，或在 composition 里写出自己的分区。
骨架按每页的内容形态选。内容形态不同，自然会落到不同骨架上；如果整份 deck 都用同一个骨架，通常说明这一步被省略了，回头确认各页的内容形态是否真的相同。不要因为某个骨架先跑通就把它套到所有页面。相邻内容页连用「同一骨架 + 同一右栏文本样式」是同类信号——连续三四页都是左边一个视觉区、右边一列 1/2/3 编号条目，阅读节奏就塌了；用骨架 variants、错开右栏样式（numbered/sectioned）或换骨架打破重复。论文图、实验数据这类证据页优先评估 architecture-evidence（外框内左文右图）：论证分节、原图与数据解读、红色结论句在同一个外框里对齐，比「左图 + 右列表」更有表达力。
版式库提供的是：版面分区、区域比例、对齐方式和填满策略的参考方案。
版式库不规定：坐标、颜色、区域数量、条目数量和具体内容——这些由 avoid_when 之外的内容需求决定。
松紧边界：骨架是软的，可以偏离且不需要写 waiver；common_rules、品牌固定层和工程质量要求是硬的——撑满内容区、对齐轴线、不侵入页脚、不重叠、不越界、不截断，无论选哪个骨架都必须满足。产出好不好看以页面本身判断，不以是否忠实复刻骨架判断。
组件使用原则
组件是可选工具。选择顺序：
- 判断内容关系和证据形态；
- 决定页面视觉策略；
- 查看是否存在高度匹配的组件；
- 匹配则使用或改造，不匹配则裸绘。
品牌框架组件与内容组件分开导入：
const Brand = require("./components/brand.js");
const Charts = require("./components/charts.js");
const Diagrams = require("./components/diagrams.js");
const Content = require("./components/content.js");
原有 scripts/components.js 仍保持兼容，可继续整体导入。
编辑既有 PPTX
若用户要求编辑已有 .pptx，以现有文件的 Master、Layout、主题和内容为事实来源，走 workflows/edit-existing.md。不要为了套用新建 deck 的组件系统而破坏原有模板结构。
输出要求
最终至少交付：
.pptx 文件；- QA 模式和结果；
- 使用外部素材时的来源说明；
- 未能获取的素材、占位或已采用的回退方案。
