@yujp_vc/ppt-assistant 0.0.0-stage → 1.5.1

package/quality_check.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Fail-fast structural quality gate for generated PowerPoint decks.
+
+This is deliberately independent of LibreOffice: it catches the common failure
+where an agent delivers a text-only ``pptx_create`` draft before visual review.
+It does not replace rendering; it prevents an obviously incomplete deck from
+being presented as finished when rendering is unavailable.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import sys
+from pathlib import Path
+
+from pptx import Presentation
+from pptx.enum.shapes import MSO_SHAPE_TYPE
+
+
+def inspect(path: Path) -> dict:
+    prs = Presentation(str(path))
+    slides = []
+    for index, slide in enumerate(prs.slides, 1):
+        images = 0
+        tables = 0
+        charts = 0
+        text_boxes = 0
+        auto_shapes = 0
+        diagram_shapes = 0
+        picture_area = 0
+        slide_area = prs.slide_width * prs.slide_height
+        for shape in slide.shapes:
+            if shape.shape_type == 13:  # MSO_SHAPE_TYPE.PICTURE
+                images += 1
+                picture_area += (shape.width or 0) * (shape.height or 0)
+            elif getattr(shape, "has_table", False):
+                tables += 1
+            elif getattr(shape, "has_chart", False):
+                charts += 1
+            elif shape.shape_type == MSO_SHAPE_TYPE.AUTO_SHAPE:
+                auto_shapes += 1
+                area_ratio = shape.width * shape.height / (prs.slide_width * prs.slide_height)
+                if 0.01 <= area_ratio <= 0.75:
+                    diagram_shapes += 1
+            if getattr(shape, "has_text_frame", False) and shape.text.strip():
+                text_boxes += 1
+        slides.append(
+            {
+                "slide": index,
+                "images": images,
+                "tables": tables,
+                "charts": charts,
+                "text_boxes": text_boxes,
+                "auto_shapes": auto_shapes,
+                "diagram_shapes": diagram_shapes,
+                "picture_coverage": round(picture_area / slide_area, 3) if slide_area else 0,
+                "shapes": len(slide.shapes),
+            }
+        )
+
+    width = prs.slide_width / 914400
+    height = prs.slide_height / 914400
+    visual_slides = sum(
+        1 for item in slides
+        if item["images"] or item["tables"] or item["charts"] or item["diagram_shapes"] >= 3
+    )
+    signatures = {
+        (
+            item["images"],
+            item["tables"],
+            item["charts"],
+            min(item["text_boxes"], 14),
+            min(item["auto_shapes"], 8),
+            min(item["shapes"], 16),
+        )
+        for item in slides
+    }
+    return {
+        "file": str(path),
+        "slides": len(slides),
+        "width_in": round(width, 3),
+        "height_in": round(height, 3),
+        "aspect_ratio": round(width / height, 4) if height else None,
+        "visual_slides": visual_slides,
+        "layout_signatures": len(signatures),
+        "slide_stats": slides,
+    }
+
+
+def failures(report: dict) -> list[str]:
+    problems: list[str] = []
+    if report["slides"] >= 5:
+        if abs(report["aspect_ratio"] - 16 / 9) > 0.03:
+            problems.append(
+                f"页面比例为 {report['width_in']}×{report['height_in']}，不是 16:9"
+            )
+        required_visual = max(3, math.ceil(report["slides"] * 0.4))
+        if report["visual_slides"] < required_visual:
+            problems.append(
+                f"仅 {report['visual_slides']}/{report['slides']} 页含图片、表格、图表或原生图示，至少需要 {required_visual} 页"
+            )
+        if report["layout_signatures"] < 4:
+            problems.append(
+                f"仅检测到 {report['layout_signatures']} 种页面结构，至少需要 4 种"
+            )
+        text_only = [
+            item["slide"]
+            for item in report["slide_stats"]
+            if not (item["images"] or item["tables"] or item["charts"])
+            and item["text_boxes"] <= 3
+            and item["diagram_shapes"] == 0
+        ]
+        if len(text_only) > max(1, report["slides"] // 4):
+            problems.append(
+                "以下页面几乎只有文字框，疑似未完成排版：" + ", ".join(map(str, text_only))
+            )
+        image_only = [
+            item["slide"]
+            for item in report["slide_stats"]
+            if item["images"] and item["picture_coverage"] >= 0.95
+            and item["text_boxes"] == 0 and not (item["tables"] or item["charts"])
+        ]
+        if image_only:
+            problems.append(
+                "以下页面是整页图片、没有可编辑文字（疑似 AI 工具导出的图片稿）："
+                + ", ".join(map(str, image_only))
+            )
+    return problems
+
+
+def compare_template(report: dict, template_path: Path) -> list[str]:
+    """Require each output page to retain its source template's structure."""
+    baseline = inspect(template_path)
+    problems: list[str] = []
+    if report["slides"] != baseline["slides"]:
+        problems.append(
+            f"模板页数为 {baseline['slides']}，输出为 {report['slides']}，模板页未完整继承"
+        )
+        return problems
+    source = Presentation(str(template_path))
+    result = Presentation(report["file"])
+    for index, (before, after, source_slide, result_slide) in enumerate(
+        zip(baseline["slide_stats"], report["slide_stats"], source.slides, result.slides), 1
+    ):
+        source_types = [int(shape.shape_type) for shape in source_slide.shapes]
+        result_types = [int(shape.shape_type) for shape in result_slide.shapes]
+        if source_types != result_types:
+            problems.append(f"第 {index} 页形状结构与模板不一致")
+        if source_slide.slide_layout.name != result_slide.slide_layout.name:
+            problems.append(f"第 {index} 页布局与模板不一致")
+        if before["images"] != after["images"]:
+            problems.append(f"第 {index} 页图片数量与模板不一致")
+    return problems
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("pptx", type=Path)
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--template", type=Path,
+                        help="compare page count, layout, shapes and image count against a source template")
+    args = parser.parse_args()
+    try:
+        report = inspect(args.pptx)
+    except Exception as exc:  # clear failure for the agent, without a traceback wall
+        print(f"quality_check: 无法读取 {args.pptx}: {exc}", file=sys.stderr)
+        return 2
+    problems = failures(report)
+    if args.template:
+        if not args.template.is_file():
+            print(f"quality_check: template not found: {args.template}", file=sys.stderr)
+            return 2
+        template_problems = compare_template(report, args.template)
+        report["template"] = str(args.template.resolve())
+        report["template_failures"] = template_problems
+        problems.extend(template_problems)
+    if args.json:
+        report["failures"] = problems
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        print(
+            f"页数={report['slides']} 比例={report['width_in']}×{report['height_in']} "
+            f"视觉页={report['visual_slides']} 版式签名={report['layout_signatures']}"
+        )
+        if problems:
+            print("FAIL")
+            for problem in problems:
+                print(f"- {problem}")
+        else:
+            print("PASS")
+    return 1 if problems else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/render_ppt.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""Render a PPTX to PDF and PNG pages for visual review.
+
+Uses a system ``soffice`` when available, then the user-scoped official
+LibreOffice bundle installed by the setup script. The output stays beside the
+input deck so foreground/background jobs see the same files.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def find_soffice() -> Path | None:
+    found = shutil.which("soffice") or shutil.which("libreoffice")
+    candidates = [
+        Path.home()
+        / ".local/share/dsh-tools/libreoffice-official/opt/libreoffice26.8/opt/libreoffice26.8/program/soffice",
+        Path.home() / ".local/share/dsh-tools/libreoffice/usr/lib/libreoffice/program/soffice",
+    ]
+    if found:
+        candidates.insert(0, Path(found))
+    return next((path for path in candidates if path.is_file() and os.access(path, os.X_OK)), None)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("pptx", type=Path)
+    parser.add_argument("--outdir", type=Path)
+    parser.add_argument("--dpi", type=int, default=110)
+    args = parser.parse_args()
+    pptx = args.pptx.resolve()
+    if not pptx.is_file():
+        print(f"render_ppt: file not found: {pptx}", file=sys.stderr)
+        return 2
+    soffice = find_soffice()
+    if soffice is None:
+        print("render_ppt: no usable soffice/libreoffice found", file=sys.stderr)
+        return 3
+    outdir = (args.outdir or pptx.parent / ".render").resolve()
+    outdir.mkdir(parents=True, exist_ok=True)
+    for old_page in outdir.glob("page-*.png"):
+        old_page.unlink()
+    profile = outdir / ".lo-profile"
+    profile.mkdir(exist_ok=True)
+    env = os.environ.copy()
+    env["SAL_USE_VCLPLUGIN"] = "svp"
+    command = [
+        str(soffice),
+        "--headless",
+        "--nologo",
+        "--nodefault",
+        "--nofirststartwizard",
+        f"-env:UserInstallation=file://{profile}",
+        "--convert-to",
+        "pdf",
+        "--outdir",
+        str(outdir),
+        str(pptx),
+    ]
+    result = subprocess.run(command, env=env, text=True, capture_output=True)
+    if result.returncode:
+        print(result.stdout, end="")
+        print(result.stderr, end="", file=sys.stderr)
+        return result.returncode
+    pdf = outdir / f"{pptx.stem}.pdf"
+    if not pdf.is_file():
+        print(f"render_ppt: conversion completed without PDF: {pdf}", file=sys.stderr)
+        return 4
+    prefix = outdir / "page"
+    subprocess.run(["pdftoppm", "-png", "-r", str(args.dpi), str(pdf), str(prefix)], check=True)
+    raw_pages = sorted(outdir.glob("page-[0-9]*.png"))
+    staging = []
+    for index, raw_page in enumerate(raw_pages, 1):
+        temporary = outdir / f".render-page-{index}.png"
+        raw_page.rename(temporary)
+        staging.append(temporary)
+    for index, temporary in enumerate(staging, 1):
+        temporary.rename(outdir / f"page-{index:02d}.png")
+    print(f"renderer={soffice}")
+    print(f"pdf={pdf}")
+    print(f"pages={len(staging)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/requirements.txt

@@ -0,0 +1,7 @@
+Pillow>=10.0
+python-pptx>=0.6.23
+pypdf>=5.0
+numpy>=1.26
+lxml>=4.9
+matplotlib>=3.7
+requests>=2.28

package/restyle.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""
+restyle.py —— 把已有 PPT 原地「套用模板风格」：统一字体与配色，输出新文件。
+（排版级重排/内容改动走 ingest → 规格 → generate 的工作流。）
+
+规则：
+  - 字体：字号 >= 20pt 视为标题 → 华文中宋；否则正文 → Noto Serif SC。
+  - 配色：黑色及非白文本 → 主色藏蓝 #192D77；白色文本保留（避免深色背景上文字消失）。
+
+用法：
+    python3 restyle.py <input.pptx> <output.pptx>
+"""
+import sys
+from pptx import Presentation
+from pptx.dml.color import RGBColor
+from pptx.oxml.ns import qn
+
+NAVY = RGBColor(0x19, 0x2D, 0x77)
+TITLE_FONT = "华文中宋"
+BODY_FONT = "Noto Serif SC"
+
+# 模板调色板（这些颜色保留，不归一化）
+PALETTE = {'192D77', 'C00000', 'D24726'}
+
+def _set_font(run, name):
+    run.font.name = name
+    rPr = run._r.get_or_add_rPr()
+    for tag in ('a:latin', 'a:ea', 'a:cs'):
+        e = rPr.find(qn(tag))
+        if e is None:
+            e = rPr.makeelement(qn(tag), {})
+            rPr.append(e)
+        e.set('typeface', name)
+
+def _rgb_str(run):
+    """返回 run 当前实色 'RRGGBB'，theme/自动色等返回 None。"""
+    try:
+        s = str(run.font.color.rgb)
+        return s if len(s) == 6 else None
+    except Exception:
+        return None
+
+def _is_whiteish(hex6):
+    r, g, b = int(hex6[0:2], 16), int(hex6[2:4], 16), int(hex6[4:6], 16)
+    return r > 220 and g > 220 and b > 220
+
+def restyle(in_path, out_path):
+    prs = Presentation(in_path)
+    stats = {'runs': 0, 'font': 0, 'color': 0, 'title': 0, 'body': 0}
+    for slide in prs.slides:
+        for shape in slide.shapes:
+            if not shape.has_text_frame:
+                continue
+            for para in shape.text_frame.paragraphs:
+                for run in para.runs:
+                    if not run.text.strip():
+                        continue
+                    stats['runs'] += 1
+                    size = run.font.size.pt if run.font.size else 18
+                    name = TITLE_FONT if size >= 20 else BODY_FONT
+                    if size >= 20:
+                        stats['title'] += 1
+                    else:
+                        stats['body'] += 1
+                    _set_font(run, name)
+                    stats['font'] += 1
+                    hex6 = _rgb_str(run)
+                    if hex6 and not _is_whiteish(hex6) and hex6.upper() not in PALETTE:
+                        run.font.color.rgb = NAVY
+                        stats['color'] += 1
+    prs.save(out_path)
+    return stats
+
+if __name__ == '__main__':
+    if len(sys.argv) < 3:
+        print("用法: python3 restyle.py <input.pptx> <output.pptx>")
+        sys.exit(1)
+    s = restyle(sys.argv[1], sys.argv[2])
+    print(f"已重排: {sys.argv[1]} -> {sys.argv[2]}")
+    print(f"  处理文本段 {s['runs']}，标题 {s['title']}，正文 {s['body']}，改字体 {s['font']}，改配色 {s['color']}")

package/run_pptfast.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Run the installed pptfast package without importing or executing workspace code.
+# Desktop deployments historically keep it in ~/ppt-assistant/node_modules; the
+# repository checkout keeps the same package layout beside this launcher.
+engine_root=$(CDPATH= cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+candidate_paths=(
+  "$engine_root/node_modules/@liustack/pptfast/dist/cli.js"
+  "${HOME}/ppt-assistant/node_modules/@liustack/pptfast/dist/cli.js"
+)
+
+for cli in "${candidate_paths[@]}"; do
+  if [[ -f "$cli" ]]; then
+    if ! command -v node >/dev/null 2>&1; then
+      echo "pptfast: 找到运行包但未找到 Node.js（需要 Node 22.19+）" >&2
+      exit 78
+    fi
+    exec node "$cli" "$@"
+  fi
+done
+
+cat >&2 <<'EOF'
+pptfast: 未找到已安装的 @liustack/pptfast 运行包。
+请在部署环境安装 @liustack/pptfast@0.20.0，或使用内置 build_deck.py；不要执行用户工作区脚本。
+EOF
+exit 78

package/run_py.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Run a PPT-engine Python script with an interpreter that actually has the
+# deck dependencies. DSH's non-login shell may resolve `python3` to a runtime
+# without python-pptx; this picks the first usable interpreter instead.
+#
+#   bash <engine-root>/run_py.sh build_deck.py spec.json out.pptx
+#   PPT_PYTHON=/path/to/python bash <engine-root>/run_py.sh quality_check.py deck.pptx
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "run_py: usage: run_py.sh <script.py> [args...]" >&2
+  exit 64
+fi
+
+engine_root=$(CDPATH= cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+script=$1
+shift
+[[ -f "$script" || -f "$engine_root/$script" ]] || { echo "run_py: script not found: $script" >&2; exit 66; }
+
+candidates=()
+[[ -n "${PPT_PYTHON:-}" ]] && candidates+=("$PPT_PYTHON")
+candidates+=(
+  "${CONDA_PREFIX:-}/bin/python"
+  "$HOME/anaconda3/bin/python"
+  "$HOME/miniconda3/bin/python"
+  "python3"
+  "python3.13"
+  "python3.12"
+  "python3.11"
+  "python3.10"
+  "python3.9"
+)
+
+for python in "${candidates[@]}"; do
+  [[ -n "$python" ]] || continue
+  command -v "$python" >/dev/null 2>&1 || continue
+  if "$python" -c 'import pptx, PIL' >/dev/null 2>&1; then
+    exec "$python" "$script" "$@"
+  fi
+done
+
+echo "run_py: 没有找到带 python-pptx/Pillow 的解释器。请安装 requirements.txt，或设置 PPT_PYTHON。" >&2
+exit 69

package/slide_ops.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""Copy editable slides between presentations while retaining media and notes."""
+from __future__ import annotations
+
+import argparse
+import copy
+import json
+import tempfile
+from pathlib import Path
+from zipfile import ZipFile
+
+from pptx import Presentation
+from pptx.opc.packuri import PackURI
+
+R = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+
+
+def _remap_relationship_ids(element, mapping: dict[str, str]) -> None:
+    """Replace relationship ids in a copied slide XML tree."""
+    for node in element.iter():
+        for attribute, value in list(node.attrib.items()):
+            if attribute.startswith(f"{{{R}}}") and value in mapping:
+                node.set(attribute, mapping[value])
+
+
+def copy_slide(source_slide, target_prs: Presentation):
+    """Append one source slide to ``target_prs`` using the target's layout/theme."""
+    layout = target_prs.slide_layouts.get_by_name(source_slide.slide_layout.name)
+    if layout is None:
+        layout = target_prs.slide_layouts[-1]
+    target = target_prs.slides.add_slide(layout)
+    target_rels = target.part.rels
+    relationship_ids: dict[str, str] = {}
+    for relationship in source_slide.part.rels.values():
+        if relationship.reltype.endswith(("/slideLayout", "/notesSlide")):
+            continue
+        relationship_ids[relationship.rId] = target_rels._add_relationship(
+            relationship.reltype, relationship._target, relationship.is_external
+        )
+
+    copied = copy.deepcopy(source_slide._element)
+    _remap_relationship_ids(copied, relationship_ids)
+    destination = target._element
+    for child in list(destination):
+        destination.remove(child)
+    for child in copied:
+        destination.append(child)
+
+    if source_slide.has_notes_slide and source_slide.notes_slide.notes_text_frame.text:
+        target.notes_slide.notes_text_frame.text = source_slide.notes_slide.notes_text_frame.text
+    return target
+
+
+def import_dependencies(source_prs, target_prs, pages):
+    """Rename imported parts to avoid ZIP collisions; reject internal slide links.
+
+    Images, charts and their embedded workbooks may share filenames with the
+    target. Each imported graph retains sharing but receives a unique partname.
+    Slide navigation needs an explicit page mapping and is therefore rejected.
+    """
+    occupied = {str(part.partname) for part in target_prs.part.package.iter_parts()}
+    visited = set()
+
+    def visit(part):
+        if part in visited:
+            return
+        visited.add(part)
+        original = str(part.partname)
+        name = original
+        number = 1
+        path = Path(original)
+        while name in occupied:
+            name = str(path.with_name(f"{path.stem}_copy{number}{path.suffix}"))
+            number += 1
+        occupied.add(name)
+        part._partname = PackURI(name)
+        for relationship in part.rels.values():
+            if relationship.is_external:
+                continue
+            if relationship.reltype.endswith("/slide"):
+                raise ValueError("internal slide links require an explicit page mapping")
+            visit(relationship.target_part)
+
+    for page in pages:
+        for relationship in source_prs.slides[page - 1].part.rels.values():
+            if relationship.is_external or relationship.reltype.endswith(("/slideLayout", "/notesSlide")):
+                continue
+            if relationship.reltype.endswith("/slide"):
+                raise ValueError("internal slide links require an explicit page mapping")
+            visit(relationship.target_part)
+
+
+def copy_slides(source: Path, target: Path, output: Path, pages: list[int], position: int | None = None) -> dict:
+    """Copy selected 1-based pages from ``source`` into ``target`` atomically.
+
+    The target's slide layout and theme remain authoritative. Source media,
+    charts, external hyperlinks and editable shape XML are copied with relationship ids
+    remapped; source notes are copied when present. ``position`` is a zero-based
+    insertion point in the target's existing slide list, defaulting to append.
+    """
+    if output.resolve() in {source.resolve(), target.resolve()}:
+        raise ValueError("output must be separate from both input presentations")
+    if not pages or any(type(page) is not int or page < 1 for page in pages):
+        raise ValueError("pages must contain positive 1-based integers")
+    source_prs = Presentation(source)
+    target_prs = Presentation(target)
+    if any(page > len(source_prs.slides) for page in pages):
+        raise ValueError("source page is outside the presentation")
+    if position is not None and not 0 <= position <= len(target_prs.slides):
+        raise ValueError("position must be within the target slide list")
+    if (source_prs.slide_width, source_prs.slide_height) != (target_prs.slide_width, target_prs.slide_height):
+        raise ValueError("source and target slide dimensions must match")
+
+    import_dependencies(source_prs, target_prs, pages)
+    copied = [copy_slide(source_prs.slides[page - 1], target_prs) for page in pages]
+
+    def slide_id(slide):
+        return next(item for item in target_prs.slides._sldIdLst
+                    if target_prs.part.related_part(item.rId).partname == slide.part.partname)
+
+    if position is not None:
+        ids = target_prs.slides._sldIdLst
+        copied_ids = [slide_id(slide) for slide in copied]
+        for copied_id in copied_ids:
+            ids.remove(copied_id)
+        anchor = list(ids)[position] if position < len(ids) else None
+        for copied_id in copied_ids:
+            if anchor is None:
+                ids.append(copied_id)
+            else:
+                ids.insert(ids.index(anchor), copied_id)
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(dir=output.parent, prefix=".slide-ops-") as directory:
+        temporary = Path(directory) / "presentation.pptx"
+        target_prs.save(temporary)
+        with ZipFile(temporary) as archive:
+            if len(archive.namelist()) != len(set(archive.namelist())) or archive.testzip():
+                raise ValueError("copied deck contains invalid or duplicate ZIP entries")
+        readback = Presentation(temporary)
+        if len(readback.slides) != len(target_prs.slides):
+            raise ValueError("slide count changed during save")
+        temporary.replace(output)
+    return {"source_pages": pages, "copied": len(pages), "output_pages": len(target_prs.slides)}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("source", type=Path, help="presentation containing reusable pages")
+    parser.add_argument("target", type=Path, help="presentation receiving the pages")
+    parser.add_argument("output", type=Path)
+    parser.add_argument("--pages", type=int, nargs="+", required=True)
+    parser.add_argument("--position", type=int, help="zero-based insertion point; default appends")
+    args = parser.parse_args()
+    print(json.dumps(copy_slides(args.source, args.target, args.output, args.pages, args.position)))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())