dsh-courseware 0.1.0

package/engine/pptxgen/review.py

@@ -0,0 +1,184 @@
+"""设计审查（Design Review）—— 把"好看"变成可检查的规则。
+
+规则来源：腾讯 PPTX 技能的设计宪法（story-principle / design-principle），
+按中小学课件的场景做了下调与改写：
+
+  · 版式多样性：相邻页不得同骨架；单一骨架不得占满全篇
+  · 信息密度  ：内容页正文字数下限；卡片组按卡计算
+  · 视觉锚点  ：每页至少一个"明显更大"的元素（大标题/大图/大色块），
+                禁止所有元素趋近中间大小
+  · 润色落实  ：每页关键词高亮、有图必有图注、超长列表必须分块
+  · 节奏      ：封面/结束页以外的页面不得连续同型（由版式多样性覆盖）
+
+用法：
+    pptxgen review decks/xxx.yaml                 # 只查大纲层
+    pptxgen review decks/xxx.yaml --pptx out/xxx.pptx   # 追加成品层检查
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List, Optional, Sequence, Tuple
+
+from .patterns import collect_texts, guess_pattern, highlight_count, text_len
+
+# 每页正文字数下限（中小学课件，比商务汇报低一档）
+MIN_WORDS = {
+    "content": 60,
+    "example": 60,
+    "practice": 40,
+    "summary": 40,
+    "homework": 30,
+    "objectives": 60,
+    "toc": 30,
+    "section": 15,
+    "cover": 8,
+    "end": 8,
+}
+
+# 骨架健康度阈值
+MAX_SINGLE_PATTERN_SHARE = 0.55      # 单一骨架最多占全篇比例
+MAX_CARDS_PER_DECK = 0.45            # 卡片矩阵最多占全篇比例（防"千页一卡"）
+
+
+class Finding:
+    def __init__(self, level: str, page: Optional[int], text: str):
+        self.level = level          # "错误" / "建议"
+        self.page = page
+        self.text = text
+
+    def __str__(self) -> str:
+        where = f"P{self.page}" if self.page else "全篇"
+        return f"[{self.level}] {where} {self.text}"
+
+
+def review_deck(deck: dict, pptx_path: Optional[str] = None) -> Tuple[List[Finding], str]:
+    slides = deck.get("slides") or []
+    findings: List[Finding] = []
+    stats: List[str] = []
+
+    patterns: List[str] = []
+    for i, s in enumerate(slides, 1):
+        stype = s.get("type")
+        bullets = [b for b in (s.get("bullets") or []) if b.get("text")]
+        pat = guess_pattern(s, bullets)
+        if pat in ("image_left", "image_right"):
+            pat = "bullets"
+        patterns.append(pat)
+
+        texts = collect_texts(s)
+        n = text_len(texts)
+        title = (s.get("title") or "")[:18]
+        stats.append(f"  P{i:>2} [{stype:<10}] {pat:<9} {n:>4}字  高亮{highlight_count(s)}处  {title}")
+
+        # 密度下限
+        floor = MIN_WORDS.get(stype, 40)
+        if n < floor:
+            findings.append(Finding("建议", i, f"内容偏薄（{n} 字 < 下限 {floor} 字）"))
+
+        # 润色落实
+        if stype in ("content", "example") and highlight_count(s) == 0 and n >= 40:
+            findings.append(Finding("建议", i, "整页没有关键词高亮（`**关键词**`）"))
+        if (s.get("image_prompt") or s.get("image")) and not s.get("image_caption"):
+            findings.append(Finding("建议", i, "有配图但没有图注（image_caption）"))
+
+        # 超长列表未分块
+        if stype in ("content", "example") and pat == "bullets":
+            lvl0 = [b for b in bullets if int(b.get("level", 0) or 0) == 0]
+            if len(lvl0) >= 5:
+                findings.append(Finding("建议", i,
+                                        f"{len(lvl0)} 条一级要点仍用 bullets，建议分块"
+                                        f"（cards/steps/flow/compare）"))
+
+    # 版式多样性（借用"相邻页不得同版式"）
+    core = [(i, p) for i, (p, s) in enumerate(zip(patterns, slides), 1)
+            if s.get("type") not in ("cover", "end")]
+    for (i1, p1), (i2, p2) in zip(core, core[1:]):
+        if p1 == p2 and p1 in ("bullets", "cards"):
+            findings.append(Finding("建议", i2, f"与上一页同为 {p1} 骨架，建议换一种"))
+
+    counts: Dict[str, int] = {}
+    for _, p in core:
+        counts[p] = counts.get(p, 0) + 1
+    total = max(len(core), 1)
+    for p, c in counts.items():
+        if c / total > MAX_SINGLE_PATTERN_SHARE and total >= 6:
+            findings.append(Finding("建议", None,
+                                    f"骨架 {p} 占 {c}/{total} 页（>{int(MAX_SINGLE_PATTERN_SHARE*100)}%），"
+                                    f"全篇偏单调"))
+    if counts.get("cards", 0) / total > MAX_CARDS_PER_DECK and total >= 6:
+        findings.append(Finding("建议", None,
+                                f"卡片矩阵占 {counts['cards']}/{total} 页，建议穿插 steps/flow/compare"))
+
+    # 视觉锚点（需要成品才能算字号与面积）
+    if pptx_path:
+        findings.extend(_review_pptx(pptx_path))
+
+    report = "设计审查（Design Review）\n" + "\n".join(stats)
+    return findings, report
+
+
+def _review_pptx(pptx_path: str) -> List[Finding]:
+    """成品层检查：每页是否有"视觉锚点"（明显更大的字号或大图）。"""
+    from pptx import Presentation
+    from pptx.util import Emu
+
+    findings: List[Finding] = []
+    try:
+        prs = Presentation(pptx_path)
+    except Exception as exc:
+        return [Finding("建议", None, f"无法读取成品：{exc}")]
+    W = float(prs.slide_width or 1)
+    H = float(prs.slide_height or 1)
+    for i, slide in enumerate(prs.slides, 1):
+        sizes: List[float] = []
+        max_pic = 0.0
+        for sh in slide.shapes:
+            if sh.has_text_frame:
+                for p in sh.text_frame.paragraphs:
+                    for r in p.runs:
+                        if r.font.size:
+                            sizes.append(r.font.size.pt)
+            try:
+                if sh.shape_type is not None and "PICTURE" in str(sh.shape_type):
+                    max_pic = max(max_pic, (float(sh.width) * float(sh.height)) / (W * H))
+            except Exception:
+                pass
+        if not sizes:
+            continue
+        from collections import Counter as _Counter
+        rounded = [round(s, 1) for s in sizes]
+        distinct = sorted(set(rounded), reverse=True)
+        top = distinct[0]
+        if len(distinct) == 1:
+            # 全页只有一个字号：靠"字号本身够大"或大图撑锚点
+            anchor = top >= 32 or max_pic >= 0.12
+            body_ref = top
+        else:
+            # 锚点 = "有没有比正文明显更大的东西"，所以拿最常见字号（正文）做基准
+            _counts = _Counter(rounded)
+            _maxn = max(_counts.values())
+            # 并列最常见时取较小者当"正文"（封面/结束页只有标题+副标题两个字号）
+            body_ref = min(sz for sz, n in _counts.items() if n == _maxn)
+            # 借鉴来源的学术分支：主标 32-40 / 正文 22-28，比值约 1.25-1.45，取 1.35
+            anchor = (top >= body_ref * 1.35) or max_pic >= 0.12
+        if not anchor:
+            findings.append(Finding("建议", i,
+                                    f"缺少视觉锚点（最大字号 {top:.0f}pt / 正文字号 {body_ref:.0f}pt，"
+                                    f"最大图占比 {max_pic*100:.0f}%）"))
+    return findings
+
+
+def format_findings(findings: Sequence[Finding]) -> str:
+    if not findings:
+        return "设计审查：未发现问题。"
+    errs = [f for f in findings if f.level == "错误"]
+    tips = [f for f in findings if f.level != "错误"]
+    out = []
+    if errs:
+        out.append(f"发现 {len(errs)} 个错误：")
+        out.extend(f"  ! {f}" for f in errs)
+    if tips:
+        out.append(f"发现 {len(tips)} 条建议：")
+        out.extend(f"  · {f}" for f in tips)
+    return "\n".join(out)

package/engine/pptxgen/schemacheck.py

@@ -0,0 +1,122 @@
+"""严格模式校验：按 OOXML Schema（ECMA-376，与 PowerPoint 同源）检查生成文件的各部件。
+
+LibreOffice 对很多结构错误很宽容（例如 <a:spcBef pts="..."/>），PowerPoint 则会
+直接弹"内容有问题"修复框。这里的 XSD 校验能提前抓到这一类错误。
+
+注意：微软扩展命名空间（p14/a14/p15/a15/p16/a16 等）不在 ECMA-376 标准 Schema 内，
+含这些扩展的部件会跳过严格校验（PowerPoint 自带处理），避免误报。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import zipfile
+from typing import List, Optional, Tuple
+
+from lxml import etree
+
+SCHEMA_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "schemas")
+
+# 微软扩展命名空间前缀 → 跳过严格校验（ECMA-376 的 XSD 不覆盖它们）
+MS_EXT_NS = re.compile(
+    r"schemas\.microsoft\.com/office/(powerpoint|drawing|word|excel)/"
+)
+
+# pml.xsd 覆盖的部件范围（根元素在 presentationml 命名空间下的部分）
+PML_PARTS = re.compile(
+    r"^ppt/(slides/slide\d+|notesSlides/notesSlide\d+|slideLayouts/slideLayout\d+|"
+    r"slideMasters/slideMaster\d+|notesMasters/notesMaster\d+)\.xml$"
+)
+PML_PRESENTATION = "ppt/presentation.xml"
+
+_schema_cache: Optional[etree.XMLSchema] = None
+
+
+def _load_schema() -> Optional[etree.XMLSchema]:
+    """加载 pml.xsd（含全部 import，缓存）。"""
+    global _schema_cache
+    if _schema_cache is not None:
+        return _schema_cache
+    if not os.path.isdir(SCHEMA_DIR):
+        return None
+    xsd = os.path.join(SCHEMA_DIR, "pml.xsd")
+    if not os.path.exists(xsd):
+        return None
+
+    class _Resolver(etree.Resolver):
+        def resolve(self, url, public_id, context):
+            base = os.path.basename(url)
+            p = os.path.join(SCHEMA_DIR, base)
+            if os.path.exists(p):
+                return self.resolve_filename(p, context)
+            return None
+
+    parser = etree.XMLParser(load_dtd=False, no_network=True)
+    parser.resolvers.add(_Resolver())
+    try:
+        doc = etree.parse(xsd, parser)
+        _schema_cache = etree.XMLSchema(doc)
+    except Exception:
+        _schema_cache = None
+    return _schema_cache
+
+
+def _has_ms_extension(xml: bytes) -> bool:
+    """部件里是否含微软扩展命名空间（含则跳过严格校验）。"""
+    return bool(MS_EXT_NS.search(xml.decode("utf-8", "ignore")))
+
+
+def check_schema(pptx_path: str) -> Tuple[List[str], List[str], bool]:
+    """校验 pptx 里所有 presentationml 部件。
+
+    返回 (failures, skipped, available)：
+      failures  —— (部件, 错误) 描述列表
+      skipped   —— 含微软扩展命名空间、跳过严格校验的部件
+      available —— Schema 是否可用（不可用时 failures 恒为空，不阻断 check）
+    """
+    schema = _load_schema()
+    if schema is None:
+        return [], [], False
+    failures: List[str] = []
+    skipped: List[str] = []
+    try:
+        z = zipfile.ZipFile(pptx_path)
+    except Exception as exc:
+        return [f"（无法读取 pptx：{exc}）"], [], True
+    targets = [n for n in z.namelist()
+               if n.endswith(".xml") and (PML_PARTS.match(n) or n == PML_PRESENTATION)]
+    for n in sorted(targets):
+        blob = z.read(n)
+        if _has_ms_extension(blob):
+            skipped.append(n)
+            continue
+        try:
+            doc = etree.fromstring(blob)
+        except Exception as exc:
+            failures.append(f"{n}: XML 解析失败：{exc}")
+            continue
+        if not schema.validate(doc):
+            errs = "; ".join(f"line {e.line} {e.message}" for e in schema.error_log[:4])
+            failures.append(f"{n}: {errs}")
+    z.close()
+    return failures, skipped, True
+
+
+def describe(pptx_path: str) -> str:
+    """供 check 命令输出的描述文本。"""
+    failures, skipped, available = check_schema(pptx_path)
+    lines = []
+    if not available:
+        lines.append("严格模式校验（OOXML Schema）：不可用（缺少 Schema 文件），已跳过")
+    elif failures:
+        lines.append(f"严格模式校验（OOXML Schema）：发现 {len(failures)} 个问题")
+        for f in failures[:12]:
+            lines.append(f"  ! {f}")
+        if len(failures) > 12:
+            lines.append(f"  ... 其余 {len(failures) - 12} 个")
+    else:
+        lines.append("严格模式校验（OOXML Schema）：全部部件通过")
+    if skipped:
+        lines.append(f"  （{len(skipped)} 个部件含微软扩展命名空间，已跳过：{skipped[0]} 等）")
+    return "\n".join(lines)