dsh-courseware 0.1.0

package/lib/index.js

@@ -0,0 +1,186 @@
+// dsh-courseware: 中小学课件生成技能（courseware）的 DSH 插件包。
+//
+// 一个 Cordis 插件：把本包内 `skills/courseware` 注册进 `ctx.skills` 注册表
+// 的 host 层，使 profile 里每个 agent 的技能目录都能看到并加载它。
+// 技能正文随包分发（`../skills/<name>/SKILL.md`），提供器用
+// `import.meta.url` 定位（包的组装事实，不是用户配置），按需读取正文。
+//
+// 提供器协议对齐 @deepseek-ai/dsh-skill-filesystem：
+//   - list()  扫描 skills/ 下的目录型技能（name/description/whenToUse 从
+//             YAML frontmatter 读取，正文留到 get() 才读）
+//   - get()   解析获胜候选的 SKILL.md，返回完整定义，resourceBase 指向
+//             技能目录，使相对引用（workflows/、references/）可以解析
+//
+// 零运行时依赖：只使用 Node 内置模块。frontmatter 解析只覆盖 DSH 技能
+// 发现消费的标量字段（name/description/whenToUse），并支持 `>` 折叠块。
+//
+// @module dsh-courseware
+import { readdir, readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const name = 'dsh-courseware'
+const inject = ['skills']
+
+/** 打包技能提供器的注册优先级：低于本地 bundled 根（600），高于用户层默认。 */
+const PACKAGED_SKILL_RANK = 550
+
+/** 这批技能对外声明的来源桶（prompt 可见元数据）。 */
+const SOURCE = 'custom'
+
+/**
+ * 解析 SKILL.md 的 YAML frontmatter 块，返回元数据 + 正文。
+ * 只处理 DSH 技能发现消费的标量字段（name/description/whenToUse），
+ * 支持 `key: value`（含引号）、`key: >` 折叠块、`key: |` 字面块；
+ * 缩进的嵌套键（如 `metadata: version: "1.0.0"`）扁平化进 metadata，
+ * 不深度解析。
+ * @param text - 技能文件原始内容。
+ * @returns 解析出的元数据与正文；文件没有 frontmatter 块时返回 null。
+ */
+function parseFrontmatter(text) {
+  if (!text.startsWith('---')) return null
+  const end = text.indexOf('\n---', 3)
+  if (end === -1) return null
+  const block = text.slice(3, end)
+  const body = text.slice(end + 4).replace(/^\n+/, '')
+  const metadata = {}
+  const lines = block.split('\n')
+  let key = null
+  let mode = null // null | '>' | '|'
+  let pending = null
+  const commit = () => {
+    if (key === null) return
+    metadata[key] = mode === '>' ? pending.join(' ').replace(/\s+/g, ' ').trim()
+      : mode === '|' ? pending.join('\n')
+      : pending
+    key = null; mode = null; pending = null
+  }
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (trimmed === '' || trimmed.startsWith('#')) {
+      if (mode !== null) pending.push('')
+      continue
+    }
+    const match = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(trimmed)
+    const indented = line.startsWith(' ') || line.startsWith('\t')
+    if (match && !indented) {
+      commit()
+      key = match[1]
+      const value = match[2].trim()
+      if (value === '>') { mode = '>'; pending = [] }
+      else if (value === '|') { mode = '|'; pending = [] }
+      else {
+        mode = null; pending = value
+        if ((pending.startsWith('"') && pending.endsWith('"'))
+            || (pending.startsWith("'") && pending.endsWith("'"))) {
+          pending = pending.slice(1, -1)
+        }
+      }
+    } else if (mode !== null && pending !== null) {
+      // 折叠/字面块的续行：接在上一行后面
+      pending.push(trimmed)
+    } else if (match) {
+      // 缩进的嵌套键：扁平化进 metadata（不深度解析）
+      let value = match[2].trim()
+      if ((value.startsWith('"') && value.endsWith('"'))
+          || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1)
+      }
+      metadata[match[1]] = value
+    }
+  }
+  commit()
+  return { metadata, body }
+}
+
+/**
+ * 读取并解析一个技能目录的 SKILL.md。
+ * @param skillFile - SKILL.md 的绝对路径。
+ * @param signal - 可选的取消信号，中止读取。
+ * @returns 解析后的技能记录；文件消失时返回 undefined。
+ */
+async function parseSkillFile(skillFile, signal) {
+  let text
+  try {
+    text = await readFile(skillFile, 'utf8')
+  } catch {
+    return undefined
+  }
+  if (signal?.aborted) return undefined
+  const parsed = parseFrontmatter(text)
+  if (parsed === null) return undefined
+  return {
+    name: parsed.metadata.name ?? '',
+    description: parsed.metadata.description ?? '',
+    whenToUse: parsed.metadata.whenToUse,
+    metadata: parsed.metadata,
+    content: parsed.body,
+  }
+}
+
+/**
+ * 扫描本包 `skills/` 目录发现候选技能：每个子目录一个技能，内含 SKILL.md。
+ * @param skillsRoot - 本包 skills 目录的绝对路径。
+ * @param signal - 可选取消信号。
+ * @returns 候选列表。
+ */
+async function discoverCandidates(skillsRoot, signal) {
+  let entries
+  try {
+    entries = await readdir(skillsRoot, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const candidates = []
+  for (const entry of entries) {
+    if (signal?.aborted) break
+    if (!entry.isDirectory()) continue
+    const skillDir = join(skillsRoot, entry.name)
+    const skillFile = join(skillDir, 'SKILL.md')
+    const parsed = await parseSkillFile(skillFile, signal)
+    if (parsed === undefined) continue
+    candidates.push({
+      name: parsed.name,
+      description: parsed.description,
+      ...(parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {}),
+      invocation: { modelInvocable: true, userInvocable: true },
+      source: SOURCE,
+      provider: name,
+      rank: PACKAGED_SKILL_RANK,
+      locator: skillDir,
+      path: skillFile,
+      ...(Object.keys(parsed.metadata).length > 0 ? { metadata: parsed.metadata } : {}),
+    })
+  }
+  return candidates
+}
+
+/** 把本包技能注册进 `ctx.skills`。 */
+function apply(ctx) {
+  const skillsRoot = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills')
+  ctx.skills.registerProvider((control) => ({
+    name,
+    async list(options) {
+      return discoverCandidates(skillsRoot, options.signal)
+    },
+    async get(candidate, options) {
+      const parsed = await parseSkillFile(candidate.path, options.signal)
+      if (parsed === undefined) return undefined
+      return {
+        name: parsed.name,
+        description: parsed.description,
+        ...(parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {}),
+        invocation: { modelInvocable: true, userInvocable: true },
+        source: SOURCE,
+        provider: name,
+        resourceBase: { kind: 'directory', path: candidate.locator },
+        path: candidate.path,
+        ...(Object.keys(parsed.metadata).length > 0 ? { metadata: parsed.metadata } : {}),
+        content: parsed.content,
+      }
+    },
+  }))
+}
+
+export { apply, name, inject, parseFrontmatter }
+export default { apply, name, inject }

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "dsh-courseware",
+  "description": "中小学课件生成技能包：拿用户自己的 .pptx 模板 + 课程大纲，产出套用模板风格的多页课件。由 DeepSeek Harness 的 courseware 技能 + pptxgen 引擎打包而成。",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "skills",
+    "engine",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "skill",
+    "courseware",
+    "pptx",
+    "课件"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/skills/courseware/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: courseware
+description: >
+  面向中小学课堂的课件生成工作流：拿用户自己的 .pptx 模板 + 一份课程大纲（教案/文档/纯文本），
+  产出套用该模板背景、配色、字体、页面骨架的课件 .pptx。支持多母版模板、配图生成、
+  思维导图页、随堂练习与答案页、讲稿备注。当用户要求「用这个模板做一份课件 / 把这节课的教案
+  做成 PPT / 生成上课用的幻灯片」，或提到 courseware、课件、教案转 PPT 时使用。
+metadata:
+  version: "1.0.0"
+  engine: pptxgen
+  license: MIT
+---
+
+# Courseware —— 中小学课件生成
+
+用**用户自己的模板**生成课件，而不是从零设计。本文件只负责**路由**与**全局纪律**；
+每个路线的具体步骤由它自己的流程文件拥有。
+
+## 硬规则 —— 引擎位置
+
+引擎（Python 包 `pptxgen` + 它的 venv）**随本 skill 一起分发**，位于
+技能基础目录的**上两级**：`<技能基础目录>/../../engine`。技能基础目录 =
+本文件所在目录（agent 会从资源提示 "Base directory for this skill" 拿到它）。
+
+引擎目录判定（按顺序取第一个成立的）：
+
+1. `<技能基础目录>/../../engine`（本插件包自带的引擎）
+2. 环境变量 `PPTXGEN_ENGINE_HOME` 指向的目录（用户可自指引擎）
+
+**都不存在 → 报告并停止，不要搜索、不要新建 venv、不要猜测路径。**
+
+首次使用需初始化 Python 虚拟环境（一次性，目标机器需有 Python 3.10+）：
+
+```bash
+python3 -m venv "<引擎目录>/.venv"
+"<引擎目录>/.venv/bin/pip" install -r "<引擎目录>/requirements.txt"
+```
+
+调用方式（**可在任意工作目录执行**，引擎目录会自动加入 PYTHONPATH）：
+
+```bash
+"$ENGINE_HOME/pptxgen.sh" <命令>
+```
+
+其中 `ENGINE_HOME` 为上面判定出的引擎目录。若当前工作目录下就有
+`"$ENGINE_HOME/pptxgen.sh"`，优先用它（在引擎目录里开发时）。
+
+### 引擎目录 vs 工作目录
+
+这是两回事，不要混：
+
+| | 位置 | 内容 | 是否变动 |
+|---|---|---|---|
+| **引擎目录** | `$ENGINE_HOME` | `pptxgen/` 源码、`.venv/`、内置示例 | 固定不动 |
+| **工作目录** | 当前项目 | `templates/`（模板）、`decks/`（课件规格）、`out/`（产物） | 每门课可新建一个 |
+
+在**工作目录**下要有 `templates/` 与 `decks/` 两个子目录；没有就建。
+所有 `inspect` / `build` / `check` 的路径参数都相对**工作目录**解析。
+
+## 硬规则 —— 先诊断模板
+
+**在写任何课件内容之前，必须先跑 `inspect`。** 模板的母版数量、页面骨架、真实字体
+都只能从样张里读出来；跳过这一步会套错整套配色与背景。
+
+```bash
+"$ENGINE_HOME/pptxgen.sh" inspect "templates/用户的模板.pptx"
+```
+
+把输出里的三块读给用户确认：**母版**、**样式档案**、**页型→版式映射**。
+
+## 路由
+
+| 用户意图 | 路线 | 权威流程 |
+|---|---|---|
+| 用模板 + 大纲生成新课件 | **Generate** | [`workflows/generate.md`](workflows/generate.md) |
+| 同上，但明确说"快一点、不用确认" | **Quick** | [`workflows/quick.md`](workflows/quick.md) |
+| 只想让工具认一认模板 / 检查模板可用性 | **Template Intake** | [`workflows/template-intake.md`](workflows/template-intake.md) |
+| 已有课件，想改内容 / 加配图 / 换模板 | **Revise** | [`workflows/revise.md`](workflows/revise.md) |
+
+选择唯一一条路线，然后只加载该路线拥有的流程文件。子流程与参考文档**不是**顶层路线。
+
+**不要给用户列路线菜单。** 请求已匹配上表某一行时，直接进入该路线。
+
+## 全局纪律
+
+1. **串行执行** —— 按所选流程的步骤顺序走，不要跳步或并行准备。
+2. **闸门处停下** —— 遇到 `⛔ 闸门` 必须等用户明确确认，不要替用户决定。
+3. **不投机执行** —— 后续阶段的产物不要在它所属的步骤之前生成。
+4. **失败在所属层修复** —— 单页问题改页面；大纲问题改大纲；引擎问题改引擎。
+   不要用"换一页"来掩盖引擎缺陷。
+5. **不静默降级** —— 配图生成失败、模板版式缺失、字号缩到下限，都必须显式报告，
+   不要悄悄跳过。
+6. **改版面前先落锚点** —— 调整排版参数前把生成的 pptx 复制一份到
+   `out/_backup/`，改完对比不过就回滚。
+
+## 质量闭闸
+
+任何路线在交付前，必须跑完下面三条并**把原始输出贴给用户**：
+
+```bash
+"$ENGINE_HOME/pptxgen.sh" check "out/xxx.pptx" --render
+"$ENGINE_HOME/pptxgen.sh" review "decks/xxx.yaml" --pptx "out/xxx.pptx"
+"$ENGINE_HOME/pptxgen.sh" preview "out/xxx.pptx" -o out/preview
+```
+
+`check --render` 用真实渲染结果检查文字重叠与越界，并做 OOXML Schema 严格校验
+（PowerPoint 同源规则）——这是**可证伪的证据**，不是自我评估。它报 0 问题才算闭闸。
+
+`review` 是设计审查：版式多样性（相邻页不得同型）、信息密度下限、视觉锚点、
+润色落实（关键词高亮 / 图注 / 长列表分块），规则见
+[`references/design-review.md`](references/design-review.md)。
+
+两者都通过后才交付；报问题则按「读全量 → 一次合并修复 → 单次复跑」处理，不要逐个试。
+
+## 已知短板
+
+我们**没有**吸收 ppt-master 的全部能力。能力对照、差距与取舍理由见
+[`references/roadmap.md`](references/roadmap.md) —— 用户问"为什么不如某某工具"时读它，
+不要含糊其辞。
+
+最要紧的三条：
+- 没有 SVG 自由版面层 → 版面受模板约束，不能任意设计
+- 没有图片搜索与许可合规 → 只有 AI 生成这一条配图来源
+- 没有原生图表/表格/公式 → 表格只能用文字或图片表达
+
+## 输出约定
+
+- 生成的课件放在 `out/<课件名>.pptx`
+- 预览图放在 `out/preview/`，总览图是 `out/preview/_总览.png`
+- 交付时**必须**告诉用户：页数、`check --render` 结果、预览图路径

package/skills/courseware/references/content-polish.md

@@ -0,0 +1,121 @@
+# 内容润色（讲义式润色）
+
+**权威来源**：从一份优秀的同题成品（同一模板、同一教案）逆向总结出来的写法。
+模板骨架一律不动——只把**教案文字**加工成**能直接投屏讲课的讲义文字**。
+
+> 核心判据：把教案原句直接贴上去 = 不及格。每一页都要看得见下面六件事里的至少三件。
+
+---
+
+## 一、六个动作
+
+### 1. 标题二次创作（不照抄教案标题）
+
+教案标题是给老师看的，页面标题是给学生看的。改成**短、具体、有钩子**的说法。
+
+| 教案原句 | 润色后 |
+|---|---|
+| 雷达是怎么工作的？ | 雷达工作的三步 |
+| 怎么看雷达图？ | 看懂雷达回波图 |
+| 多普勒雷达 | 多普勒雷达：还能测出快慢 |
+| 揭晓答案 | 答案揭晓 |
+| 它们像哪种天气探测设备？ | 猜一猜，他们像哪种设备？ |
+| 手摇式仪器：看清台风的路径 | 动手做：手摇式台风路径仪 |
+| 卫星云图告诉我们什么？ | 卫星云图能告诉我们什么 |
+
+### 2. 每页一句导语（`subtitle`）
+
+紧跟标题、15pt 左右、灰调颜色。**一句话说清这一页要干什么**，常用"公式/类比/悬念"。
+
+- 发射 → 散射 → 接收，一个来回就完成了一次探测
+- 看颜色，就能大致读出降水的强弱
+- 看形态、看结构、看亮度、看纹理——云图上藏着一整天的天气
+- 跟着两位「神仙」，一起去认识气象卫星和气象雷达
+- 跟着说明书动手做一台仪器，看看卫星监测到的台风会怎么走。
+
+### 3. 分块小标题（把长列表拆成 2–3 块）
+
+一段 5 条以上的要点，学生记不住。拆成带小标题的块，每块 2–4 条：
+
+- 一句话说清楚 / 它是怎么做到的
+- 它们在天上做什么
+- 科学家这样看云图
+- 怎么测出速度 / 怎么测出距离 / 本领更强
+
+引擎里用 `pattern: cards`（每张卡=一个块，卡标题=小标题）或 `pattern: steps` 实现。
+
+### 4. 关键词内嵌着色（**最重要的一条**）
+
+整句保持正文色，**只把术语染色加粗**。这是"讲义感"的主要来源。
+
+```yaml
+- text: 雷达是**无线电探测**，即用无线电的方法发现目标，并测定它们在空间的位置。
+- text: 当电磁波探测到物体时，电磁波会**散射回到雷达接收器**处。
+- text: 于是在雷达荧光屏上，回波的亮度就不一样——**越亮，说明水滴直径越大**。
+- text: 按**形态、结构**识别云的种、属
+```
+
+`**…**` 由引擎渲染成"模板标题色 + 加粗"，其余文字保持正文色。
+
+### 5. 口语化 + 类比 + 记忆钩子
+
+- 就像站得越高、看得越远
+- 隔着高山大海，也能听见千里之外的声音
+- 回来的时间越久，说明目标离我们越远
+- 它「看」得又远又广，一次能看遍大半个地球
+- 记住两个关键词：发射、回波
+- 颜色由冷到暖，降水由弱到强
+
+术语用 `「」` 括起（「神仙」「风云」「多普勒效应」），与强调色区分开。
+
+### 6. 结论块 / 提示块 / 图注 / 手册指引
+
+| 元素 | 写法 | 引擎实现 |
+|---|---|---|
+| 结论色块 | 深色底 + 白色粗体一句话 + 一行小字解释 | `pattern: callout` |
+| 提示条 | "小提示：…" / "! 发射和回波之间的时间差，就是雷达测距离的秘密" | callout 的第二段或 bullets |
+| 图注 | 图下方一句"这张图在说什么" | `image_caption` |
+| 手册指引 | "请在手册第 15 页，把答案写下来" | bullets 里的一条 |
+| 视频卡 | "▶ 播放动画片段" + 片名 + 时长 | bullets 里的一条 |
+| 呼应页 | 结束页写"回顾手册第 15、16 页""别忘了整理实验台" | end 页 `subtitle` / items |
+
+---
+
+## 二、字号层级（相对值，最终由模板决定）
+
+| 用途 | 参考字号 | 颜色 |
+|---|---|---|
+| 封面/结束页大标题 | 51–61pt | 模板标题色 |
+| 页面标题 | 24pt | 模板标题色（深） |
+| 卡片小标题 | 15–18pt | 模板强调色（亮） |
+| 导语 / 金句 | 15pt | 中间调 |
+| 正文 | 13.5–14.25pt | 近黑正文色 |
+| 图注 / 次要说明 | 11.25–12.75pt | 灰调 |
+| 页脚页码 | 11.25pt | 反白或灰调 |
+
+**颜色只有一个来源：模板。** 同一个模板里所有颜色都是模板主色的深浅阶梯
+（深色标题 / 亮色强调 / 近黑正文 / 灰调注释），不要引入模板之外的颜色
+（内容本身有语义色的除外，例如雷达回波图的绿-黄-红）。
+
+---
+
+## 三、页面级骨架
+
+1. **封面**：课题 + 板块 + 第几课 + 授课年级 + 系列名
+2. **本课导航页**（教案里的"知识/能力/素养目标"→ 01/02/03 三张卡）
+3. 正文页：`module` 模块标签 + 标题条 + 导语 + 分块内容 + 配图
+4. **结束页**：一句话课程口号（"千里眼看天，顺风耳听雨"）+ 回顾清单 + 系列名
+
+---
+
+## 四、交付前自检清单
+
+- [ ] 有没有哪一页的标题是**直接抄教案**的？→ 改写
+- [ ] 每页有没有**导语**？
+- [ ] 超过 5 条要点的页面，**分块**了吗？
+- [ ] 每页至少有 **1–2 处 `**关键词**`** 强调？
+- [ ] 有没有至少一处**类比或记忆钩子**？
+- [ ] 结论/难点页有没有**色块**突出？
+- [ ] 有图的页有没有**图注**（图在说什么）？
+- [ ] 教案提到手册页码的地方，页面上有没有**指引**？
+- [ ] 颜色是否**全部来自模板**（有无野色）？

package/skills/courseware/references/deck-spec.md

@@ -0,0 +1,155 @@
+# 参考：课件规格（YAML）字段全表
+
+规格文件是**唯一的课件内容来源**。工具只负责排版，不生成内容。
+
+## 顶层
+
+```yaml
+deck:                       # 或 meta:
+  title: 小小气象预报员
+  subtitle: 气象生活板块 · 气象与生活
+  subject: 科学
+  grade: 三、四年级
+  teacher: 王老师
+  school: 阳光小学
+  date: 2025年 春
+
+template: ../templates/第1课 神奇的天气魔法.pptx   # 相对本文件所在目录
+
+options:
+  answer_mode: end          # end | inline | none
+  page_numbers: true
+  page_number_start: 1
+  chrome: auto              # auto | off，模板装饰层
+  style_profile: auto       # auto | off，从样张学到的页面骨架
+  fit_shrink_floor: 0.62    # 文字放不下时最多缩到原字号的百分比
+  auto_toc: false
+  images:                   # 配图设置，见 references/image-backends.md
+    backend: openai-compatible
+    cache_dir: ../out/images
+    size: "1024x1024"
+    style: 儿童科普插画风格，扁平化矢量插画，…
+
+layout_map:                 # 覆盖页型→版式映射（见 template-fidelity.md）
+  cover: "封面"
+  content: 13
+
+slides:                     # 页面列表
+  - type: cover
+    ...
+```
+
+## 页型与字段
+
+| type | 中文别名 | 字段 |
+|---|---|---|
+| `cover` | 封面 | `title` `subtitle` `teacher` `school` `date` |
+| `toc` | 目录 | `title` `items[]` |
+| `section` | 章节/过渡 | `title` `subtitle` `items[]`（`index` 自动编号） |
+| `objectives` | 目标/重难点 | `title` `goals[]` `key_points[]` `hard_points[]` |
+| `content` | 知识点/正文 | `title` `subtitle` `bullets[]` `image` `images[]` `image_side` `image_caption` |
+| `example` | 例题 | `title` `bullets[]`(题干) `steps[]`(步骤，自动编号) |
+| `practice` | 练习/检测 | `title` `bullets[]`(说明) `questions[{q,options[],answer,analysis}]` |
+| `summary` | 小结/思维导图 | `title` `mindmap{center,branches[]}` 或 `points[]` |
+| `homework` | 作业 | `title` `items[]` `note` |
+| `end` | 结束页 | `title` `subtitle` |
+
+**所有页型都支持**：`module`（左上角模块标签文字）、`note`（讲稿备注）、
+`image_prompt` + `image_side`（配图）、`layout`（手工指定版式）、`chrome`（false 关闭该页装饰层）。
+
+### 版面骨架 `pattern`（content / example 页）
+
+同一份模板里，正文区可以有多种排法，避免每页都是"左文右图"一个样子。
+**模板骨架不变**：背景、装饰带（如左侧色带/渐变）、模块标签、标题条、主色与字体
+全部沿用模板——**换成紫色模板就是紫色，换成深色模板就自动用浅色文字**。
+pattern 只重排正文区，选色一律从模板主题色/样式档案里取，不写死颜色。
+不写 `pattern` 时按内容自动判断（步骤型文字自动用 `steps`）。
+
+| pattern | 适用内容 | 用到的字段 |
+|---|---|---|
+| `bullets` | 一般要点（默认，左文右图） | `bullets[]` |
+| `steps` | 有先后顺序的步骤（第1步/第2步…），卡片 + 向下箭头 | `steps[]` 或 `bullets[]` |
+| `flow` | 2–5 个环节的流程，横向方框 + 箭头 | `steps[]` 或 `bullets[]` |
+| `compare` | A 与 B 的对照，左右两栏 + 中间圆标 | `compare{left,right,vs}` |
+| `cards` | 并列要点，卡片网格（2–6 张） | `cards[]` 或 `bullets[]`（一级=标题，二级=内容） |
+| `timeline` | 先后/因果，横向时间轴（上下交错） | `timeline[{time,text}]` |
+| `callout` | 一个核心问题/结论 + 若干要点 | `key`（默认取第一条要点）或 `bullets[]` |
+| `image_left` / `image_right` | 只是把配图换到左边/右边 | `image_side` |
+
+```yaml
+- type: content
+  module: 科学概念
+  title: 雷达是怎么工作的？
+  pattern: flow
+  bullets:                     # 一级=一个环节，二级=补充说明
+    - text: 第一步：发射
+      level: 0
+    - text: 天线向空中发射电磁波
+      level: 1
+    # …
+
+- type: content
+  title: 揭晓答案
+  pattern: compare
+  compare:
+    vs: ↔
+    left:  { title: 千里眼 → 气象卫星, items: [在太空"看"地球] }
+    right: { title: 顺风耳 → 天气雷达, items: [发出无线电波"听"回声] }
+
+- type: content
+  title: 雷达是跟蝙蝠学的吗？
+  pattern: timeline
+  timeline:
+    - { time: 千万年前, text: 蝙蝠演化出回声定位 }
+    - { time: 19 世纪,  text: 人类发现电磁波 }
+```
+
+选型建议：**同一份课件里不要连续三页用同一种 pattern**；递进用 `steps`/`flow`，
+对照用 `compare`，并列用 `cards`，先后用 `timeline`，其余保持 `bullets`。
+pattern 渲染失败会自动退回 `bullets` 并在生成报告里给出「注意」提示。
+
+### bullets 的写法
+
+```yaml
+bullets:
+  - 一级要点                    # 简写
+  - text: 一级要点
+    level: 0
+  - text: 二级要点（自动缩进换符号）
+    level: 1
+```
+
+### questions 的写法
+
+```yaml
+questions:
+  - q: 下列图标中，表示"晴"的是？
+    options: [A. 晴天, B. 多云, C. 雨天]     # 或分行写
+    answer: A
+    analysis: 太阳图标表示晴天，云量很少。
+```
+
+`options` 里带 `A.` / `B、` 前缀时会自动渲染成圆形字母徽标。
+选项短且放得下时自动横排，否则竖排。
+
+### mindmap 的写法
+
+```yaml
+mindmap:
+  center: 小小气象预报员
+  branches:
+    - title: 获取途径
+      items: [手机, 网络, 报纸, 电台电视]
+    - title: 五大环节
+      items: [气象观测, 数据收集, 综合分析, 预报会商, 预报发布]
+```
+
+分支数建议 3–6 个，每个分支 items 2–5 个。
+
+## 写内容的原则
+
+1. **一页一个知识点**。要点 3–6 条，每条不超过 ~40 个汉字。
+2. **标题条要短**。超过约 24 个汉字会被压字号。
+3. **`note` 写讲稿**，不要写进正文 —— 正文是给学生看的，讲稿是给老师看的。
+4. **模块名用教案里的原词**，不要自创（"科学解释"而不是"知识讲解"）。
+5. **教案里标了页码节奏（P2-3、P4）就照它切**。