@lark-apaas/coding-steering 0.1.6-alpha.0 → 0.1.6-alpha.10

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

@@ -0,0 +1,177 @@
+---
+name: server-builtins-file-storage-service
+description: "Use when server-side code needs to upload or download files programmatically, such as file format conversion, automated report generation, or background tasks that produce files. NOT for frontend file operations. 触发词：服务端文件上传, 服务端文件下载, FileService, nestjs file, 后端文件处理, 文件格式转换, 生成文件上传"
+steering: true
+steering-topic: server_builtins_file_storage_service
+match-template-name: nestjs-react-fullstack
+---
+
+# NestJS File Service SDK
+
+在 NestJS 服务端代码中使用 `FileService` 进行文件上传、下载、删除和管理。
+
+> **使用注意**: 仅用于服务端文件处理场景，非必要文件上传下载场景请使用前端 `client-builtins-file-storage-service` skill。
+> CLI 调试场景请参考 `file-storage` skill。
+
+## 使用场景
+
+| 场景 | 说明 |
+|------|------|
+| 服务端文件处理 | 下载文件到本地处理后重新上传，如图片格式转换、docx 格式转换等 |
+| 自动化任务生成文件 | 定时任务或事件触发后，根据数据库/插件内容生成文件并上传，如定时生成 PDF 报告、图片海报等 |
+
+## Quick Reference
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
+| `upload(file, options?)` | 上传文件 | `FileMeta` |
+| `download(path)` | 下载文件（≤50MB） | `FileDownloadBuilder` |
+| `remove(filePaths)` | 删除文件 | `RemoveResponse` |
+| `getFileMetadata(filePath)` | 获取文件元信息 | `FileMeta` |
+
+## 注入 FileService
+
+```typescript
+import { FileService } from '@lark-apaas/fullstack-nestjs-core';
+
+@Injectable()
+export class MyService {
+  constructor(private readonly fileService: FileService) {}
+}
+```
+
+## 公共类型
+
+```typescript
+interface FileMeta {
+  id: string;
+  name: string;
+  filePath: string;
+  metadata: { contentLength: string; mimeType: string };
+  downloadURL: string;
+  createdAt: string;
+  updatedAt: string;
+  bucketID: string;
+}
+```
+
+## 核心操作
+
+### 1. 上传文件
+
+**入参：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `file` | `FileBody` | 是 | 文件内容（支持 `Buffer`、`ReadableStream`、`ArrayBuffer`、`Blob`、`string` 等） |
+| `options` | `UploadOptions` | 否 | 上传选项 |
+
+**UploadOptions：**
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `fileName` | `string` | 否 | 文件名称 |
+| `contentType` | `string` | 否 | MIME 类型 |
+| `cacheControl` | `string \| number` | 否 | 缓存控制 |
+| `upsert` | `boolean` | 否 | 是否覆盖已有文件 |
+
+**返回值：** `FileMeta`
+
+**示例：**
+
+```typescript
+// 基本上传
+const result = await this.fileService.upload(buffer);
+
+// 带选项上传
+const result = await this.fileService.upload(fileBody, {
+  fileName: 'report.pdf',
+  contentType: 'application/pdf',
+  upsert: false,
+});
+```
+
+### 2. 下载文件
+
+**入参：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `path` | `string` | 是 | downloadURL 或文件存储路径 |
+
+**返回值 `DownloadResult`：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `content` | `Blob`（默认）/ `ReadableStream`（流式） | 文件内容 |
+| `metadata` | `FileMeta` | 文件元信息 |
+
+> **推荐始终使用 `.asStream()`**，避免大文件导致内存溢出。直接 `await download()` 有 50MB 限制。
+
+**示例：**
+
+```typescript
+// 推荐：使用 downloadURL + 流式下载
+const downloadURL = fileMeta.downloadURL; // 从上传返回值或数据库获取
+const { content, metadata } = await this.fileService
+  .download(downloadURL)
+  .asStream();
+
+// 也可以使用文件存储路径
+const { content, metadata } = await this.fileService
+  .download('file.pdf')
+  .asStream();
+
+// 不推荐：Blob 下载（限制 50MB，会将整个文件加载到内存）
+const { content, metadata } = await this.fileService.download(downloadURL);
+```
+
+### 3. 删除文件
+
+**入参：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `filePaths` | `string[]` | 是 | downloadURL 或文件存储路径数组 |
+
+**返回值：** `FileMeta[]` - 删除成功的文件元信息数组
+
+**示例：**
+
+```typescript
+// 推荐：使用 downloadURL
+const result = await this.fileService.remove([fileMeta.downloadURL]);
+
+// 也可以使用文件存储路径
+const result = await this.fileService.remove(['file1.pdf', 'file2.png']);
+```
+
+### 4. 获取文件元信息
+
+**入参：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `filePath` | `string` | 是 | downloadURL 或文件存储路径 |
+
+**返回值：** `FileMeta | null` - 文件元信息或 `null` 表示文件不存在或删除失败
+
+**示例：**
+
+```typescript
+// 推荐：使用 downloadURL
+const meta = await this.fileService.getFileMetadata(fileMeta.downloadURL);
+
+// 也可以使用文件存储路径
+const meta = await this.fileService.getFileMetadata('file.pdf');
+```
+
+## Common Mistakes
+
+| 错误 | 正确做法 |
+|------|----------|
+| 直接 `await download()` 导致内存溢出 | 始终使用 `.asStream()` 流式下载 |
+| 忘记设置 `contentType` 导致浏览器无法预览 | 上传时明确指定 `contentType` |
+| 直接 `new FileService()` 手动实例化 | 通过 NestJS DI 注入 `FileService` |
+| 在异步回调中调用 `download()` 导致上下文丢失 | 在请求处理函数中立即调用，SDK 内部已处理上下文捕获 |
+| 删除时传单个字符串 | `remove()` 参数为 `string[]` 数组 |

package/steering/nestjs-react-fullstack/skills/user-management-best-practices/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: user-management-best-practices
+description: "Use when 决定是否创建用户表、选择用户唯一标识（user_id vs email/手机号）、设计 user_profile 字段与 UNIQUE 约束、处理防重复提交/upsert 去重，或涉及问卷、抽奖、报名、投票等用户提交场景的表结构设计。触发词：用户管理, 用户表设计, user_id, email, user_profile, 去重, 防重复提交, 批量导入用户, upsert, UNIQUE约束, UserSelect, UserDisplay, user management, deduplication"
+steering: true
+steering-topic: user_management_best_practices
+match-template-name: nestjs-react-fullstack
+---
+
+# 用户管理最佳实践指南
+
+## 概述
+
+本指南适用于生成涉及用户管理、问卷、抽奖、报名、投票等用户提交场景的代码。
+
+**核心问题：**
+
+- 妙搭 Agent 无法获取企业的所有用户数据，需要构建应用维度的用户表
+- 企业无法显式感知飞书的 user_id（不透明的数字字符串，如 "1847292357012580"），无法批量导入飞书用户到应用的用户表
+- 推荐使用邮箱或者手机号作为业务层唯一标识（不是 user_id）
+- UserSelect 返回的 IUserProfile 对象已包含 email 和 phone_number 字段，可直接使用
+
+**本指南解决：**
+
+- 何时使用 UserSelect 组件 vs 何时创建用户表
+- 如何设计用户业务表（正确的唯一约束）
+- 防止重复提交的正确实现方式
+
+---
+
+## 核心原则：禁止事项
+
+| 禁止操作                              | 说明                                                   | 正确做法                                                                                     |
+| ------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| 不推荐实现批量导入用户的功能          | Agent 无法获取企业全量用户，批量 INSERT users 表行不通 | 推荐使用 UserSelect 组件动态选择用户                                                         |
+| 不推荐用 user_id 作为去重逻辑         | 企业不感知飞书用户 id，无法感知是谁                    | 使用 email 或者手机号做唯一约束（UNIQUE(email)），不要使用姓名，可能会重复                   |
+| 禁止编造 user_id                      | Mock 数据中不能随意编造 user_id 值                     | 必须使用 SQL skill 规定的测试用户列表                                                        |
+| 禁止全量查询用户列表                  | 全量拉取数据会导致接口超时或 OOM                       | 使用后端分页查询（skip/take）                                                                |
+| 禁止前端分页用户列表                  | 前端分页需要全量拉取数据，导致性能问题                 | 使用后端分页，前端仅控制页码                                                                 |
+| 禁止只存 user_id 不存 email or 手机号 | 业务层无法用 user_id 做防重和查询                      | 存储 user_profile 字段（已包含 email/phone），并在表中单独添加 email 或 phone 列用于唯一约束 |
+
+---
+
+## 决策树示例：何时创建用户表 vs 何时使用 user_profile
+
+```text
+需要记录用户相关业务数据？
+    │
+    ├─ 仅需要识别"谁"执行操作（发帖人、评论者）
+    │   └─ ✅ 直接使用 user_profile 类型字段
+    │       示例：posts.author（user_profile）
+    │
+    └─ 需要存储业务特定的用户数据
+        │
+        ├─ 数据与具体业务资源强绑定（问卷提交、抽奖记录）
+        │   └─ ✅ 创建业务表 + user_profile 字段 + email 唯一约束
+        │       示例：questionnaire_responses (id, respondent, email, UNIQUE(questionnaire_id, email))
+        │
+        └─ 数据代表"用户在系统中的身份"（员工、学生、会员）
+            └─ ✅ 创建人员实体表，user_profile 作为主键
+                示例：employees (employee_profile PRIMARY KEY, department, position)
+```
+
+---
+
+## 用户列表查询与性能注意事项
+
+### UserSelect vs 分页列表的选择
+
+根据场景选择正确的用户选择方式：
+
+| 场景               | 使用组件         | 数据加载方式 | 典型数量 |
+| ------------------ | ---------------- | ------------ | -------- |
+| 表单选择用户       | UserSelect       | 搜索驱动     | 1-10     |
+| 用户管理后台       | Table + 后端分页 | 分页加载     | 100+     |
+| 问卷提交记录列表   | Table + 后端分页 | 分页加载     | 100+     |
+| 抽奖参与者名单展示 | Table + 后端分页 | 分页加载     | 100+     |
+
+- **UserSelect 组件**：搜索驱动，返回完整 IUserProfile 对象（含 email、phone_number）。详细用法参考 **client-builtins-user-service**
+- **Table + 后端分页**：详细实现参考 **table-skill**
+
+### 分页实现
+
+用户列表必须使用后端分页，禁止前端全量拉取。具体实现参考 **table-skill**。
+
+### 动态创建用户记录
+
+**何时动态创建：**
+
+1. **首次提交场景**：用户首次提交问卷/参与抽奖时，使用 `upsert` 方法
+2. **首次登录场景**：用户首次登录系统时，创建用户记录
+
+## 常见错误速查表
+
+| 错误模式                | 问题                   | 正确做法                                                     | 影响        |
+| ----------------------- | ---------------------- | ------------------------------------------------------------ | ----------- |
+| 批量 INSERT users       | Agent 无法获取全量用户 | 使用 UserSelect 组件                                         | 🔴 CRITICAL |
+| `UNIQUE(user_id)`       | 企业不认识 user_id     | `UNIQUE(email)`                                              | 🔴 CRITICAL |
+| 编造 user_id            | Mock 数据无效          | 使用测试用户列表                                             | 🔴 CRITICAL |
+| 全量查询用户列表        | 接口超时或 OOM         | 使用后端分页（skip/take）                                    | 🔴 CRITICAL |
+| 前端分页（全量拉取）    | 首次加载超时           | 使用后端分页                                                 | 🔴 CRITICAL |
+| 只存 user_id 不存 email | 无法做业务层防重       | 存储 user_profile（已含 email），并添加 email 列用于唯一约束 | 🟠 BUG      |
+| 直接显示 user_id        | 用户体验差             | 使用 UserDisplay 组件                                        | 🟡 UX       |
+| 创建 users 基础表       | 无法同步飞书数据       | 使用 user_profile 类型                                       | 🟠 DESIGN   |
+
+## 相关技能参考
+
+- **client-builtins-user-service**: UserSelect 详细用法、IUserProfile 类型定义、UserDisplay 组件、useCurrentUserProfile hook
+- **sql**: user_profile 类型约束、JSONB 验证规则、测试用户列表
+- **table-skill**: Table 组件使用、后端分页实现、前端分页最佳实践
+- **authz-guide**: 结合基于角色的访问控制（如：只允许用户查看/编辑自己的提交）
+
+## 自查清单
+
+### 表设计
+
+- [ ] 判断是否需要创建用户表（参考决策树）
+- [ ] 人员实体表使用 `user_profile PRIMARY KEY`
+- [ ] 业务表使用 `id UUID PRIMARY KEY` + `user_profile` 字段
+- [ ] 业务表包含 `email VARCHAR(255)` or `phone VARCHAR(255)` 字段
+- [ ] 设置了正确的唯一约束（使用 email or 手机号，如 `UNIQUE(resource_id, email)`）
+
+### 前端实现
+
+- [ ] 使用 UserSelect 组件而非手动输入
+- [ ] 使用 UserDisplay 展示用户（不直接显示 user_id）
+- [ ] 用户列表使用后端分页（不全量拉取）
+- [ ] Table 组件的 onChange 触发后端请求
+
+### 后端实现
+
+- [ ] Entity 定义了正确的唯一约束（`@Unique(['resourceId', 'email'])` or `@Unique(['resourceId', 'phone'])`）
+- [ ] 错误处理包含唯一约束冲突（409 Conflict）
+- [ ] 存储 user_profile 字段（已包含 email/phone）
+- [ ] 在表中单独添加 email 或 phone 列，用于唯一约束和索引查询
+- [ ] 列表接口使用 skip/take 分页查询
+- [ ] 返回 pagination 对象（page, pageSize, total）
+
+### Mock 数据
+
+- [ ] user_id 使用测试用户列表（不编造）
+- [ ] user_profile 中的 email/phone 与 user_id 对应正确
+- [ ] 测试了重复提交场景（唯一约束生效）

package/steering/nestjs-react-fullstack/{skills → skills_local}/code-fix/SKILL.md

@@ -1,9 +1,6 @@
 ---
 name: code-fix
-description: Use when encountering code errors such as import failures, TypeScript/Dto type mismatches, JSX syntax issues, API call exceptions (traceid troubleshooting), production log troubleshooting that should route through miaoda-cli, route 404 errors, or **lucide-react icon not found / duplicate identifier / barrel-export naming conflicts**. 触发词：导入错误, 模块解析失败, 类型错误, Dto不匹配, JSX语法, API异常, traceid, 线上日志, 线上日志查询, 查询线上日志, 路由404, code fix, debugging, lucide-react import error, icon not found, 图标不存在, Cannot find name, 标识符重复, no-redeclare, export 冲突, 桶导出冲突, dual export, "请修复错误" 通用排错
-steering: true
-steering-topic: code_fix
-match-template-name: nestjs-react-fullstack
+description: Use when encountering code errors such as import failures, TypeScript/Dto type mismatches, JSX syntax issues, API call exceptions, route 404 errors, or **lucide-react icon not found / duplicate identifier / barrel-export naming conflicts**. 触发词：导入错误, 模块解析失败, 类型错误, Dto不匹配, JSX语法, API异常, 路由404, code fix, debugging, lucide-react import error, icon not found, 图标不存在, Cannot find name, 标识符重复, no-redeclare, export 冲突, 桶导出冲突, dual export, "请修复错误" 通用排错
 ---
 
 
@@ -70,7 +67,7 @@ import { ListPlus, Cake, Home, Building, Twitter } from "lucide-react";
 
 1. **不确定就查**：图标名不在你已知列表里 → 先 `Read packages/client/lucide-react/iconMappings.json`（或 lucide-react 包的 d.ts 导出列表）确认存在，再写 import
 2. **替换图标必须连同 import 列表一起检查**：把旧图标替换成新图标时，**必须先 grep 当前文件 import 列表**确认新名未已 import，避免触发 LSP "标识符重复" / `no-redeclare`
-3. **LSP 警告是硬约束**：multi_edit / 写代码后看到 LSP 任意 "Cannot find name" / "标识符重复" → **必须先修完警告才能 commit**，禁止带 LSP 错误跑 `commit_task`
+3. **LSP 警告是硬约束**：写代码后看到 LSP 任意 "Cannot find name" / "标识符重复" → **必须先修完警告才能 commit**，禁止带 LSP 错误提交
 
 ### 同名 export 重复（修复 SOP）
 
@@ -156,22 +153,11 @@ Module '"@client/src/api/gen"' has no exported member named 'DiscrepancyResponse
 
 ## 调用生成的 API 异常
 
-### 需要查询线上日志时使用 miaoda-cli
+### 查看本地运行日志
 
-**适用场景**：仅当用户提供 traceid、logid、线上报错、发布错误日志、线上运行日志、线上链路追踪，或排查必须依赖线上前端/后端日志。
+**适用场景**：本地开发期 API 调用异常、控制台报错、后端进程行为异常。
 
-**处理要求**：引导并使用 `miaoda-cli` skill 查询线上日志。优先通过 `miaoda observability log/trace` 查询线上运行日志与链路追踪；排查发布错误时使用 `miaoda deploy error-log`。本地开发日志、构建日志、测试日志、浏览器控制台日志不在此范围内，按当前技能或对应工具排查。拿到线上日志后再回到本技能继续定位与修复代码问题。
-
-### 用户提供了 traceid，排查错误
-
-**解决方案**：使用 `miaoda-cli` skill 读取线上前端与后端日志，获取详细错误
-
-**排查示例**：
-
-用户输入：8ae6724e-277e-4d51-afbf-b524b654f27f 看看这个 trace 为什么报错了
-排查路径：
-1. 使用 `miaoda-cli` skill 查询线上服务端与 trace 日志
-2. 根据服务端日志中对应的日志内容修复对应代码逻辑
+**处理要求**：本地日志由 `scripts/dev.js` 落到 `logs/` 目录(`dev.log`、`server.log` 及对应的 `.std.log`),直接 `cat` / `tail -F` 查看;浏览器侧错误看 DevTools Console。本地版**不接管线上日志/traceid 排查链路**(那条路径由发布平台和 oncall 工具承接)。
 
 ### 调用 API 客户端时后端返回异常
 

package/steering/nestjs-react-fullstack/{skills → skills_local}/coding-guide/SKILL.md

@@ -1,11 +1,6 @@
 ---
 name: coding-guide
-description: "项目全局编码规范，必须在任何代码编写、阅读、修改、排查前加载。覆盖：项目结构、目录组织、文件命名、NestJS 后端（MVCS/Drizzle ORM/API 规范/异常处理/用户上下文）、React 19 前端（shadcn/ui/Tailwind/路由/样式/组件规范）、前后端联调（shared 类型/axiosForBackend）、数据库操作、插件能力、质量保障流程、日志规范。Use when: 编写任意前端或后端代码、新建页面或模块、修改接口或数据库操作、排查编译错误或运行时问题、代码审查、理解项目架构。"
-steering: true
-steering-inclusion: always
-steering-topic: coding_guide
-match-template-name: nestjs-react-fullstack
-control-by-feature-ab: true
+description: "项目全局编码规范，必须在任何代码编写、阅读、修改、排查前加载。覆盖：项目结构、目录组织、文件命名、NestJS 后端（MVCS/Drizzle ORM/API 规范/异常处理/用户上下文）、React 19 前端（shadcn/ui/Tailwind/路由/样式/组件规范）、前后端联调（shared 类型/axiosForBackend）、数据库操作、质量保障流程、日志规范。Use when: 编写任意前端或后端代码、新建页面或模块、修改接口或数据库操作、排查编译错误或运行时问题、代码审查、理解项目架构。"
 ---
 # 项目结构
 
@@ -36,8 +31,8 @@ server/ # 符合 NestJS 项目基本规范
 │       ├── hello.controller.ts # controller 示例
 │       ├── hello.module.ts  # module 示例
 │       └── hello.service.ts # service 示例（可选）
-├── database/                # Drizzle ORM 数据库相关。应用仅能进行 DML 操作。若用户需求设计表结构变更，DDL 相关操作需要使用 `ddl_sql` 工具进行。
-│   ├── schema.ts              # Drizzle ORM 数据库 Schema 定义。会在执行完 DDL 操作后自动生成，必须从该文件导入数据库类型，禁止自行编写 schema 文件。如有需要可调用 CodeGen 工具手动生成。
+├── database/                # Drizzle ORM 数据库相关。表结构变更需走 drizzle-kit migration 流程,不要手写 SQL DDL。
+│   ├── schema.ts              # Drizzle ORM 数据库 Schema 定义。必须从该文件导入数据库类型,禁止自行编写或修改 schema 文件 — 应通过 drizzle migration 生成。
 └── common/                  # 共享工具和接口
 │      ├── filters/          # 通用错误处理。
 │      ├── constants/         # 通用常量。
@@ -68,10 +63,8 @@ client/
 │   ├── components/        # 可复用的 UI 组件
 │   │   ├── ui/            # shadcn/ui 组件[Use the components for functionality, but heavily style them.]
 │   │   │   ├── README.md      # shadcn/ui 组件库使用说明 [请务必参考该文档进行组件使用]
-{% if projectMeta['flags']['supportBusinessUser'] %}
 │   │   ├── business-ui/            # 封装好的用户，部门选择组件以及展示组件
 │   │   │   ├── README.md      # 用户展示，用户头像展示，部门选择展示逻辑必须使用 [请务必参考该文档进行组件使用]，禁止直接使用avatar组件等方式自行实现
-{% endif %}
 │   │   ├── Layout.tsx     # 布局包装器
 │   ├── hooks/             # 自定义 React hooks
 │   └── utils/             # 工具函数
@@ -160,10 +153,10 @@ shared/ # 前后端共享的目录
 2. 改动服务端代码 → 进行接口测试，确保新增接口测试通过
 3. 提交前 **必须** 读取相关日志确认无错误（服务端: server/server-devserver 日志；客户端: client-devserver 日志）
 
-如果用户反馈编译失败、服务无法启动：
-1. 调用代码检查工具
-2. 读取 server-devserver 和 client-devserver 日志
-3. dev 服务无响应时可 `pkill -f "dev:server"` / `pkill -f "dev:client"` 触发重启
+如果用户反馈编译失败、服务无法启动:
+1. 跑 `tsc --noEmit` / `eslint` 等代码检查
+2. 查看 `logs/server.log` / `logs/server.std.log` / `logs/dev.log` 找具体错误
+3. dev 服务无响应:在跑 `npm run dev` 的终端 Ctrl+C 后重新启动即可
 
 ---
 
@@ -209,9 +202,8 @@ shared/ # 前后端共享的目录
 
 - **@Injectable() Service 注册**：创建 `@Injectable()` Service → 在对应 Module 的 `providers` 中注册（这条在模块目录内部完成，与聚合文件无关）
 - **三方集成**：调用第三方 API 需在后端实现，使用 @nestjs/axios
-- **能力边界**：服务端不支持文件上传（FaaS 限制），前端用 dataloom SDK 上传，服务端仅保存元信息
+- **文件上传**：前端用 dataloom SDK 上传,服务端仅保存元信息(不要在服务端处理 multipart/form-data)
 - **环境判断**：`process.env.NODE_ENV === "production"` 表示生产环境
-- **文件系统**：**严禁使用 `fs` 写入非 `/tmp` 路径**（无状态 FaaS 容器）
 
 ## 日志约定
 
@@ -286,8 +278,8 @@ await db.select().from(users).where(eq(users.adminUser, userId));
 ### 数据库使用强约束
 
 - 仅通过 schema.ts 暴露的客户端和类型读写，禁止手写 SQL/临时类型
-- **变更流程（CRITICAL）**：`execute_sql` 执行 DDL → 系统自动 codegen → **立即重新读取 schema.ts** → 再编写业务代码。跳过重新读取直接编码是 TS2339 批量错误的主要根因
-- 连接失败/SSL 错误：立即停机并提示用户联系技术支持
+- **变更流程（CRITICAL）**：通过 drizzle-kit migration 修改表结构 → 重新生成 schema.ts → **立即重新读取 schema.ts** → 再编写业务代码。跳过重新读取直接编码是 TS2339 批量错误的主要根因
+- 连接失败/SSL 错误：先检查 `.env.local` 里 `SUDA_DATABASE_URL` 是否正确(走过 `lark-cli apps env pull`),再排查网络/代理
 
 ## API 规范
 
@@ -341,115 +333,11 @@ async createArticle(@Req() req: Request, @Body() dto: CreateArticleDto) {
 
 ## 插件能力（Plugin）
 
-### 召回规则（强制执行）
-
-当用户需求涉及以下关键词时，**必须查询相应 Skill 获取开发指南**：
-
-| 关键词 | 对应能力 |
-|-------|---------|
-| 多维表格、飞书表格、Base、bitable | 飞书多维表格增删改查 |
-| 飞书消息、发送通知、消息推送 | 发送飞书消息 |
-| 飞书群、创建群组、群聊 | 创建飞书群组 |
-| AI生文、AI写作、文本生成 | AI智能生文 |
-| AI总结、文本摘要、内容提炼 | AI文本总结 |
-| AI翻译、多语言翻译、语言互译 | AI智能翻译 |
-| AI分类、文本分类、自动归类 | AI智能分类 |
-| 文本转JSON、结构化提取、文本解析 | AI文本转JSON |
-| AI生图、图片生成、智能配图 | AI智能生图 |
-| 图生图、图片编辑、图片修改 | AI图片编辑 |
-| 图片理解、图片识别、图片分析 | AI图片理解 |
-| 图片转JSON、图片提取、图片结构化 | AI图片转JSON |
-| 图片对比、图片比较、图片差异 | AI图片对比 |
-| 抠图、去背景、去水印、去文字 | AI智能抠图 |
-| 背景替换、换背景、背景合成 | AI背景替换 |
-| 文档解析、PDF解析、文件提取 | AI文档解析 |
-| 搜索总结、网页搜索、搜索摘要 | AI搜索总结 |
-| 语音合成、文本转语音、TTS | AI语音合成 |
-| 语音识别、音频转文字、STT | AI语音转文字 |
-| 插件实例、PluginInstance、Capability | 通用插件调用 |
-
-### 插件配置完整性（CRITICAL）
-
-调用 `capabilityClient.load(pluginInstanceId)` 前**必须确认**：
-1. `server/capabilities/` 下存在对应 `.json` 配置文件
-2. 配置 `id` 与代码中 `pluginInstanceId` 完全匹配
-3. 不存在则**必须先用 `plugin_instance` 工具创建配置**
+本地开发态**暂不支持** PluginInstance / capability 类插件能力的创建与调用 — 这套链路依赖云端 agent 工具(`plugin_instance` / `get_plugin_ai_json`)与平台下发的 `server/capabilities/` 配置,本地没有等价物。
 
-```typescript
-// ❌ 调用不存在的插件（CapabilityNotFoundError — 开发态 Top 错误）
-capabilityClient.load('feishu_monthly_demand'); // server/capabilities/ 下无此配置
-
-// ✅ load 失败时停止后续请求
-try {
-  const result = await plugin.call('read_records', input);
-} catch (err) {
-  if (err.name === 'CapabilityNotFoundError') { setConfigError(true); return; }
-  throw err;
-}
-```
-**缓存 load 结果**，避免重复 load 放大错误请求（单应用可达每页 4-6 次失败）。
-
-### 关键区分：多维表格 vs 数据库表
-
-| 场景 | 判断 | 操作 |
-|-----|------|-----|
-| 明确提到"多维表格/飞书/Base/bitable" | 飞书平台外部服务 | 召回 `plugin_guide` |
-| "建表/DDL/schema变更" | 应用内数据库结构 | 使用 `ddl_sql` 工具 |
-| "往XX表插入数据"（无明确来源） | 检查 `schema.ts` | 有定义→Drizzle ORM；无定义→询问用户确认 |
-
-### 多维表格应用的数据架构选择
-
-当应用需要读取飞书多维表格数据时，根据**查询模式**选择架构：
-
-| 查询模式 | 架构选择 | 实现方式 |
-|---------|---------|---------|
-| 展示/编辑单条记录 | 纯插件 | `getRecord` / `batchUpdateRecords` |
-| 列表分页浏览 | 纯插件 | `searchRecords` + `pageToken` 游标分页 |
-| 统计聚合（计数/求和/平均） | **纯插件 + aggregateQuery** | 禁止 searchRecords 全量拉取后内存计算 |
-| 统计 + 明细下钻 | 纯插件 | 聚合用 `aggregateQuery`，下钻用 `searchRecords` + filter |
-| 排行榜 / TOP N | 纯插件 | `searchRecords` + sort + pageSize=N |
-| 复杂排序/多表关联/全文搜索 | 插件同步 + 本地数据库 | 定时/Webhook 同步到 postgres，复杂查询走数据库 |
-| 高频写入 + 读取 | 本地数据库为主 | 多维表格仅作展示/备份 |
-
-**快捷判断：**
-- 用户说"仪表盘/dashboard/驾驶舱/看板/统计" → **必须用 `aggregateQuery`**
-- 用户说"列表/明细/详情" → `searchRecords` 分页
-- 用户说"排行榜/TOP N" → `searchRecords` + sort + pageSize=N
-- 需要跨表关联或复杂计算 → 建本地数据库表 + 同步
-
-### 使用方式
-1. **复用优先**：先查询插件的 Skills，查看已有的候选插件实例 `available_plugin_instances`。
-2. **查 Runtime Spec**：对候选插件实例调用 `get_plugin_ai_json(pluginInstanceId)`，以返回的 `actions[].key / inputSchema / outputSchema / outputMode` 作为**唯一权威**。
-3. **不能复用才创建/更新**：通过 `plugin_instance` 工具 CREATE/UPDATE 生成或调整单文件 PluginInstance 配置。**绝对禁止**使用 `multi_edit` 工具和 `write` 工具来直接修改 `server/capabilities/` 目录下的内容。
-4. **生成调用代码**：必须先调用 `get_plugin_ai_json(pluginInstanceId)` 获取输入输出要求，严格按 schema 与 outputMode 生成调用逻辑。
-> 详细用法、配置格式、代码示例请参阅 `plugin_guide` 文档。
-
-### 插件调用 API 签名
-
-```typescript
-// Client 侧
-capabilityClient.load(pluginInstanceId).call(actionKey, input)      // 非流式
-capabilityClient.load(pluginInstanceId).callStream(actionKey, input) // 流式
-// Server 侧
-capabilityService.load(pluginInstanceId).call(actionKey, input)
-```
-
-| 参数 | 说明 |
-|------|------|
-| `pluginInstanceId` | 插件实例 ID，如 `'booking_notification_feishu'` |
-| `actionKey` | 来自 `get_plugin_ai_json` 返回的 `actions[].key` |
-| `input` | 结构必须符合 `actions[].inputSchema` |
-
-```typescript
-// ❌ 错误：把参数对象作为 actionKey 传入
-plugin.call(JSON.stringify({ meeting_title: '...' }));
-// ❌ 错误：漏掉 actionKey，直接传参数对象
-plugin.call({ meeting_title: '...' });
-// ✅ 正确：actionKey + input 分开传
-plugin.call('send_feishu_message', { meeting_title: '...' });
-```
-
-使用方式：复用优先 → 查 Runtime Spec（`get_plugin_ai_json`）→ 不能复用才创建 → 严格按 schema 生成调用代码。**绝对禁止**用 `multi_edit`/`write` 工具直接修改 `server/capabilities/` 目录下的内容。
+如果业务用到飞书多维表格、AI 生文/翻译/分类、消息推送等"插件能力"覆盖的场景:
+- **数据存储/查询类**(多维表格 CRUD、列表分页、聚合统计):优先用本应用自带的 Postgres + Drizzle,数据可在云端运行时再同步飞书 Base
+- **AI / 飞书消息类**:在云端发布后由平台插件链路承接;本地开发时可先用接口 mock 桩占位
 
 ## 自动化任务
 
@@ -471,10 +359,10 @@ plugin.call('send_feishu_message', { meeting_title: '...' });
 
 ## 问题排查指引
 
-1. 使用 API 测试工具测试不依赖用户信息的接口
-2. 积极使用 `read_logs` 工具，如无有效日志可增加 logger 打印
-3. DevServer 停止响应时 `pkill` 对应进程触发重启
-4. API 测试返回 HTML 内容时：检查模块注册顺序、路由顺序、请求路径。禁止修改内置 ViewController
+1. 用 `curl` / 浏览器 DevTools / 第三方 HTTP 客户端测试不依赖用户信息的接口
+2. 查看 `logs/server.log` / `logs/server.std.log` 找后端报错;无有效日志时主动补 logger 打印
+3. dev 服务无响应:在跑 `npm run dev` 的终端 Ctrl+C 后重新启动
+4. API 测试返回 HTML 内容时:检查模块注册顺序、路由顺序、请求路径。禁止修改内置 ViewController
 
 ---
 
@@ -489,13 +377,9 @@ plugin.call('send_feishu_message', { meeting_title: '...' });
 - **图表**: ReactECharts，**开发前必须调用 `/charts-skill`**
 - **图标**: Lucide React（唯一图标库，禁止 Emoji 和其他图标库）
 - **表格/表单/图表**: 见下方"组件 Skill 召回规则"，开发前必须先调用对应 Skill
-{% if projectMeta['flags']['supportBusinessUser'] %}
 - **用户**: 用户信息展示/选择必须用 `business-ui` 组件（阅读 README.md），禁止直接展示 userId
-{% endif %}
-{% if projectMeta['flags']['supportTiptapAndStreamdown'] %}
 - **富文本**: `business-ui/tiptap-editor`（阅读 README.md）
 - **Markdown 渲染**: `components/ui/streamdown`（内置 prose 排版）
-{% endif %}
 
 ## API 请求
 
@@ -527,13 +411,9 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 | 组件 | 来源 | 用途 |
 |------|------|------|
 | Table | `@lark-apaas/client-toolkit/antd-table` | 数据表格，**先调 `/table-skill`** |
-{% if projectMeta['flags']['supportBusinessUser'] %}
 | UserSelect/UserDisplay/UserProfile/DepartmentSelect | `business-ui/*` | 用户/部门选择展示 |
-{% endif %}
-{% if projectMeta['flags']['supportTiptapAndStreamdown'] %}
 | TiptapEditorComplete | `business-ui/tiptap-editor` | 富文本编辑器 |
 | Streamdown | `components/ui/streamdown` | Markdown/流式渲染 |
-{% endif %}
 
 ### 组件 Skill 召回规则（强制执行）
 
@@ -557,7 +437,7 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 
 ## @lark-apaas/client-toolkit
 
-**零假设原则**：绝不基于假设使用任何子模块。使用任何 `@lark-apaas/client-toolkit` 子模块前**必须**：① 查询 Skills 或 `steering_doc_search` → ② 等待响应获取文档 → ③ 严格按文档编码。**禁止直接调用 `@lark-apaas/client-toolkit` 任何函数/方法**（不基于查询到的文档）。该库**仅可在前端代码中使用，禁止在后端代码中引用**。
+**零假设原则**：绝不基于假设使用任何子模块。使用任何 `@lark-apaas/client-toolkit` 子模块前**必须**：① 先查询本地已加载的 Skills 或对应包文档 → ② 严格按文档编码。**禁止直接调用 `@lark-apaas/client-toolkit` 任何函数/方法**（不基于查询到的文档）。该库**仅可在前端代码中使用，禁止在后端代码中引用**。
 
 | 功能 | 导入路径 |
 |------|----------|
@@ -571,7 +451,7 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 
 **useCurrentUserProfile** 返回 `Partial<IUserProfile>`，初始为空对象：访问字段用 `?.`，判断加载完成用 `if (!userInfo?.user_id)`。
 
-**UserService.listUsersByIds**: 根据用户 ID 获取用户详细信息（姓名/头像/邮箱/部门）时**必须使用**，**禁止自行实现用户信息查询逻辑**。非组件上下文需要批量获取用户信息时使用。返回 `result.data.userInfoMap: Record<string, UserInfo>`，UserInfo 含 `userID: string`, `name: I18nText { zh_cn, en_us?, ja_jp? }`, `avatar: string`, `email?: string`, `userType: "_employee"|"_externalUser"|"_anonymousUser"`, `department: { departmentID, name: I18nText }`。{% if projectMeta['flags']['supportBusinessUser'] %}展示场景仍优先用 UserDisplay/UserProfile 组件。{% endif %}
+**UserService.listUsersByIds**: 根据用户 ID 获取用户详细信息（姓名/头像/邮箱/部门）时**必须使用**，**禁止自行实现用户信息查询逻辑**。非组件上下文需要批量获取用户信息时使用。返回 `result.data.userInfoMap: Record<string, UserInfo>`，UserInfo 含 `userID: string`, `name: I18nText { zh_cn, en_us?, ja_jp? }`, `avatar: string`, `email?: string`, `userType: "_employee"|"_externalUser"|"_anonymousUser"`, `department: { departmentID, name: I18nText }`。展示场景仍优先用 UserDisplay/UserProfile 组件。
 
 > ⚠️ `UserInfo` 不含任何飞书 ID 字段（`lark_user_id` / `open_id` / `union_id` 都没有）。需要飞书 ID 一律见 `user-identity` skill（当前用户、任意用户 user_id、open_id、union_id 各种场景都在那里）。
 
@@ -661,18 +541,16 @@ return <h1>{data?.title || '未知标题'}</h1>;
 ## 图片规范
 
 - **展示**：必须用 `@client/src/components/ui/image` 组件（非原生 `<img>`），响应式设 `sizes`，固定宽设 `width`
-{% if projectMeta['flags']['supportBusinessUser'] %}
 - 用户头像用 business-ui 组件
-{% endif %}
 
 ### 图片资源优先级
 
-1. 用户上传图片（最高）
-2. `generate_image`（主要方案）— 每个位置独立图片，禁止重复。提示词格式：`[主体] + [环境] + [风格] + [色彩] + [无文字说明]`
-   - **必须包含**：「无文字、无字母、无符号」明确说明
-   - **禁止出现**：① 使用场景（"适合移动端"）② 功能描述（"适合/用于/作为"）③ 目标用途（"品牌展示/课程封面"）④ 观众定位（"吸引年轻人"）⑤ 预期效果（"视觉冲击力/引人注目"）⑥ 媒介格式（"移动端/印刷品"）
-3. 内置 Avatar（仅头像）— `@client/src/utils/img-resources/avatar-placeholders.ts`
-4. Picsum（临时）— `https://picsum.photos/seed/${seed}/${w}/${h}`（必须带 seed）
+1. 用户上传图片(最高)
+2. 用户自带的素材库 / 设计资源 — 放到 `client/public/` 或 CDN
+3. 内置 Avatar(仅头像)— `@client/src/utils/img-resources/avatar-placeholders.ts`
+4. Picsum(临时)— `https://picsum.photos/seed/${seed}/${w}/${h}`(必须带 seed)
+
+> 本地开发态不接 AI 图片生成,需要 AI 生图请走云端发布后由平台插件链路承接
 
 ## 核心功能依赖