ultimate-ppt-master

Name: ultimate-ppt-master
Author: kdnsna

github.com/kdnsna文档处理299 次安装12 周前更新

代码仓库

关于 ultimate-ppt-master

Ultimate PPT Master 是用于编辑现有 PowerPoint 并保留未修改内容的技能，也支持根据资料生成可编辑演示文稿。它通过定向修复、渲染和质量检查辅助审阅与交付。

主要功能

01定向编辑并保留未修改幻灯片
02编辑文本、样式、表格、形状和图表
03生成可编辑 PPTX 或 Web Deck
04规划故事板和视觉方向
05渲染并审计演示文稿质量

适用场景

01修正 PPTX 中指定的文本或对象
02根据资料制作可编辑演示文稿
03交付前进行幻灯片视觉审阅

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/kdnsna/ultimate-ppt-master-skill --skill ultimate-ppt-master

安装后在 Claude Code 中输入/ultimate-ppt-master确认已加载。

详细介绍

保真改 PPT Skill (Ultimate PPT Master)

能力等级（v7.0.0-beta.1）： 保留并编辑 = RC；通过 upm make 生成可编辑演示文稿 = Beta（可编辑的 DrawingML 形状，不是原生 a:tbl / 图表数据对象）；upm make --format web-deck = 实验性 SVG HTML 预览（非杂志风格 GA）；Kimi 导出 = 实验性 / 非正式。自动修复 = 有限的溢出字体缩小 + 修复计划，不是完整的两轮执行器。正式模式会拒绝占位符 / 无来源的交付。优先使用 bin/upm 质量门禁；CLI 退出码为 0 表示必需门禁均已通过。

以保真为先编辑 PowerPoint：只修改用户指定的幻灯片 / 对象，其他内容逐字节保持不变，并交付可在 WPS / PowerPoint 中正常打开的可编辑 .pptx。仍支持根据源材料生成新的可编辑 PPTX 或杂志风格网页演示文稿，但这属于次要功能——不要把修改 / 修复请求变成从头重新生成。

主要模式 — 保留并编辑现有 PPTX：读取修复计划 → 仅修改指定的幻灯片 / 对象 → 渲染修改前后版本 → 写回可编辑 .pptx + 安全报告（见下方的 现有 PPTX 修复模式）。

次要模式 — 根据源材料生成：输入 → 故事板 → 设计与生成 → 优化与交付。

步骤 0 — 环境检查（运行脚本前执行）

运行任何脚本前，先检查一次运行环境（速度快；保留并编辑模式仅依赖 Python 标准库，生成路线需要更多依赖）：

python3 --version        # needs 3.10+; picks python3.13/3.12/3.11/3.10/python3 on PATH

如果 ${SKILL_DIR}/.venv 存在，优先使用 ${SKILL_DIR}/.venv/bin/python 执行所有操作。
如果不存在，请安装一次轻量级 Python 依赖：
```
bash ${SKILL_DIR}/scripts/bootstrap.sh --profile core
```
（--profile core 只安装 requirements-core.txt——不包含 Chromium，也不包含 npm。如果任务需要转换源文件、生成图像或使用 Playwright 渲染，请使用 --profile all 或 visual-review。）
如果脚本运行时出现 ModuleNotFoundError，缺少的包是该路线的可选依赖——通过 pip install <package> 在 ${SKILL_DIR}/.venv 中安装（查看 requirements.txt 的章节标题，确认该依赖所属路线），不要静默跳过此步骤。

工作模式

将此 Skill 视为围绕 PowerPoint 的本地质量与工作流层，而不是 PowerPoint 原生编辑器的替代品。默认面向用户的流程如下：

输入 — 接收一行任务描述、文件、URL 或现有 PPTX；推断技术设置，而不是一开始就让用户选择。
故事板 — 最多提出三个关键问题，然后展示幻灯片任务、证据关联和明确的缺口。
设计与生成 — 提供三个完整的视觉方向，涵盖封面 / 正文 / 数据的呈现方式；先创建确定性的结构草稿，再仅优化选定的幻灯片或审查失败的幻灯片。
优化与交付 — 按稳定的 slideId 进行处理；保留可编辑的 PowerPoint 对象，并在 PowerPoint 中完成正式编辑。

专业 / 诊断模式仍可使用 Bridge、providers、DeckIR、脚本和 JSON 契约。保留 project-brief.json、storyboard.json、asset_plan.json、quality-report.json 以及现有的 Bridge 交接兼容性。存在 DeckSession 时，在每个产物中保留其阶段（intake / outline / generating / review / delivered）和稳定的 slideId 值。

如果提供现有 PPTX 作为视觉或品牌参考，请运行：

python3 ${SKILL_DIR}/scripts/pptx_template_import.py <reference.pptx> --manifest-only --reference-style-mode style-only

使用生成的 reference-style.json 复用母版 / 布局节奏、主题字体和颜色、占位符、图表样式和常见页面角色，但不要复制私密内容。

现有 PPTX 修复模式

当交接内容包含 attachments/pptlint-repair-plan.json 时，应将源 PPTX 视为需要修复的交付成果，而不只是新建演示文稿的素材：

采用快速、优先手动的修复路径；跳过故事板生成、视觉方向探索、图片获取、元素工具包生成，以及不会直接修改指定对象的完整演示文稿制作步骤；
规划前先阅读选定的修复任务，且只操作其中指定的幻灯片；
除非用户明确解除限制，否则保留所有可见字符、数字、数据、结论、幻灯片数量、幻灯片顺序，以及未选中的幻灯片，不作任何更改；
对于局部修复，绝不能通过 Artifact Tool、SVG 或其他重建流程导入并重新导出整个源演示文稿；这些方式可能会重新解释母版、透明度、占位符、组合对象、链接和未修改的幻灯片；
使用保留原生格式和文件包结构的对象编辑路径——编辑器 scripts/preserve_edit_pptx.py。它会逐字节复制所有文件包部件，仅重新序列化指定的幻灯片（以及该幻灯片的图表操作所触及的任何图表部件），因此未触及的幻灯片、徽标、母版、版式、主题、媒体和链接都能保持逐字节不变。先检查，再编辑：
```
python3 ${SKILL_DIR}/scripts/preserve_edit_pptx.py --list <source.pptx>
python3 ${SKILL_DIR}/scripts/preserve_edit_pptx.py <source.pptx> <repaired.pptx> \
    --slide <N> --replace "旧文本=新文本" --report <fidelity-report.json>
```
支持的原生操作（优先使用这些操作，而非重新生成整个演示文稿）：
- 文本：--replace OLD=NEW 或操作 replace_text
- 样式：操作 style_text——字体 / 大小 / 粗体 / 颜色（可选匹配条件）
- 表格：操作 replace_table_cell——按行 / 列或查找文本定位
- 形状：操作 set_shape_geometry——按点移动 / 调整大小（按索引 / 名称 / 文本匹配）
- 图表：操作 replace_chart_text、set_chart_value（仅重写关联的图表部件）一次执行多张幻灯片 / 混合操作：
```
python3 ${SKILL_DIR}/scripts/preserve_edit_pptx.py <source.pptx> <repaired.pptx> \
    --edits edits.json --report <fidelity-report.json>
# edits.json: [{"slide":1,"replacements":{"Q2":"Q3"}},{"slide":4,"operations":[{"op":"replace_table_cell","row":2,"col":1,"text":"128"}]}]
```
也可以在单张幻灯片上执行一个类型化操作：--op '{"op":"style_text","size":24,"bold":true}'。未匹配到内容时，即使指定的幻灯片也会保持逐字节不变。
保真度报告是硬性门槛：safe 必须为 true——只能更改预期的幻灯片 / 图表部件，且不得添加或移除任何部件。任何意外更改、添加或移除的部件都属于严重失败——停止并报告，不要交付；
对于编辑器目前尚不支持的更改——添加 / 移除幻灯片、插入新图片、重建表格结构或自由形式重新设计——不要对整个演示文稿进行往返处理；应仅返回针对这些对象的简短 PowerPoint/WPS 操作步骤；
如果当前环境无法使用编辑器，不要生成修复后的 PPTX；应立即返回简短的 PowerPoint/WPS 操作步骤，而不是启动常规演示文稿制作流程；
如果无法在不违反限制的前提下改进某个选定的问题，应保留原页面，并报告用户必须作出的具体决定；
实际完成原生编辑后，应通过 PowerPoint、WPS 或 LibreOffice 渲染修改后的幻灯片，并以完整尺寸检查修改前后的效果；可见对象缺失、背景变黑 / 改变、徽标损坏、链接改变或发生意外移动，都属于严重失败；
将修复后的 PPTX 另存为独立文件，运行 pptlint proof，仅将其评分 / 规则结果作为辅助证据。未经渲染后的视觉检查，不得仅凭文本 / 规则检查宣称成功或授予 Verified 凭证。

此模式是一条针对性修订路径。不得暗中将修复请求变成新故事板、改变叙事、重新生成未受影响的页面，也不得为小型局部修复耗费完整生成所需的时间。

质量流程附加要求：面向利益相关者的演示文稿还必须通过 Visual Direction → Page Role Contract → Visual Completion Audit。

最佳效果简报增强器

生成式工作流政策

本节根据 contracts/ 生成。请勿手动编辑；运行 python3 scripts/generate_contracts.py。

信息来源

主要工作流：SKILL.md
设计约定：DESIGN.md
机器策略：contracts/workflow-policy.yaml、contracts/route-policy.yaml、contracts/visual-defaults.yaml、contracts/quality-modes/

最佳效果简报增强器

在选择路线或生成文件之前，将用户的简短指令改写为 bestEffectBrief。记录提示词质量、自动扩展的受众／场景／核心信息／页数／风格／来源／素材假设、推荐路线，以及哪些决定来自用户、哪些来自 Agent。

路由

按策略自动选择路线。如果请求可分类，不要在生成前强迫用户在 PPTX 和 Web 之间做选择。
最多提出 3 个有针对性的问题，并且仅当事实、来源、品牌／IP、合规要求或路线选择会实质性影响交付内容时才提问。
编辑现有 PPTX（改PPT / 保真修改 / edit this pptx）→ preserve-edit（保真编辑引擎）。
正式／可编辑／政府／金融／培训／报告／.pptx 信号 → editable-deck，质量模式为 standard。
HTML / Web PPT / 杂志 / 编辑风格 / 电子墨水屏 / 瑞士风格 / 横向滑动 / keynote / 展示 / 演示日 / 浏览器优先信号 → web-deck（仅在用户明确要求时启用）。
只有主题、信息极少且没有正式／Web 信号的提示词，使用 editable-deck 回退方案 → Editable Deck，风格为 正式商务 PPTX / 微软雅黑 / 可编辑正文，共 6 页，封面底色为 light-or-warm-paper。

信息极少的提示词回退方案：页面节奏

浅色或暖纸色封面，包含一个醒目的标题、精简的副标题，以及一个边缘柔和的视觉／证据面板
背景页：介绍问题、趋势或情境
证据／数据页：陈述须以来源为依据
对比或流程页
风险或行动页
浅色收尾页：总结要点并提出下一步

视觉默认值

默认封面底色：light-or-warm-paper（浅色／暖纸色／近白色）。
仅在以下情况允许使用深色封面：用户要求、品牌系统、明确的艺术指导、以图像为主的发布。
除非用户、品牌或明确的艺术指导有此要求，否则不要使用整页黑色封面。
墨色主要用作文字颜色，而非默认的整页背景色。

来源导入

默认导入模式：copy（--copy）。
--move / 归档并移除原件属于明确指定的高级选项，不是默认选项。
仓库内部生成的研究资料仍可移动，以避免意外提交。

证据状态

允许的值：unmapped、candidate、grounded、conflicted、missing。
仅因存在来源而创建的草稿幻灯片必须从 unmapped 开始，绝不能标记为 grounded。
grounded 要求来源与具体主张绑定。

质量模式

默认模式：standard。
可用模式：quick、standard、audit。

模式	用途	关键门槛
quick	草稿、内部讨论、内容验证	结构／文件有效性失败；视觉证据警告
standard	大多数正式报告，默认制作路径	正式交付失败；建议提供视觉证据
audit	董事会材料、政府、金融合规、对外发布	缺少预览 PNG／设计报告／空白页风险即失败

语义断言：

defaultCoverSurface=light
extremeThinAutoRoutes=True
extremeThinDefaultFormat=editable-deck
formalSignalDefaultFormat=editable-pptx
mustAskBeforeGenerate=False

在选择路线或开始制作之前，将用户的原始请求转换为 bestEffectBrief。直接使用 Agent 时必须执行此步骤，因为许多用户只会写一个简短主题或“帮我做个 PPT”。

bestEffectBrief 必须记录：

用户原始请求摘要；
提示词质量：complete、thin 或 extreme-thin；
自动扩展后的简报：受众、场景、核心信息、页数、叙事脉络、输出路线、风格方向、来源边界、素材／IP 政策和假设；
推荐路线：guizang-web-fixed-style、formal-editable-pptx 或 dual-delivery；
固定回退决策及其选择原因；
哪些内容来自用户，哪些是 Agent 推断的。

路由决策顺序

在默认交付路由之前，按以下确定性顺序进行判断。第一个匹配项优先；正式/可编辑关键词的优先级高于提示词信息不足。

顺序	决策键	触发条件	结果
1	`explicit-formal-signal`	`pptx`、`.pptx`、`PowerPoint`、可编辑、汇报、报告、政府、金融、培训、审计、咨询/商业报告，或经利益相关方修订的文件	`formal-editable-pptx`
2	`explicit-web-signal`	杂志风、网页PPT、HTML、横滑、Swiss/瑞士风、编辑风/电子墨水风、浏览器优先、主题演讲/展示/演示日	`magazine-web-deck`
3	`extreme-thin-fallback`	只有主题，或 <=25 个字符/单词，且没有受众、场景、来源、页数、风格或核心信息信号	`guizang-web-fixed-style`
4	`thin-guided-intake`	有主题，且至少有一个上述信号，但缺少来源或核心内容	分阶段提问
5	`complete-source-first`	来源和制作背景充足	继续优先处理来源

如有疑问，请运行有测试样例支持的分类器：

python3 ${SKILL_DIR}/scripts/best_effect_router.py "<raw user request>"

极简提示词回退方案

如果用户只提供一个主题、一句话请求，或几乎没有源材料，不要先要求用户写出完美提示词。除非用户明确要求正式/可编辑/政府/金融/培训类 PPTX，否则使用以下稳定默认方案：

路由：Guizang-like Magazine Web Deck fixed style；
模式：Mode 2: Magazine Web Deck；
风格：Style A · 电子杂志 × 电子墨水；
长度：8 页，除非用户指定其他页数；
页面节奏：
1. 浅色或暖纸色封面，搭配一个醒目的标题、简短副标题和一个边缘柔和的视觉/证据面板；
2. 浅色背景页面，用于呈现问题、趋势或背景；
3. 图片/文字页面或克制的信息页面，用于呈现张力或机遇；
4. 浅色结构页面，呈现三部分框架、路径或方法；
5. 大字陈述式章节分隔页；
6. 证据/场景/案例页面；
7. 观点页面，呈现最终判断或问题；仅当用户、参考资料或所选方向有此要求时才使用深色；
8. 浅色收尾页，呈现行动、要点或结束语。

此回退方案是“稳定的高质量输出”路径。只有当缺失的事实、品牌/IP 许可、合规边界或来源权威性会实质性影响演示文稿时，Agent 才可以提出一个有针对性的问题。普通的风格信息缺失由固定风格补足。

如果用户明确要求正式可编辑的演示文稿、政府/金融/培训/报告材料或 .pptx，则切换到 formal-editable-pptx：创建一份 8-12 页的可编辑 PPTX 简报，使用 Microsoft YaHei，封面默认采用浅色/近白色，包含一个大型边缘柔和的主视觉面板、正式商务质量门槛、来源可信度、官方/IP 资源方案，以及相同的 bestEffectBrief 记录。除非用户或品牌方向明确要求，否则不要使用整页黑色封面。

简报清晰度关卡

开始制作前，判断请求是通过视觉网页简报提交的，还是通过 Codex 直接对话提交的：

Web Visual Brief Builder：读取 project-brief.json.visualBrief、guidedBrief 和 expectationFit。Web 标签代表用户意图，并非装饰。粘贴的背景信息和特殊要求与标签默认值冲突时，以前者为准。
Codex Guided Intake：如果 Codex 直接请求没有提供足够细节，不要直接开始制作最终质量的 PPT。应逐步提问，直到明确制作框架。
以源文件为先：如果已提供可靠的源文件和目标背景，记录假设并继续。
基于假设起草：仅当用户明确要求草稿、初稿或“先按默认做一版”时使用。

对于直接使用 Agent 的情况，在引导式信息收集前运行 Best-Effect Brief Enhancer。只有当 bestEffectBrief 无法安全推断制作路径时，才分阶段提问。

引导式信息收集可以检查以下事项，但在展示分镜之前，面向用户的问题不得超过三个。推断风险较低的技术选择，并将剩余细节作为可编辑假设列出：

使用场景和目标受众；
希望受众采取的行动或做出的决定；
源材料和权威内容边界；
核心信息和必须包含的要点；
页数、章节结构和演讲者备注需求；
视觉风格和信息密度；
品牌、官方／IP 素材、是否允许使用 AI 生成图像，以及必须避免的内容；
输出格式，默认为可编辑 PPTX。

用户回答后，撰写简洁的确认简报。仅当 expectationFit.readyForProduction = true，或用户明确接受附带已记录假设的草稿时，才继续制作。

默认交付路径

此技能针对实际办公 PPT 交付进行了优化。路径选择应保持简单：

对于内容不为空且具备足够正式背景的一般商务请求，默认选择 Mode 1：可编辑 PPTX，并在完成 bestEffectBrief 后继续。
对于“做一个关于 AI 的 PPT”“帮我做 PPT”“make a deck”这类极度简略的请求，或只有主题、没有正式／可编辑倾向的请求，默认使用 Mode 2：杂志风网页演示文稿，并采用归藏风格杂志网页演示文稿固定样式。
当用户要求 PowerPoint、.pptx、可编辑文件、商业报告、咨询演示文稿、培训材料、政府／金融材料，或其他人可能需要修改的内容时，选择 Mode 1：可编辑 PPTX。
当用户明确要求杂志风格、网页 PPT、HTML 幻灯片、横向滑动演示文稿、编辑／电子墨水风格、瑞士风格、主题演讲／展示／演示日风格、优先通过浏览器交付，或触发极简提示词回退时，选择 Mode 2：杂志风网页演示文稿。
如果用户两种都要，则在不同项目文件夹中分别交付。
只有当请求的路径确实模棱两可，且无法根据场景判断时，才请用户选择。提出一个简洁问题，然后继续。

一般请求的通俗说法：

我会先将你的简短指令自动扩写为最佳效果简报；如果只有主题／一句话，且没有明确要求正式、可编辑的 PPTX，我会默认采用归藏风格杂志网页 PPT，先做一版稳定的高质量版本。如果你需要正式汇报或可编辑文件，我会改用 PPTX。

正式商务交付关卡

先选择质量模式：草稿使用 quick，大多数正式报告使用 standard（默认），董事会／政府／金融／对外发布材料使用 audit／formal-audit。对于商业、报告、咨询、培训、政府、金融类演示文稿，以及预期要交付给真实利益相关方的任何内容，默认将 qualityGate.level = "formal-business"。除非用户明确要求快速草稿，否则此项为默认质量标准。在生成最终 PPTX 或 Web Deck 文件之前，请在 design_spec.md、spec_lock.md 和 design-quality-report.md 中锁定以下事项：

从 templates/visual-directions/ 中选择视觉方向；若没有合适的方向，则记录有据可查的 custom 基准。
页面角色与页面方案约定：在 design_spec.md / spec_lock.md 中，每页都必须包含 page_role、visual_weight、layout_family、page_recipe_id、asset_requirement、visual_layer、raster_policy 和 anti_patterns。
品牌素材或有据可查的备用方案。
官方/IP 素材计划，涵盖来源或用户提及的确定性标识，例如公司 Logo、活动 Logo、旅游 IP、产品标识、二维码、印章和合作伙伴标识。优先搜索官方或授权来源；绝不可绘制仿造 Logo 的占位图。
可追溯的证据来源和数据解读边界。
默认使用 Codex 原生 GPT 图像生成（如可用，则使用 image2）作为自定义视觉素材引擎；这是“以 ChatGPT/OpenAI 作为主要视觉素材引擎”的 Codex 执行路径。在 asset-plan.md 或 images/image_prompts.md 中记录提示词、文件名、目标幻灯片和手动编辑内容。
适用时制定可复用的小型元素素材计划：章节分隔符、指标徽章、流程节点、连接线、图标点缀、纹理和标注贴纸。
记录通过 scripts/generate_visual_element_kit.py 生成的本地元素状态：assets/generated/element-manifest.json、images/image_prompts.json 和 images/image_prompts.md。
制定用于查找证据、官方参考资料和品牌边界的公开素材搜索计划，或明确说明不搜索的理由；对每项选用的公开素材，记录来源 URL、发布方、许可/使用说明和插入位置。
在 spec_lock.md brand_assets 和 asset-plan.md / images/image_sources.json 中，为演示文稿里出现的每个确定性 IP 标识添加条目。每个条目都必须记录 official-source、user-provided、text-lockup-fallback 或 needs-authorized-replacement。
制定图像、图表和信息图计划，或明确采用无图策略。
规划页面节奏、布局多样性和每张幻灯片的作用。
在 spec_lock.md aesthetic_checks 中涵盖正文基准字号、标题/正文比例、卡片数量、卡片内边距、留白目标、Logo 处理方式和重复布局风险。
采用 4.0 混合可编辑视觉策略：生成的视觉素材作为无文字图层辅助页面；正式的正文页面仍保持可编辑。
记录视觉完成状态：已渲染截图/PNG、已检查重复布局风险、占位素材已标注，并已撰写设计质量报告。
检查产物，确保 PPTX 对象可编辑，且 Web Deck 的视觉内容已完整渲染。正式交付规则：
不要用重复的标题页加卡片页拼成整套演示文稿。
除非《设计规范》中记录了明确理由，否则不要让连续三张内容页采用相同的版式系列。
除非《设计规范》中记录了明确理由，否则不要让连续三张内容页采用相同的页面方案。
正式 PPTX 正文页不得使用整页生成图。整页栅格图仅可用于封面、章节页／尾页、海报／KV 页、Web 展示页，或用户明确同意并记录在 raster_policy 中的情况。
除非明确将演示文稿标记为草稿，且用户接受此限制，否则不要只用幻灯片标题继续制作。
如果视觉方向包与演示文稿的语境相符，不要采用泛泛的“自由设计”风格。先选择方向包，再进行调整。
当视觉素材能改善演示文稿时，优先使用 Codex 原生 GPT 图像生成功能（可用时使用 image2）作为视觉素材引擎。在最终组装幻灯片前，生成构图完整的辅助视觉素材和可重复使用的小型素材。
不要依赖随意的图库图片或单纯堆叠元素。每个 AI 视觉素材都必须承担场景构图职责：背景氛围、证据插图、流程点缀、概念隐喻、产品／语境场景，或无文字视觉层。
适用时，生成并复用一套风格统一的元素素材包：小型章节分隔符、指标徽章、流程节点、连接线、图标点缀、细腻图案和标注贴纸。
对含有重复微型素材的正式演示文稿，在最终组装幻灯片前运行 python3 scripts/generate_visual_element_kit.py <project_path>。如果没有图像后端／密钥，且没有主机原生图像工具，则使用 images/image_prompts.md 中的 Needs-Manual 提示词继续；不要因此阻塞整个演示文稿。
公开／官方／可复用素材搜索应主要用于事实证据、官方参考和品牌边界；插入素材前记录来源和使用边界。
对源文中的固定 IP 名称，生成素材前先搜索官方来源。例如：交通银行、好客山东、文旅大戏、产品／卡片名称、合作机构、城市／旅游品牌、应用／小程序标识、活动标识。优先选择官方网站、新闻稿、媒体资料包、政府／公共服务门户或用户提供的文件。第三方 Logo 下载网站只能作为搜索线索，不能作为最终来源证据。
确定性 IP 素材不是装饰性图标。若已从官方渠道获取或由用户提供，应插入真实素材；否则使用简洁的文字组合，并附上醒目／有记录的替代说明。不要创作伪造标志、通用徽章或“看起来相似”的标识。
将 Codex／GPT／OpenAI 生成的素材存放在 assets/generated/ 或项目图片文件夹中，并作为真实素材插入。
私有源材料、内部截图、客户数据和 API 密钥均须保留在本地，除非用户明确批准上传。
PPTX 输出必须使用可编辑的文本、形状、图表、图片和备注；不要将幻灯片扁平化为整页截图。
Logo 和品牌标识必须使用真实素材、规范的矢量处理，或有记录的文字替代方案；Logo 不得退化成 b／c 之类的文字碎片。
不得用随意的形状、首字母、图标徽章或生成的近似图替换已知 Logo 和活动 IP 标识。如果无法安全获取官方素材，则在 design-quality-report.md 中阻止对外发布，并记录 needs-authorized-replacement。
对于 Web 演示文稿，验证桌面端／移动端视觉完整性、媒体渲染效果和版式多样性。
Design Doctor 默认只生成报告。除非用户明确要求自动修复，否则不要自动修复 SVG。

交付设计默认值

除非用户、品牌指南或所选模板明确覆盖这些默认值，否则请使用以下默认值：

字体系列：默认的 CJK 和正文字体为 "Microsoft YaHei"（微软雅黑），仅将 "PingFang SC" 用作预览备用字体，并将 Arial 用作拉丁文字备用字体。这样可让 PowerPoint 交接更实用，并避免网页字体的版权或安装风险。
标题与正文的关系：大多数正式演示文稿都统一使用 Microsoft YaHei，通过字重对比而非增加字体来形成层次。只有当演示文稿需要编辑风、学术风或主题演讲风格，且字体已预装或有明确说明时，才使用衬线字体或展示字体形成对比。
主题艺术指导：阅读源内容并选定视觉方向后，在生成前先提出一个契合主题的艺术概念。概念应足够具体，能够指导封面、尾页以及可选的全篇重复元素。例如，文旅主题的演示文稿可以采用 山海交汇烟火同行，并融入海岸线、山峦剪影、旅行印章的节奏、温暖的市集灯光，以及克制的银行品牌结构。如果源内容主题更丰富，就不要让整份演示文稿停留在“商务蓝”。
艺术化标题设计：除非演示文稿属于工作报告、严肃的政府／金融合规文件，或其他不适合表现性标题的场景，否则主标题应通过定制构图体现主题艺术指导：层叠文字组合、以形状绘制的书法感笔触、图像蒙版点缀、大面积留白，或融入主题元素的标题框架。正文仍使用 Microsoft YaHei；任何展示字体都必须已安装、获得授权，或替换为绘制的矢量效果。
16:9 PPT 字号：封面标题 60-92px，章节标题 44-60px，页面标题 30-40px，副标题 22-28px，正文 18-24px，图表标签／说明文字 12-16px。内容密集的咨询类页面通常使用 18-20px 正文；培训或主题演讲页面使用 22-24px。
尺寸与宽裕感：避免“小 PPT”综合征。页面包含 3-5 组文字时，正式正文通常应为 20-22px；内容密集的报告中，18px 是下限。如果文字必须小于 18px，应拆分页、将散文式内容改为表格／流程，或将细节移至备注。页面标题的视觉主次应明显突出，字号约为正文的 1.6-2.0 倍；卡片标题约为正文的 1.15-1.35 倍；脚注应保持视觉上的次要地位。
边距与网格：16:9 安全边距为 48-64px，标题区高度为 72-96px，页脚高度为 28-40px，主要内容区应对齐 12 列网格，或采用经过设计的不对称分栏。文字不得贴近画布边缘、图表坐标轴或装饰层。
单页内容上限：每页传达一个主要判断。正文页通常应包含一个主导视觉系统及 2-4 个辅助要点，或一张带有明确结论标题的密集表格／图表。
版式多样性：在正文页之间交替使用不同页面类型：图表＋结论、图片／文字分栏、流程图、证据表、留白式陈述、矩阵、时间线、常见问题／风险列表。避免默认反复使用“标题＋三张卡片”。
元素规范：使用扁平形状、清晰分隔线、轻微填充和克制的阴影。卡片用于归纳分组内容，而非包裹每一段文字。图标有助于快速浏览，但不能替代内容。
图片规范：生成的视觉素材应作为无文字辅助图层使用，除非页面是封面、章节分隔页、海报／展示页，或刻意以图像为主的 Web Deck 页面。正式正文 PPTX 应保持可编辑。
精修规范：避免过窄的间距、成片的直角方框、过度圆角的卡片、处处等权重的方框、薄弱的标题层级、对比度不足的灰色文字、孤立标签、拥挤的徽标、随意的装饰线条，以及未经授权但外观仿官方的标志。需要容器时，默认在可编辑 PPTX 中统一采用克制的 8-14 pt 圆角系列（Web 中为 12-20 px）；单个封面主视觉／证据面板可采用 18-24 pt／24-32 px。图表、分隔线和表格内部线条应保持笔直。添加装饰前，先运用留白、尺寸、对齐和一个清晰的主导元素。

项目文件存在时，运行正式审查：

python3 scripts/audit_formal_delivery.py <project_path_or_artifact>
python3 scripts/audit_design_completion.py <project_path_or_artifact>
python3 scripts/audit_visual_recipes.py <project_path_or_artifact>
python3 scripts/audit_pptx_native_objects.py <final.pptx> --expect text,shape

如果审查未通过，请报告具体问题，并在最终交付前修复演示文稿，除非用户明确选择在已知风险下发布。

注意

🚨 全局执行规范（强制）

此工作流是严格的串行流水线。以下规则优先级最高——违反其中任何一条都视为执行失败：

精简串行执行 — 按顺序执行各步骤，但不要人为制造额外等待。前置条件满足后，继续执行非阻塞步骤，无需询问用户是否“继续”。

引导式信息收集前先撰写最佳效果简报 — 如果用户直接在 Codex 中提出请求，且提供的信息不足以制作真正的 PPT，请先撰写 bestEffectBrief。如果提示只是信息较少，仅针对会实质影响交付成果的事实、来源、品牌/IP、合规或路线选择分阶段提问。如果提示属于 extreme-thin，且用户未明确要求正式的可编辑 PPTX，则使用 Extreme Thin Prompt Fallback，并制作固定风格的 Guizang 风格杂志网页演示文稿。

信息收集后仅因真实阻碍而停止 — 简报清晰到足以继续后，仅在缺少必要来源、路线选择、法律/品牌授权或必需的手动素材会导致继续操作风险时才停止。否则，做出合理假设、记录下来并继续。

信息收集后提供一份交付简报 — 如果请求含糊，引导式信息收集可以分多轮简短对话进行；此后，用一份简明的交付简报取代进一步的多轮确认。策略师仍负责决定画布、页数、受众、风格、颜色、图标、排版和图片，但这些内容应作为一份制作约定记录，而不是一连串面向用户的检查点。

进入步骤前设置关卡 — 每个步骤的前置条件（🚧 GATE）都列在该步骤顶部；开始该步骤前必须核实这些条件

禁止推测性执行 — 严禁为后续步骤“预先准备”内容（例如，在策略师阶段编写 SVG 代码）

禁止子 Agent 生成 SVG — 执行者第 6 步中的 SVG 生成依赖上下文，必须由当前主 Agent 从头到尾完成。严禁将页面 SVG 生成工作委派给子 Agent

仅可按顺序逐页生成 — 在执行者第 6 步中，全局设计上下文锁定后，必须在一次连续执行中逐页按顺序生成 SVG 页面。严禁分组批量生成页面（例如，每次生成 5 页）

每页重新读取 SPEC_LOCK — 生成每个 SVG 页面前，执行者必须执行 read_file <project_path>/spec_lock.md。所有颜色/字体/图标/图片都必须取自此文件，不得凭记忆使用或临时编造任何值。执行者还必须查阅当前页面的 page_rhythm 标签，并应用相应的版式规范（anchor / dense / breathing — 参见 executor-base.md §2.1）。此规则旨在防止长篇演示文稿中的上下文压缩漂移，并打破“每页都是卡片网格”的单一默认布局

SVG 必须手写，不得通过脚本生成 — 可编辑 PPTX 中的 SVG 页面必须由主 Agent 直接逐页编写。不得使用 Python / Node / shell 脚本批量生成演示文稿的 SVG。

重要

🌐 语言与沟通规则

回复语言：始终与用户输入和所提供源材料的语言保持一致。例如，用户用中文提问时，用中文回复；源材料为英文时，用英文回复。

明确覆盖规则：如果用户明确指定语言（例如，“请用英文回答”或“Reply in Chinese”），则使用指定语言。

模板格式：无论对话使用何种语言，design_spec.md 文件都必须始终遵循其原始英文模板结构（章节标题、字段名）。模板中的内容值可以使用用户的语言。 [!IMPORTANT]

🔌 与通用编码技能的兼容性

ultimate-ppt-master 是特定于仓库的工作流技能，不是通用应用程序脚手架

默认情况下，不要创建或要求 .worktrees/、tests/、分支工作流或其他通用工程结构

如果其他通用编码技能建议的仓库约定与此工作流冲突，请优先遵循此技能，除非用户明确另有要求

重要

本地运行时规则

运行脚本前，将 SKILL_DIR 解析为此技能目录。

如果存在捆绑的虚拟环境，请优先使用：${SKILL_DIR}/.venv/bin/python。

否则，请使用 Python 3.10+ 解释器（python3.13、python3.12、python3.11 或 python3.10）。不要使用 Python 3.9 或更早版本运行 PPT Master 脚本。

以下命令示例中若写有 python3，请替换为已解析的 Python 解释器。

主要流水线脚本

脚本	用途
`${SKILL_DIR}/scripts/source_to_md/pdf_to_md.py`	PDF 转 Markdown
`${SKILL_DIR}/scripts/source_to_md/doc_to_md.py`	文档转 Markdown——DOCX/HTML/EPUB/IPYNB 使用原生 Python；旧格式（.doc/.odt/.rtf/.tex/.rst/.org/.typ）使用 pandoc 作为备用方案
`${SKILL_DIR}/scripts/source_to_md/excel_to_md.py`	Excel 工作簿转 Markdown——支持 .xlsx/.xlsm；旧版 .xls 应另存为 .xlsx
`${SKILL_DIR}/scripts/source_to_md/ppt_to_md.py`	PowerPoint 转 Markdown
`${SKILL_DIR}/scripts/source_to_md/web_to_md.py`	网页转 Markdown（通过 `curl_cffi` 支持微信公众号和高安全性网页）
`${SKILL_DIR}/scripts/source_to_md/web_to_md.cjs`	为此融合包保留的旧版 Node.js 备用方案；优先使用 `web_to_md.py`
`${SKILL_DIR}/scripts/project_manager.py`	项目初始化 / 验证 / 管理
`${SKILL_DIR}/scripts/best_effect_router.py`	基于路由测试样例的确定性 Best-Effect 路由分类器
`${SKILL_DIR}/scripts/analyze_images.py`	图像分析
`${SKILL_DIR}/scripts/build_asset_plan.py`	在生成图像前构建 / 合并 `asset_plan.json`、提示词文件和生成项清单
`${SKILL_DIR}/scripts/image_gen.py`	AI 图像生成（多提供方）
`${SKILL_DIR}/scripts/image_search.py`	用于获取 PPTX 图像的网页图像搜索辅助工具
`${SKILL_DIR}/scripts/svg_quality_checker.py`	SVG 质量检查
`${SKILL_DIR}/scripts/spec_lock_slice.py`	强制执行 `spec_lock.md` 行数预算，并返回逐页锁定切片
`${SKILL_DIR}/scripts/execution_budget.py`	对页数超过阈值的演示文稿，要求使用 `resume-execute` 拆分模式
`${SKILL_DIR}/scripts/total_md_split.py`	拆分演讲者备注
`${SKILL_DIR}/scripts/finalize_svg.py`	SVG 后处理（统一入口）
`${SKILL_DIR}/scripts/svg_to_pptx.py`	导出为 PPTX
`${SKILL_DIR}/scripts/validate-magazine-deck.mjs`	静态验证 Style A 杂志风格演示文稿：占位符、类、节奏和图像引用
`${SKILL_DIR}/scripts/validate-swiss-deck.mjs`	使用 `references/magazine-web/swiss-layout-registry.json` 静态验证 Style B 瑞士风格演示文稿
`${SKILL_DIR}/scripts/animation_config.py`	可选的对象级 PPTX 动画辅助文件脚手架
`${SKILL_DIR}/scripts/notes_to_audio.py`	可选的录制式旁白音频生成
`${SKILL_DIR}/scripts/update_spec.py`	将 `spec_lock.md` 中的颜色 / font_family 更改应用到所有生成的 SVG
`${SKILL_DIR}/scripts/visual_review.py`	可选的基于评分标准的生成 SVG 页面视觉审核流程
`${SKILL_DIR}/scripts/audit_design_completion.py`	对页面角色、布局重复、素材、备注和交付准备情况进行视觉完成度审核
`${SKILL_DIR}/scripts/generate_visual_layers.py`	为混合可编辑演示文稿准备无文字页面视觉层提示词 / 清单
`${SKILL_DIR}/scripts/audit_visual_recipes.py`	审核 4.0 混合可编辑演示文稿的页面方案、视觉层和栅格策略

完整工具文档请参阅 ${SKILL_DIR}/scripts/README.md。

模板索引

索引	路径	用途
布局模板	`${SKILL_DIR}/templates/layouts/layouts_index.json`	查询可用的页面布局模板
场景预设指引	`${SKILL_DIR}/templates/presets/preset-directions.json`	预设常见的演示文稿结构、来源要求、模板候选项和 QA 检查
视觉方向套件	`${SKILL_DIR}/templates/visual-directions/index.json`	在 Strategist 编写 `design_spec.md` 前，选择符合特定上下文的美学准则
页面方案	`${SKILL_DIR}/templates/page-recipes/index.json`	在生成 PPTX/网页前，选择每页的结构方案
品牌预设	`${SKILL_DIR}/templates/brands/brands_index.json`	查询可用的品牌标识预设（颜色/排版/Logo/语调）
可视化模板	`${SKILL_DIR}/templates/charts/charts_index.json`	查询可用的可视化 SVG 模板（图表、信息图、示意图、框架）
图标库	`${SKILL_DIR}/templates/icons/`	参阅 `${SKILL_DIR}/templates/icons/README.md`；使用 `ls templates/icons/<library>/ \| grep <keyword>` 按需搜索图标
杂志网页样式 A 模板	`${SKILL_DIR}/assets/magazine-web/template.html`	单文件编辑风格/电子墨水风格网页演示文稿种子模板
杂志网页样式 B 模板	`${SKILL_DIR}/assets/magazine-web/template-swiss.html`	单文件瑞士风格网页演示文稿种子模板
杂志网页参考资料	`${SKILL_DIR}/references/magazine-web/`	主题、布局、组件、图像提示词、截图取景和 QA 检查清单

独立工作流

工作流	路径	用途
`topic-research`	`workflows/topic-research.md`	用户只提供主题、没有源文件时，在流水线开始前进行研究
`create-template`	`workflows/create-template.md`	独立的模板创建工作流
`create-brand`	`workflows/create-brand.md`	独立的纯品牌模板创建工作流
`resume-execute`	`workflows/resume-execute.md`	在完成步骤 1-5 后，于新的聊天中恢复 SVG 执行
`verify-charts`	`workflows/verify-charts.md`	导出前校准图表坐标
`customize-animations`	`workflows/customize-animations.md`	可选的 PPTX 对象级动画自定义
`generate-audio`	`workflows/generate-audio.md`	可选的录制旁白/音频工作流
`live-preview`	`workflows/live-preview.md`	基于浏览器的实时预览和批注工作流
`visual-review`	`workflows/visual-review.md`	SVG 生成后、后期处理前可选的逐页视觉审查

模式 2：杂志风格网页演示文稿工作流

仅当默认交付路径选择杂志风格网页演示文稿时，才使用此工作流。

网页步骤 1：明确演示文稿需求

复制模板前，先选择一种视觉子风格：

风格	适用情况	模板	参考资料
A · 电子杂志 × 电子墨水（默认）	用户提到杂志、编辑风格、电子墨水、类似 Monocle、人文风格、叙事风格，或未指定子风格	`assets/magazine-web/template.html`	`themes.md`、`layouts.md`、`components.md`
B · 瑞士国际主义 / 瑞士风格	用户提到瑞士风格、瑞士风、Helvetica、网格、信息设计、数据驱动、产品/工程/KPI 演示文稿	`assets/magazine-web/template-swiss.html`	`themes-swiss.md`、`layouts-swiss.md`、`swiss-layout-lock.md`

如果用户尚未提供这些信息，请一次只问一个简短问题：子风格 A/B、受众/场景、演讲时长或目标页数、源材料、图像可用性/截图处理方式、主题偏好和硬性约束。如果信息已足够，则说明假设后继续。默认保留样式 A，以保持原有的杂志/电子墨水美学不变。

如果用户需要结构方面的帮助，可提出以下叙事脉络：

Hook → Context → Core → Shift → Takeaway

网页步骤 2：创建 HTML 演示文稿文件夹

为网页演示文稿创建一个文件夹，通常为 <project_name>/ppt/，并在旁边创建一个 images/ 目录。复制种子模板：

mkdir -p "<project_path>/ppt/images" "<project_path>/ppt/assets"
cp "${SKILL_DIR}/assets/magazine-web/motion.min.js" "<project_path>/ppt/assets/motion.min.js"

风格 A · 编辑风／电子墨水风：

cp "${SKILL_DIR}/assets/magazine-web/template.html" "<project_path>/ppt/index.html"

风格 B · 瑞士风格：

cp "${SKILL_DIR}/assets/magazine-web/template-swiss.html" "<project_path>/ppt/index.html"

立即替换 index.html 中的 <title> 占位符；搜索 [必填]，并在交付前移除所有剩余占位符。

网页步骤 3：选择主题和布局

根据所选风格，只阅读所需的杂志参考资料：

风格 A 主题选择：${SKILL_DIR}/references/magazine-web/themes.md
风格 A 布局骨架和主题节奏规则：${SKILL_DIR}/references/magazine-web/layouts.md
风格 B 主题选择：${SKILL_DIR}/references/magazine-web/themes-swiss.md
风格 B 固定布局骨架：${SKILL_DIR}/references/magazine-web/layouts-swiss.md
风格 B 布局锁定规则：${SKILL_DIR}/references/magazine-web/swiss-layout-lock.md
风格 B 布局注册表：${SKILL_DIR}/references/magazine-web/swiss-layout-registry.json
共享组件详情：${SKILL_DIR}/references/magazine-web/components.md
截图取景：${SKILL_DIR}/references/magazine-web/screenshot-framing.md（仅在使用截图／UI 捕获时）
可选的生成式图像提示词：${SKILL_DIR}/references/magazine-web/image-prompts.md
最终 QA：${SKILL_DIR}/references/magazine-web/checklist.md

规则：

风格 A 使用五种精选主题之一；风格 B 使用一种瑞士主题预设。除非用户明确要求覆盖美学系统，否则不要自行编造十六进制颜色。
不要在同一个演示文稿中混用风格 A 和风格 B 的类系统。复制一种模板，并且只使用匹配的布局参考。
编写幻灯片前先规划页面节奏：每个 <section> 都必须包含 light、dark、hero light 或 hero dark。
使用布局骨架，不要从头编写幻灯片。
添加幻灯片标记前，检查 index.html 中的 <style> 块，确认所选骨架使用的每个类都已定义。
将图像放在 ppt/images/ 下，并使用 images/01-cover.jpg 这样的相对路径引用。
对于风格 B，每张幻灯片都应带有来自 swiss-layout-registry.json 的已注册 data-layout 值；如果布局定义了图像槽位，本地图像还应包含 data-image-slot。

网页步骤 4：生成、预览和检查

用所选区块填充 <main id="deck">，然后运行以下检查：

grep -n "\\[必填\\]" "<project_path>/ppt/index.html"
grep -n 'class="slide' "<project_path>/ppt/index.html"
node "${SKILL_DIR}/scripts/validate-magazine-deck.mjs" "<project_path>/ppt/index.html"

对于风格 B，还要运行静态瑞士风格锁定验证器：

node "${SKILL_DIR}/scripts/validate-swiss-deck.mjs" "<project_path>/ppt/index.html"

直接在浏览器中打开文件：

open "<project_path>/ppt/index.html"

使用 ${SKILL_DIR}/references/magazine-web/checklist.md 进行最终 QA。交付前必须修复 P0 问题。输出文件是 index.html，不是 .pptx。

模式 1：可编辑 PPTX 工作流

步骤 1：处理源内容

🚧 GATE：用户已提供源材料（PDF / DOCX / EPUB / URL / Markdown 文件 / 文本描述 / 对话内容——任何形式均可）。

如果用户提供的 PPT 制作上下文不够充分，请在转换源材料前运行 Brief Clarity Gate。对于直接的 Codex 请求，请分阶段提问，而不是自行假设完整需求。如果用户只说“做个 PPT”，没有提供主题、受众、源材料或目标，请勿开始主题调研或制作。

如果用户只提供主题名称或简要要求，没有源文件或实质性源内容，请先运行 workflows/topic-research.md，然后返回此处并使用生成的 Markdown / 源材料。

用户提供非 Markdown 内容时，请立即转换：

用户提供	命令
PDF 文件	`python3 ${SKILL_DIR}/scripts/source_to_md/pdf_to_md.py <file>`
DOCX / Word / Office 文档	`python3 ${SKILL_DIR}/scripts/source_to_md/doc_to_md.py <file>`
XLSX / XLSM / Excel 工作簿	`python3 ${SKILL_DIR}/scripts/source_to_md/excel_to_md.py <file>`
CSV / TSV	直接作为纯文本表格源读取
PPTX / PowerPoint 演示文稿	`python3 ${SKILL_DIR}/scripts/source_to_md/ppt_to_md.py <file>`
EPUB / HTML / LaTeX / RST / 其他	`python3 ${SKILL_DIR}/scripts/source_to_md/doc_to_md.py <file>`
网页链接	`python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <URL>`
微信 / 高安全性网站	`python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <URL>`（需要 `curl_cffi`；仅当该程序包不可用时，才回退到 `node web_to_md.cjs <URL>`）
Markdown	直接读取

DOCX/PPTX 源中的 Office 矢量素材（EMF/WMF）：将提取出的 EMF/WMF 文件保留为一等矢量素材。除非用户明确接受栅格化，否则不要将其转换为 PNG；finalize_svg.py 会跳过这些文件，svg_to_pptx.py 会将其作为原生 Office 媒体嵌入。

✅ 检查点——确认源内容已就绪，然后继续步骤 2。

步骤 2：初始化项目

🚧 GATE：步骤 1 已完成；源内容已就绪（Markdown 文件、用户提供的文本或对话中描述的需求均有效）。

python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name> --format <format>

格式选项：ppt169（默认）、ppt43、xhs、story 等。完整格式列表请参阅 references/canvas-formats.md。

导入源内容（根据情况选择）：

情况	操作
有源文件（PDF/MD 等）	`python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files...> --copy`
用户在对话中直接提供了文本	无需导入——内容已在对话上下文中；后续步骤可直接引用

✅ 默认使用 --copy：导入时会在 sources/ 下创建项目本地副本，并保留用户的原始文件。

对于桌面、下载目录、共享驱动器和多项目复用，优先使用 --copy。

仅当用户明确要求导入后删除原文件时，才使用 --move / 归档并删除原文件。

为避免意外提交，仓库内部生成的研究素材仍可能默认移动；传入 --copy 可覆盖此行为。

中间素材（例如 _files/ 目录）会由 import-sources 自动处理。

✅ 检查点——确认项目结构已成功创建，sources/ 中包含所有源文件，转换后的素材已就绪。然后继续步骤 3。

步骤 3：模板选项

🚧 关卡：步骤 2 已完成；项目目录结构已就绪。

默认路径 — 自由设计，不询问。 直接进入步骤 4。不要查询 layouts_index.json，也不要询问用户是选择 A/B 模板还是自由设计。自由设计是标准模式：AI 会根据具体内容量身定制结构和风格。

模板流程需用户主动选择。 只有用户之前的消息中出现以下明确触发条件之一时，才进入模板流程：

用户指定某个模板（例如：“用 mckinsey 模板” / “use the academic_defense template”）
用户指定可对应到某个模板的风格或品牌参考（例如：“McKinsey 那种” / “Google style” / “学术答辩样式”）
用户明确询问有哪些模板（例如：“有哪些模板可以用”）

场景预设提示（非阻塞）。 如果任务明显符合某个常见场景，请读取 ${SKILL_DIR}/templates/presets/preset-directions.json，并使用匹配的预设来确定叙述思路、来源要求、推荐的幻灯片列表、候选图表和质量检查项。这不会强制使用视觉模板。仅当用户明确要求使用该模板、询问有哪些模板并选择其中一个，或交接清单中已包含明确的预设/模板选择时，才复制版式/品牌模板文件。

仅当触发条件满足时：读取 ${SKILL_DIR}/templates/layouts/layouts_index.json，确定匹配项（或在触发条件 3 下列出可用选项），并将模板文件复制到项目目录：

cp ${SKILL_DIR}/templates/layouts/<template_name>/*.svg <project_path>/templates/
cp ${SKILL_DIR}/templates/layouts/<template_name>/design_spec.md <project_path>/templates/
cp ${SKILL_DIR}/templates/layouts/<template_name>/*.png <project_path>/images/ 2>/dev/null || true
cp ${SKILL_DIR}/templates/layouts/<template_name>/*.jpg <project_path>/images/ 2>/dev/null || true

轻量提示（非阻塞，可选）。 进入步骤 4 前，如果用户的内容明显非常适合某个现有模板（例如，显然是学术答辩、政府报告或 McKinsey 风格的咨询演示文稿），且用户没有表达任何模板意向，AI 可以发送一句提示，然后继续，无需等待：

注意：模板库中有一个名为 <name> 的模板，与此场景非常契合。如果你想使用它，请告诉我；否则我会继续采用自由设计。

这只是提示，不是提问——不要阻塞流程，也不要要求用户回答。如果匹配程度较弱或存在歧义，则完全跳过此提示。

如需创建新的全局模板，请读取 workflows/create-template.md

✅ 检查点 — 默认路径无需用户互动，直接进入步骤 4。如果触发了模板流程，则在继续之前复制模板文件。

步骤 4：交付简报与策略师阶段（必需 — 不可跳过）

🚧 关卡：步骤 3 已完成；已采用默认自由设计路径，或者（如触发模板流程）已将模板文件复制到项目中。

首先，读取角色定义：

Read references/strategist.md

⚠️ strategist.md 中的强制关卡：编写 design_spec.md 之前，策略师必须 read_file templates/design_spec_reference.md，并按照其完整的 I–XI 部分结构编写规格说明。明确的关卡规则见 strategist.md 第 1 节。

⚠️ 视觉方向关卡：策略师必须读取 templates/visual-directions/index.json，选择最匹配的视觉方向包（或选择 custom），并记录其适用原因、主要美学风险、必需的页面角色、页面配方和反模式。

必须完成一份交付简报：

交付简报是一项精简的制作决策，不是八项分别面向用户的确认。对于 Web 交接项目，先从 project-brief.json 中读取 bestEffectBrief、briefMode、visualBrief、guidedBrief 和 expectationFit。对于直接向 Codex 提出的请求，请在任何引导式信息收集之前创建 bestEffectBrief。如果 bestEffectBrief.strategy = best-effect-fixed-style，则采用类似 Guizang 的杂志风格 Web Deck 固定样式继续，除非事实、来源、品牌/IP 或合规方面的阻碍会实质性改变交付内容。否则，如果 expectationFit.readyForProduction 为 false，则进行引导式信息收集。如果来源、受众和输出路径都已足够明确，请记录假设并继续，无需等待。

幻灯片格式
页数范围
目标受众
风格目标
配色方案
图标使用方式
字体排版方案
图片使用方式

同时记录预期契约：

bestEffectBrief：v5.3 自动扩展的最佳效果简报、提示词质量、推荐路线、极简提示词回退状态、固定风格和假设；
briefMode：visual-tags、codex-guided-intake、source-first、draft-with-assumptions、best-effect-expanded 或 best-effect-fixed-style；
visualBrief：所选标签、粘贴的背景信息、特殊要求和参考链接；
guidedBrief：场景、受众、目的、核心信息、来源、页数、风格、素材规则、输出格式、必须包含项和必须避免项；
expectationFit：风险级别、缺失信号、假设、冲突、来源充足度、成功标准，以及是否已准备好投入制作。

简报中使用面向用户的浅显措辞。除非有助于理解，否则不要暴露专业标签：在对话中使用“可编辑正文”“页面角色”“主视觉”“图文分栏”“图表页”“风险页”，而不是依赖 raster_policy、page_recipe_id 或 layout_family。将技术字段名称保留在 design_spec.md 和 spec_lock.md 中。

如果页数较多或来源内容庞大，请在第 5 步之后添加一条简短的分步模式说明，使用用户的语言，建议用户开启新对话并输入 继续生成 projects/<project_name>，以运行 workflows/resume-execute.md。规模正常时，默认使用连续模式。

在定稿 spec_lock.md 之前，确保不超出上下文预算：

python3 ${SKILL_DIR}/scripts/spec_lock_slice.py --check-budget <project_path>
python3 ${SKILL_DIR}/scripts/execution_budget.py --page-count <N>

spec_lock.md 行数预算：将 spec_lock.md 控制在 120 行以内。如果内容必须增加，执行器应在处理每一页之前运行 python3 ${SKILL_DIR}/scripts/spec_lock_slice.py <project_path> PNN，而不是重新读取整个锁定文件。超过 16 页的幻灯片必须在第 5 步之后使用 workflows/resume-execute.md；以 execution_budget.py 的结果为准。

如果用户提供了图片，必须在输出设计规范之前运行分析脚本（不要直接读取或打开图片文件——仅使用脚本输出）：

python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images

⚠️ 图片处理规则：AI 绝不能直接读取、打开或查看图片文件（.jpg、.png 等）。所有图片信息都必须来自 analyze_images.py 脚本输出或设计规范的图片资源列表。

输出：

<project_path>/design_spec.md — 易于阅读的设计说明
<project_path>/spec_lock.md — 机器可读的执行契约（根据 design_spec.md 中的决策提炼；执行器在处理每一页之前都会重新读取此文件）。骨架请参阅 templates/spec_lock_reference.md。
<project_path>/design-quality-report.md — 在验证期间创建或更新；总结视觉方向契合度、页面角色覆盖情况、素材、重复布局风险和剩余阻塞项。

✅ 检查点 — 阶段交付物已完成，自动进入下一步：

## ✅ Strategist Phase Complete
- [x] One delivery brief completed (or assumptions recorded)
- [x] Design Specification & Content Outline generated
- [x] Execution lock (spec_lock.md) generated
- [ ] **Next**: Auto-proceed to [Image_Generator / Executor] phase

第 5 步：图像获取阶段（有条件）

🚧 关卡：第 4 步已完成；已生成设计规范和内容大纲，且任何实际阻塞问题均已解决。

触发条件：至少有一行设计规范图像的 Acquire Via: ai 和／或 Acquire Via: web。如果所有行都是 user 或 placeholder，则直接跳至第 6 步。

首先构建或合并 Asset Factory 父级契约：

python3 ${SKILL_DIR}/scripts/build_asset_plan.py <project_path>

asset_plan.json 是唯一事实来源。asset-plan.md 仅供人类阅读。构建器会按 ID 保留已有条目的 status、current_generation_evidence 和已完成的提示词文件；重新运行时绝不能清除 Generated 证据。

始终先阅读通用框架：

Read references/image-base.md

然后按需加载所需的特定路径参考资料：

获取方式	加载参考资料	执行
`ai`	`references/image-generator.md`	默认使用 Codex 原生 GPT 图像生成（可用时使用 `image2`）；否则运行 `python3 ${SKILL_DIR}/scripts/image_gen.py --asset-plan <project_path>/asset_plan.json`
`web`	`references/image-searcher.md`	`python3 ${SKILL_DIR}/scripts/image_search.py ...`
`user` / `placeholder`	跳过	跳过

Generated 资源证据架构：

{"run_id":"...","timestamp":"...","backend":"...","prompt_sha256":"...","file_sha256":"...","width":1792,"height":1024}

每个 Generated asset_plan.json.items[] 条目都必须具有非空的 current_generation_evidence，且符合此架构。第 6 步之前，运行 python3 ${SKILL_DIR}/scripts/audit_image_contracts.py <project_path>/asset_plan.json。

✅ 检查点 — 确认已尝试为每一行生成图像，然后继续第 6 步：

## ✅ Image_Generator Phase Complete
- [x] Prompt document created
- [x] Each image: status is either `Generated` (file present in images/) or `Needs-Manual` (reported to user with filename + reason)
- [x] No row remains `Pending`

如果生成失败，不要停止 — 按照 references/image-generator.md 中的故障处理规则操作：重试一次；在可行时，在 Codex／image2 和已配置的后端之间切换；然后将该行标记为 Needs-Manual，报告文件名和原因，并继续第 6 步。

🚧 Needs-Manual 图像条目会阻止第 6 步：如果任何 asset_plan.json 条目的状态为 Needs-Manual，则预期文件必须存在于 project/images/<filename>，或者 Executor 必须绘制一个清晰标注预期文件名的占位框。不要在图像引用缺失且未提示的情况下开始生成 SVG。

步骤 6：执行阶段

🚧 GATE：步骤 4（以及触发时的步骤 5）已完成；asset_plan.json 中没有未解决的 Pending 行；任何 Needs-Manual 行都有实际文件或明确标注的占位方案；所有前置交付物均已就绪。

根据所选样式阅读角色定义：

Read references/executor-base.md          # REQUIRED: common guidelines
Read references/shared-standards.md       # REQUIRED: SVG/PPT technical constraints
Read references/executor-general.md       # General flexible style
Read references/executor-consultant.md    # Consulting style
Read references/executor-consultant-top.md # Top consulting style (MBB level)

只需阅读 executor-base + shared-standards + 一个样式文件。

设计参数确认（强制）：生成第一个 SVG 之前，Executor 必须检查并输出设计规范中的关键设计参数（画布尺寸、配色方案、字体方案、正文字号），以确保遵循规范。详情请参见 executor-base.md 第 2 节。

实时预览自动启动（强制）：生成第一个 SVG 之前，以实时模式启动浏览器编辑器，并在执行器阶段和导出期间保持运行：

python3 ${SKILL_DIR}/scripts/svg_editor/server.py <project_path> --live

Executor 开始时立即启动；此时 svg_output/ 目录可能仍为空。
默认 URL 为 http://localhost:5050；如果端口被占用，请使用 --port <other>，并报告实际 URL。
将其作为长期运行的独立进程运行。生成页面前不要等待它退出。
生成期间不要读取或应用提交的批注。如果用户之后要求应用批注，请在导出后使用 workflows/live-preview.md。

预生成批量读取（强制）：生成第一个 SVG 之前，批量读取 spec_lock.page_layouts 中引用的每个不同版式 SVG，以及 spec_lock.page_charts 中引用的每个不同图表 SVG（包括备用图表引用）。每个文件在开始时读取一次。

逐页重新读取 spec_lock（强制）：生成每一页 SVG 之前，Executor 必须读取锁文件。如果锁文件未超出预算，则执行 read_file <project_path>/spec_lock.md；如果超出预算，或演示文稿在新的聊天中恢复，则运行 python3 ${SKILL_DIR}/scripts/spec_lock_slice.py <project_path> PNN 并使用该切片。只能使用其中列出的颜色、字体、图标和图像，以及逐页查询到的 page_rhythm、page_layouts 和 page_charts。详情请参见 executor-base.md §2.1。

生成规范遵循全局执行规范第 7–10 条：仅由主 Agent 执行、按顺序逐页生成、逐页读取或切片锁文件，以及手工编写 SVG。

视觉构建阶段：

按顺序逐页生成 SVG，每次生成一页，一次连续完成 → <project_path>/svg_output/

质量检查关卡（强制）——所有 SVG 生成完毕后、演讲者备注生成之前：

python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>

任何 error（禁止使用的 SVG 功能、viewBox 不匹配、偏离 spec_lock 等）都必须在继续之前于出错页面修复——返回视觉构建阶段，重新生成该页面并重新运行检查。
warning 条目（例如低分辨率图像、不适用于 PPT 的字体末端样式）应在易于处理时检查并修复；否则可以确认并继续。
必须针对 svg_output/ 运行检查器——如果只在 finalize_svg.py 之后运行，就太迟了（finalize 会重写 SVG，且某些违规可能被掩盖）。
检查成功后，检查器会将 svg_output 摘要写入 pipeline-state.json。如果自上次检查通过后 SVG 文件发生变化，svg_to_pptx.py 会阻止导出。

逻辑构建阶段：

生成演讲者备注 → <project_path>/notes/total.md

✅ 检查点——确认所有 SVG 和备注均已完整生成并通过质量检查。直接进入步骤 7 后处理：

## ✅ Executor Phase Complete
- [x] All SVGs generated to svg_output/
- [x] svg_quality_checker.py passed (0 errors)
- [x] Speaker notes generated at notes/total.md

包含图表页面？ 如果此演示文稿包含数据图表，请在步骤 7 之前运行 workflows/verify-charts.md 以校准坐标。如果演示文稿没有图表页面，则跳过。

步骤 7：后处理与导出

🚧 门槛：步骤 6 已完成；所有 SVG 均已生成到 svg_output/；演讲者备注 notes/total.md 已生成；pipeline-state.json 记录了当前 svg_output 摘要的 SVG 质量检查通过。

🚧 图像就绪门槛：如果步骤 5 留下了任何 Needs-Manual 图像行，则在运行步骤 7.1 前，所有预期文件都必须存在于 project/images/<filename>。如果文件缺失，请暂停并报告文件名及所需位置。

⚠️ 以下三个子步骤必须逐个单独执行。每条命令都必须运行完毕并确认成功后，才能运行下一条。 ❌ 绝不要将三条命令放在同一个代码块或单次 shell 调用中。

运行规范的三命令流程（与 references/shared-standards.md §5 相同）：

步骤 7.1 — 拆分演讲者备注：

python3 ${SKILL_DIR}/scripts/total_md_split.py <project_path>

步骤 7.2 — SVG 后处理（图标嵌入／图像裁剪与嵌入／文本扁平化／圆角矩形转路径）：

python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>

步骤 7.3 — 导出 PPTX（默认嵌入演讲者备注）：

python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path>
# Output: exports/<project_name>_<timestamp>.pptx
#
# Optional SVG snapshot preview:
# python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> --svg-snapshot
#
# Optional conversion diagnostics:
# python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> --trace-conversion

步骤 7.4 — 视觉完成度审查：

python3 ${SKILL_DIR}/scripts/visual_review.py <project_path>
python3 ${SKILL_DIR}/scripts/audit_design_completion.py <project_path>

如果浏览器渲染依赖不可用，visual_review.py 可能会失败；如果发生这种情况，请在 design-quality-report.md 中记录阻碍因素，而不是悄悄跳过视觉 QA。
正式交付前，audit_design_completion.py 必须通过，除非用户明确接受所列的视觉阻碍因素。

❌ 绝不要使用 cp 代替 finalize_svg.py——它会执行多个关键处理步骤 ❌ 绝不要添加 --only 等额外标志

可选动画标志：默认设置已启用丰富的入场动画。仅在用户提出要求时调整：

-t <effect> 页面转场；默认值为 fade
-a <effect> 单个元素的入场动画；默认值为 mixed
--animation-trigger {on-click,with-previous,after-previous}
--animation-config <path> 可选的对象级 sidecar，通常通过 workflows/customize-animations.md 创建
--auto-advance <seconds> 类似自助展示终端的自动播放

可选录制旁白：仅当用户要求旁白／音频／视频导出时，才运行 workflows/generate-audio.md。不要脱离该工作流直接调用 notes_to_audio.py，因为必须一次性确认后端／语音／速率／嵌入选项。

导出后批注时段：如果实时预览服务仍在运行，且用户提交了批注，请仅在导出后通过 workflows/live-preview.md 应用这些批注。

角色切换协议

切换角色前，必须先阅读相应的参考文件——禁止跳过。输出标记：

## [Role Switch: <Role Name>]
📖 Reading role definition: references/<filename>.md
📋 Current task: <brief description>

参考资源

资源	路径
共享技术约束	`references/shared-standards.md`
画布格式规范	`references/canvas-formats.md`
图像布局规范	`references/image-layout-spec.md`
SVG 图像嵌入	`references/svg-image-embedding.md`
图标库	`templates/icons/README.md`

备注

本地预览：python3 -m http.server -d <project_path>/svg_final 8000
故障排查：如果用户在生成过程中遇到问题（布局溢出、导出错误、图像空白等），建议查看 docs/faq.md——其中包含从真实用户报告中整理的已知解决方案，并会持续更新

支持 Markdown

登录后评论

基本信息

作者: kdnsna
仓库: kdnsna/ultimate-ppt-master-skill
分类: 文档处理
安装次数: 99
GitHub Stars: 2

报告问题