@lark-apaas/coding-steering 0.1.32-dev.4f80f68 → 0.1.32-dev.942e73f

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

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Regression tests for template logo placement in generated deck HTML."""
+import os
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from verify_logo_scope import validate_logo_scope
+
+
+class LogoScopeTest(unittest.TestCase):
+    def write_pack(self, root):
+        with open(os.path.join(root, 'design.md'), 'w', encoding='utf-8') as stream:
+            stream.write(
+                '---\n'
+                'assets:\n'
+                '  logo-1:\n'
+                '    path: assets/logos/1.png\n'
+                '    kind: logo\n'
+                'layouts: layouts.md\n'
+                '---\n'
+            )
+        with open(os.path.join(root, 'layouts.md'), 'w', encoding='utf-8') as stream:
+            stream.write(
+                '---\n'
+                'canvas: 1920x1080\n'
+                'layouts:\n'
+                '  cover:\n'
+                '    role: cover\n'
+                '    slots:\n'
+                '      - {role: logo, box: [64, 64, 224, 48], type: pic, asset: logo-1}\n'
+                '  content:\n'
+                '    role: content\n'
+                '    slots:\n'
+                '      - {role: title, box: [100, 100, 800, 100], type: title}\n'
+                '  closing:\n'
+                '    role: closing\n'
+                '    slots:\n'
+                '      - {role: logo, box: [64, 64, 224, 48], type: pic, asset: logo-1}\n'
+                '---\n'
+            )
+
+    def write_html(self, root, content):
+        path = os.path.join(root, 'index.html')
+        with open(path, 'w', encoding='utf-8') as stream:
+            stream.write(content)
+        return path
+
+    def test_logo_is_limited_to_every_archetype_with_its_slot(self):
+        with tempfile.TemporaryDirectory() as root:
+            self.write_pack(root)
+            html = self.write_html(
+                root,
+                '<deck-stage>'
+                '<section data-pptx-layout="cover">'
+                '<img src="assets/pptx-volcengine/logos/1.png"></section>'
+                '<section data-pptx-layout="content"><h1>正文</h1></section>'
+                '<section data-pptx-layout="closing">'
+                '<img src="assets/pptx-volcengine/logos/1.png"></section>'
+                '</deck-stage>',
+            )
+
+            self.assertEqual(
+                [],
+                validate_logo_scope(root, html, 'assets/pptx-volcengine'),
+            )
+
+    def test_logo_on_an_unowned_archetype_is_rejected(self):
+        with tempfile.TemporaryDirectory() as root:
+            self.write_pack(root)
+            html = self.write_html(
+                root,
+                '<deck-stage>'
+                '<section data-pptx-layout="content">'
+                '<img src="assets/pptx-volcengine/logos/1.png"></section>'
+                '</deck-stage>',
+            )
+
+            problems = validate_logo_scope(root, html, 'assets/pptx-volcengine')
+
+            self.assertEqual(1, len(problems))
+            self.assertIn('content', problems[0])
+            self.assertIn('logo-1', problems[0])
+
+    def test_nested_content_section_does_not_become_a_slide(self):
+        with tempfile.TemporaryDirectory() as root:
+            self.write_pack(root)
+            html = self.write_html(
+                root,
+                '<deck-stage><section data-pptx-layout="cover">'
+                '<section class="content"><img src="assets/pptx-volcengine/logos/1.png">'
+                '</section></section></deck-stage>',
+            )
+
+            self.assertEqual(
+                [],
+                validate_logo_scope(root, html, 'assets/pptx-volcengine'),
+            )
+
+    def test_each_slide_declares_its_template_archetype(self):
+        with tempfile.TemporaryDirectory() as root:
+            self.write_pack(root)
+            html = self.write_html(
+                root,
+                '<deck-stage><section><h1>未声明页型</h1></section></deck-stage>',
+            )
+
+            self.assertEqual(
+                ['第 1 页缺少 data-pptx-layout，无法核验模板 logo 归属'],
+                validate_logo_scope(root, html, 'assets/pptx-volcengine'),
+            )
+
+    def test_logo_in_global_css_is_rejected(self):
+        with tempfile.TemporaryDirectory() as root:
+            self.write_pack(root)
+            html = self.write_html(
+                root,
+                '<style>.slide-logo { background-image: url('
+                '"assets/pptx-volcengine/logos/1.png") }</style>'
+                '<deck-stage><section data-pptx-layout="content">正文</section></deck-stage>',
+            )
+
+            self.assertEqual(
+                ['模板 logo logo-1 出现在 slide section 外，无法核验页型归属'],
+                validate_logo_scope(root, html, 'assets/pptx-volcengine'),
+            )
+
+    def test_logo_in_a_slide_style_block_is_rejected(self):
+        with tempfile.TemporaryDirectory() as root:
+            self.write_pack(root)
+            html = self.write_html(
+                root,
+                '<deck-stage><section data-pptx-layout="content"><style>'
+                '.slide-logo { background-image: url('
+                '"assets/pptx-volcengine/logos/1.png") }</style>'
+                '正文</section></deck-stage>',
+            )
+
+            self.assertEqual(
+                ['模板 logo logo-1 出现在 slide section 外，无法核验页型归属'],
+                validate_logo_scope(root, html, 'assets/pptx-volcengine'),
+            )
+
+
+if __name__ == '__main__':
+    unittest.main()

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

@@ -2,6 +2,7 @@
 """Regression tests for inherited layout text and model-decided text roles."""
 import json
 import os
+import re
 import sys
 import tempfile
 import unittest
@@ -142,16 +143,16 @@ class TextRoleContractTest(unittest.TestCase):
             with open(path, encoding='utf-8') as stream:
                 draft = stream.read()
 
-        self.assertIn('text_roles:', draft)
+        self.assertIn('默认均为 body', draft)
         self.assertIn(
-            'layout-1-text-1: TODO文本角色',
+            '# text-role: layout-1-text-1',
             draft,
         )
         self.assertEqual(draft.count('box: [120, 80, 840, 120]'), 1)
 
         decided = draft.replace(
-            'layout-1-text-1: TODO文本角色',
-            'layout-1-text-1: title',
+            'layouts:',
+            'text_roles:\n  layout-1-text-1: title\nlayouts:',
         )
         layouts_md = build_layouts_md(split_top_blocks(decided), (1920, 1080))
 
@@ -163,6 +164,152 @@ class TextRoleContractTest(unittest.TestCase):
         )
         self.assertIn('css: "font-size: 48px; color: #C41230"', layouts_md)
 
+    def test_header_role_uses_a_v2_slot_type(self):
+        draft = """names:
+  layout-1: 内容页
+roles:
+  layout-1: content
+text_roles:
+  layout-1-text-1: header
+layouts:
+  layout-1:
+    slots:
+      # text-role: layout-1-text-1
+      - {role: body, box: [120, 80, 840, 120], type: body}
+    confidence: high
+"""
+
+        layouts_md = build_layouts_md(split_top_blocks(draft), (1920, 1080))
+
+        self.assertIn(
+            'role: header, box: [120, 80, 840, 120], type: body',
+            layouts_md,
+        )
+        self.assertNotIn('type: header', layouts_md)
+
+    def test_decided_layout_role_replaces_the_draft_default(self):
+        draft = """names:
+  layout-1: 末页
+roles:
+  layout-1: closing
+layouts:
+  layout-1:
+    role: content
+    slots:
+      - {role: title, box: [120, 80, 840, 120], type: title}
+    confidence: high
+"""
+
+        layouts_md = build_layouts_md(split_top_blocks(draft), (1920, 1080))
+
+        self.assertIn('    role: closing', layouts_md)
+        self.assertNotIn('    role: content', layouts_md)
+        self.assertEqual(layouts_md.count('    role:'), 1)
+
+    def test_last_slide_is_kept_as_a_role_candidate_when_layout_limit_is_full(self):
+        shapes, slides = [], []
+        for index in range(1, 11):
+            slide_part = 'ppt/slides/slide%d.xml' % index
+            shapes.append(text_shape(
+                slide_part,
+                'slide',
+                str(index),
+                {'x': 120, 'y': 80, 'w': 840, 'h': 120},
+                'Slide %d' % index,
+                {'type': 'body', 'idx': str(index)},
+            ))
+            slides.append({
+                'part': slide_part,
+                'layout': 'ppt/slideLayouts/slideLayout1.xml',
+                'background': '#%02x0000' % index,
+            })
+        data = {
+            'canvas': {'px': [1920, 1080]},
+            'form_hint': {'form': 0},
+            'slides': slides,
+            'background_composites': {},
+        }
+
+        with tempfile.TemporaryDirectory() as output_dir:
+            os.makedirs(os.path.join(output_dir, 'ref'))
+            with open(os.path.join(output_dir, 'ref', 'shapes.json'), 'w',
+                      encoding='utf-8') as stream:
+                json.dump({'shapes': shapes}, stream)
+            archetypes, _, leftover = draft_layouts(data, output_dir)
+            emit_layouts(archetypes, output_dir)
+            with open(os.path.join(output_dir, 'layouts.yaml'), encoding='utf-8') as stream:
+                draft = stream.read()
+
+        last_archetype = next(
+            archetype for archetype in archetypes if archetype['pages'] == [10]
+        )
+        self.assertTrue(last_archetype['_last_page_candidate'])
+        self.assertNotIn(10, leftover)
+        self.assertIn(
+            '代表页 %s，共 1 页；' % last_archetype['rep'],
+            draft,
+        )
+        self.assertIn('末页候选，结合样张判断 closing 或实际角色', draft)
+        decided = draft.replace(
+            '%s: TODO角色' % last_archetype['name'],
+            '%s: closing' % last_archetype['name'],
+        )
+        layouts_md = build_layouts_md(split_top_blocks(decided), (1920, 1080))
+        self.assertRegex(
+            layouts_md,
+            r'  %s:\n(?:    .*\n)*?    role: closing\n'
+            % last_archetype['name'],
+        )
+        self.assertRegex(
+            layouts_md,
+            r'  %s:\n(?:    .*\n)*?      - \{role: body, box: \[120, 80, 840, 120\]'
+            % last_archetype['name'],
+        )
+        self.assertIn(
+            '  %s:' % last_archetype['name'],
+            layouts_md,
+        )
+
+    def test_template_layout_shape_without_ph_key_does_not_crash(self):
+        # form=3 模板里，版式层可能有「带 box、带文字、但没有 ph 键」的普通形状
+        # （非占位符的文本/装饰）。layouts_from_template 的入口筛选是
+        # `s.get('ph') or shape_text(s)`——有文字就放进来，随后按 ph 判类型时若用
+        # s['ph'] 直接下标就会 KeyError: 'ph'，整份抽取在草案阶段崩掉（EXTRACT_PARTIAL）。
+        layout_part = 'ppt/slideLayouts/slideLayout1.xml'
+        shape = {
+            'part': layout_part,
+            'layer': 'layout',
+            'id': '7',
+            'kind': 'sp',
+            'name': '页脚文字',
+            # 关键：没有 'ph' 键
+            'box': {'x': 100, 'y': 980, 'w': 800, 'h': 60},
+            'text': {
+                'bodyPr': {},
+                'lstStyle': {'lvl1pPr': {'sz_px': 20}},
+                'paragraphs': [{'runs': [{'text': '内部资料'}]}],
+            },
+        }
+        data = {
+            'canvas': {'px': [1920, 1080]},
+            'form_hint': {'form': 3},
+            'layouts': [{'part': layout_part}],
+            'slides': [{'part': 'ppt/slides/slide1.xml', 'layout': layout_part,
+                        'background': None}],
+            'background_composites': {},
+        }
+
+        with tempfile.TemporaryDirectory() as output_dir:
+            os.makedirs(os.path.join(output_dir, 'ref'))
+            with open(os.path.join(output_dir, 'ref', 'shapes.json'), 'w',
+                      encoding='utf-8') as stream:
+                json.dump({'shapes': [shape]}, stream)
+            # 修复前这里抛 KeyError: 'ph'（draft.py 用 s['ph'] 直接下标），
+            # 抽取在草案阶段崩掉、退成 EXTRACT_PARTIAL。修复后应正常返回。
+            archetypes, pages, leftover = draft_layouts(data, output_dir)
+
+        self.assertIsInstance(archetypes, list)
+
 
 if __name__ == '__main__':
     unittest.main()

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

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Verify that generated slides use template logos only on owning archetypes."""
+import argparse
+import posixpath
+import re
+import sys
+from html.parser import HTMLParser
+from urllib.parse import urlsplit
+
+from check_v2 import Pack
+
+
+URL_RE = re.compile(r'url\(\s*[\'"]?([^\'")\s]+)', re.I)
+VOID_TAGS = {
+    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+    'link', 'meta', 'param', 'source', 'track', 'wbr',
+}
+
+
+def normalized_path(value):
+    path = urlsplit(value).path.replace('\\', '/')
+    return posixpath.normpath(path).lstrip('./')
+
+
+def asset_urls(pack, asset_prefix):
+    prefix = normalized_path(asset_prefix).rstrip('/')
+    urls = {}
+    for asset_id, (entry, _) in pack.assets.items():
+        if not isinstance(entry, dict) or entry.get('kind') != 'logo':
+            continue
+        path = entry.get('path')
+        if not isinstance(path, str) or not path:
+            continue
+        relative = normalized_path(path)
+        if relative.startswith('assets/'):
+            relative = relative[len('assets/'):]
+        urls[posixpath.join(prefix, relative)] = asset_id
+    return urls
+
+
+def contains_asset(value, asset_id):
+    if isinstance(value, dict):
+        return (value.get('asset') == asset_id
+                or any(contains_asset(child, asset_id) for child in value.values()))
+    if isinstance(value, list):
+        return any(contains_asset(child, asset_id) for child in value)
+    return False
+
+
+def logo_owners(pack):
+    owners = {}
+    for asset_url, asset_id in asset_urls(pack, '').items():
+        del asset_url
+        owners[asset_id] = {
+            name
+            for name, (layout, _) in pack.layouts.items()
+            if contains_asset(layout, asset_id)
+        }
+    return owners
+
+
+def urls_from_attrs(attrs):
+    urls = []
+    for key, value in attrs:
+        if not value:
+            continue
+        if key.lower() in ('src', 'href'):
+            urls.append(value)
+        elif key.lower() == 'srcset':
+            urls.extend(item.strip().split(' ', 1)[0] for item in value.split(','))
+        elif key.lower() == 'style':
+            urls.extend(URL_RE.findall(value))
+    return urls
+
+
+class SlideAssetParser(HTMLParser):
+    def __init__(self):
+        super().__init__()
+        self.slides = []
+        self._tags = []
+        self._sections = []
+        self._active_slides = []
+        self._style_depth = 0
+        self.outside_urls = []
+
+    def handle_starttag(self, tag, attrs):
+        tag = tag.lower()
+        urls = urls_from_attrs(attrs)
+        parent = self._tags[-1] if self._tags else None
+        if tag == 'section':
+            slide = (
+                {'layout': dict(attrs).get('data-pptx-layout'), 'urls': urls}
+                if parent == 'deck-stage' else None
+            )
+            self._sections.append(slide)
+            if slide is not None:
+                self._active_slides.append(slide)
+        elif self._active_slides:
+            self._active_slides[-1]['urls'].extend(urls)
+        else:
+            self.outside_urls.extend(urls)
+        if tag == 'style':
+            self._style_depth += 1
+        if tag not in VOID_TAGS:
+            self._tags.append(tag)
+
+    def handle_startendtag(self, tag, attrs):
+        if self._active_slides:
+            self._active_slides[-1]['urls'].extend(urls_from_attrs(attrs))
+        else:
+            self.outside_urls.extend(urls_from_attrs(attrs))
+
+    def handle_endtag(self, tag):
+        tag = tag.lower()
+        if tag == 'style' and self._style_depth:
+            self._style_depth -= 1
+        if tag == 'section' and self._sections:
+            slide = self._sections.pop()
+            if slide is not None:
+                self.slides.append(slide)
+                self._active_slides.pop()
+        if tag not in VOID_TAGS and self._tags:
+            self._tags.pop()
+
+    def handle_data(self, data):
+        if not self._style_depth:
+            return
+        self.outside_urls.extend(URL_RE.findall(data))
+
+
+def validate_logo_scope(pack_dir, html_path, asset_prefix):
+    """Return every template-logo placement that does not match the slide archetype."""
+    pack = Pack(pack_dir)
+    known_urls = asset_urls(pack, asset_prefix)
+    owners = logo_owners(pack)
+    if not known_urls:
+        return []
+
+    with open(html_path, encoding='utf-8') as stream:
+        text = stream.read()
+    parser = SlideAssetParser()
+    parser.feed(text)
+    parser.close()
+
+    problems = []
+    for url in parser.outside_urls:
+        asset_id = known_urls.get(normalized_path(url))
+        if asset_id:
+            problems.append(
+                '模板 logo %s 出现在 slide section 外，无法核验页型归属' % asset_id)
+    for number, slide in enumerate(parser.slides, 1):
+        layout = slide['layout']
+        if not layout:
+            problems.append('第 %d 页缺少 data-pptx-layout，无法核验模板 logo 归属' % number)
+            continue
+        if layout not in pack.layouts:
+            problems.append('第 %d 页声明了不存在的模板页型: %s' % (number, layout))
+            continue
+        for url in slide['urls']:
+            asset_id = known_urls.get(normalized_path(url))
+            if asset_id and layout not in owners.get(asset_id, set()):
+                allowed = '、'.join(sorted(owners.get(asset_id) or ())) or '（无）'
+                problems.append(
+                    '第 %d 页页型 %s 不得使用 %s；只允许: %s'
+                    % (number, layout, asset_id, allowed))
+    return problems
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        description='Verify that generated deck HTML places PPTX logos only on owning layouts.')
+    parser.add_argument('pack_dir')
+    parser.add_argument('html_path')
+    parser.add_argument('--asset-prefix', required=True)
+    args = parser.parse_args(argv)
+
+    problems = validate_logo_scope(args.pack_dir, args.html_path, args.asset_prefix)
+    if not problems:
+        print('PPTX_LOGO_SCOPE: PASS')
+        return 0
+    print('PPTX_LOGO_SCOPE: FAIL count=%d' % len(problems))
+    for problem in problems:
+        print('[logoScope] %s' % problem)
+    return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/steering/design-html/skills/pptx-style-extract/v2-format-spec.md

@@ -133,7 +133,7 @@ layouts:
 
 - **`background` 三形态**：`<asset-id>` / `{<theme>: <asset-id>}` / `{color: <colors-token>}`（`color` 是保留键，主题名禁止叫 color）。`asset` 两形态：`<asset-id>` / `{<theme>: <asset-id>}`。
 - **背景安全扩展**：有真实背景图的 archetype 建议写 `text_safe: [x,y,w,h]`、`avoid: [{box: [x,y,w,h], reason: "..."}]`、`pairing_rule: "..."`。这些是消费约束，不参与封闭枚举；用于避免标题、正文、图表、卡片、表格、时间线及其容器外接矩形覆盖背景视觉主体、强光斑或深色透明区；透明容器也不能跨进禁放区。
-- **流式页型**：内容长度会变化的内容页可用 `flow.regions` 表达纵向区带。`stack` 表达单列顺序，`grid` 表达并列列组，`free` 中的 item 必须带 `box`，用于 logo、页码、页眉和页脚等固定锚点。并列卡片可在 `grid.items` 中使用一层 `{role: group, css, gap, items}`：group 的 `css` 是卡片容器样式，内部 `items` 按顺序排布；不继续嵌套 group。纵向位置与留白由消费模型结合实际内容决定，不把样张的 `y` 坐标当作流式硬约束。
+- **流式页型**：内容长度会变化的内容页可用 `flow.regions` 表达纵向区带。`stack` 表达单列顺序，`grid` 表达并列列组，`free` 中的 item 必须带 `box`，用于 logo、页码、页眉和页脚等固定锚点。并列卡片可在 `grid.items` 中使用一层 `{role: group, css, gap, items}`：group 的 `css` 是卡片容器样式，内部 `items` 按顺序排布；不继续嵌套 group。区带可带自己的 `margin: [左, 右]`，覆盖 `flow` 整块的 `margin`（居中卡片组和贴左标题横向范围本就不同）；不带则继承整块 `margin`。纵向位置与留白由消费模型结合实际内容决定，不把样张的 `y` 坐标当作流式硬约束。
 - **`decor`（可选）**：这一页无文字的图形骨架——图标托底的圆、卡片、分隔线。每条 `{box, geom, css}`：`box` 定位，`css` 是可直接写进 style 的声明串，`geom` 取源形状的 prst（`ellipse` 另加 `border-radius: 50%`）。圆角以每条 `css` 为准，没有 `border-radius` 就按 `0`；不得因 `geom: roundRect` 自行补圆角，因为 OOXML 的 roundRect 可以有零圆角调节点。层级在背景之上、`slots` 之下；带 `asset` 的槽落在 decor 之上是版式本意，不算重叠。
 - **slot 样式契约**：`box` 只承载 `[x,y,w,h]` 几何；可渲染属性统一放进 `css`，并可直接写入 HTML `style`。PPTX `bodyPr.insets_px` 转成 `box-sizing: border-box; padding: ...`，字号/字重/颜色/水平与垂直对齐/行高/字距/旋转分别转成标准 CSS。禁止在 slot 中输出 `size` / `weight` / `color` / `align` / `valign` / `insets_px` 等旧字段。
 - **文本角色判断**：脚本把实例页及其引用版式中的现有文本槽、几何和 CSS 完整写入草案；`text_roles` 只供模型把这些槽判断为 `title | subtitle | header | footer | body`，不控制槽位去留。判断不清时用 `body`，不归纳模板中不存在的标题、页眉或页脚。