zhouwei713 / luobo-ppt

萝卜 PPT（luobo-ppt）

两条路线共用一套设计引擎。生成是"写出内容再设计"，美化是"抽出原稿内容再设计"，从版式规划开始完全一样。

三份中间文件串起全流程，脚本负责确定性的活，Claude 负责理解内容和审美判断。

下文 $S 指本 skill 的 scripts 目录，$W 指本次的工作目录（如 ./ppt_work）。Windows 上把 python3 换成 python。

开工前

1. 判断路线

   • 用户给了 .pptx，要换个好看的样子 → 路线 A 美化
   • 给的是题目、文章、口播稿、大纲或其他素材，要做成 PPT → 路线 B 生成
   • 给了 .pptx 但要重写内容、调整结构 → 路线 B，把 pptx 当素材读

2. 环境自检，之前通过的话一秒内结束，否则自动补装依赖。退出码非 0 就把建议告诉用户并停下；只缺推荐组件（如 LibreOffice）可以继续，pipeline 会改用 render_lite.py 按排版数据直接画近似预览，排版、配色、溢出照样能看，交付时说明预览是近似图。想跳过 LibreOffice 提速也可以加 --lite。
   `bash
   python3 $S/setup_check.py --quick --install
   `

3. 生图状态 python3 $S/make_assets.py $W --status，用一句话告诉用户接了哪家模型，或者走程序化插画。配置方法见 references/imagegen_config.md。
4. 一次提问问清路线需要的选择，其余用默认值。用户说"直接做""不用问"或者不在场时，全部用默认值，交付时列出做过的选择。

5. 快速模式：用户说"快速模式""别问了""赶时间"时，跳过风格卡、大纲、设计规格的确认，五维自评只修一轮"要修"，"顺手改"写进交付说明不动手。12 页左右的稿子，正常 15 到 25 分钟，快速模式 10 分钟上下；时间大头在转写文字和看图，脚本本身只要一两分钟。

   • 美化：力度 light / standard / full（默认 full），是否允许精修文字（默认不允许）
   • 生成：用途、受众、时长、有无参考图、要不要口播备注，默认值见 references/generate.md

路线 A 美化

1. 解析原稿 python3 $S/extract_deck.py 原稿.pptx $W，然后看 source_png/sheet.png。脚本会修复 LibreOffice 打不开的 zip，也能读出藏在 descr 属性里的口播备注。
2. 读参考图 python3 $S/extract_style.py 参考图.png $W，再亲自看图，按 references/style_extraction.md 写 $W/style.json，然后 python3 $S/style_card.py $W 出风格卡。用户在场就发风格卡确认。
3. 整理 deck.json，按 references/deck_schema.md 从 deck.draft.json 转写。文字逐字复制，局部加粗写成 **片段**；图片里的文字重建成 diagram 等原生结构；notes 原样带上；写好 meta.anchor 视觉锚点。原稿页面上的小标签（"01 · 概览"这类章节胶带）写进该页的 kicker，条目自带的编号（01、02）写进条目的 num，这样换任何列表符号都不会丢字。原稿里用公式编辑器打的公式，解析时会自动转成普通文字公式（如 V′(x) = (a−2x)(a−6x)），照常逐字转写；公式多的讲解页用 explain 页型。SVG 图会顺手转一份 PNG（raw.json 里的 png 字段），版式里用 PNG。logo、"AI 生成"标识这类小图写进 stamps 原样保留。原稿里的软件截图（media/ 下的图片）用 screenshot 或 screenshots 页型，截图会放进统一的窗口外框，讲解点可以用 at 打在截图上。
4. 接着走下面的"版式、出图与检查"。

路线 B 生成

开始前先读 references/generate.md，里面有故事线、结论式标题、密度、口播备注和页型选择的全部规则。

1. 分析素材 python3 $S/analyze_source.py $W --file 文章.md（只有题目用 --topic "…"，可加 --minutes 3）。只有题目或需要补充事实时，先搜索查证，查不到的不写。
2. 写 deck.json：先定故事线，再按"内容形状决定页型"逐页写，标题写结论，屏幕放关键词，完整的话放 notes。分了章节的稿子在封面后放一页 toc 目录（不写 items 会自动列章节），卡片页连得多了插一页 question 大问句或 big_quote 大引文。工具教程类的素材有截图时，一张图配几个操作点用 screenshot，几张图走流程用 screenshots。除了常规的卡片、步骤、对比，还有时间线、漏斗、中心辐射、2x2 矩阵、原生表格、原生图表和 SWOT/PEST/五力/商业画布，拿不准装不装得下就 python3 $S/layout_info.py <版式名> 查容量和示例。
3. 检查大纲 python3 $S/outline_check.py $W，修到没有 ERROR，把 outline.md 里的"只读标题"发给用户确认。
4. 定风格：有参考图走路线 A 第 2 步；没有就 python3 $S/style_previews.py $W --auto 出三张样张（用户自己的封面和内容页），发 previews/sheet.png 让用户挑，再 --apply <id>。预设在 references/styles/，共十四套，每套的硬规则排版时要遵守。要在会议室投影的，在 meta 里写 "projection": true，字号下限会抬高。
5. 接着走下面的"版式、出图与检查"。

版式、出图与检查（两条路线共用）

1. 版式规划 python3 $S/plan_deck.py $W --level full（有生图模型时加 --sheets，一张大图切出几张小插画，风格更统一也更省）。
   重跑时内容没变的页会保留原来的规划（包括手改过的版式和插画提示词），要全部重排加 --reset。
   审 plan.json：版式贴不贴内容（references/layouts.md）、图标达不达意（references/icons.md）、插画提示词具不具体（references/image_prompts.md）。内容超出版式容量时脚本会自动换版式，并写进 design_spec.md 的"容量提醒"，出图前先处理掉。
   把生成的 design_spec.md 发给用户确认后再出图，出图最花钱。快速模式跳过确认。

2. 出图、组装、自检一条命令：
   `bash
   python3 $S/pipeline.py $W
   `
   依次运行 makeassets（插画、背景、装饰，AI 提示词先落盘到 prompts/）、builddeck、render、qacheck、comparesheet、review。

   检查	级别	处理
   美化时原稿文字缺失或被改；生成时 deck.json 的文字没上页面	ERROR	对照原文或 deck.json 修正
   文字溢出、文本框重叠、文字越过底线（压到胶囊条或页脚）	ERROR	换版式、拆页，或用 free 版式手工摆
   强调色一页超过 3 处或面积超过 8%	WARN	只留一处强调
   文字压插画、对比度不足、出界、正文过小	WARN	看图判断，多数要修
   新增的页眉、页码、步骤编号	INFO	正常

3. 五维自评：看 out/sheet.png 和逐页 PNG，对照 out/review.md 里脚本数出的证据，按 references/critique.md 给统一、层级、细节、传达、节奏各打 0 到 10 分，写出保留、要修、顺手改三张清单。"要修"的交付前改掉，改完只重跑受影响的步骤，最多三轮。

交付

• out/beautified.pptx，文件名用 原名_美化版.pptx 或 主题.pptx
• 美化附 out/compare.png 前后对比图，生成附 out/sheet.png 全览图
• 一句话报五维自评的分数和最弱的一项
• 一两句话说明风格、插画来源（哪家模型或程序化插画）、字体，美化时说明有无精修文字，生成时说明哪些内容需要用户再核实
• 用户连接了本地文件夹时，写回素材所在的位置

硬规则

通用

1. 所有文字都是可编辑文本框，卡片、胶囊条、分隔线用原生形状，只有背景、插画、图标、笔刷是图片。
2. 参考图只用来抽风格，不裁切、不贴进 PPT。
3. AI 插画里不出现文字（产品首字母这种图形化字母除外），提示词始终带负面约束。
4. 程序化插画是兜底方案，交付时如实说明，不说成 AI 生成。
5. 做稿子的过程中不改 skill 自己的文件。遇到 skill 的问题，绕过去完成交付，再把问题写进交付说明，由用户决定要不要改 skill。

美化

1. 默认不改任何文字；用户允许精修时，改动逐条列给用户过目。
2. 页序和页数与原稿一致，备注保留。

生成

1. 数据和事实只用素材里的或查证过的，标上 source；查不到就不写，绝不编数字。图表数据改了，标题和 insights 的结论跟着重写。
2. 大纲（只读标题）经用户确认后再做设计；风格和设计规格同理，快速模式除外。

局部修改

• 单页重做：改 plan.json 里那一页的 layout、icons，或改 prompts/hero_NN.md，再 make_assets.py $W --only hero_NN --force 和 pipeline.py $W
• 换风格：换 style.json（参考图或 style_previews.py --apply），插画 --force 重出，deck.json 和 plan.json 可以沿用
• 特殊页面：该页 layout 设为 free，在 plan 里直接写 elements（格式见 references/layouts.md）
• 只要轻度美化：plan_deck.py $W --level light，不出插画

常见问题

• soffice 转换失败：渲染只影响预览，不影响交付文件；先确认 extract_deck.py 产出的 source.pptx 能打开
• 预览字体和用户电脑不同：预览用思源黑体代替微软雅黑，版式留了余量，见 references/fonts.md
• 生图失败：自动换程序化插画，assets/manifest.json 记录错误，交付时说明哪几页是兜底图

文件索引