若水PPT —— 柔性课件制作技能
> 上善若水。水善利万物而不争，处众人之所恶，故几于道。
> 本技能不硬性套模板，而是如水般随用户的真实需求变形：用户要求详细就详细，要求结构图就拉满图解，
> 要求批量就复用基线，要求微调就记录演进。一切以"做出用户满意的那一版"为准绳。
一、何时启用（触发条件）
- 最简触发：用户只要说 "若水PPT" 即可唤起本技能（推荐用法）。
- 用户给出教案 / 文档 / 书目 / 大纲，要求制作 PPT 课件或演示文稿
- 关键词命中：
做PPT、制作课件、教案转PPT、名著阅读PPT、系列课件、结构图课件 - 用户说：
"请按之前的方案做"、"继续做"、"尽可能生成结构图"、"先做一个，确认后再做其余" - 用户对已做课件提出字体 / 配图 / 结构图 / 风格 / 模板等迭代反馈
> 本技能依赖 ppt-master 引擎（SVG→PPTX 流水线），请确认其已安装；若未安装，先协助用户安装或加载 ppt-master。
二、核心工作流（柔性七步）
> 这不是 rigid pipeline，而是可裁剪的方法论。用户只要一页也可只走 5→6→7；系列任务走全七步。
| 步 | 名称 | 关键动作 | 是否需等用户 |
|---|---|---|---|
| 1 | 解析源材料 | docx→md（见工具链）；提取章节/案例/要点 | 否 |
| 2 | 初始化项目 | 建 projects/<name>_ppt169_YYYYMMDD/{svg_output,images,exports} |
否 |
| 3 | 确定设计规范 | 读基线（references/design_baseline.md）；新项目可走八项确认，复用项目直接套基线 | 首案例 BLOCKING |
| 4 | 生成 AI 插图 | ImageGen 逐张生成，立即语义化重命名，ls 核对 | 否 |
| 5 | 逐页手写 SVG | 每页一份 SVG，结构化图解贯穿（见弹药库） | 否 |
| 6 | 导出 PPTX | managed Python + svg_to_pptx.py -f ppt169 |
否 |
| 7 | 预览与交付 | ①check_delivery.py 体检（SVG/预览/PPTX 三项，须 0 致命）→ ②build_selfcontained_preview.py 生成自包含 preview.html（内联 SVG + 位图、无外部引用）→ ③present_files 呈现 |
否 |
导出命令（精确，勿改路径格式）：
cd "C:/Users/86180/.workbuddy/skills/ppt-master/scripts" && \
"C:/Users/86180/.workbuddy/binaries/python/envs/default/Scripts/python.exe" \
svg_to_pptx.py "<项目目录>" -o "<项目目录>/exports/<name>.pptx" -f ppt169
> ⚠️ 必须用 envs/default venv（.../envs/default/Scripts/python.exe，已装 python-pptx 1.0.2 / svglib / lxml / Pillow）。
> 裸 managed 解释器（versions/3.13.12/python.exe）是未装 pptx 的裸解释器，直接跑会 ModuleNotFoundError（见坑点15）。
> 缺依赖时：envs/default/Scripts/python.exe -m pip install python-pptx svglib reportlab Pillow。
导出前必做排版自检（见 §五 工具链 svg_quality_checker.py）：0 告警再导出。
三、设计规范基线（默认样板，可被用户覆盖）
> 完整版见 references/design_baseline.md。以下为快速默认值；用户逐案例调整时必须记录 px 演进（见 §六）。
- 画布：16:9（1280×720）
- 风格：古风模板 + 学术简洁（古典文化内容用古风装饰）
- 配色（60-30-10）：深藏青
#1A3C5E+ 宣纸白#F7F3ED+ 朱砂红#B8423A - 字体：楷体标题 × 黑体正文
- 字号基线（案例四定型，案例五~七沿用）：封面主标题 96px 粗体；封面白线下副标题 48px；页面标题 54px 粗体；卡片小标题 28–30px；注释/脚注 20–22px。
- 正文字号按页面空间分档（⭐ 唯一权威档位，见下条与
references/design_baseline.md §11）：疏页 34–44px / 中页 30–34px / 密页 27–30px（硬下限 27px=20号，不可破）/ 极密（>14 块）拆页或卡片化、绝不缩小字号。间距增大避免重叠。 - 古风装饰：顶部双线+菱形纹样、右上角回纹角花、左下角朱砂方印"读"
- 封面规范：书名（如《儒林外史》名著阅读）放左上角（红色竖线+楷体），主标题居中加大加粗，无"案例X"/"教学课件"字样
- 页脚规范：仅保留书名标识，去掉案例编号
- 图片：AI 生成水墨画风格（方案A：文人雅致），逐张生成
- 公式策略：文学内容用 text-only；若有数学内容则用标准 LaTeX 公式（ppt-master 的
latex_render.py），字号 ≥40px（建议 40–46px）
模板选择：按内容选型（⭐ 基本技能）
> 这是若水PPT的核心基本功：拿到任意内容，先判"时代属性"定视觉风格，再判"内容结构"定页布局。
> 如水随形——内容什么样，模板就什么样。完整决策表与冲突处理见 references/template_guide.md，生成每页前过一遍其「自检清单」。
两步法：
1. 判时代属性 → 定视觉风格：古典文学/历史人物 → 古风模板（双线菱形纹+回纹角花+朱砂"读"印）；现代/通用/理科 → 学术简洁风；数据密集 → 数据图表风。
2. 判内容结构 → 定页布局 + 图解：叙述→要点卡片；双主体→双栏/对比表/韦恩；流程因果→流程图/概念图；成长变化→折线图；群像关系→星图/双气泡；纠错→红叉错误表+绿勾正确表；总结→金句留白页。
铁律：视觉风格全篇统一，但页布局可混用；封面永远用主视觉（背景大图+大标题），不套内容页模板；用户指定风格优先级最高。
理科内容：实验 / 公式 / 图表（⭐ 基本技能）
> 理科课件以"准确 + 清晰 + 可复现"为魂，信息呈现尽可能结构化。完整规范见 references/science_content.md，生成理科页前过一遍其「自检清单」。
三项硬标准：
- 公式：用 ppt-master latex_render.py 渲染为标准 LaTeX PNG，禁止文字冒充；独立成行居中、等号对齐、字号 ≥40px（建议 40–46px）。
- 图表：柱状/折线/饼/散点按需选；必备标题+轴标签+单位+图例+弱化网格；数据墨水比高；原始数据用表、趋势用图双呈现。
- 实验：拆为标准结构（目的→原理→器材→步骤流程图→装置矢量图→数据表→图表→结论对照表→误差分析）；装置图用 SVG 矢量手绘标注，避免模糊位图。
根据页面可用空间匹配字号（⭐ 硬约束，权威档位见 references/design_baseline.md §11）：以"可用空间"（页面净面积 − 标题/页脚/装饰固定区 − 图表图片占位）和"信息密度"（文本块数）为决策输入，按档匹配——疏页（≤4 块/大留白）34–44px、中页（5–8 块）30–34px、密页（9–14 块）27–30px、极密（>14 块）改用③拆多页/②卡片化解决，绝不把正文缩到硬下限 20 号（≈27px）以下。🔴正文硬性下限 = 20 号（≈27px）：任何页正文都不得低于此值（用户明确要求"正文字体 ≥ 20 号"）。公式图注独立设字号（≥正文 1.3 倍，约 40–46px）以"后排可读"为准。空间不足三级应对：①精简文字 ②卡片化/分栏 ③拆多页。优先级：可读 > 不重叠 > 美观 > 字号统一。
插图与知识准确性（⭐ 硬约束，详见 references/design_baseline.md §11.5）：AI 生成或选用的插图/示意图/数据图必须准确对应文案——机型·型号·对象、概念、数据、术语须与源文档一致，严禁张冠李戴或用"看起来像"的近似物糊弄。生成前须从源文档（含内嵌图片层）确认对象的具体型号与可辨识特征，prompt 据此精确描述；若源文档未指明具体型号，则用中性、通用的标准形象，不得臆造具名型号外观。知识必须严谨、准确。
文学类 · 诗意配图模板（⭐ 基本技能）
> 文学类课件（诗词鉴赏 / 散文品读 / 名著导读 / 文言教学 / 语文主张）不应只有一种模板，须有诗意、不单调。
> 完整规范与 5 套风格规格见 references/literary_templates.md；可复用骨架见 templates/literary/<style>/（5 风格 × 5 版式 = 25 个 SVG，由 generate.py 生成）。
五套风格（风格统一、辨识度各异）：
1. 水墨江南——青灰水色、小桥流水纹样，适配婉约/水乡散文
2. 古典诗词——赭金卷轴、明月云纹，适配唐诗宋词名篇
3. 山水意境——石青远山、孤舟飞鸟，适配田园隐逸
4. 花鸟写意——胭脂梅枝、雀鸟墨色，适配咏物托志
5. 四季流转——春绿夏青秋枫冬青、四时环纹，适配时令专题
每套必备 5 类版式：封面页 / 章节页 / 内容页 / 引用页 / 结尾页（坐标规格见规范文档 §2）。
传统美学四要素（每页取 2–3）：留白（边距≥12%）· 题跋（竖排小字 writing-mode=tb）· 印章（朱砂方印 1–2 字）· 卷轴边框（内缩双线框+四角菱形）。
字体（衬线/书法风）：标题诗句用 KaiTi,STKaiti,楷体,SimSun,serif；正文出处用 FangSong,STFangsong,仿宋,SimSun,serif；font-family 值内不加引号不加空格（防引号闭合 bug）。
诗句排版：居中或竖排，楷体 ≥40px（封面/引用可 64px），行距 1.6–2.0；出处右对齐仿宋 26–30px「—— 作者《篇名》」。
配图：封面/章节用 AI 写意诗意图（各风格 img_prompt 见规范 §3）；内容/引用页用矢量传统纹样点缀，不依赖位图、清晰可编辑。
选择：用户指定优先；未指定按主题匹配（见规范 §4）；多章节推荐全篇统一一套最协调，或四季流转按章节换季相。
交付格式：WPS / PowerPoint 双兼容（⭐ 基本技能）
> 课件最终必须是一份任何主流演示软件都能打开的 .pptx。这是交付底线，不是加分项。
标准与兼容要点：
- 格式：一律导出标准 OOXML .pptx（python-pptx / pptxgenjs 原生产物），WPS 与 PowerPoint 均原生兼容，无需格式转换。
- 最大兼容做法：SVG→PPTX 把每页转成"原生形状 + 文本 + 图片"，不用 SmartArt、不用程序专属特效，最不容易在任一软件里打不开或错版。
- 字体：只用系统通用字体（Microsoft YaHei / SimHei / 黑体 / 宋体 / 楷体）；避免冷门字体——目标机未装会被替换导致版式漂移；公式/代码用等宽 Courier New。
- 导出后强制校验（防"打不开"）：用 zipfile.testzip() 验 zip 完整性 + 逐 part xml.etree.ElementTree 解析验 XML 合法；任一报错即回查 SVG 源（最常见根因：font-family 值误用单引号闭合，见坑点18）。校验通过才 present_files。
- 兜底交付：同时生成 自包含 preview.html（SVG 内联进单文件、无任何外部引用，浏览器/内置面板直接开，无需任何 PPT 软件）；用户本机无 PowerPoint/WPS 时，可转 PDF（环境有 LibreOffice/WPS 时另存）。
- 运行环境：用 managed Python 的 envs/default venv 跑 svg_to_pptx.py（见 §二 导出命令）；裸 managed 解释器未装 pptx 会 ModuleNotFoundError（坑点15）。仅当该 venv 也不可用才退守 Node.js + pptxgenjs（LAYOUT_WIDE + writeFile）。
四、结构化图解弹药库（核心交付标准，非可选增强）
> 用户明确"尽可能生成结构图""结构化图解内容"时，把图解密度拉满。下表按内容选型。
| 图解类型 | 适用场景 | 本项目中出处 |
|---|---|---|
| 对比表 / 维度总表 | 多主体多维度对照 | 案例六五维度对比表、案例七解读维度总表 |
| 双栏对照 | 两种路径/人物并置 | 案例五两种突围、案例六双栏详解 |
| 韦恩同异图 | 求同存异 | 案例六心灵分身同异 |
| 双气泡图 | 两人特征+共同点 | 案例五撕掉标签 |
| 概念图 / 流程图 | 机制、因果、步骤 | 案例六精神家园流程、案例七理想社会蓝图 |
| 折线图 / 双曲线 | 成长、变化曲线 | 案例四成长曲线 |
| 三元链 ×N | A↔B↔C 有机统一 | 案例七才艺↔性格↔命运 |
| 探究星图 | 一核心+多卫星人物 | 案例七王冕为中心7星 |
| 人格弧线图 | 人物成长轨迹 | 案例七理想人格弧线 |
| 卡片矩阵 / 三卡 | 分点罗列、脑科学原理 | 各案例脑科学三卡 |
| 纠错对比表 | 正误对照（红叉/绿勾） | 案例七张冠李戴速记表 |
五、工具链速查
| 工具 | 用法 |
|---|---|
| 文档提取 | python tools/docx_extract.py <file.docx>（stdlib zipfile+ElementTree，无 mammoth 依赖，自动识别标题样式与表格）；或 ppt-master scripts/source_to_md/doc_to_md.py |
| AI 插图 | ToolSearch("ImageGen") → DeferExecuteTool，参数 prompt(中文水墨画描述)、output_dir、quality:"high"、size:"1536x1024"|"1024x1024" |
| SVG→PPTX | envs/default venv + svg_to_pptx.py（见 §二命令；裸 managed Python 缺 pptx） |
| 排版自检 | ppt-master/scripts/svg_quality_checker.py（envs/default venv，传入 svg_output 目录）：查文本重叠/越界/字号<20 |
| 预览 | python tools/build_selfcontained_preview.py <project_dir> --title "标题" [--out <路径>] → 生成 svg_output/preview.html：自包含单文件（内联 SVG + 内联位图 base64，无任何外部引用），浏览器/内置面板直接打开，规避"网页版看不了"。目录容错：无 svg_output 子目录时按平铺目录读取；历史项目根目录若已有旧 preview.html，用 --out 一并覆盖 |
| 交付前体检 | python tools/check_delivery.py <项目或工作区目录> [--fix-preview]：①SVG XML 合法性 ②font-family 单引号闭合 bug（坑点18）③preview.html 自包含性（坑点20）④PPTX zip+XML 完整性（双兼容）。退出码 0 才允许交付；加 --fix-preview 可自动重建非自包含预览 |
| 技能文档体检 | python tools/check_consistency.py [skill_dir]：坑点条数四处同步、编号连续/集合一致、§六 条数、frontmatter 发布元数据、工具链完整性。改完 SKILL/pitfalls 后必跑；打包前置关卡，退出码 0 才允许打包（见坑点28） |
| 打包发布 | python mk_skill_package.py / --full（输出 ruoshui-ppt_发布版_v{version}_{date}.zip，自动读 frontmatter 版本号命名，内置上述两项体检） |
| 交付 | present_files 呈现 pptx + preview.html |
AI 插图铁律（避开文件名冲突 + 429）：
1. 逐张生成，绝不并行
2. 生成后立即 mv 为语义名（cover_bg.png、lu_jiwa.png…）
3. 生成后 ls -la *.png 核对数量，缺失即补
4. 每案例图片控制在 2–3 张，降低 429 概率
六、柔性响应规则（关键：灵活应对用户要求）
> 这是"若水"之魂。按顺序匹配用户意图，不阻塞、不硬推、不重复确认。
> 注：本节的"规则"是对 §三 各基本功的场景化索引——具体数值/标准以 §三 与各 references/*.md 为唯一权威，本节不再复述全套数值，避免漂移。
- 要求模糊 / 没回答确认题 → 用 §三 合理默认先出一版，再让用户评价（切勿因"信息不全"拖延）。
- "按之前的方案做" / "继续做" → 先读项目
MEMORY.md与~/.workbuddy/MEMORY.md的设计基线，直接复用，不再走八项确认。 - 逐案例微调字体 → 记录精确 px 演进（如封面副标题 44→48→52→64；正文 28-32→30-34），后续案例直接套用最新基线。
- "尽可能生成结构图" → 把 §四 弹药库密度拉满，每页至少一种图解。
- 跳过 AskUserQuestion → 不纠缠，用默认推进（见坑点11）。
- 429 配额中断 → 如实告知"额度耗尽，任务已安全保留"，暂停等"继续"，从中断点续做，不重来（见坑点14）。
- "先做一个，确认后再做其余" → 首案例作样板，确认后固化基线进项目记忆，其余批量复用（见坑点7）。
- 用户推翻某规范（如"改成古风模板""去掉案例编号"）→ 立即改样板并回写基线，后续全部跟随新规范。
- 矛盾要求（大字体 vs 不重叠）→ 优先"不重叠"，用增大间距/分页/缩句满足两者。
- 按内容选模板 → 用
references/template_guide.md两步法（判时代属性定风格、判内容结构定布局）；视觉风格全篇统一、页布局混用、封面用主视觉、用户指定优先。 - 理科内容 → 用
references/science_content.md：公式 LaTeX 渲染（≥40px、等号对齐、禁文字冒充）；图表表+图双呈现；实验拆标准结构（步骤流程图/装置矢量图/数据表/结论对照）。 - 信息尽可能结构化 → 默认用卡片/表格/流程图/对比/星图呈现，避免大段纯文字；高密度内容先拆结构再排版（见
references/design_baseline.md §10）。 - 根据空间大小匹配字号 → 见 §三「理科内容」段与
references/design_baseline.md §11的唯一权威档位：疏页 34–44px / 中页 30–34px / 密页 27–30px（硬下限 27px=20号）/ 极密拆页或卡片化；公式图注独立设字号（≥正文1.3倍）；空间不足依次 精简→卡片化→分页；优先级 可读 > 不重叠 > 美观 > 字号统一。 - 交付双兼容 .pptx → 见 §三「交付格式」段：导出标准 OOXML + 强制校验（zip+XML）+ 自包含 preview.html 兜底，确保 WPS/PowerPoint 都能开。
- 插图与知识准确性 → 见 §三「插图与知识准确性」段与
references/design_baseline.md §11.5：AI 图须精确对应文案对象（型号·概念·数据），严禁张冠李戴；生成前从源文档（含内嵌图）确认对象特征，未指明型号用中性通用形象。 - 文学类·诗意配图模板 → 见 §三「文学类·诗意配图模板」段与
references/literary_templates.md：五套风格×五版式，复制templates/literary/<style>/骨架填字，避免"只有一种模板太单调"。 - "源文档改了，请同步修改课件" → 不凭印象改：先
doc_to_md提新版，用difflib.unified_diff(旧md, 新md)出逐行差异清单，再用特征字符串grep -c双向核验哪版是修订版（防读反 diff）；按差异清单映射到具体页，只改变动项；新版新增整节→新增整页并重排后续文件编号与页脚页码；改完grep -l扫旧版残留词确认清扫干净；导出用_v2/_v3新名避开被占用的旧文件（详见坑点25）。
七、坑点速查（28 条索引）
> 详细现象+解决方案见 references/pitfalls.md（与本节 1–27 一一对应）。长时记忆 ~/.workbuddy/MEMORY.md 亦存全文。
> 读书会与沙龙类（若水PPT 亦适用）坑点见 pitfalls.md 附录 A，不占 1–28 编号。
| # | 坑点 | 一句话解法 |
|---|---|---|
| 1 | Glob 不支持 Windows 跨盘符 | 用 find /d -maxdepth 3 -iname |
| 2 | skills-security-check 未装时审计 | 手动 Grep 危险模式，出 P0/P1/P2 报告 |
| 3 | pip 路径 Git Bash 格式 | Windows 程序用 C:/Users/... |
| 4 | pip 完整安装耗时阻塞 | 只装核心包 + 后台装完整依赖 |
| 5 | AI 图并行文件名冲突 | 逐张生成 + 立即 mv 语义名 + ls 核对 |
| 6 | ppt-master 八项确认 BLOCKING | 捆绑推荐集 + AskUserQuestion，确认后再生成 |
| 7 | 用户"先样板后批量"模式 | 首案例固化基线，其余复用 |
| 8 | python-pptx 在裸解释器缺依赖 | 用 envs/default venv（坑点15）；原"切 Node.js"方案已作废 |
| 9 | PowerShell 5.1 不支持 && |
用 ; 或换行 |
| 10 | PowerShell 带空格路径 exe 参数异常 | 用 & "path" args |
| 11 | AskUserQuestion 被跳过 | 用合理默认先出第一版 |
| 12 | 临时脚本/node_modules 污染工作目录 | 临时文件放系统 temp |
| 13 | run_in_background 输出检查错用 Get-Job | 用 TaskOutput + task_id |
| 14 | AI 图 429 配额中断 | 任务不丢，告知暂停，等"继续"续做 |
| 15 | 修正坑点8 —— svg_to_pptx 用 envs/default venv | 用 envs/default venv（非裸 versions/.../python.exe，后者未装 pptx）；仅 venv 也不可用才退守 Node.js |
| 16 | 用户强偏好结构化图解 | 列为默认交付标准 + 弹药库选型 |
| 17 | 多案例基线漂移 | 样板+基线管理，记录 px 演进 |
| 18 | PPTX 打不开 / 双兼容 | 标准 OOXML + 强制校验（zip+XML）；最常见根因：font-family 值误用单引号闭合致 XML 非法，写 SVG 时 font-family 用双引号且不加空格不夹引号；preview.html 兜底；字体用系统通用 |
| 19 | 插图张冠李戴 / 知识不严谨 | 生成前从源文档(含内嵌图)确认对象型号特征，prompt精确描述；未指明则用中性通用形象 |
| 20 | 文学课件只有一种模板太单调 | 用诗意配图模板体系：5 风格×5版式，四要素+衬线书法字体+矢量纹样，复制 templates/literary/<style>/ 骨架 |
| 21 | 封面与主题不相关 | 封面图 prompt 必须写清主题意象（如"选课岔路—深耕的路—作业灯火"），禁用泛用水乡/山水图；封面可放团扇圆形（clipPath）主视觉 |
| 22 | 竖排文本（writing-mode=tb）溢出 | y 是起点且沿 y 向下延伸 字数×字号；按容器高度反推起点（≈ top+12），别把 y 当居中 |
| 23 | 右下印章（1104,596）压字 | 居中长行右端易撞印章：居中行 ≤ 约30字(28px)，或整行上移 |
| 24 | 密集卡片文字溢出卡片 | 卡片内宽度 ÷ 字号 = 每行字数上限（如 330px ÷ 22px ≈ 15 字），超了就缩句不缩字号 |
| 25 | 源文档修订后同步课件改错方向 | 先 difflib.unified_diff(旧md, 新md) 出差异清单，再 grep -c 特征字符串双向核验哪版更新；只改变动项；新增整节→新增整页并重排后续文件编号+页脚页码；改完 grep -l 扫旧版残留词 |
| 26 | 存量预览"过期"（工具修好≠产物修好） | 历史 preview.html 仍是外部引用，打开照样空白。改完工具必须回扫存量：check_delivery.py <workspace> --fix-preview；校验正则须覆盖单/双引号并排除 data: 前缀；根目录旧预览用 --out 一并覆盖 |
| 27 | <g opacity> 被官方自检判 ERROR |
ppt-master svg_quality_checker 禁止组元素带 opacity（一整批页会 Failed）。装饰的 stroke/fill/opacity 逐条写在子元素上，印章等组合不套 <g>；用生成器脚本时改一处即全批恢复 |
| 28 | 坑点条数四处不同步（文档计数漂移） | 新增坑点只改了 pitfalls.md，忘了 SKILL.md §七标题/索引行、relationship_to_pptmaster.md 计数、pitfalls 标题——历史曾"标题写 20 条实列 25 条"。每次改完必跑 tools/check_consistency.py，退出码 0 才允许打包（已内置于 mk_skill_package.py 前置关卡） |
八、交付物与记忆管理
每案例交付物：
- svg_output/01_cover.svg … 14_conclusion.svg（14 页，可据内容增减）
- exports/<name>.pptx
- svg_output/preview.html（自包含，由 tools/build_selfcontained_preview.py 生成）
- images/（AI 插图）
记忆写入：
- 项目进度/规范 → 项目级 .workbuddy/memory/MEMORY.md 与 YYYY-MM-DD.md
- 跨项目经验/坑点/偏好 → ~/.workbuddy/MEMORY.md（长时）
- 设计规范基线 px 演进 → 项目记忆，避免重复确认
完成标志：svg_to_pptx.py 输出 X/X 页成功、0 失败；且对导出 pptx 跑 zip 完整性 + 各 part XML 合法性校验通过；present_files 已呈现 pptx + 自包含 preview.html（双兼容兜底）。
