@lark-apaas/coding-steering 0.1.43-alpha.20260831015213 → 0.1.43

package/package.json

@@ -1,14 +1,11 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.43-alpha.20260831015213",
+  "version": "0.1.43",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [
     "steering"
   ],
-  "scripts": {
-    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
-  },
   "devDependencies": {
     "markdownlint-cli": "^0.47.0"
   },
@@ -20,5 +17,8 @@
     "miaoda",
     "coding-steering"
   ],
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
+  }
+}

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

@@ -155,7 +155,7 @@ shared/ # 前后端共享的目录
 
 ## 依赖使用规范
 
-1. **子包完整性检查**：部分库有多个子包（如 `@radix-ui/react-*` 系列每个组件都是独立子包），添加 import 后必须确认 package.json 中包含所有需要的子包
+1. **子包完整性检查**：部分库有多个子包（如 `@dnd-kit/core` + `@dnd-kit/sortable` + `@dnd-kit/utilities`），添加 import 后必须确认 package.json 中包含所有需要的子包
 2. 用法不清时查看 readme，可进一步搜索或网页访问获取信息
 
 ## 文件命名约定
@@ -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` 仍会被等待，无法缩短启动时间
 
 ## 日志约定
 
@@ -569,8 +570,6 @@ async createArticle(@Req() req: Request, @Body() dto: CreateArticleDto) {
 {% if projectMeta['flags']['supportTiptapAndStreamdown'] %}
 - **富文本**: `business-ui/tiptap-editor`（阅读 README.md）
 - **Markdown 渲染**: `components/ui/streamdown`（内置 prose 排版）
-{% else %}
-- **Markdown 渲染**: `components/ui/markdown`（react-markdown + remark-gfm，内置 prose 排版）
 {% endif %}
 
 ## API 请求
@@ -608,8 +607,6 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 {% if projectMeta['flags']['supportTiptapAndStreamdown'] %}
 | TiptapEditorComplete | `business-ui/tiptap-editor` | 富文本编辑器 |
 | Streamdown | `components/ui/streamdown` | Markdown/流式渲染 |
-{% else %}
-| Markdown | `components/ui/markdown` | Markdown 渲染（react-markdown + remark-gfm） |
 {% endif %}
 
 ### 组件 Skill 召回规则（强制执行）
@@ -773,12 +770,15 @@ return <h1>{data?.title || '未知标题'}</h1>;
 | 验证 | zod |
 | 工具函数 | lodash |
 | 样式 | clsx |
-| 文件上传 | 原生 `<input type="file">`，用 shadcn 组件封装样式 |
+| Excel | xlsx（**仅前端实现，禁止服务端实现**。解析后将结构化数据传到服务端保存） |
+| PDF 导出 | jspdf + html2canvas（**仅前端实现，禁止服务端实现**） |
+| 文件上传 | react-dropzone |
+| 二维码 | qrcode.react |
 | 用户反馈 | sonner |
-| 数字动画 | `requestAnimationFrame` 手写，或 framer-motion 的 `animate` |
-| Base64 | 原生 `atob`/`btoa`（Unicode 内容先经 `TextEncoder`/`TextDecoder`）；服务端用 `Buffer` |
-
-> Excel 解析、PDF 导出、二维码、拖拽、3D 场景等能力已随依赖瘦身不再预装（xlsx、jspdf、html2canvas、qrcode.react、@dnd-kit、react-dropzone、react-countup、js-base64、cobe 已从模板移除）。确有此类需求时，先在 package.json 显式添加所需依赖并安装，再编写代码。
+| 拖拽 | @dnd-kit/core |
+| 数字动画 | react-countup |
+| Base64 | js-base64 — `import { encode, decode } from 'js-base64'` |
+| 3D 场景 | cobe |
 
 ## 滚动分页最佳实践
 

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

@@ -20,6 +20,7 @@ gate-tools:
 | 获取运行时投影 | 调用 `get_plugin_ai_json(pluginInstanceId)` |
 | Client 侧调用 | `capabilityClient.load(id).call(actionKey, input)`（流式用 `callStream`） |
 | Server 侧调用（仅兜底） | `capabilityService.load(id).call(actionKey, input)` |
+| 长耗时 AI 结果 | 大体量/多字段/多份/多语言/文件或多模态串联等结构信号命中时，优先前端 `callStream` 渐进展示；需保存则流式结束后复用 CRUD 落库；仅在 Client 侧无法满足时使用后端任务记录 + 状态查询 + 结果读取；禁止单个 HTTP 请求等待完整结果后才返回 |
 | capabilityClient 导入 | `import { capabilityClient } from '@lark-apaas/client-toolkit'` |
 | CapabilityService 导入 | `import { CapabilityService } from '@lark-apaas/fullstack-nestjs-core';` |
 
@@ -70,6 +71,7 @@ gate-tools:
    - 必须先调 `get_plugin_ai_json(pluginInstanceId)`，再产出 **Schema 摘录卡**（格式见 `references/plugin-coding-guide.md`）；摘录卡字段缺失禁止编码，`output.fields` 必须完整列出且每个输出字段在代码中被消费（持久化或展示）
    - 按 `actions[].key` 选 actionKey；严格按 `inputSchema` 构造入参（`type: array` 字段必须传数组）、按 `outputSchema` 解析出参——流式 chunk 是**对象**（按字段解构如 `chunk.content`，禁止当字符串拼接），非流式同理按字段名读取；**务必阅读并遵循 `readme`**
    - 调用侧：优先 Client（`unary` → `call()`，`stream` → `callStream()`）；触发器/定时任务、敏感凭证、强事务、结果需落库 → Server 侧
+   - 高耗时 AI capability 闸门：若运行时投影或功能设计显示输出规模大、输出字段多、需要多份结果、多语言/长文本、文件或多模态输入后继续生成、多个 capability 串联、或结果需后续查看/落库，禁止把完整生成放进一个同步 HTTP 请求等待；能由前端承接时优先 `callStream` 渐进展示，需保存则流式结束后复用 CRUD 落库；仅在 Client 侧无法满足时后端创建任务记录后快速返回、由前端短轮询状态/结果，或拆成多个独立小调用
 4. **代码放置**：Client（默认，用户交互触发）→ `client/` 组件/hooks；Server（兜底）→ `server/` Service。
 5. **真实调用冒烟（完成前必须）**：至少成功调用一次 `call()` 或 `callStream()`（按 outputSchema 读 chunk）；失败日志含最小字段（字段清单见 `references/plugin-coding-guide.md`）。无冒烟结果不得宣告完成。
 
@@ -136,6 +138,9 @@ const structured = await capabilityClient
         ├── 输出包含多个独立字段（标题+正文+评分等）
         │   → 拆成多个独立插件并行调用（⭐ 优先）或用 ai-text-to-json
         │   → ⛔ 禁止用 ai-text-generate + 正则/split 解析多字段
+        ├── 输出规模大（多份结果、多语言、长正文、多章节或批量对象）
+        │   → 优先拆分为多个独立生成单元；需要汇总持久化时使用任务状态模型承接
+        │   → ⛔ 禁止一个后端 HTTP 请求同步等待所有生成结果后才响应
         └── 输出为单一文本（仅展示，不需解析）→ ai-text-generate
 ```
 
@@ -203,9 +208,9 @@ const structured = await capabilityClient
 
 1. **禁止静默吞异常**：每个 `catch` 至少满足其一——向用户展示错误（toast/页面状态），或触发补偿机制（重试/降级/记录待处理列表）
 2. **异步操作必须有终态**：不阻塞主流程的插件调用须在 DB 维护状态（pending → success/failed），前端必须展示 failed，不能永远 loading
-3. **通知类插件失败必须有补偿**：如 `send-feishu-message` 失败，至少记录"待发送"列表或 UI 提示"通知发送失败，请手动联系"
-4. **配置完整性（load 前必查）**：`load(id)` 前确认实例已创建且 id 与代码完全匹配，否则抛 `CapabilityNotFoundError`（开发态 Top 错误）；load/call 失败时停止后续请求避免放大错误；**缓存 load 结果**，同一 id 不重复 load
-5. **线上/客户反馈的插件问题先查 runtime log 取证**：用户反馈「线上 / 已发布」的插件问题（飞书消息发不出 / 插件不生效 / capability 调用「用户收不到」）时，**先查线上 runtime log 再定位代码**——用 `miaoda observability log`（必要时 `trace`）看 CapabilityService 真实错误、plugin_key、action、必填参数/输入校验错误，拿到线上 ERROR/WARN 再读代码修复。**即使你已在代码里读到一个疑似原因，也不得据此直接下根因、跳过取证**——静态代码里的可疑点常不是运行时真正的失败点（线上真错误多为运行时入参为空 / 校验失败 / 授权态问题，代码静态看不出），runtime log 是这类问题下结论前的必经步。沙箱 `read_logs` 只覆盖 dev 态，**不能**作为「线上插件无错误」的证据；纯本地 dev 态插件报错仍用 `read_logs`
+3. **长耗时 AI 生成不得同步等完**：大体量、多字段、多份、多语言、文件/多模态串联或需要持久化的 AI capability 调用，触发接口必须快速返回任务状态或采用前端流式展示；若 `api_request`、浏览器操作或页面请求出现超时/连接断开，不能只凭服务端最终日志或数据库最终写入宣告成功，必须证明用户侧存在可读取的终态结果
+4. **通知类插件失败必须有补偿**：如 `send-feishu-message` 失败，至少记录"待发送"列表或 UI 提示"通知发送失败，请手动联系"
+5. **配置完整性（load 前必查）**：`load(id)` 前确认实例已创建且 id 与代码完全匹配，否则抛 `CapabilityNotFoundError`（开发态 Top 错误）；load/call 失败时停止后续请求避免放大错误；**缓存 load 结果**，同一 id 不重复 load
 
 ## 缓存与幂等性
 
@@ -240,7 +245,7 @@ const structured = await capabilityClient
 
 ### 通知接收人动态解析
 
-接收人（`receiverUserList`/`receiverGroupList` 等）按角色/条件变化时，必须实时查询角色成员经 `input` 传入（角色/成员的运行时查询写法见 `authz-guide` 技能），禁止硬编码或凭经验拼装 ID。如引入缓存，必须提供显式失效手段（如角色变更时清缓存）并明示 TTL，禁止无失效手段的常驻缓存导致接收人信息过期。通知发送失败的补偿要求见上文「插件调用错误处理」第 3 条铁律，不重复展开。
+接收人（`receiverUserList`/`receiverGroupList` 等）按角色/条件变化时，必须实时查询角色成员经 `input` 传入（角色/成员的运行时查询写法见 `authz-guide` 技能），禁止硬编码或凭经验拼装 ID。如引入缓存，必须提供显式失效手段（如角色变更时清缓存）并明示 TTL，禁止无失效手段的常驻缓存导致接收人信息过期。通知发送失败的补偿要求见上文「插件调用错误处理」第 4 条铁律，不重复展开。
 
 ## 飞书深链 URL 规范
 

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

@@ -2,15 +2,19 @@
 
 ### 核心原则：根据场景选择调用侧
 
-**默认优先在 Client 侧调用 capabilityClient；但当插件结果需要持久化到数据库时，应考虑在 Server 侧调用或确保前端调用后及时通过后端接口保存。**
+**默认优先在 Client 侧调用 capabilityClient；流式或高耗时 AI 生成优先 `callStream` 渐进展示。结果需要持久化时，优先在流式结束后通过已有后端接口保存；只有 Client 侧无法满足时才切到 Server 侧。**
+
+**高耗时 AI capability 先判调用形态**：只要输出规模大、输出字段多、需要多份结果、多语言/长文本、文件或多模态输入后继续生成、多个 capability 串联、或结果需后续查看/落库，就不得把完整 AI 结果塞进一个同步 HTTP 请求等待。能由前端承接时，优先用前端 `callStream` 渐进展示，并在流式结束后按需复用已有 CRUD 接口保存结果；只有 Client 侧无法满足（触发器/敏感凭证/强事务/必须由后端保证落库一致性等）时，才采用后端任务记录 + 状态/结果查询，避免把后台任务作为默认方案。
+
 **严禁** import ｛ capabilityClient ｝ from '@lark-apaas/client-capability'。
 **唯一指定**的导入方式是 import { capabilityClient } from '@lark-apaas/client-toolkit';
 
 | 优先级 | 场景 | 调用方式 |
 |-------|------|---------|
-| **首选** | 绝大多数场景 | `capabilityClient.load(id).call()` |
-| **首选** | 流式输出场景 | `capabilityClient.load(id).callStream()` |
-| **兜底** | Client 侧无法满足时 | `CapabilityService.load(id).call()` |
+| **首选** | 绝大多数即时展示场景 | `capabilityClient.load(id).call()` |
+| **首选** | 流式输出，或高耗时但可由前端承接的 AI 生成 | `capabilityClient.load(id).callStream()`（流式结束后按需持久化） |
+| **必要时** | 高耗时且 Client 侧无法满足：触发器、敏感凭证、强事务、必须由后端保证落库一致性 | 后端任务记录 + 后台调用 `CapabilityService.load(id).call()` + 前端短轮询状态/结果 |
+| **兜底** | Client 侧无法满足且单次调用可在交互边界内完成 | `CapabilityService.load(id).call()` |
 
 #### 什么情况下应使用 Server 侧？
 
@@ -19,7 +23,7 @@
 1. **涉及敏感凭证**：调用需要服务端私密 token/secret，不适合暴露给前端
 2. **必须后端编排**：多个插件调用之间有强事务依赖，需要后端统一编排
 3. **触发器/定时任务场景**：没有前端上下文，只能由后端发起
-4. **插件结果需要持久化**：调用结果需要保存到数据库，在 Server 侧可以在同一方法中完成调用+落库，保证数据一致性
+4. **插件结果需要持久化**：调用结果需要保存到数据库；能由前端承接时，优先前端 `callStream` 渐进展示并在结束后复用已有 CRUD 接口保存；只有 Client 侧无法满足或必须由后端保证落库一致性时，才在 Server 侧调用并落库。若此时输出规模大、字段多、结果多份或需多步能力串联，必须改为任务记录 + 后台执行 + 状态/结果查询，避免一个 HTTP 请求等待完整生成
 
 > **提示**：如果插件结果不需要存储、仅用于即时展示（如流式生成文本、发送消息），优先在前端调用。但当结果需要保存到数据库时，不要回避使用 Server 侧。
 
@@ -42,9 +46,13 @@
 
 ```
 插件结果是否需要持久化到数据库？
-├── 否（一次性即时展示）→ Client 侧调用（默认）
-└── 是 → 推荐方案 A：Server 侧调用，在 Service 中调用插件并在同一方法中落库
-         备选方案 B：Client 侧调用插件 → 成功后通过已有 CRUD 接口保存结果
+├── 否（一次性即时展示）
+│   ├── `outputMode=stream` 或内容生成较慢 → Client 侧 `callStream()` 渐进展示
+│   └── 单次短输出 → Client 侧 `call()`（默认）
+└── 是
+    ├── `outputMode=stream` 且前端可承接 → 推荐方案 A：Client 侧 `callStream()` 渐进展示，成功后通过已有 CRUD 接口保存结果
+    ├── 输出较小且可在交互边界内完成、且必须由后端保证一致性 → Server 侧调用并在同一方法中落库
+    └── Client 侧无法满足且输出规模大/多字段/多份/多语言/多步骤 → 方案 B：Server 侧创建任务记录，快速返回任务状态；后台调用插件并落库；前端短轮询状态/结果
 ```
 
 | 应避免的做法 | 推荐做法 |
@@ -271,10 +279,11 @@ function MultiPluginStreamExample({ recordId }: { recordId: string }) {
 2. 一个 `stream` action 的真实调用结果（chunk 按 `outputSchema` 字段读取）
 3. 调用失败时的最小日志字段齐全
 4. 若无法执行真实调用，必须明确写明阻塞原因，禁止直接标记“开发完成”
+5. 若用户触发 AI 生成的请求超时、连接断开或工具返回超时，必须判定为验收失败；只有触发请求快速返回、随后能通过页面或接口读到明确完成或失败终态和结果，才允许标记通过
 
 ### Server 侧调用方式（仅兜底场景）
 
-> 以下场景适合使用 Server 侧调用，特别是涉及数据持久化时不要回避后端。
+> 以下场景适合使用 Server 侧调用；若前端 `callStream` + 既有 CRUD 保存即可满足展示和持久化，不要优先引入后端后台任务。
 
 #### 1. 何时适合用 Server 侧？
 
@@ -285,6 +294,7 @@ function MultiPluginStreamExample({ recordId }: { recordId: string }) {
 | 敏感凭证调用 | 凭证不能暴露给前端 | 调用需要 admin token 的 API |
 | 强事务编排 | 多步骤需要原子性 | 创建记录 → 发通知 → 更新状态必须全成功或全回滚 |
 | 插件结果需持久化 | 调用结果需保存到数据库 | AI 分类/摘要结果需落库、文档解析的结构化数据需入库、图片识别结果需关联业务记录、语音转文字结果需存档等 |
+| 高耗时 AI 生成需后续查看 | 请求不能长期占用用户交互链路 | 批量、多版本、多语言、长文本、多字段结构化生成，或文件/多模态分析后再生成内容 |
 
 #### 2. NestJS 注入方式
 
@@ -328,6 +338,7 @@ try {
 
 - PluginInstance 调用在 Server 侧通常属于 **外部依赖 / side-effect**
 - 除非业务明确要求强一致性，**默认不应阻塞主业务流程**
+- 已选择 Server 侧承接的高耗时 AI capability 必须有可观测状态：创建任务时记录处理进度、完成终态、失败终态、输入摘要、错误信息和结果引用；触发接口只返回任务标识与当前状态，前端通过短轮询读取进度和最终结果
 
 推荐写法：异步触发 + catch 兜底：
 

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

@@ -129,7 +129,7 @@ shared/ # 前后端共享的目录
 
 1. 优先使用项目已有依赖，仅在无法实现时安装新依赖
 2. 使用前先查看 `package.json` 确保依赖已存在
-3. **子包完整性检查**：部分库有多个子包（如 `@radix-ui/react-*` 系列每个组件都是独立子包），添加 import 后必须确认 package.json 中包含所有需要的子包
+3. **子包完整性检查**：部分库有多个子包（如 `@dnd-kit/core` + `@dnd-kit/sortable` + `@dnd-kit/utilities`），添加 import 后必须确认 package.json 中包含所有需要的子包
 4. 用法不清时查看 readme，可进一步搜索或网页访问获取信息
 
 ## 文件命名约定
@@ -443,13 +443,14 @@ NestJS 自己不读 env。直连 NestJS 端口 → header 缺失 → `req.userCo
 
 - **框架**: React 19 + TypeScript
 - **路由**: React Router DOM v6
-- **样式**: tailwindcss（语义化 token）为主，复杂 CSS 用 CSS Modules（`*.module.css`），动态计算值用行内 `style`
+- **样式**: styled-jsx + tailwindcss（语义化 token）。styled-jsx 使用前提见下方"样式开发"
 - **UI 组件库**: shadcn/ui — Use components for functionality, heavily style them
 - **图表**: ReactECharts，**开发前必须调用 `/charts-skill`**
 - **图标**: Lucide React（唯一图标库，禁止 Emoji 和其他图标库）
 - **表格/表单/图表**: 见下方"组件 Skill 召回规则"，开发前必须先调用对应 Skill
 - **用户**: 用户信息展示/选择必须用 `business-ui` 组件（阅读 README.md），禁止直接展示 userId
-- **Markdown 渲染**: `components/ui/markdown`（react-markdown + remark-gfm，内置 prose 排版）
+- **富文本**: `business-ui/tiptap-editor`（阅读 README.md）
+- **Markdown 渲染**: `components/ui/streamdown`（内置 prose 排版）
 
 ## API 请求
 
@@ -482,7 +483,8 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 | --------------------------------------------------- | --------------------------------------- | --------------------------------- |
 | Table                                               | `@lark-apaas/client-toolkit/antd-table` | 数据表格，**先调 `/table-skill`** |
 | UserSelect/UserDisplay/UserProfile/DepartmentSelect | `business-ui/*`                         | 用户/部门选择展示                 |
-| Markdown                                            | `components/ui/markdown`                | Markdown 渲染（react-markdown + remark-gfm） |
+| TiptapEditorComplete                                | `business-ui/tiptap-editor`             | 富文本编辑器                      |
+| Streamdown                                          | `components/ui/streamdown`              | Markdown/流式渲染                 |
 
 ### 组件 Skill 召回规则（强制执行）
 
@@ -533,7 +535,7 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 ```
 需要写样式？
 ├─ 基础布局/间距/颜色 → Tailwind ✅
-├─ 复杂动画/伪元素/高级CSS → CSS Modules（`*.module.css`）✅
+├─ 复杂动画/伪元素/高级CSS → styled-jsx ✅
 └─ JS动态计算值 → 行内 style ✅
 ```
 
@@ -546,12 +548,10 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 - **arbitrary values 中空格用下划线**：`from-[hsl(215_60%_18%)]` 非 `from-[hsl(215 60% 18%)]`
 - `tailwind-theme.css` 自定义属性用 `hsl(H, S%, L%)` 格式（非 `23 10% 23%`）
 
-### CSS Modules 规范
+### styled-jsx 规范
 
-- 文件名：`ComponentName.module.css`，与组件同目录
-- 导入用 `import styles from './ComponentName.module.css'`，通过 `className={styles.foo}` 引用
-- 类名用 camelCase，避免使用连字符（`styles.myClass` 而非 `styles['my-class']`）
-- 全局样式（如动画 keyframes、CSS 变量）放在 `client/src/index.css` 或 `tailwind-theme.css`
+- **技术栈一致性**：仅在已配置 styled-jsx 插件的项目中使用。`package.json` 无 `styled-jsx` 依赖则**禁用**，否则运行时 SyntaxError
+- **禁止动态插值**：`<style jsx>` 内禁止 `${...}` 等表达式（会卡死）。动态值放 CSS 变量，用 `var(--xxx)` 引用
 
 ### 布局/排版
 
@@ -635,12 +635,15 @@ return <h1>{data?.title || '未知标题'}</h1>;
 | 验证       | zod                                                                      |
 | 工具函数   | lodash                                                                   |
 | 样式       | clsx                                                                     |
-| 文件上传   | 原生 `<input type="file">`，用 shadcn 组件封装样式                       |
+| Excel      | xlsx（**仅前端实现，禁止服务端实现**。解析后将结构化数据传到服务端保存） |
+| PDF 导出   | jspdf + html2canvas（**仅前端实现，禁止服务端实现**）                    |
+| 文件上传   | react-dropzone                                                           |
+| 二维码     | qrcode.react                                                             |
 | 用户反馈   | sonner                                                                   |
-| 数字动画   | `requestAnimationFrame` 手写，或 framer-motion 的 `animate`              |
-| Base64     | 原生 `atob`/`btoa`（Unicode 内容先经 `TextEncoder`/`TextDecoder`）；服务端用 `Buffer` |
-
-> Excel 解析、PDF 导出、二维码、拖拽、3D 场景等能力已随依赖瘦身不再预装（xlsx、jspdf、html2canvas、qrcode.react、@dnd-kit、react-dropzone、react-countup、js-base64、cobe 已从模板移除）。确有此类需求时，先在 package.json 显式添加所需依赖并安装，再编写代码。
+| 拖拽       | @dnd-kit/core                                                            |
+| 数字动画   | react-countup                                                            |
+| Base64     | js-base64 — `import { encode, decode } from 'js-base64'`                 |
+| 3D 场景    | cobe                                                                     |
 
 ## 滚动分页最佳实践
 

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

@@ -35,6 +35,7 @@ lark-cli apps --help 2>&1 | grep -q '+plugin-install' && echo "READY" || echo "M
 | Client 侧非流式调用 | `capabilityClient.load(id).call(actionKey, input)` |
 | Client 侧流式调用 | `capabilityClient.load(id).callStream(actionKey, input)` |
 | Server 侧调用（仅兜底） | `capabilityService.load(id).call(actionKey, input)` |
+| 长耗时 AI 结果 | 大体量/多字段/多份/多语言/文件或多模态串联等结构信号命中时，优先前端 `callStream` 渐进展示；需保存则流式结束后复用 CRUD 落库；仅在 Client 侧无法满足时使用后端任务记录 + 状态查询 + 结果读取；禁止单个 HTTP 请求等待完整结果后才返回 |
 | capabilityClient 导入 | `import { capabilityClient } from '@lark-apaas/client-toolkit'` |
 | CapabilityService 导入 | `import { CapabilityService } from '@lark-apaas/fullstack-nestjs-core';` |
 | CapabilityService 注入 | `@Inject() private readonly capabilityService: CapabilityService` |
@@ -516,7 +517,9 @@ npx @lark-apaas/miaoda-cli plugin list --id <instance_id>
 2. 结果供后续功能消费
 3. 用户再次访问时需要看到结果
 
-**推荐**：Server 侧 Service 调用插件 + 同一方法落库。**备选**：Client 侧调用 → 流式结束后调已有 CRUD 接口保存。
+**推荐**：能由前端承接时，Client 侧 `callStream` 渐进展示，流式结束后调已有 CRUD 接口保存。**必要时**：敏感凭证、触发器、强事务或必须由后端保证落库一致性时，Server 侧 Service 调用插件并落库。
+
+**高耗时 AI capability 闸门**：若插件输出定义或功能设计显示输出规模大、输出字段多、需要多份结果、多语言/长文本、文件或多模态输入后继续生成、多个 capability 串联、或结果需后续查看/落库，禁止把完整生成放进一个同步 HTTP 请求等待；能由前端承接时优先 `callStream` 渐进展示，需保存则流式结束后复用 CRUD 落库；仅在 Client 侧无法满足时后端创建任务记录后快速返回、由前端短轮询状态/结果，或拆成多个独立小调用。
 
 ### 生成代码
 
@@ -535,7 +538,8 @@ npx @lark-apaas/miaoda-cli plugin list --id <instance_id>
 
 1. **禁止静默吞异常**：每个 `catch` 块必须向用户展示错误或触发补偿
 2. **异步操作必须有终态**：DB 中维护状态（pending → success / failed）
-3. **插件失败必须有补偿**：至少记录到待处理列表或提示用户重试
+3. **长耗时 AI 生成不得同步等完**：大体量、多字段、多份、多语言、文件/多模态串联或需要持久化的 AI capability 调用，触发接口必须快速返回任务状态或采用前端流式展示；若接口请求、浏览器操作或页面请求出现超时/连接断开，不能只凭服务端最终日志或数据库最终写入宣告成功，必须证明用户侧存在可读取的终态结果
+4. **插件失败必须有补偿**：至少记录到待处理列表或提示用户重试
 
 ## 缓存与幂等性
 

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

@@ -2,15 +2,19 @@
 
 ### 核心原则：根据场景选择调用侧
 
-**默认优先在 Client 侧调用 capabilityClient；但当插件结果需要持久化到数据库时，应考虑在 Server 侧调用或确保前端调用后及时通过后端接口保存。**
+**默认优先在 Client 侧调用 capabilityClient；流式或高耗时 AI 生成优先 `callStream` 渐进展示。结果需要持久化时，优先在流式结束后通过已有后端接口保存；只有 Client 侧无法满足时才切到 Server 侧。**
+
+**高耗时 AI capability 先判调用形态**：只要输出规模大、输出字段多、需要多份结果、多语言/长文本、文件或多模态输入后继续生成、多个 capability 串联、或结果需后续查看/落库，就不得把完整 AI 结果塞进一个同步 HTTP 请求等待。能由前端承接时，优先用前端 `callStream` 渐进展示，并在流式结束后按需复用已有 CRUD 接口保存结果；只有 Client 侧无法满足（触发器/敏感凭证/强事务/必须由后端保证落库一致性等）时，才采用后端任务记录 + 状态/结果查询，避免把后台任务作为默认方案。
+
 **严禁** import ｛ capabilityClient ｝ from '@lark-apaas/client-capability'。
 **唯一指定**的导入方式是 import { capabilityClient } from '@lark-apaas/client-toolkit';
 
 | 优先级 | 场景 | 调用方式 |
 |-------|------|---------|
-| **首选** | 绝大多数场景 | `capabilityClient.load(id).call()` |
-| **首选** | 流式输出场景 | `capabilityClient.load(id).callStream()` |
-| **兜底** | Client 侧无法满足时 | `CapabilityService.load(id).call()` |
+| **首选** | 绝大多数即时展示场景 | `capabilityClient.load(id).call()` |
+| **首选** | 流式输出，或高耗时但可由前端承接的 AI 生成 | `capabilityClient.load(id).callStream()`（流式结束后按需持久化） |
+| **必要时** | 高耗时且 Client 侧无法满足：触发器、敏感凭证、强事务、必须由后端保证落库一致性 | 后端任务记录 + 后台调用 `CapabilityService.load(id).call()` + 前端短轮询状态/结果 |
+| **兜底** | Client 侧无法满足且单次调用可在交互边界内完成 | `CapabilityService.load(id).call()` |
 
 #### 什么情况下应使用 Server 侧？
 
@@ -19,7 +23,7 @@
 1. **涉及敏感凭证**：调用需要服务端私密 token/secret，不适合暴露给前端
 2. **必须后端编排**：多个插件调用之间有强事务依赖，需要后端统一编排
 3. **触发器/定时任务场景**：没有前端上下文，只能由后端发起
-4. **插件结果需要持久化**：调用结果需要保存到数据库，在 Server 侧可以在同一方法中完成调用+落库，保证数据一致性
+4. **插件结果需要持久化**：调用结果需要保存到数据库；能由前端承接时，优先前端 `callStream` 渐进展示并在结束后复用已有 CRUD 接口保存；只有 Client 侧无法满足或必须由后端保证落库一致性时，才在 Server 侧调用并落库。若此时输出规模大、字段多、结果多份或需多步能力串联，必须改为任务记录 + 后台执行 + 状态/结果查询，避免一个 HTTP 请求等待完整生成
 
 > **提示**：如果插件结果不需要存储、仅用于即时展示（如流式生成文本、发送消息），优先在前端调用。但当结果需要保存到数据库时，不要回避使用 Server 侧。
 
@@ -31,9 +35,13 @@
 
 ```
 插件结果是否需要持久化到数据库？
-├── 否 → Client 侧调用（默认）
-└── 是 → 推荐方案 A：Server 侧调用，在 Service 中调用插件并在同一方法中落库
-         备选方案 B：Client 侧调用插件 → 成功后通过已有 CRUD 接口保存结果
+├── 否
+│   ├── `outputMode=stream` 或内容生成较慢 → Client 侧 `callStream()` 渐进展示
+│   └── 单次短输出 → Client 侧 `call()`（默认）
+└── 是
+    ├── `outputMode=stream` 且前端可承接 → 推荐方案 A：Client 侧 `callStream()` 渐进展示，成功后通过已有 CRUD 接口保存结果
+    ├── 输出较小且可在交互边界内完成、且必须由后端保证一致性 → Server 侧调用并在同一方法中落库
+    └── Client 侧无法满足且输出规模大/多字段/多份/多语言/多步骤 → 方案 B：Server 侧创建任务记录，快速返回任务状态；后台调用插件并落库；前端短轮询状态/结果
 ```
 
 | 应避免的做法 | 推荐做法 |
@@ -233,10 +241,11 @@ function MultiPluginStreamExample() {
 2. 一个 `stream` action 的真实调用结果（chunk 按 `outputSchema` 字段读取）
 3. 调用失败时的最小日志字段齐全
 4. 若无法执行真实调用，必须明确写明阻塞原因，禁止直接标记"开发完成"
+5. 若用户触发 AI 生成的请求超时、连接断开或工具返回超时，必须判定为验收失败；只有触发请求快速返回、随后能通过页面或接口读到明确完成或失败终态和结果，才允许标记通过
 
 ### Server 侧调用方式（仅兜底场景）
 
-> 以下场景适合使用 Server 侧调用，特别是涉及数据持久化时不要回避后端。
+> 以下场景适合使用 Server 侧调用；若前端 `callStream` + 既有 CRUD 保存即可满足展示和持久化，不要优先引入后端后台任务。
 
 #### 1. 何时适合用 Server 侧？
 
@@ -247,6 +256,7 @@ function MultiPluginStreamExample() {
 | 敏感凭证调用 | 凭证不能暴露给前端 | 调用需要 admin token 的 API |
 | 强事务编排 | 多步骤需要原子性 | 创建记录 → 发通知 → 更新状态必须全成功或全回滚 |
 | 插件结果需持久化 | 调用结果需保存到数据库 | AI 分类/摘要结果需落库、文档解析的结构化数据需入库、图片识别结果需关联业务记录、语音转文字结果需存档等 |
+| 高耗时 AI 生成需后续查看 | 请求不能长期占用用户交互链路 | 批量、多版本、多语言、长文本、多字段结构化生成，或文件/多模态分析后再生成内容 |
 
 #### 2. NestJS 注入方式
 
@@ -290,6 +300,7 @@ try {
 
 - PluginInstance 调用在 Server 侧通常属于 **外部依赖 / side-effect**
 - 除非业务明确要求强一致性，**默认不应阻塞主业务流程**
+- 已选择 Server 侧承接的高耗时 AI capability 必须有可观测状态：创建任务时记录处理进度、完成终态、失败终态、输入摘要、错误信息和结果引用；触发接口只返回任务标识与当前状态，前端通过短轮询读取进度和最终结果
 
 推荐写法：异步触发 + catch 兜底：