minimal-agent 0.8.2 → 0.10.0

package/skills/ui-design/scripts/source_usage_check.py

@@ -0,0 +1,581 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+source_usage_check.py —— 确定性硬闸门：校验「用户提供的图片是否都用进了 deck.html」。
+
+为什么需要
+==========
+用户红线：客户给的图**一定要用进 PPT，不能给了不用**。靠 prompt 要求弱模型「别冷落客户图」不可靠，
+故收归确定性闸门（同 image_plan_lint / deck_pages_check 哲学）：读 material.json 的客户图清单 + deck.html，
+逐张核对是否被真实资源引用。未用尽 → 报 UNUSED + 退出 1，让构建步必须补上。
+
+判定
+====
+- material.json 无 / 无客户图 → `SOURCE_USAGE_OK: 无客户图`，退出 0（纯 topic / 纯文档无图，无需检查）。
+- 每张 images[].file（src_K.png）必须出现在真实资源引用里才算「已用」：`img/src`、`source/srcset`、
+  SVG `image href`、内联 style 或 `<style>` 里的 `url(...)` 等。正文、注释、脚本字符串里出现文件名不算。
+- 图生图增强派生图是默认首选使用：默认识别 `enhanced_src_K.png` / `src_K_enhanced.png`，也支持 material
+  中显式声明 `derived_files` / `enhanced_file`。原图直接使用只在 `image_generation_report.json` 记录对应增强图失败时允许。
+  导出前可加 `--require-existing-derived`，要求增强图必须真实存在于 build/assets；若失败报告存在，则原图 fallback 可通过。
+- 低清原图不得做全幅背景：宽 <1280 或像素 <0.8MP 的原始 `src_K` 若出现在 CSS `background-image`
+  / `data-bg` / `data-background` 中，判 `LOW_RES_BACKGROUND`。这类图应走 `source-enhanced` 或小图/侧图/画廊。
+- 全部用上 → `SOURCE_USAGE_OK: N 张客户图全部用上`，退出 0。
+- 有未用 → `UNUSED: src_3.png, src_5.png（共 K/N 张客户图未用进 deck）`，退出 1。
+- deck.html 不存在 → `NO_DECK: …`，退出 2（无法核验；构建未产出 deck）。
+
+用法
+====
+    python source_usage_check.py [--build ./build] [--require-existing-derived]
+    python source_usage_check.py --material ./build/material.json --deck ./build/deck.html
+    python source_usage_check.py --build ./build --design-only          # 仅章节错位预警（WARNING，恒 0）
+    python source_usage_check.py --build ./build --layout-intent-only   # 仅版式违规（ERROR，exit 1；可修档）
+"""
+
+import argparse
+from html.parser import HTMLParser
+import json
+import os
+import re
+import sys
+from urllib.parse import unquote, urlparse
+
+
+URL_RE = re.compile(r"url\(\s*(['\"]?)(.*?)\1\s*\)", re.IGNORECASE | re.DOTALL)
+LOW_RES_BG_MIN_WIDTH = 1280
+LOW_RES_BG_MIN_MEGAPIXELS = 0.8
+RESOURCE_ATTRS = {
+    "src",
+    "poster",
+    "data-src",
+}
+BACKGROUND_RESOURCE_ATTRS = {"data-bg", "data-background"}
+HREF_RESOURCE_TAGS = {"image", "feimage"}
+SRCSET_ATTRS = {"srcset", "data-srcset"}
+
+
+def _normalize_resource(value):
+    """从 URL/路径里取 basename；query/hash 不影响匹配。"""
+    value = (value or "").strip().strip("\"'")
+    if not value:
+        return ""
+    parsed = urlparse(value)
+    path = parsed.path or value.split("?", 1)[0].split("#", 1)[0]
+    return os.path.basename(unquote(path))
+
+
+def _srcset_urls(value):
+    for item in (value or "").split(","):
+        first = item.strip().split()
+        if first:
+            yield first[0]
+
+
+def _css_urls(value):
+    for m in URL_RE.finditer(value or ""):
+        yield m.group(2)
+
+
+class ResourceRefParser(HTMLParser):
+    """只收集 HTML/CSS 资源引用，不把正文、注释、script 字符串当作图片使用。
+
+    另单独收集「整页背景用法」证据（bg_img_uses，供 --layout-intent-only 版式违规检查）：
+    `<img class="bg-img">` 的 src 与 data-source-file——**不并入 refs/background_refs**，
+    以免改变 hard 档（未用尽/低清背景）的既有判定语义。"""
+
+    def __init__(self):
+        super().__init__(convert_charrefs=True)
+        self.refs = set()
+        self.background_refs = set()
+        # [(slide_no, basename)]；slide_no 从 1 起（按 class 含 slide token 的容器计数），供报错定位页。
+        self.bg_img_uses = []
+        self._slide_no = 0
+        self._style_depth = 0
+        self._script_depth = 0
+
+    def handle_starttag(self, tag, attrs):
+        tag = tag.lower()
+        attr_map = {str(k).lower(): (v or "") for k, v in attrs}
+        if tag == "style":
+            self._style_depth += 1
+        elif tag == "script":
+            self._script_depth += 1
+
+        class_tokens = set((attr_map.get("class") or "").split())
+        if "slide" in class_tokens:
+            self._slide_no += 1
+        if tag == "img" and "bg-img" in class_tokens:
+            for key in ("src", "data-source-file"):
+                base = _normalize_resource(attr_map.get(key, ""))
+                if base:
+                    self.bg_img_uses.append((self._slide_no, base))
+
+        for raw_name, raw_value in attrs:
+            name = (raw_name or "").lower()
+            value = raw_value or ""
+            if name in RESOURCE_ATTRS:
+                self._add(value)
+            elif name in BACKGROUND_RESOURCE_ATTRS:
+                self._add_background(value)
+            elif name in {"href", "xlink:href"} and self._is_resource_href(tag, attr_map):
+                self._add(value)
+            elif name in SRCSET_ATTRS:
+                for url in _srcset_urls(value):
+                    self._add(url)
+            elif name == "style":
+                for url in _css_urls(value):
+                    self._add_background(url)
+
+    def handle_endtag(self, tag):
+        tag = tag.lower()
+        if tag == "style" and self._style_depth:
+            self._style_depth -= 1
+        elif tag == "script" and self._script_depth:
+            self._script_depth -= 1
+
+    def handle_data(self, data):
+        if self._style_depth and not self._script_depth:
+            for url in _css_urls(data):
+                self._add_background(url)
+
+    def _add(self, value):
+        base = _normalize_resource(value)
+        if base:
+            self.refs.add(base)
+
+    def _add_background(self, value):
+        base = _normalize_resource(value)
+        if base:
+            self.refs.add(base)
+            self.background_refs.add(base)
+
+    def _is_resource_href(self, tag, attrs):
+        if tag in HREF_RESOURCE_TAGS:
+            return True
+        if tag == "link":
+            rel = attrs.get("rel", "").lower()
+            as_type = attrs.get("as", "").lower()
+            return "preload" in rel and as_type == "image"
+        return False
+
+
+def extract_resource_filenames(html):
+    parser = ResourceRefParser()
+    parser.feed(html)
+    parser.close()
+    return parser.refs
+
+
+def extract_resource_usage(html):
+    parser = ResourceRefParser()
+    parser.feed(html)
+    parser.close()
+    return parser.refs, parser.background_refs
+
+
+def extract_layout_usage(html):
+    """供版式违规检查：([(slide_no, basename)] 的 .bg-img 用法, CSS background basename 集合)。"""
+    parser = ResourceRefParser()
+    parser.feed(html)
+    parser.close()
+    return parser.bg_img_uses, parser.background_refs
+
+
+def _derived_candidates(image):
+    if not isinstance(image, dict):
+        return []
+    fn = image.get("file")
+    out = []
+    for key in ("enhanced_file", "derived_file"):
+        v = image.get(key)
+        if isinstance(v, str) and v:
+            out.append(os.path.basename(v))
+    for key in ("derived_files", "enhanced_files"):
+        values = image.get(key)
+        if isinstance(values, list):
+            out.extend(os.path.basename(v) for v in values if isinstance(v, str) and v)
+    if isinstance(fn, str) and fn:
+        stem, ext = os.path.splitext(fn)
+        out.append(f"enhanced_{fn}")
+        out.append(f"{stem}_enhanced{ext or '.png'}")
+    # 去重保序
+    seen = set()
+    result = []
+    for item in out:
+        if item and item not in seen:
+            seen.add(item)
+            result.append(item)
+    return result
+
+
+def _asset_exists(deck_path, filename):
+    """增强派生图只有真实落盘才算用上；普通原图由抽取阶段保证存在。"""
+    if not filename:
+        return False
+    deck_dir = os.path.dirname(os.path.abspath(deck_path))
+    candidates = [
+        os.path.join(deck_dir, "assets", filename),
+        os.path.join(os.path.dirname(deck_dir), "assets", filename),
+    ]
+    return any(os.path.isfile(p) for p in candidates)
+
+
+def _is_low_res_for_background(image):
+    try:
+        w = int(image.get("w") or 0)
+        h = int(image.get("h") or 0)
+    except Exception:
+        return False
+    if w <= 0 or h <= 0:
+        return False
+    return w < LOW_RES_BG_MIN_WIDTH or (w * h / 1_000_000) < LOW_RES_BG_MIN_MEGAPIXELS
+
+
+def _load_generation_report(deck_path):
+    deck_dir = os.path.dirname(os.path.abspath(deck_path))
+    candidates = [
+        os.path.join(deck_dir, "image_generation_report.json"),
+        os.path.join(os.path.dirname(deck_dir), "image_generation_report.json"),
+    ]
+    for path in candidates:
+        try:
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+            if isinstance(data, dict):
+                return data
+        except Exception:
+            continue
+    return {}
+
+
+def _failed_enhanced_files(report):
+    out = set()
+    for item in (report.get("degraded") or []):
+        if not isinstance(item, dict):
+            continue
+        if item.get("mode") == "image-to-image" and item.get("file"):
+            out.add(os.path.basename(item["file"]))
+    return out
+
+
+CJK_RE = re.compile(r"[一-鿿]+")
+WORD_RE = re.compile(r"[A-Za-z0-9]{2,}")
+# 无锚定意义的 section 形态：pdf/pptx 按页号命名（"page 3" / "第3页"）——不是真实章节标题。
+PAGELIKE_SECTION_RE = re.compile(r"#?\s*(?:page|slide|p)\s*\d+|第\s*\d+\s*[页张]", re.IGNORECASE)
+
+
+def _tokens(text):
+    """CJK 双字 bigram + ASCII 词（≥2 字符小写）——供「章节+邻近文案 ↔ 页主题」词元交集判定。"""
+    out = set()
+    for seg in CJK_RE.findall(text or ""):
+        for i in range(len(seg) - 1):
+            out.add(seg[i : i + 2])
+    for w in WORD_RE.findall(text or ""):
+        out.add(w.lower())
+    return out
+
+
+def _section_meaningful(section, file=""):
+    """章节字段是否可作配页锚点：空 / 等于文件名（独立散图）/ 纯页号（pdf/pptx 锚）都不算。"""
+    sec = (section or "").strip()
+    if not sec:
+        return False
+    base = os.path.basename(file or "")
+    if sec in (base, os.path.splitext(base)[0]):
+        return False
+    if PAGELIKE_SECTION_RE.fullmatch(sec):
+        return False
+    return True
+
+
+def _load_json_or_none(path):
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+
+def section_mismatch_warnings(design_path, plan_path):
+    """【图片章节错位】（治张冠李戴，WARNING 级不阻断）：客户图来自原文特定章节（plan.section，
+    由 extract→material→plan 透传），却被设计步配到词元零交集的页。返回 (warnings, checked)。
+
+    诚实边界：词元交集（CJK bigram + ASCII 词）是模糊判定，只报 WARNING + 精确定位；
+    真正防错在设计 prompt 的「章节锚定优先」硬规则，本检查是它的确定性兜底。
+    豁免：纯背景氛围（source_enhanced_bg）与弃用图（discard）不做章节锚定；
+    section 无意义（空/文件名/页号）跳过。design/plan 缺失或非法 → 返回空（不添乱）。"""
+    design = _load_json_or_none(design_path)
+    plan = _load_json_or_none(plan_path)
+    if not isinstance(design, dict) or not isinstance(plan, dict):
+        return [], 0
+    plan_map = {
+        str(item.get("file")): item
+        for item in (plan.get("images") or [])
+        if isinstance(item, dict) and item.get("file")
+    }
+    warnings = []
+    checked = 0
+    for p in design.get("pages") or []:
+        if not isinstance(p, dict):
+            continue
+        visual = p.get("visual") if isinstance(p.get("visual"), dict) else {}
+        src = visual.get("source_file")
+        if not isinstance(src, str) or not src:
+            continue
+        src = os.path.basename(src)
+        entry = plan_map.get(src) or {}
+        if str(entry.get("usage_intent") or "") in ("source_enhanced_bg", "discard"):
+            continue
+        section = entry.get("section")
+        if not _section_meaningful(section, src):
+            continue
+        checked += 1
+        img_tokens = _tokens(str(section)) | _tokens(str(entry.get("near_text") or ""))
+        page_text = " ".join(
+            str(p.get(k) or "") for k in ("title", "key_point", "one_sentence_takeaway")
+        )
+        if _tokens(page_text) & img_tokens:
+            continue
+        warnings.append(
+            f"【图片章节错位】页 {p.get('page', '?')} · 「{src}」来自章节『{section}』"
+            f"· 页主题『{str(p.get('title') or '')[:24]}』——两者词元零交集"
+            f"  ｜建议移到覆盖该章节内容的页；确属跨章节氛围素材可忽略"
+        )
+    return warnings, checked
+
+
+# 规划为「框内展示」的意图：被用作整页背景即版式违规（2026-07-03 真机第4页事故：src_6 识图明说
+# "绝对不能用作整页背景或叠字"、规划判 direct_contain，build 仍铺成 .bg-img 整页背景+叠打同款标题）。
+# source_enhanced_bg（本就是背景）/ source_enhanced_hero（编辑式融合 hero 允许出血）/ discard 豁免。
+CONTAIN_INTENTS = ("direct_contain", "gallery", "small_evidence")
+
+
+def _stem(name):
+    return os.path.splitext(os.path.basename(name or ""))[0]
+
+
+def layout_intent_violations(material_path, deck_path):
+    """【版式违规】（Edit 可修，供视觉门可修档驱动修复轮，不进 hard 档）：
+    规划 usage_intent ∈ CONTAIN_INTENTS 的客户图（含其 enhanced 派生图），却在 deck.html 中
+    被用作整页背景（`<img class="bg-img">` 或 CSS background url()）。
+
+    比对按**文件名 stem**（掉扩展名）：真机 deck 里 data-source-file="src_6.jpg" 而 material
+    记 src_6.png，扩展名会漂移。返回 (errors, checked)；material/plan/deck 缺失 → ([], 0)。"""
+    material = _load_json_or_none(material_path)
+    if not isinstance(material, dict):
+        return [], 0
+    image_items = [
+        im for im in (material.get("images") or [])
+        if isinstance(im, dict) and im.get("file")
+    ]
+    if not image_items:
+        return [], 0
+    plan_map = _load_plan_map(material_path, deck_path)
+    if not plan_map:
+        return [], 0
+    try:
+        with open(deck_path, encoding="utf-8") as f:
+            html = f.read()
+    except Exception:
+        return [], 0
+
+    bg_img_uses, css_bg_refs = extract_layout_usage(html)
+    bg_stem_pages = {}
+    for slide_no, base in bg_img_uses:
+        bg_stem_pages.setdefault(_stem(base), set()).add(slide_no)
+    for base in css_bg_refs:
+        bg_stem_pages.setdefault(_stem(base), set())
+
+    errors = []
+    checked = 0
+    for im in image_items:
+        fn = im.get("file")
+        plan = plan_map.get(fn) if isinstance(plan_map.get(fn), dict) else {}
+        intent = str(plan.get("usage_intent") or "")
+        if intent not in CONTAIN_INTENTS:
+            continue
+        checked += 1
+        cand_stems = {_stem(fn)} | {_stem(c) for c in _derived_candidates(im)}
+        hit_pages = set()
+        hit = False
+        for stem in cand_stems:
+            if stem in bg_stem_pages:
+                hit = True
+                hit_pages |= bg_stem_pages[stem]
+        if not hit:
+            continue
+        pages = "/".join(str(p) for p in sorted(hit_pages) if p) or "?"
+        errors.append(
+            f"ERROR: 【版式违规】页 {pages} · 「{fn}」规划为 {intent}（框内展示），"
+            f"却被用作整页背景（.bg-img / CSS background）"
+            f"  ｜必须改为 contain 框图/画廊格：换成 <img> 放进图槽卡片，背景另配氛围图或纯色；"
+            f"带自有文字的截图类素材当背景会与顶层文字互相打架（识图/规划早已禁止）"
+        )
+    return errors, checked
+
+
+def _load_plan_map(material_path, deck_path):
+    """source_layout_plan.json 的 {file: entry}（与 material 同目录探测；缺则空 = 行为不变）。"""
+    for base in (os.path.dirname(os.path.abspath(material_path)),
+                 os.path.dirname(os.path.abspath(deck_path))):
+        path = os.path.join(base, "source_layout_plan.json")
+        try:
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+        except Exception:
+            continue
+        out = {}
+        for item in (data.get("images") or []) if isinstance(data, dict) else []:
+            if isinstance(item, dict) and item.get("file"):
+                out[str(item["file"])] = item
+        return out
+    return {}
+
+
+def check(material_path, deck_path, require_existing_derived=False):
+    """返回 (code, message)。code: 0 ok / 1 有未用 / 2 无 deck。"""
+    try:
+        with open(material_path, encoding="utf-8") as f:
+            material = json.load(f)
+    except Exception:
+        return 0, "SOURCE_USAGE_OK: 无 material.json（无客户图，跳过）"
+
+    images = material.get("images") or []
+    image_items = [im for im in images if isinstance(im, dict) and im.get("file")]
+    files = [im.get("file") for im in image_items]
+    if not files:
+        return 0, "SOURCE_USAGE_OK: 无客户图"
+
+    if not os.path.isfile(deck_path):
+        return 2, f"NO_DECK: {deck_path} 不存在，无法核验客户图是否用进 deck"
+
+    with open(deck_path, encoding="utf-8") as f:
+        html = f.read()
+
+    used, background_used = extract_resource_usage(html)
+    # 2026-07-05 真机复盘：material.json 没记 enhanced_file 时，_derived_candidates 只能按
+    # 「原文件同扩展名」猜（enhanced_src_2.jpg），但生图实际落盘常是 .png——deck.html 引用
+    # enhanced_src_2.png，逐字符串匹配对不上，客户图被误判 UNUSED 直接 hard halt（真机连续两次
+    # 事故）。用 stem（掉扩展名）建索引兜底，与 layout_intent_violations 的扩展名漂移处理同口径。
+    used_stems = {}
+    for u in used:
+        used_stems.setdefault(_stem(u), u)
+    failed_enhanced = _failed_enhanced_files(_load_generation_report(deck_path))
+    plan_map = _load_plan_map(material_path, deck_path)
+    unused = []
+    direct_without_failed_enhance = []
+    low_res_background = []
+    for im in image_items:
+        fn = im.get("file")
+        plan = plan_map.get(fn) if isinstance(plan_map.get(fn), dict) else {}
+        # 弃用图（规划判定与主题不相关/负面，2026-07-02 坠机图事故）：豁免「必须用上」。
+        # 「弃用图反被用进 deck」不在此判——那是 Edit 可修缺陷，归 deck_visual_style_check ERROR
+        # 驱动修复轮；本检查在 hard 档（失败即 halt、先于修复步），只留「未用尽」这类构建级失败。
+        if str(plan.get("usage_intent") or "") == "discard":
+            continue
+        direct_used = fn in used
+        candidates = _derived_candidates(im)
+        derived_used = []
+        missing_derived = []
+        for c in candidates:
+            actual = c if c in used else used_stems.get(_stem(c))
+            if not actual:
+                continue
+            if require_existing_derived and not _asset_exists(deck_path, actual):
+                missing_derived.append(actual)
+                continue
+            derived_used.append(actual)
+        has_failed_enhance = any(c in failed_enhanced for c in candidates)
+        if direct_used and not derived_used and not has_failed_enhance:
+            direct_without_failed_enhance.append(fn)
+        if not direct_used and not derived_used:
+            unused.append(fn)
+        if fn in background_used and _is_low_res_for_background(im):
+            low_res_background.append(
+                f"{fn}({im.get('w', '?')}×{im.get('h', '?')})"
+            )
+    if low_res_background:
+        return 1, (
+            "LOW_RES_BACKGROUND: "
+            + ", ".join(low_res_background)
+            + " 被当作背景使用；低清客户原图必须先 source-enhanced 图生图扩图/重绘，"
+            + "或改成小图/侧图/画廊/证据图。"
+        )
+    if direct_without_failed_enhance:
+        return 1, (
+            "SOURCE_DIRECT_WITHOUT_ENHANCE_FAILURE: "
+            + ", ".join(direct_without_failed_enhance)
+            + " 直接使用了客户原图；当前策略要求先使用 enhanced_src_K 图生图派生图，"
+            + "只有 image_generation_report.json 记录对应 image-to-image 失败时才允许原图 fallback。"
+        )
+    if unused:
+        return 1, (
+            f"UNUSED: {', '.join(unused)}"
+            f"（共 {len(unused)}/{len(files)} 张客户图未用进 deck —— 必须全部用上）"
+        )
+    n_discard = sum(
+        1 for im in image_items
+        if str((plan_map.get(im.get("file")) or {}).get("usage_intent") or "") == "discard"
+    )
+    if n_discard:
+        return 0, (
+            f"SOURCE_USAGE_OK: {len(files) - n_discard}/{len(files)} 张客户图用上"
+            f"（{n_discard} 张规划弃用，豁免）"
+        )
+    return 0, f"SOURCE_USAGE_OK: {len(files)} 张客户图全部用上"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="校验客户图是否都用进 deck.html（确定性硬闸门）")
+    parser.add_argument("--build", default="./build", help="产物目录（默认 ./build）")
+    parser.add_argument("--material", default=None, help="material.json 路径（覆盖 --build 推断）")
+    parser.add_argument("--deck", default=None, help="deck.html 路径（覆盖 --build 推断）")
+    parser.add_argument(
+        "--require-existing-derived",
+        action="store_true",
+        help="导出前使用：增强派生图必须已真实落盘，否则不算客户图使用",
+    )
+    parser.add_argument("--design", default=None, help="design.json 路径（覆盖 --build 推断；供章节错位检查）")
+    parser.add_argument(
+        "--design-only",
+        action="store_true",
+        help="只跑【图片章节错位】检查（不需要 deck.html；WARNING 级恒 exit 0，供生图前预警）",
+    )
+    parser.add_argument(
+        "--layout-intent-only",
+        action="store_true",
+        help="只跑【版式违规】检查（contain 类客户图被当整页背景；ERROR 级 exit 1，供视觉门可修档驱动修复）",
+    )
+    args = parser.parse_args()
+
+    material_path = args.material or os.path.join(args.build, "material.json")
+    deck_path = args.deck or os.path.join(args.build, "deck.html")
+    design_path = args.design or os.path.join(args.build, "design.json")
+    plan_path = os.path.join(os.path.dirname(os.path.abspath(material_path)), "source_layout_plan.json")
+
+    if args.layout_intent_only:
+        errors, checked = layout_intent_violations(material_path, deck_path)
+        for e in errors:
+            print(e)
+        if errors:
+            print(f"LAYOUT_INTENT_FAILED: {len(errors)}/{checked} 张 contain 类客户图被违规用作整页背景")
+            return 1
+        print(f"LAYOUT_INTENT_OK: 核对 {checked} 张 contain 类客户图，无整页背景违规")
+        return 0
+
+    sec_warnings, sec_checked = section_mismatch_warnings(design_path, plan_path)
+    for w in sec_warnings:
+        print("WARNING: " + w)
+    if args.design_only:
+        print(
+            f"SECTION_MATCH_DONE: 核对 {sec_checked} 张章节锚定图，"
+            f"{len(sec_warnings)} 条错位提示（WARNING 级，不阻断）"
+        )
+        return 0
+
+    code, msg = check(material_path, deck_path, args.require_existing_derived)
+    print(msg)
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())