@lark-apaas/coding-steering 0.1.42 → 0.1.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.42",
+  "version": "0.1.43",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [

package/steering/design-html/skills/pptx-style-extract/SKILL.md

@@ -130,7 +130,7 @@ Read `<pack_dir>/design.md` first, especially `## Usage`, `## Hard Rules`, color
 When generating a deck:
 
 1. Call `copy_starter_component` with `kind: "deck-stage.js"`.
-2. Build `<deck-stage width="<canvas width>" height="<canvas height>">` using the `canvas` declared in `layouts.md` — source decks are not always 16:9, and a default-sized stage shifts every coordinate on the page. Each slide is one static `<section data-pptx-layout="<chosen archetype>">`.
+2. Build `<deck-stage width="<canvas width>" height="<canvas height>">` using the `canvas` declared in `layouts.md` — source decks are not always 16:9, and a default-sized stage shifts every coordinate on the page. Each slide is one static `<section data-pptx-layout="<chosen archetype>">`. For a multi-theme pack, choose layouts compatible with `default-theme` by default. When a page intentionally switches theme, add `data-pptx-theme="<theme>"`; the theme must be listed by that layout's `themes`.
 3. Inline CSS variables from `design.md` into the HTML `<style>` block using a `--ppt-*` prefix.
 4. **位移动画用独立的 `translate` 属性**：`@keyframes fadeUp { from{opacity:0; translate:0 24px} to{opacity:1; translate:0 0} }`。`transform` 是单一属性，动画里碰它会覆盖掉元素原有的那条（`left:50%; transform:translateX(-50%)` 的居中就此丢失）；`translate` / `rotate` / `scale` 各自独立，与已有 `transform` 叠加。
 5. Map `layouts.md` slots to absolute-positioned elements inside each section: expand `box: [x,y,w,h]` mechanically to `left/top/width/height`, then apply the slot's `css` declaration string unchanged. `box` owns geometry; `css` owns all rendering style, including the template's text padding, typography, alignment, line height, letter spacing, and rotation. Do not reinterpret PPTX fields or replace slot CSS with your own type scale. A slot with `asset` is a fixed image element: use that exact asset at that box on that archetype only; do not omit or replace it. Do not reflow any of this as generic web grids.

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

@@ -1243,7 +1243,21 @@ def layouts_from_template(d, shapes, cW, cH):
     sample_pages_of_layout = defaultdict(list)
     for slide_part, layout_part in lay_of_slide.items():
         sample_pages_of_layout[layout_part].append(slide_no(slide_part))
+    sampled_theme_counts = Counter(
+        theme_of_master.get(master_of.get(layout_part))
+        for layout_part in lay_of_slide.values()
+    )
+    sampled_theme_counts.pop(None, None)
     default_theme = topo.get('default')
+    if sampled_theme_counts:
+        highest = max(sampled_theme_counts.values())
+        leaders = sorted(
+            theme for theme, count in sampled_theme_counts.items()
+            if count == highest
+        )
+        if default_theme not in leaders:
+            default_theme = leaders[0]
+        topo['default'] = default_theme
     multi = len(topo.get('themes') or []) > 1
 
     rows = []
@@ -2394,7 +2408,9 @@ def emit_manifest(d, assets, vision_groups, ldir, archetypes=()):
          '  TODO: 一句话说清这套模板的视觉性格（底色 / 主色 / 字形 / 版面骨架），给消费模型定调。']
     themes = d['theme_topology'].get('themes') or ['single']
     if themes != ['single'] and len(themes) > 1:
-        L += ['themes: [%s]' % ', '.join(themes), 'default-theme: %s' % themes[0]]
+        default_theme = d['theme_topology'].get('default') or themes[0]
+        L += ['themes: [%s]' % ', '.join(themes),
+              'default-theme: %s' % default_theme]
     if assets:
         L.append('assets:')
         for a in assets:
@@ -2921,6 +2937,8 @@ def emit_layouts(archetypes, ldir, busy_hints=None, facts=None, recipes=None):
         L.append('  %s:' % a['name'])
         if a.get('role'):
             L.append('    role: %s' % a['role'])
+        if a.get('theme'):
+            L.append('    themes: [%s]' % a['theme'])
         if a['bg']:
             L.append('    background: %s' % a['bg'])
         fl = a.get('flow')
@@ -3056,6 +3074,8 @@ def emit_body(d, tokens, fonts, roles, assets, archetypes, exceptions, cusage, l
           '页数多于页型时，挑最接近的一个原样套用它的 slot：用不到的槽删掉，'
           '内容比槽多就按同类槽的间距等距加，**坐标一律沿用该页型给的那套，不要自己另起网格**。'
           '每个生成页面的 `<section>` 都写 `data-pptx-layout="<页型名>"`，'
+          '多主题包默认只选兼容 `default-theme` 的页型；确需切换时，该页同时写 '
+          '`data-pptx-theme="<主题名>"`，且主题必须属于该页型的 `themes`。'
           '交付前据此核验该页型绑定的背景与图片资产均已使用，且没有跨页型误用。' % sidecar,
           '3. **按页型给的形态落元素** —— 页型给 `flow` 就用流式，给 `slots` 就用绝对，'
           '两者只会出现一个。'

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

@@ -15,6 +15,7 @@ from draft import (asset_vision_contexts, bound_visual_candidates,  # noqa: E402
                    cover_background_media,
                    emit_asset_vision_groups, emit_layouts, emit_manifest,
                    fullscreen_overlay_media,
+                   layouts_from_template,
                    needs_asset_judgment, preserve_image_bearing_groups,
                    select_asset_vision_groups, slide_image_marks, slot_style,
                    visual_slot_candidates)
@@ -24,6 +25,125 @@ from package import (FONTSIZE_RE, Fail, apply_asset_decisions,  # noqa: E402
 
 
 class LayoutCssTest(unittest.TestCase):
+    def test_template_layouts_use_sampled_theme_as_default_and_keep_theme_scope(self):
+        dark_master = 'ppt/slideMasters/slideMaster1.xml'
+        light_master = 'ppt/slideMasters/slideMaster2.xml'
+        dark_layout = 'ppt/slideLayouts/slideLayout1.xml'
+        light_layout = 'ppt/slideLayouts/slideLayout2.xml'
+        data = {
+            'layouts': [
+                {'part': dark_layout, 'name': 'Dark content', 'used_by_slides': 2},
+                {'part': light_layout, 'name': 'Light content', 'used_by_slides': 0},
+            ],
+            'slides': [],
+            'theme_topology': {
+                'themes': ['light', 'dark'],
+                'default': 'light',
+                'per_master': [
+                    {'master': dark_master, 'theme_label': 'dark'},
+                    {'master': light_master, 'theme_label': 'light'},
+                ],
+            },
+            'reference_graph': {
+                'master_of_layout': {
+                    dark_layout: dark_master,
+                    light_layout: light_master,
+                },
+                'layout_of_slide': {
+                    'ppt/slides/slide1.xml': dark_layout,
+                    'ppt/slides/slide2.xml': dark_layout,
+                },
+            },
+            'background_composites': {},
+        }
+        shapes = [
+            {
+                'part': part,
+                'layer': 'layout',
+                'kind': 'sp',
+                'box': {'x': 100, 'y': 100, 'w': 800, 'h': 100},
+                'ph': {'type': 'title', 'idx': '1'},
+                'text': {'paragraphs': [{'runs': [{'text': 'Title', 'sz_px': 40}]}]},
+            }
+            for part in (dark_layout, light_layout)
+        ]
+
+        archetypes = layouts_from_template(data, shapes, 1920, 1080)
+
+        self.assertEqual('dark', data['theme_topology']['default'])
+        self.assertEqual(
+            {'content': 'dark', 'content-2': 'light'},
+            {item['name']: item['theme'] for item in archetypes},
+        )
+        with tempfile.TemporaryDirectory() as output_dir:
+            emit_layouts(archetypes, output_dir)
+            emit_manifest(data, [], [], output_dir, archetypes)
+            with open(os.path.join(output_dir, 'layouts.yaml'), encoding='utf-8') as stream:
+                layouts = stream.read()
+            with open(os.path.join(output_dir, 'manifest.yaml'), encoding='utf-8') as stream:
+                manifest = stream.read()
+        self.assertIn('    themes: [dark]', layouts)
+        self.assertIn('    themes: [light]', layouts)
+        self.assertIn('default-theme: dark', manifest)
+
+    def test_template_twin_layouts_keep_topology_but_scope_retained_layout(self):
+        dark_master = 'ppt/slideMasters/slideMaster1.xml'
+        light_master = 'ppt/slideMasters/slideMaster2.xml'
+        dark_layout = 'ppt/slideLayouts/slideLayout1.xml'
+        light_layout = 'ppt/slideLayouts/slideLayout2.xml'
+        data = {
+            'layouts': [
+                {'part': dark_layout, 'name': 'Content', 'used_by_slides': 2},
+                {'part': light_layout, 'name': 'Content', 'used_by_slides': 0},
+            ],
+            'slides': [],
+            'theme_topology': {
+                'themes': ['light', 'dark'],
+                'default': 'light',
+                'per_master': [
+                    {'master': dark_master, 'theme_label': 'dark'},
+                    {'master': light_master, 'theme_label': 'light'},
+                ],
+            },
+            'reference_graph': {
+                'master_of_layout': {
+                    dark_layout: dark_master,
+                    light_layout: light_master,
+                },
+                'layout_of_slide': {
+                    'ppt/slides/slide1.xml': dark_layout,
+                    'ppt/slides/slide2.xml': dark_layout,
+                },
+            },
+            'background_composites': {},
+        }
+        shapes = [
+            {
+                'part': part,
+                'layer': 'layout',
+                'kind': 'sp',
+                'box': {'x': 100, 'y': 100, 'w': 800, 'h': 100},
+                'ph': {'type': 'title', 'idx': '1'},
+                'text': {'paragraphs': [{'runs': [{'text': 'Title', 'sz_px': 40}]}]},
+            }
+            for part in (dark_layout, light_layout)
+        ]
+
+        archetypes = layouts_from_template(data, shapes, 1920, 1080)
+
+        self.assertEqual(1, len(archetypes))
+        self.assertEqual('dark', archetypes[0]['theme'])
+        with tempfile.TemporaryDirectory() as output_dir:
+            emit_layouts(archetypes, output_dir)
+            emit_manifest(data, [], [], output_dir, archetypes)
+            with open(os.path.join(output_dir, 'layouts.yaml'), encoding='utf-8') as stream:
+                layouts = stream.read()
+            with open(os.path.join(output_dir, 'manifest.yaml'), encoding='utf-8') as stream:
+                manifest = stream.read()
+        self.assertIn('    themes: [dark]', layouts)
+        self.assertIn('themes: [light, dark]', manifest)
+        self.assertIn('default-theme: dark', manifest)
+
     def test_text_slot_emits_rendering_style_as_css_only(self):
         shape = {
             'text': {

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

@@ -128,6 +128,31 @@ class LayoutAssetContractTest(unittest.TestCase):
                 '---\n'
             )
 
+    def write_theme_pack(self, root):
+        with open(os.path.join(root, 'design.md'), 'w', encoding='utf-8') as stream:
+            stream.write(
+                '---\n'
+                'themes: [dark, light]\n'
+                'default-theme: dark\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'
+                '  dark-content:\n'
+                '    role: content\n'
+                '    themes: [dark]\n'
+                '    slots: []\n'
+                '  light-content:\n'
+                '    role: content\n'
+                '    themes: [light]\n'
+                '    slots: []\n'
+                '---\n'
+            )
+
     def test_logo_is_limited_to_every_archetype_with_its_slot(self):
         with tempfile.TemporaryDirectory() as root:
             self.write_pack(root)
@@ -200,6 +225,102 @@ class LayoutAssetContractTest(unittest.TestCase):
                 validate_layout_assets(root, html, 'assets/pptx-volcengine'),
             )
 
+    def test_missing_deck_slides_is_rejected_even_without_fixed_assets(self):
+        with tempfile.TemporaryDirectory() as root:
+            self.write_theme_pack(root)
+            html = self.write_html(root, '<main><section>普通页面</section></main>')
+
+            self.assertEqual(
+                ['没有识别到 deck-stage 的直属 slide section，无法核验模板页型'],
+                validate_layout_assets(root, html, 'assets/pptx-theme'),
+            )
+
+    def test_layout_outside_default_theme_requires_explicit_theme(self):
+        with tempfile.TemporaryDirectory() as root:
+            self.write_theme_pack(root)
+            html = self.write_html(
+                root,
+                '<deck-stage>'
+                '<section data-pptx-layout="light-content">正文</section>'
+                '</deck-stage>',
+            )
+
+            self.assertEqual(
+                ['第 1 页页型 light-content 不支持当前主题 dark；'
+                 '允许主题: light。若确需切换，显式声明 data-pptx-theme'],
+                validate_layout_assets(root, html, 'assets/pptx-theme'),
+            )
+
+    def test_explicit_non_default_theme_must_match_layout(self):
+        with tempfile.TemporaryDirectory() as root:
+            self.write_theme_pack(root)
+            html = self.write_html(
+                root,
+                '<deck-stage>'
+                '<section data-pptx-layout="light-content" '
+                'data-pptx-theme="light">正文</section>'
+                '</deck-stage>',
+            )
+
+            self.assertEqual(
+                [],
+                validate_layout_assets(root, html, 'assets/pptx-theme'),
+            )
+
+    def test_unknown_explicit_theme_is_rejected(self):
+        with tempfile.TemporaryDirectory() as root:
+            self.write_theme_pack(root)
+            html = self.write_html(
+                root,
+                '<deck-stage>'
+                '<section data-pptx-layout="dark-content" '
+                'data-pptx-theme="brand-new">正文</section>'
+                '</deck-stage>',
+            )
+
+            self.assertEqual(
+                ['第 1 页声明了不存在的模板主题: brand-new'],
+                validate_layout_assets(root, html, 'assets/pptx-theme'),
+            )
+
+    def test_pack_without_fixed_assets_still_accepts_valid_layout(self):
+        with tempfile.TemporaryDirectory() as root:
+            self.write_theme_pack(root)
+            html = self.write_html(
+                root,
+                '<deck-stage>'
+                '<section data-pptx-layout="dark-content">正文</section>'
+                '</deck-stage>',
+            )
+
+            self.assertEqual(
+                [],
+                validate_layout_assets(root, html, 'assets/pptx-theme'),
+            )
+
+    def test_non_mapping_layout_entry_does_not_crash_theme_validation(self):
+        with tempfile.TemporaryDirectory() as root:
+            self.write_theme_pack(root)
+            with open(os.path.join(root, 'layouts.md'), 'w', encoding='utf-8') as stream:
+                stream.write(
+                    '---\n'
+                    'canvas: 1920x1080\n'
+                    'layouts:\n'
+                    '  malformed: unavailable\n'
+                    '---\n'
+                )
+            html = self.write_html(
+                root,
+                '<deck-stage>'
+                '<section data-pptx-layout="malformed">正文</section>'
+                '</deck-stage>',
+            )
+
+            self.assertEqual(
+                [],
+                validate_layout_assets(root, html, 'assets/pptx-theme'),
+            )
+
     def test_logo_in_global_css_is_rejected(self):
         with tempfile.TemporaryDirectory() as root:
             self.write_pack(root)

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

@@ -207,6 +207,7 @@ class SlideAssetParser(HTMLParser):
             tag == 'section' and parent and parent['tag'] == 'deck-stage')
         slide = ({
             'layout': attrs_map.get('data-pptx-layout'),
+            'theme': attrs_map.get('data-pptx-theme'),
             'references': [],
         } if slide_root else parent_slide)
         if slide_root:
@@ -270,8 +271,6 @@ def validate_layout_assets(pack_dir, html_path, asset_prefix):
     pack = Pack(pack_dir)
     owners = layout_asset_contract(pack)
     known_urls = asset_urls(pack, asset_prefix, owners)
-    if not known_urls:
-        return []
     asset_urls_by_id = {
         asset_id: url
         for url, asset_ids in known_urls.items()
@@ -285,6 +284,10 @@ def validate_layout_assets(pack_dir, html_path, asset_prefix):
     parser.close()
 
     problems = copied_asset_problems(pack, html_path, asset_prefix, owners)
+    if not parser.slides:
+        problems.append(
+            '没有识别到 deck-stage 的直属 slide section，无法核验模板页型')
+        return problems
     for url in parser.outside_urls:
         for asset_id in sorted(known_urls.get(normalized_path(url), ())):
             problems.append(
@@ -297,8 +300,26 @@ def validate_layout_assets(pack_dir, html_path, asset_prefix):
         if layout not in pack.layouts:
             problems.append('第 %d 页声明了不存在的模板页型: %s' % (number, layout))
             continue
+        layout_entry = pack.layouts[layout][0]
+        explicit_theme = slide['theme']
+        default_theme = pack.design.data.get('default-theme')
+        active_theme = explicit_theme or default_theme
+        if explicit_theme and explicit_theme not in pack.themes:
+            problems.append(
+                '第 %d 页声明了不存在的模板主题: %s' % (number, explicit_theme))
+            continue
+        layout_themes = (
+            (layout_entry.get('themes') or [])
+            if isinstance(layout_entry, dict) else []
+        )
+        if active_theme and layout_themes and active_theme not in layout_themes:
+            problems.append(
+                '第 %d 页页型 %s 不支持当前主题 %s；允许主题: %s。'
+                '若确需切换，显式声明 data-pptx-theme'
+                % (number, layout, active_theme, '、'.join(layout_themes)))
+            continue
         expected = layout_asset_instances(
-            pack.layouts[layout][0], set(pack.assets), pack.canvas)
+            layout_entry, set(pack.assets), pack.canvas)
         actual = []
         for reference in slide['references']:
             referenced_ids = set()

package/steering/nestjs-react-fullstack/skills/app-init-feasibility-guide/SKILL.md

@@ -71,6 +71,7 @@ available-agents:
 | 实时多人编辑、毫秒级协同 | 弱实时刷新、提交后同步 |
 | 原生 App、桌面端、浏览器插件 | Web 应用、响应式页面 |
 | 服务端持久写本地文件 | 平台文件服务、数据库、临时 `/tmp` |
+| 服务启动时下载大文件、全量同步或批量迁移 | 采用异步处理，避免阻塞服务启动 |
 | 无凭证调用受限第三方系统 | 要求用户提供 API、凭证或授权方式 |
 | 自建账号体系绕过平台登录 | 使用平台内置身份与权限 |
 | 多语言 i18n、深浅色主题切换（非平台内置） | 需自行实现并计入工作量；规格中先确认是否必要 |

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

@@ -232,8 +232,9 @@ shared/ # 前后端共享的目录
 - **三方集成**：调用第三方 API 需在后端实现，使用 @nestjs/axios
 - **能力边界**：服务端不支持文件上传（FaaS 限制），前端用 dataloom SDK 上传，服务端仅保存元信息
 - **环境判断**：`process.env.NODE_ENV === "production"` 表示生产环境
-- **文件系统**：**严禁使用 `fs` 写入非 `/tmp` 路径**（无状态 FaaS 容器）
+- **文件系统**：临时文件、下载内容和处理中间产物统一写入 `/tmp` 下的独立目录，用完后清理
 - **服务端运行时资源文件**（字体 / 证书 / 模板 / wasm 等需在运行时读取的非代码文件，CRITICAL — 发布后静默失效根因）：① 必须在 `nest-cli.json` 的 `assets` 中声明（如 `{"include": "assets/<dir>/**/*", "outDir": "dist/server"}`），否则不会进 `dist/` 构建产物；② 路径用 `__dirname` 相对**编译产物**定位（如 `path.join(__dirname, "../assets/...")`），**禁止 `process.cwd()` 相对源码路径**——dev 跑源码能命中、发布跑 `dist/` 会落空；③ 资源缺失或加载失败必须 **fail-loud**（抛错或明确错误日志），禁止 `catch` 后静默返回残缺产物
+- **启动生命周期**：`constructor`、`onModuleInit` 和 `onApplicationBootstrap` 应快速完成，避免在其中下载大文件、全量同步或批量迁移；仅将钩子声明为 `async` 仍会被等待，无法缩短启动时间
 
 ## 日志约定