@lark-apaas/coding-steering 0.1.42-alpha.20260827112854 → 0.1.42

package/package.json

@@ -1,14 +1,11 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.42-alpha.20260827112854",
+  "version": "0.1.42",
   "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/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

@@ -443,7 +443,7 @@ 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 和其他图标库）
@@ -535,7 +535,7 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 ```
 需要写样式？
 ├─ 基础布局/间距/颜色 → Tailwind ✅
-├─ 复杂动画/伪元素/高级CSS → CSS Modules（`*.module.css`）✅
+├─ 复杂动画/伪元素/高级CSS → styled-jsx ✅
 └─ JS动态计算值 → 行内 style ✅
 ```
 
@@ -548,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)` 引用
 
 ### 布局/排版
 

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 兜底：