waterdjiang/wattter_openskills/wtt-course-pptx-builder

课程 PPT 构建器技能

AI 驱动的多格式 SVG 内容生成系统。通过多角色协作将源文档转换为高质量 SVG 页面，并最终导出为 PPTX。

核心流水线: 源文档 → 创建项目 → [模板] → 策略师 → [图像生成] → 执行器实时预览 → 质量检查 → 后期处理 → 导出

[!CAUTION]

## 🚨 全局执行纪律（强制要求）

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

1. 串行执行（SERIAL EXECUTION） — 各步骤必须按顺序执行；前一步的输出是后一步的输入。一旦前置条件满足，相邻的非 BLOCKING 步骤可以连续进行，无需用户说"继续"

2. BLOCKING = 硬停止（BLOCKING = HARD STOP） — 标记为 ⛔ BLOCKING 的步骤需要完全停下；AI 必须等待用户明确回复后才能继续，绝不能替用户做任何决定

3. 禁止跨阶段打包（NO CROSS-PHASE BUNDLING） — 跨阶段打包是被禁止的。（注：Step 1 的流程闸口与 Step 4 的八项确认属于 ⛔ BLOCKING——AI 必须先呈现推荐方案并等待用户明确确认后才能继续。一旦用户确认，后续所有非 BLOCKING 步骤——设计规范输出、SVG 生成、讲者备注、后期处理——都可以自动进行，无需再次确认）

4. 进入前先过闸（GATE BEFORE ENTRY） — 每个 Step 顶部都列出了前置条件（🚧 GATE），开始该 Step 前必须先校验

5. 禁止投机执行（NO SPECULATIVE EXECUTION） — 禁止"预先准备"后续 Step 的内容（例如，在 Strategist 阶段就写 SVG 代码）

6. 禁止子代理生成 SVG（NO SUB-AGENT SVG GENERATION） — Executor Step 6 的 SVG 生成是上下文相关的，必须由当前主代理端到端完成。禁止把页面 SVG 生成委派给子代理

7. 只允许逐页顺序生成（SEQUENTIAL PAGE GENERATION ONLY） — 在 Executor Step 6 中，确认全局设计上下文后，SVG 页面必须以一次性连续过程逐页生成。禁止批量生成（例如一次 5 页）

8. 每页重读 SPEC_LOCK（SPEC_LOCK RE-READ PER PAGE） — 在生成每张 SVG 页面之前，Executor 必须 read_file <project_path>/spec_lock.md。所有颜色 / 字体 / 图标 / 图片都必须来自该文件——禁止凭记忆或临时编造。Executor 还必须查询当前页的 page_rhythm（anchor / dense / breathing）、page_layouts（如要继承的模板 SVG）以及 page_charts（如要套用的图表模板）。空 / 缺失条目是 Strategist 的有意信号——参见 executor-base.md §2.1。该规则是为了抵御长 deck 上的上下文压缩漂移，并打破"每页都是卡片网格"的统一默认

9. SVG 必须手写，禁止脚本生成（SVG MUST BE HAND-WRITTEN, NOT SCRIPT-GENERATED） — 每张 SVG 页面都由主代理直接逐页手写（参见规则 6 和 7）。禁止编写或运行 Python / Node / shell 脚本批量产出 SVG 文件——包括循环生成页面、数据模板化、或通过生成器发出——即便以"省 token"、"快速草稿"或"用户赶时间"为借口。脚本生成路径曾在特性分支上试过并被放弃：跨页视觉一致性依赖于带完整上游上下文的逐页手写，生成器脚本无法复现

[!IMPORTANT]

## 🌐 语言与沟通规则

- 回答语言：与用户输入及源材料保持一致。若用户明确指定（如"请用英文回答"），以用户指定为准。

- 模板格式：design_spec.md 必须保持其原始英文模板结构（章节标题、字段名），无论对话使用何种语言。内容值可使用用户语言。

[!IMPORTANT]

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

- wtt-course-pptx-builder 是仓库级工作流，不是通用应用脚手架

- 默认不要创建 .worktrees/、tests/、分支工作流或通用工程结构

- 与通用编码技能冲突时，除非用户明确说明，否则以本技能为准

主要流水线脚本

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

Windows 提示：若 python3 ... 命令失败（python.org 安装版本常见，只提供 python.exe 而无 python3.exe），请改用 python 重跑同一命令。

模板索引

三个模板索引（brands / layouts / decks）的每条条目都自带 kind 与 path 字段，供 Step 3 流程 1 的统一菜单与"有哪些模板？"带外问答共用。新模板经 register_template.py 注册后自动出现在索引与流程 1 菜单中。

独立工作流

工作流

Step 1：流程确认与源内容处理

🚧 GATE：用户已提供初始需求（主题 / 源文件 / 模板文件 / 文字描述——任何形式均可）。

1a. 流程确认（三选一闸口）

⛔ BLOCKING（仅当歧义时）：向用户呈现三条流程并等待选择。若用户开场消息已隐含某条流程，则预选并在同一轮内确认，无需单独追问。

推荐信号：附 .pptx 模板 → 推荐流程 2；提及库中模板名或明确要复用 → 推荐流程 1；其余 → 推荐流程 3。无信号或歧义时才 BLOCKING 三选一。

显式路径逃生口：用户若直接给出一个模板目录路径（如 templates/decks/招商银行/），视为流程 1 预选该模板，跳过 Step 3 的菜单选择，一轮确认即进入 Step 4。

确认后，所选流程决定 Step 3 的获取方式；Step 2 及之后的生成流水线三条流程完全一致。

1b. 源内容处理

没有源内容怎么办？ 当用户只提供主题名或需求，没有任何文件或实质性描述时，请先运行 `topic-research` 工作流，再回到此处以其产物作为输入。

若用户提供的是非 Markdown 内容，请立即转换：

流程 2 的 `.pptx` 模板文件不是内容源——它是设计参考。在 Step 2 import-sources 时随内容源一起进入 sources/，但 Step 1b 不对它做内容转换；它的设计分析发生在 Step 3 流程 2。

来自 DOCX/PPTX 源中的 Office 矢量资源（EMF/WMF）：

doc_to_md.py / ppt_to_md.py 会提取内嵌的 Office 矢量图像（.emf/.wmf）

与位图一起被导出。import-sources 后，这些资源会落到 images/ 目录中，

与 image_manifest.json 一起作为 §VIII 图像资源清单中的一等资源。

不要把 EMF/WMF 转成 PNG。 课程 PPT 构建器流水线将它们作为外部引用保留

（finalize_svg.py 会跳过它们），svg_to_pptx.py 通过

image/x-emf / image/x-wmf MIME 嵌入为 PPTX 原生媒体——PowerPoint 以全矢量保真度渲染。

通过 LibreOffice/Inkscape 转换会引入 CJK 字体替换漂移以及

栅格化损失；原始 EMF/WMF 始终比转换后的 PNG 保真度更高。

基于浏览器的实时预览无法渲染 EMF（会显示空白）——这是预期行为；

PPTX 输出才是最终标准。

✅ 检查点 —— 确认流程已选定、源内容就绪后，进入 Step 2。

Step 2：项目初始化

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

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

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

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

⚠️ 必须使用 `--move`（而不是拷贝）：所有源文件——Step 1 生成的 Markdown、原始 PDF / MD / 图片——都会通过 import-sources --move 进入 sources/。执行完毕后，原始位置将不再保留。中间产物（如 _files/）会自动处理。

✅ 检查点 —— 确认项目结构创建成功，`sources/` 包含所有源文件，转换材料就绪。进入 Step 3。

Step 3：模板获取（按流程分支）

🚧 GATE：Step 2 已完成；项目目录结构就绪。按 Step 1a 选定的流程分支获取模板。

三条流程共用同一生成流水线——差异只在模板如何到达 <project>/templates/。无论哪条流程，一旦 <project>/templates/design_spec.md 就位，Step 4 Strategist 的读取与锁定逻辑完全一致。

流程 1 · 用 skill 库模板（渐进式目录）

Tier 1 — 读索引渲染菜单：读取三个 *_index.json（条目已含 kind / path，轻量），合并为统一菜单呈现给用户：

Read templates/brands/brands_index.json
Read templates/layouts/layouts_index.json
Read templates/decks/decks_index.json

每条展示：id / kind / summary / primary_color（brand、deck）/ canvas_format / page_count（layout、deck）。用户按编号或 id 选一个或多个（可跨 kind 融合，见下方"多选融合"）。

兼容新增模板：register_template.py 自动把新模板注册进 *_index.json；本菜单实时读索引，新模板零代码改动即出现。不要在 skill 任何地方硬编码模板列表。

"有哪些模板？"属于带外问答——通过列出索引条目及其 path 回答。仅列举不推进流水线；用户必须在流程 1 的菜单里选定才能推进。

Tier 2 — 选定后加载模板：用户选定后，按各条目的 path 字段定位目录，cp -r <selected_dir>/* <project_path>/templates/（多选则先融合，见下）。选定前不读模板的 design_spec.md 或 SVG——渐进式加载，省 token。

显式路径逃生口：若用户在 Step 1a 已直接给出目录路径（或在流程 1 中直接给路径），跳过菜单，等价于预选该路径，直接 cp。AI 不应"贴心"地把裸名字解析成路径——用户必须走菜单或给路径。

三种模板类型（架构上有三个相互独立的参考包；完整 schema 见 `docs/zh/templates-architecture.md`）：

单选派发（按所选条目的 kind）：

TEMPLATE_DIR=<selected path from index>
cp -r ${TEMPLATE_DIR}/* <project_path>/templates/

一行复制对三种类型都够用——spec 中的 kind 字段会告诉 Strategist 如何读取；下游代码不做区分。

多选融合——当用户选了两个或以上不同 kind 的模板时，Step 3 将它们融合成单个 <project>/templates/design_spec.md。默认粒度是段级整体替换——识别 / 结构 / 中段这些整段内容从该段优先级最高的来源取，不做隐式的字段级混搭。

段的归属（决定融合覆盖优先级）：

按段的覆盖优先级：

字段级微调（例如"用 anthropic brand 但主色改为 #FF0000"）不属于 Step 3 融合的范畴——它会作为普通用户请求流入 Strategist 的八项确认 e–g。

同 kind 多选——冲突解决：当用户选了两个同 kind 的模板（例如 brands/anthropic + brands/google）时，Step 3 会在融合前弹出一个冲突提示——类似于解决 git 合并冲突：

AI: 你选了两个 brand，检测到段级冲突：
    - 配色（Anthropic 橙红 vs Google 多色）
    - 字体（Styrene/AnthropicSans vs GoogleSans/Roboto）
    - Logo（Anthropic 标 vs Google 标）
    - 语气（克制 vs 友好）
    - 图标风格（描边 vs 填充）
 
    要 (a) 全部按 Anthropic / (b) 全部按 Google / (c) 逐段挑？

规则：

• 默认：不做隐式排序——任何跨来源的段差异都报告为冲突
• 仅当用户选择 (c) 时，AI 才会逐段过一遍
• 字段级冲突不在范围内——只做段级
• 三个或以上同 kind 选择不支持——请用户收敛到最多两个

融合后 spec 的来源说明：当发生融合时（任何多选情况），生成的 <project>/templates/design_spec.md 会在其 H1 标题正下方带一个来源说明块：

> **融合来源：**
> - deck: `templates/decks/招商银行/` （基底）
> - brand: `templates/brands/anthropic/` （识别覆盖）
> - layout: `templates/layouts/academic_defense/` （结构覆盖）
> - 已解决冲突：配色取自 anthropic（用户选了 a）