Qiaomu PPT

制作真正可用的演示文稿。除非用户明确要求只要 HTML、只看风格预览或只要策划材料，否则默认走中文优先、资料有据、面向可编辑 PPTX 的生产流程。

Copyright (c) 向阳乔木 X: https://x.com/vista8 GitHub: https://github.com/joeseesun/ License: AGPL-3.0-only

核心契约

• 把 SKILL.md 当作入口路由器，而不是完整手册。只读取当前路线和风险真正需要的参考文件。
• 面向用户的说明、方案、问题和结论默认使用准确中文。英文只保留在文件名、脚本名、字段名、格式名、产品名或必须稳定匹配的机器状态中，例如 route、final_delivery、research_dossier.md、design_proposal.md、PPTX、HTML deck、missing evidence。
• 不要把用户项目、来源抓取、预览或导出文件写进 skill 目录。默认写到用户下载目录的 ~/Downloads/Qiaomu PPT/<date>-<slug>/；只有用户、项目或调用方明确指定时，才写到其他位置。每次任务一个可理解的文件夹名，优先用日期和主题短 slug。
• 用户提到 PPT、PowerPoint、PPTX、课件、可编辑或二次修改时，默认交付可编辑 PPTX。整页图片式 PPTX 只能作为明确标注的等效预览、社交图片导出，或用户批准的不可编辑草稿。
• NotebookLM、Keynote、HTML 动效和社媒图片式 deck 是可选路线包。只有用户明确点名、接受对应取舍，或 plan_run.py 选中对应路线时才读取和执行；默认可编辑 PPTX 不因这些边缘能力增加步骤。
• NotebookLM 原生路线下，如果用户没有明确指定视觉风格，方案阶段必须给 3-5 个按主题挑选的风格建议和一个推荐默认值。建议要偏可读、清爽、能把源内容视觉化但不抢内容；每项给一行可直接填入 NotebookLM 描述框的短 prompt。不要静默套用 data/cinematic/consulting，也不要给长 production rulebook。
• NotebookLM 原生路线是直传来源路线，不是 qiaomu 可编辑 PPTX 规划路线。用户明确要“用 NotebookLM 生成/上传到 NotebookLM/NotebookLM 原生 PPT”时，把完整来源文件、URL、YouTube 或 NotebookLM research 结果直接交给 NotebookLM；不要先跑 source_cards.py、outline_from_source_cards.py、content_preflight.py 或四页预览去压缩长文。默认生成现场演示用的简化 deck，使用 --format presenter --length short；只有用户明确要讲义、详细阅读版、资料汇编或 standalone handout 时，才使用 --format detailed 或 --length default。NotebookLM 的风格 prompt、preset 描述、页数/可读性要求和工具流程说明都是内部生成指令，不能作为可见标题、副标题、标签或脚注；观众可见文案只能来自来源内容中的判断、概念、证据锚点和行动结论。只有在后续要改做 qiaomu 可编辑 PPTX 时，才另开 source card / slide plan 流程。
• 在 Codex 或宿主生图可用时，推荐方案、预览和正式 PPT 默认必须使用生图作为整页或主区域主视觉。PPT/HTML 前景只承载可编辑标题、介绍文本、结论、短标签、讲解路径、必要标注、真实来源证据框和少量版面控件；不要用 SVG/形状手画人物、骨架、产品、场景、复杂图解或氛围画面作为主视觉，除非用户明确要求这种风格，或生图不可用并已标为降级。
• final/professional/release deck 需要真实关键页主视觉和可追溯证据。Codex 原生 image_gen 可用时优先使用并记录 generator: "codex-native-image_gen"；非 Codex 或宿主生图不可用时，可使用已配置且验证过的图像 provider，但必须记录 provider、输出文件、尺寸、使用页和 missing evidence 边界。只有用户明确要求草稿、离线冒烟测试或禁止生图时，才能用 SVG/形状/程序化背景作为降级。
• 用户没有指定视觉风格时，默认不是自由发挥，而是必须选择最适合主题、受众、证据类型和使用场景的风格。先判断内容域需要的可信度、现场感、技术密度、情绪张力和阅读方式，再定视觉语气；把推荐风格、备选风格、明确避开的风格和避开理由写入 design_proposal.md、style_direction.json/md 或等价 sidecar。风格好看但削弱内容可信度、专业感或叙事目标时，视为失败。
• 美观不是固定模板、固定配色或某个题材禁忌清单。默认审美决策必须按 主题内容域 -> 受众/场合 -> 证据/媒体类型 -> 情绪温度 -> 版式节奏 -> 图像语言 推导，并在方案和 sidecar 中记录。任何主题都要避免“上一任务遗留风格”“好看但不合题”“图片和文字各讲各的”“连续页面同一结构指纹”。
• 下载/提取的资料图可以使用，而且应优先用于证据页、截图页、对比页和出处明确的图表页；但资料图不能替代真实生图。最终质量的长 deck 至少关键页面必须有真实生图：封面/开场主论点、一个主要证明或框架页、一个流程/架构/转折页、结尾页；20 页左右默认目标不少于 4 张真实生图。其它页面可以使用同一视觉系统下的相似背景，但背景必须聚焦本页内容表达，不能只是占位纹理、抽象卡片或本地源资料衍生图。
• 使用生图不等于完成设计。媒体页必须把主视觉当作可读论证画布，声明文字安全区、焦点、裁切、标注目标和融合动作；不要把图片和一块大黑/白文字栏并排，当成默认的图文排版。
• 图片必须和本页内容融合，而不是贴图。每张生成图或来源图都要绑定本页 audience_takeaway、证明对象、焦点区域、可编辑前景、标注目标、文字安全区和一个明确 integration_move；如果去掉标题后图片可以套到任何主题，或图片只能当装饰背景，说明图像导演失败，必须重写 prompt、换图、重裁或重排，而不是继续生成 PPT。
• 可见文案必须先从观众视角生成，而不是从制作方法、版式合同、图片资产说明或检查报告里摘取。把“观众会读到/听到的话”作为独立内容层，内部工作流只写入 sidecar、备注或 QA 报告。
• 不要把上游演示文稿 skill 当运行时依赖。上游研究只作为参考证据；实际执行使用本包的脚本、数据、参考文档和乔木自有契约。
• 不要把第三方模板、完整风格包、长提示词或受版权保护的页面设计复制进生成结果。
• 缺工具、缺凭证、缺来源权限、缺图片生成、缺 Office/Keynote/导出验证时，必须记录为缺失证据；机器状态仍使用 missing evidence，不要说成已经完成。

默认轻量路径

1. 先运行或等价执行 python3 <skill>/scripts/qiaomu_ppt.py plan --prompt "<用户请求>"，得到路线卡、确认边界、必读参考和当前档位检查。
2. 默认只走核心链路：plan -> prepare -> proposal/preview -> build -> check。不要因为 skill 内有 NotebookLM、Keynote、HTML motion、style catalog 或 benchmark 研究资产，就自动激活它们。
3. 风格库通过 data/style_packs.json 分层。默认只用 core、magazine、ppt_master_cases；32kw_bento、完整案例索引、NotebookLM 风格和 HTML motion 是可选 pack，只有用户点名、路线命中或排障需要时再打开。
4. 面向用户只暴露少量可读产物：方案/逐页计划、预览图或最终导出、交付检查.md。调试 sidecar、内部报告和长 JSON 默认留在项目目录，不在聊天里铺开。
5. 只有当前路线、失败排障或用户追问需要时，才打开对应 reference。SKILL.md 负责决策边界，深方法放在 references/data/scripts。
6. 最终是否可交付以 final_status.json 和 交付检查.md 为单一入口；benchmark、repair plan 和 project check 都是它的输入，不单独替代最终结论。

第一步

1. 先确定项目目录。默认使用 ~/Downloads/Qiaomu PPT/<date>-<slug>/，并在项目里保留 README.md 和 task_manifest.json，让用户能看懂本次任务的资料、图片、规划、提示词和导出文件在哪里。
2. 能运行脚本时，先用 python3 <skill>/scripts/plan_run.py --prompt "<用户请求>" 生成路线卡、必读参考、主要脚本、确认边界和检查计划。不能运行脚本时，按本节手动判断。
3. 先判断请求类型，并在生成幻灯片前写一个简短路线卡。路线卡包含 route、final_delivery、confidence，以及会影响输出的关键假设。
4. 如果首条请求宽泛或信息不足，按 data/ppt_guided_choice_flow.json 和 references/guided-choice-flow.md 给出紧凑选择卡。可以推荐默认值，不要强迫用户回答不必要的问题。
5. 第一阶段是资料搜索整理、归档和内容消化，不是过场：调用模型已有知识、用户材料和联网/来源抓取，保存引用链接、来源文件、下载/提取图片、sources/source_manifest.json、sources/source_cards.json、research_dossier.md、图片候选和缺口；随后为主题型 PPT 写一篇中文内容母稿（如 内容母稿-<主题>.md 或 content_report.md），把来源消化成有主张、有结构、有判断的长文。research_dossier.md 是资料档案，不能替代内容母稿。即使后面不生成 PPT，这个调研包和内容母稿也应能独立阅读和复用。例外：NotebookLM 原生路线只需要把完整来源和轻量风格/页数/prompt 归档，不生成 source cards 或内容母稿。
6. 第二阶段才基于第一阶段的全部资料、来源卡和内容母稿，创建 content_contract.json、逐页大纲、页面脚本、逐字 PPT 讲解稿/讲者备注、spec_lock.json 或 ppt_config.json、visual_contract.json、visual_asset_manifest.json、assets/images/image_prompts.json/md，再进入预览和生产。正式 slide_plan.json 应从内容母稿抽取页面主张，不要直接从链接清单或来源摘要生成页面。
7. 用户在选择卡之后回复 生成、默认、按默认 或部分选项代码，只代表同意按默认值进入资料收集和规划阶段，不代表允许直接渲染最终 PPT。
8. 只有用户明确使用免确认生产措辞时，才能跳过确认，例如 不用确认、无需确认、跳过方案、跳过资料确认、跳过预览、直接进入生成阶段、直接生成最终版、直接出完整 PPT、一口气生成 或 先出草稿不用等我。把原话记录进项目。

确认门

• 对 PPT、deck 或较重的演示内容生产，先给用户一个可审阅的方案，再生成最终文件。方案应包括假设、推荐路线、交付格式、受众/使用场景、页数、故事线或逐页大纲、视觉方向、资料/搜索深度、已知风险和取舍。
• 方案给出后停下，等用户明确确认，再生成 PPTX、PDF、正式 HTML、图片资产或其他最终交付物。
• 简短主题、ppt、介绍下、不用过多搜索 等说法，不等于允许跳过确认。把它们理解为允许先出方案，而不是直接渲染整套 PPT。
• 不要把粗略想法、路线卡、道歉时顺手列出的简纲或不完整草案当成正式方案。可审阅方案必须包含路线卡、推荐判断、关键假设、完整逐页大纲或 storyboard、内容与资料来源计划、视觉方向、预览/审批计划、输出清单、风险和取舍。
• 可审阅方案中的视觉方向必须明确生图计划：哪些页用 Codex/宿主生图做整页或主区域主视觉，哪些页使用真实来源图，哪些可编辑前景文字/标注/讲解路径会叠加在图像之上。默认所有非来源证据的视觉页都先规划 Codex/宿主主视觉；SVG/形状只作为简洁前景控件或降级方案。缺少这部分时，不得进入预览或生产。
• 可审阅方案中的视觉方向必须说明为什么该风格最适合当前主题，并列出一个明确 avoid_style。如果用户没有指定风格，方案不能只给“高级、科技、杂志、插画”等抽象词，必须把内容域、受众、证据类型、情绪温度、版式节奏和画面语言对应起来；不同主题的避让项不同，不要把某一次返工里的题材规则硬套到所有 PPT。
• NotebookLM 原生方案如果用户未指定风格，必须包含 NotebookLM 风格建议：3-5 个候选、推荐默认项、适用理由、可直接作为 UI 描述框或 --prompt 的短句。优先推荐手绘白板图解、火柴人分镜、博物馆专题展览、自然图鉴、动画设定集、极简教学卡片等可读性强的视觉语言；避免容易塞满屏幕的赛博 HUD、数据仪表盘、游戏技能面板和密集商业咨询风，除非用户明确要。
• 可审阅方案必须先定版式再定生图：逐页列出 Lxx 版式模式；有主要图片、截图、人物、产品、场景、证据图或生成图时，同时列出 ITLxx 图文模式、焦点位置、安全文字区、裁切策略和缩略图节奏角色。缺少逐页版式合同的方案，不得当作已确认的视觉方案。
• 进入正式逐页大纲前，运行或等价检查 python3 <skill>/scripts/content_preflight.py <project> --profile plan。内容任务书、研究问题树、证据卡矩阵、内容母稿、叙事主线、页面内核表或视觉翻译准备不足时，先补第一步，不要直接写大纲。
• 进入四页预览或最终生成前，运行或等价检查 python3 <skill>/scripts/top_quality_plan.py <project> --profile plan|draft|final。资料档案、故事大纲、页面文案、视觉系统和图片艺术指导任一项阻塞时，先补上游契约，不要直接靠渲染修质量。
• 需要预览时，用户确认方案只代表授权生成预览或草稿，不代表可以直接生成最终整套 PPT。最终生成仍需要用户看过预览后批准，或在看过方案后明确要求跳过预览。
• 用户在当前流程里看过方案后，回复 确认、按这个做、生成、继续生成 或同等明确批准，可以进入生产。

路线默认值

• editable_pptx：PPT、PowerPoint、PPTX、课件、教师交接、协作修改，或最终格式不清楚时的默认路线。
• notebooklm_native_pptx：仅当用户明确要 NotebookLM 原生生成、NotebookLM 搜索/Deep Research、或接受图片式/原生 PPTX 时使用；交付 NotebookLM 生成的 PPTX/PDF，必须标注 image_backed_ok，保留 prompt/source/research/download/水印清理证据。
• pptx_plus_semantic_html：用户想要普通 PPT 加网页版本时使用；两种输出必须共享同一内容和视觉契约。
• semantic_html_deck：仅在用户明确要求网页/HTML、浏览器演示、互动 deck、WebGL 或强动效时使用。
  • HTML-only 不继承可编辑 PPTX 的坐标锁、SVG 页、PPTX/PDF/Keynote 或 Codex 生图硬门。使用 slide_plan.json、html_design_kernel.json、html_layout_intent、html_source_map.json 和浏览器截图来约束语义、层级、节奏和可读性；spec_lock.json 在 HTML-only 中是轻量意图/审计记录，不是逐页绝对坐标执行 JSON。
• html_preview 或 preview_then_pptx：用于快速看视觉方向、风格关卡或“先看效果”；必须标注为预览。
• planning_only：用户只要大纲、方案、故事线、重设计计划、审计或页面文案时使用。

检查档位：

• plan：路线、来源缺口、方案和确认边界；默认不跑导出、预览、图片生成、原生软件或完整质量基准。
• draft：草稿/预览验证；只检查项目结构、文件存在、关键页预览或截图，不承诺最终质量。
• final：最终交付验证；才运行 PPTX/HTML 路线相关导出、预览、文本、语义、质量基准和修复计划。
• release：公开发布、客户交付或用户要求严验时使用；在 final 基础上追加交付包、敏感信息和明确要求的原生软件验证。需要强制严验时给 plan_run.py 加 --validation-profile release。

常见路线重点：

• 品牌发布：叙事张力、首屏冲击、品牌真实性、少字、真实产品/媒体证据。
• 高中课件：教学目标、概念阶梯、教室可读性、例题、练习、教师备注、学科正确性。
• 商业报告/演讲：来源支撑的判断、具体锚点、有说服力的结构、清楚的证明对象、可讲备注。
• 旧 PPTX 优化：先看缩略图和文本，保留有价值的版式，再进入修复和验证循环。

路线不明显时，读 references/routing-playbook.md。

按需读取参考

不要一次读完所有参考。按场景读取：

• 机器可读路线表在 data/route_reference_map.json，检查策略在 data/check_policy.json。优先按 scripts/plan_run.py 输出读取参考、脚本和检查计划；只有路线不明、验证失败或用户要求更深解释时，再读更多参考。
• 第一步内容准备规则在 data/content_preparation_contract.json，执行 scripts/content_preflight.py。需要让资料更充分、大纲更精准、故事线更强或后续视觉更稳时，先看内容任务书、研究问题树、证据卡矩阵、页面内核表和视觉翻译准备。
• 顶级质量前置规则在 data/top_quality_rubric.json、data/research_dossier_schema.json、data/story_outline_contract.json 和 data/image_art_direction_schema.json。需要判断资料、大纲、文案、视觉系统或图片计划是否足够支撑高质量 PPT 时，运行 scripts/top_quality_plan.py，不要靠主观感觉放行。
• 宽泛主题、URL、PDF、Office、EPUB、文件夹、ZIP、图片、微信、飞书、arXiv 或 Hugging Face 输入：读 references/source-intake-method.md、references/topic-research-method.md、references/url-ingestion.md，并按来源类型追加 references/paper-source-intake.md 或 references/wechat-source-intake.md。
• NotebookLM 原生 PPTX、NotebookLM 搜索/Deep Research、NotebookLM 下载 PPTX/PDF、或“火柴人风格 PPT”等 NotebookLM 风格提示生成：读 references/notebooklm-native-deck.md，使用 scripts/notebooklm_deck.py，可用 --list-styles 查看 20 个 --style-preset，并把水印清理报告写入 reports/notebooklm_watermark_cleanup.json。
• 设计方案、执行锁定、多阶段生产或默认审美决策：读 references/model-driven-generation.md、references/production-contract.md、references/ppt-design-generation-methodology.md 和 references/ppt-aesthetic-quality-framework.md。
• 版式、中文字体/间距、图文关系、图表、图解、组件、图标或视觉系统：读 references/chinese-typography-layout.md、references/presentation-layout-principles.md、references/layout-pattern-library.md、references/image-text-layout-patterns.md、references/image-text-integration-contract.md、references/chart-diagram-components.md、references/icon-assets.md 和 references/visual-systems.md。
• 高设计要求、编辑风、ppt-master 级别、低质量返工、风格匹配或“想要任何 PPT 都好看”：读 references/ppt-aesthetic-quality-framework.md、references/ppt-master-grade-execution.md、references/ppt-master-research.md、references/design-style-library.md、references/visual-character-and-style-picker.md、references/ppt-anti-slop.md 和 references/ppt-visual-failure-patterns.md。
• 生成图片、来源图片、背景、图片队列或媒体出处：读 references/visual-asset-acquisition.md、references/codex-image-backgrounds.md、references/procedural-backgrounds.md 和 data/image_generation_providers.json。
• 正式 HTML deck 或动效：读 references/html-output.md、references/html-design-kernel.md、references/html-motion.md、data/html_deck_design_kernel.json 和 data/html_motion_presets.json。
• PPTX 导出、SVG 兼容、Keynote 或旧 deck 修复：读 references/svg-pptx-compatibility.md、references/pptx-skill-method-adaptation.md 和 references/quality-gates.md。

运行依赖

• 不要在方案档或纯路线判断阶段默认运行依赖检查。只有新安装、环境未知、脚本报缺包、准备来源转换、PPTX/HTML 导出、图片生成或检查计划要求时，运行 python3 <skill>/scripts/bootstrap.py --check。
• 如果缺 Python 包，运行 python3 <skill>/scripts/bootstrap.py --install-python；需要隔离环境时使用 --venv，然后重跑 --check。
• 完整可编辑 PPTX 交付和 PPTX 预览验证需要 LibreOffice (soffice)。缺失时运行 python3 <skill>/scripts/bootstrap.py --install-system，然后重跑 --check。
• 只有需要 Poppler、ImageMagick、Node.js 或压缩包解压器等可选工具时，才使用 --install-system --include-optional-system。
• Keynote 导出是 macOS 可选能力。不要用 PPTX 或 LibreOffice 证据推断 Keynote 兼容性。需要 Keynote 证据时使用 scripts/export_bundle.py、scripts/keynote_smoke.py 或 scripts/keynote_probe.py --with-control。
• HTML 动效是可选增强层。GSAP、Lottie 和 dotLottie 只能作为打包的浏览器资产或明确声明的外部依赖使用，并写入 html_motion_manifest.json，再用 validate_html_deck.py --motion-manifest 验证。

生产流程

1. 收集上下文和来源材料。
   • 先选择项目目录；默认使用 ~/Downloads/Qiaomu PPT/<date>-<slug>/，并保留 README.md 和 task_manifest.json。
   • 有来源输入时运行 python3 <skill>/scripts/source_to_markdown.py <inputs...> --output-dir <project>/sources。
   • 宽泛主题默认运行 python3 <skill>/scripts/topic_research.py "<topic>" --output-dir <project>/sources --depth fast，除非用户禁止网页或来源研究。
   • 正式大纲前先按 data/content_preparation_contract.json 准备或审计内容包：content_contract.json、research_questions.json、sources/source_cards.json 或 evidence_matrix.json、page_kernel_map.json 和视觉翻译准备；运行 python3 <skill>/scripts/content_preflight.py <project> --profile plan。
   • 幻灯片规划前按 data/research_dossier_schema.json 保存 Markdown 资料与研究档案，区分已验证事实、解释判断、来源覆盖、引用链接、下载/提取图片、候选图片、权利说明、矛盾和缺口。机器文件可使用 research_dossier.md。
2. 创建演示文稿契约。
   • 普通主题/文件/链接准备优先使用 python3 <skill>/scripts/create_deck.py --topic "<topic>" <inputs...> --project <project> --slides <n>。
   • 只有方案获批或用户明确免确认时，才使用 --produce。
   • 方案必须方便用户审阅：页数、受众状态变化、故事线、来源摘要、风格候选、推荐方向、图片策略、版式组合、逐页计划、备注目标和质量风险。
   • slide_plan.json 按 data/story_outline_contract.json 从 page_kernel_map.json 扩展成叙事链：每页有主判断、证明对象、来源/具体锚点、观众变化、视觉角色、布局理由、阅读路径和 QA 风险。
   • 同时建立观众文案层：每页先写 audience_takeaway、audience_question、visible_title、visible_body、visible_labels 和 speaker_notes_only。只有 visible_* 字段允许进入幻灯片画布；speaker_notes_only、版式理由、制作方法、检查策略和资产说明必须留在备注或 sidecar。
   • 需要讲述型交付时，同时写逐页脚本和逐字讲解稿：可用 notes/total.md、speaker_notes_plan.md、page_content_guide.md/json 或等价文件承载，不要只留在聊天里。
3. 锁定叙事和视觉系统。
   • 按路线写入或检查 deck_brief.md、design_proposal.md、content_contract.json、slide_plan.json、style_direction.json/md、spec_lock.md/json、visual_contract.json 和 visual_asset_manifest.json。
   • 普通页面必须有判断式标题、具体锚点、证明对象、版式模式、阅读路径和质量风险。
   • 图文页面必须声明图文版式、安全文字区、裁切策略、前景角色和图文融合方式。
   • 图文页面的图片槽必须是比例受约束的媒体容器：声明 slot_aspect_ratio、fit_policy（cover_crop、contain_letterbox 或 native_size）、焦点位置和允许裁切边界。渲染时先把图片裁切/留白到槽比例，再插入 PPTX；不得用同时指定宽高的方式把不同比例图片强行拉伸进槽。
   • 图文页面还必须声明至少一个 integration_move：真实留白、局部渐隐/遮罩、图像作为标注画布、证据区域放大、边缘融合、引线标注、对象周边排布或对比构图。连续页面不得复用“左侧大文字栏 + 右侧图片”或同等黑/白半屏面板作为默认结构。
   • 图文页面必须声明 text_surface_policy：原图真实留白、烘焙渐变阅读底、局部编辑 matte、独立浅/深阅读区、证据图外侧说明区或讲者备注。正文、长 claim 和来源说明不得直接压在浅色纹理、复杂图像或高频细节上。
   • 背景默认不得使用网格线、引导线、稿纸线、施工线、装饰线叠层、tech lines、side rails 或抽象条纹。除非用户明确要求，线条只能作为图表轴/系列、表格线、连接线、流程/时间线/地图路径、焦点下划线、分隔线或真实形状边界，并在契约中说明语义目的。
   • 版式不是渲染后的微调。进入图片生成前，先从 layout-pattern-library.md 和 image-text-layout-patterns.md 选择逐页 Lxx/ITLxx，并把这些 ID 写入 slide_plan.json、spec_lock、visual_contract.json 和 visual_asset_manifest.json 的对应条目。
   • 高设计、编辑风或 ppt-master 级别项目还必须把组件选择理由写进 slide_plan.json、design_spec.md 或 spec_lock：每个图表、步骤、地图、表格、KPI、票档、日程、列表或卡片系统要说明为什么选它；有明显但错误的备选组件时记录 rejected reason。
   • 用户未指定风格时，style_direction.json/md 必须包含通用审美判断：primary_visual_family、alternative_family、avoid_family、avoid_reason、domain_fit_reason、audience_fit_reason、visual_temperature、rhythm_strategy 和 image_content_binding_policy。避让项来自当前主题和受众，不来自上一套 deck 的返工经验。
   • 在 Codex/宿主生图可用且用户未禁止时，visual_asset_manifest.json 必须按 data/image_art_direction_schema.json 包含整页或主区域 Codex/宿主主视觉条目；每张图要有对应 Lxx/ITLxx、画面角色、焦点位置、构图、文字安全区、裁切策略、负面提示、可编辑前景边界和缩略图节奏角色。正文、标题、结论、标签、标注、来源说明和讲解路径不得烘焙进图像。只用 SVG、形状、渐变、程序化纹理或占位图的预览/正式稿必须标为降级方案，并向用户说明。
   • 生成图 prompt 不是风格咒语。每条 prompt 必须带上本页内容角色、具体对象/场景、画面焦点、前景文字安全区、可标注对象、与页面 claim 的关系和本主题的负面风格。负面风格必须按内容域生成，例如严肃技术商业主题避开童趣插画，教育课件避开过度奢华大片感，文化人物主题避开无出处的假古董纸面。
   • 计划 AI 图片时，最终质量项目必须有 assets/images/image_prompts.json 和 assets/images/image_prompts.md 或等价 sidecar；prompt 队列不能只存在聊天上下文里。对 presentation-ready、旁白或 Keynote 式交付，另需规划 notes/total.md 和 animations.json/animation_manifest.json，或在报告中标明静态降级。
   • 四页预览前运行 python3 <skill>/scripts/top_quality_plan.py <project> --profile draft；最终生成前运行 --profile final。未过线时先修资料、大纲、文案、视觉系统或图片艺术指导。
4. 普通 7 页以上 deck 先生成四页预览。
   • 四页预览应覆盖不同页面角色：封面/开场、密集证明页、图解/流程页、呼吸页/引用页/转折页。
   • 优先使用 python3 <skill>/scripts/prepare_deck_project.py ... --generate-preview --preview-decision pending 或 python3 <skill>/scripts/four_slide_preview.py <project>。
   • preview_gate.json 记录批准或用户明确跳过之前，不要进入完整生成。
5. 生成演示文稿。
   • NotebookLM 原生路线使用：python3 <skill>/scripts/notebooklm_deck.py <project> --title "<title>" --input <url-or-file> --search "<query>" --style-preset data_storytelling --style "<optional short creative direction>" --format presenter --length short --language zh_Hans --research-wait-timeout 180 --artifact-wait-timeout 900 --preview。这是明确的图片式/原生 PPTX 路线，不替代默认 SVG-first 可编辑路线。该路线直接把完整来源交给 NotebookLM，不要求 sources/source_cards.json、content_contract.json、slide_plan.json 或四页预览。默认使用 presenter + short 控制可见字数；只有用户明确要详细讲义/阅读版时才切到 detailed。默认会让 strip_notebooklm_watermark.py 尝试 --inpaint-raster-watermark；若缺 OpenCV/numpy 或未检测到图片水印，必须写进报告。输出必须包含 notebooklm_generation_manifest.json、export_manifest.json、reports/notebooklm_watermark_cleanup.json 和 pptx_text_check.json（allow_image_backed: true）。
   • 默认最终质量命令：python3 <skill>/scripts/qiaomu_ppt.py build <project> --quality-profile final --generate-images --enforce-quality-benchmark --fail-on-critical-repairs --benchmark-min-score 85
   • 对 semantic_html_deck 且 requested_formats 只有 HTML 的项目，最终硬门是 html_delivery_manifest.json、validate_html_deck.py、浏览器截图、来源/风格审计和可读性 QA；deck_quality_benchmark.py 只作为参考分数，不能因为缺未请求的 PPTX/PDF/Keynote 或未要求的 image_gen 判失败。
   • 快速视觉草稿使用 --quality-profile draft --image-limit 4 --formats pptx，仍应包含真实关键图片。
   • --no-generate-images 只用于明确标注的离线或文本结构冒烟测试，不用于最终视觉质量。final/professional 项目没有达到关键页真实生图或可信来源主视觉目标时，produce_deck.py、deck_quality_benchmark.py 和 check_project.py --require-real-imagegen 都必须判失败；Codex 原生生图可用时优先使用，但不是非 Codex 环境的硬依赖。
   • 手工排障不得把默认路线改回 SVG/形状主视觉。SVG-first 只能用于验证版面、导出链路、前景可编辑控件或离线降级；一旦视觉质量进入评审，优先重新生成或替换 Codex/宿主主视觉，再叠加可编辑前景文本，并运行预览缩略图、PPTX 导出、文本检查、项目检查、质量基准和修复计划。
6. 完成前验证。
   • 运行或检查 produce_deck.py 生成的路线相关报告。
   • 最终/professional/release 输出前必须运行或检查 reports/style_fit_audit.json/md。如果报告显示默认审美决策不完整、风格与内容域/受众/证据类型不匹配、命中当前主题避让风格、或生成图缺少内容绑定，不得继续发布；先重选风格、重写图像导演、重生/换图或重排版。
   • 检查 top_quality_plan.py 报告；如果总分或分项未达当前档位门槛，不要说已经达到顶级质量。
   • 按 plan_run.py 的 check_plan 执行当前档位检查；不要把 defer_until_final 或 skip_by_default 的项目提前跑成默认动作。
   • 生成了项目目录且检查计划要求时，运行 python3 <skill>/scripts/check_project.py <project>。
   • 生成最终 PPTX 后，必须运行 python3 <skill>/scripts/pptx_text_check.py <pptx> --slide-plan <project>/slide_plan.json --output <project>/pptx_text_check.json，并只在 ok: true 后交付。这个检查要早于最终回答，不应等用户指出标题、小字或强调框问题后再补跑。
   • 生成了 SVG/HTML/PPTX 预览缩略图或 SVG 中间层时，运行 python3 <skill>/scripts/visual_rhythm_check.py <project> --output reports/visual-rhythm.json 或等价检查；若报告指出连续重复结构、图片使用不足或节奏单调，先修版式合同和视觉 prompts，再进入最终导出。
   • 检查缩略图、手机截图或联系表时，把图文割裂当成硬缺陷：大块文字面板遮住主视觉、短标签像底部控件但没有指向目标、标题在窄栏里尴尬换行、来源/脚注小到不可读、文字跨过复杂亮区或连续页面结构指纹重复，都要先改 Lxx/ITLxx、融合动作或图片构图。
   • 预览通过后进入完整 PPTX 时，必须重新跑 PPTX 几何检查，而不能沿用 PNG/HTML 预览的肉眼判断。pptx_text_check.py 或 layout_guard.py 报告标题框过紧、标题与副标题/正文间距不足、强调 chip 过扁、强调条不是圆角矩形、或任意文本溢出时，先修 PPTX 再交付。
   • 检查手机截图或单页预览时，把低对比文字当成硬缺陷：彩色文字落在浅色/纹理图上、正文没有稳定阅读底、透明 PPT 形状在 LibreOffice/PowerPoint 渲染不一致、脚注比主视觉先丢失可读性，都要先修 text_surface_policy、字号、文字颜色或图片处理。
   • 能打开或预览 HTML/PPTX 时必须打开或预览。无法验证原生 Office、WPS、PowerPoint、Keynote、浏览器截图或图片生成时，说清具体缺口。
   • 最后运行或检查 python3 <skill>/scripts/qiaomu_ppt.py check <project>，把 production_manifest.json、project_check.json、export_manifest.json、pptx_text_check.json、benchmark 和 repair plan 收敛为 final_status.json / 交付检查.md。

视觉与内容规则

• 普通页面应有一个主判断和一个主证明对象。教学页或报告页可以更密，但仍要有层级。
• 页面可见文字是给观众看的正式文案，不是给制作者看的项目说明。生成每个文本框前先问：观众是否需要在现场读到这句话？讲者是否会自然照着这句话说？如果答案是否定的，移动到讲者备注、qa_report.md、design_spec.md、visual_contract.json 或其他 sidecar。
• 风格名、风格提示词、生成方式和可读性约束不是观众文案。不要让“老师讲解”“白板讲解风”“教学白板风”“手绘极简少字版”“创意方向”“可读性要求”“视觉要求”“结构要求”等内部说明出现在画布上；NotebookLM 图片式输出也必须用缩略图检查这类 prompt 泄漏。
• 强制三层分离：visible audience copy 只写观众要理解的判断、证据、行动和对象名称；speaker notes 写讲解顺序、转场、读图提示和讲者提醒；production metadata 写路线、版式、Lxx/ITLxx、素材、生成策略、质量门和导出状态。普通科普、商业、课件和报告 PPT 不得把后两层露在画布上。
• 不要把内部词汇露到画布上，例如 deck、route、artifact、fallback、pipeline、source_fetch、模型名、工具名、生成策略、质量备注或出处标签。中文也一样：讲解顺序、版式、路线卡、交付、可编辑 PPTX、生成图、提示词、检查报告、图版、证据 01 / ... 这类制作者标签默认不能出现在观众画面里，除非用户明确要做流程/方法类演示。
• 图片说明要从“资产说明”改写成“观众可理解的内容锚点”。例如不要写“复原图版：羽毛恐龙与现代鸟类的连续感”，改成“羽毛和前肢结构提示它们在同一条演化线上”；不要写“讲解顺序：化石图版 -> 特征组合”，改成讲者备注或直接删除。
• 页面角色、证据编号、章节名和风格名只有在它们本身能帮助观众定位内容时才可见。否则把“自然史图鉴 01”“证据 02 / 共享结构”改成面向观众的问题或判断，例如“鸟为什么属于恐龙？”“骨骼比外形更能说明亲缘关系”。
• 有来源图、用户图或网页图时，优先把它们作为证据使用；同时仍应使用生图提供场景、质感、复原示意或主视觉节奏。AI 生成图不能伪造截图、图表、表格、标志、来源文档、产品证据或用户未提供的前景物。
• source-derived、本地脚本绘制的“源资料衍生图”、程序化背景或占位图只能算降级辅助视觉，不能算真实来源图，也不能算真实生图。若最终质量报告中真实生图数量低于关键页下限，必须继续生成或明确降级为草稿，不得发布。
• 在 Codex 或宿主原生图片生成可用时，推荐生成的 PPT 默认必须先生成真实整页或主区域位图主视觉，再叠加可编辑标题、介绍文本、结论、标签、标注、图表、来源说明和少量版面形状。整页位图作为视觉层是允许的，但不得把可编辑文本和科学/商业结论烘焙进图像；pptx_text_check.py 应证明前景文字仍是原生对象且 image_backed_ratio 不构成伪可编辑整页截图。程序化资产、纯 SVG 线稿、几何形状和渐变只能作为离线 fallback、占位预览或前景可编辑解释层，除非用户明确接受它们作为视觉风格。
• 图片、截图、生成图和来源图不得非等比缩放。每个媒体对象进入 PPTX 前必须满足：embedded_image_ratio 与 shape_slot_ratio 基本一致，或明确使用 contain/letterbox；如果比例不一致，先重生图、扩图、裁切、加留白或调整槽位，不允许拉伸人物、产品、骨骼、场景、图表或截图。
• 不要把 Codex 图当作普通背景再随手贴文字框。生成图的构图必须服从已选 Lxx/ITLxx：焦点、留白、裁切、安全文字区、前景标注区和阅读路径都要在 prompt 里被指定。若缩略图看起来单调、图文割裂或只是重复左文右图，优先更换版式模式并重生/重组主视觉，而不是只挪动文本框。
• 默认生成图必须逐页服务具体内容：封面图要承载主论点气质，证明页图要露出可标注对象，流程页图要能承接步骤或因果，转折页图要制造叙事变化，结尾图要回扣行动或判断。禁止把同一类“好看的背景图”换标题后反复使用；连续两页以上出现无内容绑定的相似主视觉，应先判定为视觉失败。
• 图文融合优先使用图像中的真实留白、对象周边标注、局部渐隐、边缘裁切、放大细节和引线关系。大块半屏文字面板、底部标签排、重复黑栏和漂浮卡片只能在版式合同明确需要时使用；如果它们在缩略图里先于主视觉被看见，说明 chrome 抢戏，必须简化。
• 所有标注、标签、chip 和引线必须指向具体图像目标、比较对象或讲解路径；没有目标的标签排应改为标题副句、讲者备注或直接删除。手机预览中不可读的脚注、来源、标签和长词换行不是小问题，是导出前缺陷。
• 红色/蓝色/绿色等强调 chip、短标签和信息条必须是稳定的圆角矩形组件，不要做成压扁胶囊、贴纸、短高不足的色块或硬边矩形。强调条默认高度至少 0.40in（短词标签也不低于 0.34in），文字上下要有真实内边距；如果只是为了装饰，不要用强调色容器。
• 可读性优先于配色好看。长句、正文、解释性 claim 和路径文字默认使用高对比中性色；强调色只用于短词、短标签、线条或大号标题。若文字压在生成图或来源图上，必须先有稳定阅读底，再谈色彩风格。
• 中文标题和正文必须拉开层级：16:9 画布上标题到正文/证明对象默认至少留 36-56px 或 0.55-0.80 个标题行高；标题到副标题至少 18-28px；正文行高默认 1.45-1.75。如果缩略图里标题、正文、标签或媒体对象像粘在一起，必须先增大间距、重排换行或减少内容，不要靠线条、边框、阴影补救。
• 普通视觉型 deck 不应连续复用同一种结构指纹。除非是严格报告模板，4 页以上的视觉预览应包含明显不同的封面/证据/图解/呼吸页结构；7 页以上 deck 应在缩略图网格中体现 anchor、dense、breathing 节奏和多种 Lxx/ITLxx 组合。
• 拒绝常见 AI/网页设计指纹：默认紫色渐变、装饰球、卡片套卡片、假玻璃、装饰图标堆、假证据、嘈杂线条、默认页面控件、重复卡片栅格。
• 路线承诺可编辑 PPTX 时，前景标题、介绍文本、标签、图表、标注、讲解路径、引用和关键形状应尽量保持可编辑；复杂图像质感和主视觉质量交给 Codex/宿主生成图，而不是手画 SVG/形状。
• 正式 HTML deck 必须以 HTML 原生语义为主：section.slide、真实标题/正文/列表/图表容器、CSS/JS 舞台和可选局部 SVG/Canvas/WebGL；不要默认依赖整页 SVG，不要为了填满 visual_asset_manifest 或 spec_lock 制造无语义背景物件。使用固定 16:9 舞台、html_design_kernel.json、html_layout_intent、html_source_map.json 和默认键盘导航；除非用户明确要求，不要把可见上一页/下一页按钮或进度条放进幻灯片画布；使用本地优化资产并提供 validate_html_deck.py 证据。

质量门

按 plan_run.py 输出的检查档位和检查计划运行相关质量门。没有通过当前档位要求、或没有标明缺失证据前，不要声称该档位完成。

修改本技能的路由、确认边界、检查策略或指令遵循规则后，运行 python3 <skill>/scripts/instruction_eval.py --cases <skill>/evals/instruction_cases.json --output <skill>/reports/instruction-eval.json --markdown <skill>/reports/instruction-eval.md。 修改视觉 lint、字体策略或重复结构规则后，运行 python3 <skill>/scripts/visual_quality_regression.py。修改生产状态或检查聚合后，至少运行 python3 <skill>/scripts/final_status.py <existing-project> --report-only 或相应自测项目。

1. 信息收集门。
2. 路线和最终交付门。
3. 内容准备门：内容任务书、研究问题树、证据卡矩阵、内容母稿、叙事主线、页面内核表、视觉翻译准备。
4. 资料与研究档案门、来源证据门。
5. 主题/论文/微信/特定来源提取门。
6. 逐页计划确认门。
7. 面向专业/最终/高设计运行的内容大纲、元素计划、风格适配和 ppt-master 轴向审计。
8. 顶级质量前置门：内容准备包、资料档案、叙事大纲、页面文案、视觉系统、图片艺术指导。
9. 叙事、文案、具体性、版式多样性、缩略图节奏、字体层级和图文融合门。
10. 视觉资产获取、来源图片使用、生成图片出处、主要媒体证据和视觉资产状态门。
11. 反俗套、页面控件、形状组件、连接线、可读性、观众视角可见文案和可见文案出处门。
12. HTML、PPTX 可编辑性、PPTX 预览、PDF、Keynote、备注、生产、export_manifest.json、质量基准、修复计划和最终验证门。

详细规则见 references/quality-gates.md。如果质量基准或修复计划报告关键问题，先修契约、清单、来源、资产或渲染映射，再说达到最终质量。

输出证据

普通 deck 运行默认只向用户汇报以下核心子集；更细 sidecar 留在项目目录供追溯：

• skill 目录外的项目目录。
• README.md 和 task_manifest.json，作为每次任务的人类可读和机器可读归档索引。
• deck_brief.md、research_dossier.md 或足够完整的 sources/source_notes.md、内容母稿-<主题>.md 或 content_report.md、design_proposal.md、content_contract.json、slide_plan.json、style_direction.json/md、spec_lock.md/json 或 ppt_config.json、visual_contract.json。
• 高质量第一步应包含 content-preflight.json/md，以及 research_questions.json、evidence_matrix.json 或 sources/source_cards.json、page_kernel_map.json 等内容准备包产物。
• 使用来源输入时的 sources/source_manifest.json、sources/source_cards.json、引用链接、下载/提取的来源图片或来源侧车文件。
• 使用视觉时的 visual_asset_manifest.json、图片提示/队列、生成或来源资产文件、出处说明。
• 高设计或 ppt-master 级别运行时的 reports/ppt_master_axis_audit.json/md，以及 AI 图片对应的 assets/images/image_prompts.json/md。
• 高质量运行时的 top-quality-plan.json/md，或等价的资料、叙事、文案、视觉系统和图片艺术指导评估。
• 用户请求的 SVG/HTML/PPTX/PDF/Keynote 导出；无法交付时，在 export_manifest.json 中明确记录缺失或失败。
• 需要现场讲述、旁白或演示动效时的 notes/total.md、逐页讲稿/per-page notes、animations.json 或 animation_manifest.json。
• PPTX 文本/可编辑性检查、预览或缩略图网格、HTML 验证报告、qa_report.md、质量基准报告、修复计划、final_status.json、交付检查.md 和已知缺口。

完整产物结构见 references/production-contract.md。

暂停条件

遇到以下情况，先暂停并询问用户：

• 需要专有品牌资产、受版权保护的源文件、付费 API、凭证或账号操作。
• 任务需要产品、法律、医学/科学事实、考试标准或当前事件判断，但无法从用户提供的来源中验证。
• 用户要求复杂 HTML/WebGL deck 与可编辑 PPTX 像素级一致。说明可编辑 PPTX 和网页渲染的取舍。
• 可编辑 PPTX 导出器不可用，但用户要求真实 .pptx。
• 连续三轮聚焦修复后，叙事、可读性或导出问题仍未解决。