dsh-courseware 0.1.0

package/engine/pptxgen/spec.py

@@ -0,0 +1,529 @@
+"""课件内容规格：解析与规整 YAML / JSON / Markdown 大纲。"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+from .util import clean_lines
+
+# --------------------------------------------------------------------------
+# 页型定义
+# --------------------------------------------------------------------------
+TYPE_ALIASES = {
+    "cover": "cover", "封面": "cover", "首页": "cover", "title": "cover",
+    "toc": "toc", "目录": "toc", "contents": "toc", "agenda": "toc",
+    "section": "section", "章节": "section", "过渡": "section", "divider": "section",
+    "objectives": "objectives", "目标": "objectives", "学习目标": "objectives",
+    "重难点": "objectives", "objective": "objectives", "goals": "objectives",
+    "content": "content", "内容": "content", "知识点": "content", "正文": "content",
+    "point": "content", "knowledge": "content",
+    "practice": "practice", "练习": "practice", "习题": "practice", "检测": "practice",
+    "quiz": "practice", "exercise": "practice", "example": "example", "例题": "example",
+    "summary": "summary", "小结": "summary", "总结": "summary", "课堂小结": "summary",
+    "思维导图": "summary", "mindmap": "summary",
+    "homework": "homework", "作业": "homework", "课后作业": "homework",
+    "end": "end", "结束": "end", "谢谢": "end", "thanks": "end",
+}
+
+KNOWN_TYPES = {
+    "cover", "toc", "section", "objectives", "content",
+    "example", "practice", "summary", "homework", "end",
+}
+
+TYPE_LABELS = {
+    "cover": "封面",
+    "toc": "目录",
+    "section": "章节过渡",
+    "objectives": "学习目标",
+    "content": "知识点",
+    "example": "例题",
+    "practice": "课堂练习",
+    "summary": "课堂小结",
+    "homework": "课后作业",
+    "end": "结束页",
+}
+
+
+class SpecError(Exception):
+    pass
+
+
+def normalize_type(value: Optional[str], default: str = "content") -> str:
+    if not value:
+        return default
+    key = str(value).strip().lower()
+    if key in TYPE_ALIASES:
+        return TYPE_ALIASES[key]
+    raw = str(value).strip()
+    if raw in TYPE_ALIASES:
+        return TYPE_ALIASES[raw]
+    if key in KNOWN_TYPES:
+        return key
+    return default
+
+
+# --------------------------------------------------------------------------
+# 字段规整
+# --------------------------------------------------------------------------
+def norm_bullets(value) -> List[dict]:
+    """统一成 [{'text': str, 'level': int}]。"""
+    out: List[dict] = []
+    for item in clean_lines(value):
+        if isinstance(item, dict):
+            text = item.get("text") or item.get("title") or item.get("q") or ""
+            level = int(item.get("level", 0) or 0)
+            entry = {"text": str(text), "level": max(0, min(level, 3))}
+            for k, v in item.items():
+                if k not in ("text", "level"):
+                    entry[k] = v
+            out.append(entry)
+        else:
+            text = str(item)
+            stripped = text.lstrip()
+            indent = len(text) - len(stripped)
+            # 支持 "  - 子项" 这种手工缩进
+            level = 1 if indent >= 2 and stripped[:1] not in ("",) else 0
+            text = re.sub(r"^[-*•]\s*", "", stripped)
+            out.append({"text": text, "level": level})
+    return out
+
+
+def norm_questions(value) -> List[dict]:
+    out = []
+    for item in value or []:
+        if isinstance(item, str):
+            out.append({"q": item, "options": [], "answer": "", "analysis": ""})
+            continue
+        if not isinstance(item, dict):
+            continue
+        q = item.get("q") or item.get("question") or item.get("text") or ""
+        opts = item.get("options") or item.get("choices") or []
+        answer = item.get("answer") or item.get("ans") or ""
+        analysis = item.get("analysis") or item.get("explain") or item.get("note") or ""
+        entry = {
+            "q": str(q),
+            "options": [str(o) for o in (opts if isinstance(opts, (list, tuple)) else [opts])],
+            "answer": str(answer),
+            "analysis": str(analysis),
+        }
+        for k, v in item.items():
+            if k not in entry:
+                entry[k] = v
+        out.append(entry)
+    return out
+
+
+def norm_mindmap(value, fallback_points=None) -> dict:
+    if isinstance(value, dict):
+        center = value.get("center") or value.get("title") or ""
+        branches = []
+        for b in value.get("branches") or []:
+            if isinstance(b, dict):
+                branches.append({
+                    "title": str(b.get("title") or b.get("name") or ""),
+                    "items": [str(i) for i in (b.get("items") or b.get("points") or [])],
+                })
+            else:
+                branches.append({"title": str(b), "items": []})
+        if branches:
+            return {"center": str(center), "branches": branches}
+    # 退化成要点列表 -> 单分支
+    pts = [p["text"] for p in norm_bullets(fallback_points)] if fallback_points else []
+    return {"center": "", "branches": [{"title": "", "items": pts}] if pts else []}
+
+
+def norm_compare(value) -> Optional[dict]:
+    """对比页：{left: {title, items}, right: {title, items}}。"""
+    if not isinstance(value, dict):
+        return None
+    def side(v):
+        if isinstance(v, dict):
+            return {
+                "title": str(v.get("title") or v.get("name") or ""),
+                "items": [str(i) for i in (v.get("items") or v.get("points") or [])],
+            }
+        if isinstance(v, (list, tuple)):
+            return {"title": "", "items": [str(i) for i in v]}
+        return None
+    left, right = side(value.get("left")), side(value.get("right"))
+    if not left and not right:
+        return None
+    return {"left": left or {"title": "", "items": []},
+            "right": right or {"title": "", "items": []},
+            "vs": str(value.get("vs") or "") or None}
+
+
+def norm_timeline(value) -> List[dict]:
+    """时间轴：[{time, text}]。"""
+    out: List[dict] = []
+    for item in value or []:
+        if isinstance(item, dict):
+            out.append({
+                "time": str(item.get("time") or item.get("when") or item.get("label") or ""),
+                "text": str(item.get("text") or item.get("title") or item.get("event") or ""),
+            })
+        else:
+            out.append({"time": "", "text": str(item)})
+    return [it for it in out if it["text"] or it["time"]]
+
+
+def norm_cards(value) -> List[dict]:
+    """卡片组：[{title, items:[str], color}]。"""
+    out: List[dict] = []
+    for item in value or []:
+        if isinstance(item, dict):
+            items = item.get("items") or item.get("points") or item.get("bullets") or []
+            if isinstance(items, str):
+                items = [items]
+            out.append({
+                "title": str(item.get("title") or item.get("text") or item.get("name") or ""),
+                "items": [str(i) for i in items],
+                "color": item.get("color"),
+            })
+        else:
+            out.append({"title": str(item), "items": [], "color": None})
+    return [c for c in out if c["title"] or c["items"]]
+
+
+def _norm_answer_mode(value, default="end") -> str:
+    v = str(value or default).strip().lower()
+    return v if v in ("end", "inline", "none") else default
+
+
+# --------------------------------------------------------------------------
+# 单页规整
+# --------------------------------------------------------------------------
+def normalize_slide(raw: Dict[str, Any], index: int, section_counter: List[int]) -> dict:
+    if isinstance(raw, str):
+        raw = {"type": "content", "title": raw}
+    slide = dict(raw)
+    stype = normalize_type(slide.get("type"), default="content")
+    slide["type"] = stype
+
+    if stype == "cover":
+        slide["title"] = slide.get("title") or slide.get("deck_title") or ""
+        slide["subtitle"] = slide.get("subtitle") or ""
+        slide["teacher"] = slide.get("teacher") or slide.get("author") or ""
+        slide["school"] = slide.get("school") or ""
+        slide["date"] = slide.get("date") or ""
+    elif stype == "toc":
+        slide["title"] = slide.get("title") or "目 录"
+        slide["items"] = norm_bullets(slide.get("items") or slide.get("bullets"))
+    elif stype == "section":
+        section_counter[0] += 1
+        slide["index"] = slide.get("index", section_counter[0])
+        slide["title"] = slide.get("title") or ""
+        slide["subtitle"] = slide.get("subtitle") or ""
+        slide["items"] = norm_bullets(slide.get("items"))
+    elif stype == "objectives":
+        slide["title"] = slide.get("title") or "学习目标"
+        slide["goals"] = norm_bullets(slide.get("goals") or slide.get("bullets") or slide.get("items"))
+        slide["key_points"] = norm_bullets(slide.get("key_points") or slide.get("key") or slide.get("重点"))
+        slide["hard_points"] = norm_bullets(slide.get("hard_points") or slide.get("hard") or slide.get("难点"))
+    elif stype in ("content", "example", "practice", "summary", "homework"):
+        slide["title"] = slide.get("title") or ""
+        slide["subtitle"] = slide.get("subtitle") or ""
+        if stype in ("content", "example"):
+            slide["bullets"] = norm_bullets(slide.get("bullets") or slide.get("points") or slide.get("items"))
+            slide["steps"] = norm_bullets(slide.get("steps"))
+            slide["compare"] = norm_compare(slide.get("compare"))
+            slide["timeline"] = norm_timeline(slide.get("timeline"))
+            slide["cards"] = norm_cards(slide.get("cards"))
+            slide["pattern"] = slide.get("pattern") or slide.get("variant") or None
+        if stype == "practice":
+            slide["questions"] = norm_questions(slide.get("questions") or slide.get("items"))
+            slide["bullets"] = norm_bullets(slide.get("bullets"))
+        if stype == "summary":
+            slide["points"] = norm_bullets(slide.get("points") or slide.get("bullets") or slide.get("items"))
+            slide["mindmap"] = norm_mindmap(slide.get("mindmap"), slide.get("points"))
+        if stype == "homework":
+            slide["items"] = norm_bullets(slide.get("items") or slide.get("bullets"))
+            slide["note"] = slide.get("note") or slide.get("tips") or ""
+    elif stype == "end":
+        slide["title"] = slide.get("title") or "谢谢观看"
+        slide["subtitle"] = slide.get("subtitle") or ""
+
+    # 通用可选字段
+    slide.setdefault("image", None)
+    slide.setdefault("image_side", "right")
+    slide.setdefault("image_caption", None)
+    slide.setdefault("images", None)
+    slide.setdefault("note", slide.get("note") or "")
+    slide.setdefault("layout", None)
+    slide.setdefault("pattern", slide.get("pattern") or slide.get("variant") or None)
+    slide.setdefault("cards", norm_cards(slide.get("cards")))
+    slide.setdefault("compare", norm_compare(slide.get("compare")))
+    slide.setdefault("timeline", norm_timeline(slide.get("timeline")))
+    slide.setdefault("chrome", None)
+    return slide
+
+
+def normalize_deck(raw: Dict[str, Any]) -> dict:
+    if not isinstance(raw, dict):
+        raise SpecError("课件文件的顶层必须是映射（key: value）结构")
+
+    meta = dict(raw.get("deck") or raw.get("meta") or {})
+    for k in ("title", "subtitle", "subject", "grade", "teacher", "school", "date", "term"):
+        if k in raw and k not in meta:
+            meta[k] = raw[k]
+
+    options = {
+        "answer_mode": _norm_answer_mode((raw.get("options") or {}).get("answer_mode")
+                                         or raw.get("answer_mode")),
+        "page_numbers": bool((raw.get("options") or {}).get("page_numbers", True)),
+        "page_number_start": int((raw.get("options") or {}).get("page_number_start", 1) or 1),
+        "chrome": (raw.get("options") or {}).get("chrome", "auto"),
+        "auto_toc": bool((raw.get("options") or {}).get("auto_toc", False)),
+        "section_cover": bool((raw.get("options") or {}).get("section_cover", True)),
+        "default_layout": (raw.get("options") or {}).get("default_layout"),
+        "fit_shrink_floor": float((raw.get("options") or {}).get("fit_shrink_floor", 0.62)),
+    }
+    # 其余自定义选项（例如 images 配图设置）原样保留，不要丢掉
+    for _k, _v in (raw.get("options") or {}).items():
+        if _k not in options:
+            options[_k] = _v
+
+    raw_slides = raw.get("slides") or raw.get("pages") or []
+    if not isinstance(raw_slides, list):
+        raise SpecError("slides 必须是列表")
+
+    section_counter = [0]
+    slides = [normalize_slide(s, i, section_counter) for i, s in enumerate(raw_slides)]
+
+    # 如果第一页不是封面，自动从 meta 生成封面
+    if not slides or slides[0]["type"] != "cover":
+        cover = normalize_slide({
+            "type": "cover",
+            "title": meta.get("title", ""),
+            "subtitle": meta.get("subtitle", ""),
+            "teacher": meta.get("teacher", ""),
+            "school": meta.get("school", ""),
+            "date": meta.get("date", ""),
+        }, 0, section_counter)
+        slides.insert(0, cover)
+
+    # 自动目录
+    if options["auto_toc"] and not any(s["type"] == "toc" for s in slides):
+        items = []
+        for s in slides:
+            if s["type"] == "section" and s.get("title"):
+                items.append({"text": s["title"], "level": 0})
+        if items:
+            toc = normalize_slide({"type": "toc", "title": "目 录", "items": items},
+                                  len(slides), section_counter)
+            slides.insert(1, toc)
+
+    return {
+        "meta": meta,
+        "options": options,
+        "template": raw.get("template"),
+        "output": raw.get("output"),
+        "layout_map": raw.get("layout_map") or {},
+        "style": raw.get("style") or {},
+        "slides": slides,
+    }
+
+
+# --------------------------------------------------------------------------
+# 读取
+# --------------------------------------------------------------------------
+def load_deck(path: str) -> dict:
+    if not os.path.exists(path):
+        raise SpecError(f"找不到课件文件：{path}")
+    with open(path, "r", encoding="utf-8") as f:
+        text = f.read()
+    ext = os.path.splitext(path)[1].lower()
+    if ext == ".json":
+        raw = json.loads(text)
+    elif ext == ".md" or ext == ".markdown":
+        raw = parse_markdown(text)
+    else:
+        raw = yaml.safe_load(text)
+    deck = normalize_deck(raw or {})
+    deck["_source"] = os.path.abspath(path)
+    deck["_dir"] = os.path.dirname(os.path.abspath(path))
+    return deck
+
+
+# --------------------------------------------------------------------------
+# Markdown 大纲 -> deck
+#   # 封面标题 | 副标题
+#   ## [章节] 第一节 xxx
+#   ## [目标] 学习目标
+#   ## [练习] 随堂练习
+#   > 重点：xxx
+# --------------------------------------------------------------------------
+_HEAD_RE = re.compile(r"^(#{1,6})\s*(.*)$")
+_MARK_RE = re.compile(r"^\[([^\]]+)\]\s*(.*)$")
+_ANS_RE = re.compile(r"^[→➜>]\s*(?:答案|answer)\s*[:：]\s*(.*)$", re.I)
+_ANA_RE = re.compile(r"^[※*]\s*(?:解析|分析|说明)\s*[:：]\s*(.*)$")
+_OPT_RE = re.compile(r"^[（(]?([A-Ha-h])[)）.、．:：]\s*(.*)$")
+_NUM_RE = re.compile(r"^\s*(\d{1,2})[.、．)）]\s+(.*)$")
+
+
+def parse_markdown(text: str) -> dict:
+    lines = text.replace("\r\n", "\n").split("\n")
+    meta: Dict[str, Any] = {}
+    body_start = 0
+    if lines and lines[0].strip() == "---":
+        for i in range(1, len(lines)):
+            if lines[i].strip() == "---":
+                body_start = i + 1
+                break
+            if ":" in lines[i]:
+                k, v = lines[i].split(":", 1)
+                meta[k.strip()] = v.strip()
+    lines = lines[body_start:]
+
+    slides: List[dict] = []
+    cur: Optional[dict] = None
+    mode = "bullets"
+    pending_q: Optional[dict] = None
+    goals: List[str] = []
+    key_points: List[str] = []
+    hard_points: List[str] = []
+
+    def flush():
+        nonlocal cur, pending_q, goals, key_points, hard_points
+        if cur is not None:
+            if cur["type"] == "objectives":
+                cur["goals"] = goals
+                cur["key_points"] = key_points
+                cur["hard_points"] = hard_points
+            if pending_q and cur.get("questions") is not None:
+                cur["questions"].append(pending_q)
+            slides.append(cur)
+        cur, pending_q = None, None
+        goals, key_points, hard_points = [], [], []
+
+    for raw_line in lines:
+        line = raw_line.rstrip()
+        stripped = line.strip()
+
+        m = _HEAD_RE.match(stripped)
+        if m:
+            level = len(m.group(1))
+            text_part = m.group(2).strip()
+            if level == 1:
+                flush()
+                title, _, sub = text_part.partition("|")
+                meta.setdefault("title", title.strip())
+                if sub.strip():
+                    meta.setdefault("subtitle", sub.strip())
+                continue
+            flush()
+            mm = _MARK_RE.match(text_part)
+            if mm:
+                stype = normalize_type(mm.group(1), default="content")
+                title = mm.group(2).strip()
+            else:
+                stype = "content"
+                title = text_part
+            cur = {"type": stype, "title": title}
+            mode = {
+                "objectives": "objectives",
+                "practice": "practice",
+                "example": "steps",
+                "homework": "items",
+                "summary": "points",
+            }.get(stype, "bullets")
+            if mode == "objectives":
+                cur["goals"], cur["key_points"], cur["hard_points"] = [], [], []
+            if mode == "practice":
+                cur["questions"] = []
+            continue
+
+        if stripped == "":
+            continue
+
+        if cur is None:
+            # 文件开头的自由文本，作为封面副标题
+            meta.setdefault("subtitle", stripped)
+            continue
+
+        # 重点/难点（引用块）
+        if stripped.startswith(">"):
+            content = stripped.lstrip("> ").strip()
+            if re.match(r"^(重点|教学重点)", content):
+                key_points.extend(_split_inline(re.sub(r"^(重点|教学重点)\s*[:：]\s*", "", content)))
+                continue
+            if re.match(r"^(难点|教学难点)", content):
+                hard_points.extend(_split_inline(re.sub(r"^(难点|教学难点)\s*[:：]\s*", "", content)))
+                continue
+            if re.match(r"^(目标|学习目标)", content):
+                goals.extend(_split_inline(re.sub(r"^(目标|学习目标)\s*[:：]\s*", "", content)))
+                continue
+            if cur["type"] == "content":
+                cur.setdefault("bullets", []).append({"text": content, "level": 1})
+            continue
+
+        # 练习页
+        if cur["type"] == "practice" or (cur["type"] == "example" and mode == "steps"):
+            am = _ANS_RE.match(stripped)
+            if am:
+                if pending_q is None:
+                    pending_q = {"q": "", "options": [], "answer": "", "analysis": ""}
+                pending_q["answer"] = am.group(1).strip()
+                continue
+            nm = _ANA_RE.match(stripped)
+            if nm:
+                if pending_q is None:
+                    pending_q = {"q": "", "options": [], "answer": "", "analysis": ""}
+                pending_q["analysis"] = nm.group(1).strip()
+                continue
+            om = _OPT_RE.match(stripped)
+            if om and pending_q is not None:
+                pending_q["options"].append(f"{om.group(1).upper()}. {om.group(2).strip()}")
+                continue
+            qm = _NUM_RE.match(line)
+            if qm:
+                if pending_q:
+                    cur["questions"].append(pending_q)
+                pending_q = {"q": qm.group(2).strip(), "options": [], "answer": "", "analysis": ""}
+                continue
+            if stripped.startswith(("-", "*", "•")) or re.match(r"^[（(]?\d+[)）.、．]", stripped):
+                text = re.sub(r"^[-*•]\s*", "", stripped)
+                if cur["type"] == "example" and not re.match(r"^[（(]?\d+[)）.、．]", text):
+                    cur.setdefault("steps", []).append({"text": text, "level": 0})
+                else:
+                    cur.setdefault("questions", []).append(
+                        {"q": text, "options": [], "answer": "", "analysis": ""})
+                continue
+            # 续行
+            if pending_q is not None:
+                pending_q["q"] = (pending_q["q"] + " " + stripped).strip()
+            continue
+
+        # 目标页
+        if mode == "objectives":
+            text = re.sub(r"^[-*•]\s*", "", stripped)
+            goals.append(text)
+            continue
+
+        # 通用列表
+        indent = len(line) - len(line.lstrip())
+        text = re.sub(r"^[-*•]\s*", "", stripped)
+        text = re.sub(r"^\d{1,2}[.、．)）]\s*", "", text)
+        level = 1 if indent >= 2 else 0
+        target = {
+            "points": "points", "items": "items", "steps": "steps", "bullets": "bullets",
+        }.get(mode, "bullets")
+        cur.setdefault(target, []).append({"text": text, "level": level})
+
+    flush()
+
+    raw = {"deck": meta, "slides": slides}
+    for k in ("template", "output"):
+        if k in meta:
+            raw[k] = meta.pop(k)
+    return raw
+
+
+def _split_inline(text: str) -> List[str]:
+    parts = re.split(r"[；;]|,\s*(?=[\u4e00-\u9fff])", text)
+    return [p.strip() for p in parts if p.strip()]