@lark-apaas/coding-steering 0.1.31 → 0.1.32-beta.0

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

@@ -0,0 +1,1120 @@
+#!/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: image-1-1.jpeg  # 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: "#2D5A8E"
+    safe-area:
+      content: {top: 60, right: 90, bottom: 113, left: 90, 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: [257, 313, 1406, 130], 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'}
+# stage1 ref/ 里随包分发的审计件（其余如 shapes.json 体量大、不进包）
+REF_CARRY = ('color-freq-raw.json', 'font-clusters.json', 's5-acceptance.json',
+             'content-clusters.json', 'notes.md')
+
+
+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 —— 从取整后的整数反算会明显偏
+                    # （volcano logo 224.1/47.8=4.688，用 224/48 算成 4.667）。
+                    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 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 []
+            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 '，每页固定放一次')
+            else:
+                when = '按 `%s` 的语义使用' % e['kind']
+            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))
+
+
+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):
+            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 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
+    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,
+                 layouts_index=None):
+    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'
+    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'):
+        text += '\n'
+    return text
+
+
+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)
+        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)
+        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 names:
+        raise Fail('names 里这些页型在 layouts 下找不到：%s' % ', '.join(sorted(names)))
+    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)))
+
+    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)
+    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)
+    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')
+    os.makedirs(ref, exist_ok=True)
+    with open(os.path.join(ref, 'audit.yaml'), '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 = 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('  ref/ %s' % ', '.join(carried))
+
+    # ---- 数值可追溯机检：产物里每个色值/字号/坐标都得能指回普查值
+    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)
+    print('\n--- 数值可追溯机检 ---')
+    print('  受检 hex %d / fontSize %d / slot box %d；derived 豁免 %d%s'
+          % (checked['hex'], checked['size'], checked['box'], checked['exempt'],
+             '；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 ---')
+        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())