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

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

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""Regression tests for inherited layout text and model-decided text roles."""
+import json
+import os
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from draft import draft_layouts, emit_layouts, inherited_text_shapes
+from package import build_layouts_md, split_top_blocks
+
+
+def text_shape(part, layer, shape_id, box, text, placeholder):
+    return {
+        'part': part,
+        'layer': layer,
+        'id': shape_id,
+        'kind': 'sp',
+        'name': 'Text Placeholder',
+        'ph': placeholder,
+        'box': box,
+        'text': {
+            'bodyPr': {},
+            'lstStyle': {
+                'lvl1pPr': {
+                    'sz_px': 48,
+                    'weight': 600,
+                    'color': {'resolved': '#C41230'},
+                },
+            },
+            'paragraphs': [
+                {
+                    'runs': [{'text': text}],
+                },
+            ] if text else [],
+        },
+    }
+
+
+class TextRoleContractTest(unittest.TestCase):
+    def test_empty_non_placeholder_layout_shape_is_not_a_text_slot(self):
+        layout_part = 'ppt/slideLayouts/slideLayout2.xml'
+        decorative_shape = text_shape(
+            layout_part,
+            'layout',
+            '9',
+            {'x': 0, 'y': 0, 'w': 1920, 'h': 24},
+            '',
+            None,
+        )
+        decorative_shape['name'] = 'Decorative bar'
+
+        self.assertEqual(inherited_text_shapes([decorative_shape], []), [])
+
+    def test_empty_slide_inherits_text_slot_and_css_from_its_layout(self):
+        layout_part = 'ppt/slideLayouts/slideLayout2.xml'
+        slide_part = 'ppt/slides/slide1.xml'
+        shapes = [
+            text_shape(
+                layout_part,
+                'layout',
+                '10',
+                {'x': 120, 'y': 80, 'w': 840, 'h': 120},
+                'Example heading',
+                {'type': 'body', 'idx': '10'},
+            ),
+            text_shape(
+                slide_part,
+                'slide',
+                '2',
+                None,
+                '',
+                {'type': 'body', 'idx': '10'},
+            ),
+        ]
+        data = {
+            'canvas': {'px': [1920, 1080]},
+            'form_hint': {'form': 0},
+            'slides': [
+                {
+                    'part': slide_part,
+                    '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': shapes}, stream)
+            archetypes, _, _ = draft_layouts(data, output_dir)
+
+        self.assertEqual(len(archetypes), 1)
+        self.assertEqual(len(archetypes[0]['slots']), 1)
+        slot = archetypes[0]['slots'][0]
+        self.assertEqual(slot['box'], [120, 80, 840, 120])
+        self.assertEqual(slot['txt'], 'Example heading')
+        self.assertEqual(slot['role'], 'body')
+        self.assertEqual(slot['type'], 'body')
+        self.assertTrue(slot['_needs_role'])
+        self.assertIn('font-size: 48px', slot['css'])
+        self.assertIn('font-weight: 600', slot['css'])
+        self.assertIn('color: #C41230', slot['css'])
+
+    def test_text_role_judgement_changes_semantics_without_dropping_slot(self):
+        archetype = {
+            'name': 'layout-1',
+            'zh': None,
+            'role': 'content',
+            'bg': None,
+            'slots': [
+                {
+                    'role': 'body',
+                    'type': 'body',
+                    'box': [120, 80, 840, 120],
+                    'sz': 48,
+                    'txt': 'Example heading',
+                    'css': 'font-size: 48px; color: #C41230',
+                    '_needs_role': True,
+                    '_source_layer': 'layout',
+                    '_placeholder': 'body/10',
+                },
+            ],
+            'decor': [],
+            'pages': [1],
+            'rep': 1,
+            'pic_n': 0,
+            'confidence': 'low',
+        }
+
+        with tempfile.TemporaryDirectory() as output_dir:
+            emit_layouts([archetype], output_dir)
+            path = os.path.join(output_dir, 'layouts.yaml')
+            with open(path, encoding='utf-8') as stream:
+                draft = stream.read()
+
+        self.assertIn('text_roles:', draft)
+        self.assertIn(
+            'layout-1-text-1: TODO文本角色',
+            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_md = build_layouts_md(split_top_blocks(decided), (1920, 1080))
+
+        self.assertNotIn('text_roles:', layouts_md)
+        self.assertEqual(layouts_md.count('box: [120, 80, 840, 120]'), 1)
+        self.assertIn(
+            'role: title, box: [120, 80, 840, 120], type: title',
+            layouts_md,
+        )
+        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

@@ -16,7 +16,7 @@
 
 - 消费方直接读 design.md，靠目录约定找 sidecar 与资产；frontmatter `path` 是唯一文件引用点。
 - manifest（`manifest.json`，识别靠内部 `schemaVersion` 字面量不靠文件名）服务存储、索引、校验和迁移；消费模型不需要读它。
-- `ref/` 是包内可剥离子目录：抽取产出必含（check_v2 不校验其存在性，归位是打包步骤的责任），入库/下发时链路剥离，不进消费上下文。
+- `ref/` 只放 `audit.yaml`（数值出处的人工复核记录，几 KB）。频次原表、聚类原始数据、`extract.json`、重建图、logo 候选图**留在抽取工作目录，不进交付包**——原设计是「下发时链路剥离」，但链路上没有环节真的做剥离，审计材料会连带进消费上下文并占掉包体的大头。
 
 ## 1. design.md frontmatter 新增键
 
@@ -53,10 +53,10 @@ canvas: 1920x1080      # layouts.md 首键；px = round(EMU / sldSz_cx * 1920)
 themes: [dark, light]
 default-theme: dark            # 双主题包必填（V2-13）
 colors:                        # v1 单层扁平，主题进 token 名
-  dark-surface: "#0A0E1E"
-  dark-on-surface: "#FFFFFF"
-  light-surface: "#FFFFFF"
-  primary: "#3C7FFF"           # 共用色不加前缀
+  dark-surface: "#RRGGBB"
+  dark-on-surface: "#RRGGBB"
+  light-surface: "#RRGGBB"
+  primary: "#RRGGBB"           # 共用色不加前缀
 ```
 
 - token 前缀约定（`dark-X`/`light-X` = 主题专属，无前缀 = 共用）在 `## Usage` 里向消费者写一句；主题机制溯源（clrMap 反转等）落 `ref/audit.yaml`。
@@ -65,7 +65,7 @@ colors:                        # v1 单层扁平，主题进 token 名
 
 ### 1.3 排除色
 
-- **排除色进 `## Hard Rules` 带证据计数**，正向给替代（如「`#FBAE40` 为编辑器参考线色（出现 72 次），非设计色」）。频次原表与 color-confidence 证据进 `ref/`。
+- **排除色进 `## Hard Rules` 带证据计数**，正向给替代（如「`<hex>` 为编辑器参考线色（出现 <N> 次），非设计色」）。频次原表与 color-confidence 证据进 `ref/`。
 - 排除色断言必须以**解析后频次**为准，`styleRef` 主题兜底引用（不渲染）与真实设计用色分开。
 
 ## 2. `assets` 段
@@ -84,7 +84,7 @@ assets:
     kind: background
     role: cover                # cover | content | section | closing | accent
     theme: dark
-    recipe: "linear-gradient(135deg, #0A0E1E 0%, #12204A 100%)"   # 可选：CSS 重绘配方
+    recipe: "linear-gradient(<angle>, <color> 0%, <color> 100%)"   # 可选：CSS 重绘配方
   bg-content-solid:            # 纯色背景：无 path/url，引 colors token
     kind: background
     role: content
@@ -99,17 +99,18 @@ 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）
 
 design.md 是消费模型的操作文档，不是抽取记录。`## Usage` 承载三件事，全部**可执行**（具体文件、具体坐标、具体顺序）：
 
-1. **三步指引**：① 搭任何一页之前先读 `layouts.md`，从页型清单里选 archetype，slots 坐标照抄；② 按资产用法表给该页铺底图/放 logo；③ 双主题包写明默认主题与 token 前缀切换法。
+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` 段 token，强调色只用 primary 家族——风格与内容解耦，内容主题不改变色板。
+3. **强调色族纪律**：强调色族以 `colors` 段和 layout slot CSS 为主。必要时可使用其他颜色，但新增颜色须与模板整体的色相、明度和饱和度关系协调，且不能形成与模板主色竞争的第二强调色。中性色、低彩度辅助色或局部语义色可表达正负、风险、警告、状态、图表序列，但须保持辅助层级；新色不得通过高饱和、高对比、大面积、跨页重复，或用于标题、关键数字、图表主序列、卡片底色、渐变来获得主视觉权重。
+4. **交付检查**：逐页确认色板、字体、版式、背景、资产和 Hard Rules 均来自本包，并检查资源加载、内容溢出与画幅裁切。
 
-**Hard Rules 必须包含对应的正向硬规则**（有资产的包）：每页放 logo（位置+文件）；封面底图必用 cover 资产；版式从 layouts.md 取；颜色只从 colors 取。禁止句只用于无法正向表达的红线，且同句给替代。
+**Hard Rules 必须包含对应的正向硬规则**（有资产的包）：每页放 logo（位置+文件）；封面底图必用 cover 资产；版式从 layouts.md 取；以 colors / layout slot CSS 为强调色基准，新增颜色与整体色板协调并保持辅助层级。禁止句只用于无法正向表达的红线，且同句给替代。
 
 ## 3. `layouts` 段（默认 sidecar）
 
@@ -123,13 +124,21 @@ layouts:
     themes: [dark, light]      # 深浅孪生合并
     background: {dark: bg-cover-dark, light: bg-cover-light}
     slots:
-      - {role: title, box: [110, 340, 970, 160], type: title}
-      - {role: logo,  box: [120, 121, 235, 74], asset: {dark: logo-on-dark, light: logo-on-light}}
+      - {role: title, box: [<x>, <y>, <w>, <h>], type: title, css: "<CSS 声明串>"}
+      - {role: logo,  box: [<x>, <y>, <w>, <h>], asset: {dark: logo-on-dark, light: logo-on-light}}
+    decor:
+      - {box: [<x>, <y>, <w>, <h>], geom: ellipse, css: "<CSS 声明串>"}
     confidence: high
 ```
 
 - **`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`，不归纳模板中不存在的标题、页眉或页脚。
+- **标题结构**：存在合适的模板页型时，沿用其标题层级和局部 CSS，只渲染该页型已有的文字槽；背景中已经可见的固定标题不重复创建文本，该页型没有副标题槽时不新增副标题。没有合适参考时由模型按模板整体视觉判断。
+- **圆角作用域**：`rounded` 只允许表达全档共同的单一圆角档位；零圆角与非零圆角混用、或存在多个非零档位时不输出该全局 token。此时每个 `role: container` / `decor` 的 `css` 是唯一事实源，逐项原样消费，不得归并或推断。
 - **`type` 封闭枚举**：`title | subtitle | body | pic | table | chart | media | slide-number | footer`。大数字/序号走 `type: title`，语义由 `role`（如 `big-number`）承担。
 - **`slots.*.role` 开放不校验**（语义槽位）：优先复用已知词表（OOXML ST_SlideLayoutType / Slidev 20 布局 / Google PredefinedLayout，如 big-number、caption、main-point），确无对应再自造。
 - archetype ≤15（内联降级形态 ≤11）；深浅孪生合并为一条；版式溯源/母版取舍进 `ref/`。
@@ -139,14 +148,14 @@ layouts:
 
 ```yaml
 safe-area:                     # 开放命名 map，可多套边距体系
-  content:    {top: 214, right: 133, bottom: 77, left: 133, applies-to: [content, quote]}
-  editorial:  {left: 120, right: 120, applies-to: [cover, section, closing]}
+  content:    {top: <px>, right: <px>, bottom: <px>, left: <px>, applies-to: [content, quote]}
+  editorial:  {left: <px>, right: <px>, applies-to: [cover, section, closing]}
   confidence: medium
 ```
 
 冲突裁决：`slots.box` 是实例真值，`safe-area` 是归纳框架，**以 slots.box 为准**。
 
-## 5. check_v2 校验（16 行：V2-1..V2-13 + V2-R5/R6/R7）
+## 5. check_v2 校验（19 行：V2-1..V2-16 + V2-R5/R6/R7）
 
 check_v1 全部规则原样生效。扫描范围 = 包目录，V2-1/V2-2 跨 design.md + layouts.md 求并集。
 
@@ -165,6 +174,9 @@ check_v1 全部规则原样生效。扫描范围 = 包目录，V2-1/V2-2 跨 des
 | V2-11 | 键名命中 YAML 1.1 布尔字面量 | FAIL |
 | V2-12 | `path`/`url`/`color` 恰好存在一个；`color` 仅 background 允许；`full` 仅可伴随 `path` | FAIL |
 | V2-13 | 多主题（`themes` 长度 >1）缺 `default-theme`（只看 design.md frontmatter——冲突以 design.md 为准） | WARN |
+| V2-14 | 版式的 `flow` 与 `slots` 互斥（同时出现 = FAIL）；`flow.regions[].kind` 在 `grid`/`stack`/`free` 内，`grid` 必带 `cols` | FAIL |
+| V2-15 | 同段字段自洽：`backgrounds.*` 的 `text_safe` 不得与任一 `avoid` 相交；两者形态须为 `[x, y, w, h]` 四个数且 w/h 为正 | FAIL |
+| V2-16 | slot/flow item 的渲染样式只通过 `css` 承载；出现 `size/weight/color/align/valign/insets_px` 旧键 | FAIL |
 | V2-R5 | sidecar frontmatter 重复 design.md 已有顶层键（`layouts` 载荷键与 `canvas` 除外——canvas 的家就在 sidecar） | WARN |
 | V2-R6 | assets 条目出现审计字段（boxes/aspect/mark/confidence）或 design.md 顶层出现 canvas/canvas-source/theme-mechanism/color-confidence——应移 `ref/audit.yaml` / layouts.md | WARN |
 | V2-R7 | 有 layouts sidecar 指针但正文未出现 `layouts.md` 字样（弱指针，消费者到不了版式数据） | WARN |

package/steering/design-html/skills/slide-deck/SKILL.md

@@ -17,14 +17,6 @@ metadata:
 
 每张幻灯片既是版式设计的练习，也是文案写作的练习。动手前先写大纲；好的大纲本身就是一次讲故事和叙事结构的练习。
 
-## PPTX/POTX 模板附件前置步骤
-
-如果用户上传了 `.pptx` 或 `.potx`，并要求制作/生成/改做一个 PPT、演示文稿、slides、deck，先判断附件是否是模板或视觉参考。
-
-- 命中“按这个模板 / 照附件风格 / 参考这个 PPT / 保持同款视觉 / 基于这个模板”等意图时，先调用 `pptx-style-extract` skill，读取产出的 `design.md`、`layouts.md` 和 `assets/`，再开始写 deck。
-- 只总结、翻译、提取内容、审阅已有 PPTX 时，不需要抽取风格。
-- 不要用 `SummarizeAttachmentOrFile` 的 Markdown/文本摘要替代风格抽取；文本摘要不包含母版、色板、字体、版式坐标和素材角色。
-
 ## 动手前先问
 
 - 如果用户没有说明想要的视觉风格，也没有提供 design system，就用提问工具（ask_user_question）**主动询问**。绝不要直接给出一个通用设计！
@@ -45,18 +37,6 @@ metadata:
 
 deck-stage 组件会对每个 slotted 子元素做绝对定位——**绝不**在幻灯片 `<section>` 元素上自行设置 position/inset/width/height。
 
-### 使用 PPTX 风格包
-
-如果前一步产出了 `pptx-style-extract` 风格包，必须把它当作本 deck 的设计系统：
-
-- 先读 `design.md` 的 Usage / Hard Rules / colors / typography / components / assets / safe-area。
-- 再读 `layouts.md`，用其中的 layout archetype 和 slots 坐标生成页面；坐标单位已经是 px@1920，不需要 EMU 或 pt 换算。
-- 消费并落实 colors / typography / spacing / rounded / safe-area 等样式 token；可以用 CSS variables、类名或内联样式承载，但最终页面必须看得出这些 token 被系统性使用，而不是另起一套视觉系统。
-- 背景和版式必须成对消费：选择某个 layout archetype 时，同时采用它声明的 `background`、`text_safe`、`avoid` / `pairing_rule`。标题、正文、图表、表格、卡片、时间线及其容器外接矩形不得进入背景禁放区；如果内容与背景主体冲突，换页型、拆页或缩小内容区域，不要只换背景色或把容器铺到禁放区。
-- 把包内 `assets/` 复制到项目内相对目录并引用复制后的路径；最终 HTML 禁止引用 `/tmp` 或本机绝对路径。
-- 字体使用 design.md 的完整 font stack 和 fallback，不现场安装字体。
-- 自检时除了常规 deck preflight，还要确认色板、字体、版式坐标、资产和 Hard Rules 均来自该风格包。
-
 ### 把幻灯片内容写成静态 HTML，而不是 React
 
 幻灯片内容应写成静态 HTML，而非 React 或脚本生成的 DOM。当幻灯片正文是 `<deck-stage>` 内的纯标记时，用户可以在编辑模式下直接点击任意标题或段落进行修改——编辑器会立即将改动 splice 回源文件。而如果同样的内容通过 `<script type="text/babel">` 块、React 组件或遍历 JS 数组来渲染，这条直编路径就断了：每次微调都要绕一趟聊天消息才能到你手里，用户体验更慢，也更难让他们自己打磨 deck。因此，凡是静态页面能表达的——文本、布局、背景、图片——都直接在 HTML 里写字面元素并用 CSS 设置样式。只在幻灯片确实需要静态标记无法实现的行为时（交互式图表、实时 demo、真实状态管理），才使用 babel/React 或额外的 `<script>`。同样的渲染结果，静态 HTML 版本**始终优先于**动态版本，因为静态版本可被直接编辑。Tweaks 面板（`tweaks-panel.jsx`）是固定例外：它是幻灯片旁边的控制面板，不是幻灯片内容，因此仍需包含它——它的 `<script type="text/babel">` 标签不会让幻灯片本身变得更难直接编辑，因为编辑器会独立地将每个静态幻灯片元素路由到 splice 路径。
@@ -144,6 +124,21 @@ deck-stage 组件会对每个 slotted 子元素做绝对定位——**绝不**
 5. **把这套 token 当成每页的内容预算**：在上述数值下，一页正文区大约容纳 14 行正文、或 6 个两行 bullet——在 scratchpad 排内容时就按预算裁剪，而不是写完再看塞不塞得下。装不下的处置顺序是**拆页 > 删内容 > 换更省空间的版式**；缩小字号是最后手段，且绝不越过 24px 下限——靠缩字塞进去的页，只是把溢出换成了后排看不清。反过来，内容远少于预算的页按「视觉平衡」的出路增密或合并，而不是放大字号去撑面积。
 6. 构建幻灯片，牢记每张幻灯片既是设计练习也是文案练习。在版式、文字内容和语调方面给予每张幻灯片应有的关注。遵循上述原则，确保每张幻灯片能独立成立；一个只看这一页的人，应当无需其他上下文就能理解其高层含义。
 
+## 提交前资源完整性门禁
+
+最终一次写入 HTML/CSS 后、调用 `run_commit` 前，必须从项目根目录运行：
+
+```bash
+python3 <本skill目录>/scripts/check_local_references.py index.html
+```
+
+把 `<本skill目录>` 换成本 skill 的实际所在目录。脚本从最终 `index.html` 出发，递归检查 HTML/CSS 引用的每个项目内脚本、样式、图片、字体等文件是否真实存在；外部 URL 不做离线探测。
+
+- 只有输出 `RESOURCE_CHECK: PASS` 才能提交。
+- 输出 `RESOURCE_CHECK: FAIL` 时，先重新复制或修正列出的项目内文件，再原样重跑；不得删除引用来掩盖仍在使用的资源。
+- 该检查针对最终工作区状态。较早执行过复制命令或检查，不能证明最终提交完整。
+- `run_commit` 的静态检查跳过参数不能替代本门禁，也不能用来绕过失败；提交时必须包含检查通过所依赖的全部项目内文件。
+
 ## 验证要点
 
 审阅时，用幻灯片构图规则——而非网页布局直觉——来检查版面。底部留白是不是缺陷，用「留白 ≠ 空洞」的归属判据：内容自身完整、下方是无边框的整块呼吸空间，这是正确的幻灯片构图——不要出于网页直觉把 `flex-start` 改成 `center`；空白被元素边界圈占的，是被动空洞，按「视觉平衡」的出路修。

package/steering/design-html/skills/slide-deck/scripts/check_local_references.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+
+import re
+import sys
+from html.parser import HTMLParser
+from pathlib import Path
+from urllib.parse import unquote, urlsplit
+
+
+CSS_URL_PATTERN = re.compile(r"""url\(\s*(['"]?)(.*?)\1\s*\)""", re.IGNORECASE)
+CSS_IMPORT_PATTERN = re.compile(
+    r"""@import\s+(?:url\(\s*)?(['"])(.*?)\1\s*\)?""",
+    re.IGNORECASE,
+)
+CSS_COMMENT_PATTERN = re.compile(r"/\*.*?\*/", re.DOTALL)
+HREF_RESOURCE_TAGS = {"image", "link", "use"}
+SRC_RESOURCE_TAGS = {
+    "audio",
+    "embed",
+    "iframe",
+    "img",
+    "input",
+    "script",
+    "source",
+    "track",
+    "video",
+}
+
+
+class ReferenceParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__()
+        self.references: set[str] = set()
+        self.in_style = False
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        tag = tag.lower()
+        if tag == "style":
+            self.in_style = True
+        attributes = dict(attrs)
+        if tag in HREF_RESOURCE_TAGS and attributes.get("href"):
+            self.references.add(attributes["href"])
+        if tag in SRC_RESOURCE_TAGS and attributes.get("src"):
+            self.references.add(attributes["src"])
+        if tag == "object" and attributes.get("data"):
+            self.references.add(attributes["data"])
+        if tag == "video" and attributes.get("poster"):
+            self.references.add(attributes["poster"])
+
+        srcset = attributes.get("srcset")
+        if tag in {"img", "source"} and srcset:
+            self.references.update(
+                candidate.strip().split()[0]
+                for candidate in srcset.split(",")
+                if candidate.strip()
+            )
+
+        style = attributes.get("style")
+        if style:
+            self.references.update(css_references(style))
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag.lower() == "style":
+            self.in_style = False
+
+    def handle_data(self, data: str) -> None:
+        if self.in_style:
+            self.references.update(css_references(data))
+
+
+def css_references(content: str) -> set[str]:
+    content_without_comments = CSS_COMMENT_PATTERN.sub("", content)
+    references = {
+        match.group(2).strip() for match in CSS_URL_PATTERN.finditer(content_without_comments)
+    }
+    references.update(
+        match.group(2).strip() for match in CSS_IMPORT_PATTERN.finditer(content_without_comments)
+    )
+    return references
+
+
+def resolve_local_reference(
+    raw_reference: str,
+    source: Path,
+    project_root: Path,
+) -> Path | None:
+    reference = raw_reference.strip()
+    parsed = urlsplit(reference)
+    if (
+        not reference
+        or reference.startswith(("#", "//"))
+        or (parsed.scheme and parsed.scheme.lower() != "file")
+        or parsed.netloc
+    ):
+        return None
+
+    path_text = unquote(parsed.path)
+    if not path_text:
+        return None
+
+    if parsed.scheme.lower() == "file":
+        return Path(path_text).resolve()
+    if path_text.startswith("/"):
+        return (project_root / path_text.lstrip("/")).resolve()
+    return (source.parent / path_text).resolve()
+
+
+def collect_references(entry: Path, project_root: Path) -> list[tuple[Path, str, Path]]:
+    pending = [entry]
+    visited: set[Path] = set()
+    local_references: list[tuple[Path, str, Path]] = []
+
+    while pending:
+        source = pending.pop()
+        if source in visited or not source.is_file():
+            continue
+        visited.add(source)
+
+        content = source.read_text(encoding="utf-8")
+        if source.suffix.lower() == ".css":
+            references = css_references(content)
+        else:
+            parser = ReferenceParser()
+            parser.feed(content)
+            references = parser.references
+
+        for raw_reference in sorted(references):
+            target = resolve_local_reference(raw_reference, source, project_root)
+            if target is None:
+                continue
+            local_references.append((source, raw_reference, target))
+            if target.suffix.lower() == ".css" and target.is_file():
+                pending.append(target)
+
+    return local_references
+
+
+def display_path(path: Path, project_root: Path) -> str:
+    try:
+        return path.relative_to(project_root).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("usage: check_local_references.py <entry.html>", file=sys.stderr)
+        return 2
+
+    project_root = Path.cwd().resolve()
+    entry = (project_root / sys.argv[1]).resolve()
+    if not entry.is_file():
+        print(f"RESOURCE_CHECK: FAIL entryNotFound={sys.argv[1]}")
+        return 1
+
+    missing: list[tuple[Path, str, Path]] = []
+    for source, raw_reference, target in collect_references(entry, project_root):
+        try:
+            target.relative_to(project_root)
+        except ValueError:
+            missing.append((source, raw_reference, target))
+            continue
+        if not target.is_file():
+            missing.append((source, raw_reference, target))
+
+    if not missing:
+        print("RESOURCE_CHECK: PASS")
+        return 0
+
+    print(f"RESOURCE_CHECK: FAIL missingLocalReferences={len(missing)}")
+    for source, raw_reference, target in missing:
+        source_name = display_path(source, project_root)
+        target_name = display_path(target, project_root)
+        print(f"- {source_name}: {raw_reference} -> {target_name}")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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 %}