minimal-agent 0.8.2 → 0.10.0

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

@@ -0,0 +1,427 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+source_usage_check_test.py —— source_usage_check.py 单测。
+
+锁定：
+  - 全部客户图被 deck.html 引用 → code 0 / SOURCE_USAGE_OK。
+  - 有客户图未被引用 → code 1 / UNUSED 列出缺的。
+  - background-image:url() 引用也算「已用」。
+  - 无客户图 / 无 material.json → code 0（跳过）。
+  - deck.html 不存在 → code 2 / NO_DECK。
+依赖：标准库。
+"""
+
+import json
+import os
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import source_usage_check as su  # noqa: E402
+
+
+def _write(path, obj):
+    with open(path, "w", encoding="utf-8") as f:
+        if isinstance(obj, str):
+            f.write(obj)
+        else:
+            json.dump(obj, f, ensure_ascii=False)
+
+
+class TestUsageCheck(unittest.TestCase):
+    def setUp(self):
+        self.d = tempfile.mkdtemp(prefix="usage-")
+        self.material = os.path.join(self.d, "material.json")
+        self.deck = os.path.join(self.d, "deck.html")
+
+    def _material(self, files):
+        _write(self.material, {"has_source": True, "images": [{"file": f} for f in files]})
+
+    def _asset(self, name):
+        assets = os.path.join(self.d, "assets")
+        os.makedirs(assets, exist_ok=True)
+        path = os.path.join(assets, name)
+        with open(path, "wb") as f:
+            f.write(b"x")
+        return path
+
+    def _failure_report(self, *items):
+        _write(
+            os.path.join(self.d, "image_generation_report.json"),
+            {"degraded": [{"file": file, "source_file": source, "mode": "image-to-image"} for file, source in items]},
+        )
+
+    def test_all_used(self):
+        self._material(["src_1.png", "src_2.png"])
+        _write(
+            self.deck,
+            '<img src="assets/enhanced_src_1.png"><div style="background-image:url(assets/enhanced_src_2.png)"></div>',
+        )
+        code, msg = su.check(self.material, self.deck)
+        self.assertEqual(code, 0)
+        self.assertIn("SOURCE_USAGE_OK", msg)
+
+    def test_style_tag_srcset_and_query_are_real_usage(self):
+        self._material(["src_1.png", "src_2.png", "src_3.png"])
+        _write(
+            self.deck,
+            """
+            <style>.hero{background-image:url("./assets/enhanced_src_1.png?v=2")}</style>
+            <picture><source srcset="assets/enhanced_src_2.png 1x, assets/other.png 2x"></picture>
+            <svg><image href="assets/enhanced_src_3.png#crop"></image></svg>
+            """,
+        )
+        code, msg = su.check(self.material, self.deck)
+        self.assertEqual(code, 0)
+        self.assertIn("SOURCE_USAGE_OK", msg)
+
+    def test_enhanced_source_image_counts_as_original_usage(self):
+        _write(
+            self.material,
+            {
+                "has_source": True,
+                "images": [
+                    {"file": "src_1.png"},
+                    {"file": "src_2.png", "enhanced_file": "custom_enhanced_2.png"},
+                ],
+            },
+        )
+        self._asset("enhanced_src_1.png")
+        self._asset("custom_enhanced_2.png")
+        _write(
+            self.deck,
+            '<img src="assets/enhanced_src_1.png"><img src="assets/custom_enhanced_2.png">',
+        )
+        code, msg = su.check(self.material, self.deck)
+        self.assertEqual(code, 0)
+        self.assertIn("SOURCE_USAGE_OK", msg)
+
+    def test_planned_enhanced_file_counts_before_generation(self):
+        _write(
+            self.material,
+            {"has_source": True, "images": [{"file": "src_1.png", "enhanced_file": "enhanced_src_1.png"}]},
+        )
+        _write(self.deck, '<img src="assets/enhanced_src_1.png">')
+        code, msg = su.check(self.material, self.deck)
+        self.assertEqual(code, 0)
+        self.assertIn("SOURCE_USAGE_OK", msg)
+
+    def test_missing_enhanced_file_does_not_count_at_export_gate(self):
+        _write(
+            self.material,
+            {"has_source": True, "images": [{"file": "src_1.png", "enhanced_file": "enhanced_src_1.png"}]},
+        )
+        _write(self.deck, '<img src="assets/enhanced_src_1.png">')
+        code, msg = su.check(self.material, self.deck, require_existing_derived=True)
+        self.assertEqual(code, 1)
+        self.assertIn("UNUSED", msg)
+        self.assertIn("src_1.png", msg)
+
+    def test_low_resolution_original_image_cannot_be_background(self):
+        _write(
+            self.material,
+            {"has_source": True, "images": [{"file": "src_1.png", "w": 640, "h": 412}]},
+        )
+        _write(self.deck, '<section style="background-image:url(assets/src_1.png)"></section>')
+        code, msg = su.check(self.material, self.deck)
+        self.assertEqual(code, 1)
+        self.assertIn("LOW_RES_BACKGROUND", msg)
+
+    def test_low_resolution_original_image_can_be_inline_evidence(self):
+        _write(
+            self.material,
+            {"has_source": True, "images": [{"file": "src_1.png", "w": 640, "h": 412}]},
+        )
+        self._failure_report(("enhanced_src_1.png", "src_1.png"))
+        _write(self.deck, '<figure class="evidence"><img src="assets/src_1.png"></figure>')
+        code, msg = su.check(self.material, self.deck)
+        self.assertEqual(code, 0)
+        self.assertIn("SOURCE_USAGE_OK", msg)
+
+    def test_original_image_without_enhance_failure_is_rejected(self):
+        _write(
+            self.material,
+            {"has_source": True, "images": [{"file": "src_1.png", "w": 1600, "h": 900}]},
+        )
+        _write(self.deck, '<figure class="evidence"><img src="assets/src_1.png"></figure>')
+        code, msg = su.check(self.material, self.deck)
+        self.assertEqual(code, 1)
+        self.assertIn("SOURCE_DIRECT_WITHOUT_ENHANCE_FAILURE", msg)
+
+    def test_text_comment_and_script_mentions_do_not_count_as_usage(self):
+        self._material(["src_1.png", "src_2.png", "src_3.png"])
+        _write(
+            self.deck,
+            """
+            <p>素材 src_1.png 应该放在这里</p>
+            <!-- src_2.png TODO -->
+            <script>const asset = "src_3.png";</script>
+            """,
+        )
+        code, msg = su.check(self.material, self.deck)
+        self.assertEqual(code, 1)
+        self.assertIn("UNUSED", msg)
+        self.assertIn("src_1.png", msg)
+        self.assertIn("src_2.png", msg)
+        self.assertIn("src_3.png", msg)
+
+    def test_plain_anchor_href_does_not_count_but_image_preload_does(self):
+        self._material(["src_1.png", "src_2.png"])
+        _write(
+            self.deck,
+            """
+            <a href="assets/src_1.png">下载素材</a>
+            <link rel="preload" as="image" href="assets/enhanced_src_2.png">
+            """,
+        )
+        code, msg = su.check(self.material, self.deck)
+        self.assertEqual(code, 1)
+        self.assertIn("src_1.png", msg)
+        self.assertNotIn("src_2.png", msg)
+
+    def test_some_unused(self):
+        self._material(["src_1.png", "src_2.png", "src_3.png"])
+        _write(self.deck, '<img src="assets/enhanced_src_1.png">')
+        code, msg = su.check(self.material, self.deck)
+        self.assertEqual(code, 1)
+        self.assertIn("UNUSED", msg)
+        self.assertIn("src_2.png", msg)
+        self.assertIn("src_3.png", msg)
+        self.assertNotIn("src_1.png", msg)
+
+    def test_derived_extension_drift_still_counts_as_used(self):
+        # 2026-07-05 真机复盘：material.json 无 enhanced_file 字段时按「原扩展名」猜
+        # enhanced_src_2.jpg，但实际生图落盘是 .png；deck.html 用 .bg-img 引用 .png 版，
+        # 逐字符串比对对不上，误判 UNUSED 直接 hard halt（真机连续两次真实事故）。
+        self._material(["src_2.jpg"])
+        self._asset("enhanced_src_2.png")
+        _write(
+            self.deck,
+            '<img class="bg-img" src="assets/enhanced_src_2.png" data-source-file="src_2.jpg">',
+        )
+        code, msg = su.check(self.material, self.deck, require_existing_derived=True)
+        self.assertEqual(code, 0)
+        self.assertIn("SOURCE_USAGE_OK", msg)
+
+    def test_no_images(self):
+        self._material([])
+        _write(self.deck, "<html></html>")
+        code, msg = su.check(self.material, self.deck)
+        self.assertEqual(code, 0)
+        self.assertIn("无客户图", msg)
+
+    def test_no_material(self):
+        _write(self.deck, "<html></html>")
+        code, msg = su.check(os.path.join(self.d, "nope.json"), self.deck)
+        self.assertEqual(code, 0)
+
+    def test_no_deck(self):
+        self._material(["src_1.png"])
+        code, msg = su.check(self.material, os.path.join(self.d, "nope.html"))
+        self.assertEqual(code, 2)
+        self.assertIn("NO_DECK", msg)
+
+
+class TestDiscardExemption(unittest.TestCase):
+    """discard 豁免（2026-07-02 坠机图事故）：规划判弃用的图不再被「必须全部用上」硬塞进 deck。"""
+
+    def setUp(self):
+        self.d = tempfile.mkdtemp(prefix="usage-discard-")
+        self.material = os.path.join(self.d, "material.json")
+        self.deck = os.path.join(self.d, "deck.html")
+
+    def _plan(self, intents):
+        _write(os.path.join(self.d, "source_layout_plan.json"),
+               {"images": [{"file": f, "usage_intent": i} for f, i in intents.items()]})
+
+    def test_discarded_unused_is_ok(self):
+        _write(self.material, {"has_source": True,
+                               "images": [{"file": "src_1.jpg"}, {"file": "src_2.png"}]})
+        self._plan({"src_1.jpg": "discard", "src_2.png": "source_enhanced_bg"})
+        _write(self.deck, "<img src='assets/enhanced_src_2.png'>")
+        code, msg = su.check(self.material, self.deck)
+        self.assertEqual(code, 0, msg)
+        self.assertIn("豁免", msg)
+
+    def test_non_discarded_unused_still_fails(self):
+        _write(self.material, {"has_source": True,
+                               "images": [{"file": "src_1.jpg"}, {"file": "src_2.png"}]})
+        self._plan({"src_1.jpg": "discard", "src_2.png": "source_enhanced_bg"})
+        _write(self.deck, "<p>无图</p>")
+        code, msg = su.check(self.material, self.deck)
+        self.assertEqual(code, 1, msg)
+        self.assertIn("src_2.png", msg)
+        self.assertNotIn("src_1.jpg", msg)
+
+    def test_no_plan_file_behavior_unchanged(self):
+        # 无 source_layout_plan.json（旧产物/webppt 场景）→ 行为与改前一致：全要求用上。
+        _write(self.material, {"has_source": True, "images": [{"file": "src_1.jpg"}]})
+        _write(self.deck, "<p>无图</p>")
+        code, msg = su.check(self.material, self.deck)
+        self.assertEqual(code, 1, msg)
+        self.assertIn("src_1.jpg", msg)
+
+
+class TestSectionMismatch(unittest.TestCase):
+    """【图片章节错位】（2026-07-02 张冠李戴裁决，WARNING 级）：客户图来自原文特定章节，
+    却被设计步配到词元零交集的页。模糊判定只提示不阻断；防错主力在设计 prompt 章节锚定。"""
+
+    def setUp(self):
+        self.d = tempfile.mkdtemp(prefix="usage-section-")
+        self.design = os.path.join(self.d, "design.json")
+        self.plan = os.path.join(self.d, "source_layout_plan.json")
+
+    def _write_plan(self, images):
+        _write(self.plan, {"images": images})
+
+    def _write_design(self, pages):
+        _write(self.design, {"pages": pages})
+
+    def _page(self, page, title, key_point="", src=None, takeaway=""):
+        p = {"page": page, "title": title, "key_point": key_point,
+             "one_sentence_takeaway": takeaway}
+        if src:
+            p["visual"] = {"route": "source-enhanced", "source_file": src}
+        return p
+
+    def test_mismatch_reports_warning(self):
+        self._write_plan([{"file": "src_1.jpg", "usage_intent": "source_enhanced_hero",
+                           "section": "三、现场作业场景", "near_text": "巡检人员在高空平台开展检修作业"}])
+        self._write_design([self._page(5, "成本效益分析", "投入产出比测算", src="src_1.jpg")])
+        warnings, checked = su.section_mismatch_warnings(self.design, self.plan)
+        self.assertEqual(checked, 1)
+        self.assertEqual(len(warnings), 1, warnings)
+        self.assertIn("【图片章节错位】页 5", warnings[0])
+        self.assertIn("src_1.jpg", warnings[0])
+        self.assertIn("三、现场作业场景", warnings[0])
+
+    def test_section_token_match_passes(self):
+        # 章节「系统平台建设」与页题「平台总体架构」共享 bigram「平台」→ 视为锚定成立。
+        self._write_plan([{"file": "src_1.jpg", "usage_intent": "source_enhanced_hero",
+                           "section": "二、系统平台建设"}])
+        self._write_design([self._page(3, "平台总体架构", src="src_1.jpg")])
+        warnings, checked = su.section_mismatch_warnings(self.design, self.plan)
+        self.assertEqual((checked, warnings), (1, []))
+
+    def test_near_text_match_passes(self):
+        # 章节词不合、但邻近文案与页 key_point 有交集 → 也算锚定成立（near_text 扩大匹配面）。
+        self._write_plan([{"file": "src_1.jpg", "usage_intent": "direct_contain",
+                           "section": "五、附录", "near_text": "巡检效率提升与人力成本对比数据"}])
+        self._write_design([self._page(5, "成本效益", "巡检效率提升三倍", src="src_1.jpg")])
+        warnings, _ = su.section_mismatch_warnings(self.design, self.plan)
+        self.assertEqual(warnings, [])
+
+    def test_background_and_discard_exempt(self):
+        self._write_plan([
+            {"file": "src_1.jpg", "usage_intent": "source_enhanced_bg", "section": "三、现场作业场景"},
+            {"file": "src_2.jpg", "usage_intent": "discard", "section": "三、现场作业场景"},
+        ])
+        self._write_design([self._page(5, "成本效益分析", src="src_1.jpg"),
+                            self._page(6, "总结展望", src="src_2.jpg")])
+        warnings, checked = su.section_mismatch_warnings(self.design, self.plan)
+        self.assertEqual((checked, warnings), (0, []))
+
+    def test_meaningless_section_skipped(self):
+        # 页号型（pdf/pptx 锚）与文件名型（独立散图）section 无锚定意义 → 跳过不查。
+        self._write_plan([
+            {"file": "src_1.jpg", "usage_intent": "source_enhanced_hero", "section": "page 3"},
+            {"file": "src_2.jpg", "usage_intent": "source_enhanced_hero", "section": "第3页"},
+            {"file": "src_3.jpg", "usage_intent": "source_enhanced_hero", "section": "src_3"},
+        ])
+        self._write_design([self._page(2, "成本效益", src="src_1.jpg"),
+                            self._page(3, "范式变化", src="src_2.jpg"),
+                            self._page(4, "总结展望", src="src_3.jpg")])
+        warnings, checked = su.section_mismatch_warnings(self.design, self.plan)
+        self.assertEqual((checked, warnings), (0, []))
+
+    def test_missing_files_silent(self):
+        warnings, checked = su.section_mismatch_warnings(
+            os.path.join(self.d, "nope.json"), os.path.join(self.d, "nope2.json"))
+        self.assertEqual((checked, warnings), (0, []))
+
+
+class TestLayoutIntentViolations(unittest.TestCase):
+    """【版式违规】（2026-07-03 真机第4页事故，ERROR 级可修档）：规划为 contain 类
+    （direct_contain/gallery/small_evidence）的客户图被 build 违规用作整页背景
+    （<img class="bg-img"> 或 CSS background url()）。豁免 source_enhanced_bg/hero/discard。"""
+
+    def setUp(self):
+        self.d = tempfile.mkdtemp(prefix="usage-intent-")
+        self.material = os.path.join(self.d, "material.json")
+        self.deck = os.path.join(self.d, "deck.html")
+
+    def _setup(self, intents, deck_html):
+        _write(self.material, {"has_source": True,
+                               "images": [{"file": f} for f in intents]})
+        _write(os.path.join(self.d, "source_layout_plan.json"),
+               {"images": [{"file": f, "usage_intent": i} for f, i in intents.items()]})
+        _write(self.deck, deck_html)
+
+    def test_contain_image_as_bg_img_reports_error_with_page(self):
+        # 真机第4页原型：enhanced 派生图铺成 .bg-img，data-source-file 扩展名漂移（.jpg vs .png）。
+        self._setup(
+            {"src_6.png": "direct_contain"},
+            '<section class="slide"><p>p1</p></section>'
+            '<section class="slide"><img class="bg-img" src="assets/enhanced_src_6.png"'
+            ' data-source-file="src_6.jpg"></section>',
+        )
+        errors, checked = su.layout_intent_violations(self.material, self.deck)
+        self.assertEqual(checked, 1)
+        self.assertEqual(len(errors), 1, errors)
+        self.assertIn("【版式违规】页 2", errors[0])
+        self.assertIn("src_6.png", errors[0])
+        self.assertIn("direct_contain", errors[0])
+
+    def test_contain_image_as_css_background_reports_error(self):
+        self._setup(
+            {"src_1.png": "gallery"},
+            '<section class="slide" style="background-image:url(assets/enhanced_src_1.png)"></section>',
+        )
+        errors, checked = su.layout_intent_violations(self.material, self.deck)
+        self.assertEqual(checked, 1)
+        self.assertEqual(len(errors), 1, errors)
+        self.assertIn("src_1.png", errors[0])
+
+    def test_contain_image_in_contain_slot_passes(self):
+        self._setup(
+            {"src_1.png": "direct_contain"},
+            '<section class="slide"><figure><img src="assets/enhanced_src_1.png"></figure></section>',
+        )
+        errors, checked = su.layout_intent_violations(self.material, self.deck)
+        self.assertEqual((checked, errors), (1, []))
+
+    def test_enhanced_bg_and_hero_intents_exempt(self):
+        self._setup(
+            {"src_1.png": "source_enhanced_bg", "src_2.png": "source_enhanced_hero"},
+            '<img class="bg-img" src="assets/enhanced_src_1.png">'
+            '<img class="bg-img" src="assets/enhanced_src_2.png">',
+        )
+        errors, checked = su.layout_intent_violations(self.material, self.deck)
+        self.assertEqual((checked, errors), (0, []))
+
+    def test_unrelated_bg_img_does_not_flag_contain_image(self):
+        # AI 生成背景（ai_p3.png）与 contain 客户图无关 → 不误报。
+        self._setup(
+            {"src_1.png": "small_evidence"},
+            '<section class="slide"><img class="bg-img" src="assets/ai_p3.png">'
+            '<img src="assets/enhanced_src_1.png"></section>',
+        )
+        errors, checked = su.layout_intent_violations(self.material, self.deck)
+        self.assertEqual((checked, errors), (1, []))
+
+    def test_missing_plan_or_material_silent(self):
+        _write(self.material, {"has_source": True, "images": [{"file": "src_1.png"}]})
+        _write(self.deck, '<img class="bg-img" src="assets/enhanced_src_1.png">')
+        # 无 source_layout_plan.json → 不添乱（webppt/旧产物场景）。
+        errors, checked = su.layout_intent_violations(self.material, self.deck)
+        self.assertEqual((checked, errors), (0, []))
+        # 无 material.json → 同样静默。
+        errors, checked = su.layout_intent_violations(
+            os.path.join(self.d, "nope.json"), self.deck)
+        self.assertEqual((checked, errors), (0, []))
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)