@lark-apaas/coding-steering 0.1.32-beta.0 → 0.1.32-dev.5abff3b

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

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Regression tests for preserving per-container radii."""
+import os
+import tempfile
+import unittest
+
+from draft import emit_body, emit_frontmatter
+from query import _recipe_css
+
+
+def render_frontmatter(radii):
+    data = {
+        'radii_census': radii,
+        'spacing_candidates': {},
+    }
+    tokens = [('surface', {'hex': '#FFFFFF'})]
+
+    with tempfile.TemporaryDirectory() as output_dir:
+        emit_frontmatter(
+            data,
+            tokens,
+            [],
+            {},
+            [],
+            [],
+            output_dir,
+        )
+        with open(os.path.join(output_dir, 'frontmatter.yaml'), encoding='utf-8') as stream:
+            return stream.read()
+
+
+def render_body():
+    data = {
+        'canvas': {'px': [1920, 1080]},
+        'form_hint': {'form': 2},
+        'counts': {'slides': 1},
+    }
+
+    with tempfile.TemporaryDirectory() as output_dir:
+        emit_body(
+            data,
+            [],
+            [],
+            {},
+            [],
+            [],
+            [],
+            {},
+            output_dir,
+        )
+        with open(os.path.join(output_dir, 'body.md'), encoding='utf-8') as stream:
+            return stream.read()
+
+
+class RoundedContractTest(unittest.TestCase):
+    def test_multiple_radius_tiers_are_not_collapsed_into_one_card_token(self):
+        frontmatter = render_frontmatter(
+            [
+                {'px': 6.9, 'n': 2},
+                {'px': 11.9, 'n': 2},
+                {'px': 14.4, 'n': 3},
+            ]
+        )
+
+        self.assertNotIn('rounded:', frontmatter)
+
+    def test_single_radius_tier_can_remain_a_global_token(self):
+        frontmatter = render_frontmatter([{'px': 12, 'n': 9}])
+
+        self.assertIn('rounded:\n  card: 12px', frontmatter)
+
+    def test_rare_rounded_exceptions_do_not_override_a_zero_radius_majority(self):
+        frontmatter = render_frontmatter(
+            [
+                {'px': 0, 'n': 241},
+                {'px': 3.4, 'n': 4},
+                {'px': 6.9, 'n': 3},
+                {'px': 50.5, 'n': 1},
+            ]
+        )
+
+        self.assertNotIn('rounded:', frontmatter)
+
+    def test_generated_usage_defaults_unspecified_container_radius_to_zero(self):
+        body = render_body()
+
+        self.assertIn('没有 `border-radius` 就按 `0`', body)
+        self.assertIn('不得自行补圆角', body)
+
+    def test_recipe_does_not_promote_one_rounded_exception_to_the_whole_group(self):
+        css = _recipe_css(
+            {'type': 'solid', 'color': {'hex': '#FFFFFF'}},
+            None,
+            [0] * 70 + [50.5],
+            None,
+        )
+
+        self.assertFalse(any('border-radius' in declaration for declaration in css))
+
+    def test_recipe_keeps_a_radius_shared_by_the_whole_group(self):
+        css = _recipe_css(
+            {'type': 'solid', 'color': {'hex': '#FFFFFF'}},
+            None,
+            [6.9] * 17,
+            None,
+        )
+
+        self.assertIn('border-radius: 6.9px', css)
+
+
+if __name__ == '__main__':
+    unittest.main()

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

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""Regression tests for inherited layout text and model-decided text roles."""
+import json
+import os
+import re
+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('默认均为 body', draft)
+        self.assertIn(
+            '# text-role: layout-1-text-1',
+            draft,
+        )
+        self.assertEqual(draft.count('box: [120, 80, 840, 120]'), 1)
+
+        decided = draft.replace(
+            'layouts:',
+            'text_roles:\n  layout-1-text-1: title\nlayouts:',
+        )
+        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_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/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
@@ -105,11 +105,12 @@ assets:
 
 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/nestjs-react-fullstack/skills/app-init-feasibility-guide/SKILL.md

@@ -54,6 +54,7 @@ available-agents:
 | 前端应用 | 页面、路由、表单、表格、图表、文件预览、交互组件 |
 | 后端服务 | HTTP JSON API：CRUD、聚合统计、业务规则、外部 API 编排 |
 | 数据库 | 应用自有业务数据的持久化、关系建模、查询与统计 |
+| 数据缓存 | 提供跨部署实例的缓存能力 |
 | 用户身份 | 登录、当前用户、用户信息展示 |
 | 权限 | 角色可见性、操作权限点位 |
 | 文件 | 前端上传至平台文件服务，后端保存元信息 |

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

@@ -24,6 +24,11 @@ match-template-name: nestjs-react-fullstack
     │   └─ 不需要任何装饰器 ──→ AuthNPaasGuard 默认放行未标 @NeedLogin() 的接口
     │       （`@Public()` 是历史遗留 no-op，不要使用，详见第二节）
     │
+    ├─ 公开接口会写入应用数据库吗？
+    │   ├─ 是，且允许未登录提交 ──→ 接口保持公开；目标 RLS 表补 `FOR INSERT TO anon WITH CHECK (true)`，未登录 POST 验证
+    │   │   （anon SELECT / authenticated INSERT 都不能替代 anon INSERT WITH CHECK）
+    │   └─ 否，需要当前用户或管理员身份 ──→ 使用 @NeedLogin()，不要开放匿名插入
+    │
     ├─ 接口返回 401 / 登录跳转不对？
     │   └─ 是 ──→ 第四节 · 401 未授权
     │
@@ -97,6 +102,7 @@ export class ApiController {
 | 手动实例化 `AuthNPaasGuard` | 模块自动注册为全局守卫，无需手动 `@UseGuards()` |
 | 用 `@Public()` 标记公开接口 | `@Public()` 是 no-op；公开接口不需要任何装饰器（opt-in 模式默认放行未标 `@NeedLogin()` 的接口） |
 | 在未标 `@NeedLogin()` 的接口里依赖 `req.userContext.userId` 做业务判断 | 该接口默认放行未登录请求，`userId` 可能为 `undefined`，必须先判空 |
+| 公开接口写 RLS 表但只给 anon SELECT / authenticated INSERT | 允许未登录提交时补 `FOR INSERT TO anon WITH CHECK (true)` 或等价 Drizzle policy，并用未登录 POST 验证；否则加 `@NeedLogin()` |
 | 业务层自行返回 401 实现"未登录跳转" | 用 `@NeedLogin()` 让守卫统一处理，确保 `x-login-url` 头被正确写入 |
 | 自建认证传输：自签 JWT 走自定义 `Authorization` / `X-Auth-Token` 头、自定义 cookie、query token | 这些头在妙搭网关转发时**不透传**（白名单只放 `x-suda-csrf-token` / `x-larkgw-suda-webuser` + 标准头），后端必拿不到 → 401，且易被误诊为网关故障。任何自有账号体系/自分配账号需求，身份一律取 `req.userContext`（网关注入，解析自 `x-larkgw-suda-webuser`）、用 `@NeedLogin()` 认证 + 业务角色表授权，不要自签 JWT 走自定义传输 |
 

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

@@ -30,7 +30,7 @@ match-template-name: nestjs-react-fullstack
 
 "开启权限服务"/"设计权限体系"/"规划角色"/"升级鉴权模式"/"开启角色服务" → **必须先调用 `rbac_role_manager` tool 的 DESIGN action**，用户确认后再实施。日常"给某功能加权限"不触发 DESIGN。
 
-> **相关技能**：角色的查询、创建、更新、模拟等 CLI 操作通过 `authz-cli` skill 执行。
+> **相关技能**：角色的查询、创建、更新等 CLI 操作通过当前沙箱的权限管理 skill 执行。
 
 ### 403 统一处理（所有模式通用）
 
@@ -60,7 +60,7 @@ if (response.status === 403) throw new Error('无操作权限，请联系管理
 2. 统一使用 `useAuth()` 获取 `{ ability, isLoading }`，**禁止** `useAuthAbility` / `useCanRole`（已移除）
 3. 必须处理 `isLoading`——加载期间 `ability.can()` 返回 false，不检查会误判无权限
 4. 创建角色后必须编写鉴权代码，切忌只创建角色不编写代码
-5. **`@CanRole([X])`/`<CanRole roles={[X]}>` 里的 X 必须等于平台实际角色标识（bizID），不能凭语义臆造**——创建角色时用 `miaoda-auth-cli role create --biz-id <X>` 把标识固定成代码要用的值，或先 `miaoda-auth-cli role list` 取实际标识再写代码。若代码写 `'admin'`/`'reviewer'` 但平台分配给用户的角色标识是 `role_xxx`，两者对不上 → 线上恒 403（日志可见 `用户角色 [role_xxx], 需要 [admin, reviewer]`）
+5. **`@CanRole([X])`/`<CanRole roles={[X]}>` 里的 X 必须等于平台实际角色标识（bizID），不能凭语义臆造**——创建角色时用当前沙箱权限管理 skill 的建角色命令把标识固定成代码要用的值（该 skill 支持显式指定角色标识），或先用它列出角色取实际标识再写代码。若代码写 `'admin'`/`'reviewer'` 但平台分配给用户的角色标识是 `role_xxx`，两者对不上 → 线上恒 403（日志可见 `用户角色 [role_xxx], 需要 [admin, reviewer]`）
 
 ### 前端
 
@@ -161,9 +161,9 @@ import { CanRole } from '@lark-apaas/fullstack-nestjs-core';
 
 | 问题 | 处理方式 |
 |------|---------|
-| 403 错误 | 明确告知是无权限报错，确认是否符合预期；用 `miaoda-auth-cli` MOCK 模拟角色调试 |
-| 线上 403 但 dev 正常 / 用户"已授权"仍 403 | 先核对两件事：(1) 角色面板授给用户的角色**标识(bizID)** 是否等于代码 `@CanRole` 里的字符串（`miaoda-auth-cli role list` 取实际标识比对）；(2) 是否另搞了一套平台不认的权限（自建角色表 / 引用平台没 create 过的标识 / user_id 名单）绕开平台。两者任一不符即解释 403 |
-| 开发环境授权不生效 | 引导用户使用 `miaoda-auth-cli` MOCK 功能 |
+| 403 错误 | 明确告知是无权限报错，确认是否符合预期；用当前沙箱权限管理 skill 核验该用户实际命中的角色（该通道提供角色模拟能力时可用其调试） |
+| 线上 403 但 dev 正常 / 用户"已授权"仍 403 | 先核对两件事：(1) 角色面板授给用户的角色**标识(bizID)** 是否等于代码 `@CanRole` 里的字符串（用当前沙箱权限管理 skill 列角色，取实际标识比对）；(2) 是否另搞了一套平台不认的权限（自建角色表 / 引用平台没 create 过的标识 / user_id 名单）绕开平台。两者任一不符即解释 403 |
+| 开发环境授权不生效 | 先用当前沙箱权限管理 skill 核对用户命中的角色与角色成员配置；该通道提供角色模拟能力时引导用户使用 |
 | 用户要求管理角色 | 开发态：`[角色面板](BaseURL?openPanel=auth)`；运行态：按第二节实施 |
 
 ---

package/steering/nestjs-react-fullstack/skills/authz-guide/references/dynamic-permission-guide.md

@@ -95,7 +95,7 @@ Step 9: 验证（禁止跳过）
 
 ## Step 1: 数据库表 + 数据初始化
 
-> 对应 `authz-cli` 的 Action：Step 1.1 = `PERM_CREATE_TABLE`，Step 1.2 + 1.3 = `PERM_SEED`。
+> 对应权限管理 skill 的 Action：Step 1.1 = `PERM_CREATE_TABLE`，Step 1.2 + 1.3 = `PERM_SEED`。
 
 **⛔ 必须严格按以下三步顺序执行，禁止合并步骤或跳步。`authz_role_permissions` 有外键依赖 `authz_permissions`，合并执行会导致映射表静默为空。**