@lark-apaas/coding-steering 0.1.32-beta.0 → 0.1.32-dev.4f80f68

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

@@ -38,7 +38,7 @@ L 层判断单 schema（<l-out-dir> 四个文件，这段就是填写说明书
     assets:                           # 可选；无资产包可整段省略
       - id: bg-cover                  # 必填。命名规则 <kind 前缀>-<语义名>，
                                       #   logo- / slogan- / bg- / texture- / icon-
-        source_media: image-1-1.jpeg  # media-out/ 里的**原图**文件名（不是压缩版）
+        source_media: <原图文件名>     # media-out/ 里的**原图**文件名（不是压缩版）
         kind: background              # logo|slogan|background|texture|icon
         role: cover                   # background/icon 用；封闭枚举见规范 §2
         theme: dark                   # 双主题包按需
@@ -80,9 +80,9 @@ L 层判断单 schema（<l-out-dir> 四个文件，这段就是填写说明书
 
     colors:
       surface: "#FFFFFF"
-      primary: "#2D5A8E"
+      primary: "#RRGGBB"
     safe-area:
-      content: {top: 60, right: 90, bottom: 113, left: 90, applies-to: [content]}
+      content: {top: <px>, right: <px>, bottom: <px>, left: <px>, applies-to: [content]}
       confidence: medium
 
 --------------------------------------------------------------------------------
@@ -98,7 +98,8 @@ L 层判断单 schema（<l-out-dir> 四个文件，这段就是填写说明书
         role: cover
         background: bg-cover
         slots:
-          - {role: title, box: [257, 313, 1406, 130], type: title}
+          - {role: title, box: [<x>, <y>, <w>, <h>], type: title,
+             css: "<由源模板转译出的 CSS 声明串>"}
         confidence: high
 
   可选 `body:` 块标量 —— 追加到 layouts.md frontmatter 之后作为说明正文。
@@ -139,9 +140,11 @@ 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'}
-# stage1 ref/ 里随包分发的审计件（其余如 shapes.json 体量大、不进包）
-REF_CARRY = ('color-freq-raw.json', 'font-clusters.json', 's5-acceptance.json',
-             'content-clusters.json', 'notes.md')
+# 交付包的 ref/ 只留 audit.yaml（人复核数值出处用，几 KB）。
+# 频次原表、聚类原始数据、extract.json、重建图、logo 候选图全部留在 stage1 抽取目录，
+# 不拷进包——规范原本指望「下发时链路剥离」，但链路上没有环节真的剥离，结果
+# 审计材料带着「别读我」一起进消费上下文，还占掉包体的大头。
+REF_CARRY = ()
 
 
 class Fail(SystemExit):
@@ -272,6 +275,10 @@ def truthy(v):
     return str(v).strip().lower() in ('1', 'true', 'yes', 'on')
 
 
+# 浏览器能解码的图片格式。落进包的资产必须在此列，否则消费端引用到就是一张空白图。
+WEB_SAFE_EXT = {'png', 'jpg', 'jpeg', 'webp', 'gif', 'svg', 'avif'}
+
+
 def asset_ext(name):
     return name.rsplit('.', 1)[-1].lower() if '.' in name else ''
 
@@ -351,12 +358,25 @@ def place_assets(manifest, extract, stage1, pack):
                 entry['path'] = 'assets/%ss/%s.%s' % (kind, base, cext)
                 if truthy(a.get('use_full')):
                     oext = asset_ext(row['out'])
-                    fdst = os.path.join(sub, '%s@full.%s' % (base, oext))
-                    shutil.copy2(orig_path, fdst)
-                    copied.append(fdst)
-                    entry['full'] = 'assets/%ss/%s@full.%s' % (kind, base, oext)
+                    if oext.lower() in WEB_SAFE_EXT:
+                        fdst = os.path.join(sub, '%s@full.%s' % (base, oext))
+                        shutil.copy2(orig_path, fdst)
+                        copied.append(fdst)
+                        entry['full'] = 'assets/%ss/%s@full.%s' % (kind, base, oext)
+                    else:
+                        # 原图是浏览器不解码的格式（tiff/bmp 之类）。落进包并在 design.md
+                        # 里声明成可用资源，消费端引用它就是一张空白图——实测踩过一次，
+                        # 封面与结束页因此空白。压缩版已经带着全部像素，full 不给。
+                        print('  ⚠ %s 的原图是 .%s，浏览器不解码，只给压缩版' % (aid, oext))
             else:
                 oext = asset_ext(row['out'])
+                if oext.lower() not in WEB_SAFE_EXT:
+                    # 转码两条路（Pillow / sips）都没成，原图又是浏览器不解码的格式。
+                    # 照落进去就是把一张永远显示不出来的图当资产下发——实测封面因此空白。
+                    raise Fail('%s: 原图是 .%s，浏览器不解码，而转码没有产物'
+                               '（extract.json 里看 transcode_blocked 的原因）。'
+                               '装上 Pillow 重跑抽取，或把这条资产从 manifest 删掉'
+                               '并在 gaps 写明。' % (aid, oext))
                 dst = os.path.join(sub, '%s.%s' % (base, oext))
                 shutil.copy2(orig_path, dst)
                 copied.append(dst)
@@ -382,7 +402,7 @@ def place_assets(manifest, extract, stage1, pack):
                 if boxes:
                     au['boxes'] = boxes
                     # aspect 取**未取整**的 box —— 从取整后的整数反算会明显偏
-                    # （volcano logo 224.1/47.8=4.688，用 224/48 算成 4.667）。
+                    # 先取整再相除，误差会落到小数点后两位，logo 这种细长框尤其明显。
                     raw = clusters[0]['box']
                     if raw.get('h'):
                         au['aspect'] = round(raw['w'] / float(raw['h']), 3)
@@ -406,6 +426,27 @@ def _pages_of(extract, source_media):
     return sorted(pages)
 
 
+def _archetypes_using(layouts_text, aid, key='asset'):
+    """layouts.yaml 里哪些 archetype 引用了这个资产。
+
+    key='asset' 查 slots 里的图片槽；key='background' 查页型底图。
+    """
+    out, cur, sect = [], None, None
+    for line in (layouts_text or '').split('\n'):
+        if re.match(r'^\w[\w-]*:\s*$', line):
+            sect = line.split(':')[0]
+            continue
+        if sect != 'layouts':
+            continue
+        m = re.match(r'^  ([\w-]+):\s*$', line)
+        if m:
+            cur = m.group(1)
+            continue
+        if cur and re.search(r'%s:\s*%s\b' % (key, re.escape(aid)), line) and cur not in out:
+            out.append(cur)
+    return out
+
+
 def expand_placeholders(body, manifest, consumer, audit, extract, layouts_text):
     """body.md 里的 `{{ASSET_TABLE}}` / `{{LAYOUT_LIST}}` 由本脚本按落盘真值渲染——
     路径与页型清单是打包期才确定的事实，不该由 L 层手抄（抄错就是死链）。"""
@@ -415,18 +456,19 @@ def expand_placeholders(body, manifest, consumer, audit, extract, layouts_text):
         for aid, e in consumer.items():
             pages = _pages_of(extract, src_of.get(aid))
             box = (audit.get(aid) or {}).get('boxes') or []
-            if e['kind'] == 'background' and e.get('role') == 'cover':
-                when = '封面页整幅铺满，必用'
-            elif e['kind'] == 'background':
-                when = '内容页整幅铺满——哪个页型用哪张见 `layouts.md` 的 `background`'
-            elif box:
-                b = box[0]
-                when = '固定位 (%d, %d)，尺寸 %dx%d px' % tuple(b)
-                when += ('，全 %d 页里只出现在第 %s 页' % (extract['counts']['slides'],
-                                                    '、'.join(map(str, pages)))
-                         if pages and len(pages) <= 4 else '，每页固定放一次')
+            # 单元格保持短句：哪个页型用哪张由 `background` 字段决定，
+            # 那句说明放在表格前一次即可，逐行重复只是把同一句抄 N 遍。
+            if e['kind'] == 'background':
+                users = _archetypes_using(layouts_text, aid, key='background')
+                when = ('%s 用它' % '/'.join('`%s`' % o for o in users[:6])
+                        if users else '未被任何页型引用')
             else:
-                when = '按 `%s` 的语义使用' % e['kind']
+                # 位置逐页型不同（同一 logo 常在封面左上、内容页右上，尺寸也不同），
+                # 所以这里只给归属，坐标一律交给 layouts.md 的 slots。
+                owners = _archetypes_using(layouts_text, aid)
+                when = ('%s 这 %d 个页型带它' % ('/'.join('`%s`' % o for o in owners[:6]),
+                                              len(owners))
+                        if owners else '⚠ 没有页型声明它的位置，本包不使用它')
             f = '`%s`' % e['path'] if e.get('path') else (
                 '`%s`' % e['url'] if e.get('url') else '纯色 `%s`' % e.get('color'))
             if e.get('full'):
@@ -466,7 +508,7 @@ def render_assets_block(consumer):
 
 # ------------------------------------------------- 数值可追溯机检（抄错即 FAIL）
 HEX_RE = re.compile(r'#([0-9A-Fa-f]{6})\b')
-FONTSIZE_RE = re.compile(r'\bfontSize:\s*([\d.]+)px')
+FONTSIZE_RE = re.compile(r'\b(?:fontSize|font-size):\s*([\d.]+)px')
 BOX_RE = re.compile(r'\bbox:\s*\[\s*(-?[\d.]+)\s*,\s*(-?[\d.]+)\s*,'
                     r'\s*(-?[\d.]+)\s*,\s*(-?[\d.]+)\s*\]')
 KEYLINE_RE = re.compile(r'^(\s*)-?\s*([A-Za-z_][\w-]*):\s*(.*)$')
@@ -604,6 +646,47 @@ def _box_hit(box, idx):
                    % (best[0], best[1], best[2], best[3], best[4], bestd))
 
 
+# 判断产物：L 层看着背景图划出来的区域，本就不该命中普查值——整键豁免，
+# 不要求写 derived。逼它们走 derived 只会把整段豁免掉，机检反而更弱。
+JUDGEMENT_KEYS = frozenset(('avoid', 'text_safe', 'pairing_rule'))
+
+
+def media_integrity(stage1, extract):
+    """extract.json 记录的尺寸，必须和磁盘上那个文件真实的尺寸一致。
+
+    这条挡的是「记录全对、文件被顶替」——两个 media 的输出名撞车时，后写的覆盖先写的，
+    extract.json 里各自的记录都还是对的，任何只读记录的检查都发现不了；只有把记录和
+    文件本身对一遍才抓得到。实测某模板因此把一张 109x109 的图当成了整页背景。
+    """
+    try:
+        from PIL import Image
+    except Exception:
+        return []                      # 没有 Pillow 就量不了，跳过而不是假装通过
+    bad, seen = [], {}
+    for m in extract.get('media') or []:
+        for key, rel in (('source_px', m.get('out')),
+                         ('compressed_px', m.get('compressed_out'))):
+            rec = m.get(key)
+            if not rel or not rec:
+                continue
+            path = os.path.join(stage1, rel)
+            if not os.path.exists(path):
+                bad.append('%s 的 %s 指向 %s，文件不存在' % (m['media'], key, rel))
+                continue
+            try:
+                with Image.open(path) as im:
+                    real = list(im.size)
+            except Exception:
+                continue
+            if real != list(rec):
+                bad.append('%s 的 %s 记录 %s，但 %s 实际是 %s'
+                           % (m['media'], key, rec, rel, real))
+            if rel in seen and seen[rel] != m['media']:
+                bad.append('%s 与 %s 都写到 %s' % (seen[rel], m['media'], rel))
+            seen[rel] = m['media']
+    return bad
+
+
 def trace_check(pack, extract, shapes, derived_values, derived_tokens, factor):
     """产物里每个 hex / 字号 / slot 坐标都必须可追溯到普查值或 derived 声明。"""
     idx = build_trace_index(extract, shapes)
@@ -614,6 +697,9 @@ def trace_check(pack, extract, shapes, derived_values, derived_tokens, factor):
         if not text:
             continue
         for lineno, path, raw in _scan_keyed(text):
+            if JUDGEMENT_KEYS & set(path):
+                checked['judgement'] += 1
+                continue
             exempt_token = any(k in derived_tokens for k in path)
             for m in HEX_RE.finditer(raw):
                 val = '#' + m.group(1).upper()
@@ -762,106 +848,6 @@ def build_package_manifest(manifest, consumer, audit, extract, pack):
     return {k: v for k, v in pkg.items() if v is not None}
 
 
-def layout_fast_index(layouts_blocks, max_slots=4):
-    if not layouts_blocks:
-        return []
-    blocks = {k: (inline, lines) for k, inline, lines in layouts_blocks}
-    if 'layouts' not in blocks:
-        return []
-    items = []
-    cur = None
-    for line in blocks['layouts'][1]:
-        m = re.match(r'^  ([\w-]+):\s*$', line)
-        if m:
-            cur = {'id': m.group(1), 'name': '', 'role': '', 'background': '', 'slots': []}
-            items.append(cur)
-            continue
-        if not cur:
-            continue
-        m = re.match(r'^    (name|role|background):\s*(.+?)\s*$', line)
-        if m:
-            cur[m.group(1)] = unquote(m.group(2))
-            continue
-        m = re.match(r'^\s{6}-\s*\{(.+)\}\s*$', line)
-        if m and len(cur['slots']) < max_slots:
-            raw = m.group(1)
-            role = re.search(r'role:\s*([^,}]+)', raw)
-            box = re.search(r'box:\s*\[([^\]]+)\]', raw)
-            typ = re.search(r'type:\s*([^,}]+)', raw)
-            if role and box:
-                label = unquote(role.group(1).strip())
-                if typ:
-                    label += '/' + unquote(typ.group(1).strip())
-                cur['slots'].append('%s [%s]' % (label, box.group(1).strip()))
-    out = []
-    for item in items:
-        parts = ['`%s`' % item['id']]
-        if item.get('name'):
-            parts.append(item['name'])
-        if item.get('role'):
-            parts.append(item['role'])
-        if item.get('background'):
-            parts.append('背景 `%s`' % item['background'])
-        slots = '；'.join(item['slots'])
-        out.append('%s：%s' % (' / '.join(parts), slots or '按最接近用途套用'))
-    return out
-
-
-def render_fast_path(manifest, consumer, has_sidecar, canvas, layouts_index=None):
-    """Render the small consumer-first block that keeps runtime agents out of ref/."""
-    cover = next((aid for aid, a in consumer.items()
-                  if a.get('kind') == 'background' and a.get('role') == 'cover'), None)
-    content_bgs = [aid for aid, a in consumer.items()
-                   if a.get('kind') == 'background' and a.get('role') == 'content']
-    logos = [aid for aid, a in consumer.items() if a.get('kind') in ('logo', 'slogan')]
-    assets = []
-    for aid, a in consumer.items():
-        path = a.get('path') or a.get('color') or a.get('url')
-        role = a.get('role') or a.get('kind')
-        if path:
-            assets.append('`%s` -> `%s` (%s)' % (aid, path, role))
-    if len(assets) > 8:
-        assets = assets[:8] + ['其余资产见 frontmatter `assets`，不要去 `ref/` 里临时挑图。']
-
-    lines = [
-        '## Agent Fast Path',
-        '',
-        '消费本风格时先读这一节；它是给生成 Agent 的短路径，目标是把风格理解控制在 1 分钟内，避免把审计材料重新理解一遍。',
-        '',
-        '- **时间预算**：风格导入最多做 1 次 `read_file design.md`。本节已经内联常用坐标，读完后必须直接开始生成，不要再探索风格包。',
-        '- **只读入口**：常规生成只需要 `design.md`。只有本节的版式索引无法覆盖目标页时，才打开 %s。'
-        % ('`layouts.md`' if has_sidecar else '`design.md` 里的 `layouts`'),
-        '- **附件/zip 兜底**：如果当前内容来自 zip 附件的文本摘要，直接使用摘要中 `design.md` / `layouts.md` 的文本；不要尝试修复 zip、解析二进制、搜索附件目录或重建压缩包。',
-        '- **禁止动作**：不要读取 `ref/color-freq-raw.json`、`ref/font-clusters.json`、`ref/extract.json`、`ref/rebuild/`、`ref/rebuild/png/*`；不要 summarize / view 参考页；不要重新统计颜色、字体或版式。',
-        '- **信息来源优先级**：本节 > `## Usage` > frontmatter `assets` / `colors` / `typography` > `layouts.md`。除此之外的文件只用于人工审计，不用于生成。',
-        '- **缺信息时降级**：如果某个细节本节没有写，用 frontmatter token 和最接近的 `layouts.md` archetype 推断；不要打开审计文件补证。',
-    ]
-    if canvas:
-        lines.append('- **画布**：所有坐标按 `%dx%d` 绝对像素理解。' % tuple(canvas))
-    if cover:
-        lines.append('- **封面背景**：优先使用 `%s`；整幅铺满画布，禁止自造渐变替代。' % cover)
-    if content_bgs:
-        lines.append('- **内容页背景**：按 `layouts.md` 中 archetype 的 `background` 字段取；常用内容背景为 %s。'
-                     % '、'.join('`%s`' % x for x in content_bgs[:4]))
-    if cover or content_bgs:
-        lines.append('- **背景安全区**：背景图和版式必须配对。按 archetype 的 `background`、`text_safe`、`avoid` 一起放文字和卡片；标题、正文、关键数字、图表、卡片、时间线及其容器的外接矩形都不得压到背景视觉主体、强光斑、深色透明区上，透明容器也不能跨进禁放区。')
-    if logos:
-        lines.append('- **标识资产**：只使用 %s；不得重画、不得改比例。'
-                     % '、'.join('`%s`' % x for x in logos))
-    lines += [
-        '- **配色与字体**：颜色只取 frontmatter `colors`；字体/字号只取 frontmatter `typography`；内容主题不得引入新色相。',
-        '- **版式**：优先使用下面内联版式索引；需要更多 slot 时才读 `layouts.md`；不要用 `ref/rebuild/png` 反推坐标。',
-    ]
-    if layouts_index:
-        lines += ['', '内联版式索引（先用这里，不要为了选页型再读文件）：']
-        lines += ['- ' + x for x in layouts_index]
-    if assets:
-        lines += ['', '关键资产：']
-        lines += ['- ' + a for a in assets]
-    lines.append('')
-    return '\n'.join(lines) + '\n'
-
-
 def strip_agent_fast_path(body):
     if '## Agent Fast Path' not in body:
         return body
@@ -869,8 +855,7 @@ def strip_agent_fast_path(body):
                   count=1, flags=re.S).lstrip('\n')
 
 
-def build_design(manifest, l_frontmatter, consumer, body, has_sidecar, canvas,
-                 layouts_index=None):
+def build_design(manifest, l_frontmatter, consumer, body, has_sidecar, canvas):
     blocks = {k: (inline, lines) for k, inline, lines in l_frontmatter}
     bad = set(blocks) - L_FRONTMATTER_KEYS
     if bad:
@@ -908,9 +893,9 @@ def build_design(manifest, l_frontmatter, consumer, body, has_sidecar, canvas,
             out.append('canvas: %dx%d' % tuple(canvas))
     out.append('---')
     text = '\n'.join(out) + '\n'
+    # Fast Path 已废弃：它是 Usage / Hard Rules / 资产表 / 页型清单的第二份副本。
+    # 规则的唯一出处是正文各段，这里只负责把历史产物里的残留剥掉。
     body = strip_agent_fast_path(body)
-    text += '\n' + render_fast_path(manifest, consumer, has_sidecar, canvas,
-                                    layouts_index=layouts_index)
     if body:
         text += body if body.startswith('\n') else '\n' + body
     if not text.endswith('\n'):
@@ -918,26 +903,258 @@ def build_design(manifest, l_frontmatter, consumer, body, has_sidecar, canvas,
     return text
 
 
+def layout_forms(lines):
+    """每个页型草案里实际给了哪几种形态（flow / slots）。"""
+    out, cur = {}, None
+    for line in lines:
+        m = re.match(r'^  ([\w-]+):\s*$', line)
+        if m:
+            cur = m.group(1)
+            out[cur] = set()
+            continue
+        m = re.match(r'^    (flow|slots):\s*$', line)
+        if m and cur:
+            out[cur].add(m.group(1))
+    return out
+
+
+def layout_modes(lines):
+    """读取扁平 `layout_modes:` 判断区。"""
+    out = {}
+    for line in lines:
+        m = re.match(r'^\s{2}([\w-]+):\s*([^\s#]+)', line)
+        if m:
+            out[m.group(1)] = m.group(2).strip()
+    return out
+
+
+def text_role_boxes(lines):
+    """从 slots 里的同名标记取回文本槽坐标，供 flow 固定锚点复用。"""
+    out, pending = {}, None
+    for line in lines:
+        marker = re.match(r'^\s*#\s*text-role:\s*([\w-]+)\s*$', line)
+        if marker:
+            pending = marker.group(1)
+            continue
+        if pending:
+            box = re.search(r'\bbox:\s*(\[[^\]]+\])', line)
+            if box:
+                out[pending] = box.group(1)
+                pending = None
+    return out
+
+
+def select_layout_forms(lines, modes):
+    """按 `layout_modes` 只保留每个页型选中的 flow 或 slots。"""
+    out, layout, drop = [], None, False
+    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, drop = layout_match.group(1), False
+        elif form_match:
+            drop = modes.get(layout) not in (None, form_match.group(1))
+        elif drop and re.match(r'^    \S', line):
+            drop = False
+        if not drop:
+            out.append(line)
+    return out
+
+
+def shrink_safe_area(lines):
+    """text_safe 与 avoid 相交时把安全区收掉重叠的那部分。
+
+    text_safe 是脚本按「该背景各页型的槽位并集」算的，而模板里的槽位本身可能就压在
+    主视觉上；avoid 是看图的人填的。两者从不同来源来，会直接打架——实测一张背景的
+    text_safe 有 34% 落在 avoid 里，消费端按 text_safe 把标题放进了禁放区，正好压在
+    背景的山峰主体上。这里以 avoid 为准收缩：能不能放字是看图的人说了算。
+    """
+    def parse_box(s):
+        m = re.findall(r'-?\d+', s)
+        return [int(x) for x in m[:4]] if len(m) >= 4 else None
+
+    ts_i = ts = None
+    avoids = []
+    for i, ln in enumerate(lines):
+        st = ln.strip()
+        if st.startswith('text_safe:'):
+            ts_i, ts = i, parse_box(st.split(':', 1)[1].split('#')[0])
+        elif st.startswith('avoid:'):
+            for chunk in re.findall(r'box:\s*\[[^\]]*\]', st):
+                b = parse_box(chunk)
+                if b:
+                    avoids.append(b)
+    if ts is None or not avoids:
+        return lines, None
+    x0, y0, x1, y1 = ts[0], ts[1], ts[0] + ts[2], ts[1] + ts[3]
+    for a in avoids:
+        ax0, ay0, ax1, ay1 = a[0], a[1], a[0] + a[2], a[1] + a[3]
+        if ax1 <= x0 or ax0 >= x1 or ay1 <= y0 or ay0 >= y1:
+            continue                       # 不相交
+        # 从被侵占得最少的一边切：优先保留面积最大的剩余矩形
+        cands = []
+        if ax0 > x0:
+            cands.append((x0, y0, ax0, y1))
+        if ax1 < x1:
+            cands.append((ax1, y0, x1, y1))
+        if ay0 > y0:
+            cands.append((x0, y0, x1, ay0))
+        if ay1 < y1:
+            cands.append((x0, ay1, x1, y1))
+        if not cands:
+            return lines, 'text_safe 被 avoid 完全覆盖，这张背景没有可放文字的区域'
+        x0, y0, x1, y1 = max(cands, key=lambda c: (c[2] - c[0]) * (c[3] - c[1]))
+    new = [x0, y0, x1 - x0, y1 - y0]
+    if new == ts:
+        return lines, None
+    lines = list(lines)
+    lines[ts_i] = '    text_safe: [%d, %d, %d, %d]   # 已按 avoid 收缩（原 %s）' % (
+        new[0], new[1], new[2], new[3], ts)
+    return lines, None
+
+
 def build_layouts_md(layouts_blocks, canvas):
     blocks = {k: (inline, lines) for k, inline, lines in layouts_blocks}
     if 'canvas' in blocks:
         raise Fail('layouts.yaml 不要写 canvas —— 脚本从 extract.json 取')
     if 'layouts' not in blocks:
         raise Fail('layouts.yaml 缺顶层键 `layouts:`')
-    # `names:` 是给 L 层集中改中文页型名的一块——在这里并回各 archetype，不进产物
-    names = {}
-    for line in blocks.get('names', ('', []))[1]:
-        m = re.match(r'^\s{2}([\w-]+):\s*(.+?)\s*$', line)
+    # `names:` / `roles:` / `text_roles:` / `layout_modes:` / `bg_rules:` 是给 L 层集中填判断的
+    # 扁平区——在这里并回各 archetype，本身不进产物。让 L 层只改扁平键值，别去动 layouts 里的
+    # slots/confidence 结构（嵌套结构手改极易破坏缩进，进而静默改变语义）。
+    names, roles = {}, {}
+    for key, sink in (('names', names), ('roles', roles)):
+        for line in blocks.get(key, ('', []))[1]:
+            m = re.match(r'^\s{2}([\w-]+):\s*(.+?)\s*$', line)
+            if m:
+                sink[m.group(1)] = unquote(m.group(2))
+    text_roles = {}
+    allowed_text_roles = {'title', 'subtitle', 'header', 'footer', 'body'}
+    for line in blocks.get('text_roles', ('', []))[1]:
+        m = re.match(r'^\s{2}([\w-]+):\s*([A-Za-z-]+)(?:\s+#.*)?$', line)
+        if not m:
+            continue
+        role_id, role = m.groups()
+        if role not in allowed_text_roles:
+            raise Fail('text_roles.%s 取值 %s 非法；应为 %s'
+                       % (role_id, role, '|'.join(sorted(allowed_text_roles))))
+        text_roles[role_id] = role
+    bg_rules, cur = {}, None
+    for line in blocks.get('bg_rules', ('', []))[1]:
+        # 键后面允许行内注释（草案会标「用它的页型：…」）
+        m = re.match(r'^\s{2}([\w-]+):\s*(?:#.*)?$', line)
         if m:
-            names[m.group(1)] = unquote(m.group(2))
-    out = ['---', 'canvas: %dx%d' % tuple(canvas), 'layouts:']
-    for line in blocks['layouts'][1]:
-        out.append(line)
+            cur = m.group(1)
+            bg_rules[cur] = []
+            continue
+        if cur and line.strip():
+            bg_rules[cur].append('    ' + line.strip())
+    out = ['---', 'canvas: %dx%d' % tuple(canvas)]
+    # 禁放区是背景的属性，按背景写一次；页型只留 `background:` 指针。
+    # 合并进每个页型会把同一句话按页型数复制 N 遍。
+    if bg_rules:
+        out.append('backgrounds:')
+        for bg, lines in bg_rules.items():
+            lines, err = shrink_safe_area(lines)
+            if err:
+                raise Fail('%s: %s' % (bg, err))
+            out.append('  %s:' % bg)
+            out += lines
+    modes = layout_modes(blocks.get('layout_modes', ('', []))[1])
+    out.append('layouts:')
+    pending_text_role = None
+    used_text_roles = set()
+    source_layout_lines = blocks['layouts'][1]
+    role_boxes = text_role_boxes(source_layout_lines)
+    layout_lines = select_layout_forms(source_layout_lines, modes)
+    cur, fixed_items = None, []
+
+    def flush_fixed_items():
+        if not fixed_items:
+            return
+        out.append('        - kind: free')
+        out.append('          items:')
+        out.extend(fixed_items)
+        fixed_items.clear()
+
+    for line in layout_lines:
         m = re.match(r'^  ([\w-]+):\s*$', line)
+        if m:
+            flush_fixed_items()
+            cur = m.group(1)
+        elif fixed_items and re.match(r'^    \S', line):
+            flush_fixed_items()
+        # 判断单里的结构事实（栅格、间距序列、样张字数、命中配方）是给 L 层判断用的，
+        # 不进产物——消费端要的是结论，不是推导过程。layout_mode 同理，它是判断的载体。
+        if line.lstrip().startswith('#'):
+            marker = re.match(r'^\s*#\s*text-role:\s*([\w-]+)\s*$', line)
+            if marker:
+                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)
+                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 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)))
+    flush_fixed_items()
     if names:
         raise Fail('names 里这些页型在 layouts 下找不到：%s' % ', '.join(sorted(names)))
+    if roles:
+        raise Fail('roles 里这些页型在 layouts 下找不到：%s' % ', '.join(sorted(roles)))
+    unused_text_roles = set(text_roles) - used_text_roles
+    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)]
+    if missing_role:
+        raise Fail('这些页型没有 role（在 layouts.yaml 的 roles 段填）：%s' % ', '.join(missing_role))
+    # `layout_modes.*: TODO` 由上面那道通用 TODO 扫描报（它连行内提示一起打出来），
+    # 这里只管它管不到的两种：整行被删、以及填了 flow/slots 之外的值。
+    forms = layout_forms(blocks['layouts'][1])
+    bad = []
+    for k, v in sorted(modes.items()):
+        if len(forms.get(k) or ()) < 2:
+            continue                          # 只有一份形态，无从选择
+        if v not in ('flow', 'slots'):
+            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*$',
+                              '\n'.join(blocks['layouts'][1]), re.M))
+    stray = set(bg_rules) - declared
+    if stray:
+        raise Fail('backgrounds 段里这些背景没有任何页型在用：%s' % ', '.join(sorted(stray)))
     out.append('---')
     text = '\n'.join(out) + '\n'
     if 'body' in blocks:
@@ -993,6 +1210,12 @@ def main(argv=None):
     if left:
         raise Fail('判断单还有 %d 处草案占位没改（TODO 是 draft.py 留给 L 层的判断点）：\n    %s'
                    % (len(left), '\n    '.join(left)))
+    mdesc = re.search(r'^description:\s*[|>]?\s*\n((?:\s+\S.*\n?)+)',
+                      open(os.path.join(lout, 'manifest.yaml'), encoding='utf-8').read(), re.M)
+    if mdesc and len(re.sub(r'\s+', '', mdesc.group(1))) < 20:
+        raise Fail('manifest 的 description 只有 %d 个字符——它是消费模型定调的唯一入口，'
+                   '写清底色/主色/字形/版面骨架，不要留占位'
+                   % len(re.sub(r'\s+', '', mdesc.group(1))))
 
     manifest = read_manifest(os.path.join(lout, 'manifest.yaml'))
     if args.style_name:
@@ -1016,34 +1239,23 @@ def main(argv=None):
 
     lay_text = open(lay_path, encoding='utf-8').read() if os.path.exists(lay_path) else ''
     body = expand_placeholders(body, manifest, consumer, audit, extract, lay_text)
-    layouts_index = layout_fast_index(layouts_blocks)
     design = build_design(manifest, l_fm, consumer, body,
-                          has_sidecar=layouts_blocks is not None, canvas=canvas,
-                          layouts_index=layouts_index)
+                          has_sidecar=layouts_blocks is not None, canvas=canvas)
     with open(os.path.join(pack, 'design.md'), 'w', encoding='utf-8') as f:
         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))
 
-    ref = os.path.join(pack, 'ref')
+    # 审计记录写回**抽取工作目录**，不进交付包：包是消费产物，`ref/` 里的东西
+    # 没有任何门禁读、消费模型也用不上，放进去只会让「别读我」和「几 MB 材料」同时下发。
+    ref = os.path.join(stage1, 'ref')
     os.makedirs(ref, exist_ok=True)
-    with open(os.path.join(ref, 'audit.yaml'), 'w', encoding='utf-8') as f:
+    audit_path = os.path.join(ref, 'audit.yaml')
+    with open(audit_path, 'w', encoding='utf-8') as f:
         f.write(render_audit(manifest, extract, audit))
     carried = []
-    for name in REF_CARRY:
-        srcf = os.path.join(stage1, 'ref', name)
-        if os.path.exists(srcf):
-            shutil.copy2(srcf, os.path.join(ref, name))
-            carried.append(name)
-    shutil.copy2(ex_path, os.path.join(ref, 'extract.json'))
-    carried.append('extract.json')
-    for sub in ('rebuild', 'logo-candidates'):
-        s = os.path.join(stage1, 'ref', sub)
-        if os.path.isdir(s):
-            shutil.copytree(s, os.path.join(ref, sub), dirs_exist_ok=True)
-            carried.append(sub + '/')
-    # L 层自备的 ref 补充件（判断理由、版式溯源等）原样带入
+    # L 层自备的 ref 补充件（判断理由、版式溯源等）也归到抽取目录
     l_ref = os.path.join(lout, 'ref')
     if os.path.isdir(l_ref):
         shutil.copytree(l_ref, ref, dirs_exist_ok=True)
@@ -1061,7 +1273,9 @@ def main(argv=None):
     print('  assets %d 条目 / %d 文件落盘' % (len(consumer), len(copied)))
     for d in copied:
         print('    %-52s %8d B' % (os.path.relpath(d, pack), os.path.getsize(d)))
-    print('  ref/ %s' % ', '.join(carried))
+    print('  审计记录 -> %s%s（不进交付包）'
+          % (os.path.relpath(audit_path, os.path.dirname(stage1)),
+             '  ' + ', '.join(carried) if carried else ''))
 
     # ---- 数值可追溯机检：产物里每个色值/字号/坐标都得能指回普查值
     derived_values, derived_tokens = set(), set()
@@ -1079,9 +1293,17 @@ def main(argv=None):
     shapes = json.load(open(sp, encoding='utf-8'))['shapes'] if os.path.exists(sp) else []
     problems, checked = trace_check(pack, extract, shapes,
                                     derived_values, derived_tokens, factor)
+    integrity = media_integrity(stage1, extract)
+    if integrity:
+        print('\n--- 媒体产物完整性 ---')
+        for b in integrity:
+            print('  FAIL ' + b)
+        raise Fail('media-out 里的文件和 extract.json 的记录对不上（%d 处）' % len(integrity))
     print('\n--- 数值可追溯机检 ---')
-    print('  受检 hex %d / fontSize %d / slot box %d；derived 豁免 %d%s'
+    print('  受检 hex %d / fontSize %d / slot box %d；derived 豁免 %d%s%s'
           % (checked['hex'], checked['size'], checked['box'], checked['exempt'],
+             '；判断键跳过 %d 行（avoid/text_safe/pairing_rule）' % checked['judgement']
+             if checked['judgement'] else '',
              '；rebase_factor=%g' % factor if factor else ''))
     if not shapes:
         print('  ⚠ 未找到 %s，slot 坐标一项无法校验' % sp)
@@ -1108,6 +1330,7 @@ def main(argv=None):
             print('check_v1: 未探测到（$DSM_V1_DIR / 同级 skill / 开发机路径均无）—— v1 门禁未跑，交付前必须补跑')
     if args.check_v1:
         print('\n--- check_v1 ---')
+        sys.stdout.flush()
         r1 = subprocess.run([sys.executable, args.check_v1,
                              os.path.join(pack, 'design.md'), 'slide'])
         rc = rc or r1.returncode