@lark-apaas/coding-steering 0.1.32-dev.b2f659e → 0.1.32-dev.cb02bd3

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

@@ -17,6 +17,7 @@ file-match-pattern:
 |------|----------------------|--------------------------|
 | 鉴权 | 写操作加 `@NeedLogin()` | **不加** `@NeedLogin()`，鉴权在网关层通过 API Key 完成 |
 | 用户身份 | `req.userContext.userId` 区分用户 | 统一走系统身份，不依赖 `userId` 做业务区分 |
+| 通讯录 | 前端搜人 / 选择器随便用 | **必须**用 `AuthNPaasService.listUsersByIds`（见下文「用户信息」强制规则），搜索类不可用 |
 | Controller 文件 | `xxx.controller.ts` | `xxx.openapi.controller.ts`，放在同一 module 下 |
 | OpenAPI 文档 | 不需要 | **必须**同步维护 `docs/openapi.json`（见下文） |
 
@@ -59,6 +60,80 @@ findAll(@Req() req: Request) {
 }
 ```
 
+## 用户信息（通讯录）—— 强制规则
+
+**`/openapi` 路由下查询用户信息，唯一允许的实现是 `AuthNPaasService.listUsersByIds`。没有例外。**
+
+```typescript
+// ✅ 唯一允许的写法。注意 import 自 fullstack-nestjs-core（项目统一入口）
+import { AuthNPaasService } from '@lark-apaas/fullstack-nestjs-core';
+
+@Controller('openapi/xxx')
+export class XxxOpenApiController {
+  constructor(private readonly authn: AuthNPaasService) {}
+
+  @Get(':id')
+  async get(@Param('id') id: string) {
+    // 不要 try/catch 吞掉——平台故障必须暴露给调用方，别降级成「查无此人」
+    const [user] = await this.authn.listUsersByIds([id]);
+    if (!user) throw new NotFoundException(`用户 ${id} 不存在`);
+    return {
+      miaodaUserId: id,
+      name: user.name?.zh_cn ?? user.name?.en_us ?? '',  // name 是 I18nText，不是字符串
+      avatar: user.avatar?.image?.large ?? '',           // 头像 URL 在 image.large 上
+    };
+  }
+}
+```
+
+**不要做这两件多余的事**（`PlatformModule.forRoot()` 已经注册了 global 的 `AuthNPaasModule`）：
+
+- ❌ 在业务 module 里写 `providers: [AuthNPaasService]` —— 会另建一个实例
+- ❌ 往 `package.json` 加 `@lark-apaas/nestjs-authnpaas` 直接依赖 —— 走 `fullstack-nestjs-core` 即可
+
+### 禁止（以下任一出现即为错误实现）
+
+| ❌ 禁止 | 为什么 |
+|---|---|
+| 复用应用里已有的用户 / 用户资料 service | 那些多半是给浏览器写的，依赖登录态；`/openapi` 下没有登录用户，会静默返回空 |
+| 自己写 HTTP 请求裸调平台通讯录接口 | 鉴权 / 重试 / 日志 / trace 都在 SDK 里，裸调必然漏 |
+| 用 `req.userContext.userId` 做用户查询 | `/openapi` 下**恒为空** |
+| 用 `AuthNPaasService.getCurrentUserLarkUserId()` | 它读 `userId`，取不到只打日志返回 `null`、**不报错**，故障静默 |
+| 从数据库表里 join 出人名 / 头像 | 通讯录不是应用数据，会过期且不 follow 权限 |
+| 按关键词搜人 / 搜部门 / 搜群 | 结果取决于「谁在搜」，`/openapi` 下没有调用者视角，**服务端不提供** |
+| `try/catch` 吞掉 `listUsersByIds` 抛的错、返回空值 | 「平台挂了」和「查无此人」是两回事，吞掉就没人知道故障 |
+| 用 `getBatchLarkUserIds` 判断用户是否存在 | 它是 ID 转换，**外部用户本来就没有 employeeId**，会把外部用户误判成不存在 |
+| 服务端拿不到的字段用 `''` 占位塞进响应 | 调用方会以为字段存在只是没值。拿不到就**从响应类型里删掉**，并告诉用户改走飞书开放平台通讯录 API |
+
+```typescript
+// ❌ 错误：包了一层应用现有的用户服务
+const profile = await this.userProfileService.findById(id);
+
+// ❌ 错误：OpenAPI 态搜不了人
+const users = await someSearchApi({ query: keyword });
+
+// ❌ 错误：读 userId，OpenAPI 态恒为空且失败不报错
+const larkId = await this.authn.getCurrentUserLarkUserId();
+
+// ❌ 错误：吞掉平台故障 + 拿不到的字段用空串占位
+let name = '';
+try {
+  const [u] = await this.authn.listUsersByIds([id]);
+  name = u?.name?.zh_cn ?? '';
+} catch { /* 平台挂了也当查无此人 */ }
+return { userId: id, name, department: '', email: '', jobTitle: '' };
+```
+
+### `AuthNPaasService` import 不到时
+
+说明当前 `@lark-apaas/fullstack-nestjs-core` 版本还没带上这个能力。**报告阻塞、请人升级 core 版本**——不要加 `@lark-apaas/nestjs-authnpaas` 直接依赖绕过去，也不要退回上面任何一种禁止写法或自己实现替代品。
+
+### 服务端拿不到的字段
+
+手机号 / 职位 / 工号 / 直属上级 / 在职状态、以及按 ID 查群 —— 服务端**没有**这些能力。需要就走飞书开放平台通讯录 API，或把该能力放回前端做，**不要**在 `/openapi` 里自己拼一个。
+
+完整能力边界与字段口径见 [`contacts-service` › 第六节](../contacts-service/SKILL.md)。
+
 ## 模块组织
 
 `/openapi` Controller 和 `/api` Controller 放在**同一个 module** 下，共享 Service 层。用文件名 `xxx.openapi.controller.ts` 区分。

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

@@ -20,8 +20,10 @@ 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';` |
+| CapabilityService 注入 | `@Inject(CapabilityService) private readonly capabilityService: CapabilityService`（**禁止空参 `@Inject()`**，会导致启动崩溃 502；业务 Module 无需 imports） |
 
 ## 必读 references
 
@@ -70,6 +72,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 +139,9 @@ const structured = await capabilityClient
         ├── 输出包含多个独立字段（标题+正文+评分等）
         │   → 拆成多个独立插件并行调用（⭐ 优先）或用 ai-text-to-json
         │   → ⛔ 禁止用 ai-text-generate + 正则/split 解析多字段
+        ├── 输出规模大（多份结果、多语言、长正文、多章节或批量对象）
+        │   → 优先拆分为多个独立生成单元；需要汇总持久化时使用任务状态模型承接
+        │   → ⛔ 禁止一个后端 HTTP 请求同步等待所有生成结果后才响应
         └── 输出为单一文本（仅展示，不需解析）→ ai-text-generate
 ```
 
@@ -203,9 +209,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 +246,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 侧创建任务记录，快速返回任务状态；后台调用插件并落库；前端短轮询状态/结果
 ```
 
 | 应避免的做法 | 推荐做法 |
@@ -79,12 +87,18 @@
 #### call / callStream 函数签名
 
 ```typescript
-.call(actionKey: string, input: object)       // 非流式，返回 Promise<output>
-.callStream(actionKey: string, input: object)  // 流式，返回 AsyncIterable<chunk>
+// 前端 capabilityClient（@lark-apaas/client-toolkit，实际类型来自 @lark-apaas/client-capability）
+.call<T = unknown>(actionKey: string, params?: Record<string, unknown>): Promise<T>              // 非流式
+.callStream<T = unknown>(actionKey: string, params?: Record<string, unknown>): AsyncIterable<T>  // 流式
 ```
 
 - **第一个参数 `actionKey`**：必须是字符串，值来自 `get_plugin_ai_json` 返回的 `actions[].key`（如 `'sendFeishuMessage'`、`'textGenerate'`）
-- **第二个参数 `input`**：必须是对象，结构符合 `actions[].inputSchema`
+- **第二个参数 `params`**：类型是 `Record<string, unknown>`，结构符合 `actions[].inputSchema`
+- 上面是**前端**签名，带泛型。**服务端 `CapabilityService` 的 `call` / `callStream` / `callStreamWithEvents` 都没有泛型**，两者不通用，详见「Server 侧调用方式」
+
+> **`Record<string, unknown>` 不接 `interface` 声明的对象**（interface 没有隐式索引签名），直接传会撞
+> `Argument of type 'XxxInput' is not assignable to parameter of type 'Record<string, unknown>'. Index signature for type 'string' is missing in type 'XxxInput'.`
+> 三种正确写法：① 直接传内联对象字面量；② 入参类型用 `type XxxInput = { ... }` 而非 `interface`（type 别名有隐式索引签名）；③ 已有 interface 时在调用点显式 `input as unknown as Record<string, unknown>`。**不要为此改用 `as any`。**
 
 ```typescript
 // ❌ 错误：把参数 JSON.stringify 后当作 actionKey
@@ -271,10 +285,11 @@ function MultiPluginStreamExample({ recordId }: { recordId: string }) {
 2. 一个 `stream` action 的真实调用结果（chunk 按 `outputSchema` 字段读取）
 3. 调用失败时的最小日志字段齐全
 4. 若无法执行真实调用，必须明确写明阻塞原因，禁止直接标记“开发完成”
+5. 若用户触发 AI 生成的请求超时、连接断开或工具返回超时，必须判定为验收失败；只有触发请求快速返回、随后能通过页面或接口读到明确完成或失败终态和结果，才允许标记通过
 
 ### Server 侧调用方式（仅兜底场景）
 
-> 以下场景适合使用 Server 侧调用，特别是涉及数据持久化时不要回避后端。
+> 以下场景适合使用 Server 侧调用；若前端 `callStream` + 既有 CRUD 保存即可满足展示和持久化，不要优先引入后端后台任务。
 
 #### 1. 何时适合用 Server 侧？
 
@@ -285,6 +300,7 @@ function MultiPluginStreamExample({ recordId }: { recordId: string }) {
 | 敏感凭证调用 | 凭证不能暴露给前端 | 调用需要 admin token 的 API |
 | 强事务编排 | 多步骤需要原子性 | 创建记录 → 发通知 → 更新状态必须全成功或全回滚 |
 | 插件结果需持久化 | 调用结果需保存到数据库 | AI 分类/摘要结果需落库、文档解析的结构化数据需入库、图片识别结果需关联业务记录、语音转文字结果需存档等 |
+| 高耗时 AI 生成需后续查看 | 请求不能长期占用用户交互链路 | 批量、多版本、多语言、长文本、多字段结构化生成，或文件/多模态分析后再生成内容 |
 
 #### 2. NestJS 注入方式
 
@@ -296,23 +312,49 @@ import { CapabilityService } from '@lark-apaas/fullstack-nestjs-core';
 export class XxxService {
   private readonly logger = new Logger(XxxService.name);
 
+  // 注入 token 必须显式写成 @Inject(CapabilityService)
   constructor(
-    @Inject() private readonly capabilityService: CapabilityService,
+    @Inject(CapabilityService) private readonly capabilityService: CapabilityService,
   ) {}
 }
 ```
 
+**禁止空参 `@Inject()`**。本 stack 的 `nest-cli.json` 用 `builder: swc`，空参 `@Inject()` 会把注入 token 置为 undefined，Nest 回退读 `design:type` 拿到 `Function`，服务端启动即崩溃、所有 `/api` 请求返回 502：
+
+```
+UnknownDependenciesException: Nest can't resolve dependencies of the XxxService (?).
+Please make sure that the argument Function at index [0] is available in the XxxModule context.
+```
+
+见到这段报错先查构造函数有没有空参 `@Inject()`，不要去改 Module 的 `imports` / `providers`。
+
+**业务 Module 不需要注册 CapabilityModule**。`PlatformModule` 是 `@Global()` 且已把 `CapabilityModule` 放进 `exports`，`CapabilityService` 全局可注入。不要在业务 Module 里写 `imports: [CapabilityModule.forRoot(...)]` 或 `imports: [PlatformModule.forRoot()]`。
+
+同一规则适用于从 `@lark-apaas/fullstack-nestjs-core` 注入的其他平台服务（`AuthNPaasService`、`FileService` 等）。
+
 #### 3. 调用示例
 
+服务端 `CapabilityExecutor` 的**三个方法全都没有泛型参数**（`@lark-apaas/nestjs-capability`）：
+
+```typescript
+call(actionName: string, input: unknown, context?: Partial<PluginActionContext>): Promise<unknown>;
+callStream(actionName: string, input: unknown, context?): AsyncIterable<unknown>;
+callStreamWithEvents(actionName: string, input: unknown, context?): AsyncIterable<StreamEvent<unknown>>;
+```
+
+写 `.call<T>(...)` / `.callStream<T>(...)` / `.callStreamWithEvents<T>(...)` 都会报「应有 0 个类型参数，但获得 1 个」。泛型只存在于前端 `capabilityClient`。注意服务端 `input` 是**必传**（没有 `?`），且类型是 `unknown` 而非前端的 `Record<string, unknown>`。服务端接 `unknown` 后在运行时收窄，禁止 `as any`：
+
 ```typescript
 const inputParams = {
   // 严格按 get_plugin_ai_json.actions[].inputSchema 构造
 };
 
 try {
-  const output = await this.capabilityService
+  const output: unknown = await this.capabilityService
     .load('')
     .call('', inputParams);
+  // 运行时收窄后再取字段，例如：
+  // if (typeof output === 'object' && output !== null && 'content' in output) { ... }
   return output;
 } catch (error) {
   this.logger.error('pluginInstance call failed', {
@@ -328,6 +370,7 @@ try {
 
 - PluginInstance 调用在 Server 侧通常属于 **外部依赖 / side-effect**
 - 除非业务明确要求强一致性，**默认不应阻塞主业务流程**
+- 已选择 Server 侧承接的高耗时 AI capability 必须有可观测状态：创建任务时记录处理进度、完成终态、失败终态、输入摘要、错误信息和结果引用；触发接口只返回任务标识与当前状态，前端通过短轮询读取进度和最终结果
 
 推荐写法：异步触发 + catch 兜底：
 

package/steering/nestjs-react-fullstack/skills/server-builtins-file-storage-service/SKILL.md

@@ -11,7 +11,7 @@ match-template-name: nestjs-react-fullstack
 在 NestJS 服务端代码中使用 `FileService` 进行文件上传、下载、删除和管理。
 
 > **使用注意**: 仅用于服务端文件处理场景，非必要文件上传下载场景请使用前端 `client-builtins-file-storage-service` skill。
-> **入口边界**：本 SDK 是**服务端代码**读写应用存储的入口；Agent 在对话 / 开发中自己上传或调试文件用 `miaoda file` CLI（见 `miaoda-file` skill）。二者与本 SDK 操作同一个应用存储桶，但 **`miaoda file` CLI 禁止写进服务端代码**。
+> **入口边界**：本 SDK 是**服务端代码**读写应用存储的入口；Agent 在对话 / 开发中自己上传或调试文件，先加载应用文件存储操作 skill（按「应用文件存储 / 文件上传 / 文件下载」召回），用其 CLI 命令操作，具体命令一律以该 skill 为准。二者与本 SDK 操作同一个应用存储桶，但**该 CLI 命令只供 Agent 在沙箱终端使用，禁止写进服务端代码**。
 
 ## 使用场景
 

package/steering/nestjs-react-fullstack/skills_common/user-identity/SKILL.md

@@ -93,12 +93,14 @@ match-template-name: nestjs-react-fullstack
 
 > 完整的解析→守卫流程见 `authn-guide` skill 第二节"认证流程"。
 
+类型使用规则：Controller 直接用 `@Req() req: Request` 读取 SDK 增强的 `req.userContext`。测试、mock 或局部业务需要窄类型时，定义独立接口，只声明实际读取字段；不要继承 Express `Request`，也不要重声明平台增强的 `userContext`。未读取的 `tenantId` 省略；必须保留时用 `unknown` 或 SDK 兼容类型。
+
 ### 字段表
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `userId` | `string` | 妙搭用户 ID |
-| `tenantId` | `number` | 租户 ID |
+| `tenantId` | `number \| undefined` | 租户 ID；按 SDK Express `Request.userContext` 增强：可选 number |
 | `appId` | `string` | 应用 ID |
 | `loginUrl` | `string` | 登录跳转 URL |
 | `userType` | `string` | 用户类型（如 `_employee`） |

package/steering/nestjs-react-fullstack/skills_local/client-builtins-user-service/SKILL.md

@@ -14,6 +14,8 @@ match-template-name: nestjs-react-fullstack
 
 > **边界说明**：`authClient.session` 仅用于用户登录/登出/获取用户信息等鉴权操作。**插件调用（capability）不属于账户 SDK**，须使用独立的 `capabilityClient`（参见 plugin-guide）。
 >
+> **本地 dev 限制**：本 skill 的能力底层打 `/app/<appId>/__runtime__/api/v1/account/*`。这类端点只有在 `npm run dev:local` 成功 `env pull` 到 `MIAODA_DEV_PLATFORM_BASE`（或 `SANDBOX_PUBLIC_URL`）时才由 dev-proxy 反代到远端沙箱；**env pull 失败或未装 lark-cli 时该反代不挂**（启动脚本只 warn 不中断），表现为 POST 404 / GET 返回 200 + index.html。`useCurrentUserProfile()` 打的是 `account/login/user`；UserSelect / DepartmentSelect / UserDisplay 打 `search_user` / `list_users` / `user_profile` / `search_department`。先确认 `.env.local` 里有 `MIAODA_DEV_PLATFORM_BASE`；确实缺失时禁止改 `business-ui` 组件或换自研控件绕过，改由服务端出数据（`req.userContext` / `AuthNPaasService`）。
+>
 > **运行时边界**：本 skill 所有能力（`authClient`、`useCurrentUserProfile`、UserSelect/UserDisplay 等）仅限前端代码使用，**严禁在 `server/**` 中 import**。服务端获取用户身份用 `req.userContext` / `AuthNPaasService`（见 `user-identity` skill），完整边界规则见 coding-guide。
 
 ## 怎么选（决策指引）

package/steering/nestjs-react-fullstack/skills_local/code-fix/SKILL.md

@@ -116,6 +116,12 @@ Module '"@client/src/api/gen"' has no exported member named 'DiscrepancyResponse
 - [ ] 已根据实际定义修正代码
 - [ ] 已验证修改后类型使用正确
 
+## 业务日期错位
+
+**问题描述**：本地凌晨、周一或月初附近，日期落到前一天、上周或上月。
+
+**解决步骤**：按 `coding-guide` 的「业务日期」一节改——自然日统一走业务时区 helper；精确时刻不动。
+
 ## JSX 和语法错误
 
 ### 特殊字符转义处理

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，可进一步搜索或网页访问获取信息
 
 ## 文件命名约定
@@ -147,6 +147,39 @@ shared/ # 前后端共享的目录
 - `/api` 和 `/openapi` 代理已配置，前端 TS 严格模式已禁用，后端已启用
 - Rspack 用于构建，已配置好，**禁止修改**
 
+### 平台 runtime 接口（`__runtime__`）在本地要靠 env pull 才通
+
+dev server 自己只代理 `/api`、`/openapi`、`/__innerapi__`。`/app/<appId>/__runtime__/*` 这一整类平台 runtime 接口走的是另一条路：`npm run dev:local` 会先跑 `lark-cli apps +env-pull` 把沙箱身份/凭证拉进 `.env.local`，其中的 `MIAODA_DEV_PLATFORM_BASE`（或 legacy `SANDBOX_PUBLIC_URL`）才让 dev-proxy 把 `__runtime__` 反代到远端沙箱。
+
+**env pull 失败、未装 lark-cli、或 `.spark/meta.json` 缺 app_id 时，启动脚本只 warn 不中断**，反代就不会挂上。此时这些端点的症状是：**POST 返回 404；GET 落到 Vite 的 SPA fallback，返回 200 + `index.html`**（业务侧表现为「返回一坨 HTML，JSON 解析失败」）。
+
+常踩到的端点：
+
+| 端点 | 方法 | 谁会打到它 |
+|------|------|-----------|
+| `api/v1/permissions/roles` | GET | `AppContainer` 每次加载应用自动打 |
+| `api/v1/observability/{logs,traces,metrics}/collect`、`current_server_timestamp` | POST/GET | 平台埋点上报，自动打 |
+| `api/v1/account/login/user` | POST | `useCurrentUserProfile()` → `authClient.session.getUserInfo()` |
+| `api/v1/account/search_user`、`list_users`、`user_profile`、`search_department`、`convert_lark_user` | POST / `user_profile` 是 GET | `business-ui` 的 UserSelect / DepartmentSelect / UserDisplay |
+| `api/v1/account/search`、`api/v1/account/chat/list_chats` | POST | ChatSelect 选群组件 |
+| `api/v1/studio/user/profile` | GET | `getUserProfile()` |
+| `api/v1/storage/object/<bucket>/pre_upload` | POST | `dataloom.storage.uploadFile()` 前端上传 |
+| `api/v1/studio/plugins/tmp_files/acquire_upload_url`、`acquire_download_url` | POST | `capabilityClient` 的文件类入参 |
+
+> `useCurrentUserProfile()` 打的是 `account/login/user`，**不是** `user_profile`/`search_user` 那一排；它另外还打一个 `GET /api/authnpaas/lark-user-id`，那条走 `/api`、被代理、正常。
+
+排查顺序：先看 `.env.local` 里有没有 `MIAODA_DEV_PLATFORM_BASE`，没有就重跑 `env pull`。确认拉不到时：
+
+- **禁止**改 `client/src/components/business-ui/**`（平台保护文件）、**禁止**给组件加兜底请求或改用自研选人控件绕过——发布后这些端点是正常的，绕过写法反而是错的
+- 需要验证「按当前用户过滤」「展示用户姓名」这类逻辑：改由服务端出数据。服务端的 `req.userContext` 和 `AuthNPaasService` 由网关注入，不受此限制（见 `user-identity` / `contacts-service` skill）。`useCurrentUserProfile()` 长期停在加载态就是这个原因
+- 需要验证上传链路：改用接口测试直接打后端接口，或复用库里已有的文件 URL
+
+另外，`UserSelect` 弹层是**搜索驱动**的：不输关键词时列表为空属预期行为，不是接口挂了。
+
+### 服务端启动即崩、`/api` 全部 502
+
+报错形如 `UnknownDependenciesException: Nest can't resolve dependencies of the XxxService (?)... argument Function at index [0]` 时，先查构造函数有没有空参 `@Inject()`（见 plugin-guide），不要先去改 Module 的 `imports` / `providers`。
+
 ## 质量保障流程
 
 修改代码后：
@@ -286,6 +319,12 @@ await db.select().from(users).where(eq(users.adminUser, userId));
 
 - **`customTimestamptz` 跨网络后是 string**：service 内查询返回 `Date`，但 API 响应经 JSON 序列化后前端拿到 ISO string。`shared/api.interface.ts` 中 timestamptz 字段声明为 `string`，前端需要 Date 时手动 `new Date(value)`。
 
+### 业务日期
+
+需求里的日期是**自然日**（哪一天 / 哪一周 / 哪一月）而不是精确时刻时，按业务时区计算，未指定时默认 `Asia/Shanghai`。
+
+项目里放一个 helper 统一产出 `day` / `month` / `weekStart` / `shiftDay`；服务端写入、统计聚合、前端展示都比较它的返回值。
+
 ### 数据库使用强约束
 
 - 仅通过 schema.ts 暴露的客户端和类型读写，禁止手写 SQL/临时类型
@@ -329,10 +368,13 @@ await db.select().from(users).where(eq(users.adminUser, userId));
 
 - **必须从 `req.userContext` 获取**，禁止从前端传递，禁止硬编码
 - 依赖用户信息的接口不要用 API 测试工具测试，用 `think` 工具思考
+- 后端按 `user-identity` 和 `@lark-apaas/fullstack-nestjs-core` 的 Express `Request` 增强读取 `req.userContext`；`tenantId` 为可选 number，不能套用前端 `window.tenantId` / `viewContext` 字符串语义。
+- Controller 直接用 `@Req() req: Request`；测试、mock 或业务窄类型用独立接口，只声明实际读取字段。不要继承 Express `Request` 或重声明 `userContext`；未读 `tenantId` 就省略，必须保留时用 `unknown` 或 SDK 兼容类型。
 
 ```typescript
-// req.userContext 字段（由身份认证中间件挂载）：
-// - userId/tenantId/appId: string
+// req.userContext 字段（由身份认证中间件挂载，完整合同见 user-identity）：
+// - userId/appId: string
+// - tenantId: SDK Request.userContext 的可选 number
 // - env: 'preview' | 'runtime'  (preview=预览态, runtime=发布运行态)
 // - userName/userNameEn: string
 // - userNameI18n: string  (多语名字, 如 {zh_cn: '用户', en_us: 'user'})
@@ -443,14 +485,13 @@ NestJS 自己不读 env。直连 NestJS 端口 → header 缺失 → `req.userCo
 
 - **框架**: React 19 + TypeScript
 - **路由**: React Router DOM v6
-- **样式**: styled-jsx + tailwindcss（语义化 token）。styled-jsx 使用前提见下方"样式开发"
+- **样式**: tailwindcss（语义化 token）
 - **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 +524,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 +575,6 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 ```
 需要写样式？
 ├─ 基础布局/间距/颜色 → Tailwind ✅
-├─ 复杂动画/伪元素/高级CSS → styled-jsx ✅
 └─ JS动态计算值 → 行内 style ✅
 ```
 
@@ -548,11 +587,6 @@ 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 规范
-
-- **技术栈一致性**：仅在已配置 styled-jsx 插件的项目中使用。`package.json` 无 `styled-jsx` 依赖则**禁用**，否则运行时 SyntaxError
-- **禁止动态插值**：`<style jsx>` 内禁止 `${...}` 等表达式（会卡死）。动态值放 CSS 变量，用 `var(--xxx)` 引用
-
 ### 布局/排版
 
 - Spacing 保持一致（small/medium/large 三级），Panel 风格统一
@@ -635,15 +669,8 @@ return <h1>{data?.title || '未知标题'}</h1>;
 | 验证       | zod                                                                      |
 | 工具函数   | lodash                                                                   |
 | 样式       | clsx                                                                     |
-| Excel      | xlsx（**仅前端实现，禁止服务端实现**。解析后将结构化数据传到服务端保存） |
-| PDF 导出   | jspdf + html2canvas（**仅前端实现，禁止服务端实现**）                    |
-| 文件上传   | react-dropzone                                                           |
-| 二维码     | qrcode.react                                                             |
 | 用户反馈   | sonner                                                                   |
-| 拖拽       | @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,9 +35,10 @@ 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` |
+| CapabilityService 注入 | `@Inject(CapabilityService) private readonly capabilityService: CapabilityService`（**禁止空参 `@Inject()`**，会导致启动崩溃 502；业务 Module 无需 imports） |
 | 插件实例配置位置 | `server/capabilities/<instance_id>.json`（默认全栈应用）。见「配置目录」段 |
 
 > **capabilityClient 导入警告**：`capabilityClient` 是从 `@lark-apaas/client-toolkit` 直接导入的独立对象，**不是**从 `getDataloom()` 上获取的。正确且唯一的方式：`import { capabilityClient } from '@lark-apaas/client-toolkit'`。
@@ -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. **插件失败必须有补偿**：至少记录到待处理列表或提示用户重试
 
 ## 缓存与幂等性