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

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.42",
+  "version": "0.1.43-alpha.20260831015213",
   "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"
   },
@@ -17,8 +20,5 @@
     "miaoda",
     "coding-steering"
   ],
-  "license": "MIT",
-  "scripts": {
-    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
-  }
-}
+  "license": "MIT"
+}

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

@@ -155,7 +155,7 @@ shared/ # 前后端共享的目录
 
 ## 依赖使用规范
 
-1. **子包完整性检查**：部分库有多个子包（如 `@dnd-kit/core` + `@dnd-kit/sortable` + `@dnd-kit/utilities`），添加 import 后必须确认 package.json 中包含所有需要的子包
+1. **子包完整性检查**：部分库有多个子包（如 `@radix-ui/react-*` 系列每个组件都是独立子包），添加 import 后必须确认 package.json 中包含所有需要的子包
 2. 用法不清时查看 readme，可进一步搜索或网页访问获取信息
 
 ## 文件命名约定
@@ -569,6 +569,8 @@ 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 请求
@@ -606,6 +608,8 @@ 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 召回规则（强制执行）
@@ -769,15 +773,12 @@ return <h1>{data?.title || '未知标题'}</h1>;
 | 验证 | zod |
 | 工具函数 | lodash |
 | 样式 | clsx |
-| Excel | xlsx（**仅前端实现，禁止服务端实现**。解析后将结构化数据传到服务端保存） |
-| PDF 导出 | jspdf + html2canvas（**仅前端实现，禁止服务端实现**） |
-| 文件上传 | react-dropzone |
-| 二维码 | qrcode.react |
+| 文件上传 | 原生 `<input type="file">`，用 shadcn 组件封装样式 |
 | 用户反馈 | sonner |
-| 拖拽 | @dnd-kit/core |
-| 数字动画 | react-countup |
-| Base64 | js-base64 — `import { encode, decode } from 'js-base64'` |
-| 3D 场景 | cobe |
+| 数字动画 | `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 显式添加所需依赖并安装，再编写代码。
 
 ## 滚动分页最佳实践
 

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

@@ -20,7 +20,6 @@ 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';` |
 
@@ -71,7 +70,6 @@ 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`）。无冒烟结果不得宣告完成。
 
@@ -138,9 +136,6 @@ const structured = await capabilityClient
         ├── 输出包含多个独立字段（标题+正文+评分等）
         │   → 拆成多个独立插件并行调用（⭐ 优先）或用 ai-text-to-json
         │   → ⛔ 禁止用 ai-text-generate + 正则/split 解析多字段
-        ├── 输出规模大（多份结果、多语言、长正文、多章节或批量对象）
-        │   → 优先拆分为多个独立生成单元；需要汇总持久化时使用任务状态模型承接
-        │   → ⛔ 禁止一个后端 HTTP 请求同步等待所有生成结果后才响应
         └── 输出为单一文本（仅展示，不需解析）→ ai-text-generate
 ```
 
@@ -208,9 +203,9 @@ const structured = await capabilityClient
 
 1. **禁止静默吞异常**：每个 `catch` 至少满足其一——向用户展示错误（toast/页面状态），或触发补偿机制（重试/降级/记录待处理列表）
 2. **异步操作必须有终态**：不阻塞主流程的插件调用须在 DB 维护状态（pending → success/failed），前端必须展示 failed，不能永远 loading
-3. **长耗时 AI 生成不得同步等完**：大体量、多字段、多份、多语言、文件/多模态串联或需要持久化的 AI capability 调用，触发接口必须快速返回任务状态或采用前端流式展示；若 `api_request`、浏览器操作或页面请求出现超时/连接断开，不能只凭服务端最终日志或数据库最终写入宣告成功，必须证明用户侧存在可读取的终态结果
-4. **通知类插件失败必须有补偿**：如 `send-feishu-message` 失败，至少记录"待发送"列表或 UI 提示"通知发送失败，请手动联系"
-5. **配置完整性（load 前必查）**：`load(id)` 前确认实例已创建且 id 与代码完全匹配，否则抛 `CapabilityNotFoundError`（开发态 Top 错误）；load/call 失败时停止后续请求避免放大错误；**缓存 load 结果**，同一 id 不重复 load
+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`
 
 ## 缓存与幂等性
 
@@ -245,7 +240,7 @@ const structured = await capabilityClient
 
 ### 通知接收人动态解析
 
-接收人（`receiverUserList`/`receiverGroupList` 等）按角色/条件变化时，必须实时查询角色成员经 `input` 传入（角色/成员的运行时查询写法见 `authz-guide` 技能），禁止硬编码或凭经验拼装 ID。如引入缓存，必须提供显式失效手段（如角色变更时清缓存）并明示 TTL，禁止无失效手段的常驻缓存导致接收人信息过期。通知发送失败的补偿要求见上文「插件调用错误处理」第 4 条铁律，不重复展开。
+接收人（`receiverUserList`/`receiverGroupList` 等）按角色/条件变化时，必须实时查询角色成员经 `input` 传入（角色/成员的运行时查询写法见 `authz-guide` 技能），禁止硬编码或凭经验拼装 ID。如引入缓存，必须提供显式失效手段（如角色变更时清缓存）并明示 TTL，禁止无失效手段的常驻缓存导致接收人信息过期。通知发送失败的补偿要求见上文「插件调用错误处理」第 3 条铁律，不重复展开。
 
 ## 飞书深链 URL 规范
 

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

@@ -2,19 +2,15 @@
 
 ### 核心原则：根据场景选择调用侧
 
-**默认优先在 Client 侧调用 capabilityClient；流式或高耗时 AI 生成优先 `callStream` 渐进展示。结果需要持久化时，优先在流式结束后通过已有后端接口保存；只有 Client 侧无法满足时才切到 Server 侧。**
-
-**高耗时 AI capability 先判调用形态**：只要输出规模大、输出字段多、需要多份结果、多语言/长文本、文件或多模态输入后继续生成、多个 capability 串联、或结果需后续查看/落库，就不得把完整 AI 结果塞进一个同步 HTTP 请求等待。能由前端承接时，优先用前端 `callStream` 渐进展示，并在流式结束后按需复用已有 CRUD 接口保存结果；只有 Client 侧无法满足（触发器/敏感凭证/强事务/必须由后端保证落库一致性等）时，才采用后端任务记录 + 状态/结果查询，避免把后台任务作为默认方案。
-
+**默认优先在 Client 侧调用 capabilityClient；但当插件结果需要持久化到数据库时，应考虑在 Server 侧调用或确保前端调用后及时通过后端接口保存。**
 **严禁** import ｛ capabilityClient ｝ from '@lark-apaas/client-capability'。
 **唯一指定**的导入方式是 import { capabilityClient } from '@lark-apaas/client-toolkit';
 
 | 优先级 | 场景 | 调用方式 |
 |-------|------|---------|
-| **首选** | 绝大多数即时展示场景 | `capabilityClient.load(id).call()` |
-| **首选** | 流式输出，或高耗时但可由前端承接的 AI 生成 | `capabilityClient.load(id).callStream()`（流式结束后按需持久化） |
-| **必要时** | 高耗时且 Client 侧无法满足：触发器、敏感凭证、强事务、必须由后端保证落库一致性 | 后端任务记录 + 后台调用 `CapabilityService.load(id).call()` + 前端短轮询状态/结果 |
-| **兜底** | Client 侧无法满足且单次调用可在交互边界内完成 | `CapabilityService.load(id).call()` |
+| **首选** | 绝大多数场景 | `capabilityClient.load(id).call()` |
+| **首选** | 流式输出场景 | `capabilityClient.load(id).callStream()` |
+| **兜底** | Client 侧无法满足时 | `CapabilityService.load(id).call()` |
 
 #### 什么情况下应使用 Server 侧？
 
@@ -23,7 +19,7 @@
 1. **涉及敏感凭证**：调用需要服务端私密 token/secret，不适合暴露给前端
 2. **必须后端编排**：多个插件调用之间有强事务依赖，需要后端统一编排
 3. **触发器/定时任务场景**：没有前端上下文，只能由后端发起
-4. **插件结果需要持久化**：调用结果需要保存到数据库；能由前端承接时，优先前端 `callStream` 渐进展示并在结束后复用已有 CRUD 接口保存；只有 Client 侧无法满足或必须由后端保证落库一致性时，才在 Server 侧调用并落库。若此时输出规模大、字段多、结果多份或需多步能力串联，必须改为任务记录 + 后台执行 + 状态/结果查询，避免一个 HTTP 请求等待完整生成
+4. **插件结果需要持久化**：调用结果需要保存到数据库，在 Server 侧可以在同一方法中完成调用+落库，保证数据一致性
 
 > **提示**：如果插件结果不需要存储、仅用于即时展示（如流式生成文本、发送消息），优先在前端调用。但当结果需要保存到数据库时，不要回避使用 Server 侧。
 
@@ -46,13 +42,9 @@
 
 ```
 插件结果是否需要持久化到数据库？
-├── 否（一次性即时展示）
-│   ├── `outputMode=stream` 或内容生成较慢 → Client 侧 `callStream()` 渐进展示
-│   └── 单次短输出 → Client 侧 `call()`（默认）
-└── 是
-    ├── `outputMode=stream` 且前端可承接 → 推荐方案 A：Client 侧 `callStream()` 渐进展示，成功后通过已有 CRUD 接口保存结果
-    ├── 输出较小且可在交互边界内完成、且必须由后端保证一致性 → Server 侧调用并在同一方法中落库
-    └── Client 侧无法满足且输出规模大/多字段/多份/多语言/多步骤 → 方案 B：Server 侧创建任务记录，快速返回任务状态；后台调用插件并落库；前端短轮询状态/结果
+├── 否（一次性即时展示）→ Client 侧调用（默认）
+└── 是 → 推荐方案 A：Server 侧调用，在 Service 中调用插件并在同一方法中落库
+         备选方案 B：Client 侧调用插件 → 成功后通过已有 CRUD 接口保存结果
 ```
 
 | 应避免的做法 | 推荐做法 |
@@ -279,11 +271,10 @@ function MultiPluginStreamExample({ recordId }: { recordId: string }) {
 2. 一个 `stream` action 的真实调用结果（chunk 按 `outputSchema` 字段读取）
 3. 调用失败时的最小日志字段齐全
 4. 若无法执行真实调用，必须明确写明阻塞原因，禁止直接标记“开发完成”
-5. 若用户触发 AI 生成的请求超时、连接断开或工具返回超时，必须判定为验收失败；只有触发请求快速返回、随后能通过页面或接口读到明确完成或失败终态和结果，才允许标记通过
 
 ### Server 侧调用方式（仅兜底场景）
 
-> 以下场景适合使用 Server 侧调用；若前端 `callStream` + 既有 CRUD 保存即可满足展示和持久化，不要优先引入后端后台任务。
+> 以下场景适合使用 Server 侧调用，特别是涉及数据持久化时不要回避后端。
 
 #### 1. 何时适合用 Server 侧？
 
@@ -294,7 +285,6 @@ function MultiPluginStreamExample({ recordId }: { recordId: string }) {
 | 敏感凭证调用 | 凭证不能暴露给前端 | 调用需要 admin token 的 API |
 | 强事务编排 | 多步骤需要原子性 | 创建记录 → 发通知 → 更新状态必须全成功或全回滚 |
 | 插件结果需持久化 | 调用结果需保存到数据库 | AI 分类/摘要结果需落库、文档解析的结构化数据需入库、图片识别结果需关联业务记录、语音转文字结果需存档等 |
-| 高耗时 AI 生成需后续查看 | 请求不能长期占用用户交互链路 | 批量、多版本、多语言、长文本、多字段结构化生成，或文件/多模态分析后再生成内容 |
 
 #### 2. NestJS 注入方式
 
@@ -338,7 +328,6 @@ 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. **子包完整性检查**：部分库有多个子包（如 `@dnd-kit/core` + `@dnd-kit/sortable` + `@dnd-kit/utilities`），添加 import 后必须确认 package.json 中包含所有需要的子包
+3. **子包完整性检查**：部分库有多个子包（如 `@radix-ui/react-*` 系列每个组件都是独立子包），添加 import 后必须确认 package.json 中包含所有需要的子包
 4. 用法不清时查看 readme，可进一步搜索或网页访问获取信息
 
 ## 文件命名约定
@@ -443,14 +443,13 @@ NestJS 自己不读 env。直连 NestJS 端口 → header 缺失 → `req.userCo
 
 - **框架**: React 19 + TypeScript
 - **路由**: React Router DOM v6
-- **样式**: styled-jsx + tailwindcss（语义化 token）。styled-jsx 使用前提见下方"样式开发"
+- **样式**: tailwindcss（语义化 token）为主，复杂 CSS 用 CSS Modules（`*.module.css`），动态计算值用行内 `style`
 - **UI 组件库**: shadcn/ui — Use components for functionality, heavily style them
 - **图表**: ReactECharts，**开发前必须调用 `/charts-skill`**
 - **图标**: Lucide React（唯一图标库，禁止 Emoji 和其他图标库）
 - **表格/表单/图表**: 见下方"组件 Skill 召回规则"，开发前必须先调用对应 Skill
 - **用户**: 用户信息展示/选择必须用 `business-ui` 组件（阅读 README.md），禁止直接展示 userId
-- **富文本**: `business-ui/tiptap-editor`（阅读 README.md）
-- **Markdown 渲染**: `components/ui/streamdown`（内置 prose 排版）
+- **Markdown 渲染**: `components/ui/markdown`（react-markdown + remark-gfm，内置 prose 排版）
 
 ## API 请求
 
@@ -483,8 +482,7 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 | --------------------------------------------------- | --------------------------------------- | --------------------------------- |
 | Table                                               | `@lark-apaas/client-toolkit/antd-table` | 数据表格，**先调 `/table-skill`** |
 | UserSelect/UserDisplay/UserProfile/DepartmentSelect | `business-ui/*`                         | 用户/部门选择展示                 |
-| TiptapEditorComplete                                | `business-ui/tiptap-editor`             | 富文本编辑器                      |
-| Streamdown                                          | `components/ui/streamdown`              | Markdown/流式渲染                 |
+| Markdown                                            | `components/ui/markdown`                | Markdown 渲染（react-markdown + remark-gfm） |
 
 ### 组件 Skill 召回规则（强制执行）
 
@@ -535,7 +533,7 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 ```
 需要写样式？
 ├─ 基础布局/间距/颜色 → Tailwind ✅
-├─ 复杂动画/伪元素/高级CSS → styled-jsx ✅
+├─ 复杂动画/伪元素/高级CSS → CSS Modules（`*.module.css`）✅
 └─ JS动态计算值 → 行内 style ✅
 ```
 
@@ -548,10 +546,12 @@ 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%`）
 
-### styled-jsx 规范
+### CSS Modules 规范
 
-- **技术栈一致性**：仅在已配置 styled-jsx 插件的项目中使用。`package.json` 无 `styled-jsx` 依赖则**禁用**，否则运行时 SyntaxError
-- **禁止动态插值**：`<style jsx>` 内禁止 `${...}` 等表达式（会卡死）。动态值放 CSS 变量，用 `var(--xxx)` 引用
+- 文件名：`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`
 
 ### 布局/排版
 
@@ -635,15 +635,12 @@ return <h1>{data?.title || '未知标题'}</h1>;
 | 验证       | zod                                                                      |
 | 工具函数   | lodash                                                                   |
 | 样式       | clsx                                                                     |
-| Excel      | xlsx（**仅前端实现，禁止服务端实现**。解析后将结构化数据传到服务端保存） |
-| PDF 导出   | jspdf + html2canvas（**仅前端实现，禁止服务端实现**）                    |
-| 文件上传   | react-dropzone                                                           |
-| 二维码     | qrcode.react                                                             |
+| 文件上传   | 原生 `<input type="file">`，用 shadcn 组件封装样式                       |
 | 用户反馈   | sonner                                                                   |
-| 拖拽       | @dnd-kit/core                                                            |
-| 数字动画   | react-countup                                                            |
-| Base64     | js-base64 — `import { encode, decode } from 'js-base64'`                 |
-| 3D 场景    | cobe                                                                     |
+| 数字动画   | `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 显式添加所需依赖并安装，再编写代码。
 
 ## 滚动分页最佳实践
 

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

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

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

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