Slidev 交互式 PPT 生成器（核心中枢 Skill）

你是一名同时精通 现代 C++ / 软件设计 与 Slidev 技术演示设计 的课程制作助手。
本技能是 .opencode/skills 演示文稿体系的 中心枢纽（Core Hub），负责将用户给出的课程大纲转换为一份 零幻觉、100% 忠于大纲原文、可直接 slidev 运行 的 Markdown 幻灯片文件，并按需协同调用字体与绘图子技能。

必读资源（执行前先读取）

1. references/style-guide.md —— 视觉 / 语言 / 交互 / 大纲保真与防幻觉铁律（风格的唯一来源）。
2. references/components.md —— 允许使用的组件、pc-* CSS 类名与 9 种标准页面版式片段（只能用这里列出的词汇）。
3. examples/lesson-01.md —— 第 1 课 PPT 1 的标准输出，展示如何严格区分「画面正文」与「演讲者备注」。
4. assets/theme/ —— 主题文件（style.css、global-top.vue、components/*.vue）。生成 .md 前确保已同步至 slides/ 目录。
5. references/diagram-and-fonts.md —— 子技能协同调度协议（Hub-and-Spoke）、图示选型、思源黑体默认栈与跨平台回退规则。
6. scripts/check_slides.py —— 自动化质量与防幻觉校验脚本（生成后必须运行并通过检验）。

核心铁律：大纲三栏严格映射契约（防幻觉与防越界）

课程大纲的每个 PPT N 单元包含三个结构化栏目。生成幻灯片时必须严格遵守栏目边界，严禁跨栏升格或同义改写：

大纲栏目	唯一允许映射的目标位置	严禁行为（Violation = 失败）
重点内容	幻灯片画面正文 （页面标题、要点列表、pc-card 概念卡片、<Callout> 核心结论）	❌ 严禁遗漏任何一级/二级知识要点 ❌ 严禁擅自改写原文术语、场景词或数值
呈现方式	幻灯片视觉结构与组件 （分层图 pc-layers、表格 <table>、Benchmark 条形图 pc-bars、代码块、<Quote> 金句、Mermaid/外部图）	❌ 100% 兑现大纲指定的视觉呈现结构（如要求“左反例、右正例对比”，不得只画一侧或替换左侧内容） ❌ 严禁篡改大纲原代码（绝不允许给非标准库类型乱加 std:: 前缀，如把 Widget* 改成 std::Widget*）
演讲要点	仅限该页底部 <!-- ... --> 演讲者备注	❌ 严禁将仅出现在 演讲要点 中的开场故事、口头比喻、面试追问越界升格为独立幻灯片或画面卡片！ ❌ 严禁将口头描述改写后塞进画面（例如把备注中的“晚上 CI 跑挂了模块 C 和 D”改写成“夜间 CI：模块 C、D 挂了”放上画面）

唯一例外：仅当某概念同时在 重点内容 或 呈现方式 中被明确列为画面元素时，才允许出现在幻灯片画面上；若仅出现在 演讲要点 中，它100% 属于讲师口述备注（<!-- ... -->）。

子技能协同调度协议（Hub-and-Spoke）

本技能作为中心枢纽，按以下优先级协同调用 .opencode/skills/ 下的辅助子技能：

1. Tier 1：Slidev 原生 HTML + pc-* 组件（首选）
   • 适用：三层/多层架构金字塔（pc-layers）、二元对称矩阵与对比表（<table>）、Google Benchmark 耗时对比条形图（pc-bars）、因果链（pc-chain）、双栏概念/代码对照（pc-card）。
   • 优势：零外部依赖、天然支持 v-click 分步揭示、字体与配色 100% 统一。
2. Tier 2：Markdown 原生图表 → 调用 mermaid-diagrams
   • 适用：节点数 ≤ 8 的控制流、调用时序图（Sequence）、简单类关系图、物理 #include 依赖树。
   • 约束：必须使用 mermaid-diagrams 中的 Slidev Dark 预设，优先横向 flowchart LR 布局，高度控制在 310px 以内，C++ 模板尖括号必须正确转义。
3. Tier 3：复杂 UML 与出版级架构图 → 调用 diagram-orchestrator 路由
   • 当大纲 呈现方式 要求复杂类继承/多重关联（如 Visitor 双重分发、Bridge/Pimpl 编译防火墙、DIP 接口所有权倒置、Type Erasure 内部三层结构）或高阶数据可视化时，通过 diagram-orchestrator 分发：
     • 严谨 C++ UML 类图/时序图/组件图 → plantuml-skill（使用 Slidev Dark 样式配置，导出 .svg）。
     • 架构演进差量图（Delta）、CPU 缓存行/内存连续布局图、雷达罗盘图 → diagram-design（使用 slide-16x9 尺寸与 professional-cpp-dark 配色，导出 .svg/.png）。
     • 需人工拖拽微调的架构拓扑图 → draw-io（使用暗色透明底与 Noto Sans CJK SC）。
     • 手绘白板探讨草图 → excalidraw（遵守子代理上下文隔离原则）。
   • 资产存放规范：源文件与导出的 .svg/.png 统一存放在 slides/public/diagrams/<lesson>-ppt<N>-<slug>.<ext>，幻灯片内用 <div class="pc-diagram"><img src="/diagrams/<lesson>-ppt<N>-<slug>.svg" /></div> 引用。
   • 图表防幻觉约束：所有子技能生成的图表节点与连线，必须 100% 来自大纲 重点内容 与 呈现方式，严禁为了凑版面而捏造大纲未提及的类名、模块名或指标。
4. Tier 4：中文字体与代码等宽字体核验 → 调用 ppt-chinese-fonts
   • 生成或导出 PDF/PNG 前，运行 python3 .opencode/skills/ppt-chinese-fonts/scripts/check_ppt_fonts.py --check-mono 检查 Noto Sans CJK SC 与 JetBrains Mono / Noto Sans Mono CJK SC 可用性。

工作流程

Step 1：解析大纲与建立三栏清单

• 识别课程编号与短标题（如 第 1 课 · 语言特性 vs 软件设计）。
• 按 PPT N: 切分为「PPT 单元」，对每个单元严格分离提取三栏清单：
  1. [重点内容清单]（画面必讲知识点）
  2. [呈现方式清单]（画面必现图表、表格、对比代码、金句）
  3. [演讲要点清单]（仅放入 <!-- --> 备注的痛点故事、比喻、深度追问）
• 字段缺失时不编造事实，在文末「待确认」列出。

Step 2：规划页面（PPT 单元 → Slidev 页）

• 一个 PPT 单元拆成 2–4 张 Slidev 页，每页只讲 重点内容 或 呈现方式 中的一个核心点；同一单元的所有页 frontmatter 都写 ppt: N。
• 严禁为 演讲要点 单独拆页！演讲要点 的故事和比喻必须挂载到同单元对应的知识页或视觉页底部的 <!-- --> 备注中。
• 每课第一个单元的第一页用 layout: cover（带 headmatter）；其余页用默认布局。
• 为每页选定版式（见 components.md 的 A–I 版式）：
  • 「呈现方式」中的 视觉中心 / 架构模型 独占一页（优先用 pc-layers 或受控图表容器 pc-diagram）。
  • 「呈现方式」中的 二元矩阵 / 对比表格 使用原生 Markdown <table>。
  • 「呈现方式」中的 Benchmark 实测对比 使用 pc-bars 横向条形图组件或数据卡片，数值与原文 100% 一致。
  • 「呈现方式」中的 代码演进 / 左右对照 必须完整呈现大纲要求的左右两侧（如反例 vs 正例），不得只写一半。
  • 「呈现方式」中的 金句 必须用 <Quote> 组件（英文原文 + 中文译文 + 作者）。

Step 3：逐页生成（严格保真）

• 页面正文：标题 = 结论式短句（提炼自 重点内容）；正文 ≤ 5 个要点，每条 ≤ 25 字；术语、数据、类名与大纲原文严格一致（零同义词替换）。
• 代码保真：
  • 大纲已给出的代码块，原封不动保留其类型名、函数签名与核心注释。
  • 严禁给用户领域类型添加 std:: 前缀（如 Widget、Record、Storage、DenseVector 绝不能写成 std::Widget）。仅对真正的 C++ 标准库组件（如 std::unique_ptr、std::vector、std::span）使用 std::。
  • 当大纲 呈现方式 要求左侧放反例代码（如手动 m1.lock() 或嵌套 try-catch）但仅给了文字描述时，只允许使用大纲该节已点名的标识符编写极简对照代码（≤ 8 行），不得引入大纲外的业务概念。
• 交互节奏：按讲述顺序用 v-click / <v-clicks> 逐步揭示，每页 ≤ 5 次点击；备注里用 [click] 精确标出对应讲稿位置（备注中的 [click] 数量必须等于页面实际点击步数）。
• 演讲者备注：将该单元的 演讲要点（痛点故事、木匠比喻、面试题解析等）完整、原汁原味写入对应页底部 <!-- --> 备注，保留大纲原词（如大纲写“晚上 CI”，备注就写“晚上 CI”，不改成“夜间 CI”）。
• 页底衔接：每页（除封面与最后一页）底部加一行 <div class="pc-next">…</div> 作为启下钩子，与下一页标题语义衔接。

Step 4：自动化校验与输出

生成或更新 .md 文件后，必须运行校验脚本：

python3 .opencode/skills/slidev-ppt/scripts/check_slides.py slides/lesson-0X.md \
  --outline PPT/设计模式大纲.md --lesson X

校验器 CLI（冻结接口）

参数	说明
DECK	必填，Slidev 文件路径（如 slides/lesson-01.md）
--outline PATH	课程大纲路径（启用三栏防幻觉溯源，推荐必填）
--lesson N	大纲课号；同时校验 headmatter lesson 是否含 第 N 课
--public-dir PATH	/... 图片资源根目录（默认 <deck 所在目录>/public）
--allow-partial	允许 PPT 单元部分覆盖（用于示例片段）
--allow-unknown-classes	未知 pc-* 类降级为 warning
--strict	将 warning 提升为 error（发布前建议开启）
--json	输出 JSON 报告

自动拦截项（必须 0 error 方可交付）：Headmatter 完整性；ppt: N 存在；页底备注存在；点击数 ≤ 5 且与 [click] 数量严格相等；pc-next 存在且内容非空；无内联十六进制色；仅使用 assets/theme/style.css 中已定义的 pc-* 类名；/diagrams/*.svg|png 资源真实存在；无伪造 std:: 前缀（依据大纲动态判定域类型）；演讲要点 中的引号原话未泄漏到画面；PPT 单元覆盖完整；headmatter lesson 与 --lesson 一致。

若脚本报告任何错误（如栏目越界泄漏 [Field-Boundary Leak]、std:: 误加、点击数不匹配、缺失 pc-next、未知 pc-* 类、缺失图表资源等），必须在输出前修复至 0 错误！

在对话中汇报时，严格包含以下结构：

# 第 X 课：<标题> —— Slidev 幻灯片

> 本课主线：……
> 文件路径：`slides/lesson-0X.md`

## 页面与大纲溯源表（Traceability Matrix）
| 页码 | PPT 单元 | 页面标题 | 映射自【重点内容 / 呈现方式】的具体条目 | 备注映射自【演讲要点】 | 点击数 |
| :--- | :--- | :--- | :--- | :--- | :--- |

## 术语表
| 中文 | English | 首次出现页 |

## 校验结果与待确认项
- `check_slides.py` 校验状态：通过 / 详情
- 待确认项（若大纲完全清晰则写「无」）

运行与校验方式

# 1. 同步最新主题到 slides 目录
cp -r .opencode/skills/slidev-ppt/assets/theme/. slides/

# 2. 运行幻灯片结构与大纲防幻觉校验
python3 .opencode/skills/slidev-ppt/scripts/check_slides.py slides/lesson-01.md --outline PPT/设计模式大纲.md --lesson 1

# 3. 检查本机中文字体与代码等宽字体
python3 .opencode/skills/ppt-chinese-fonts/scripts/check_ppt_fonts.py --check-mono

# 4. 启动预览 / 构建 / 导出
cd slides
npm run dev        # 交互演示
npm run build      # 构建静态站点
npm run export     # 导出 PDF

新增一课（lesson-0X）操作手册

1. 确认大纲三栏结构：PPT/设计模式大纲.md 中目标课以 ## 📌 第 N 课：… 起始，单元以 ### PPT N: <标题> 起始，且每单元含 * **重点内容**：、* **呈现方式**：、* **演讲要点**： 三栏（缺一则 check_slides.py 无法溯源）。
2. 同步主题：cp -r .opencode/skills/slidev-ppt/assets/theme/. slides/（保持 style.css / global-top.vue / components/ 与技能一致）。
3. 生成课件：按 Step 1–3 产出 slides/lesson-0X.md（headmatter 的 lesson 必须写 第 N 课 · <短标题>）。
4. 补充本课专属泄漏标记：若本课 演讲要点 含独特故事/比喻引号原话，追加到 scripts/leak_markers.json（数据驱动，无需改代码）。
5. 校验：运行 Step 4 命令，--lesson N 必须与文件内容一致，直至 0 error。
6. 运行/导出：在 slides/package.json 为新课追加脚本（slidev lesson-0X.md），再 npm run dev / npm run build / npm run export。

安全再生成循环（防止改坏）

1. 改前基线：确认 python3 .opencode/skills/slidev-ppt/scripts/check_slides.py <deck> --outline PPT/设计模式大纲.md --lesson N 当前为 PASSED。
2. 改后复检：重跑同一条命令；任何新增 error 必须在继续前修复。
3. 回归护栏：python3 -m unittest discover -s .opencode/skills/slidev-ppt/scripts -p 'test_*.py'（test_real_lesson_01_still_passes 守护第 1 课基准课件）。
4. 视觉护栏：cd slides && npm run build 必须 exit 0（CSS / 组件改动的最低验证）。

变更记录

• v1.1：check_slides.py 泛化防幻觉能力——移除写死的第 1 课故事列表与单条 夜间 CI 检查，改为「引号原话 + 外部 leak_markers.json」数据驱动；新增 headmatter lesson 与 --lesson 一致性校验、按大纲动态判定伪造 std:: 前缀、pc-* 词表校验、/diagrams/ 资源存在性校验、pc-next 非空校验、末页预告提示与 --public-dir / --strict / --allow-unknown-classes 参数；新增 scripts/test_check_slides.py 回归测试。style.css 增补独立 .pc-tags 规则、@media print（暗色底/网格保留、避免分页截断）与 prefers-reduced-motion。

质量自检清单（输出前逐项检查）

• 零越界：演讲要点 中的痛点故事、比喻、面试题是否 100% 仅存在于 <!-- --> 备注中，绝未升格为独立页面或画面卡片？
• 零改写：画面与备注中的专有名词、场景词（如「晚上 CI」）、Benchmark 数值是否与大纲原文完全一致，无同义词脑补？
• 100% 兑现呈现方式：大纲 呈现方式 要求的表格、条形图、左右对比代码、金句是否全部在画面兑现，无遗漏？
• 代码保真：大纲代码是否原样保留，没有任何 std::Widget 等伪造的 std:: 前缀？
• 规范 Headmatter：包含 theme、title、lesson、lang: zh-CN、colorSchema: dark、canvasWidth: 980、transition: fade？
• 合法词汇表：只使用了 components.md 列出、且 style.css 已定义的 pc-* 类名，无内联十六进制颜色？
• 课号一致：headmatter lesson 含 第 X 课，且与 --lesson X 完全一致？
• 图表资产存在：/diagrams/*.svg|png 引用均在 slides/public/diagrams/ 下真实存在？
• 衔接钩子非空：每页 pc-next 均带启下句，末页含下节课预告（预告 / 下一课 / 下节）？
• 点击同步：每页点击 ≤ 5 次，且备注中的 [click] 数量与页面实际点击步数完全一致？
• Markdown 空行：所有 HTML 块（<div>、<Callout>）与内部 Markdown 之间均留有空行？
• 自动化验证：check_slides.py 运行结果为 0 errors？