qingfeng-ppt — 轻风PPT 自动套版（三步工作流）

启动与欢迎语

当用户指令里出现 qingfeng-ppt / 轻风PPT 等关键词时，立即启动本技能，并先回复下面这句欢迎语（一字不改）：

> 欢迎使用轻风PPT，若要生成个性化的PPT，请上传一个规范PPT模板。也可上传一张背景图片，对内置模板进行改变背景设置。若使用内置模板，直接上传文档或PPT主题。

然后等待用户输入，按下面的「第 1 步分支」处理。

核心原则（不可违反）

1. 只用模板原生【文本】占位符灌字：标题、副标题、正文、关键词框。绝不新建文本框，不改占位符位置/大小/颜色/字号/换行等任何样式，不添加任何装饰或图片。
2. 文字颜色由「背景亮度」决定，不是永远白字：换肤后按母版背景平均亮度自动选色——浅底→黑字、深底→白字（保证可读）。直接使用用户上传的规范模板时不改其任何样式（含文字色）。第 3 步生成阶段一律不动颜色。
3. 图片 / 其他占位符第 3 步一律留空：第 3 步只灌文字，图等占位符先留空，由用户在 PowerPoint 手动补，或走第 4 步（用户回复「生图」）自动生成插入。
4. 版式由内容或标注决定：用户在大纲页标题末尾写 [版式名] 即锁定；没写则由 AI 按关键词(二级标题)数量自动匹配。
5. 三步必须分步执行，第 2 步产出大纲后必须等用户确认才进第 3 步。

技能自带资源

• assets/轻风模板_规范版.pptx — 内置 14 版式骨架（默认母版）：00_封面 ~ 13_六栏，关键词框版式层文本为 输入关键词，无模板时直接用它。
• scripts/restyle_template.py — 第 1 步换肤：把用户模板的母版背景+主题色套到轻风骨架上，并按亮度自动选黑/白字；规范模板则原样复制使用；仅给图则只换背景。
• scripts/list_layouts.py — 第 2 步辅助：读出当前 TEMPLATE 的 14 个版式名称与适用场景，供用户为每页选择/锁定版式。
• scripts/build_ppt.py — 第 3 步读取严格 md 大纲（或兼容 JSON），把文字纯灌入模板文本框，不改任何样式。
• scripts/fill_images.py — 第 4 步（可选）自动生图：检测所有图片占位符，按页面内容调用 agnes-image 2.1 生成图片并插入；支持哈希缓存、失败兜底、--dry-run 预览提示词。
• scripts/validate_outline.py — 第 2 步产出大纲后的结构校验器：确认 ≥4 部分、每部分 ≥2 要点、每要点 2-6 条内容且关键词+核心齐全。
• references/OUTLINE_TEMPLATE.md — 第 2 步标准大纲文档模板（用户可改、可定义版式）。
• references/大纲标注说明.md — [版式] 标注写法与对照表。
• （optimize_template.py 为旧版，已被 restyle_template.py 取代，勿再用。）

第 1 步：换肤 / 选模板（分支处理）

先判断用户给了什么：

分支 A：用户直接上传了【文档或主题】，未给模板/图片

视为「使用内置模板」——不换肤，直接以内置骨架作 TEMPLATE（assets/轻风模板_规范版.pptx），跳过本步收尾，直接进入第 2 步。

分支 B：用户上传了模板

运行换肤脚本判断「是否规范」：

C:/Users/chenw/.workbuddy/binaries/python/envs/default/Scripts/python.exe \
  "C:/Users/chenw/.workbuddy/skills/qingfeng-ppt/scripts/restyle_template.py" \
  --user "用户模板路径.pptx" --output "更新后模板.pptx"

脚本判定逻辑（agent 据此解读输出）：
- 规范模板（母版含 输入关键词 关键词框、版式名覆盖封面/目录/节/分栏等主要角色）→ 脚本直接复制、打印「直接使用，不换肤」。直接用上传模板作 TEMPLATE。
- 非规范模板 + 母版可读到背景（图片或纯色）→ 套轻风骨架换肤，按亮度选黑/白字，输出 更新后模板.pptx。
- 非规范模板 + 母版无背景 → 脚本打印「上传模板非规范母版，请上传一张图片作为生成PPT背景」并退出。转请用户补一张背景图（回到分支 C），不强行生成。
- 若用户同时给了模板和图片，图片优先作背景，走换肤。

分支 C：用户只上传了一张背景图片

用内置骨架换肤，仅换背景：

C:/Users/chenw/.workbuddy/binaries/python/envs/default/Scripts/python.exe \
  "C:/Users/chenw/.workbuddy/skills/qingfeng-ppt/scripts/restyle_template.py" \
  --image "背景图.png" --output "更新后模板.pptx"

第 1 步收尾（分支 B/C 共用）

把 更新后模板.pptx 用 present_files 返回给用户，并提示：
> 使用此模板请上传生成PPT的文本或输入主题

然后进入第 2 步。

> 注：换肤只动视觉皮肤（母版背景图、主题配色、文字黑白），绝不改版式结构、占位符位置/数量、关键词框、分栏、文字框大小。14 个版式名称与顺序保持轻风骨架原样。
> 已知边界：亮度判定针对「整张母版背景」的平均明暗，若背景上存在深色卡片且文字落在其上，全局翻黑可能导致局部不可读——属模板设计细节，请用户在 PowerPoint 内微调。

第 2 步：生成大纲并请用户确认

目的：先提炼核心主题，再做有逻辑的结构设计，产出标准大纲供用户修改与确认。

2.1 两种入口（按第 1 步收尾后用户给的东西决定）

• 用户给了文本/文档 → 以该文本为素材提炼大纲（通读、归纳、给结论，不机械切片）。
• 用户给了主题（一句话/几个词） → 由大模型围绕主题自行设计大纲结构。

2.2 大纲设计方法论（务必遵守）

1. 通读、提主题：用一句话概括文档核心主题，作为全篇灵魂。
2. 定预算：20 分钟≈10–12 页；40 分钟≈15–18 页；60 分钟≈20–24 页。结构基数：封面(1)+目录(1)+各部分(每部分=1 节标题页+2~3 内容页)+结语(1)。
3. 拆部分（≥4）：把主题分解为 至少 4 个逻辑部分，每部分一页 [节标题]。
4. 每部分提炼 ≥2 个要点：每个要点=一页一级标题（#）。
5. 每个要点提炼 2–6 条内容：每条=一个二级标题（## 关键词）+一段核心内容（正文）。
   - 关键词是「精炼小标题」（2–8 字），不是单词。
   - 关键词数量随内容变化：模板栏数 两栏(2)/三栏(3)/四栏(4)/六栏(6)，整份 PPT 尽量覆盖 2、3、4、6 几种栏数制造疏密对比；无 5 栏版式，避免写 5 条。
6. 严格 md 契约（生成阶段唯一输入）：
   - # 页标题 → 标题框；## 关键词 → 关键词框；关键词下的正文 → 该关键词对应的「添加文本」框（一一配对）。
   - 内容页按关键词数自动选版式：2→两栏 / 3→三栏 / 4→四栏 / 5-6→六栏；也可在 # 页标题 末尾写 [版式名] 锁定。
7. 言而有物：每页只讲一件事，归纳提炼给结论。

2.3 产出与确认

1. 参考 references/OUTLINE_TEMPLATE.md 写出严格 md 大纲。
2. 运行结构校验器确认达标：
   bash C:/Users/chenw/.workbuddy/binaries/python/envs/default/Scripts/python.exe \ "C:/Users/chenw/.workbuddy/skills/qingfeng-ppt/scripts/validate_outline.py" 大纲.md
3. 用 Write 生成 .md 并 present_files 交给用户。
4. 同时返回模板的 14 个版式，方便用户为每页选择/锁定版式——运行：
   bash C:/Users/chenw/.workbuddy/binaries/python/envs/default/Scripts/python.exe \ "C:/Users/chenw/.workbuddy/skills/qingfeng-ppt/scripts/list_layouts.py" "更新后模板.pptx"
   把输出的版式清单（名称 + 适用场景）一并贴给用户，并说明可在 # 页标题 末尾写 [版式名] 锁定该页版式。
5. 明确回复下面这句（一字不改）：
   > 大纲已生成，可对大纲内容及每页采用的版式进行修改，修改后发指令"已确认"（本地）或上传修改后的大纲文件。再完成 第三步生成PPT。
6. 停下来，等用户确认 / 修改。 没确认绝不进第 3 步。

第 2.5 步：确认 / 修改大纲，再进第 3 步

• 用户发指令 "已确认"（本地聊天输入）→ 采用当前大纲，进入第 3 步。
• 用户上传了修改后的大纲文件 → 以该文件内容为准，进入第 3 步。
• 用户只口头改了部分内容（未上传文件、未说已确认）→ 按用户最新表述修订大纲，再回显并等待最终"已确认"。
• 无论哪种，第 3 步都只用最终确认版大纲 + 第 1 步得到的 TEMPLATE。

第 3 步：灌文字生成 PPT

目的：按确认后的 md 大纲把文字填进模板，产出成品。只倒文字，不改任何样式。

1. 把第 2 步确认过的 .md 交给脚本（用第 1 步得到的 TEMPLATE）：
   bash TEMPLATE="更新后模板.pptx" \ C:/Users/chenw/.workbuddy/binaries/python/envs/default/Scripts/python.exe \ "C:/Users/chenw/.workbuddy/skills/qingfeng-ppt/scripts/build_ppt.py" \ 大纲.md "生成结果.pptx"
   脚本会：清空模板示例页 → 按 # 分页、按 ## 识别关键词、[版式] 或关键词数定位版式 → 一级标题灌标题框、二级标题灌关键词框、正文灌对应「添加文本」框（一一配对）→ 图片/其他占位符原样留空 → 输出警告（如正文段数超正文框数）。全程不改颜色/字号/位置/换行。
2. 也可传 pages.json（兼容旧格式，字段 title/keywords/body/layout）。
3. 用 present_files 展示生成的 pptx，转述警告（提醒：颜色/字号调整均在 PowerPoint 里手动完成）。
4. 第 3 步完成后，先回复下面这句（一字不改）：
   > PPT已生成，为突出PPT的真实性，占位图片请自行补充。也可让我自动根据PPT内容生成图片。请回复"完成"或"生图"。

第 4 步（可选）：自动生图 或 收尾

依据用户上一步的回复分流：

分支一：用户回复「完成」

流程结束。把本次产生的所有产物及其存放地址列清楚交给用户，例如：
- 第 1 步更新后模板：更新后模板.pptx（用户指定 / 工作目录）
- 第 2 步大纲：大纲.md
- 第 3 步成品：生成结果.pptx
- （若走了第 4 步生图）第 4 步成品：生成结果_生图.pptx、图片缓存目录：生成结果_imgcache/

并提示：颜色 / 字号 / 图片微调均在 PowerPoint 内完成。

分支二：用户回复「生图」

调用 fill_images.py 按页面内容自动生成图片并插入所有图片占位符：

C:/Users/chenw/.workbuddy/binaries/python/envs/default/Scripts/python.exe \
  "C:/Users/chenw/.workbuddy/skills/qingfeng-ppt/scripts/fill_images.py" \
  "生成结果.pptx" --output "生成结果_生图.pptx"

脚本行为（agent 据此向用户说明）：
- 自动检测全部 PICTURE 占位符（含三栏 / 两栏等文字版式里夹带的图框）；每个图按位置排序与最近的关键词一一配对，用「页标题 + 关键词 + 其正文」作提示词（中文直出，强制无文字 / 无水印）。
- 出图引擎默认 agnes-image 2.1 flash（调用 ~/.workbuddy/skills/agnes-image）；不同用户 AGENT 环境可改 --generator（在脚本 GENERATORS 字典加对应引擎即可，如其它生图技能）。
- 按占位符宽高比自动选 1:1 / 16:9 / 4:3 / 3:2 …；图片按「提示词 + 尺寸 + 模型」哈希缓存到 生成结果_imgcache/，重跑免费且秒回。
- 单张失败不影响整体（该图留空 + 告警）。可加 --dry-run 先预览所有提示词再决定是否生图。
- 生成后用 present_files 展示 生成结果_生图.pptx，再回到「分支一」列出全部产物地址，流程结束。

注意事项

• 模板自带示例页，脚本自动删除，无需手工处理。
• 纯文本块超过 3 个：拆成多页（推荐）或合并；脚本兜底合并为单栏。
• blank(空白) 版式无任何原生占位符，生成后是干净空页。
• 不要在生成后再用 python-pptx 改颜色/背景——风格已由模板/换肤阶段决定。