dsh-courseware 0.1.0

package/engine/pptxgen/cli.py

@@ -0,0 +1,575 @@
+"""命令行入口。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import List, Optional
+
+from . import __version__
+from . import imagegen
+from .builtin_template import build_builtin_template
+from .layoutmap import build_map, describe_map
+from .profile import describe as describe_profile
+from .profile import learn_profile
+from .render import Renderer
+from .spec import TYPE_LABELS, SpecError, load_deck
+from .template import describe as describe_template
+from .template import load_template
+from .util import inch_from_emu, pt_from_emu
+
+DEFAULT_TEMPLATE_DIR = "templates"
+DEFAULT_OUT_DIR = "out"
+
+
+# --------------------------------------------------------------------------
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="pptxgen",
+        description="用你自己的 PPT 模板，从中小学课程大纲生成 pptx 课件。",
+    )
+    parser.add_argument("--version", action="version", version=f"pptxgen {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_ins = sub.add_parser("inspect", help="解析模板：版式、配色、字体、背景、装饰层")
+    p_ins.add_argument("template")
+    p_ins.add_argument("-v", "--verbose", action="store_true", help="列出每个版式的占位符细节")
+    p_ins.add_argument("--json", action="store_true", help="以 JSON 输出")
+    p_ins.add_argument("--map", action="store_true", help="同时输出页型->版式 的自动映射")
+    p_ins.add_argument("--write-map", metavar="FILE", help="把自动映射写入 YAML 文件")
+    p_ins.set_defaults(func=cmd_inspect)
+
+    p_build = sub.add_parser("build", help="按课件规格生成 pptx")
+    p_build.add_argument("deck", help="课件规格文件（.yaml / .json / .md）")
+    p_build.add_argument("-t", "--template", help="模板 pptx（覆盖课件文件里的 template 字段）")
+    p_build.add_argument("-o", "--out", help="输出 pptx 路径")
+    p_build.add_argument("--no-chrome", action="store_true", help="不复制模板的装饰层/背景图")
+    p_build.add_argument("--keep-template-slides", action="store_true",
+                         help="保留模板里原有的示例幻灯片")
+    p_build.add_argument("--show-map", action="store_true", help="输出页型->版式 映射")
+    p_build.add_argument("--open", action="store_true", help="生成后用系统默认程序打开")
+    p_build.set_defaults(func=cmd_build)
+
+    p_chk = sub.add_parser("check", help="自检生成的 pptx（页数、溢出风险、文字重叠）")
+    p_chk.add_argument("pptx")
+    p_chk.add_argument("--render", action="store_true",
+                       help="额外渲染成 PDF 做真实排版检查（能发现文字重叠，需要 LibreOffice）")
+    p_chk.set_defaults(func=cmd_check)
+
+    p_rev = sub.add_parser("review", help="设计审查：版式多样性、信息密度、视觉锚点、润色落实")
+    p_rev.add_argument("deck", help="课件规格文件（.yaml / .json / .md）")
+    p_rev.add_argument("--pptx", help="同时检查已生成的 pptx（能测算字号与配图面积）")
+    p_rev.set_defaults(func=cmd_review)
+
+    p_prev = sub.add_parser("preview", help="把 pptx 渲染成 PNG（需要 LibreOffice）")
+    p_prev.add_argument("pptx")
+    p_prev.add_argument("-o", "--out-dir", default=None, help="图片输出目录（默认 out/preview）")
+    p_prev.add_argument("--dpi", type=int, default=110, help="渲染分辨率，默认 110")
+    p_prev.add_argument("--no-sheet", action="store_true", help="不生成总览拼图")
+    p_prev.add_argument("--open", action="store_true", help="渲染后打开总览图")
+    p_prev.set_defaults(func=cmd_preview)
+
+    p_img = sub.add_parser("images", help="按课件里的 image_prompt 生成配图（需要图像模型 API key）")
+    p_img.add_argument("deck", nargs="?", help="课件规格文件")
+    p_img.add_argument("--dry-run", action="store_true", help="只列出会生成哪些图，不发请求")
+    p_img.add_argument("--init-config", nargs="?", const=".pptxgen.yaml", metavar="PATH",
+                       help="生成配置文件模板；传 global 则写到 ~/.pptxgen/config.yaml（全局生效）")
+    p_img.add_argument("--backend", help=f"图像后端：{' / '.join(imagegen.BACKENDS)}")
+    p_img.add_argument("--limit", type=int, help="只先生成前 N 张")
+    p_img.add_argument("--force", action="store_true", help="忽略缓存，强制重新生成")
+    p_img.set_defaults(func=cmd_images)
+
+    p_demo = sub.add_parser("demo", help="用内置模板生成一份完整示例课件")
+    p_demo.add_argument("-o", "--out-dir", default="examples", help="输出目录")
+    p_demo.set_defaults(func=cmd_demo)
+
+    p_init = sub.add_parser("init-deck", help="生成一份课件规格模板文件")
+    p_init.add_argument("--title", default="我的课件", help="课件标题")
+    p_init.add_argument("-o", "--out", default=None, help="输出 yaml 路径")
+    p_init.set_defaults(func=cmd_init_deck)
+
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except SpecError as exc:
+        print(f"错误：{exc}", file=sys.stderr)
+        return 2
+    except FileNotFoundError as exc:
+        print(f"错误：找不到文件 {exc}", file=sys.stderr)
+        return 2
+
+
+# --------------------------------------------------------------------------
+def cmd_inspect(args) -> int:
+    if not os.path.exists(args.template):
+        print(f"错误：找不到模板文件 {args.template}", file=sys.stderr)
+        return 2
+    tpl = load_template(args.template)
+    if args.json:
+        print(json.dumps(_template_to_dict(tpl), ensure_ascii=False, indent=2))
+        return 0
+    print(describe_template(tpl, verbose=args.verbose))
+    print()
+    try:
+        print(describe_profile(learn_profile(tpl)))
+    except Exception as exc:
+        print(f"样式档案：学习失败（{exc}）")
+    mapping = build_map(tpl)
+    if args.map or args.write_map:
+        print()
+        print(describe_map(tpl, mapping))
+    if args.write_map:
+        import yaml
+
+        with open(args.write_map, "w", encoding="utf-8") as f:
+            yaml.safe_dump({k: int(v) for k, v in mapping.items()}, f,
+                           allow_unicode=True, sort_keys=False)
+        print(f"\n映射已写入 {args.write_map}（可手工修改后放进课件的 layout_map 字段）")
+    return 0
+
+
+def _template_to_dict(tpl) -> dict:
+    return {
+        "path": tpl.path,
+        "slide_width_emu": tpl.width,
+        "slide_height_emu": tpl.height,
+        "slide_size_in": [round(inch_from_emu(tpl.width), 3), round(inch_from_emu(tpl.height), 3)],
+        "aspect": round(tpl.aspect, 4),
+        "sample_slides": tpl.sample_slide_count,
+        "theme_colors": tpl.theme_colors,
+        "theme_fonts": tpl.theme_fonts,
+        "master_background": _bg_to_dict(tpl.master_background),
+        "slide_background_override": (
+            {"kind": tpl.slide_background.get("kind"), "count": tpl.slide_background.get("count")}
+            if tpl.slide_background else None
+        ),
+        "style_profile": _profile_to_dict(tpl),
+        "global_chrome": [
+            {"name": it.name, "full_bleed": it.is_full_bleed, "occurrences": it.occurrences,
+             "box_in": [round(inch_from_emu(v), 3) if v is not None else None for v in it.box]}
+            for it in tpl.global_chrome
+        ],
+        "layouts": [
+            {
+                "index": lay.index,
+                "name": lay.name,
+                "background": _bg_to_dict(lay.background),
+                "chrome_count": len(lay.chrome),
+                "placeholders": [
+                    {
+                        "idx": ph.idx,
+                        "type": ph.ph_type,
+                        "name": ph.name,
+                        "box_in": [round(inch_from_emu(v), 3) for v in ph.box],
+                        "font_size_pt": ph.font_size_pt,
+                        "font_name": ph.font_name,
+                        "color": ph.color,
+                    }
+                    for ph in lay.placeholders
+                ],
+            }
+            for lay in tpl.layouts
+        ],
+    }
+
+
+def _profile_to_dict(tpl) -> Optional[dict]:
+    try:
+        prof = learn_profile(tpl)
+    except Exception:
+        return None
+    if prof is None:
+        return None
+
+    def sk(s):
+        if s is None:
+            return None
+        return {
+            "box_in": [round(v / 914400, 3) for v in s.box],
+            "occurrences": s.occurrences,
+            "font": s.style.font,
+            "size_pt": s.style.size_pt,
+            "align": s.style.align,
+            "fill": s.fill,
+            "line": s.line,
+        }
+
+    def box(b):
+        return [round(v / 914400, 3) for v in b] if b else None
+
+    return {
+        "module_label": sk(prof.module_label),
+        "title_chip": sk(prof.title_chip),
+        "content_box_in": box(prof.content_box),
+        "cover_title_box_in": box(prof.cover_title_box),
+        "end_title_box_in": box(prof.end_title_box),
+    }
+
+
+def _bg_to_dict(bg) -> Optional[dict]:
+    if not bg:
+        return None
+    return {k: v for k, v in bg.items() if k not in ("element", "owner", "blob")}
+
+
+# --------------------------------------------------------------------------
+def cmd_build(args) -> int:
+    deck = load_deck(args.deck)
+    template_path = _resolve_template(args.template or deck.get("template"), deck)
+    if template_path is None:
+        print("错误：没有可用的模板。请用 -t 指定，或在课件文件里写 template: 路径。",
+              file=sys.stderr)
+        return 2
+
+    tpl = load_template(template_path)
+    if args.no_chrome:
+        deck["options"]["chrome"] = "off"
+    if args.show_map:
+        print(describe_map(tpl, build_map(tpl, deck.get("layout_map"))))
+        print()
+
+    out = args.out or deck.get("output") or _default_output(deck, args.deck)
+    renderer = Renderer(tpl, deck)
+    report = renderer.render(out, keep_template_slides=args.keep_template_slides)
+
+    print(f"模板：{template_path}")
+    print(f"输出：{os.path.abspath(out)}")
+    print(report.text())
+    if args.open:
+        _open_file(os.path.abspath(out))
+    return 0
+
+
+def _resolve_template(value: Optional[str], deck: dict) -> Optional[str]:
+    if value:
+        cand = value if os.path.isabs(value) else os.path.join(deck.get("_dir", "."), value)
+        if os.path.exists(cand):
+            return cand
+        if os.path.exists(value):
+            return value
+        print(f"警告：课件里指定的模板不存在：{value}", file=sys.stderr)
+    # 自动发现：templates/ 下只有一个 pptx 时直接用它
+    for d in (deck.get("_dir", "."), DEFAULT_TEMPLATE_DIR, "."):
+        full = os.path.join(d, DEFAULT_TEMPLATE_DIR)
+        if os.path.isdir(full):
+            found = sorted(f for f in os.listdir(full) if f.lower().endswith(".pptx")
+                           and not f.startswith("~$"))
+            if len(found) == 1:
+                return os.path.join(full, found[0])
+            if len(found) > 1:
+                print(f"提示：{full} 下有多个模板，请在课件里用 template: 指定，或用 -t 指定。",
+                      file=sys.stderr)
+                return None
+    return None
+
+
+def _default_output(deck: dict, deck_path: str) -> str:
+    title = (deck.get("meta") or {}).get("title") or os.path.splitext(os.path.basename(deck_path))[0]
+    safe = "".join(c for c in str(title) if c not in '\\/:*?"<>|').strip() or "output"
+    base = os.path.dirname(os.path.abspath(deck_path))
+    root = base
+    for _ in range(3):
+        if os.path.basename(root) in ("decks", "examples", "input"):
+            root = os.path.dirname(root)
+            break
+        root = os.path.dirname(root)
+    return os.path.join(root, DEFAULT_OUT_DIR, f"{safe}.pptx")
+
+
+def _open_file(path: str) -> None:
+    try:
+        if sys.platform == "darwin":
+            os.system(f'open "{path}"')
+        elif os.name == "nt":
+            os.startfile(path)  # type: ignore[attr-defined]
+        else:
+            os.system(f'xdg-open "{path}"')
+    except Exception:
+        pass
+
+
+# --------------------------------------------------------------------------
+def cmd_check(args) -> int:
+    from pptx import Presentation
+
+    from .util import wrap_lines
+
+    if not os.path.exists(args.pptx):
+        print(f"错误：找不到文件 {args.pptx}", file=sys.stderr)
+        return 2
+    prs = Presentation(args.pptx)
+    W, H = prs.slide_width, prs.slide_height
+    problems = []
+    slides = list(prs.slides)
+    print(f"文件：{os.path.abspath(args.pptx)}")
+    print(f"画布：{inch_from_emu(W):.2f} x {inch_from_emu(H):.2f} in")
+    print(f"页数：{len(slides)}")
+    print()
+    for i, slide in enumerate(slides, 1):
+        texts = []
+        shapes = 0
+        pics = 0
+        for shp in slide.shapes:
+            shapes += 1
+            if shp.__class__.__name__ == "Picture":
+                pics += 1
+            if shp.has_text_frame:
+                t = shp.text_frame.text.strip()
+                if t:
+                    texts.append((shp, t))
+        title = texts[0][1].split("\n")[0][:42] if texts else "(无文字)"
+        print(f"P{i:>2} 形状={shapes:<3} 图片={pics:<2} 文本块={len(texts):<2} | {title}")
+        if not texts and pics == 0:
+            problems.append(f"P{i}: 整页没有任何文字或图片")
+
+        for shp, t in texts:
+            try:
+                w = pt_from_emu(shp.width)
+                h = pt_from_emu(shp.height)
+                left = pt_from_emu(shp.left)
+                top = pt_from_emu(shp.top)
+            except Exception:
+                continue
+            if w <= 0 or h <= 0:
+                continue
+            sizes = [r.font.size.pt for p in shp.text_frame.paragraphs
+                     for r in p.runs if r.font.size]
+            base = max(sizes) if sizes else 18.0
+            n_lines = max(1, wrap_lines(t, base, w))
+            # 单行文本只占一行字高（居中的数字/角标靠字形高度，不需要整行行高）
+            need = base * 0.95 if n_lines == 1 else n_lines * base * 1.32
+            if need > h * 1.05:
+                problems.append(
+                    f"P{i}: 文本可能溢出（约需 {need:.0f}pt，框高 {h:.0f}pt，{n_lines} 行）：{t[:28]!r}"
+                )
+            if left < -2 or top < -2 or left + w > pt_from_emu(W) + 2 or top + h > pt_from_emu(H) + 2:
+                problems.append(f"P{i}: 文本块超出画布边界：{t[:24]!r}")
+    print()
+    if args.render:
+        try:
+            rendered = _render_audit(args.pptx)
+        except Exception as exc:
+            print(f"（跳过渲染检查：{exc}）")
+            rendered = []
+        if rendered:
+            problems.extend(rendered)
+        else:
+            print("渲染检查：未发现文字重叠或越界。")
+    # 严格模式：OOXML Schema 校验（PowerPoint 同源规则，抓 LibreOffice 看不出的结构错误）
+    from .schemacheck import check_schema
+
+    schema_failures, schema_skipped, schema_ok = check_schema(args.pptx)
+    if not schema_ok:
+        print("严格模式校验（OOXML Schema）：不可用（缺少 Schema 文件），已跳过")
+    elif schema_failures:
+        print(f"严格模式校验（OOXML Schema）：发现 {len(schema_failures)} 个问题")
+        for f in schema_failures[:12]:
+            print(f"  ! {f}")
+        if len(schema_failures) > 12:
+            print(f"  ... 其余 {len(schema_failures) - 12} 个")
+        problems.append("严格模式校验发现 OOXML 结构错误（PowerPoint 会因此弹修复框）")
+    else:
+        print("严格模式校验（OOXML Schema）：全部部件通过")
+    if schema_skipped:
+        print(f"  （{len(schema_skipped)} 个部件含微软扩展命名空间，已跳过严格校验）")
+    if problems:
+        print(f"发现 {len(problems)} 个潜在问题：")
+        for p in problems:
+            print(f"  ! {p}")
+        return 1
+    print("自检通过：未发现明显溢出、越界或空白页。")
+    return 0
+
+
+# --------------------------------------------------------------------------
+def cmd_images(args) -> int:
+    from . import imagegen
+
+    if args.init_config:
+        target = args.init_config
+        if target.lower() in ("global", "user"):
+            target = imagegen.CONFIG_PATHS[1]          # ~/.pptxgen/config.yaml
+        if os.path.exists(target):
+            print(f"配置文件已存在，未覆盖：{os.path.abspath(target)}")
+            print("需要重新生成就先删掉它，或直接编辑。")
+            return 0
+        path = imagegen.write_config_template(target)
+        print(f"已生成配置模板：{os.path.abspath(path)}")
+        print("填好 base_url / model / api_key 后，运行：pptxgen images <课件.yaml>")
+        return 0
+
+    if not args.deck:
+        print("错误：请给出课件文件，或用 --init-config 生成配置模板", file=sys.stderr)
+        return 2
+    deck = load_deck(args.deck)
+    if args.backend:
+        os.environ["PPTXGEN_IMAGE_BACKEND"] = args.backend
+
+    opts = (deck.get("options") or {}).get("images") or {}
+    cache_dir = imagegen.normalize_dir(opts.get("cache_dir"), deck.get("_dir", "."))
+
+    # dry-run 不需要 key 也能算清单
+    try:
+        cfg = imagegen.load_config(opts)
+    except imagegen.ImageGenError as exc:
+        if not args.dry_run:
+            print(f"错误：{exc}", file=sys.stderr)
+            return 3
+        cfg = imagegen.ImageConfig(cache_dir=cache_dir)
+        cfg.backend = args.backend or opts.get("backend") or "openai-compatible"
+        cfg.model = opts.get("model") or "(未配置)"
+        cfg.size = opts.get("size") or imagegen.BACKENDS[cfg.backend].default_size
+        cfg.style = opts.get("style") or imagegen.DEFAULT_STYLE
+    cfg.cache_dir = cache_dir
+
+    jobs = imagegen.collect_jobs(deck, cfg)
+    if not jobs:
+        print("这份课件里没有 image_prompt，无需生成配图。")
+        print("在需要配图的页面加上一行即可，例如：")
+        print("  - type: content")
+        print("    image_prompt: 一间气象观测站，卫星天线和风速仪")
+        print("    image_side: right")
+        return 0
+
+    print(f"后端：{cfg.backend}   模型：{cfg.model}   尺寸：{cfg.size}")
+    print(f"缓存目录：{cfg.cache_dir}")
+    print(f"配图任务：{len(jobs)} 张（已缓存 {sum(1 for j in jobs if j['cached'])} 张）")
+    print()
+    for j in jobs:
+        mark = "[有]" if j["cached"] else "[待生成]"
+        print(f"  {mark} P{j['index']:>2} {j['title'][:28]:<30} {j['prompt'][:44]}")
+
+    if args.dry_run:
+        todo = [j for j in jobs if not j["cached"]]
+        print()
+        print(f"dry-run：本次会真实生成 {len(todo)} 张（另有 {len(jobs) - len(todo)} 张命中缓存）。")
+        print("确认后运行：pptxgen images " + args.deck)
+        return 0
+
+    print()
+    stats = imagegen.generate_for_deck(deck, cfg, force=args.force, limit=args.limit)
+    print()
+    print(f"完成：新生成 {stats['done']} 张，命中缓存 {stats['cached']} 张，失败 {len(stats['failed'])} 张")
+    for idx, err in stats["failed"]:
+        print(f"  ! P{idx}: {err}")
+    if stats["done"] or stats["cached"]:
+        print()
+        print("现在重新生成课件即可自动插入配图：")
+        print(f"  pptxgen build {args.deck}")
+    return 1 if stats["failed"] else 0
+
+
+def cmd_preview(args) -> int:
+    from . import preview as pv
+
+    if not os.path.exists(args.pptx):
+        print(f"错误：找不到文件 {args.pptx}", file=sys.stderr)
+        return 2
+    out_dir = args.out_dir or os.path.join(DEFAULT_OUT_DIR, "preview")
+    sheet_name = None if args.no_sheet else "_总览.png"
+    try:
+        pngs, sheet, pdf = pv.render(args.pptx, out_dir, dpi=args.dpi, sheet_name=sheet_name)
+    except RuntimeError as exc:
+        print(f"错误：{exc}", file=sys.stderr)
+        return 3
+    print(f"PDF ：{os.path.abspath(pdf)}")
+    print(f"共渲染 {len(pngs)} 页 PNG 到 {os.path.abspath(out_dir)}")
+    if sheet:
+        print(f"总览图：{os.path.abspath(sheet)}")
+        if args.open:
+            _open_file(os.path.abspath(sheet))
+    return 0
+
+
+def cmd_review(args) -> int:
+    from .review import format_findings, review_deck
+    from .spec import SpecError, load_deck
+
+    try:
+        deck = load_deck(args.deck)
+    except SpecError as exc:
+        print(f"错误：{exc}", file=sys.stderr)
+        return 2
+    findings, report = review_deck(deck, getattr(args, "pptx", None))
+    print(report)
+    print()
+    print(format_findings(findings))
+    return 1 if any(f.level == "错误" for f in findings) else 0
+
+
+def _render_audit(pptx_path: str) -> List[str]:
+    """用真实渲染结果（PDF 的文字块位置）检查重叠与越界。"""
+    import tempfile
+
+    import pymupdf as fitz
+
+    from . import preview as pv
+
+    problems: List[str] = []
+    with tempfile.TemporaryDirectory() as tmp:
+        pdf = pv.to_pdf(pptx_path, tmp)
+        with fitz.open(pdf) as doc:
+            for pno, page in enumerate(doc, 1):
+                W, H = page.rect.width, page.rect.height
+                blocks = [b for b in page.get_text("blocks") if b[4].strip()]
+                for b in blocks:
+                    x0, y0, x1, y1 = b[0], b[1], b[2], b[3]
+                    if x0 < -1.5 or y0 < -1.5 or x1 > W + 1.5 or y1 > H + 1.5:
+                        problems.append(f"P{pno}: 文字跑出页面：{_short(b[4])}")
+                for i in range(len(blocks)):
+                    for j in range(i + 1, len(blocks)):
+                        a, c = blocks[i], blocks[j]
+                        ox = min(a[2], c[2]) - max(a[0], c[0])
+                        oy = min(a[3], c[3]) - max(a[1], c[1])
+                        if ox <= 3 or oy <= 3:
+                            continue
+                        small = min((a[2] - a[0]) * (a[3] - a[1]), (c[2] - c[0]) * (c[3] - c[1]))
+                        if small > 0 and (ox * oy) / small > 0.25:
+                            problems.append(
+                                f"P{pno}: 文字互相重叠：{_short(a[4])} <-> {_short(c[4])}")
+    return problems
+
+
+def _short(text: str, n: int = 18) -> str:
+    return repr(" ".join(str(text).split())[:n])
+
+
+def cmd_demo(args) -> int:
+    out_dir = os.path.abspath(args.out_dir)
+    tpl_dir = os.path.join(out_dir, "assets")
+    os.makedirs(tpl_dir, exist_ok=True)
+    tpl_path = os.path.join(tpl_dir, "内置模板_16x9.pptx")
+    build_builtin_template(tpl_path)
+    print(f"已生成内置模板：{tpl_path}")
+
+    from .examples import DEMO_DECK_YAML
+
+    deck_path = os.path.join(out_dir, "示例课件_分数的初步认识.yaml")
+    with open(deck_path, "w", encoding="utf-8") as f:
+        f.write(DEMO_DECK_YAML)
+    print(f"已生成示例课件规格：{deck_path}")
+
+    tpl = load_template(tpl_path)
+    deck = load_deck(deck_path)
+    out_pptx = os.path.join(out_dir, "示例课件_分数的初步认识.pptx")
+    report = Renderer(tpl, deck).render(out_pptx)
+    print(f"已生成示例 pptx：{out_pptx}")
+    print(report.text())
+    return 0
+
+
+def cmd_init_deck(args) -> int:
+    from .examples import deck_template
+
+    out = args.out or f"{args.title}.yaml"
+    with open(out, "w", encoding="utf-8") as f:
+        f.write(deck_template(args.title))
+    print(f"已生成课件规格模板：{os.path.abspath(out)}")
+    print("填好后运行：pptxgen build " + out + " -t 你的模板.pptx")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())