minimal-agent 0.8.2 → 0.10.0

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

@@ -0,0 +1,1136 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+plan_source_layout_test.py —— plan_source_layout.py 单测。
+
+锁定确定性判定（治「客户图被用烂」根因的核心逻辑）：
+  - ① 全图生图政策：**所有客户图（除无 vision 盲态）一律 enhance_required=true**，不再直接用原图。
+      合格+背景图 → source_enhanced_bg（16:9）；合格+非背景 → source_enhanced_hero（按朝向定比例）；低清/坏比例同理。
+      信息密集图（截图/图表）→ direct_contain，**照样 img2img 但走忠实保真提示词**（dense，best-effort 有重绘风险）。
+      无识图（无多模态）盲态 = 唯一保守例外（low_res→small_evidence，enhance=false）。
+  - ② _background_kind 识图分流：real_scene / flat_base / unknown，联动 enhance_style（real_scene→hero / flat_base+离散主体→cutout）。
+  - ③ 三态提示词（bg/hero/cutout）统一含高清质量词（high resolution / sharp / clean lighting…）。
+  - 文字深浅按 stats.brightness 定（亮底深墨字 / 暗底白字）。
+  - ensure-img-plan：把图生图条目 union 进 img_plan.json，按 file 去重不重复注入。
+  - 无客户图 → 空规划、enhance_count=0。
+依赖：标准库 + 同目录 source_usage_check。
+"""
+
+import json
+import os
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import plan_source_layout as psl  # noqa: E402
+
+
+def _img(file, w, h, *, orient=None, vision=None, stats=None, section=None, aspect_ratio=None,
+         near_text=None, origin=None):
+    d = {"file": file, "w": w, "h": h}
+    if orient:
+        d["orient"] = orient
+    if aspect_ratio is not None:
+        d["aspect_ratio"] = aspect_ratio
+    elif h:
+        d["aspect_ratio"] = round(w / h, 3)
+    if vision is not None:
+        d["vision"] = vision
+    if stats is not None:
+        d["stats"] = stats
+    if section:
+        d["section"] = section
+    if near_text:
+        d["near_text"] = near_text
+    if origin:
+        d["origin"] = origin
+    return d
+
+
+def _vision(desc="一台工业相机产品照", *, bg=False, zone=None, elements=None,
+            content_type=None, embedded_text=None):
+    v = {"description": desc, "suitable_as_background": bg}
+    if zone:
+        v["recommended_text_zone"] = zone
+    if elements:
+        v["key_elements"] = elements
+    if content_type is not None:
+        v["content_type"] = content_type
+    if embedded_text is not None:
+        v["embedded_text"] = embedded_text
+    return v
+
+
+class TestPlanOne(unittest.TestCase):
+    def test_low_res_background_suitable_needs_img2img_bg(self):
+        e = psl.plan_one(_img("src_1.png", 800, 450, vision=_vision("开阔的山景风光照", bg=True)))
+        self.assertEqual(e["quality"], "low_res")
+        self.assertEqual(e["usage_intent"], "source_enhanced_bg")
+        self.assertEqual(e["image_role"], "background")
+        self.assertEqual(e["target_layer"], "background")
+        self.assertEqual(e["text_policy"], "avoid_new_text")
+        self.assertTrue(e["enhance_required"])
+        self.assertEqual(e["enhance_target_aspect"], "16:9")
+        self.assertEqual(e["enhanced_file"], "enhanced_src_1.png")
+        self.assertIn("no text", e["enhance_prompt"])
+        self.assertIn("16:9", e["enhance_prompt"])
+        # 用户原话三要素：保留原图内容 + 高清重绘 + 缺失区域智能补全(outpaint)
+        self.assertIn("preserve", e["enhance_prompt"])
+        self.assertIn("high resolution", e["enhance_prompt"])
+        self.assertIn("outpaint", e["enhance_prompt"])
+        self.assertIn("背景主导", e["recommended_templates"])
+
+    def test_low_res_portrait_product_needs_img2img_hero_4x5(self):
+        e = psl.plan_one(_img("src_2.png", 600, 900, vision=_vision("竖拍的手持设备产品照", bg=False)))
+        self.assertEqual(e["usage_intent"], "source_enhanced_hero")
+        self.assertTrue(e["enhance_required"])
+        self.assertEqual(e["enhance_target_aspect"], "4:5")
+        self.assertEqual(e["orient"], "portrait")
+        self.assertIn("左右产品剧场", e["recommended_templates"])
+
+    def test_high_res_background_suitable_now_img2img(self):
+        # ① 全图生图：高清合格背景图也不再直接铺，改图生图重绘成高清干净全幅背景。
+        e = psl.plan_one(_img("src_3.png", 1920, 1080, vision=_vision("辽阔的数据中心机房", bg=True)))
+        self.assertEqual(e["quality"], "ok")
+        self.assertEqual(e["usage_intent"], "source_enhanced_bg")
+        self.assertTrue(e["enhance_required"])
+        self.assertEqual(e["enhance_style"], "bg")
+        self.assertEqual(e["enhance_target_aspect"], "16:9")
+        self.assertEqual(e["enhanced_file"], "enhanced_src_3.png")
+        self.assertIn("enhance_prompt", e)
+
+    def test_dense_info_screenshot_img2img_faithful(self):
+        # 用户明确要求：dense（截图/图表）照样 img2img，但走「忠实保留版面/数据」提示词（best-effort，有重绘风险）。
+        e = psl.plan_one(
+            _img("src_4.png", 700, 480, vision=_vision("产品后台仪表盘界面截图", bg=False, elements=["图表", "表格"]))
+        )
+        self.assertTrue(e["is_dense_info"])
+        self.assertEqual(e["usage_intent"], "direct_contain")
+        self.assertTrue(e["enhance_required"])
+        self.assertEqual(e["enhance_style"], "dense")
+        self.assertEqual(e["image_role"], "faithful_document")
+        self.assertEqual(e["text_policy"], "preserve_data_text")
+        self.assertEqual(e["target_layer"], "evidence")
+        self.assertEqual(e["enhanced_file"], "enhanced_src_4.png")
+        self.assertIn("图像证据卡", e["recommended_templates"])
+        p = e["enhance_prompt"].lower()
+        self.assertIn("layout", p)           # 忠实保留版面
+        self.assertIn("high resolution", p)  # 高清质量词
+        self.assertNotIn("no text", p)       # dense 含合法数据标签/文字，绝不去字
+
+    def test_no_vision_blind_conservative(self):
+        e = psl.plan_one(_img("src_5.png", 700, 500))  # 无 vision
+        self.assertFalse(e["has_vision"])
+        self.assertFalse(e["enhance_required"])  # 唯一保守例外：盲态不冒险图生图
+        self.assertEqual(e["usage_intent"], "small_evidence")
+
+    def test_ok_photo_non_background_now_img2img_hero(self):
+        # ① 全图生图：高清合格非背景图也不再直接 contain，改图生图重绘成高清主视觉。
+        e = psl.plan_one(_img("src_6.png", 1600, 1200, vision=_vision("一块精密电路板特写", bg=False)))
+        self.assertEqual(e["quality"], "ok")
+        self.assertEqual(e["usage_intent"], "source_enhanced_hero")
+        self.assertTrue(e["enhance_required"])
+        self.assertEqual(e["target_layer"], "foreground")
+        self.assertIn("enhance_prompt", e)
+
+    def test_flat_base_discrete_subject_cutout_metadata(self):
+        e = psl.plan_one(
+            _img(
+                "src_cut.png",
+                1200,
+                900,
+                vision=_vision("白底上的独立设备产品特写", bg=False, elements=["设备", "白底"]),
+            )
+        )
+        self.assertEqual(e["enhance_style"], "cutout")
+        self.assertEqual(e["image_role"], "foreground_cutout")
+        self.assertEqual(e["target_layer"], "foreground")
+        self.assertIn("transparent", e["enhance_prompt"].lower())
+
+    def test_text_color_from_brightness(self):
+        bright = psl.plan_one(
+            _img("src_7.png", 1920, 1080, vision=_vision("明亮的白色产品照", bg=True), stats={"brightness": {"mean": 210}})
+        )
+        dark = psl.plan_one(
+            _img("src_8.png", 1920, 1080, vision=_vision("夜景城市天际线", bg=True), stats={"brightness": {"mean": 40}})
+        )
+        self.assertEqual(bright["text_color"], "dark")
+        self.assertEqual(dark["text_color"], "light")
+
+    def test_text_zone_from_vision(self):
+        e = psl.plan_one(_img("src_9.png", 800, 600, vision=_vision("产品图", bg=True, zone="left")))
+        self.assertEqual(e["text_zone"], "left")
+
+
+class TestDisplayPolicy(unittest.TestCase):
+    """显示档位 + 尺寸下限 + 缩放上限（治「客户图缩成角落小图看不清 / 低清原图放大糊」）。"""
+
+    def test_background_role_full_canvas(self):
+        e = psl.plan_one(_img("b.png", 1920, 1080, vision=_vision("辽阔机房", bg=True)))
+        self.assertEqual(e["display_role"], "background")
+        self.assertEqual(e["min_canvas_fraction"], 1.0)
+        self.assertEqual(e["max_upscale"], 1.0)
+
+    def test_hero_role_min_30pct(self):
+        # 高清非背景照 → 现在 source_enhanced_hero → foreground_hero，槽位至少占画布 30%
+        e = psl.plan_one(_img("h.png", 1600, 1200, vision=_vision("电路板特写", bg=False)))
+        self.assertEqual(e["usage_intent"], "source_enhanced_hero")
+        self.assertEqual(e["display_role"], "foreground_hero")
+        self.assertGreaterEqual(e["min_canvas_fraction"], 0.30)
+
+    def test_enhanced_hero_is_foreground_hero(self):
+        e = psl.plan_one(_img("p.png", 600, 900, vision=_vision("竖拍设备照", bg=False)))
+        self.assertEqual(e["usage_intent"], "source_enhanced_hero")
+        self.assertEqual(e["display_role"], "foreground_hero")
+
+    def test_small_evidence_still_readable_min(self):
+        # 低清无识图 → small_evidence → evidence_card，但仍须 ≥12% 画布（非角落缩略图）
+        e = psl.plan_one(_img("s.png", 700, 500))
+        self.assertEqual(e["usage_intent"], "small_evidence")
+        self.assertEqual(e["display_role"], "evidence_card")
+        self.assertGreaterEqual(e["min_canvas_fraction"], 0.12)
+
+    def test_max_upscale_always_one(self):
+        for img in (
+            _img("a.png", 1920, 1080, vision=_vision("机房", bg=True)),
+            _img("b.png", 600, 900, vision=_vision("竖拍设备", bg=False)),
+            _img("c.png", 700, 500),
+            _img("d.png", 700, 480, vision=_vision("仪表盘截图", bg=False, elements=["图表"])),
+        ):
+            self.assertEqual(psl.plan_one(img)["max_upscale"], 1.0)
+
+    def test_gallery_role_via_build(self):
+        d = tempfile.mkdtemp(prefix="srclayout-role-")
+        with open(os.path.join(d, "material.json"), "w", encoding="utf-8") as f:
+            json.dump(
+                {
+                    "has_source": True,
+                    "images": [
+                        _img(f"g{i}.png", 1500, 1000, vision=_vision(f"现场{i}", bg=False), section="案例")
+                        for i in range(3)
+                    ],
+                },
+                f,
+                ensure_ascii=False,
+            )
+        plan = psl.build_plan(d)
+        self.assertTrue(all(e["display_role"] == "gallery" for e in plan["images"]))
+        self.assertTrue(all(e["min_canvas_fraction"] == 0.10 for e in plan["images"]))
+
+
+class TestLayoutConstraint(unittest.TestCase):
+    """版式硬约束 layout_constraint（设计步照读、不自行决定 render；治「有底图还套表格/卡墙划区」）。"""
+
+    def test_high_res_bg_is_fusion_no_cards(self):
+        # 全图生图后高清背景图 → source_enhanced_bg，版式仍是编辑式融合（禁卡墙）。
+        e = psl.plan_one(_img("b.png", 1920, 1080, vision=_vision("辽阔机房", bg=True)))
+        self.assertEqual(e["usage_intent"], "source_enhanced_bg")
+        self.assertEqual(e["layout_constraint"], "fusion_no_cards")
+
+    def test_enhanced_bg_is_fusion_no_cards(self):
+        e = psl.plan_one(_img("eb.png", 800, 450, vision=_vision("山景", bg=True)))
+        self.assertEqual(e["usage_intent"], "source_enhanced_bg")
+        self.assertEqual(e["layout_constraint"], "fusion_no_cards")
+
+    def test_enhanced_hero_is_fusion_no_cards(self):
+        e = psl.plan_one(_img("eh.png", 600, 900, vision=_vision("竖拍设备照", bg=False)))
+        self.assertEqual(e["usage_intent"], "source_enhanced_hero")
+        self.assertEqual(e["layout_constraint"], "fusion_no_cards")
+
+    def test_direct_contain_is_image_text_mixed(self):
+        # direct_contain 现在由「无 vision 合格图」产出（不增强）→ image_text_mixed。
+        e = psl.plan_one(_img("dc.png", 1600, 1200))  # 无 vision、合格
+        self.assertEqual(e["usage_intent"], "direct_contain")
+        self.assertFalse(e["enhance_required"])
+        self.assertEqual(e["layout_constraint"], "image_text_mixed")
+
+    def test_small_evidence_is_evidence_ok(self):
+        e = psl.plan_one(_img("se.png", 700, 500))  # 低清无识图
+        self.assertEqual(e["usage_intent"], "small_evidence")
+        self.assertEqual(e["layout_constraint"], "evidence_ok")
+
+    def test_dense_info_is_image_text_mixed(self):
+        # 信息密集图 direct_contain → image_text_mixed（不背景化、不堆卡墙于图上）
+        e = psl.plan_one(
+            _img("d.png", 700, 480, vision=_vision("仪表盘截图", bg=False, elements=["图表", "表格"]))
+        )
+        self.assertEqual(e["usage_intent"], "direct_contain")
+        self.assertEqual(e["layout_constraint"], "image_text_mixed")
+
+    def test_gallery_constraint_via_build(self):
+        d = tempfile.mkdtemp(prefix="srclayout-lc-")
+        with open(os.path.join(d, "material.json"), "w", encoding="utf-8") as f:
+            json.dump(
+                {
+                    "has_source": True,
+                    "images": [
+                        _img(f"g{i}.png", 1500, 1000, vision=_vision(f"现场{i}", bg=False), section="案例")
+                        for i in range(3)
+                    ],
+                },
+                f,
+                ensure_ascii=False,
+            )
+        plan = psl.build_plan(d)
+        self.assertTrue(all(e["usage_intent"] == "gallery" for e in plan["images"]))
+        self.assertTrue(all(e["layout_constraint"] == "evidence_ok" for e in plan["images"]))
+
+
+class TestBuildAndEnsure(unittest.TestCase):
+    def setUp(self):
+        self.d = tempfile.mkdtemp(prefix="srclayout-")
+
+    def _material(self, images):
+        with open(os.path.join(self.d, "material.json"), "w", encoding="utf-8") as f:
+            json.dump({"has_source": True, "images": images}, f, ensure_ascii=False)
+
+    def test_build_plan_counts_and_files(self):
+        self._material(
+            [
+                _img("src_1.png", 800, 450, vision=_vision("山景", bg=True)),  # 低清 bg → enhance
+                _img("src_2.png", 1920, 1080, vision=_vision("机房", bg=True)),  # ① 高清 bg 现也 enhance
+            ]
+        )
+        plan = psl.build_plan(self.d)
+        self.assertEqual(plan["image_count"], 2)
+        self.assertEqual(plan["enhance_count"], 2)  # ① 全图生图：两张背景图都需重绘
+        self.assertEqual(plan["enhance_entries"][0]["mode"], "image-to-image")
+        self.assertEqual(plan["enhance_entries"][0]["source_file"], "src_1.png")
+        self.assertEqual(plan["enhance_entries"][0]["file"], "enhanced_src_1.png")
+        # 落盘 md/json
+        psl.write_plan_md(self.d, plan)
+        with open(os.path.join(self.d, "source_layout_plan.json"), "w", encoding="utf-8") as f:
+            json.dump(plan, f, ensure_ascii=False)
+        self.assertTrue(os.path.isfile(os.path.join(self.d, "source_layout_plan.md")))
+
+    def test_no_images_empty_plan(self):
+        self._material([])
+        plan = psl.build_plan(self.d)
+        self.assertEqual(plan["image_count"], 0)
+        self.assertEqual(plan["enhance_count"], 0)
+        self.assertEqual(plan["enhance_entries"], [])
+
+    def test_ensure_img_plan_injects_and_dedups(self):
+        self._material([_img("src_1.png", 800, 450, vision=_vision("山景", bg=True))])
+        plan = psl.build_plan(self.d)
+        with open(os.path.join(self.d, "source_layout_plan.json"), "w", encoding="utf-8") as f:
+            json.dump(plan, f, ensure_ascii=False)
+        # 预置一个纯文生图条目，注入不应覆盖它，且图生图条目应被加入。
+        with open(os.path.join(self.d, "img_plan.json"), "w", encoding="utf-8") as f:
+            json.dump([{"file": "img_1.png", "mode": "text-to-image", "prompt": "a mountain, no text"}], f)
+        rc = psl.ensure_img_plan(self.d)
+        self.assertEqual(rc, 0)
+        with open(os.path.join(self.d, "img_plan.json"), encoding="utf-8") as f:
+            ip = json.load(f)
+        files = [e["file"] for e in ip]
+        self.assertIn("img_1.png", files)
+        self.assertIn("enhanced_src_1.png", files)
+        self.assertEqual(len(ip), 2)
+        # 再次注入应幂等（不重复）。
+        psl.ensure_img_plan(self.d)
+        with open(os.path.join(self.d, "img_plan.json"), encoding="utf-8") as f:
+            ip2 = json.load(f)
+        self.assertEqual(len(ip2), 2)
+
+    def test_gallery_grouping_same_section(self):
+        self._material(
+            [
+                _img("src_1.png", 1500, 1000, vision=_vision("现场照A", bg=False), section="案例展示"),
+                _img("src_2.png", 1500, 1000, vision=_vision("现场照B", bg=False), section="案例展示"),
+                _img("src_3.png", 1500, 1000, vision=_vision("现场照C", bg=False), section="案例展示"),
+            ]
+        )
+        plan = psl.build_plan(self.d)
+        self.assertTrue(all(e["usage_intent"] == "gallery" for e in plan["images"]))
+        self.assertTrue(all("四宫格画廊" in e["recommended_templates"] for e in plan["images"]))
+        # 画廊每格照样图生图增强到高清（gallery 不再豁免）。
+        self.assertTrue(all(e["enhance_required"] for e in plan["images"]))
+        self.assertEqual(plan["enhance_count"], 3)
+
+
+class TestSectionPassthrough(unittest.TestCase):
+    """章节锚定透传（2026-07-02 张冠李戴裁决）：extract 采集的 section/near_text/origin 此前在
+    plan entry 被丢弃 → 设计步只能按识图语义配页。现原样透传 + plan.md 渲染配页锚点。"""
+
+    def test_entry_carries_section_near_text_origin(self):
+        e = psl.plan_one(_img("src_1.png", 1500, 1000, vision=_vision("高空作业平台"),
+                              section="三、现场作业场景", near_text="巡检人员在高空平台开展检修作业",
+                              origin="doc.docx#三、现场作业场景"))
+        self.assertEqual(e["section"], "三、现场作业场景")
+        self.assertEqual(e["near_text"], "巡检人员在高空平台开展检修作业")
+        self.assertEqual(e["origin"], "doc.docx#三、现场作业场景")
+
+    def test_near_text_truncated_to_120(self):
+        e = psl.plan_one(_img("src_1.png", 1500, 1000, near_text="巡检" * 100))
+        self.assertEqual(len(e["near_text"]), 120)
+
+    def test_absent_fields_stay_absent(self):
+        e = psl.plan_one(_img("src_1.png", 1500, 1000))
+        self.assertNotIn("section", e)
+        self.assertNotIn("near_text", e)
+        self.assertNotIn("origin", e)
+
+    def test_plan_md_renders_section_anchor(self):
+        d = tempfile.mkdtemp(prefix="srclayout-sec-")
+        with open(os.path.join(d, "material.json"), "w", encoding="utf-8") as f:
+            json.dump({"has_source": True, "images": [
+                _img("src_1.png", 1500, 1000, vision=_vision("现场照"),
+                     section="三、现场作业场景", near_text="巡检人员在高空平台开展检修作业")]},
+                f, ensure_ascii=False)
+        plan = psl.build_plan(d)
+        psl.write_plan_md(d, plan)
+        with open(os.path.join(d, "source_layout_plan.md"), encoding="utf-8") as f:
+            md = f.read()
+        self.assertIn("来源章节：**三、现场作业场景**", md)
+        self.assertIn("配页锚点", md)
+        self.assertIn("巡检人员在高空平台开展检修作业", md)
+
+    def test_key_message_passthrough_and_rendered(self):
+        vision = _vision("巡检效率对比图")
+        vision["content_type"] = "chart"
+        vision["key_message"] = "巡检效率提升三倍"
+        e = psl.plan_one(_img("src_1.png", 1500, 1000, vision=vision))
+        self.assertEqual(e["key_message"], "巡检效率提升三倍")
+
+        d = tempfile.mkdtemp(prefix="srclayout-km-")
+        with open(os.path.join(d, "material.json"), "w", encoding="utf-8") as f:
+            json.dump({"has_source": True, "images": [_img("src_1.png", 1500, 1000, vision=vision)]},
+                      f, ensure_ascii=False)
+        plan = psl.build_plan(d)
+        psl.write_plan_md(d, plan)
+        with open(os.path.join(d, "source_layout_plan.md"), encoding="utf-8") as f:
+            md = f.read()
+        self.assertIn("巡检效率提升三倍", md)
+        self.assertIn("key_point/evidence 须呼应", md)
+
+    def test_no_key_message_field_absent(self):
+        e = psl.plan_one(_img("src_1.png", 1500, 1000, vision=_vision("普通照片")))
+        self.assertNotIn("key_message", e)
+
+
+class TestEnsureAiImgPlan(unittest.TestCase):
+    """--ensure-ai-img-plan：把 design.json 的 ai-A/ai-B 页文生图条目确定性 union 进 img_plan
+    （约定名 ai_p<page>.png），不靠设计 LLM 记得写、按 file 去重幂等。治真机「AI 背景从未进 img_plan」事故。"""
+
+    def setUp(self):
+        self.d = tempfile.mkdtemp(prefix="srclayout-ai-")
+
+    def _design(self, pages):
+        with open(os.path.join(self.d, "design.json"), "w", encoding="utf-8") as f:
+            json.dump({"pages": pages}, f, ensure_ascii=False)
+
+    def test_injects_ai_pages_with_convention_names(self):
+        self._design(
+            [
+                {"page": 1, "visual": {"route": "source-enhanced", "source_file": "src_1.png"}},
+                {"page": 2, "visual": {"route": "ai-B", "aspect": "16:9", "prompt": "a calm blue industrial backdrop, no text"}},
+                {"page": 3, "visual": {"route": "html"}},
+                {"page": 4, "visual": {"route": "ai-A", "side": "right", "aspect": "4:5", "prompt": "an engineer in a hangar, no text"}},
+                {"page": 5, "visual": {"route": "ai-B", "aspect": "16:9"}},  # 无 prompt → 跳过
+            ]
+        )
+        # 预置一个客户图增强条目，注入不应覆盖它。
+        with open(os.path.join(self.d, "img_plan.json"), "w", encoding="utf-8") as f:
+            json.dump(
+                [{"file": "enhanced_src_1.png", "mode": "image-to-image", "source_file": "src_1.png", "prompt": "x"}], f
+            )
+        rc = psl.ensure_ai_img_plan(self.d)
+        self.assertEqual(rc, 0)
+        with open(os.path.join(self.d, "img_plan.json"), encoding="utf-8") as f:
+            ip = json.load(f)
+        by_file = {e["file"]: e for e in ip}
+        # ai-B p2 是整页背景 ai_p<page>.png；ai-A p4 是前景插图 ai_p<page>_fg.png。
+        self.assertIn("ai_p2.png", by_file)
+        self.assertIn("ai_p4_fg.png", by_file)
+        self.assertEqual(by_file["ai_p2.png"]["mode"], "text-to-image")
+        self.assertEqual(by_file["ai_p2.png"]["aspect"], "16:9")
+        self.assertEqual(by_file["ai_p4_fg.png"]["aspect"], "4:5")
+        self.assertEqual(by_file["ai_p4_fg.png"]["target_layer"], "foreground")
+        # html 页不生 AI 图；无 prompt 的 ai-B（p5）跳过；客户图增强条目保留。
+        self.assertNotIn("ai_p3.png", by_file)
+        self.assertNotIn("ai_p4.png", by_file)
+        self.assertNotIn("ai_p5.png", by_file)
+        self.assertIn("enhanced_src_1.png", by_file)
+        self.assertEqual(len(ip), 3)
+        # 幂等：再次注入不重复。
+        psl.ensure_ai_img_plan(self.d)
+        with open(os.path.join(self.d, "img_plan.json"), encoding="utf-8") as f:
+            ip2 = json.load(f)
+        self.assertEqual(len(ip2), 3)
+
+    def test_no_design_no_crash(self):
+        # 无 design.json → 跳过、不崩、不建 img_plan。
+        rc = psl.ensure_ai_img_plan(self.d)
+        self.assertEqual(rc, 0)
+
+    def test_creates_img_plan_when_absent(self):
+        # 纯 topic deck（无客户图、img_plan 还不存在）：ai-* 仍被注入、img_plan 被创建。
+        self._design([{"page": 1, "visual": {"route": "ai-B", "aspect": "16:9", "prompt": "atmosphere, no text"}}])
+        psl.ensure_ai_img_plan(self.d)
+        with open(os.path.join(self.d, "img_plan.json"), encoding="utf-8") as f:
+            ip = json.load(f)
+        self.assertEqual([e["file"] for e in ip], ["ai_p1.png"])
+
+
+class TestEnsurePageBackgrounds(unittest.TestCase):
+    """--ensure-page-backgrounds：为【无背景图的内容页】确定性补一条 VI 氛围文生图底图条目
+    （约定名 ai_p<page>.png），治真机「约一半内容页 route:none/html 无底图→退化白底卡片墙」。
+    在 --ensure-ai-img-plan 之后跑、按 file 去重幂等。"""
+
+    def setUp(self):
+        self.d = tempfile.mkdtemp(prefix="srclayout-pgbg-")
+
+    def _design(self, pages):
+        with open(os.path.join(self.d, "design.json"), "w", encoding="utf-8") as f:
+            json.dump({"pages": pages}, f, ensure_ascii=False)
+
+    def _img_plan(self, entries):
+        with open(os.path.join(self.d, "img_plan.json"), "w", encoding="utf-8") as f:
+            json.dump(entries, f, ensure_ascii=False)
+
+    def _read_plan(self):
+        with open(os.path.join(self.d, "img_plan.json"), encoding="utf-8") as f:
+            return json.load(f)
+
+    def test_backfills_only_bare_content_pages(self):
+        self._design(
+            [
+                # ① 客户图整页底 → 有背景 → 跳过
+                {"page": 1, "visual": {"route": "source-enhanced", "usage_intent": "source_enhanced_bg", "source_file": "src_1.png"}},
+                # ② 设计选定带提示词的 ai-B → 有背景（ensure_ai_img_plan 已注入）→ 跳过
+                {"page": 2, "visual": {"route": "ai-B", "aspect": "16:9", "prompt": "a calm industrial backdrop, no text"}},
+                # ③ 结构页 route=html（前景是 HTML 图表、没有背景图）→ 补氛围底图
+                {"page": 3, "visual": {"route": "html"}},
+                # ④ route=none（没有视觉）→ 补氛围底图
+                {"page": 4, "visual": {"route": "none"}},
+                # ⑤ 完全缺 visual → 补氛围底图
+                {"page": 5},
+                # ⑥ route=ai-B 但【无 prompt】（ensure_ai_img_plan 已跳过它、留给兜底）→ 该页 AI 底图没着落 → 补氛围底图
+                {"page": 6, "visual": {"route": "ai-B", "aspect": "16:9"}},
+            ]
+        )
+        # 模拟 ensure_ai_img_plan 已先跑：p2 的 ai_p2.png 已在、且有一条客户图增强条目。
+        self._img_plan(
+            [
+                {"file": "enhanced_src_1.png", "mode": "image-to-image", "source_file": "src_1.png", "prompt": "x"},
+                {"file": "ai_p2.png", "mode": "text-to-image", "aspect": "16:9", "prompt": "a calm industrial backdrop, no text"},
+            ]
+        )
+        rc = psl.ensure_page_backgrounds(self.d)
+        self.assertEqual(rc, 0)
+        ip = self._read_plan()
+        by_file = {e["file"]: e for e in ip}
+        # 无背景内容页 p3/p4/p5/p6 各补一条氛围底图（约定名）。
+        for pg in (3, 4, 5, 6):
+            self.assertIn(f"ai_p{pg}.png", by_file, f"p{pg} 应补氛围底图")
+            self.assertEqual(by_file[f"ai_p{pg}.png"]["mode"], "text-to-image")
+            self.assertEqual(by_file[f"ai_p{pg}.png"]["aspect"], "16:9")
+        # 已有背景的页不补：p1（客户图底）、p2（ai-* 带 prompt，已在）。
+        self.assertNotIn("ai_p1.png", by_file)
+        # p2 仍是原 ai_p2 那条、未被重复注入。
+        self.assertEqual(sum(1 for e in ip if e["file"] == "ai_p2.png"), 1)
+        # 客户图增强条目保留。
+        self.assertIn("enhanced_src_1.png", by_file)
+        # 总数 = 原 2 条 + 新 4 条 = 6。
+        self.assertEqual(len(ip), 6)
+
+    def test_source_enhanced_customer_visual_pages_never_get_independent_ai_bg(self):
+        # 2026-07-03 真机 3/5/6/8/9 页事故回归锁：route=source-enhanced 的页（无论 hero/contain/gallery/bg）
+        # 一律不再注入独立 ai_p<page>.png，`.edit-bg` 交给 build_batch 既有的 VI 渐变兜底。
+        self._design(
+            [
+                {"page": 3, "visual": {"route": "source-enhanced", "usage_intent": "source_enhanced_hero", "source_file": "src_2.jpg"}},
+                {"page": 5, "visual": {"route": "source-enhanced", "usage_intent": "direct_contain", "source_file": "src_6.png"}},
+                {"page": 6, "visual": {"route": "source-enhanced", "usage_intent": "gallery", "source_file": "src_3.png+src_4.png+src_5.png"}},
+                {"page": 9, "visual": {"route": "source-enhanced", "usage_intent": "source_enhanced_hero", "source_file": "src_9.png"}},
+            ]
+        )
+        rc = psl.ensure_page_backgrounds(self.d)
+        self.assertEqual(rc, 0)
+        ip = self._read_plan()
+        by_file = {e["file"]: e for e in ip}
+        for pg in (3, 5, 6, 9):
+            self.assertNotIn(f"ai_p{pg}.png", by_file, f"p{pg} 有客户图视觉，不应再补独立 AI 背景")
+        self.assertEqual(ip, [])
+
+    def test_no_customer_image_page_still_gets_ai_bg_control_group(self):
+        # 对照组（页7 真机验证：无客户图页，独立 AI 背景 + VI 渐变兜底效果正常）——回归锁，确保
+        # 「路由收紧」没有误伤真正需要背景图的页。
+        self._design([{"page": 7, "visual": {"route": "html"}}])
+        psl.ensure_page_backgrounds(self.d)
+        by_file = {e["file"]: e for e in self._read_plan()}
+        self.assertIn("ai_p7.png", by_file)
+
+    def test_atmos_prompt_shape(self):
+        self._design([{"page": 3, "visual": {"route": "html"}}])
+        psl.ensure_page_backgrounds(self.d)
+        ent = next(e for e in self._read_plan() if e["file"] == "ai_p3.png")
+        # 氛围底图提示词：产品详情页氛围 + 含质量词 + 以 no-text 尾收口（不画结构图，免与前景打架）。
+        self.assertIn("atmospheric", ent["prompt"])
+        self.assertIn("no diagrams", ent["prompt"])
+        self.assertTrue(ent["prompt"].rstrip().endswith(psl._NO_TEXT_TAIL))
+
+    def test_semantic_page_prompt_takes_priority(self):
+        self._design([
+            {
+                "page": 8,
+                "one_sentence_takeaway": "安装过程从经验依赖变成可复核路径",
+                "visual_story": "用真实装配现场让观众先看到落地方法",
+                "main_visual_layer": "航空器总装车间场景",
+                "text_overlay_zone": "left",
+                "visual": {"route": "html"},
+            }
+        ])
+        psl.ensure_page_backgrounds(self.d)
+        ent = next(e for e in self._read_plan() if e["file"] == "ai_p8.png")
+        self.assertIn("安装过程", ent["prompt"])
+        self.assertIn("航空器总装车间", ent["prompt"])
+        self.assertIn("no text", ent["prompt"].lower())
+
+    def test_i2i_style_semantic_prompt_on_non_source_page_becomes_complementary_background(self):
+        # route≠source-enhanced 的页（本函数仍会补背景）若 semantic_image_prompt 本身写成了 i2i 指令
+        # （design 误写/沿用了别处的 i2i 提示词），仍需转成不抢戏的互补背景，而不是原样喂给 t2i
+        # （模型没有参考图时会随机生成瓶子/设备等无关主体）。route=source-enhanced 的页现在由
+        # ensure_page_backgrounds 直接跳过整个背景注入，不会走到这条互补背景生成路径。
+        self._design([
+            {
+                "page": 9,
+                "one_sentence_takeaway": "多终端沉浸式调阅让档案进入现场",
+                "visual_story": "前景插图展示电脑、VR 眼镜和移动终端组合",
+                "semantic_image_prompt": (
+                    "Use the attached image as the strict visual reference: "
+                    "preserve its main subject, content and real colors exactly."
+                ),
+                "text_overlay_zone": "left",
+                "visual": {"route": "ai-B"},
+            }
+        ])
+        psl.ensure_page_backgrounds(self.d)
+        ent = next(e for e in self._read_plan() if e["file"] == "ai_p9.png")
+        prompt = ent["prompt"].lower()
+        self.assertIn("complementary", prompt)
+        self.assertIn("separate customer-image foreground", prompt)
+        self.assertNotIn("use the attached image", prompt)
+        self.assertNotIn("preserve its main subject", prompt)
+        self.assertIn("no bottle", prompt)
+        self.assertIn("no standalone product", prompt)
+
+    def test_per_page_variant_differs(self):
+        # 相邻补背景的页取不同光位变体（确定性、非随机），避免氛围底图完全雷同。
+        self._design([{"page": 3, "visual": {"route": "html"}}, {"page": 4, "visual": {"route": "none"}}])
+        psl.ensure_page_backgrounds(self.d)
+        by_file = {e["file"]: e for e in self._read_plan()}
+        self.assertNotEqual(by_file["ai_p3.png"]["prompt"], by_file["ai_p4.png"]["prompt"])
+
+    def test_dedups_existing_ai_file(self):
+        # img_plan 已有 ai_p3.png（如 ensure_ai_img_plan 注入）→ 不重复注入。
+        self._design([{"page": 3, "visual": {"route": "html"}}])
+        self._img_plan([{"file": "ai_p3.png", "mode": "text-to-image", "aspect": "16:9", "prompt": "preexisting, no text"}])
+        psl.ensure_page_backgrounds(self.d)
+        ip = self._read_plan()
+        self.assertEqual(sum(1 for e in ip if e["file"] == "ai_p3.png"), 1)
+        self.assertEqual(ip[0]["prompt"], "preexisting, no text")  # 原条目不被覆盖
+
+    def test_idempotent(self):
+        self._design([{"page": 3, "visual": {"route": "html"}}, {"page": 4, "visual": {"route": "none"}}])
+        psl.ensure_page_backgrounds(self.d)
+        n1 = len(self._read_plan())
+        psl.ensure_page_backgrounds(self.d)
+        self.assertEqual(len(self._read_plan()), n1)
+
+    def test_no_design_no_crash(self):
+        rc = psl.ensure_page_backgrounds(self.d)
+        self.assertEqual(rc, 0)
+
+    def test_creates_img_plan_when_absent(self):
+        # img_plan 还不存在时也能创建并注入。
+        self._design([{"page": 1, "visual": {"route": "none"}}])
+        psl.ensure_page_backgrounds(self.d)
+        self.assertEqual([e["file"] for e in self._read_plan()], ["ai_p1.png"])
+
+
+class TestReconcileMissing(unittest.TestCase):
+    """生图后确定性兜底：缺失的 enhanced 派生图从原图拷贝顶上（防 deck 死链空框）。"""
+
+    def _setup_build(self, images, assets_files):
+        d = tempfile.mkdtemp(prefix="srclayout-rec-")
+        assets = os.path.join(d, "assets")
+        os.makedirs(assets, exist_ok=True)
+        with open(os.path.join(d, "material.json"), "w", encoding="utf-8") as f:
+            json.dump({"has_source": True, "images": images}, f, ensure_ascii=False)
+        plan = psl.build_plan(d)
+        with open(os.path.join(d, "source_layout_plan.json"), "w", encoding="utf-8") as f:
+            json.dump(plan, f, ensure_ascii=False)
+        for name, content in assets_files.items():
+            with open(os.path.join(assets, name), "wb") as f:
+                f.write(content)
+        return d, assets, plan
+
+    def test_missing_enhanced_copied_from_source(self):
+        # 低清 bg 图 → source_enhanced_bg、enhance=true，enhanced_src_1.jpg ← src_1.jpg
+        d, assets, plan = self._setup_build(
+            [_img("src_1.jpg", 800, 450, vision=_vision("山景", bg=True))],
+            {"src_1.jpg": b"ORIGINAL-IMAGE-BYTES"},  # 原图在、增强图缺
+        )
+        self.assertEqual(plan["enhance_entries"][0]["file"], "enhanced_src_1.jpg")
+        self.assertEqual(plan["enhance_entries"][0]["source_file"], "src_1.jpg")
+        self.assertEqual(psl.reconcile_missing(d), 0)
+        enhanced = os.path.join(assets, "enhanced_src_1.jpg")
+        self.assertTrue(os.path.isfile(enhanced))  # 兜底拷出来了
+        with open(enhanced, "rb") as f:
+            self.assertEqual(f.read(), b"ORIGINAL-IMAGE-BYTES")  # 字节 = 原图
+
+    def test_existing_enhanced_not_overwritten(self):
+        d, assets, _ = self._setup_build(
+            [_img("src_1.jpg", 800, 450, vision=_vision("山景", bg=True))],
+            {"src_1.jpg": b"ORIGINAL", "enhanced_src_1.jpg": b"REAL-ENHANCED"},  # 真增强图已在
+        )
+        psl.reconcile_missing(d)
+        with open(os.path.join(assets, "enhanced_src_1.jpg"), "rb") as f:
+            self.assertEqual(f.read(), b"REAL-ENHANCED")  # 绝不被原图覆盖
+
+    def test_idempotent(self):
+        d, assets, _ = self._setup_build(
+            [_img("src_1.jpg", 800, 450, vision=_vision("山景", bg=True))],
+            {"src_1.jpg": b"ORIG"},
+        )
+        self.assertEqual(psl.reconcile_missing(d), 0)
+        self.assertEqual(psl.reconcile_missing(d), 0)  # 再跑不报错、幂等
+        with open(os.path.join(assets, "enhanced_src_1.jpg"), "rb") as f:
+            self.assertEqual(f.read(), b"ORIG")
+
+    def test_missing_source_no_crash(self):
+        d, assets, _ = self._setup_build(
+            [_img("src_1.jpg", 800, 450, vision=_vision("山景", bg=True))],
+            {},  # 连原图都没有
+        )
+        self.assertEqual(psl.reconcile_missing(d), 0)  # 恒成功、不崩
+        self.assertFalse(os.path.isfile(os.path.join(assets, "enhanced_src_1.jpg")))
+
+    def test_no_plan_no_crash(self):
+        d = tempfile.mkdtemp(prefix="srclayout-rec-empty-")
+        self.assertEqual(psl.reconcile_missing(d), 0)  # 无 source_layout_plan.json 也恒 0
+
+
+class TestEnhanceStyle(unittest.TestCase):
+    """图生图三态：bg(背景换干净底) / hero(场景换干净底) / cutout(离散主体抠透明前景插图)。"""
+
+    def test_discrete_subject_hero_is_cutout_transparent(self):
+        # 低清 + 离散主体（产品/设备/相机）+ 非背景 → source_enhanced_hero + cutout 透明
+        e = psl.plan_one(_img("p.png", 600, 900, vision=_vision("一台手持工业相机的产品特写", bg=False)))
+        self.assertEqual(e["usage_intent"], "source_enhanced_hero")
+        self.assertEqual(e["enhance_style"], "cutout")
+        self.assertIn("transparent", e["enhance_prompt"].lower())  # 抠透明背景
+
+    def test_multi_terminal_devices_are_cutout_not_dense(self):
+        e = psl.plan_one(
+            _img(
+                "terminals.png",
+                1400,
+                900,
+                vision=_vision(
+                    "多种播放终端产品展示，包括电脑显示器、VR眼镜、平板和手机，纯色渐变背景",
+                    bg=False,
+                    elements=["播放终端", "电脑", "VR眼镜", "手机"],
+                ),
+            )
+        )
+        self.assertFalse(e["is_dense_info"])
+        self.assertEqual(e["usage_intent"], "source_enhanced_hero")
+        self.assertEqual(e["enhance_style"], "cutout")
+        self.assertEqual(e["image_role"], "foreground_cutout")
+        self.assertEqual(e["target_layer"], "foreground")
+        self.assertIn("transparent", e["enhance_prompt"].lower())
+
+    def test_terminal_interface_screenshot_remains_dense(self):
+        e = psl.plan_one(
+            _img(
+                "terminal_ui.png",
+                1200,
+                800,
+                vision=_vision(
+                    "终端界面截图，包含表格、文字、数据列表和控制台状态",
+                    bg=False,
+                    elements=["终端界面", "表格", "数据列表"],
+                ),
+            )
+        )
+        self.assertTrue(e["is_dense_info"])
+        self.assertEqual(e["enhance_style"], "dense")
+        self.assertEqual(e["image_role"], "faithful_document")
+
+    def test_scene_hero_is_clean_bg_not_transparent(self):
+        # 低清 + 场景（车间/现场）+ 非背景 → source_enhanced_hero + hero(换干净底)，非透明
+        e = psl.plan_one(_img("s.png", 600, 900, vision=_vision("航空器总装车间现场", bg=False)))
+        self.assertEqual(e["usage_intent"], "source_enhanced_hero")
+        self.assertEqual(e["enhance_style"], "hero")
+        self.assertNotIn("transparent", e["enhance_prompt"].lower())
+        self.assertIn("backdrop", e["enhance_prompt"].lower())
+
+    def test_bg_style_unchanged(self):
+        e = psl.plan_one(_img("b.png", 800, 450, vision=_vision("开阔山景风光", bg=True)))
+        self.assertEqual(e["usage_intent"], "source_enhanced_bg")
+        self.assertEqual(e["enhance_style"], "bg")
+        self.assertIn("background", e["enhance_prompt"].lower())
+        self.assertNotIn("transparent", e["enhance_prompt"].lower())
+
+    def test_scene_and_subject_keyword_scene_wins(self):
+        # 同时含场景词+主体词 → 场景优先、不抠透明（保守不误抠掉环境）
+        e = psl.plan_one(_img("m.png", 600, 900, vision=_vision("车间里的一台设备", bg=False)))
+        self.assertEqual(e["enhance_style"], "hero")
+
+    def test_no_vision_has_no_style(self):
+        # 全图生图后，唯一 enhance=false 路径 = 无 vision 盲态 → enhance_style None。
+        e = psl.plan_one(_img("d.png", 1920, 1080))  # 无 vision
+        self.assertFalse(e["enhance_required"])
+        self.assertIsNone(e["enhance_style"])
+
+    def test_real_scene_hero_not_cutout(self):
+        # ③ real_scene 非背景图 → hero（保场景、不去背景），绝非 cutout 抠透明。
+        e = psl.plan_one(_img("rs.png", 1600, 1200, vision=_vision("智能工厂车间生产线现场", bg=False)))
+        self.assertEqual(e["usage_intent"], "source_enhanced_hero")
+        self.assertEqual(e["background_kind"], "real_scene")
+        self.assertEqual(e["enhance_style"], "hero")
+        self.assertNotIn("transparent", e["enhance_prompt"].lower())
+
+    def test_flat_base_discrete_subject_cutout(self):
+        # ③ flat_base（白底/棚拍）+ 离散主体（产品/相机）→ cutout 抠透明前景插图。
+        e = psl.plan_one(_img("fb.png", 600, 900, vision=_vision("白底棚拍的一台工业相机产品", bg=False)))
+        self.assertEqual(e["usage_intent"], "source_enhanced_hero")
+        self.assertEqual(e["background_kind"], "flat_base")
+        self.assertEqual(e["enhance_style"], "cutout")
+        self.assertIn("transparent", e["enhance_prompt"].lower())
+
+    def test_three_states_have_quality_words(self):
+        # ④ bg/hero/cutout 三态提示词都含高清质量词；bg 另含 cinematic depth、cutout 另含 crisp cut-out edges。
+        bg = psl.plan_one(_img("b.png", 800, 450, vision=_vision("开阔山景风光", bg=True)))
+        hero = psl.plan_one(_img("h.png", 600, 900, vision=_vision("航空器总装车间现场", bg=False)))
+        cutout = psl.plan_one(_img("c.png", 600, 900, vision=_vision("白底棚拍的一台工业相机产品", bg=False)))
+        self.assertEqual(bg["enhance_style"], "bg")
+        self.assertEqual(hero["enhance_style"], "hero")
+        self.assertEqual(cutout["enhance_style"], "cutout")
+        for e in (bg, hero, cutout):
+            p = e["enhance_prompt"].lower()
+            self.assertIn("high resolution", p)
+            self.assertIn("sharp", p)
+        self.assertIn("crisp cut-out edges", cutout["enhance_prompt"].lower())
+        self.assertIn("cinematic depth", bg["enhance_prompt"].lower())
+
+    # ---- 用户细化（2026-06-27）：带文字图不能直接当背景 + flat 底前景图抠透明（两层底打架）----
+
+    def test_flat_base_nondiscrete_foreground_is_cutout(self):
+        # flat 底（渐变/纹理/白底）的【非离散主体】前景图 → 也抠透明（治「带自有底纹的图放我们背景上=两层底打架」）。
+        e = psl.plan_one(_img("fg.png", 600, 900, vision=_vision("渐变色纹理底上的一个抽象品牌图形", bg=False)))
+        self.assertEqual(e["usage_intent"], "source_enhanced_hero")
+        self.assertEqual(e["background_kind"], "flat_base")
+        self.assertEqual(e["enhance_style"], "cutout")
+        self.assertIn("transparent", e["enhance_prompt"].lower())
+        self.assertIn("no texture", e["enhance_prompt"].lower())  # 连背景纹理一起抠掉
+
+    def test_bg_with_text_forces_textfree_redraw(self):
+        # 背景图自带文字/横幅/水印 → bg 态换「允许重绘 + 强制抹字」前导（治「带字图当背景露字」）。
+        e = psl.plan_one(_img("bt.png", 1280, 720, vision=_vision("印有标语横幅文字的开阔风光大图", bg=True)))
+        self.assertEqual(e["usage_intent"], "source_enhanced_bg")
+        self.assertEqual(e["enhance_style"], "bg")
+        self.assertTrue(e["has_embedded_text"])
+        p = e["enhance_prompt"]
+        self.assertIn("REMOVE", p)  # 强制抹掉所有文字
+        self.assertIn("text-free", p.lower())
+        self.assertNotIn("do not replace, restyle or invent", p)  # 不再用严格保内容前导
+
+    def test_bg_without_text_keeps_strict_preserve(self):
+        # 背景图无文字 → 仍用严格「保内容不换主体」前导（向后兼容）。
+        e = psl.plan_one(_img("b.png", 1280, 720, vision=_vision("开阔山景风光", bg=True)))
+        self.assertEqual(e["enhance_style"], "bg")
+        self.assertFalse(e["has_embedded_text"])
+        self.assertIn("do not replace, restyle or invent", e["enhance_prompt"])
+
+    def test_hero_with_text_removes_text(self):
+        # 场景 hero 图带水印 → hero 态也强制抹字。
+        e = psl.plan_one(_img("h.png", 1600, 1200, vision=_vision("带水印的智能工厂车间生产线现场", bg=False)))
+        self.assertEqual(e["enhance_style"], "hero")
+        self.assertTrue(e["has_embedded_text"])
+        self.assertIn("REMOVE", e["enhance_prompt"])
+
+    def test_has_embedded_text_detection(self):
+        self.assertTrue(psl._has_embedded_text(_vision("一张带标题文字的封面图")))
+        self.assertTrue(psl._has_embedded_text(_vision("product shot with a watermark")))
+        self.assertFalse(psl._has_embedded_text(_vision("开阔山景风光")))
+        self.assertFalse(psl._has_embedded_text(None))
+
+    def test_discrete_subject_never_full_background(self):
+        # 用户红线（2026-06-27 推荐改动）：离散主体(产品/设备)即便被识图标 suitable_as_background，
+        # 也【不当整页背景】(主体+自有底纹放我们背景上=两层底打架) → 转前景主视觉 + cutout 透明。
+        e = psl.plan_one(_img("p.png", 1920, 1080, vision=_vision("白底棚拍的一台工业相机产品", bg=True)))
+        self.assertEqual(e["usage_intent"], "source_enhanced_hero")  # 非 source_enhanced_bg
+        self.assertEqual(e["enhance_style"], "cutout")
+        self.assertIn("transparent", e["enhance_prompt"].lower())
+
+    def test_scene_background_still_full_background(self):
+        # 反证：真·场景背景图(非离散主体)仍走整页底图，不受上面红线影响。
+        e = psl.plan_one(_img("s.png", 1920, 1080, vision=_vision("辽阔的数据中心机房全景", bg=True)))
+        self.assertEqual(e["usage_intent"], "source_enhanced_bg")
+        self.assertEqual(e["enhance_style"], "bg")
+
+
+class TestEmbeddedTextExtraction(unittest.TestCase):
+    """2026-07-03：src_6 真机事故（enhanced_src_6.png 原样保留了「AI全景相机优势」标题+标签）——
+    识图结构化 `embedded_text` 字段优先于关键词启发式；抹字指令引用实际抄下来的文字；dense 且
+    content_type=screenshot_slide/poster 时新增「去装饰性 chrome 文字、保结构」分支；chart 类型
+    数据标签不受影响（回归锁）。"""
+
+    def test_structured_field_takes_priority_over_keyword_heuristic(self):
+        # 文案里没有任何"文字/水印"类关键词，但 embedded_text 非空 → 仍判 True（结构化数据优先）。
+        v = _vision("一张开阔风光照", embedded_text=[{"text": "夏日促销", "region": "右下角"}])
+        self.assertTrue(psl._has_embedded_text(v))
+
+    def test_structured_field_explicit_empty_overrides_keyword_false_positive(self):
+        # 字段存在且为空列表 = 识图明确判过"没有"，即便 description 里出现"标题"字样也不再猜。
+        v = {"description": "一张封面标题风格的摄影作品", "embedded_text": []}
+        self.assertFalse(psl._has_embedded_text(v))
+
+    def test_missing_field_falls_back_to_keyword_heuristic(self):
+        # 旧格式识图 JSON（无 embedded_text 键）→ 退回关键词启发式，向后兼容。
+        self.assertTrue(psl._has_embedded_text(_vision("一张带标题文字的封面图")))
+        self.assertFalse(psl._has_embedded_text(_vision("开阔山景风光")))
+
+    def test_bg_prompt_quotes_actual_embedded_text(self):
+        # bg 分支：有 embedded_text 时抹字指令引用真实抄下来的文字，而非泛泛措辞。
+        v = _vision("印有标语横幅文字的开阔风光大图", bg=True,
+                     embedded_text=[{"text": "限时特惠", "region": "顶部横幅"}])
+        e = psl.plan_one(_img("bt.png", 1280, 720, vision=v))
+        p = e["enhance_prompt"]
+        self.assertIn("限时特惠", p)
+        self.assertIn("顶部横幅", p)
+        self.assertIn("REMOVED", p)
+        self.assertNotIn("has text, captions, logos or watermarks on it", p)  # 不再是泛化措辞
+
+    def test_bg_prompt_falls_back_to_generic_wording_without_embedded_text(self):
+        # 旧格式（has_text=True 但无 embedded_text，纯关键词猜）→ 保持原泛化措辞，不报错。
+        v = _vision("印有标语横幅文字的开阔风光大图", bg=True)
+        e = psl.plan_one(_img("bt2.png", 1280, 720, vision=v))
+        self.assertIn("has text, captions, logos or watermarks on it", e["enhance_prompt"])
+
+    def test_dense_screenshot_slide_with_embedded_text_strips_caption_preserves_structure(self):
+        # src_6 真机形态：content_type=screenshot_slide + embedded_text → 保结构去装饰字。
+        v = _vision(
+            "一张完整的演示页截图，标题「AI全景相机优势」，含对比排版",
+            content_type="screenshot_slide",
+            embedded_text=[
+                {"text": "AI全景相机优势", "region": "顶部标题"},
+                {"text": "多台监控", "region": "左侧标签"},
+                {"text": "1台全景", "region": "左侧标签"},
+            ],
+        )
+        e = psl.plan_one(_img("src_6.png", 1432, 792, vision=v))
+        self.assertEqual(e["usage_intent"], "direct_contain")
+        self.assertEqual(e["enhance_style"], "dense")
+        self.assertEqual(e["text_policy"], "remove_all_text")  # 复用既有枚举值，不新造
+        p = e["enhance_prompt"]
+        self.assertIn("AI全景相机优势", p)
+        self.assertIn("多台监控", p)
+        self.assertIn("1台全景", p)
+        self.assertIn("REMOVED", p)
+        self.assertIn("layout, sub-images, comparison structure", p)  # 结构仍要求保留
+        self.assertNotIn("every data point, label, axis, value and structure unchanged", p)  # 旧全保真措辞不出现（那是"绝不去字"的措辞）
+        self.assertEqual(e["embedded_text"][0]["text"], "AI全景相机优势")
+
+    def test_dense_chart_type_unaffected_regression(self):
+        # 回归锁：真正的图表（数据标签=数据本身）即便识图误标了 embedded_text，也不能被去字——
+        # 只有 screenshot_slide/poster 才走去字分支，chart 维持原有纯保真行为。
+        v = _vision(
+            "巡检效率对比柱状图", content_type="chart",
+            embedded_text=[{"text": "68%", "region": "柱顶标签"}],
+        )
+        e = psl.plan_one(_img("chart.png", 1200, 800, vision=v))
+        self.assertEqual(e["enhance_style"], "dense")
+        self.assertEqual(e["text_policy"], "preserve_data_text")  # 不受影响
+        p = e["enhance_prompt"]
+        self.assertIn("every data point, label, axis, value and structure unchanged", p)
+        self.assertNotIn("REMOVED", p)
+
+    def test_dense_screenshot_slide_without_embedded_text_unaffected(self):
+        # screenshot_slide 但识图没抄到任何文字（embedded_text=[]）→ 仍走原保真分支，不强行造词去字。
+        v = _vision("一张干净的产品展示截图", content_type="screenshot_slide", embedded_text=[])
+        e = psl.plan_one(_img("clean.png", 1600, 900, vision=v))
+        self.assertEqual(e["text_policy"], "preserve_data_text")
+        self.assertNotIn("embedded_text", e)
+
+    def test_embedded_text_absent_from_entry_when_empty(self):
+        e = psl.plan_one(_img("plain.png", 1500, 1000, vision=_vision("普通产品照")))
+        self.assertNotIn("embedded_text", e)
+
+    def test_embedded_text_string_items_normalized(self):
+        # 兼容识图偶尔直接输出纯字符串数组（非 {text,region} 对象）而非严格 schema。
+        v = _vision("测试图", embedded_text=["纯字符串文字"])
+        self.assertEqual(psl._embedded_text_list(v), [{"text": "纯字符串文字", "region": ""}])
+
+    def test_plan_md_renders_recreate_prompt(self):
+        # 设计阶段只读 source_layout_plan.md——渲染是让它"看得见"去字信息的唯一途径。
+        vision = _vision(
+            "一张完整的演示页截图，标题「AI全景相机优势」", content_type="screenshot_slide",
+            embedded_text=[{"text": "AI全景相机优势", "region": "顶部标题"},
+                           {"text": "多台监控", "region": "左箭头标签"}],
+        )
+        d = tempfile.mkdtemp(prefix="srclayout-et-")
+        with open(os.path.join(d, "material.json"), "w", encoding="utf-8") as f:
+            json.dump({"has_source": True, "images": [_img("src_6.png", 1432, 792, vision=vision)]},
+                      f, ensure_ascii=False)
+        plan = psl.build_plan(d)
+        psl.write_plan_md(d, plan)
+        with open(os.path.join(d, "source_layout_plan.md"), encoding="utf-8") as f:
+            md = f.read()
+        self.assertIn("AI全景相机优势", md)
+        self.assertIn("多台监控", md)
+        self.assertIn("原图文字已在图生图阶段去除", md)
+        self.assertIn("用真实 HTML 文字重新配出", md)
+
+    def test_plan_md_no_recreate_line_when_no_embedded_text(self):
+        d = tempfile.mkdtemp(prefix="srclayout-et2-")
+        with open(os.path.join(d, "material.json"), "w", encoding="utf-8") as f:
+            json.dump({"has_source": True, "images": [_img("plain.png", 1500, 1000, vision=_vision("普通照片"))]},
+                      f, ensure_ascii=False)
+        plan = psl.build_plan(d)
+        psl.write_plan_md(d, plan)
+        with open(os.path.join(d, "source_layout_plan.md"), encoding="utf-8") as f:
+            md = f.read()
+        self.assertNotIn("原图文字已在图生图阶段去除", md)
+
+
+class TestBackgroundKind(unittest.TestCase):
+    """② 识图驱动背景类型分流 _background_kind：real_scene / flat_base / unknown。"""
+
+    def test_real_scene(self):
+        self.assertEqual(psl._background_kind(_vision("智能工厂车间生产线的现场实拍")), "real_scene")
+
+    def test_flat_base(self):
+        self.assertEqual(psl._background_kind(_vision("产品在纯色渐变背景上的棚拍特写")), "flat_base")
+
+    def test_unknown(self):
+        self.assertEqual(psl._background_kind(_vision("一杯热气腾腾的咖啡")), "unknown")
+
+    def test_real_scene_wins_over_flat_base(self):
+        # 同含场景词+棚拍词 → real_scene 优先（保守保场景，别误抠/误换底）。
+        self.assertEqual(psl._background_kind(_vision("车间现场的纯色背景棚拍")), "real_scene")
+
+    def test_palette_and_elements_counted(self):
+        # description + palette_impression + key_elements 一起判（不止看 description）。
+        v = {"description": "一台设备", "key_elements": ["白底"], "palette_impression": "纯色"}
+        self.assertEqual(psl._background_kind(v), "flat_base")
+
+    def test_no_vision_unknown(self):
+        self.assertEqual(psl._background_kind(None), "unknown")
+
+
+class TestStructuredVisionFields(unittest.TestCase):
+    """识图结构化字段（2026-07-02 坠机图/旧 PPT 截图事故）：relevant_to_topic / content_type。"""
+
+    def test_irrelevant_image_is_discarded(self):
+        # relevant_to_topic=false（坠机资讯图与主题负相关）→ 弃用：不增强、不进模板、零槽位。
+        v = _vision("坠机短视频封面，含黄色大字幕", bg=False)
+        v["relevant_to_topic"] = False
+        e = psl.plan_one(_img("src_1.jpg", 640, 480, vision=v))
+        self.assertEqual(e["usage_intent"], "discard")
+        self.assertFalse(e["enhance_required"])
+        self.assertEqual(e["display_role"], "discard")
+        self.assertEqual(e["min_canvas_fraction"], 0.0)
+        self.assertEqual(e["layout_constraint"], "do_not_use")
+        self.assertEqual(e["target_layer"], "none")
+        self.assertEqual(e["recommended_templates"], [])
+        self.assertNotIn("enhance_prompt", e)
+
+    def test_relevant_true_keeps_normal_flow(self):
+        v = _vision("开阔的山景风光照", bg=True)
+        v["relevant_to_topic"] = True
+        e = psl.plan_one(_img("src_2.png", 1920, 1080, vision=v))
+        self.assertEqual(e["usage_intent"], "source_enhanced_bg")
+
+    def test_old_vision_without_fields_unchanged(self):
+        # 旧 vision JSON（无新字段）→ 走既有分支，行为不变。
+        e = psl.plan_one(_img("src_3.png", 1920, 1080, vision=_vision("开阔的山景风光照", bg=True)))
+        self.assertEqual(e["usage_intent"], "source_enhanced_bg")
+
+    def test_screenshot_slide_forced_contain(self):
+        # content_type=screenshot_slide（整版 PPT 截图，slide22 事故）：即便描述词没命中 dense 启发，
+        # 也强制 direct_contain + 忠实保真——绝不背景化。
+        v = _vision("对比展示页面，上下两行内容", bg=True)  # 描述刻意不含「截图/图表」关键词
+        v["content_type"] = "screenshot_slide"
+        e = psl.plan_one(_img("src_6.png", 1432, 792, vision=v))
+        self.assertTrue(e["is_dense_info"])
+        self.assertEqual(e["usage_intent"], "direct_contain")
+        self.assertEqual(e["enhance_style"], "dense")
+        self.assertEqual(e["target_layer"], "evidence")
+
+
+class TestReconcileSourceExtensions(unittest.TestCase):
+    """design.json/img_plan.json 的客户图扩展名对齐 source_assets.json 真实文件名（治「design LLM
+    猜错扩展名致生图找不到源图、静默退化占位图」——2026-07-05 真机 src_9 事故：design 猜 src_9.jpg，
+    真实文件是 src_9.png，image-to-image 找不到源文件直接 degraded=gradient-png，deck 用了一张低质
+    量渐变图当「安全与适航」页背景，而真正生成好的 enhanced_src_9.png 被晾在一边没被引用）。"""
+
+    def _setup(self, source_assets_files, design=None, img_plan=None):
+        d = tempfile.mkdtemp(prefix="srclayout-reconcile-ext-")
+        with open(os.path.join(d, "source_assets.json"), "w", encoding="utf-8") as f:
+            json.dump({"images": [{"file": fn, "w": 800, "h": 600} for fn in source_assets_files]}, f)
+        design_path = os.path.join(d, "design.json")
+        if design is not None:
+            with open(design_path, "w", encoding="utf-8") as f:
+                json.dump(design, f, ensure_ascii=False)
+        if img_plan is not None:
+            with open(os.path.join(d, "img_plan.json"), "w", encoding="utf-8") as f:
+                json.dump(img_plan, f, ensure_ascii=False)
+        return d, design_path
+
+    def test_wrong_extension_corrected_in_img_plan_and_design(self):
+        # 真机 src_9 事故复现：真实文件 src_9.png，design/img_plan 都猜成 .jpg。
+        design = {"pages": [{"page": 10, "visual": {
+            "route": "source-enhanced", "source_file": "src_9.jpg",
+            "enhanced_file": "enhanced_src_9.jpg", "usage_intent": "source_enhanced_bg",
+        }}]}
+        img_plan = [{"file": "enhanced_src_9.jpg", "source_file": "src_9.jpg", "mode": "image-to-image"}]
+        d, design_path = self._setup(["src_9.png"], design=design, img_plan=img_plan)
+        rc = psl.reconcile_source_extensions(d, design_path)
+        self.assertEqual(rc, 0)
+        with open(design_path, encoding="utf-8") as f:
+            fixed_design = json.load(f)
+        visual = fixed_design["pages"][0]["visual"]
+        self.assertEqual(visual["source_file"], "src_9.png")
+        self.assertEqual(visual["enhanced_file"], "enhanced_src_9.png")
+        with open(os.path.join(d, "img_plan.json"), encoding="utf-8") as f:
+            fixed_plan = json.load(f)
+        self.assertEqual(fixed_plan[0]["file"], "enhanced_src_9.png")
+        self.assertEqual(fixed_plan[0]["source_file"], "src_9.png")
+
+    def test_dedup_when_corrected_entry_collides_with_existing_correct_one(self):
+        # 纠正扩展名后与 source_layout_plan 已算好的正确条目撞车 → 去重保留一条，不留重复生图任务。
+        img_plan = [
+            {"file": "enhanced_src_9.jpg", "source_file": "src_9.jpg", "mode": "image-to-image", "usage_intent": "source_enhanced_bg"},
+            {"file": "enhanced_src_9.png", "source_file": "src_9.png", "mode": "image-to-image", "usage_intent": "source_enhanced_hero"},
+        ]
+        d, design_path = self._setup(["src_9.png"], design={"pages": []}, img_plan=img_plan)
+        psl.reconcile_source_extensions(d, design_path)
+        with open(os.path.join(d, "img_plan.json"), encoding="utf-8") as f:
+            fixed_plan = json.load(f)
+        self.assertEqual(len(fixed_plan), 1, fixed_plan)
+        self.assertEqual(fixed_plan[0]["file"], "enhanced_src_9.png")
+
+    def test_no_mismatch_is_noop(self):
+        # 扩展名本来就对 → 不改动，幂等。
+        design = {"pages": [{"page": 1, "visual": {"source_file": "src_1.jpg", "enhanced_file": "enhanced_src_1.jpg"}}]}
+        img_plan = [{"file": "enhanced_src_1.jpg", "source_file": "src_1.jpg"}]
+        d, design_path = self._setup(["src_1.jpg"], design=design, img_plan=img_plan)
+        rc = psl.reconcile_source_extensions(d, design_path)
+        self.assertEqual(rc, 0)
+        with open(design_path, encoding="utf-8") as f:
+            self.assertEqual(json.load(f), design)
+        with open(os.path.join(d, "img_plan.json"), encoding="utf-8") as f:
+            self.assertEqual(json.load(f), img_plan)
+
+    def test_missing_source_assets_json_no_crash(self):
+        d = tempfile.mkdtemp(prefix="srclayout-reconcile-ext-empty-")
+        self.assertEqual(psl.reconcile_source_extensions(d), 0)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)