@lark-apaas/coding-steering 0.1.18-dev.21ea0ba → 0.1.18-dev.28c4f05

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Stage-1 deterministic extractor for PPTX/POTX style packs (票 09 原型).
+"""Stage-1 deterministic extractor for PPTX/POTX style packs.
 
     python3 extract.py <pptx> <outdir> [--export-all-media]
 
@@ -21,7 +21,8 @@ from datetime import datetime, timezone
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
-from census import (DHASH_PREFILTER_MAX, FULLSCREEN_MIN_PCT, PIXDIFF_MAX, REPEAT_MIN,
+from census import (ASSET_WARN_SINGLE, DHASH_PREFILTER_MAX, FULLSCREEN_MIN_PCT, PIXDIFF_MAX,
+                    REPEAT_MIN, SMALL_IMG_W_PCT,
                     EPS_PX, color_census, content_clusters, detect_twins, font_census,
                     image_census, image_palette, layout_inventory, media_fingerprints,
                     font_scheme_by_part, radii_effects_census, read_guides,
@@ -32,7 +33,7 @@ from parts import (Package, PartCtx, build_graph, read_clrmap, read_part_shapes,
 
 SCHEMA = 'pptx-extract/stage1-v0.1'
 WEB_FORMATS = {'png', 'jpg', 'jpeg', 'gif', 'webp', 'svg'}
-ASSET_BUDGET_BYTES = 500 * 1024                       # D5b WARN line
+ASSET_BUDGET_BYTES = ASSET_WARN_SINGLE                # V2-6 单张 WARN 线
 # Quality ladder first, then resolution — dropping pixels is the more visible
 # loss, so it is only reached once the lowest quality still overshoots.
 WEBP_QUALITY_LADDER = (85, 75, 65, 55, 45)
@@ -177,6 +178,10 @@ def export_media(pkg, images, outdir, pillow_ok, export_all=False):
                 reasons.append('variant_group')
             if info['stitch_candidate']:
                 reasons.append('crop_stitch')
+            if 0 < (info.get('max_w_pct') or 0) < SMALL_IMG_W_PCT and not info['fullscreen']:
+                # 小图（页内图标、角标）。不导出的话 L 层只能看着装饰容器里的空洞
+                # 自己编图形，编出来的与模板无关。
+                reasons.append('icon_candidate')
         if ext in ('svg', 'emf', 'wmf'):
             reasons.append('vector')
         row = {'media': part, 'ext': ext, 'bytes': size,
@@ -240,17 +245,46 @@ def export_media(pkg, images, outdir, pillow_ok, export_all=False):
 
 
 # ---------------------------------------------------------------- form hint
+# PowerPoint 出厂版式名（中英两套）。设计师起的名字是「这一页干什么用」，
+# 出厂名只是「这个占位符组合叫什么」——后者不算模板声明了页型。
+STOCK_LAYOUT_NAMES = {
+    'default', 'blank', 'custom layout', 'title slide', 'title and content',
+    'section header', 'two content', 'comparison', 'title only',
+    'content with caption', 'picture with caption', 'title and vertical text',
+    'vertical title and text', 'name card', 'quote with caption', 'true or false',
+    '空白', '自定义版式', '标题幻灯片', '标题和内容', '节标题', '两栏内容', '比较',
+    '仅标题', '内容与标题', '图片与标题', '标题和竖排文字', '竖排标题与文本',
+}
+_NUM_PREFIX = re.compile(r'^\s*\d+[\s._-]*')
+
+
+def is_semantic_layout_name(name):
+    """版式名是不是设计师起的「页型名」，而不是出厂名或纯编号。
+
+    不能按字符数判断——中文页型名两个字就说清了（「封面」「目录」），任何长度门槛
+    都会把整套 CJK 命名的模板判成没有语义版式，进而走错 form 分支。
+    """
+    n = _NUM_PREFIX.sub('', (name or '').strip())
+    if not n or n.strip('0123456789 ._-') == '':
+        return False
+    return n.lower() not in STOCK_LAYOUT_NAMES
+
+
 def form_hint(pkg, graph, layouts):
     slides_with_ph = 0
     for sp in pkg.slides:
         if pkg.xml(sp).findall('.//p:ph', NS):
             slides_with_ph += 1
     names = [(l['name'] or '') for l in layouts]
-    semantic = sum(1 for n in names if len(n) > 3 and n.upper() not in ('DEFAULT', 'BLANK'))
+    semantic = sum(1 for n in names if is_semantic_layout_name(n))
     ev = {'slides_using_placeholders': '%d/%d' % (slides_with_ph, len(pkg.slides)),
           'layouts': len(pkg.layouts), 'masters': len(pkg.masters),
           'semantic_layout_names': semantic}
-    if slides_with_ph and len(pkg.layouts) >= 5 and semantic >= 5:
+    # 「模板自带页型声明」的判据是**比例**不是个数：一套只有 4 个版式但全部起了页型名的
+    # 精简模板，和一套 30 个版式里 5 个有名字的模板，前者才是真的按页型组织的。
+    semantic_ratio = semantic / float(len(pkg.layouts) or 1)
+    ev['semantic_layout_ratio'] = round(semantic_ratio, 3)
+    if slides_with_ph and semantic >= 2 and semantic_ratio >= 0.5:
         form = 3
     elif len(pkg.layouts) > 1 and not slides_with_ph:
         form = 2
@@ -404,7 +438,7 @@ REF_NOTES = """# ref/ 审计层说明（S12）
 4. **S6 XPath 口径**（写死并逐项声明）：design = `a:solidFill//` 下的颜色 + 渐变
    `a:gs` 的直接子颜色 + `p:bgRef` 的直接子颜色；editor = `p15:clr`（参考线）；
    aux = `a:buClr` 与 `p:style/a:*Ref`。effectLst 内的阴影色不计入频次。
-5. **S5 计数双口径**：`exact_boxes` 是坐标完全一致的计数（可与票 03 recon 逐数对齐）；
+5. **S5 计数双口径**：`exact_boxes` 是坐标完全一致的计数（可与逐形状人工点数对齐）；
    `boxes[]` 是 ±0.5%（{eps:.1f}px）epsilon 聚类计数，会把微偏移的同位实例并进同一簇。
    两者都落盘，差异即「容差带来的合并」。
 6. **满屏判定独立阈值**：w ≥ {fs}% 且 h ≥ {fs}%，上不封顶；出血图（>100%）同样计入满屏。
@@ -646,7 +680,7 @@ def extract(pptx, outdir, export_all=False):
             'Pillow unavailable: byte-identical media only, no perceptual merging'),
         'palette_available': pillow_ok,
         'media': media_rows,
-        # S4 shape-facts are 49-64% of this file (volcano: 1.4 MB) and stage 2 reads
+        # S4 shape-facts dominate this file (roughly half its bytes) and stage 2 reads
         # them only when a derived statistic needs backing evidence, so they live in
         # a sidecar and extract.json keeps just the pointer plus the derived censuses.
         'shapes_ref': 'ref/shapes.json',
@@ -751,6 +785,13 @@ def main(argv):
             print('unknown option(s): %s' % ' '.join(sorted(unknown)))
         print(__doc__)
         return 2
+    if not os.path.isfile(args[0]):
+        # 猜附件文件名是高频错误起手式，报错要把「去哪儿看真名」直接说清楚
+        print('找不到 %s' % args[0])
+        print('不要猜附件文件名。先列出真实文件：ls -la .agent/<conversation_id>/attachments/')
+        print('目录里没有 .pptx / .potx 时，说明这次上传没有落成沙箱本地文件——'
+              '如实告诉用户拿不到模板文件，不要退回附件文本摘要或自造配图当风格来源。')
+        return 2
     extract(args[0], args[1], export_all='--export-all-media' in flags)
     if '--no-draft' not in flags:
         import subprocess

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

@@ -47,7 +47,7 @@ WEIGHT_TOKENS = {
 ITALIC_TOKENS = {'italic', 'oblique', 'it'}
 
 # Deterministic latin<->CJK alias hints. Emitted as a separate `alias_group` field,
-# never merged into counts, so the audit trail stays intact (see STAGE1-REPORT deviations).
+# never merged into counts, so the audit trail stays intact.
 FONT_ALIAS_GROUPS = {
     'fzlantinghei': ('方正兰亭黑', 'fzlantingheipro', 'fzlthpro', 'fzlthpros'),
     'bytesans': ('字节跳动', 'bytesans'),

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,7 @@ 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}
         confidence: high
 
   可选 `body:` 块标量 —— 追加到 layouts.md frontmatter 之后作为说明正文。
@@ -139,9 +139,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):
@@ -382,7 +384,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 +408,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 +438,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'):
@@ -604,6 +628,11 @@ 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 trace_check(pack, extract, shapes, derived_values, derived_tokens, factor):
     """产物里每个 hex / 字号 / slot 坐标都必须可追溯到普查值或 derived 声明。"""
     idx = build_trace_index(extract, shapes)
@@ -614,6 +643,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 +794,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 +801,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 +839,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'):
@@ -924,20 +855,55 @@ def build_layouts_md(layouts_blocks, canvas):
         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:` / `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))
+    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:']
+            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():
+            out.append('  %s:' % bg)
+            out += lines
+    out.append('layouts:')
     for line in blocks['layouts'][1]:
         out.append(line)
         m = re.match(r'^  ([\w-]+):\s*$', 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)))
     if names:
         raise Fail('names 里这些页型在 layouts 下找不到：%s' % ', '.join(sorted(names)))
+    if roles:
+        raise Fail('roles 里这些页型在 layouts 下找不到：%s' % ', '.join(sorted(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))
+    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 +959,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 +988,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 +1022,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()
@@ -1080,8 +1043,10 @@ def main(argv=None):
     problems, checked = trace_check(pack, extract, shapes,
                                     derived_values, derived_tokens, factor)
     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 +1073,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

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

@@ -39,15 +39,15 @@ class Package:
         self.masters = sorted((n for n in self.names if MASTER_RE.match(n)), key=_num)
         self.themes, self.theme_discovery = self._find_themes(ct)
         # zip directory entries ('ppt/media/') must not be counted as assets —
-        # 票 03 recon counted one, which is why its media totals run one high.
+        # they inflate media totals by one.
         self.media = sorted(n for n in self.names
                             if n.startswith('ppt/media/') and not n.endswith('/'))
 
     def _find_themes(self, ct):
         """Theme parts come from [Content_Types].xml, not from a path pattern.
 
-        Compressors relocate them — 飞书压缩版 puts them at
-        ppt/slideMasters/theme/themeN.xml — and a `ppt/theme/` regex then finds
+        Compressors relocate them — some rewrite them under
+        ppt/slideMasters/theme/ — and a `ppt/theme/` regex then finds
         nothing to bind the masters to, so every schemeClr resolves to
         UNRESOLVED:no-scheme. The path regex stays as the fallback for packages
         whose content types are unreadable.

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

@@ -266,8 +266,8 @@ def _recipe_css(fill, line, radii, effects):
 
 def _sig(fill, line, effects):
     """分组键 = 填充 + 描边 + 效果。**不含圆角**——OOXML 圆角是 min(w,h) 的百分比，
-    同一配方在不同尺寸的卡上绝对 px 必然不同（feishu 三张 glassCard 实测 10.8/12.8/19.5），
-    把它计入键会把一个配方拆成三组；归一到哪一档是 L11 的判断，脚本只报区间。"""
+    同一配方在不同尺寸的卡上绝对 px 必然不同，把它计入键会把一个配方拆成多组；
+    归一到哪一档是判断，脚本只报区间。"""
     f = 'none'
     if isinstance(fill, dict):
         if fill.get('type') == 'solid':

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

@@ -279,18 +279,19 @@ def render_shape(shape, media_url, stats):
 
 HEAD = """<style>
 body{margin:0;background:#2b2b2b;font-family:%s}
-.page{position:relative;width:1920px;height:1080px;overflow:hidden}
+.page{position:relative;width:%dpx;height:%dpx;overflow:hidden}
 .sp{position:absolute;box-sizing:border-box}
 .sp p{margin:0}
 .ph{position:absolute;left:6px;top:4px;font:16px/1.2 monospace;color:#ff2b88;background:#fff9;padding:1px 4px}
 </style>
-""" % CJK_STACK
+"""
 
+# 缩略框跟着画布比例走，缩放比也一起算——写死 16:9 会把非 16:9 模板的页面裁掉一截
 INDEX_EXTRA = """<style>
-.wrap{width:960px;margin:0 auto;padding:16px 0}
+.wrap{width:%dpx;margin:0 auto;padding:16px 0}
 .lbl{color:#eee;font:13px/1.6 monospace;margin:14px 0 4px}
-.box{width:960px;height:540px;overflow:hidden;margin-bottom:6px}
-.box .page{transform:scale(.5);transform-origin:top left}
+.box{width:%dpx;height:%dpx;overflow:hidden;margin-bottom:6px}
+.box .page{transform:scale(%g);transform-origin:top left}
 </style>
 """
 
@@ -508,7 +509,8 @@ def render_pages_png(pages, outdir, data, scale=0.5):
                    for m in data.get('media') or [] if m.get('exported') and m.get('out')}
     png_dir = os.path.join(outdir, 'ref', 'rebuild', 'png')
     os.makedirs(png_dir, exist_ok=True)
-    W, H = int(1920 * scale), int(1080 * scale)
+    cpx = ((data.get('canvas') or {}).get('px') or [1920, 1080])
+    W, H = int(cpx[0] * scale), int(cpx[1] * scale)
     for kind, n, label, layers, default_color, page_bg in pages:
         canvas = Image.new('RGBA', (W, H), _rgba(page_bg) or (136, 136, 136, 255))
         g = _grad_stops(page_bg or '')
@@ -642,15 +644,19 @@ def main():
                           tx1_of_master.get(master, '#000000'),
                           layout_bg.get(part, '#888')))
 
-    if only is not None:
-        pages = [p for p in pages if p[0] != 'slide' or p[1] in only]
+    if only is not None:      # 对样张和版式一律生效（form=3 的代表页是版式，不是样张）
+        pages = [p for p in pages if p[1] in only]
 
     stats = {'shapes': 0, 'text': 0, 'img_ok': 0, 'img_missing': 0, 'no_box': 0}
-    index = [HEAD, INDEX_EXTRA, '<div class="wrap">']
+    cw, ch = ((data.get('canvas') or {}).get('px') or [1920, 1080])[:2]
+    head = HEAD % (CJK_STACK, cw, ch)   # 视口跟画布走，非 16:9 模板不能按 1920x1080 裁
+    thumb_scale = 960.0 / cw
+    index = [head, INDEX_EXTRA % (960, 960, round(ch * thumb_scale), thumb_scale),
+             '<div class="wrap">']
     for kind, n, label, layers, default_color, page_bg in (() if args.no_html else pages):
         html = page_html(layers, default_color, page_bg, media_url, stats)
         with open(os.path.join(rebuild, '%s-%d.html' % (kind, n)), 'w', encoding='utf-8') as f:
-            f.write(HEAD + html)
+            f.write(head + html)
         index += ['<div class="lbl">%s</div>' % esc(label),
                   '<div class="box">%s</div>' % html]
     index.append('</div>')