@yujp_vc/ppt-assistant 0.0.0-stage → 1.5.2

package/deck_baseline.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+"""Baseline snapshot and page-by-page change ledger for scoped deck edits.
+
+A local edit is only trustworthy when it can be proven. This tool implements the
+contract used by careful human editors:
+
+  1. ``snapshot`` before touching the deck: stable page id + position + title +
+     body lines + numbers + notes.
+  2. edit a working copy, never the original.
+  3. ``compare`` after rebuilding: exactly which pages changed, which moved,
+     which protected pages were left untouched, and whether any change fell
+     outside the authorised scope.
+
+Stable ids are the slide names written by ``build_deck.py`` (``cSld/@name`` =
+``P01``, ``P02`` ...). They survive reordering; the page number does not. Decks
+without stable names fall back to positional ids and the ledger says so.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from pptx import Presentation
+from pptx.enum.shapes import MSO_SHAPE_TYPE
+
+NUMBER = re.compile(
+    r"-?\d[\d,，]*(?:\.\d+)?"
+    r"(?:\s*(?:%|‰|mm|cm|km|kg|mg|N·m|N|元|万元|亿元|美元|万|亿|ms|s|Hz|°))?"
+)
+CHROME = "chrome:"
+
+
+def sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _max_font(shape) -> float:
+    sizes = []
+    for paragraph in shape.text_frame.paragraphs:
+        if paragraph.font.size:
+            sizes.append(paragraph.font.size.pt)
+        for run in paragraph.runs:
+            if run.font.size:
+                sizes.append(run.font.size.pt)
+    return max(sizes) if sizes else 0.0
+
+
+def _title(slide, texts: list[dict]) -> str:
+    named = next((item for item in texts if item["shape"] == "title"), None)
+    if named:
+        return " ".join(named["text"].split())
+    placeholder = slide.shapes.title
+    if placeholder is not None and placeholder.text.strip():
+        return " ".join(placeholder.text.split())
+    if not texts:
+        return ""
+    # Largest type first, then the top-most shape: that is the visual heading.
+    ranked = sorted(texts, key=lambda item: (-item["size"], item.get("top", 0)))
+    return " ".join(ranked[0]["text"].split())
+
+
+def _page_record(slide, index: int) -> dict[str, Any]:
+    texts = []
+    lines: list[str] = []
+    numbers: list[str] = []
+    pictures = charts = tables = 0
+    for shape in slide.shapes:
+        if shape.shape_type == MSO_SHAPE_TYPE.PICTURE:
+            pictures += 1
+        elif getattr(shape, "has_chart", False):
+            charts += 1
+        elif getattr(shape, "has_table", False):
+            tables += 1
+        if not getattr(shape, "has_text_frame", False):
+            continue
+        text = shape.text.strip()
+        if not text:
+            continue
+        chrome = shape.name.startswith(CHROME)
+        texts.append({
+            "shape": shape.name, "shape_id": shape.shape_id,
+            "chrome": chrome, "size": round(_max_font(shape), 1),
+            "top": round(shape.top / 914400, 2) if shape.top is not None else 0,
+            "text": text,
+        })
+        if chrome:
+            continue
+        for line in text.split("\n"):
+            clean = " ".join(line.split())
+            if clean:
+                lines.append(clean)
+                numbers.extend(NUMBER.findall(clean))
+    numbers = ["".join(token.split()).replace("，", "").replace(",", "") for token in numbers]
+    notes = ""
+    if slide.has_notes_slide:
+        notes = slide.notes_slide.notes_text_frame.text.strip()
+    name = slide._element.cSld.get("name")
+    return {
+        "id": name or f"P{index:02d}",
+        "stable": bool(name),
+        "index": index,
+        "title": _title(slide, texts),
+        "texts": texts,
+        "lines": lines,
+        "numbers": numbers,
+        "pictures": pictures,
+        "charts": charts,
+        "tables": tables,
+        "notes": notes,
+    }
+
+
+def snapshot(pptx: Path) -> dict[str, Any]:
+    prs = Presentation(str(pptx))
+    pages = [_page_record(slide, index) for index, slide in enumerate(prs.slides, 1)]
+    return {
+        "file": str(pptx.resolve()),
+        "sha256": sha256(pptx),
+        "slides": len(pages),
+        "size_inches": [round(prs.slide_width / 914400, 3),
+                        round(prs.slide_height / 914400, 3)],
+        "stable_ids": any(page["stable"] for page in pages),
+        "pages": pages,
+    }
+
+
+def _diff(before: list[str], after: list[str]) -> tuple[list[str], list[str]]:
+    left, right = Counter(before), Counter(after)
+    return list((left - right).elements()), list((right - left).elements())
+
+
+def compare(before: dict[str, Any], after: dict[str, Any]) -> dict[str, Any]:
+    before_pages = before["pages"]
+    after_pages = after["pages"]
+    before_ids = {page["id"] for page in before_pages}
+    after_by_id: dict[str, dict] = {}
+    for page in after_pages:
+        after_by_id.setdefault(page["id"], page)
+    results = []
+    matched: set[str] = set()
+    for page in before_pages:
+        current = after_by_id.get(page["id"])
+        if current is None and not before["stable_ids"]:
+            current = after_pages[page["index"] - 1] if page["index"] <= len(after_pages) else None
+        if current is None:
+            results.append({"id": page["id"], "index": page["index"], "status": "missing",
+                            "title_before": page["title"], "title_after": ""})
+            continue
+        matched.add(current["id"])
+        removed_lines, added_lines = _diff(page["lines"], current["lines"])
+        removed_numbers, added_numbers = _diff(page["numbers"], current["numbers"])
+        content_changed = bool(removed_lines or added_lines or removed_numbers
+                               or added_numbers or page["notes"] != current["notes"]
+                               or page["pictures"] != current["pictures"])
+        moved = page["index"] != current["index"]
+        status = "changed" if content_changed else ("moved" if moved else "unchanged")
+        results.append({
+            "id": page["id"],
+            "index_before": page["index"],
+            "index_after": current["index"],
+            "status": status,
+            "moved": moved,
+            "title_before": page["title"],
+            "title_after": current["title"],
+            "title_changed": page["title"] != current["title"],
+            "lines_added": added_lines,
+            "lines_removed": removed_lines,
+            "numbers_added": added_numbers,
+            "numbers_removed": removed_numbers,
+            "pictures_before": page["pictures"],
+            "pictures_after": current["pictures"],
+            "notes_changed": page["notes"] != current["notes"],
+        })
+    added_pages = [page for page in after_pages if page["id"] not in before_ids
+                   and page["id"] not in matched]
+    order_before = [page["id"] for page in before_pages]
+    order_after = [page["id"] for page in after_pages]
+    return {
+        "before": {"file": before["file"], "sha256": before["sha256"], "slides": before["slides"]},
+        "after": {"file": after["file"], "sha256": after["sha256"], "slides": after["slides"]},
+        "stable_ids": before["stable_ids"] and after["stable_ids"],
+        "order_changed": order_before != order_after,
+        "order_before": order_before,
+        "order_after": order_after,
+        "pages": results,
+        "added": [{"id": page["id"], "index": page["index"], "title": page["title"]}
+                  for page in added_pages],
+        "changed": [page["id"] for page in results if page["status"] == "changed"],
+        "moved": [page["id"] for page in results if page.get("moved")],
+        "missing": [page["id"] for page in results if page["status"] == "missing"],
+    }
+
+
+def violations(report: dict[str, Any], protect: set[str], expect: set[str],
+               allow_reorder: bool) -> list[str]:
+    problems: list[str] = []
+    for page in report["pages"]:
+        page_id = page["id"]
+        touched = page["status"] in {"changed", "missing"}
+        if page_id in protect and touched:
+            problems.append(f"{page_id} 是保护页，但内容发生了变化")
+        if page_id in protect and page.get("moved"):
+            problems.append(f"{page_id} 是保护页，但位置从 {page['index_before']} "
+                            f"移到了 {page['index_after']}")
+        if expect and touched and page_id not in expect:
+            problems.append(f"{page_id} 不在授权修改范围内，却发生了内容变化")
+        if expect and page.get("moved") and not allow_reorder and page_id not in expect:
+            problems.append(f"{page_id} 未获授权就调整了页序")
+    for page in report["added"]:
+        if expect and page["id"] not in expect:
+            problems.append(f"{page['id']} 是新增页，不在授权范围内")
+    return problems
+
+
+def markdown(report: dict[str, Any], protect: set[str], expect: set[str],
+             problems: list[str]) -> str:
+    lines = [
+        "# 变更台账",
+        "",
+        f"- 基线：`{report['before']['file']}`  ·  {report['before']['slides']} 页",
+        f"- 当前：`{report['after']['file']}`  ·  {report['after']['slides']} 页",
+        f"- 稳定页名：{'是' if report['stable_ids'] else '否（按位置比较，仅供参照）'}",
+        f"- 页序变化：{'有' if report['order_changed'] else '无'}",
+        f"- 授权页：{', '.join(sorted(expect)) if expect else '未限定'}",
+        f"- 保护页：{', '.join(sorted(protect)) if protect else '未限定'}",
+        f"- 结论：{'**通过**' if not problems else '**未通过**'}",
+        "",
+        "| 页 | 位置 | 状态 | 标题 | 文字 +/− | 数字 +/− | 图片 |",
+        "| --- | --- | --- | --- | --- | --- | --- |",
+    ]
+    status_text = {"unchanged": "未变", "changed": "有改动",
+                   "moved": "仅换位", "missing": "缺失"}
+    for page in report["pages"]:
+        if page["status"] == "missing":
+            lines.append(f"| {page['id']} | {page['index']} → — | 缺失 | {page['title_before']} "
+                         "| — | — | — |")
+            continue
+        added = len(page["lines_added"]) + len(page["numbers_added"])
+        removed = len(page["lines_removed"]) + len(page["numbers_removed"])
+        title = page["title_after"] or "—"
+        if page["title_changed"]:
+            title = f"{page['title_before']} → {page['title_after']}"
+        lines.append(
+            f"| {page['id']} | {page['index_before']} → {page['index_after']} "
+            f"| {status_text.get(page['status'], page['status'])} | {title} "
+            f"| +{added} / −{removed} | +{len(page['numbers_added'])} / "
+            f"−{len(page['numbers_removed'])} | {page['pictures_before']} → "
+            f"{page['pictures_after']} |")
+    if report["added"]:
+        lines.extend(["", "## 新增页", ""])
+        for page in report["added"]:
+            lines.append(f"- {page['id']}（第 {page['index']} 页）：{page['title']}")
+    lines.extend(["", "## 明细", ""])
+    for page in report["pages"]:
+        if page["status"] != "changed":
+            continue
+        lines.append(f"### {page['id']} · {page['title_after'] or page['title_before']}")
+        for item in page["lines_removed"]:
+            lines.append(f"- − {item}")
+        for item in page["lines_added"]:
+            lines.append(f"- + {item}")
+        for item in page["numbers_removed"]:
+            lines.append(f"- 数字 − {item}")
+        for item in page["numbers_added"]:
+            lines.append(f"- 数字 + {item}")
+        if page["notes_changed"]:
+            lines.append("- 备注讲稿有变化")
+        lines.append("")
+    if problems:
+        lines.extend(["## 未通过项", ""])
+        lines.extend(f"- {item}" for item in problems)
+    return "\n".join(lines) + "\n"
+
+
+def parse_ids(value: str | None) -> set[str]:
+    return {token.strip() for token in (value or "").split(",") if token.strip()}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command", required=True)
+    snap = sub.add_parser("snapshot", help="write the pre-edit baseline")
+    snap.add_argument("pptx", type=Path)
+    snap.add_argument("out", type=Path)
+    cmp_ = sub.add_parser("compare", help="diff the baseline against the rebuilt deck")
+    cmp_.add_argument("baseline", type=Path)
+    cmp_.add_argument("pptx", type=Path)
+    cmp_.add_argument("--out", type=Path, help="markdown ledger path")
+    cmp_.add_argument("--json", type=Path, help="machine-readable ledger path")
+    cmp_.add_argument("--protect", help="comma-separated page ids that must not change")
+    cmp_.add_argument("--expect", help="comma-separated page ids allowed to change")
+    cmp_.add_argument("--allow-reorder", action="store_true",
+                      help="treat page moves as expected even outside --expect")
+    args = parser.parse_args()
+
+    if args.command == "snapshot":
+        data = snapshot(args.pptx)
+        args.out.parent.mkdir(parents=True, exist_ok=True)
+        args.out.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+        ids = ", ".join(page["id"] for page in data["pages"])
+        print(f"baseline: {args.out} ({data['slides']} pages; {ids})")
+        return 0
+
+    before = json.loads(args.baseline.read_text(encoding="utf-8"))
+    after = snapshot(args.pptx)
+    report = compare(before, after)
+    protect, expect = parse_ids(args.protect), parse_ids(args.expect)
+    problems = violations(report, protect, expect, args.allow_reorder)
+    if args.out:
+        args.out.parent.mkdir(parents=True, exist_ok=True)
+        args.out.write_text(markdown(report, protect, expect, problems), encoding="utf-8")
+    if args.json:
+        args.json.parent.mkdir(parents=True, exist_ok=True)
+        args.json.write_text(json.dumps({**report, "protect": sorted(protect),
+                                         "expect": sorted(expect),
+                                         "violations": problems},
+                                        ensure_ascii=False, indent=2), encoding="utf-8")
+    changed = len(report["changed"])
+    print(f"changed={changed} moved={len(report['moved'])} "
+          f"added={len(report['added'])} missing={len(report['missing'])} "
+          f"violations={len(problems)}")
+    for problem in problems:
+        print(f"VIOLATION: {problem}", file=sys.stderr)
+    return 2 if problems else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/delivery.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Audit a notes-only deck and synchronize explicit files with remote SHA256 checks."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import shlex
+import subprocess
+import tempfile
+from pathlib import Path, PurePosixPath
+from zipfile import ZipFile
+
+from pptx import Presentation
+from pptx.enum.shapes import MSO_SHAPE_TYPE
+
+from speaker_notes import parse_script, preservation_changes
+from video_gif import gif_info
+
+
+def sha256(path: Path) -> str:
+    with path.open("rb") as stream:
+        return hashlib.file_digest(stream, "sha256").hexdigest()
+
+
+def audit(pptx: Path, baseline: Path | None = None, script: Path | None = None,
+          gif_pages: tuple[int, ...] = ()) -> dict:
+    """Check notes equality and required animated media; compare all non-notes parts."""
+    with ZipFile(pptx) as archive:
+        if archive.testzip() or len(archive.namelist()) != len(set(archive.namelist())):
+            raise ValueError("invalid PPT ZIP")
+        entries = {name: archive.read(name) for name in archive.namelist()}
+    prs = Presentation(pptx)
+    report = {"pages": len(prs.slides), "sha256": sha256(pptx), "gif_pages": {},
+              "notes_pages": sum(s.has_notes_slide for s in prs.slides)}
+    if baseline:
+        with ZipFile(baseline) as archive:
+            original = {name: archive.read(name) for name in archive.namelist()}
+        changes = preservation_changes(original, entries)
+        if changes:
+            raise ValueError(f"content changed outside notes: {changes}")
+        report["content_preserved"] = True
+    if script:
+        sections, budget = parse_script(script, len(prs.slides))
+        for page, slide in enumerate(prs.slides, 1):
+            if not slide.has_notes_slide or slide.notes_slide.notes_text_frame.text != sections[page]:
+                raise ValueError(f"P{page}: notes differ from Markdown")
+        report.update(notes_match_markdown=True, budget_seconds=budget)
+    for page in gif_pages:
+        if not 1 <= page <= len(prs.slides):
+            raise ValueError(f"P{page}: page is outside deck")
+        animated = []
+        for shape in pictures(prs.slides[page - 1].shapes):
+            if shape.image.content_type == "image/gif":
+                animated.append(gif_info(shape.image.blob))
+        if not animated:
+            raise ValueError(f"P{page}: missing animated GIF")
+        report["gif_pages"][str(page)] = animated
+    return report
+
+
+def pictures(shapes):
+    """Visit pictures actually placed on the page, including nested groups."""
+    for shape in shapes:
+        if shape.shape_type == MSO_SHAPE_TYPE.GROUP:
+            yield from pictures(shape.shapes)
+        elif shape.shape_type == MSO_SHAPE_TYPE.PICTURE:
+            yield shape
+
+
+def sync_files(root: Path, files: list[Path], host: str, destination: str, timeout: float = 300) -> dict:
+    """Copy only requested regular files, never delete; verify remote SHA256 via SSH.
+
+    Uses the host's SSH configuration, agent or terminal-supported authentication.
+    Passwords are never accepted as parameters or persisted. Remote filenames are
+    shell-quoted.
+    """
+    if not re.fullmatch(r"[A-Za-z0-9_.@-]+", host) or host.startswith("-"):
+        raise ValueError("host must be an SSH alias or user@host")
+    if not destination.startswith("/") or any(char in destination for char in "\n\r\\"):
+        raise ValueError("remote destination must be an absolute POSIX path")
+    root = root.resolve()
+    relative = []
+    for path in files:
+        if path.is_symlink() or not path.is_file():
+            raise ValueError(f"not a regular deliverable file: {path}")
+        name = path.resolve().relative_to(root).as_posix()
+        if any(char in name for char in "\n\r\\"):
+            raise ValueError("deliverable filenames cannot contain newlines or backslashes")
+        relative.append(name)
+    if not relative or len(set(relative)) != len(relative):
+        raise ValueError("select at least one file, without duplicates")
+    ssh = ["ssh", "-o", "ConnectTimeout=10", host]
+    with tempfile.TemporaryDirectory(prefix="ppt-sync-") as directory:
+        listing = Path(directory) / "files"
+        listing.write_bytes(b"\0".join(name.encode() for name in relative) + b"\0")
+        subprocess.run([*ssh, "mkdir -p -- " + shlex.quote(destination)], check=True, timeout=timeout)
+        subprocess.run(["rsync", "-a", "--checksum", "--protect-args", "--from0",
+                        f"--files-from={listing}", "-e", "ssh -o ConnectTimeout=10",
+                        str(root) + "/", f"{host}:{destination.rstrip('/')}/"], check=True, timeout=timeout)
+    paths = [str(PurePosixPath(destination) / name) for name in relative]
+    command = "sha256sum -- " + " ".join(shlex.quote(path) for path in paths)
+    remote = subprocess.run([*ssh, command], capture_output=True, text=True, check=True, timeout=timeout)
+    lines = remote.stdout.splitlines()
+    expected = {str(PurePosixPath(destination) / name): sha256(root / name) for name in relative}
+    actual = {}
+    for line in lines:
+        digest, name = line.split("  ", 1)
+        actual[name] = digest
+    if expected != actual:
+        raise ValueError("remote SHA256 mismatch; synchronization is not verified")
+    return {"host": host, "destination": destination, "files": expected, "sha256_verified": True}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    checker = commands.add_parser("audit")
+    checker.add_argument("pptx", type=Path)
+    checker.add_argument("--baseline", type=Path)
+    checker.add_argument("--script", type=Path)
+    checker.add_argument("--gif-pages", type=int, nargs="*", default=[])
+    checker.add_argument("--report", type=Path)
+    sync = commands.add_parser("sync")
+    sync.add_argument("root", type=Path)
+    sync.add_argument("--files", nargs="+", required=True, help="paths relative to root")
+    sync.add_argument("--host", required=True)
+    sync.add_argument("--destination", required=True)
+    sync.add_argument("--timeout", type=float, default=300)
+    args = parser.parse_args()
+    if args.command == "audit":
+        report = audit(args.pptx, args.baseline, args.script, tuple(args.gif_pages))
+        if args.report:
+            args.report.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    else:
+        report = sync_files(args.root, [args.root / name for name in args.files], args.host, args.destination, args.timeout)
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/density-recipe.md

@@ -0,0 +1,110 @@
+# PPT 助手「密度优先」配方（博采众长版）
+
+来源：CyberPPT（高密度咨询式）、pptfast（DSH deck 引擎）、Awesome-PPT-Design-Skills（日系/未来科技编辑风）、ppt-master（工作流纪律）、dsh-office、dsh-wanghong-handwritten-ppt，以及本机多轮 DeepSeek 视觉模型的实测迭代。
+
+核心结论一句话：**pptfast 的默认是「编辑风留白」，要「饱满充实」必须显式走密度优先配方——dense 节奏 + 满幅背景 + 富内容 + 多版式 + 禁止大白卡 + 不对称构图。**
+
+## 0. 先定风格与结论（2026-11 补充）
+- **先当视觉总监**：受众/行动 → 七行风格简报（三个形容词、一个设计张力、密度、配色、字体、图片、节奏）→ 只选一套主配方（`style-recipes.md`），需要时主+辅，不平均折中。
+- **评审顺序**：先 `contact_sheet.py` 看缩略图总览，再抽高风险页全尺寸；不要一开始逐页看。
+- **style brief 四行**：用途/受众、气质、主色（1 个）、图像风格。主色写 `meta.accent`，需要时用 `meta.colors` 覆盖 bg/panel/text/muted；整套只用一个重点色。
+- **页计划先于 spec**：`页 / 结论句 / 证据 / 视觉类型 / 来源`。每个正文页标题必须是一句话结论，不是名词短语；一页一个思想，以上统下、顺序递进。
+- **配色按 HSL 想**：邻近色相做区分、同色相拉明度做层级；一页一个高饱和重点色，重点色出现 1–2 处。
+- **改稿先立合同**：`deck_baseline.py snapshot` 存基线 → 改工作副本 → `compare --protect … --expect …` 出台账；数字逐位核对，不为了好看改精度，不补材料里没有的评价词。
+- **工具边界**：一键 AI 工具常导出整页图片稿（文字不可编辑），不能交付；`quality_check.py` 会拦。
+
+## 1. 引擎与主题
+- 引擎：pptfast（语义 IR → 原生可编辑 PPTX + `audit` 自动几何质检）。
+- 主题按用途选：
+  - 实用/指南/汇报 → `consulting`（最密）或 `enterprise`；
+  - 情感/叙事 → `bloom`（暖玫瑰）；
+  - 科技 → `tech`；财务 → `insight`。
+- **narrative.pacing 一律用 `dense`**（balanced/spacious 会大量留白，用户明确拒绝「空荡荡」）。
+- 已知坑：`deck.spec.json` 的 `theme` 只接受**字符串**（不能写 `{id, style}` 覆盖主题色）；要改主题色用 `render --style <style.json>`（如把 consulting 的 muted `#786961` 加深到 `#5F5148` 级别，修掉暖纸渐变上的 0.06 对比度差）。
+
+## 2. 背景（消灭大白板的关键）
+- 每页必设 `background`，**禁止纯白**：
+  - 满幅照片：`{"kind":"asset","asset_id":<图>,"overlay":{"color":"#FFFFFF","opacity":0.85~0.88}}`（照片可见 + 文字可读，实测 0.88 是「饱满 vs 对比度」最优）。
+  - 或暖纸渐变（CyberPPT 8 色之一，如 `#F3F4EF`→`#F4F1EA`），用于表格/对比页（表格要最干净底）。
+- 封面/结束页用 `background: asset` + 深色 overlay（`#0B1220` 0.55）+ 白字。
+
+## 3. 排版尺度（数值化，来自编辑风 style-system）
+- 封面标题 56–76px 加粗；页标题 36–48px；正文 18–24px；说明/标签 11–13px。
+- 版心安全边距 ≥72px；12 列网格 + 24px 沟槽。
+- 行高：大标题 1.08，正文 1.35–1.55。
+- 线条 1–2px、直角 0–4px，**不用软阴影/霓虹/3D**。
+
+## 4. 内容密度（每页至少 4 个元素，忌纯 bullet）
+- 每页 content 至少 3–4 个组件：`paragraph` + `bullets` + `verdict_banner` + `image`/`image-split`；数字用 `kpi_cards`、对照用 `comparison`、流程用 `steps`。
+- **避免「密集 bullet 列表」**（编辑风明令：bullet 墙 = 单调）：把要点转成「标签块/步骤/时间线/对比模块/图标卡」。
+- **不用「大面积默认白卡片」**（CyberPPT 明令：默认白卡/默认圆角/默认阴影 = 失败）——卡片底色交给背景，不要叠白卡。
+
+## 5. 版式变换（每套 ≥5 种，相邻页不同）
+- 显式 pin 常用：`image-split`(image_side left/right)、`image-top`、`quote-stage`(金句)、`two-column`、`quiet-frame`、`narrow-column`。
+- **不对称构图**（编辑风核心）：一个主导块 + 一个辅助簇，别每页都居中对称；留一侧「安静区」形成节奏。
+- 不 pin 则交给引擎按 `seed` 自动选型（相邻页不重复）。
+- **避开 `image-lead-split`**：它右侧带一个空「手机占位框」，只有 `device_mockup` 组件能填；普通图文别用它。
+
+## 5.5 炫技版式（2026-11 补充）
+- 章节页 `section_number`：巨型数字（渐变/空心/图片填字）+ mesh 底 + 网格 + 进度点；一页只放一处巨字。
+- 满幅 `image_statement`：照片 + 巨型字艺（`art`）+ 结论标题；字艺放文字侧、透明度 0.14–0.22，别压主体。
+- 斜切 `split_diagonal`：两张图斜接 + 主色割线，适合「两种方案/两种光」对照。
+- 时间轴 `heat_bars`：阶段按 `minutes` 累加成甘特条，`fire/level` 映射颜色；比普通表格更适合讲顺序与时长。
+- 三图 `image_triptych`：左一主图 + 右两辅图，一主两辅；比等宽三列更有层级，适合生料/过程/成菜。
+- 毛玻璃 `glass_overlay`：从当前背景裁一块模糊+提亮做面板，`glass_opacity` 0.14–0.24；数字仍是真文本。
+- 金句 `quote_stage` / 大数字 `kpi_showcase`：用来换气，数字必须带标签和单位。
+- 透明抠图 `cutout_statement`：`--transparent` 生图 → 裁透明边 → 烘焙阴影 → 主体压版面；`image_annotated` 用原生圆点/引线/标签；`image_arch` 拱形裁切。
+- 质感：`mono/duotone/halftone/glitch`；glitch 只做点缀。生成图必须过 `image_check.py`（≥7、无文字/水印）。
+- 细节：`**关键词**` 主色高亮、`meta.transition` 页面切换、`sections/section_no` 进度点。
+- 克制：一套最多 2–3 页炫技，相邻页不连续堆，炫技页必须有真信息。
+
+## 6. 图片（图文并茂 + 切题 + 设计过）
+
+**取图两条路，先想清楚这页要的是「证据」还是「氛围」：**
+- 证据/实拍/真实产品 → 必应国内图片搜索（cn.bing.com，直连、无需 key、国内站点优先：苏宁/知乎/新浪/阿里/京东图床），国内找不到 → Pexels（外网、走代理）。关键词用标准说法（如「电动自行车」而非「两轮电瓶车」）命中更准。
+- 氛围/概念/封面/章节 → 用 GPT 生图（`gen_image.py`，见 §6.5）。没有合适实拍时不要硬凑，生图比错图好。
+
+**版式关系（图片必须「长在版面上」）：**
+- **满幅出血 + 渐变蒙版**（`image_hero`）：图铺满 13.33×7.5，蒙版从文字侧压到 0.9+，标题压暗部。封面/章节/收尾首选。
+- **单侧出血 + 渐变融边**（`image_overlay`）：文字一侧融出 55–65% 渐变面板，放正文 + ≤4 要点 + 2–3 个数字。
+- **瀑布流错位**（`image_wall`）：2–4 张等宽不等高、错位 0.26–0.84 英寸、圆角 + 细阴影。
+- **满格裁切 + 圆角/软阴影**（`image_split` / `image_grid`）：一强一弱，别让图缩在框里留白边。
+
+**硬规则：**
+- 一律 **cover 裁切**，不拉伸、不留白边；主体不能被裁掉。
+- 渐变色**取自图片暗部**（引擎自动采样），不要死黑；末端透明，起点 alpha 0.90–0.95。
+- 满幅页正文 ≤2 行、要点 ≤4 条、字号 ≥15；压图文字对比度按渲染色实测（≥4.5:1），不要凭感觉。
+- 每套至少 2 页满幅/出血图；相邻页不要连续用同一种图片关系。
+- 抓图/生图后**逐张 vision 核验「图对不对题」**；图片放 `assets/`，PIL 归一化成真 JPEG（源图常是 PNG 却命名 .jpg）。
+- 禁止真人/伤口（学术体制内类）；情感类可用牵手/剪影（无脸）。
+
+## 6.5 自主生图（GPT image）
+- 配置 `~/.config/ppt-assistant/image.json`（api_base + api_key），密钥不进 spec、不进成图、不进提交。
+- 尺寸 `1024x1024` / `1536x1024`（满幅 16:9 用这个再裁）/ `1024x1536`；单张 30 秒–4 分钟，后台跑。
+- 提示词骨架：`Cinematic <题材> photograph, 3:2 landscape, single clear subject on the <left|right> third, deep quiet negative space on the other side for text overlay, dramatic side backlight, cool <主色> shadows with warm amber rim light, shallow depth of field, ultra-clean uncluttered set, photorealistic, subtle film grain, no text, no letters, no logo, no watermark, no people, no collage.`
+- 一套 3–6 张，复用同一组光线/色温词；主体永远在蒙版对侧，给文字留约 40% 安静区。
+- 生成后亲眼看：主体是否对题、有没有乱码文字/水印/畸形手指、裁 16:9 后主体是否完整、蒙版侧够不够暗。最多重生成 2 次，仍不行换构图。
+- 真实性红线：生成图只作氛围/示意，页面与讲稿不得说成实拍、实验证据或真实产品照片。
+
+## 7. 容量上限（实测，写死避免试错）
+- `bullets` 最多 **6 条**（dense）。
+- `comparison` 最多 **5 行**。
+- `kpi_cards` 最多 **3 张**（4 张窄卡会被省略号截断文字）。
+- `steps` 最多 **5 步**（再多会溢出、压到底部 verdict）。
+- `image-split` 半宽侧塞不下 `paragraph + kpi(3) + verdict`；只放 `image + 3 张卡 + verdict`。
+- 超了就拆页/换组件，别硬塞。
+
+## 7.5 调研/分析类内容结构（学 TraeWork/WorkBuddy，天然密度高）
+封面/目录 → **多维度对比总表**（每个维度打分 + 综合第一标绿/色块突出）→ **逐对象深度档案**（每家/每项一页，末尾一段优劣势小结）→ 关键差异点表格+色块 → 结论页 **3 条可执行建议** → 最后一页「**一页速览**」总结卡片（可直接截图转发）。这种结构比「标题+要点」密度高得多，也更有用。
+
+## 8. 质检（闭环）
+0. `quality_check.py <deck.pptx>` → 必须 PASS（含「整页图片、无可编辑文字」拦截）。
+1. `pptfast audit <deck项目>` → 必须 exit 0（溢出/越界/低对比/重叠/截断全查）。
+2. `python3 vision_check.py <render/pg-xx.png> "<问题>"`（DeepSeek `deepseek-v4-flash-vision-exp`）逐页评饱满度，修到 ≥8。
+3. 渲染：`soffice --headless --convert-to pdf` → `pdftoppm -png`。
+4. 改稿：`deck_baseline.py compare baseline.json 新稿.pptx --protect … --expect …` → exit 0 且台账无违规。
+4. **查「单字成行」**：读 `pptx_read` 输出，看有没有「E / 照」「6–7 / 折」「…三 / 点」这类数字/字母后跟单字量词被断行的——有就重排/缩短标题要点。
+5. **以 audit 为准**：consulting 主题的 banner-motif 黄色装饰条会被 vision 误判成「文字被遮挡」，但确定性 audit 是 0 问题——几何结论信 audit，vision 只做「留白/断行/单调」这类主观反馈。
+
+## 8. 边界页（已知限制，写进预期）
+- pptfast 的 `cover`/`chapter`/`ending` 是「边界页」：`ending` 运行时只保留 `heading`（subheading/background/decor 全被丢弃），天然简洁——把它当「谢谢页」，别指望它「饱满」；收尾的丰富度放在它前面的 content 页（quote-stage 满幅金句）。

package/example.json

@@ -0,0 +1,26 @@
+{
+  "meta": {
+    "title": "PPT 助手示例"
+  },
+  "slides": [
+    {
+      "layout": "cover",
+      "title": "PPT 助手示例",
+      "body": "可编辑演示文稿"
+    },
+    {
+      "layout": "cards",
+      "title": "验证结果",
+      "items": [
+        {
+          "title": "可编辑",
+          "body": "原生文本与图表"
+        },
+        {
+          "title": "已校验",
+          "body": "结构检查通过"
+        }
+      ]
+    }
+  ]
+}