@lark-apaas/coding-steering 0.1.32-dev.a87aa13 → 0.1.32-dev.b2f659e

package/steering/design-html/skills/pptx-style-extract/scripts/package.py

@@ -52,6 +52,15 @@ L 层判断单 schema（<l-out-dir> 四个文件，这段就是填写说明书
         role: content
         color: "{colors.surface}"
 
+    asset_vision_groups:              # 抽取草案专用，打包后不进入消费包
+      - id: vision-1
+        source_media: [mark.png, ornament.png]
+        visual_kind: decorative       # FaaS 枚举；同组默认，可被 asset_decisions 覆盖
+
+    asset_decisions:                  # 可选：单图覆盖；旧版 decision 仍兼容
+      - source_media: chart.png
+        visual_kind: chart
+
   说明：`boxes` / `aspect` / `canvas-source` **不要填**——脚本按 source_media 从
   extract.json 的 images[] 直接取，写进 ref/audit.yaml。
 
@@ -112,7 +121,7 @@ L 层判断单 schema（<l-out-dir> 四个文件，这段就是填写说明书
   Exceptions……）。脚本原样拼在 frontmatter 之后，不改一个字。
 """
 import argparse
-from collections import Counter
+from collections import Counter, defaultdict
 import hashlib
 import json
 import os
@@ -140,6 +149,32 @@ ASSET_CONSUMER_FIELDS = ['path', 'url', 'color', 'full', 'kind', 'role',
 ASSET_AUDIT_FIELDS = ['boxes', 'aspect', 'mark', 'confidence']
 KIND_PREFIX = {'background': 'bg', 'logo': 'logo', 'slogan': 'slogan',
                'texture': 'texture', 'icon': 'icon'}
+# 与 studio_server_faas 的 assetVisualKinds 对齐。它是抽取期视觉分类，不是 v2
+# 消费包的 kind：后者仍只允许 KIND_PREFIX 中的五种资产类型。
+ASSET_VISUAL_KINDS = {
+    'logo', 'slogan', 'background', 'texture', 'icon',
+    'decorative', 'illustration', 'photo', 'chart', 'screenshot',
+    'footer-copyright', 'page-number', 'watermark', 'content-image', 'unknown',
+}
+VISUAL_KIND_TO_DECISION = {
+    'logo': 'logo',
+    'slogan': 'slogan',
+    'background': 'background',
+    'texture': 'texture',
+    'icon': 'icon',
+    'decorative': 'texture',
+    'illustration': 'texture',
+    'photo': 'content',
+    'chart': 'content',
+    'screenshot': 'content',
+    'content-image': 'content',
+    'footer-copyright': 'omit',
+    'page-number': 'omit',
+    'watermark': 'omit',
+    # FaaS 也会把非内容的 unknown 局部图保留为 texture，避免丢掉未能命名的装饰。
+    'unknown': 'texture',
+}
+LEGACY_ASSET_DECISIONS = {'content', 'texture', 'logo', 'icon', 'slogan'}
 # 交付包的 ref/ 只留 audit.yaml（人复核数值出处用，几 KB）。
 # 频次原表、聚类原始数据、extract.json、重建图、logo 候选图全部留在 stage1 抽取目录，
 # 不拷进包——规范原本指望「下发时链路剥离」，但链路上没有环节真的剥离，结果
@@ -152,6 +187,46 @@ class Fail(SystemExit):
         super().__init__('package.py: %s' % msg)
 
 
+class AssetDecisions(dict):
+    """按素材的默认决定，以及只在对应 slot 生效的实例覆盖。"""
+
+    def __init__(self, defaults=None, overrides=None, roles=None,
+                 default_overrides=None, explicit_overrides=None):
+        super().__init__(defaults or {})
+        self.overrides = overrides or {}
+        self.roles = roles or {}
+        self.default_overrides = default_overrides or set()
+        self.explicit_overrides = explicit_overrides or set()
+
+    def for_slot(self, source, line, layout_name=None):
+        box = source_box(line) or slot_box(line)
+        return self.for_scope(source, layout_name, box)
+
+    def for_scope(self, source, layout_name, box):
+        if box is not None:
+            for key in ((source, layout_name, box), (source, None, box)):
+                if key in self.explicit_overrides:
+                    return self.overrides[key]
+        if source in self.default_overrides:
+            return self.get(source)
+        if box is not None:
+            for key in ((source, layout_name, box), (source, None, box)):
+                if key in self.overrides:
+                    return self.overrides[key]
+        return self.get(source)
+
+
+class AssetIds(dict):
+    """同一原图因实例用途不同而落成多个资产时，按最终用途取对应 id。"""
+
+    def __init__(self, defaults=None, by_decision=None):
+        super().__init__(defaults or {})
+        self.by_decision = by_decision or {}
+
+    def for_decision(self, source, decision):
+        return self.by_decision.get((source, decision)) or self.get(source)
+
+
 # ------------------------------------------------------------ 极简 YAML 读取
 def split_top_blocks(text):
     """顶层 `key:` 切块。返回 [(key, inline_value, block_lines)]，块内逐字节保留。"""
@@ -176,6 +251,55 @@ def split_top_blocks(text):
     return out
 
 
+LAYOUT_CONTROL_KEYS = {
+    'names', 'roles', 'text_roles', 'layout_modes', 'bg_rules',
+}
+
+
+def control_entry_keys(lines):
+    """读取扁平判断段的一级条目，防止整段覆盖时漏掉旧结论。"""
+    return {
+        match.group(1)
+        for line in lines
+        for match in [re.match(r'^\s{2}([\w-]+):', line)]
+        if match
+    }
+
+
+def load_layout_blocks(lout):
+    """读取版式坐标事实；新草案把可编辑判断区放在独立的小文件里。"""
+    lay_path = os.path.join(lout, 'layouts.yaml')
+    if not os.path.exists(lay_path):
+        return None
+    with open(lay_path, encoding='utf-8') as stream:
+        layouts = split_top_blocks(stream.read())
+    controls_path = os.path.join(lout, 'layout-controls.yaml')
+    if not os.path.exists(controls_path):
+        return layouts
+    with open(controls_path, encoding='utf-8') as stream:
+        controls = split_top_blocks(stream.read())
+    invalid = {key for key, _, _ in controls} - LAYOUT_CONTROL_KEYS
+    if invalid:
+        raise Fail('layout-controls.yaml 只能包含 %s，不能包含：%s'
+                   % ('|'.join(sorted(LAYOUT_CONTROL_KEYS)), ', '.join(sorted(invalid))))
+    legacy_keys = {key for key, _, _ in layouts if key in LAYOUT_CONTROL_KEYS}
+    control_keys = {key for key, _, _ in controls}
+    missing = legacy_keys - control_keys
+    if missing:
+        raise Fail('layout-controls.yaml 必须覆盖 layouts.yaml 的全部判断段，缺：%s'
+                   % ', '.join(sorted(missing)))
+    legacy_blocks = {key: lines for key, _, lines in layouts}
+    control_blocks = {key: lines for key, _, lines in controls}
+    for key in sorted(legacy_keys):
+        missing_entries = (control_entry_keys(legacy_blocks[key])
+                           - control_entry_keys(control_blocks[key]))
+        if missing_entries:
+            raise Fail('layout-controls.yaml 的 %s 段缺少旧判断条目：%s'
+                       % (key, ', '.join(sorted(missing_entries))))
+    base = [block for block in layouts if block[0] not in LAYOUT_CONTROL_KEYS]
+    return controls + base
+
+
 def unquote(s):
     s = s.strip()
     if len(s) >= 2 and s[0] == s[-1] and s[0] in '"\'':
@@ -235,11 +359,15 @@ def parse_item_list(lines):
 
 def read_manifest(path):
     blocks = split_top_blocks(open(path, encoding='utf-8').read())
-    man, assets, raw = {}, [], {}
+    man, assets, asset_vision_groups, asset_decisions, raw = {}, [], [], [], {}
     derived = []
     for key, inline, lines in blocks:
         if key == 'assets':
             assets = parse_item_list(lines)
+        elif key == 'asset_vision_groups':
+            asset_vision_groups = parse_item_list(lines)
+        elif key == 'asset_decisions':
+            asset_decisions = parse_item_list(lines)
         elif key == 'derived':
             derived = parse_item_list(lines)
         elif inline.startswith('['):
@@ -253,11 +381,102 @@ def read_manifest(path):
             # 不把作者的折行改成一条长行。
             raw[key] = (inline, lines)
     man['assets'] = assets
+    man['asset_vision_groups'] = asset_vision_groups
+    man['asset_decisions'] = asset_decisions
     man['derived'] = derived
     man['_raw'] = raw
     return man
 
 
+def validate_asset_vision_groups(lout, manifest):
+    """新草案的候选索引存在时，视觉判断必须逐项覆盖且不改写实例事实。"""
+    index_path = os.path.join(lout, 'asset-vision-groups.json')
+    if not os.path.exists(index_path):
+        return {}
+    try:
+        with open(index_path, encoding='utf-8') as stream:
+            index = json.load(stream)
+    except (OSError, ValueError) as exc:
+        raise Fail('asset-vision-groups.json 无法读取：%s' % exc)
+    if 'selected' not in index:
+        raise Fail('asset-vision-groups.json 缺少 selected 候选列表')
+
+    expected = {}
+    for group in index.get('selected') or []:
+        for candidate in group.get('candidates') or []:
+            candidate_id = unquote(str(candidate.get('id') or ''))
+            source = unquote(str(candidate.get('source_media') or candidate.get('file') or ''))
+            placements = candidate.get('placements') or []
+            placement = placements[0] if placements else {}
+            raw_box = placement.get('box')
+            box = tuple(raw_box) if isinstance(raw_box, list) and len(raw_box) == 4 else None
+            layout = unquote(str(candidate.get('layout') or placement.get('archetype') or ''))
+            if not candidate_id or not source or box is None:
+                raise Fail('asset-vision-groups.json 的候选缺少 id、source_media 或 box')
+            if candidate_id in expected:
+                raise Fail('asset-vision-groups.json 的候选 id 重复：%s' % candidate_id)
+            expected[candidate_id] = (source, layout or None, box)
+
+    actual = {}
+    for item in manifest.get('asset_vision_groups') or []:
+        candidate_id = unquote(item.get('id') or '')
+        sources = source_media_list(item.get('source_media') or '')
+        layout, box = decision_scope(item, 'asset_vision_groups.%s' % candidate_id)
+        if not candidate_id:
+            raise Fail('asset_vision_groups 必须逐项填写 id')
+        if candidate_id in actual:
+            raise Fail('asset_vision_groups 的候选 id 重复：%s' % candidate_id)
+        actual[candidate_id] = (sources, layout, box)
+
+    expected_ids = set(expected)
+    actual_ids = set(actual)
+    instance_format = index.get('version', 1) >= 2
+    if instance_format:
+        missing = sorted(expected_ids - actual_ids)
+        extra = sorted(actual_ids - expected_ids)
+        if missing or extra:
+            problems = []
+            if missing:
+                problems.append('缺少：%s' % ', '.join(missing))
+            if extra:
+                problems.append('出现未知项：%s' % ', '.join(extra))
+            raise Fail('asset_vision_groups 必须逐项保留抽取候选，%s'
+                       % '；'.join(problems))
+        for candidate_id, expected_scope in expected.items():
+            sources, layout, box = actual[candidate_id]
+            expected_source, expected_layout, expected_box = expected_scope
+            if sources != [expected_source] or box != expected_box:
+                raise Fail('asset_vision_groups.%s 改写了抽取候选的图片或位置'
+                           % candidate_id)
+            if layout and expected_layout and layout != expected_layout:
+                raise Fail('asset_vision_groups.%s 改写了抽取候选的页型'
+                           % candidate_id)
+        return expected
+
+    # 旧草案用视觉组 id 和 source_media 列表表达默认判断，无法逐实例比对。
+    # 保留这种兼容输入，但仍要求每个选中的候选来源至少被一个组覆盖。
+    actual_sources = {
+        source for sources, _, _ in actual.values() for source in sources
+    }
+    missing_sources = sorted({
+        source for source, _, _ in expected.values()
+    } - actual_sources)
+    if missing_sources:
+        raise Fail('asset_vision_groups 必须覆盖抽取候选来源，缺少：%s'
+                   % ', '.join(missing_sources))
+    return {}
+
+
+def bind_asset_vision_group_scopes(lout, manifest):
+    """用 v2 候选 id 恢复实例页型，模型无需重复填写 layout。"""
+    expected = validate_asset_vision_groups(lout, manifest)
+    for item in manifest.get('asset_vision_groups') or []:
+        candidate_id = unquote(item.get('id') or '')
+        scope = expected.get(candidate_id)
+        if scope and scope[1]:
+            item['_resolved_layout'] = scope[1]
+
+
 # ------------------------------------------------------------------- 组装
 def yaml_scalar(v):
     """标量回写。已带引号 / 流式结构原样；含 YAML 危险序列才补引号。"""
@@ -291,6 +510,284 @@ def strip_kind_prefix(aid, kind):
     return aid
 
 
+def source_media_list(value):
+    """`source_media: one.png` 与视觉组的 `[a.png, b.png]` 两种写法都接受。"""
+    raw = value.strip()
+    parsed = parse_flow_list(raw)
+    return parsed if parsed is not None else [unquote(raw)] if raw else []
+
+
+def visual_kind_decision(value, label):
+    visual_kind = unquote(value or '')
+    if visual_kind not in ASSET_VISUAL_KINDS:
+        raise Fail('%s 的 visual_kind 只能是 %s'
+                   % (label, '|'.join(sorted(ASSET_VISUAL_KINDS))))
+    return VISUAL_KIND_TO_DECISION[visual_kind]
+
+
+def slot_box(line):
+    match = re.search(r'\bbox:\s*\[([^\]]+)\]', line)
+    return parse_box_match(match)
+
+
+def source_box(line):
+    match = re.search(r'\bsource_box:\s*\[([^\]]+)\]', line)
+    return parse_box_match(match)
+
+
+def parse_box_match(match):
+    if not match:
+        return None
+    try:
+        values = tuple(int(float(part.strip())) for part in match.group(1).split(','))
+    except ValueError:
+        return None
+    return values if len(values) == 4 else None
+
+
+def decision_scope(item, label):
+    raw_box = item.get('box')
+    box = slot_box('box: %s' % raw_box) if raw_box else None
+    if raw_box and box is None:
+        raise Fail('%s 的 box 必须是四个数的 [x, y, w, h]' % label)
+    layout = unquote(item.get('_resolved_layout') or item.get('layout') or '')
+    if layout and box is None:
+        raise Fail('%s 的 layout 必须与 box 一起填写' % label)
+    return layout or None, box
+
+
+def register_asset_decision(decisions, visual_kinds, key, decision, visual_kind):
+    """合并相同实例的重复判断；显式 visual_kind 必须逐字一致。"""
+    if key not in decisions:
+        decisions[key] = decision
+        visual_kinds[key] = visual_kind
+        return
+    previous_kind = visual_kinds[key]
+    if ((previous_kind and visual_kind and previous_kind != visual_kind)
+            or (not previous_kind or not visual_kind)
+            and decisions[key] != decision):
+        label = 'source_media' if key[2] is None else '实例'
+        raise Fail('图片判断的 %s判断冲突: %s' % (label, key[0]))
+
+
+def register_asset_role(roles, background_roles, source, layout, box, decision, role):
+    if not role:
+        return
+    if source in roles and roles[source] != role:
+        raise Fail('图片判断的 source_media role 冲突: %s' % source)
+    roles[source] = role
+    if decision != 'background' or box is None:
+        return
+    for (known_layout, known_box), (known_source, known_role) in background_roles.items():
+        if (known_box == box
+                and (known_layout == layout
+                     or known_layout is None
+                     or layout is None)
+                and known_role != role):
+            raise Fail('图片判断的背景实例 role 冲突: %s、%s'
+                       % (known_source, source))
+    background_roles[(layout, box)] = (source, role)
+
+
+def decision_overrides(manifest):
+    """把视觉组默认值与单图/单页型实例覆盖展开为按 source_media 的内部决定。"""
+    scoped, visual_kinds, roles, background_roles = {}, {}, {}, {}
+    for group in manifest.get('asset_vision_groups') or []:
+        group_id = unquote(group.get('id') or '')
+        sources = source_media_list(group.get('source_media') or '')
+        if not group_id or not sources:
+            raise Fail('asset_vision_groups 必须逐项填写 id 与 source_media')
+        visual_kind = unquote(group.get('visual_kind') or '')
+        decision = visual_kind_decision(visual_kind,
+                                        'asset_vision_groups.%s' % group_id)
+        layout, box = decision_scope(
+            group, 'asset_vision_groups.%s' % group_id)
+        if box is not None and len(sources) != 1:
+            raise Fail('asset_vision_groups.%s 的实例判断只能填写一个 source_media'
+                       % group_id)
+        role = unquote(group.get('role') or '')
+        for source in sources:
+            key = (source, layout, box)
+            register_asset_decision(scoped, visual_kinds, key, decision, visual_kind)
+            register_asset_role(
+                roles, background_roles, source, layout, box, decision, role)
+
+    explicit_defaults, explicit_default_kinds = {}, {}
+    explicit_overrides, explicit_override_kinds = {}, {}
+    explicit_roles = {}
+    for item in manifest.get('asset_decisions') or []:
+        source = unquote(item.get('source_media') or '')
+        visual_kind = item.get('visual_kind')
+        legacy = item.get('decision')
+        if not source or (visual_kind and legacy):
+            raise Fail('asset_decisions 每项只填 source_media 和 visual_kind（或旧 decision）')
+        if visual_kind:
+            decision = visual_kind_decision(visual_kind, 'asset_decisions.%s' % source)
+        else:
+            decision = unquote(legacy or '')
+            if decision not in LEGACY_ASSET_DECISIONS:
+                raise Fail('asset_decisions 的旧 decision 只能是 %s'
+                           % '|'.join(sorted(LEGACY_ASSET_DECISIONS)))
+        layout, box = decision_scope(item, 'asset_decisions.%s' % source)
+        target = (explicit_defaults, explicit_default_kinds) if box is None else (
+            explicit_overrides, explicit_override_kinds)
+        register_asset_decision(
+            target[0], target[1], (source, layout, box), decision,
+            unquote(visual_kind) if visual_kind else None)
+        role = unquote(item.get('role') or '')
+        register_asset_role(
+            explicit_roles, background_roles, source, layout, box, decision, role)
+
+    scoped.update(explicit_defaults)
+    scoped.update(explicit_overrides)
+    for source, role in explicit_roles.items():
+        if source in roles and roles[source] != role:
+            raise Fail('图片判断的 source_media role 冲突: %s' % source)
+        roles[source] = role
+
+    defaults = {
+        source: decision
+        for (source, _, box), decision in scoped.items()
+        if box is None
+    }
+    overrides = {
+        (source, layout, box): decision
+        for (source, layout, box), decision in scoped.items()
+        if box is not None
+    }
+    return AssetDecisions(
+        defaults, overrides, roles,
+        {source for source, _, _ in explicit_defaults},
+        set(explicit_overrides),
+    )
+
+
+def reusable_decisions_for_source(source, decisions):
+    """无布局槽位时，收集该源图所有可能落盘的可复用用途。"""
+    reusable = {'background', 'texture', 'logo', 'icon', 'slogan'}
+    default = decisions.get(source)
+    overrides = {
+        decision for (override_source, layout, box), decision in decisions.overrides.items()
+        if override_source == source
+        and decision in reusable
+        and (source not in decisions.default_overrides
+             or (override_source, layout, box) in decisions.explicit_overrides)
+    }
+    return overrides | ({default} if default in reusable else set())
+
+
+def reusable_decisions_for_slots(source, decisions, source_slots=None):
+    """按实际图片槽的最终决定保留资产，可让同图在不同实例按用途绑定。"""
+    reusable = {'background', 'texture', 'logo', 'icon', 'slogan'}
+    slots = (source_slots or {}).get(source)
+    if slots is None:
+        return reusable_decisions_for_source(source, decisions)
+    return {
+        decisions.for_scope(source, layout_name, box)
+        for layout_name, box in slots
+    } & reusable
+
+
+def validate_instance_decisions(decisions, bound_slots):
+    """实例判断必须指向已有图片槽，避免 layout 拼错后静默退化为通用图片。"""
+    if bound_slots is None:
+        return
+    for source, layout_name, box in decisions.overrides:
+        slots = bound_slots.get(source) or set()
+        matches = ((layout_name, box) in slots if layout_name is not None
+                   else any(slot_box == box for _, slot_box in slots))
+        if not matches:
+            raise Fail('图片判断的实例没有对应图片槽: %s' % source)
+
+
+def apply_asset_decisions(manifest, bound_sources=None, bound_slots=None):
+    """把抽取期图片判断并入正式 assets；内容图与噪声不进入消费产物。"""
+    decisions = decision_overrides(manifest)
+    if bound_sources is not None:
+        declared = set(decisions)
+        declared |= {source for source, _, _ in decisions.overrides}
+        unbound = sorted(declared - set(bound_sources))
+        if unbound:
+            raise Fail('图片判断中这些图片没有对应图片槽：%s'
+                       % '、'.join(unbound))
+    validate_instance_decisions(decisions, bound_slots)
+
+    assets = []
+    by_source_kind = {}
+    serial = Counter()
+    used_ids = {unquote(item.get('id') or '')
+                for item in manifest.get('assets') or [] if item.get('id')}
+    decision_sources = list(decisions)
+    for source, _, _ in decisions.overrides:
+        if source not in decision_sources:
+            decision_sources.append(source)
+    desired_kinds = {
+        source: reusable_decisions_for_slots(source, decisions, bound_slots)
+        for source in decision_sources
+    }
+    emitted = set()
+
+    def next_asset_id(kind):
+        serial[kind] += 1
+        aid = '%s-%d' % (KIND_PREFIX[kind], serial[kind])
+        while aid in used_ids:
+            serial[kind] += 1
+            aid = '%s-%d' % (KIND_PREFIX[kind], serial[kind])
+        used_ids.add(aid)
+        return aid
+
+    def append_asset(item, source, decision):
+        old_kind = unquote(item.get('kind') or '')
+        pair = (source, decision if source in decision_sources else old_kind)
+        if source and pair in emitted:
+            return
+        row = dict(item)
+        if decision and decision != old_kind:
+            row['kind'] = decision
+            row['id'] = next_asset_id(decision)
+            for field in ('role', 'theme', 'on-bg', 'mark'):
+                row.pop(field, None)
+        if decision == 'background':
+            row['role'] = decisions.roles.get(source) or 'content'
+        if source:
+            emitted.add(pair)
+            by_source_kind[(source, row['kind'])] = row
+        used_ids.add(unquote(row.get('id') or ''))
+        assets.append(row)
+
+    for item in manifest.get('assets') or []:
+        source = unquote(item.get('source_media') or '')
+        if source in decision_sources:
+            for decision in sorted(desired_kinds[source]):
+                append_asset(item, source, decision)
+        else:
+            append_asset(item, source, None)
+
+    for source in decision_sources:
+        for decision in sorted(desired_kinds[source]):
+            if (source, decision) in emitted:
+                continue
+            append_asset({
+                'id': next_asset_id(decision),
+                'source_media': source,
+                'kind': decision,
+            }, source, decision)
+    manifest['assets'] = assets
+    source_kinds = defaultdict(set)
+    for source, kind in by_source_kind:
+        source_kinds[source].add(kind)
+    defaults = {
+        source: unquote(by_source_kind[(source, next(iter(kinds)))]['id'])
+        for source, kinds in source_kinds.items()
+        if len(kinds) == 1
+    }
+    scoped = {
+        (source, kind): unquote(item['id'])
+        for (source, kind), item in by_source_kind.items()
+    }
+    return decisions, AssetIds(defaults, scoped)
+
+
 def media_row_of(extract, source_media):
     for m in extract.get('media') or []:
         if m.get('out') and os.path.basename(m['out']) == source_media:
@@ -475,6 +972,16 @@ def expand_placeholders(body, manifest, consumer, audit, extract, layouts_text):
                 f += '（原图 `%s`）' % e['full']
             rows.append('| `%s` | %s | %s |' % (aid, f, when))
         body = body.replace('{{ASSET_TABLE}}', '\n'.join(rows))
+    if '{{LOGO_RULES}}' in body:
+        rows = []
+        for aid, entry in consumer.items():
+            if entry.get('kind') != 'logo':
+                continue
+            owners = _archetypes_using(layouts_text, aid)
+            rows.append('- `%s` 只出现在这些页型上：%s；其余页型不放。位置取该页型 '
+                        '`slots` 里 `role: logo` 那一项的 `box`，原样使用该文件、保持原比例。'
+                        % (aid, '、'.join('`%s`' % owner for owner in owners) or '（无）'))
+        body = body.replace('{{LOGO_RULES}}', '\n'.join(rows))
     if '{{LAYOUT_LIST}}' in body:
         rows, sect, names = [], None, {}
         for line in (layouts_text or '').split('\n'):
@@ -946,6 +1453,7 @@ def text_role_boxes(lines):
 
 def select_layout_forms(lines, modes):
     """按 `layout_modes` 只保留每个页型选中的 flow 或 slots。"""
+    forms = layout_forms(lines)
     out, layout, drop = [], None, False
     for line in lines:
         layout_match = re.match(r'^  ([\w-]+):\s*$', line)
@@ -953,7 +1461,10 @@ def select_layout_forms(lines, modes):
         if layout_match:
             layout, drop = layout_match.group(1), False
         elif form_match:
-            drop = modes.get(layout) not in (None, form_match.group(1))
+            selected = modes.get(layout)
+            if selected is None and len(forms.get(layout) or ()) >= 2:
+                selected = 'slots'
+            drop = selected is not None and selected != form_match.group(1)
         elif drop and re.match(r'^    \S', line):
             drop = False
         if not drop:
@@ -1013,7 +1524,58 @@ def shrink_safe_area(lines):
     return lines, None
 
 
-def build_layouts_md(layouts_blocks, canvas):
+def resolve_asset_candidate_lines(lines, decisions, asset_ids):
+    """把 source_media 临时字段转成资产引用；内容图保留通用 pic 槽。"""
+    out = []
+    content_slots = set()
+    layout_name, layout_form = None, None
+    for line in lines:
+        layout_match = re.match(r'^  ([\w-]+):\s*$', line)
+        form_match = re.match(r'^    (flow|slots):\s*$', line)
+        if layout_match:
+            layout_name, layout_form = layout_match.group(1), None
+        elif form_match:
+            layout_form = form_match.group(1)
+        match = re.search(r'\bsource_media:\s*([^,}]+)', line)
+        if not match:
+            out.append(line)
+            continue
+        source = unquote(match.group(1).strip())
+        candidate_box = source_box(line) or slot_box(line)
+        decision = (decisions.for_slot(source, line, layout_name)
+                    if isinstance(decisions, AssetDecisions)
+                    else decisions.get(source))
+        line = re.sub(r'\s*,?\s*source_media:\s*[^,}]+', '', line, count=1)
+        line = re.sub(r'\s*,?\s*source_box:\s*\[[^\]]+\]', '', line, count=1)
+        # 预算裁掉、没有进入视觉组的素材不凭空判成风格资产；保留原位置通用图片槽，
+        # 让生成侧可放这一页的内容图。`omit` 是页码/水印等纯噪声，直接去掉槽。
+        if decision == 'omit':
+            continue
+        if decision in (None, 'content'):
+            line = re.sub(r'\s*,?\s*asset:\s*[^,}]+', '', line, count=1)
+            line = re.sub(r'(\brole:\s*)[\w-]+', r'\g<1>pic', line, count=1)
+            # 内容图不进风格资产，但同一位置只能留一个通用图片槽。不同图片源在同一
+            # box 的叠加是原 PPT 的内容选择，不应被转换成两个生成时必然重叠的 pic 槽。
+            content_key = (layout_name, layout_form, candidate_box or line.strip())
+            if content_key in content_slots:
+                continue
+            content_slots.add(content_key)
+            out.append(line)
+            continue
+        aid = (asset_ids.for_decision(source, decision)
+               if isinstance(asset_ids, AssetIds) else asset_ids.get(source))
+        if not aid:
+            raise Fail('layouts.yaml 引用了未完成资产判断的 source_media: %s' % source)
+        if re.search(r'\basset:\s*[^,}]+', line):
+            line = re.sub(r'(\basset:\s*)[^,}]+', r'\g<1>%s' % aid, line, count=1)
+        else:
+            line = line.replace('}', ', asset: %s}' % aid, 1)
+        line = re.sub(r'(\brole:\s*)[\w-]+', r'\g<1>%s' % decision, line, count=1)
+        out.append(line)
+    return out
+
+
+def build_layouts_md(layouts_blocks, canvas, asset_decisions=None, asset_ids=None):
     blocks = {k: (inline, lines) for k, inline, lines in layouts_blocks}
     if 'canvas' in blocks:
         raise Fail('layouts.yaml 不要写 canvas —— 脚本从 extract.json 取')
@@ -1061,13 +1623,18 @@ def build_layouts_md(layouts_blocks, canvas):
             out.append('  %s:' % bg)
             out += lines
     modes = layout_modes(blocks.get('layout_modes', ('', []))[1])
+    decided_layout_roles = set(roles)
     out.append('layouts:')
     pending_text_role = None
     used_text_roles = set()
-    source_layout_lines = blocks['layouts'][1]
+    decisions = asset_decisions if asset_decisions is not None else {}
+    resolved_asset_ids = asset_ids if asset_ids is not None else {}
+    source_layout_lines = resolve_asset_candidate_lines(
+        blocks['layouts'][1], decisions, resolved_asset_ids)
     role_boxes = text_role_boxes(source_layout_lines)
     layout_lines = select_layout_forms(source_layout_lines, modes)
     cur, fixed_items = None, []
+    emitted_roles = set()
 
     def flush_fixed_items():
         if not fixed_items:
@@ -1084,6 +1651,10 @@ def build_layouts_md(layouts_blocks, canvas):
             cur = m.group(1)
         elif fixed_items and re.match(r'^    \S', line):
             flush_fixed_items()
+        if cur in decided_layout_roles and re.match(r'^    role:\s*', line):
+            # 页型草案中的 role 只是初始值；最终语义只由扁平 roles 判断单决定。
+            # 否则两者同时写入会产生重复 YAML 键，并让后面的草案默认值覆盖模型判断。
+            continue
         # 判断单里的结构事实（栅格、间距序列、样张字数、命中配方）是给 L 层判断用的，
         # 不进产物——消费端要的是结论，不是推导过程。layout_mode 同理，它是判断的载体。
         if line.lstrip().startswith('#'):
@@ -1092,34 +1663,38 @@ def build_layouts_md(layouts_blocks, canvas):
                 pending_text_role = marker.group(1)
             continue
         if pending_text_role:
-            if pending_text_role not in text_roles:
-                raise Fail('text_roles 缺少 %s 的判断' % pending_text_role)
-            role = text_roles[pending_text_role]
-            slot_type = role if role in ('title', 'subtitle', 'header', 'footer') else 'body'
-            line, role_n = re.subn(r'(\{\s*role:\s*)[\w-]+',
-                                   r'\g<1>%s' % role, line, count=1)
-            line, type_n = re.subn(r'(\btype:\s*)[\w-]+',
-                                   r'\g<1>%s' % slot_type, line, count=1)
-            if role_n != 1 or type_n != 1:
-                raise Fail('text_roles.%s 没有命中一个文本槽' % pending_text_role)
-            if (modes.get(cur) == 'flow' and role in ('header', 'footer')
-                    and re.match(r'^\s{12}-\s*\{', line) and 'box:' not in line):
-                box = role_boxes.get(pending_text_role)
-                if not box:
-                    raise Fail('text_roles.%s 识别为 %s，但 slots 中没有坐标'
-                               % (pending_text_role, role))
-                line = re.sub(r',\s*type:', ', box: %s, type:' % box, line, count=1)
-                fixed_items.append(line)
+            role = text_roles.get(pending_text_role)
+            if role:
+                # header 是语义角色，V2 没有同名的渲染 slot type；保留 role 供消费端
+                # 识别固定页眉，同时用 body 通过 V2 的类型枚举。
+                slot_type = role if role in ('title', 'subtitle', 'footer') else 'body'
+                line, role_n = re.subn(r'(\{\s*role:\s*)[\w-]+',
+                                       r'\g<1>%s' % role, line, count=1)
+                line, type_n = re.subn(r'(\btype:\s*)[\w-]+',
+                                       r'\g<1>%s' % slot_type, line, count=1)
+                if role_n != 1 or type_n != 1:
+                    raise Fail('text_roles.%s 没有命中一个文本槽' % pending_text_role)
+                if (modes.get(cur) == 'flow' and role in ('header', 'footer')
+                        and re.match(r'^\s{12}-\s*\{', line) and 'box:' not in line):
+                    box = role_boxes.get(pending_text_role)
+                    if not box:
+                        raise Fail('text_roles.%s 识别为 %s，但 slots 中没有坐标'
+                                   % (pending_text_role, role))
+                    line = re.sub(r',\s*type:', ', box: %s, type:' % box, line, count=1)
+                    fixed_items.append(line)
+                    used_text_roles.add(pending_text_role)
+                    pending_text_role = None
+                    continue
                 used_text_roles.add(pending_text_role)
-                pending_text_role = None
-                continue
-            used_text_roles.add(pending_text_role)
             pending_text_role = None
         out.append(line)
+        if cur and re.match(r'^    role:\s*', line):
+            emitted_roles.add(cur)
         if m and m.group(1) in names:
             out.append('    name: "%s"' % names.pop(m.group(1)))
         if m and m.group(1) in roles:
             out.append('    role: %s' % roles.pop(m.group(1)))
+            emitted_roles.add(m.group(1))
     flush_fixed_items()
     if names:
         raise Fail('names 里这些页型在 layouts 下找不到：%s' % ', '.join(sorted(names)))
@@ -1129,13 +1704,14 @@ def build_layouts_md(layouts_blocks, canvas):
     if unused_text_roles:
         raise Fail('text_roles 里这些判断没有命中文本槽：%s'
                    % ', '.join(sorted(unused_text_roles)))
-    missing_role = [k for k in re.findall(r'^  ([\w-]+):\s*$', '\n'.join(blocks['layouts'][1]), re.M)
-                    if not re.search(r'^  %s:\s*$(?:\n(?!  \S).*)*?\n    role:' % re.escape(k),
-                                     '\n'.join(out), re.M)]
+    missing_role = [
+        k for k in re.findall(r'^  ([\w-]+):\s*$', '\n'.join(blocks['layouts'][1]), re.M)
+        if k not in emitted_roles
+    ]
     if missing_role:
         raise Fail('这些页型没有 role（在 layouts.yaml 的 roles 段填）：%s' % ', '.join(missing_role))
-    # `layout_modes.*: TODO` 由上面那道通用 TODO 扫描报（它连行内提示一起打出来），
-    # 这里只管它管不到的两种：整行被删、以及填了 flow/slots 之外的值。
+    # 未声明 layout_modes 时默认 slots：固定坐标是从原 PPT 直接普查的安全交付形态。
+    # 模型只在看样张确认内容需要随高度重排时显式改为 flow。
     forms = layout_forms(blocks['layouts'][1])
     bad = []
     for k, v in sorted(modes.items()):
@@ -1145,9 +1721,6 @@ def build_layouts_md(layouts_blocks, canvas):
             bad.append('%s 的 layout_modes 判断是 %r' % (k, v))
         elif v not in forms[k]:
             bad.append('%s 选了 %s 但该页型没有这一份' % (k, v))
-    for k, forms_for_layout in sorted(forms.items()):
-        if len(forms_for_layout) >= 2 and k not in modes:
-            bad.append('%s 缺 layout_modes 判断' % k)
     if bad:
         raise Fail('layout_modes 只能填 flow 或 slots，一个页型一个词：%s' % '；'.join(bad))
     declared = set(re.findall(r'^    background:\s*(\S+)\s*$',
@@ -1200,7 +1773,13 @@ def main(argv=None):
         raise Fail('%s 非空；加 --force 覆盖' % pack)
 
     left = []
-    for f in ('manifest.yaml', 'frontmatter.yaml', 'layouts.yaml', 'body.md'):
+    control_path = os.path.join(lout, 'layout-controls.yaml')
+    draft_files = ['manifest.yaml', 'frontmatter.yaml', 'body.md']
+    # 新草案的可编辑判断已移到小型控制文件；layouts.yaml 中保留的旧控制区只是
+    # 兼容坐标事实，仍含 TODO 也不会进入最终 layouts.md。
+    draft_files.append('layout-controls.yaml' if os.path.exists(control_path)
+                       else 'layouts.yaml')
+    for f in draft_files:
         p = os.path.join(lout, f)
         if not os.path.exists(p):
             continue
@@ -1218,6 +1797,7 @@ def main(argv=None):
                    % len(re.sub(r'\s+', '', mdesc.group(1))))
 
     manifest = read_manifest(os.path.join(lout, 'manifest.yaml'))
+    bind_asset_vision_group_scopes(lout, manifest)
     if args.style_name:
         manifest['name'] = args.style_name
     if not manifest.get('name'):
@@ -1229,15 +1809,37 @@ def main(argv=None):
     l_fm = split_top_blocks(open(os.path.join(lout, 'frontmatter.yaml'),
                                  encoding='utf-8').read())
     body = open(os.path.join(lout, 'body.md'), encoding='utf-8').read()
-    lay_path = os.path.join(lout, 'layouts.yaml')
-    layouts_blocks = (split_top_blocks(open(lay_path, encoding='utf-8').read())
-                      if os.path.exists(lay_path) else None)
+    layouts_blocks = load_layout_blocks(lout)
+    bound_sources, bound_slots = set(), defaultdict(set)
+    if layouts_blocks is not None:
+        for key, _, lines in layouts_blocks:
+            layout_name = None
+            for line in lines:
+                layout_match = re.match(r'^  ([\w-]+):\s*$', line)
+                if layout_match:
+                    layout_name = layout_match.group(1)
+                match = re.search(r'\bsource_media:\s*([^,}]+)', line)
+                if match:
+                    source = unquote(match.group(1).strip())
+                    bound_sources.add(source)
+                    box = source_box(line) or slot_box(line)
+                    if key == 'layouts' and box is not None:
+                        bound_slots[source].add((layout_name, box))
+    has_asset_judgments = bool(
+        manifest.get('asset_vision_groups') or manifest.get('asset_decisions'))
+    asset_decisions, asset_ids = apply_asset_decisions(
+        manifest,
+        bound_sources=bound_sources if has_asset_judgments else None,
+        bound_slots=bound_slots if has_asset_judgments else None)
     canvas = extract['canvas']['px']
+    final_layouts = (build_layouts_md(
+        layouts_blocks, canvas, asset_decisions=asset_decisions, asset_ids=asset_ids)
+        if layouts_blocks is not None else None)
 
     os.makedirs(pack, exist_ok=True)
     consumer, audit, copied = place_assets(manifest, extract, stage1, pack)
 
-    lay_text = open(lay_path, encoding='utf-8').read() if os.path.exists(lay_path) else ''
+    lay_text = final_layouts or ''
     body = expand_placeholders(body, manifest, consumer, audit, extract, lay_text)
     design = build_design(manifest, l_fm, consumer, body,
                           has_sidecar=layouts_blocks is not None, canvas=canvas)
@@ -1245,7 +1847,7 @@ def main(argv=None):
         f.write(design)
     if layouts_blocks is not None:
         with open(os.path.join(pack, 'layouts.md'), 'w', encoding='utf-8') as f:
-            f.write(build_layouts_md(layouts_blocks, canvas))
+            f.write(final_layouts)
 
     # 审计记录写回**抽取工作目录**，不进交付包：包是消费产物，`ref/` 里的东西
     # 没有任何门禁读、消费模型也用不上，放进去只会让「别读我」和「几 MB 材料」同时下发。
@@ -1336,6 +1938,7 @@ def main(argv=None):
         rc = rc or r1.returncode
     if rc:
         print('\n门禁未过（exit %d）。回修属 L 层的事：改判断单后重跑本脚本。' % rc)
+        return rc
     return rc