dsh-courseware 0.1.0

package/skills/courseware/workflows/revise.md

@@ -0,0 +1,40 @@
+# Revise —— 改已有课件
+
+已有规格 YAML 或已生成的 pptx，要改内容 / 加配图 / 换模板。
+
+## 判定改哪里
+
+| 用户要求 | 改什么 | 重跑到哪一步 |
+|---|---|---|
+| 改某页文字 / 加减要点 | `decks/xxx.yaml` 对应页 | 步骤 5（build）起 |
+| 加/换配图 | `image_prompt` | 步骤 4（images）起 |
+| 换模板 | `template:` 字段 | **步骤 1（inspect）重跑** |
+| 调页序 / 拆页 / 并页 | `slides:` 列表 | 步骤 3 起，需要重新过闸门 |
+| 改答案位置 | `options.answer_mode` | 步骤 5 起 |
+| 改页码 / 装饰层开关 | `options` | 步骤 5 起 |
+
+**换模板必须从步骤 1 重走** —— 新模板的母版数、骨架、字体都可能不同，
+旧的内容编排可能不再合适。
+
+## 步骤
+
+1. **读现有 YAML**，确认结构完整（`deck` / `template` / `options` / `slides`）
+2. **只改需要改的字段**，不要顺手重排其它页
+3. **如果改了页序或页数** → 回到 [`generate.md`](generate.md) 的 `⛔ 闸门 1` 确认
+4. 重跑 `build`
+5. **重跑质量闭闸**（`check --render`）—— 改动可能引入新的重叠
+
+## 纪律
+
+- **不要重新生成整份 YAML**。增量修改，保留用户已经确认过的内容。
+- **改动前后各留一个副本**到 `out/_backup/`，便于对比和回滚。
+- **报告改了什么**：逐条列出，不要只说"已修改"。
+
+## 常见陷阱
+
+| 陷阱 | 后果 | 避免 |
+|---|---|---|
+| 换了模板没重跑 inspect | 套错母版，背景字体全不对 | 强制重跑步骤 1 |
+| 加了要点没重跑 check | 文字溢出/重叠 | 强制重跑闭闸 |
+| 改了 `image_prompt` 没重跑 images | 用的是旧图（prompt 哈希缓存） | 重跑 `images`，必要时 `--force` |
+| 直接编辑生成的 pptx | 下次 build 会被覆盖 | 只改 YAML，改 pptx 的改动要么回写 YAML 要么明确告知会被覆盖 |

package/skills/courseware/workflows/routing.md

@@ -0,0 +1,49 @@
+# 路由规则
+
+**权威**：本文件是路线选择的唯一权威。与 `SKILL.md` 或任何其它文档冲突时，以本文件为准。
+
+## 路线矩阵
+
+| 路线 | 请求形态 | 前置条件 | 权威流程 |
+|---|---|---|---|
+| **Generate** | 用模板 + 大纲生成新课件 | 有模板 pptx；有大纲；已跑 `inspect` | [`generate.md`](generate.md) |
+| **Quick** | 同上，且用户明确说"快一点/不用确认/直接出" | 同 Generate | [`quick.md`](quick.md) |
+| **Template Intake** | 只诊断模板、检查可用性、解决模板问题 | 有模板 pptx | [`template-intake.md`](template-intake.md) |
+| **Revise** | 已有课件要改内容/加配图/换模板 | 有规格 yaml 或已有 pptx | [`revise.md`](revise.md) |
+
+## 纪律
+
+- **选一条路线**，然后只加载该路线拥有的流程文件。
+- **不给用户列路线菜单**。请求已匹配上表某一行时直接进入。
+- **前置条件缺失时报告并停止**，不要发明替代路径。
+  - 没模板 → 问用户要，不要用内置模板冒充
+  - 没大纲 → 问用户要，不要编造课程内容
+- **支持文档不是顶层路线**。`stages/` 与 `references/` 只精化已选路线。
+
+## 判定辅助
+
+| 用户话术 | 判定 |
+|---|---|
+| "用这个模板做第 2 课" | Generate |
+| "快一点，别问我了" / "直接出" | Quick |
+| "先看看这个模板能不能用" | Template Intake |
+| "这份 PPT 帮我改一下第 5 页" | Revise |
+| "把教案做成 PPT"（未给模板） | 先问模板；给不出则 Template Intake 报告缺模板 |
+| "帮我做个 PPT"（无模板无大纲） | 追问两者；两者都无 → 报告无法执行 |
+
+## Quick 与 Generate 的差别
+
+| | Generate | Quick |
+|---|---|---|
+| 大纲确认闸门 | ⛔ 必须 | 跳过，agent 自行决定 |
+| 交付确认闸门 | ⛔ 必须 | 报告结果即可 |
+| 输出 | 完整流程 | 同样完整，只是少了两次交互 |
+| **不省略** | — | `inspect`、质量闭闸、结果报告 |
+
+**Quick 不是"低质量模式"**，只是"少问两次"。质量闭闸在任何模式下都不能跳过。
+
+## 与 ppt-master 的一个关键差异
+
+ppt-master 的 Quick 会丢掉 spec/lock 规划与部分质量门禁，靠"current agent
+自行决定"填补 —— 这在长对话里容易失控。本 skill 的 Quick **只砍交互，不砍检查**：
+`inspect` 与 `check --render` 在两条路线里都是强制的。

package/skills/courseware/workflows/stages/generate-images.md

@@ -0,0 +1,74 @@
+# Stage：配图生成
+
+课件里写了 `image_prompt` 的页面需要这一步。没有 `image_prompt` 就跳过。
+
+## 三步走（顺序不能变）
+
+```bash
+# 1) 先看会生成几张、什么 prompt —— 不发任何请求，不花钱
+"$ENGINE_HOME/pptxgen.sh" images "decks/xxx.yaml" --dry-run
+
+# 2) 只试 2 张，确认画风对不对 —— 别一次出 14 张才发现风格不合
+"$ENGINE_HOME/pptxgen.sh" images "decks/xxx.yaml" --limit 2
+
+# 3) 满意后全量
+"$ENGINE_HOME/pptxgen.sh" images "decks/xxx.yaml"
+```
+
+**`--limit 2` 是强制习惯**，不是可选项。生图按张计费，风格错了就是纯浪费。
+
+## 用占位图先验证版面
+
+用户还没配图像模型 key 时，**不要让流程卡住**：
+
+```bash
+"$ENGINE_HOME/pptxgen.sh" images "decks/xxx.yaml" --backend mock
+"$ENGINE_HOME/pptxgen.sh" build "decks/xxx.yaml"
+```
+
+`mock` 出的是本地生成的渐变色块，**不联网不花钱**，用来判断
+"图片放右侧、正文缩到 24pt" 这个版面合不合适。
+
+交付时**必须明确告诉用户这是占位图**，并给出配 key 的方法：
+
+```
+这批图是本地占位图，不是真实配图。换成真图：
+  1. 编辑 .pptxgen.yaml，填 base_url / model / api_key
+  2. "$ENGINE_HOME/pptxgen.sh" images "decks/xxx.yaml"
+  3. "$ENGINE_HOME/pptxgen.sh" build "decks/xxx.yaml"
+```
+
+**禁止**把占位图当成品交付而不说明。
+
+## 写 image_prompt 的方法
+
+| 要素 | 例子 |
+|---|---|
+| 主体 | 一间电视天气预报演播室 |
+| 细节 | 主持人站在大幅天气图前，屏幕上有云朵和太阳图案 |
+| 风格 | 交给全局 `style` 统一控制，**不要每页重复写** |
+
+好 prompt 的特征：
+- **具体可画**："孩子们的小手在剪纸、涂色、粘贴" 优于 "动手实践"
+- **一个画面一件事**：不要在一张图里塞三个场景
+- **不要求画面出文字**（全局 style 已声明"不要出现文字"，因为模型写的字通常是错的）
+
+## 缓存与成本
+
+- 按 `(后端, 模型, 尺寸, prompt, 风格)` 的哈希缓存到 `out/images/`
+- **同样的 prompt 重跑不重复计费**
+- 改了 prompt 会生成新图，旧图仍在缓存里（不浪费，可回退）
+- `--force` 强制重生成
+
+渲染阶段只读 `out/images/manifest.json`，**不需要 key** —— 换机器生成课件也能复用已出的图。
+
+## 失败处理
+
+| 症状 | 处理 |
+|---|---|
+| 缺 API key | 明确告知配置方法；不要静默跳过 |
+| 单张生成失败 | 报告是第几页、什么错；其余页继续 |
+| 全部失败 | 停下来查后端配置，不要重试到死 |
+| 配额/限流 | 报告并建议稍后重试；不要无限重试 |
+
+后端清单见 [`references/image-backends.md`](../../references/image-backends.md)。

package/skills/courseware/workflows/template-intake.md

@@ -0,0 +1,112 @@
+# Template Intake —— 模板诊断与修复
+
+只诊断模板，不产出课件。用户拿来一个新模板、或课件效果不对时走这条路线。
+
+## 步骤 1 —— 基础诊断
+
+```bash
+"$ENGINE_HOME/pptxgen.sh" inspect "templates/xxx.pptx"
+```
+
+必读四段，判断模板是否可用：
+
+| 段落 | 看什么 | 不可用的表现 |
+|---|---|---|
+| 画布尺寸 | 4:3 还是 16:9 | — |
+| **母版** | 几个母版、主母版是哪个 | 全部示例页挂在同一个母版上 → 只有一个真正可用 |
+| **样式档案** | 模块标签 / 标题条 / 内容区 / 正文排版 | 整个「样式档案：未学到」→ 模板不靠骨架，只靠版式 |
+| **版式列表** | 有没有「标题=有 正文=有」的版式 | 全部版式都没有占位符 → 需要手工定版式 |
+
+再跑一次看映射：
+
+```bash
+"$ENGINE_HOME/pptxgen.sh" inspect "templates/xxx.pptx" --map
+```
+
+## 步骤 2 —— 判定模板类型
+
+| 类型 | 特征 | 后续 |
+|---|---|---|
+| **骨架型** | 样式档案学到了模块标签/标题条 | 最理想，`generate.md` 直接可用 |
+| **版式型** | 样式档案未学到，但版式齐全（标题+正文） | 可用，靠版式渲染 |
+| **图片型** | 每页是一整张设计图，无版式无骨架 | 需人工指定内容区，见步骤 4 |
+| **空壳型** | 没有任何示例页 | `inspect` 的装饰层与骨架全空，只能继承母版背景 |
+
+## 步骤 3 —— 视觉验证（推荐）
+
+```bash
+"$ENGINE_HOME/pptxgen.sh" build "decks/<示例>.yaml" -t "templates/xxx.pptx" -o out/_tpltest.pptx
+"$ENGINE_HOME/pptxgen.sh" preview out/_tpltest.pptx -o out/_tplcheck
+```
+
+用内置示例课件 `examples/示例课件_分数的初步认识.yaml` 当探针，渲染出来看：
+背景、配色、页面骨架是否和模板自己的页面一致。
+
+**不做这一步就下结论是危险的** —— XML 层面一致不代表渲染一致
+（多母版问题就是这样漏掉的）。详见 [`template-fidelity.md`](../references/template-fidelity.md)。
+
+## 步骤 4 —— 修复分支
+
+### 4a. 版式选错了
+
+在课件 YAML 里覆盖：
+
+```yaml
+layout_map:
+  cover: "封面页"      # 版式名，支持部分匹配
+  content: 13          # 或全局版式序号
+```
+
+或单页指定：
+
+```yaml
+- type: content
+  layout: "两栏内容"
+  title: …
+```
+
+全局版式序号从 `inspect` 的版式列表读（多母版时序号跨母版连续）。
+
+### 4b. 装饰层没识别到
+
+```bash
+"$ENGINE_HOME/pptxgen.sh" inspect "templates/xxx.pptx" --json | python -c "
+import json,sys; d=json.load(sys.stdin)
+print('装饰层:', [c['name'] for c in d['global_chrome']])
+print('幻灯片级背景覆盖:', d['slide_background_override'])
+"
+```
+
+识别不到的原因通常是「每页装饰都不一样」—— 那不是模板的一部分，正常。
+
+### 4c. 骨架学错了位置
+
+编辑 `workflows/` 之外的参数：在课件 YAML 里关掉骨架，回到纯版式渲染：
+
+```yaml
+options:
+  style_profile: off
+```
+
+### 4d. 图片型模板
+
+每页一整张设计图、没有版式时，只能：
+1. 在 `inspect` 里确认内容区（白区）范围
+2. 用 `image_side: right` 等字段手工排版
+3. 明确告诉用户：这类模板的排版自由度受限
+
+## 步骤 5 —— 报告
+
+给用户：
+
+```
+模板：<路径>
+类型：骨架型 / 版式型 / 图片型 / 空壳型
+母版：2 个，主母版 master2（24/25 页在用）
+骨架：模块标签 23 页重复 / 标题条 10 页重复
+正文：微软雅黑 28pt（从样张学到）
+映射：封面→master1，内容→master2，结束页→自定义版式
+可用性：✅ 可直接生成
+```
+
+若不可用，明确说明**缺什么**、**能不能绕过**、**绕过后的代价**。