@lark-apaas/coding-steering 0.1.18-dev.ee5404f → 0.1.18-dev.fb5e270

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

@@ -8,8 +8,13 @@ import unittest
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
 from check_v2 import Pack, rule_v2_16  # noqa: E402
-from draft import emit_layouts, slot_style  # noqa: E402
-from package import FONTSIZE_RE, build_layouts_md, split_top_blocks  # noqa: E402
+from draft import (attach_leftover_image_marks, contact_sheets, draft_layouts,  # noqa: E402
+                   emit_layouts, emit_manifest, fullscreen_overlay_media,
+                   has_small_image_cluster, needs_asset_judgment,
+                   slide_image_marks, slot_style)
+from package import (FONTSIZE_RE, Fail, apply_asset_decisions,  # noqa: E402
+                     build_layouts_md, resolve_asset_candidate_lines,
+                     split_top_blocks)
 
 
 class LayoutCssTest(unittest.TestCase):
@@ -93,6 +98,406 @@ class LayoutCssTest(unittest.TestCase):
         self.assertEqual(len(result.fails), 1)
         self.assertIn('旧样式键 align/size', result.fails[0])
 
+    def test_normautofit_fontscale_shrinks_emitted_font_size(self):
+        # 章节大号数字：160px 字号靠 normAutofit fontScale 0.9 装进 144px 的框。
+        # 不乘 fontScale，消费端拿到 160px，字比框高，渐变裁切把底部切成透明。
+        shape = {
+            'text': {
+                'bodyPr': {'anchor': 't', 'font_scale': 0.9, 'ln_spc_reduction': 0.1},
+                'lstStyle': {'lvl1pPr': {'sz_px': 160, 'lnSpc': {'mult': 1.0}}},
+                'paragraphs': [{'runs': [{'text': '01.'}]}],
+            },
+        }
+        style = slot_style(shape)
+        self.assertIn('font-size: 144px', style['css'])
+        self.assertNotIn('font-size: 160px', style['css'])
+        # lnSpcReduction 0.1 把 1.0*1.2 的行高压到 1.08
+        self.assertIn('line-height: 1.08', style['css'])
+
+    def test_missing_autofit_leaves_font_size_untouched(self):
+        # 无 normAutofit（或无 fontScale）时零影响：字号原样、行高不缩。
+        shape = {
+            'text': {
+                'bodyPr': {'anchor': 't'},
+                'lstStyle': {'lvl1pPr': {'sz_px': 160, 'lnSpc': {'mult': 1.0}}},
+                'paragraphs': [{'runs': [{'text': '01.'}]}],
+            },
+        }
+        style = slot_style(shape)
+        self.assertIn('font-size: 160px', style['css'])
+        self.assertIn('line-height: 1.2', style['css'])
+
+    def test_run_level_style_is_emitted_from_flat_ooxml_record(self):
+        # read_txbody 把 a:rPr 的属性直接展开到 run；没有嵌套 rPr 字段。
+        shape = {
+            'text': {
+                'bodyPr': {'anchor': 't'},
+                'paragraphs': [{
+                    'runs': [{
+                        'text': '品牌标题',
+                        'sz_px': 52,
+                        'weight': 700,
+                        'latin': 'Brand Sans',
+                        'color': {'resolved': '#C1121F'},
+                    }],
+                }],
+            },
+        }
+
+        style = slot_style(shape)
+
+        self.assertIn('font-size: 52px', style['css'])
+        self.assertIn(
+            'font-family: "Brand Sans", "PingFang SC", "Microsoft YaHei", sans-serif',
+            style['css'],
+        )
+        self.assertIn('font-weight: 700', style['css'])
+        self.assertIn('color: #C1121F', style['css'])
+
+    def test_run_level_style_overrides_inherited_list_style(self):
+        shape = {
+            'text': {
+                'lstStyle': {
+                    'lvl1pPr': {
+                        'sz_px': 20,
+                        'latin': 'Inherited Sans',
+                        'color': {'resolved': '#111111'},
+                    },
+                },
+                'paragraphs': [{
+                    'runs': [{
+                        'text': '直接格式',
+                        'sz_px': 52,
+                        'latin': 'Direct Sans',
+                        'color': {'resolved': '#C1121F'},
+                    }],
+                }],
+            },
+        }
+
+        style = slot_style(shape)
+
+        self.assertIn('font-size: 52px', style['css'])
+        self.assertIn('font-family: "Direct Sans"', style['css'])
+        self.assertIn('color: #C1121F', style['css'])
+        self.assertNotIn('font-size: 20px', style['css'])
+        self.assertNotIn('Inherited Sans', style['css'])
+
+    def test_asset_decisions_keep_content_slots_and_bind_texture_slots(self):
+        manifest = {
+            'assets': [],
+            'asset_decisions': [
+                {'source_media': 'chart.png', 'decision': 'content'},
+                {'source_media': 'ornament.png', 'decision': 'texture'},
+            ],
+        }
+
+        decisions, asset_ids = apply_asset_decisions(manifest)
+        lines = resolve_asset_candidate_lines([
+            '      - {role: asset-candidate, box: [10, 20, 300, 200], type: pic, '
+            'source_media: chart.png}',
+            '      - {role: asset-candidate, box: [20, 30, 80, 80], type: pic, '
+            'source_media: ornament.png}',
+        ], decisions, asset_ids)
+
+        self.assertEqual(len(lines), 2)
+        self.assertNotIn('chart.png', lines[0])
+        self.assertNotIn('source_media', lines[0])
+        self.assertNotIn('asset:', lines[0])
+        self.assertIn('role: pic', lines[0])
+        self.assertNotIn('source_media', lines[1])
+        self.assertIn('role: texture', lines[1])
+        self.assertIn('asset: texture-1', lines[1])
+        self.assertEqual(manifest['assets'], [{
+            'id': 'texture-1',
+            'source_media': 'ornament.png',
+            'kind': 'texture',
+        }])
+
+    def test_asset_decisions_do_not_reuse_an_existing_asset_id(self):
+        manifest = {
+            'assets': [
+                {
+                    'id': 'logo-primary',
+                    'source_media': 'candidate.png',
+                    'kind': 'logo',
+                },
+                {
+                    'id': 'texture-1',
+                    'source_media': 'existing.png',
+                    'kind': 'texture',
+                },
+            ],
+            'asset_decisions': [
+                {'source_media': 'candidate.png', 'decision': 'texture'},
+            ],
+        }
+
+        _, asset_ids = apply_asset_decisions(manifest)
+
+        self.assertEqual(asset_ids['existing.png'], 'texture-1')
+        self.assertEqual(asset_ids['candidate.png'], 'texture-2')
+        self.assertEqual(
+            [asset['id'] for asset in manifest['assets']],
+            ['texture-2', 'texture-1'],
+        )
+
+    def test_asset_decisions_reject_candidates_without_layout_slots(self):
+        manifest = {
+            'assets': [],
+            'asset_decisions': [
+                {'source_media': 'orphan-decoration.png', 'decision': 'texture'},
+            ],
+        }
+
+        with self.assertRaisesRegex(Fail, '没有对应图片槽'):
+            apply_asset_decisions(manifest, bound_sources=set())
+
+    def test_translucent_fullscreen_decoration_requires_model_judgment(self):
+        candidate = {
+            'file': 'glow.png',
+            'fullscreen': True,
+            'slides': [2],
+            'probe': {'alpha_mean': 80},
+        }
+
+        with tempfile.TemporaryDirectory() as output_dir:
+            emit_manifest({'theme_topology': {}}, [], [candidate], output_dir)
+            with open(os.path.join(output_dir, 'manifest.yaml'), encoding='utf-8') as stream:
+                manifest = stream.read()
+
+        self.assertIn('source_media: glow.png', manifest)
+        self.assertIn('decision: TODO-kind-1', manifest)
+
+    def test_deterministic_fullscreen_images_skip_model_judgment(self):
+        self.assertFalse(needs_asset_judgment({
+            'fullscreen': True,
+            'probe': {'alpha_mean': 255, 'near_blank': False},
+        }))
+        self.assertFalse(needs_asset_judgment({
+            'fullscreen': True,
+            'probe': {'alpha_mean': 5, 'near_blank': True},
+        }))
+
+    def test_shape_fill_images_are_exposed_as_slide_marks(self):
+        data = {
+            'images': [{
+                'media': 'ppt/media/fill.png',
+                'fullscreen': False,
+                'boxes': [{
+                    'box': {'x': 120, 'y': 240, 'w': 360, 'h': 420},
+                    'parts': ['ppt/slides/slide2.xml'],
+                }],
+            }],
+        }
+
+        marks = slide_image_marks(data)
+
+        self.assertEqual(marks['ppt/slides/slide2.xml'], [{
+            'media': 'ppt/media/fill.png',
+            'box': {'x': 120, 'y': 240, 'w': 360, 'h': 420},
+        }])
+
+    def test_form3_layouts_include_instance_image_fills(self):
+        layouts = []
+        shapes = []
+        for index in range(1, 4):
+            part = 'ppt/slideLayouts/slideLayout%d.xml' % index
+            layouts.append({
+                'part': part,
+                'name': 'Layout %d' % index,
+                'used_by_slides': 1,
+            })
+            shapes.append({
+                'part': part,
+                'layer': 'layout',
+                'kind': 'sp',
+                'box': {'x': 10, 'y': 10, 'w': 500, 'h': 100},
+                'ph': {'type': 'title', 'idx': str(index)},
+                'text': {'paragraphs': [{'runs': [{
+                    'text': 'Title %d' % index,
+                    'sz_px': 40,
+                }]}]},
+            })
+        data = {
+            'canvas': {'px': [1920, 1080]},
+            'form_hint': {'form': 3},
+            'layouts': layouts,
+            'images': [{
+                'media': 'ppt/media/fill.png',
+                'fullscreen': False,
+                'boxes': [{
+                    'box': {'x': 120, 'y': 240, 'w': 360, 'h': 420},
+                    'parts': ['ppt/slides/slide1.xml'],
+                }],
+            }],
+            'media': [],
+            'theme_topology': {
+                'themes': ['single'],
+                'per_master': [],
+                'default': 'single',
+            },
+            'reference_graph': {
+                'master_of_layout': {},
+                'layout_of_slide': {
+                    'ppt/slides/slide1.xml': 'ppt/slideLayouts/slideLayout1.xml',
+                },
+            },
+            '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:
+                import json
+                json.dump({'shapes': shapes}, stream)
+            archetypes, _, _ = draft_layouts(data, output_dir)
+
+        self.assertTrue(any(
+            slot.get('media') == 'ppt/media/fill.png'
+            for archetype in archetypes
+            for slot in archetype['slots']
+        ))
+
+    def test_shape_opacity_marks_opaque_fullscreen_media_as_overlay(self):
+        data = {
+            'media': [{
+                'media': 'ppt/media/overlay.png',
+                'out': 'media-out/overlay.png',
+            }],
+            'images': [{
+                'media': 'ppt/media/overlay.png',
+                'fullscreen': True,
+            }],
+        }
+        shapes = [{
+            'kind': 'pic',
+            'media': 'ppt/media/overlay.png',
+            'w_pct': 100,
+            'h_pct': 100,
+            'opacity': 0.25,
+        }]
+
+        with tempfile.TemporaryDirectory() as output_dir:
+            media_dir = os.path.join(output_dir, 'media-out')
+            os.makedirs(media_dir)
+            try:
+                from PIL import Image
+            except ImportError:
+                self.skipTest('Pillow unavailable')
+            Image.new('RGB', (16, 9), (20, 40, 60)).save(
+                os.path.join(media_dir, 'overlay.png'))
+
+            overlays = fullscreen_overlay_media(data, output_dir, shapes)
+
+        self.assertEqual(overlays, {'ppt/media/overlay.png'})
+
+    def test_page_with_multiple_small_images_is_kept_for_logo_wall_judgment(self):
+        page = {
+            'marks': [
+                {'media': 'ppt/media/logo-%d.png' % index,
+                 'box': {'x': index * 180, 'y': 300, 'w': 120, 'h': 100}}
+                for index in range(3)
+            ],
+        }
+
+        self.assertTrue(has_small_image_cluster([page], (1920, 1080)))
+        self.assertFalse(has_small_image_cluster([{
+            'marks': page['marks'][:2],
+        }], (1920, 1080)))
+
+    def test_single_image_orphan_reuses_nearest_layout_without_new_archetype(self):
+        archetypes = [{
+            'name': 'layout-1',
+            'slots': [],
+            'rep': 2,
+            '_source_layouts': ['ppt/slideLayouts/slideLayout1.xml'],
+            '_source_backgrounds': ['ppt/media/bg.png'],
+            '_text_n': 4,
+        }, {
+            'name': 'layout-2',
+            'slots': [],
+            'rep': 8,
+            '_source_layouts': ['ppt/slideLayouts/slideLayout2.xml'],
+            '_source_backgrounds': ['ppt/media/other-bg.png'],
+            '_text_n': 12,
+        }]
+        pages = [{
+            'part': 'ppt/slides/slide11.xml',
+            'no': 11,
+            'layout': 'ppt/slideLayouts/slideLayout1.xml',
+            'rendered_bg': 'ppt/media/bg.png',
+            'bg_media': None,
+            'bg_color': None,
+            'texts': [{}, {}, {}, {}, {}],
+            'marks': [{
+                'media': 'ppt/media/ornament.png',
+                'box': {'x': 40, 'y': 120, 'w': 80, 'h': 240},
+            }],
+        }]
+
+        attach_leftover_image_marks(archetypes, pages, kept_parts=set())
+
+        self.assertEqual(len(archetypes), 2)
+        self.assertEqual(archetypes[0]['slots'], [{
+            'role': 'logo',
+            'type': 'pic',
+            'sz': 0,
+            'txt': '',
+            'media': 'ppt/media/ornament.png',
+            'box': [40, 120, 80, 240],
+        }])
+        self.assertEqual(archetypes[1]['slots'], [])
+
+    def test_contact_sheets_cover_all_candidates_without_truncation(self):
+        try:
+            from PIL import Image
+        except ImportError:
+            self.skipTest('Pillow unavailable')
+
+        with tempfile.TemporaryDirectory() as output_dir:
+            media_dir = os.path.join(output_dir, 'media-out')
+            lout_dir = os.path.join(output_dir, 'l-out')
+            os.makedirs(media_dir)
+            os.makedirs(lout_dir)
+            candidates = []
+            for index in range(13):
+                filename = 'image-%02d.png' % index
+                Image.new('RGBA', (8, 8), (index, 20, 30, 255)).save(
+                    os.path.join(media_dir, filename))
+                candidates.append({
+                    'file': filename,
+                    'out': 'media-out/' + filename,
+                    'n': 1,
+                    'probe': {'w': 8, 'h': 8},
+                })
+
+            sheets = contact_sheets(output_dir, candidates, lout_dir)
+            legacy_exists = os.path.exists(os.path.join(lout_dir, 'contact-sheet.png'))
+
+        self.assertEqual(len(sheets), 2)
+        self.assertEqual(
+            [os.path.basename(path) for path in sheets],
+            ['contact-sheet-1.png', 'contact-sheet-2.png'],
+        )
+        self.assertTrue(legacy_exists)
+
+    def test_content_candidates_at_same_geometry_collapse_to_one_slot(self):
+        lines = resolve_asset_candidate_lines([
+            '      - {role: asset-candidate, box: [10, 20, 300, 200], type: pic, '
+            'source_media: chart-a.png}',
+            '      - {role: asset-candidate, box: [10, 20, 300, 200], type: pic, '
+            'source_media: chart-b.png}',
+        ], {
+            'chart-a.png': 'content',
+            'chart-b.png': 'content',
+        }, {})
+
+        self.assertEqual(lines, [
+            '      - {role: pic, box: [10, 20, 300, 200], type: pic}',
+        ])
+
 
 if __name__ == '__main__':
     unittest.main()

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

@@ -163,6 +163,46 @@ class TextRoleContractTest(unittest.TestCase):
         )
         self.assertIn('css: "font-size: 48px; color: #C41230"', 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/v2-format-spec.md

@@ -99,7 +99,7 @@ assets:
   - 方案甲·包内（抽取产物默认形态）：大图保留原图 + 压缩图（`<name>@full.<ext>` / `<name>.<ext>`，`path` 指压缩图、`full` 指原图），消费侧优先用压缩图；压缩图 >500KB WARN、包内总量 >20MB FAIL。
   - 方案乙·平台云盘（入库后目标形态）：条目用 `url`，消费时按云盘图片处理参数取压缩版；包内不落二进制，体积约束不适用。入库时由后端把 `path`/`full` 重写为 `url`（重写版仍须过 V2-1/V2-12）。
   - `url` 必须 http(s) 持久地址，禁 24h TTL 签名 URL。
-- 被遮挡/无用资产、页面内容图不进包；抽不出不编造（记 `gaps`，logo 候选图存 `ref/logo-candidates/`）。**边界**：「内容图」指内容区里的图表/截图/配图；实例页整幅替换底图的满屏主视觉（含封面艺术图）属背景族，照收。
+- 图片按用途三分：整幅替换底图的满屏主视觉（含封面艺术图）属**背景族**，照收；服务于具体内容的图表/截图/产品说明图是**内容图，不进包**；既非 logo、又不服务内容的纹理/装饰插画/色块/几何点缀是**装饰图，标 `texture`**。`logo` 特指这份 deck 自己的品牌标志——logo 墙里的第三方 logo 算内容图。被遮挡/无用资产不进包；抽不出不编造（记 `gaps`，logo 候选图存 `ref/logo-candidates/`）。
 
 ## 2.5 `## Usage` 章节（正文必产，紧随 Overview）
 
@@ -107,10 +107,10 @@ design.md 是消费模型的操作文档，不是抽取记录。`## Usage` 承
 
 1. **消费步骤**：① 画布取 `layouts.md` 的 `canvas`；② 从页型清单选 archetype，按其 flow / slots / decor / background 原样落版；③ `design.md` frontmatter 的 colors / typography / spacing / rounded / components 作为全局 token，局部 CSS 优先；④ 包内资产复制到项目相对目录后引用，字体使用完整 fallback 栈且不在运行时安装；⑤ 双主题包写明默认主题与 token 前缀切换法。
 2. **资产用法表**：每个资产一行——id、文件路径、用在哪类页、怎么摆（logo 给坐标，背景给首选序——如「封面首选 cover-art，无主视觉需求用 cover-dark」）。
-3. **强调色族纪律**：强调色族以 `colors` 段和 layout slot CSS 为准，不新增第二强调色。允许新增中性色、低彩度辅助色或局部语义色来表达正负、风险、警告、状态、图表序列，但必须保持辅助层级；新色不得通过高饱和、高对比、大面积、跨页重复，或用于标题、关键数字、图表主序列、卡片底色、渐变来获得主视觉权重——风格与内容解耦，内容主题不改变强调色体系。
+3. **强调色族纪律**：强调色族以 `colors` 段和 layout slot CSS 为主。必要时可使用其他颜色，但新增颜色须与模板整体的色相、明度和饱和度关系协调，且不能形成与模板主色竞争的第二强调色。中性色、低彩度辅助色或局部语义色可表达正负、风险、警告、状态、图表序列，但须保持辅助层级；新色不得通过高饱和、高对比、大面积、跨页重复，或用于标题、关键数字、图表主序列、卡片底色、渐变来获得主视觉权重。
 4. **交付检查**：逐页确认色板、字体、版式、背景、资产和 Hard Rules 均来自本包，并检查资源加载、内容溢出与画幅裁切。
 
-**Hard Rules 必须包含对应的正向硬规则**（有资产的包）：每页放 logo（位置+文件）；封面底图必用 cover 资产；版式从 layouts.md 取；强调色只从 colors / layout slot CSS 取，新增颜色保持辅助层级。禁止句只用于无法正向表达的红线，且同句给替代。
+**Hard Rules 必须包含对应的正向硬规则**（有资产的包）：每页放 logo（位置+文件）；封面底图必用 cover 资产；版式从 layouts.md 取；以 colors / layout slot CSS 为强调色基准，新增颜色与整体色板协调并保持辅助层级。禁止句只用于无法正向表达的红线，且同句给替代。
 
 ## 3. `layouts` 段（默认 sidecar）
 
@@ -133,6 +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。区带可带自己的 `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`，不归纳模板中不存在的标题、页眉或页脚。

package/steering/nestjs-react-fullstack/skills/coding-guide/SKILL.md

@@ -395,6 +395,8 @@ async createArticle(@Req() req: Request, @Body() dto: CreateArticleDto) {
 | 语音识别、音频转文字、STT | AI语音转文字 |
 | 插件实例、PluginInstance、Capability | 通用插件调用 |
 
+> ⚠️ **语义检索 / 相似推荐场景例外**：若需求是对**应用自有数据**做语义检索、向量检索、相似推荐、相关推荐、按内容找相似，**不要**用上表的「AI搜索总结 / AI文本转JSON / AI智能生文」等通用插件替代，必须召回 `/semantic-search`。上表的 AI 搜索/文本插件用于公网搜索、文本生成、结构化抽取，**不具备对自有数据库的向量检索能力**。
+
 ### 关键区分：多维表格 vs 数据库表
 
 | 场景 | 判断 | 操作 |
@@ -497,6 +499,14 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 
 禁止未调用 Skill 直接编写表单/图表/表格代码。
 
+### 检索 Skill 召回规则（强制执行）
+
+| 场景 | Skill | 说明 |
+|------|-------|------|
+| 语义检索、向量检索、相似推荐、相关推荐、相似内容、按内容找相似、猜你喜欢 | `/semantic-search` | 对应用自有数据库的数据做向量检索 / 相似召回 |
+
+禁止未调用 Skill 直接用「AI搜索总结 / AI文本转JSON / AI智能生文」等通用插件实现对自有数据的语义检索。
+
 ### 组件使用规范
 
 - 优先使用 `client/src/components` 下已有组件（Card/Button/Badge 等）

package/steering/nestjs-react-fullstack/skills/plugin-guide/SKILL.md

@@ -215,7 +215,7 @@ const structured = await capabilityClient
 - **Plugin（插件）**：底层承载单元，包含插件元信息与表单定义（form.schema）。模型侧只感知插件及其表单字段，不感知插件内部实现细节。
 - **PluginInstance（插件实例配置）**：基于某个 Plugin 的表单做"业务封装"，以 **单文件 JSON** 的形式存储（每个插件实例一个文件，语义化 id）。
   - 通过 `paramsSchema` 暴露业务入参
-  - 通过 `formValue` 将业务入参映射到插件表单字段（可常量或引用 `{{input.xxx}}`）
+  - 通过 `formValue` 将业务入参映射到插件表单字段（可常量或引用 `{% raw %}{{input.xxx}}{% endraw %}`）
 - **PluginInstanceAIJson（pluginInstance.ai.json）**：工程转化层产物，是 pluginInstance 的**运行时投影 / 调用合同（Runtime Spec）**。
   - 包含插件定位信息、actions 入口列表、input/output schema、outputMode、readme 等
   - Code Agent 在生成**调用代码**前，必须读取它作为权威依据（Server 侧用 `CapabilityService`，Client 侧用 `capabilityClient`）
@@ -258,6 +258,7 @@ Plugin 的具体内容以JSON格式给出，例如：
 
 
 PluginInstance 的配置以 JSON 形式输出，例如：
+{% raw %}
 ```json
 {
   "id": "create_feishu_group",       // 全局唯一语义化 ID
@@ -279,6 +280,7 @@ PluginInstance 的配置以 JSON 形式输出，例如：
   }
 }
 ```
+{% endraw %}
 
 **注意**paramsSchema 支持以下 4 种参数类型,需要按下面规定的格式进行填充：
 
@@ -560,7 +562,7 @@ PluginInstanceAIJson 的配置以 JSON 形式输出，例如：
 | 未按 `outputSchema` 解析返回值，猜测返回结构 | 严格按 `get_plugin_ai_json` 返回的 `outputSchema` 读取字段，流式和非流式均适用 |
 | 未输出 Schema 摘录卡就直接写调用代码 | 先完成“编码前闸门”中的摘录卡，再开始编码 |
 | 改完未做真实调用冒烟就宣告完成 | 至少完成一次 unary/stream 真实调用验证，并附最小日志字段 |
-| formValue 中用 `["{{input.xxx}}"]` 包装已经是 `type: array` 的 paramsSchema 参数 | 当 paramsSchema 定义为 array 时，formValue 应透传 `"{{input.xxx}}"`，不要再包一层数组 |
+| formValue 中用 `{% raw %}["{{input.xxx}}"]{% endraw %}` 包装已经是 `type: array` 的 paramsSchema 参数 | 当 paramsSchema 定义为 array 时，formValue 应透传 `{% raw %}"{{input.xxx}}"{% endraw %}`，不要再包一层数组 |
 | 通过 `getDataloom().capability` 或 `(dataloom as any).capability` 调用插件 | `capabilityClient` 是独立导入，不通过 dataloom 访问。dataloom 仅提供 storage 和 service |
 | Client 侧调用插件时，先通过 dataloom 上传文件拿 URL 再传给插件 | Client 侧可直接传 File/Blob 对象给 `capabilityClient`，SDK 自动处理上传。适用于所有文件类型字段（`format` 为 `file`/`picture`/`plugin-file-url`）。Server 侧仍需传 URL |
 | 前端调用插件后不保存结果到数据库，导致页面刷新后数据丢失 | 需要持久化时：优先在 Server 侧调用并直接落库（方案A）；若在 Client 侧调用，必须通过已有 CRUD 接口立即保存结果（方案B） |
@@ -642,7 +644,7 @@ try {
 | 场景 | 正确做法 | 示例 |
 |------|---------|------|
 | 需求明确的**固定**接收人/配置 | 在 `plugin_instance CREATE` 的 `formValue` 中直接写死 | `formValue.receiverUserList: ["1854102143505690"]` |
-| **动态**接收人/配置（按角色/条件变化） | 从配置/平台 API/DB 获取，传入 `input` 参数 | `formValue.receiverUserList: "{{input.receiverIds}}"` |
+| **动态**接收人/配置（按角色/条件变化） | 从配置/平台 API/DB 获取，传入 `input` 参数 | `{% raw %}formValue.receiverUserList: "{{input.receiverIds}}"{% endraw %}` |
 
 > **关键区分**：`formValue` 中配置固定值 ≠ 代码中硬编码。`formValue` 是插件实例的声明式配置，修改不需要改代码；而代码中硬编码的值散落在业务逻辑中，难以维护。
 

package/steering/nestjs-react-fullstack/skills_local/plugin-guide/SKILL.md

@@ -8,6 +8,8 @@ steering-topic: plugin_guide
 match-template-name: nestjs-react-fullstack
 ---
 
+{% raw %}
+
 # Plugin 集成指南（本地开发）
 
 AI 插件集成规范，使用 lark-cli 命令管理插件包与实例，通过 capabilityClient / CapabilityService 生成调用代码。
@@ -578,3 +580,5 @@ npx @lark-apaas/miaoda-cli plugin list --id <instance_id>
 5. **禁止用 `npm install` 安装插件包** — 插件包和 npm 包是两套独立机制。
 6. **禁止 Mock** — 必须走真实插件实例调用链路。
 7. **formValue 禁止 Handlebars 控制语法** — 仅允许 `{{input.xxx}}`。
+
+{% endraw %}

package/steering/vite-react/skills/plugin-guide/SKILL.md

@@ -180,7 +180,7 @@ const structured = await (jsonExtractor as any).call('textToJson', { text: rawRe
 - **Plugin（插件）**：底层承载单元，包含插件元信息与表单定义（form.schema）。模型侧只感知插件及其表单字段，不感知插件内部实现细节。
 - **PluginInstance（插件实例配置）**：基于某个 Plugin 的表单做"业务封装"，以 **单文件 JSON** 的形式存储（每个插件实例一个文件，语义化 id）。
   - 通过 `paramsSchema` 暴露业务入参
-  - 通过 `formValue` 将业务入参映射到插件表单字段（可常量或引用 `{{input.xxx}}`）
+  - 通过 `formValue` 将业务入参映射到插件表单字段（可常量或引用 `{% raw %}{{input.xxx}}{% endraw %}`）
 - **PluginInstanceAIJson（pluginInstance.ai.json）**：工程转化层产物，是 pluginInstance 的**运行时投影 / 调用合同（Runtime Spec）**。
   - 包含插件定位信息、actions 入口列表、input/output schema、outputMode、readme 等
   - Code Agent 在生成**调用代码**前，必须读取它作为权威依据（使用 `capabilityClient` 调用）
@@ -224,6 +224,7 @@ Plugin 的具体内容以JSON格式给出，例如：
 
 PluginInstance 的配置以 JSON 形式输出，例如：
 
+{% raw %}
 ```json
 {
   "id": "create_feishu_group",       // 全局唯一语义化 ID
@@ -245,6 +246,7 @@ PluginInstance 的配置以 JSON 形式输出，例如：
   }
 }
 ```
+{% endraw %}
 
 **注意**paramsSchema 支持以下 4 种参数类型,需要按下面规定的格式进行填充：
 

package/steering/vite-react/skills/react-three-fiber/SKILL.md

@@ -5,6 +5,8 @@ steering: true
 steering-topic: react_three_fiber
 ---
 
+{% raw %}
+
 # React Three Fiber (R3F) 编码指南
 
 实现 3D 场景 / 3D 游戏 / 3D 数据可视化时, MUST 用 **react-three-fiber + drei** 声明式栈, 严禁用 React + CSS / SVG / `transform: rotateX` 伪 3D.
@@ -220,3 +222,5 @@ npm install react-error-boundary        # 必装! Canvas 外包 ErrorBoundary
 
 - `client-coding-guide` - vite-react 通用编码规范
 - `component-conventions` - React 组件命名 / 文件结构
+
+{% endraw %}