@lark-apaas/coding-steering 0.1.18-dev.4aa21f4 → 0.1.18-dev.4e64c13

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

@@ -0,0 +1,1204 @@
+#!/usr/bin/env python3
+"""S11 打包器：把「阶段一抽取产物 + L 层判断单」机械组装成风格包 v2。
+
+    python3 package.py <stage1-outdir> <l-out-dir> <pack-out-dir> [选项]
+
+      --check-v1 <path>   顺带跑 v1 门禁（需要外部 check_v1.py 路径）
+      --style-name <name> 覆盖 manifest 里的 name（包目录名仍取 pack-out-dir）
+      --force             pack-out-dir 已存在且非空时照样写
+
+本脚本零判断：所有语义来自 <l-out-dir>，所有数值来自 <stage1-outdir>/extract.json。
+它只做四件机械事——排键序、拷资产、算审计数据、跑门禁。
+
+================================================================================
+L 层判断单 schema（<l-out-dir> 四个文件，这段就是填写说明书）
+================================================================================
+
+本脚本自带极简 YAML 读取器，只认下面这些写法，**不要用锚点/别名/复杂嵌套流**：
+  key: 标量                     标量可加引号（会原样保留到产物里）
+  key: [a, b, c]                流式列表
+  key: |  或  key: >            块标量（`|` 保留换行，`>` 折成一行）
+  key:                          后跟缩进块 —— 对 frontmatter.yaml / layouts.yaml
+    ...                         这类「原样透传」的键，块内文本**逐字节照搬**进产物，
+                                所以缩进/引号/注释请按最终想要的样子写
+
+--------------------------------------------------------------------------------
+1) manifest.yaml —— 包身份 + 资产映射（唯一需要本脚本解析结构的文件）
+--------------------------------------------------------------------------------
+
+    version: alpha                    # 可选，默认 alpha
+    name: azure-mist-deck             # 必填，包名（英文 kebab）
+    name_zh: 碧空雾面                  # 可选
+    description: >                    # 可选，一段话，会折成单行进 frontmatter
+      整幅铺满带颗粒感的淡蓝雾面底图……
+    themes: [dark, light]             # 可选；单主题包不写
+    default-theme: dark               # themes 长度 >1 时必填（V2-13）
+    theme-mechanism: "……"             # 可选，进 ref/audit.yaml（不进 design.md）
+    color-confidence: {level: medium, note: "……"}   # 可选，进 ref/audit.yaml
+    assets:                           # 可选；无资产包可整段省略
+      - id: bg-cover                  # 必填。命名规则 <kind 前缀>-<语义名>，
+                                      #   logo- / slogan- / bg- / texture- / icon-
+        source_media: <原图文件名>     # media-out/ 里的**原图**文件名（不是压缩版）
+        kind: background              # logo|slogan|background|texture|icon
+        role: cover                   # background/icon 用；封闭枚举见规范 §2
+        theme: dark                   # 双主题包按需
+        on-bg: light                  # logo/slogan 用
+        mark: lockup                  # logo/slogan 用；**自动进 audit.yaml**
+        use_full: true                # true = 同时落原图为 <name>@full.<ext>
+        recipe: "linear-gradient(…)"  # 可选，CSS 重绘配方
+        confidence: high              # 可选，默认 high；**自动进 audit.yaml**
+      - id: bg-surface                # 纯色背景：不给 source_media，给 color
+        kind: background
+        role: content
+        color: "{colors.surface}"
+
+  说明：`boxes` / `aspect` / `canvas-source` **不要填**——脚本按 source_media 从
+  extract.json 的 images[] 直接取，写进 ref/audit.yaml。
+
+    derived:                          # 可选：推导值豁免声明（数值可追溯机检用）
+      - value: "1.05"                 #   按字面值豁免：产物里出现的该值放行
+        reason: "CJK 行高转译"
+      - value: "#5A5A5A"
+        reason: "白字 70% 不透明度的等效实色"
+      - token: light-surface          #   按键名豁免：该 token（或其祖先键）下所有值放行
+        reason: "材质推导，gaps 已注明"
+    rebase_factor: 1.6                # 可选：字号等比上抬倍率；命中「普查值 × 它 ±1px」即放行
+
+  打包最后一步会校验产物里每个 hex / fontSize / slots.box 是否可追溯：
+  hex 命中 color_freq ∪ 形状与背景的填充/描边/渐变 stop 色 ∪ images[].dominant_colors
+  （每通道 ±8，采样色有量化误差）；fontSize 命中 text_scale；box 命中 ref/shapes.json
+  某形状框 ±2px。命不中又没在 derived 里声明 → FAIL 并给出最近候选。
+
+--------------------------------------------------------------------------------
+2) frontmatter.yaml —— L 层判断产物，原样进 design.md frontmatter
+--------------------------------------------------------------------------------
+
+  顶层键只允许这些（缺哪个就不写哪个，脚本按规范 §1 键序重排）：
+    colors / typography / spacing / rounded / components / omitted
+    anchors / gaps / exceptions / safe-area
+  写法就是最终 frontmatter 的样子，例如：
+
+    colors:
+      surface: "#FFFFFF"
+      primary: "#RRGGBB"
+    safe-area:
+      content: {top: <px>, right: <px>, bottom: <px>, left: <px>, applies-to: [content]}
+      confidence: medium
+
+--------------------------------------------------------------------------------
+3) layouts.yaml —— archetype 数据，渲染成 layouts.md
+--------------------------------------------------------------------------------
+
+  只需一个顶层键 `layouts:`，内容原样透传。**不要写 canvas**——脚本从
+  extract.json 取并放成 layouts.md frontmatter 首键（V2-10 / V2-R6）。
+
+    layouts:
+      cover:
+        name: "封面"
+        role: cover
+        background: bg-cover
+        slots:
+          - {role: title, box: [<x>, <y>, <w>, <h>], type: title}
+        confidence: high
+
+  可选 `body:` 块标量 —— 追加到 layouts.md frontmatter 之后作为说明正文。
+
+--------------------------------------------------------------------------------
+4) body.md —— design.md 正文全文
+--------------------------------------------------------------------------------
+
+  从 `## Overview` 开始的全部正文（Usage / Colors / Typography / Hard Rules /
+  Exceptions……）。脚本原样拼在 frontmatter 之后，不改一个字。
+"""
+import argparse
+from collections import Counter
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+# 规范 §1 键序：官方白名单 → v1 自造 → v2 自造。审计键（canvas-source /
+# theme-mechanism / color-confidence）按 V2-R6 不进 design.md，故不在此列。
+FRONTMATTER_ORDER = [
+    'version', 'name', 'name_zh', 'description',
+    'colors', 'typography', 'spacing', 'rounded', 'components', 'omitted',
+    'anchors', 'gaps', 'exceptions',
+    'themes', 'default-theme', 'assets', 'layouts', 'safe-area',
+]
+# frontmatter.yaml 允许 L 层提供的键（其余由 manifest / 脚本产出）
+L_FRONTMATTER_KEYS = {'colors', 'typography', 'spacing', 'rounded', 'components',
+                      'omitted', 'anchors', 'gaps', 'exceptions', 'safe-area'}
+# design.md 资产条目只留消费字段，顺序固定（check_v2 V2-R6 把其余判成审计字段）
+ASSET_CONSUMER_FIELDS = ['path', 'url', 'color', 'full', 'kind', 'role',
+                         'theme', 'on-bg', 'recipe']
+ASSET_AUDIT_FIELDS = ['boxes', 'aspect', 'mark', 'confidence']
+KIND_PREFIX = {'background': 'bg', 'logo': 'logo', 'slogan': 'slogan',
+               'texture': 'texture', 'icon': 'icon'}
+# 交付包的 ref/ 只留 audit.yaml（人复核数值出处用，几 KB）。
+# 频次原表、聚类原始数据、extract.json、重建图、logo 候选图全部留在 stage1 抽取目录，
+# 不拷进包——规范原本指望「下发时链路剥离」，但链路上没有环节真的剥离，结果
+# 审计材料带着「别读我」一起进消费上下文，还占掉包体的大头。
+REF_CARRY = ()
+
+
+class Fail(SystemExit):
+    def __init__(self, msg):
+        super().__init__('package.py: %s' % msg)
+
+
+# ------------------------------------------------------------ 极简 YAML 读取
+def split_top_blocks(text):
+    """顶层 `key:` 切块。返回 [(key, inline_value, block_lines)]，块内逐字节保留。"""
+    out, cur = [], None
+    for raw in text.splitlines():
+        if not raw.strip() or raw.lstrip().startswith('#'):
+            if cur:
+                cur[2].append(raw)
+            continue
+        m = re.match(r'([A-Za-z_][\w-]*):(.*)$', raw)
+        if m and not raw[0].isspace():
+            cur = [m.group(1), m.group(2).strip(), []]
+            out.append(cur)
+        elif cur:
+            cur[2].append(raw)
+        else:
+            raise Fail('顶层出现无键行: %r' % raw[:60])
+    # 去掉每块尾部空行，避免透传时带出多余空白
+    for entry in out:
+        while entry[2] and not entry[2][-1].strip():
+            entry[2].pop()
+    return out
+
+
+def unquote(s):
+    s = s.strip()
+    if len(s) >= 2 and s[0] == s[-1] and s[0] in '"\'':
+        return s[1:-1]
+    # 未加引号的标量后面跟行内注释：按 YAML 规矩剥掉（前面必须有空白）
+    s = re.split(r'\s+#', s, maxsplit=1)[0].strip()
+    return s
+
+
+def scalar_of(inline, lines):
+    """标量取值：支持 `key: v`、`key: |`、`key: >`。
+
+    `|` 按公共缩进整体 dedent，**不逐行 strip** —— 正文里的嵌套列表/缩进代码块
+    靠相对缩进表意，逐行 strip 会把它们拍平。
+    """
+    if inline in ('|', '>', '|-', '>-'):
+        if inline.startswith('>'):
+            return ' '.join(ln.strip() for ln in lines if ln.strip()).strip()
+        indents = [len(ln) - len(ln.lstrip()) for ln in lines if ln.strip()]
+        pad = min(indents) if indents else 0
+        return '\n'.join(ln[pad:] if len(ln) >= pad else ln.lstrip()
+                         for ln in lines).strip('\n')
+    return unquote(inline)
+
+
+def parse_flow_list(s):
+    s = s.strip()
+    if not (s.startswith('[') and s.endswith(']')):
+        return None
+    inner = s[1:-1].strip()
+    return [unquote(x) for x in inner.split(',') if x.strip()] if inner else []
+
+
+def parse_item_list(lines):
+    """`- key: v` 形式的对象列表。"""
+    items, cur = [], None
+    for raw in lines:
+        if not raw.strip() or raw.lstrip().startswith('#'):
+            continue
+        stripped = raw.strip()
+        if stripped.startswith('- '):
+            cur = {}
+            items.append(cur)
+            stripped = stripped[2:].strip()
+            if not stripped:
+                continue
+        if cur is None:
+            raise Fail('资产列表里出现不属于任何 `- ` 项的行: %r' % raw[:60])
+        m = re.match(r'([A-Za-z_][\w-]*):(.*)$', stripped)
+        if not m:
+            raise Fail('资产列表行无法解析: %r' % raw[:60])
+        # 值原样保留（含作者的引号）：recipe / color / url 这些是直接透传进
+        # design.md 的文本，重新决定要不要加引号会改掉作者的写法。
+        cur[m.group(1)] = m.group(2).strip()
+    return items
+
+
+def read_manifest(path):
+    blocks = split_top_blocks(open(path, encoding='utf-8').read())
+    man, assets, raw = {}, [], {}
+    derived = []
+    for key, inline, lines in blocks:
+        if key == 'assets':
+            assets = parse_item_list(lines)
+        elif key == 'derived':
+            derived = parse_item_list(lines)
+        elif inline.startswith('['):
+            man[key] = parse_flow_list(inline)
+        elif inline.startswith('{'):
+            man[key] = inline                      # 流映射原样透传
+        else:
+            man[key] = scalar_of(inline, lines)
+        if lines:
+            # 记住原始块形态（如 `description: >` 多行），回写时逐字节照搬，
+            # 不把作者的折行改成一条长行。
+            raw[key] = (inline, lines)
+    man['assets'] = assets
+    man['derived'] = derived
+    man['_raw'] = raw
+    return man
+
+
+# ------------------------------------------------------------------- 组装
+def yaml_scalar(v):
+    """标量回写。已带引号 / 流式结构原样；含 YAML 危险序列才补引号。"""
+    s = str(v)
+    if not s:
+        return "''"
+    if s[0] in '"\'[{' or s[-1] in '"\']}':
+        return s
+    if re.search(r':\s|\s#|^[-?*&!|>%@`]', s) or s.strip() != s:
+        return '"%s"' % s.replace('"', '\\"')
+    return s
+
+
+def truthy(v):
+    return str(v).strip().lower() in ('1', 'true', 'yes', 'on')
+
+
+def asset_ext(name):
+    return name.rsplit('.', 1)[-1].lower() if '.' in name else ''
+
+
+def strip_kind_prefix(aid, kind):
+    """`bg-cover` + background -> `cover`；前缀对不上就整名照用。"""
+    for pref in (KIND_PREFIX.get(kind), kind):
+        if pref and aid.startswith(pref + '-'):
+            return aid[len(pref) + 1:]
+    return aid
+
+
+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:
+            return m
+    for m in extract.get('media') or []:
+        if os.path.basename(m['media']) == source_media:
+            return m
+    return None
+
+
+def image_row_of(extract, source_media):
+    for i in extract.get('images') or []:
+        if os.path.basename(i['media']) == source_media:
+            return i
+    # An svg that ships as a raster's vector companion has no images[] row of its
+    # own — the placement is recorded on the raster (a:blip embeds the png, the svg
+    # rides in a:extLst/svgBlip). Its boxes therefore come from the companion.
+    for i in extract.get('images') or []:
+        comp = i.get('svg_companion')
+        if comp and os.path.basename(comp) == source_media:
+            return i
+    return None
+
+
+def place_assets(manifest, extract, stage1, pack):
+    """拷贝资产 + 生成 design.md 的 assets 段 + audit.yaml 的 assets 段。"""
+    consumer, audit, copied = {}, {}, []
+    for a in manifest['assets']:
+        a = dict(a)
+        for f in ('id', 'kind', 'source_media', 'use_full', 'mark', 'confidence'):
+            if f in a:
+                a[f] = unquote(a[f])
+        aid = a.get('id')
+        if not aid:
+            raise Fail('assets 里有条目缺 id')
+        kind = a.get('kind')
+        if kind not in KIND_PREFIX:
+            raise Fail('%s: kind=%r 不在 %s 内' % (aid, kind, sorted(KIND_PREFIX)))
+        entry = {'kind': kind}
+        for f in ('role', 'theme', 'on-bg', 'recipe'):
+            if a.get(f):
+                entry[f] = a[f]
+
+        if a.get('color'):
+            entry['color'] = a['color']            # 纯色背景，不落文件
+        elif a.get('url'):
+            entry['url'] = a['url']
+        elif a.get('source_media'):
+            src = a['source_media']
+            row = media_row_of(extract, src)
+            if row is None or not row.get('out'):
+                raise Fail('%s: media-out 里找不到 %s（extract.json media 无该导出行；'
+                           '非候选图需先用 extract.py --export-all-media 补导）' % (aid, src))
+            base = strip_kind_prefix(aid, kind)
+            sub = os.path.join(pack, 'assets', kind + 's')
+            os.makedirs(sub, exist_ok=True)
+            comp = row.get('compressed_out')
+            orig_path = os.path.join(stage1, row['out'])
+            if comp:
+                comp_path = os.path.join(stage1, comp)
+                cext = asset_ext(comp)
+                dst = os.path.join(sub, '%s.%s' % (base, cext))
+                shutil.copy2(comp_path, dst)
+                copied.append(dst)
+                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)
+            else:
+                oext = asset_ext(row['out'])
+                dst = os.path.join(sub, '%s.%s' % (base, oext))
+                shutil.copy2(orig_path, dst)
+                copied.append(dst)
+                entry['path'] = 'assets/%ss/%s.%s' % (kind, base, oext)
+                if truthy(a.get('use_full')):
+                    raise Fail('%s: use_full=true 但 %s 没有压缩版产物，'
+                               'path/full 会指向同一文件' % (aid, src))
+        else:
+            raise Fail('%s: 必须给 source_media / color / url 之一' % aid)
+
+        consumer[aid] = entry
+        # ---- 审计数据全部机器算，L 层不碰
+        au = {}
+        if a.get('source_media'):
+            img = image_row_of(extract, a['source_media'])
+            if img:
+                # 首项为主位 = 出现次数最多者；次数打平时按阅读顺序（上→下、左→右）
+                # 定序，避免同频簇的先后取决于字典插入顺序。
+                clusters = sorted(img.get('boxes') or [],
+                                  key=lambda c: (-c['count'], c['box']['y'], c['box']['x']))
+                boxes = [[int(round(c['box'][k])) for k in ('x', 'y', 'w', 'h')]
+                         for c in clusters]
+                if boxes:
+                    au['boxes'] = boxes
+                    # aspect 取**未取整**的 box —— 从取整后的整数反算会明显偏
+                    # 先取整再相除，误差会落到小数点后两位，logo 这种细长框尤其明显。
+                    raw = clusters[0]['box']
+                    if raw.get('h'):
+                        au['aspect'] = round(raw['w'] / float(raw['h']), 3)
+        if a.get('mark'):
+            au['mark'] = a['mark']
+        au['confidence'] = a.get('confidence') or 'high'
+        audit[aid] = au
+    return consumer, audit, copied
+
+
+def _pages_of(extract, source_media):
+    img = image_row_of(extract, source_media) if source_media else None
+    if not img:
+        return []
+    pages = set()
+    for c in img.get('boxes') or []:
+        for p in c.get('parts') or []:
+            m = re.search(r'slide(\d+)\.xml$', p)
+            if m and '/slides/' in p:
+                pages.add(int(m.group(1)))
+    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 层手抄（抄错就是死链）。"""
+    if '{{ASSET_TABLE}}' in body:
+        rows = ['| 资产 | 文件 | 什么时候用 |', '|---|---|---|']
+        src_of = {unquote(a.get('id', '')): a.get('source_media') for a in manifest['assets']}
+        for aid, e in consumer.items():
+            pages = _pages_of(extract, src_of.get(aid))
+            box = (audit.get(aid) or {}).get('boxes') or []
+            # 单元格保持短句：哪个页型用哪张由 `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:
+                # 位置逐页型不同（同一 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'):
+                f += '（原图 `%s`）' % e['full']
+            rows.append('| `%s` | %s | %s |' % (aid, f, when))
+        body = body.replace('{{ASSET_TABLE}}', '\n'.join(rows))
+    if '{{LAYOUT_LIST}}' in body:
+        rows, sect, names = [], None, {}
+        for line in (layouts_text or '').split('\n'):
+            if re.match(r'^\w[\w-]*:\s*$', line):
+                sect = line.split(':')[0]
+                continue
+            m = re.match(r'^  ([\w-]+):\s*(.*)$', line)
+            if not m:
+                m2 = re.match(r'^    name:\s*(.+?)\s*$', line)
+                if m2 and rows and rows[-1][1] is None:
+                    rows[-1][1] = unquote(m2.group(1))
+                continue
+            if sect == 'names' and m.group(2).strip():
+                names[m.group(1)] = unquote(m.group(2))
+            elif sect == 'layouts' and not m.group(2).strip():
+                rows.append(['- `%s`' % m.group(1), names.get(m.group(1))])
+        rows = ['%s —— %s' % (k, n) if n else k for k, n in rows]
+        body = body.replace('{{LAYOUT_LIST}}', '\n'.join(rows) or '（无 archetype）')
+    return body
+
+
+def render_assets_block(consumer):
+    out = ['assets:']
+    for aid, entry in consumer.items():
+        out.append('  %s:' % aid)
+        for f in ASSET_CONSUMER_FIELDS:
+            if f in entry:
+                out.append('    %s: %s' % (f, yaml_scalar(entry[f])))
+    return out
+
+
+# ------------------------------------------------- 数值可追溯机检（抄错即 FAIL）
+HEX_RE = re.compile(r'#([0-9A-Fa-f]{6})\b')
+FONTSIZE_RE = re.compile(r'\bfontSize:\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*(.*)$')
+DOMINANT_TOL = 8         # 采样主色的每通道容差（量化误差天然存在）
+BOX_TOL = 2.0            # slot 坐标逐维容差
+SIZE_TOL = 0.51          # 字号容差（px 取整误差）
+REBASE_TOL = 1.0         # 等比上抬后的字号容差
+
+
+def _hex2rgb(h):
+    h = h.lstrip('#')
+    return int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
+
+
+def frontmatter_of(path):
+    if not os.path.exists(path):
+        return ''
+    t = open(path, encoding='utf-8').read()
+    parts = t.split('---\n')
+    return parts[1] if len(parts) >= 3 else ''
+
+
+def _scan_keyed(text):
+    """逐行产出 (行号, 该行祖先键路径, 行内容)，供 token 级豁免定位。"""
+    stack = []
+    for i, raw in enumerate(text.splitlines(), 1):
+        m = KEYLINE_RE.match(raw)
+        if m:
+            indent = len(m.group(1))
+            while stack and stack[-1][0] >= indent:
+                stack.pop()
+            path = [k for _, k in stack] + [m.group(2)]
+            stack.append((indent, m.group(2)))
+            yield i, path, raw
+        else:
+            yield i, [k for _, k in stack], raw
+
+
+def build_trace_index(extract, shapes):
+    """可命中集合：色 / 字号 / 形状框。"""
+    hexes, dominant = set(), []
+    for c in extract.get('color_freq') or []:
+        for k in ('resolved', 'hex'):
+            v = c.get(k)
+            if isinstance(v, str) and v.startswith('#') and len(v) == 7:
+                hexes.add(v.upper())
+    # 主题 clrScheme 也是普查值：出厂色常被「排除色」条款正面引用（页面频次为 0
+    # 恰恰是它要论证的事），不收进来会把这类正确引用误判成抄错。
+    for t in extract.get('themes') or []:
+        for v in (t.get('clrScheme') or {}).values():
+            if isinstance(v, str) and v.startswith('#') and len(v) == 7:
+                hexes.add(v.upper())
+
+    def eat_fill(f):
+        if not isinstance(f, dict):
+            return
+        col = f.get('color') or {}
+        for k in ('resolved', 'hex'):
+            v = col.get(k) if isinstance(col, dict) else None
+            if isinstance(v, str) and v.startswith('#') and len(v) == 7:
+                hexes.add(v.upper())
+        for st in f.get('stops') or []:                 # 渐变 stop 色
+            eat_fill(st if 'color' in st else {'color': st})
+
+    for grp in ('slides', 'layouts'):
+        for row in extract.get(grp) or []:
+            eat_fill(row.get('background'))
+    for s in shapes:
+        eat_fill(s.get('fill'))
+        ln = s.get('line') or {}
+        eat_fill(ln)
+        eat_fill(ln.get('gradient'))
+    for i in extract.get('images') or []:
+        for dc in i.get('dominant_colors') or []:
+            if dc.get('hex'):
+                dominant.append((_hex2rgb(dc['hex']), dc['hex'].upper()))
+
+    sizes = sorted({e['sz_px'] for e in extract.get('text_scale') or []
+                    if e.get('sz_px')})
+    boxes = []
+    for s in shapes:
+        b = s.get('box')
+        if b and b.get('w') is not None:
+            boxes.append((b['x'], b['y'], b['w'], b['h'],
+                          '%s %s' % (os.path.basename(s['part']), s.get('name') or s['kind'])))
+    return {'hexes': hexes, 'dominant': dominant, 'sizes': sizes, 'boxes': boxes}
+
+
+def _hex_hit(value, idx):
+    v = value.upper()
+    if v in idx['hexes']:
+        return True, None
+    rgb = _hex2rgb(v)
+    best, bestd = None, None
+    for drgb, dhex in idx['dominant']:
+        d = max(abs(a - b) for a, b in zip(rgb, drgb))
+        if d <= DOMINANT_TOL:
+            return True, None
+        if bestd is None or d < bestd:
+            best, bestd = dhex, d
+    for h in idx['hexes']:
+        d = max(abs(a - b) for a, b in zip(rgb, _hex2rgb(h)))
+        if bestd is None or d < bestd:
+            best, bestd = h, d
+    return False, ('最近 %s（每通道差 %d）' % (best, bestd) if best else '普查里无任何色值')
+
+
+def _size_hit(v, idx, factor):
+    for s in idx['sizes']:
+        if abs(s - v) <= SIZE_TOL:
+            return True, None
+        if factor and abs(s * factor - v) <= REBASE_TOL:
+            return True, None
+    if not idx['sizes']:
+        return False, '普查里无字号'
+    near = min(idx['sizes'], key=lambda s: abs(s - v))
+    tip = '最近 %gpx' % near
+    if factor:
+        nf = min(idx['sizes'], key=lambda s: abs(s * factor - v))
+        tip += '；×%g 后最近 %gpx→%.1f' % (factor, nf, nf * factor)
+    return False, tip
+
+
+def _box_hit(box, idx):
+    best, bestd = None, None
+    for x, y, w, h, tag in idx['boxes']:
+        d = max(abs(box[0] - x), abs(box[1] - y), abs(box[2] - w), abs(box[3] - h))
+        if d <= BOX_TOL:
+            return True, None
+        if bestd is None or d < bestd:
+            best, bestd = (x, y, w, h, tag), d
+    if best is None:
+        return False, 'shapes.json 无形状'
+    return False, ('最近 [%g, %g, %g, %g]（%s，最大维差 %.1fpx）'
+                   % (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)
+    problems, checked = [], Counter()
+    targets = [('design.md', frontmatter_of(os.path.join(pack, 'design.md'))),
+               ('layouts.md', frontmatter_of(os.path.join(pack, 'layouts.md')))]
+    for fname, text in targets:
+        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()
+                checked['hex'] += 1
+                if exempt_token or val in derived_values:
+                    checked['exempt'] += 1
+                    continue
+                ok, tip = _hex_hit(val, idx)
+                if not ok:
+                    problems.append(('hex', fname, lineno, val, tip, '.'.join(path)))
+            for m in FONTSIZE_RE.finditer(raw):
+                val = float(m.group(1))
+                checked['size'] += 1
+                if exempt_token or m.group(1) in derived_values:
+                    checked['exempt'] += 1
+                    continue
+                ok, tip = _size_hit(val, idx, factor)
+                if not ok:
+                    problems.append(('fontSize', fname, lineno, '%gpx' % val, tip,
+                                     '.'.join(path)))
+            for m in BOX_RE.finditer(raw):
+                box = [float(x) for x in m.groups()]
+                checked['box'] += 1
+                key = '[%s]' % ', '.join(m.groups())
+                if exempt_token or key in derived_values:
+                    checked['exempt'] += 1
+                    continue
+                ok, tip = _box_hit(box, idx)
+                if not ok:
+                    problems.append(('slot box', fname, lineno,
+                                     '[%g, %g, %g, %g]' % tuple(box), tip, '.'.join(path)))
+    return problems, checked
+
+
+def render_audit(manifest, extract, audit):
+    L = ['# 审计元数据（从 design.md 剥离，消费模型不需要；机检与人工复核用）']
+    src = extract['canvas']['source']
+    L.append('canvas-source: {cx: %d, cy: %d, unit: %s}'
+             % (src['cx'], src['cy'], src.get('unit', 'EMU')))
+    for k in ('theme-mechanism', 'color-confidence'):
+        if manifest.get(k):
+            L.append('%s: %s' % (k, yaml_scalar(manifest[k])))
+    if audit:
+        L.append('assets:')
+        for aid, au in audit.items():
+            L.append('  %s:' % aid)
+            if au.get('boxes'):
+                L.append('    boxes:')
+                for b in au['boxes']:
+                    L.append('    - [%d, %d, %d, %d]' % tuple(b))
+            for f in ('aspect', 'mark', 'confidence'):
+                if f in au:
+                    L.append('    %s: %s' % (f, yaml_scalar(au[f])))
+    return '\n'.join(L) + '\n'
+
+
+def _sha256(path):
+    h = hashlib.sha256()
+    with open(path, 'rb') as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b''):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _rel_files(root):
+    files = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames.sort()
+        for name in sorted(filenames):
+            path = os.path.join(dirpath, name)
+            files.append(os.path.relpath(path, root))
+    return files
+
+
+def build_package_manifest(manifest, consumer, audit, extract, pack):
+    """Machine index for the style package.
+
+    design.md remains the consumer entry. manifest.json is for storage/control
+    planes: stable identity plus file and asset checksums.
+    """
+    files = []
+    for rel in _rel_files(pack):
+        if rel == 'manifest.json':
+            continue
+        path = os.path.join(pack, rel)
+        files.append({
+            'path': rel,
+            'bytes': os.path.getsize(path),
+            'sha256': _sha256(path),
+        })
+
+    assets = []
+    for aid, entry in consumer.items():
+        item = {'id': aid, 'kind': entry.get('kind')}
+        for key in ('role', 'theme', 'on-bg', 'path', 'full', 'url', 'color'):
+            if entry.get(key):
+                item[key] = entry[key]
+        for key in ('path', 'full'):
+            rel = entry.get(key)
+            if rel:
+                path = os.path.join(pack, rel)
+                if os.path.exists(path):
+                    item[key + '_bytes'] = os.path.getsize(path)
+                    item[key + '_sha256'] = _sha256(path)
+        au = audit.get(aid) or {}
+        if au.get('confidence'):
+            item['confidence'] = au['confidence']
+        assets.append(item)
+
+    files_digest = hashlib.sha256()
+    for item in files:
+        files_digest.update(item['path'].encode('utf-8'))
+        files_digest.update(b'\0')
+        files_digest.update(item['sha256'].encode('ascii'))
+        files_digest.update(b'\0')
+        files_digest.update(str(item['bytes']).encode('ascii'))
+        files_digest.update(b'\n')
+
+    pkg = {
+        'schemaVersion': 'pptx-style-package/v2',
+        'id': manifest.get('name'),
+        'name': manifest.get('name'),
+        'name_zh': manifest.get('name_zh'),
+        'version': manifest.get('version') or 'alpha',
+        'description': manifest.get('description'),
+        'entry': 'design.md',
+        'layouts': 'layouts.md' if os.path.exists(os.path.join(pack, 'layouts.md')) else None,
+        'canvas': '%dx%d' % tuple(extract['canvas']['px']),
+        'source': {
+            'filename': (extract.get('source') or {}).get('filename'),
+            'content_type_kind': (extract.get('source') or {}).get('content_type_kind'),
+            'is_template': (extract.get('source') or {}).get('is_template'),
+            'bytes': (extract.get('source') or {}).get('bytes'),
+        },
+        'themes': manifest.get('themes') or ['single'],
+        'default_theme': manifest.get('default-theme'),
+        'files': files,
+        'assets': assets,
+        'totals': {
+            'file_count': len(files),
+            'bytes': sum(f['bytes'] for f in files),
+            'sha256': files_digest.hexdigest(),
+            'asset_count': len(assets),
+        },
+    }
+    return {k: v for k, v in pkg.items() if v is not None}
+
+
+def strip_agent_fast_path(body):
+    if '## Agent Fast Path' not in body:
+        return body
+    return re.sub(r'\n?## Agent Fast Path\n.*?(?=\n## |\Z)', '\n', body,
+                  count=1, flags=re.S).lstrip('\n')
+
+
+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:
+        raise Fail('frontmatter.yaml 出现不该由 L 层提供的顶层键: %s'
+                   '（身份键写 manifest.yaml，assets/layouts 由脚本生成）'
+                   % ', '.join(sorted(bad)))
+    out = ['---']
+    for key in FRONTMATTER_ORDER:
+        if key in ('version', 'name', 'name_zh', 'description'):
+            block = (manifest.get('_raw') or {}).get(key)
+            if block:
+                out.append('%s:%s' % (key, (' ' + block[0]) if block[0] else ''))
+                out += block[1]
+                continue
+            v = manifest.get(key) or ('alpha' if key == 'version' else None)
+            if v:
+                out.append('%s: %s' % (key, yaml_scalar(v)))
+        elif key in ('themes', 'default-theme'):
+            v = manifest.get(key)
+            if isinstance(v, list):
+                out.append('%s: [%s]' % (key, ', '.join(v)))
+            elif v:
+                out.append('%s: %s' % (key, yaml_scalar(v)))
+        elif key == 'assets':
+            if consumer:
+                out += render_assets_block(consumer)
+        elif key == 'layouts':
+            if has_sidecar:
+                out.append('layouts: layouts.md')
+        elif key in blocks:
+            inline, lines = blocks[key]
+            out.append('%s:%s' % (key, (' ' + inline) if inline else ''))
+            out += lines
+        if key == 'exceptions' and not has_sidecar and 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)
+    if body:
+        text += body if body.startswith('\n') else '\n' + body
+    if not text.endswith('\n'):
+        text += '\n'
+    return text
+
+
+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:` / `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:
+            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
+    out.append('layouts:')
+    for line in blocks['layouts'][1]:
+        # 判断单里的结构事实（栅格、间距序列、样张字数、命中配方）是给 L 层判断用的，
+        # 不进产物——消费端要的是结论，不是推导过程。
+        if line.lstrip().startswith('#'):
+            continue
+        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))
+    # flow 与 slots 二选一：两份都留下，消费端不知道该听哪份坐标——design.md 正文与
+    # layouts.md 打架就是这么来的，别重演。
+    both, cur, has = [], None, {}
+    for line in blocks['layouts'][1]:
+        m = re.match(r'^  ([\w-]+):\s*$', line)
+        if m:
+            if cur and has.get('flow') and has.get('slots'):
+                both.append(cur)
+            cur, has = m.group(1), {}
+            continue
+        m = re.match(r'^    (flow|slots):\s*$', line)
+        if m:
+            has[m.group(1)] = True
+    if cur and has.get('flow') and has.get('slots'):
+        both.append(cur)
+    if both:
+        raise Fail('这些页型同时留了 flow 和 slots，二选一删掉另一个：%s' % ', '.join(both))
+    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:
+        body = scalar_of(blocks['body'][0], blocks['body'][1])
+        if body:
+            text += '\n' + body.rstrip('\n') + '\n'
+    return text
+
+
+# --------------------------------------------------------------------- 主流程
+
+def _autodetect_check_v1():
+    skill_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    for cand in (os.environ.get('DSM_V1_DIR'),
+                 os.path.join(os.path.dirname(skill_root), 'miaoda-design-system-extract'),
+                 os.path.expanduser('~/dev/gitlab/miaoda_workspace/.agents/skills/miaoda-design-system-extract')):
+        if cand and os.path.isfile(os.path.join(cand, 'scripts', 'check_v1.py')):
+            return os.path.join(cand, 'scripts', 'check_v1.py')
+    return None
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(add_help=True)
+    ap.add_argument('stage1')
+    ap.add_argument('lout')
+    ap.add_argument('pack')
+    ap.add_argument('--check-v1', default=None, help='check_v1.py 路径；缺省自动探测（$DSM_V1_DIR → 同级 skill → 开发机路径）')
+    ap.add_argument('--style-name', default=None)
+    ap.add_argument('--force', action='store_true')
+    args = ap.parse_args(argv)
+
+    stage1, lout, pack = (os.path.abspath(p) for p in (args.stage1, args.lout, args.pack))
+    ex_path = os.path.join(stage1, 'extract.json')
+    if not os.path.exists(ex_path):
+        raise Fail('找不到 %s' % ex_path)
+    extract = json.load(open(ex_path, encoding='utf-8'))
+
+    need = ['manifest.yaml', 'frontmatter.yaml', 'body.md']
+    for f in need:
+        if not os.path.exists(os.path.join(lout, f)):
+            raise Fail('判断单缺 %s（schema 见本脚本 docstring）' % f)
+    if os.path.isdir(pack) and os.listdir(pack) and not args.force:
+        raise Fail('%s 非空；加 --force 覆盖' % pack)
+
+    left = []
+    for f in ('manifest.yaml', 'frontmatter.yaml', 'layouts.yaml', 'body.md'):
+        p = os.path.join(lout, f)
+        if not os.path.exists(p):
+            continue
+        for i, line in enumerate(open(p, encoding='utf-8'), 1):
+            if 'TODO' in line:
+                left.append('%s:%d  %s' % (f, i, line.strip()[:90]))
+    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:
+        manifest['name'] = args.style_name
+    if not manifest.get('name'):
+        raise Fail('manifest.yaml 缺 name')
+    themes = manifest.get('themes')
+    if isinstance(themes, list) and len(themes) > 1 and not manifest.get('default-theme'):
+        raise Fail('themes 有 %d 个主题，必须给 default-theme（V2-13）' % len(themes))
+
+    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)
+    canvas = extract['canvas']['px']
+
+    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 ''
+    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)
+    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/` 里的东西
+    # 没有任何门禁读、消费模型也用不上，放进去只会让「别读我」和「几 MB 材料」同时下发。
+    ref = os.path.join(stage1, 'ref')
+    os.makedirs(ref, exist_ok=True)
+    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 = []
+    # L 层自备的 ref 补充件（判断理由、版式溯源等）也归到抽取目录
+    l_ref = os.path.join(lout, 'ref')
+    if os.path.isdir(l_ref):
+        shutil.copytree(l_ref, ref, dirs_exist_ok=True)
+        carried.append('(L 层 ref/)')
+
+    with open(os.path.join(pack, 'manifest.json'), 'w', encoding='utf-8') as f:
+        json.dump(build_package_manifest(manifest, consumer, audit, extract, pack),
+                  f, ensure_ascii=False, indent=2, sort_keys=True)
+        f.write('\n')
+
+    print('pack → %s' % pack)
+    print('  design.md %d 行 / %.1f KB%s'
+          % (len(design.splitlines()), len(design.encode()) / 1024.0,
+             '   layouts.md sidecar' if layouts_blocks is not None else '   (layouts 内联/缺省)'))
+    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('  审计记录 -> %s%s（不进交付包）'
+          % (os.path.relpath(audit_path, os.path.dirname(stage1)),
+             '  ' + ', '.join(carried) if carried else ''))
+
+    # ---- 数值可追溯机检：产物里每个色值/字号/坐标都得能指回普查值
+    derived_values, derived_tokens = set(), set()
+    for d in manifest.get('derived') or []:
+        if d.get('value'):
+            v = unquote(d['value'])
+            derived_values.add(v.upper() if v.startswith('#') else v)
+        if d.get('token'):
+            derived_tokens.add(unquote(d['token']))
+    try:
+        factor = float(manifest.get('rebase_factor') or 0) or None
+    except ValueError:
+        raise Fail('rebase_factor 不是数字: %r' % manifest.get('rebase_factor'))
+    sp = os.path.join(stage1, 'ref', 'shapes.json')
+    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%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)
+    trace_rc = 0
+    if problems:
+        trace_rc = 1
+        print('  FAIL %d 处数值无法追溯（既不命中普查值，也没在 manifest 的 derived 里声明）：'
+              % len(problems))
+        for kind, fname, lineno, val, tip, path in problems:
+            print('    %s:%d  %s %s  ← %s' % (fname, lineno, kind, val, path))
+            print('        %s' % (tip or ''))
+        print('  修法二选一：改成命中的值，或在 manifest.yaml 的 derived: 段声明推导理由。')
+    else:
+        print('  PASS 全部可追溯')
+
+    rc = trace_rc
+    print('\n--- check_v2 ---')
+    sys.stdout.flush()          # 子进程直写 fd，不 flush 会让本脚本的输出排在其后
+    r = subprocess.run([sys.executable, os.path.join(HERE, 'check_v2.py'), pack])
+    rc = rc or r.returncode
+    if not args.check_v1:
+        args.check_v1 = _autodetect_check_v1()
+        if not args.check_v1:
+            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
+    if rc:
+        print('\n门禁未过（exit %d）。回修属 L 层的事：改判断单后重跑本脚本。' % rc)
+    return rc
+
+
+if __name__ == '__main__':
+    sys.exit(main())