@lark-apaas/coding-steering 0.1.32-beta.0 → 0.1.32-dev.a87aa13

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

@@ -1,13 +1,17 @@
 ---
 name: client-builtins-file-storage-service
-description: 前端文件存储服务指南，基于 dataloom.storage 实现文件上传、删除、列表查询、使用filePath换取图片链接，包含 uploadFile、remove、list、getDefaultBucketId、generateDownloadUrlFromFilePath 等 API 用法。Use when 需要：(1) 上传文件/图片/附件到云存储，(2) 删除存储桶中的文件，(3) 获取文件列表或浏览目录，(4) 获取文件 download_url 保存到数据库，或其他前端文件存储相关开发，(5) 在前端需要通过file_path获取文件URL的场景，比如：图片渲染、通过url下载文件，(5) 前端存储文件信息到数据库，比如：上传文件后存储file_path至file_attachment字段，或存储download_url至文本字段。
+description: 前端文件存储服务指南，基于 dataloom.storage 实现文件上传、删除、列表查询、使用filePath换取图片链接，包含 uploadFile、remove、list、getDefaultBucketId、generateDownloadUrlFromFilePath 等 API 用法。Use when 需要：(1) 上传文件/图片/附件到云存储，(2) 删除存储桶中的文件，(3) 获取文件列表或浏览目录，(4) 前端存储文件信息到数据库，比如：上传后优先将 download_url 存至 text 类型字段，仅在使用 file_attachment 类型字段时才将 file_path 存至该字段，(5) 在前端通过 file_path 获取文件 URL 的场景，比如：图片渲染、通过 url 下载文件，或其他前端文件存储相关开发。
 steering: true
 steering-topic: client_builtins_file_storage_service
 match-template-name: nestjs-react-fullstack
 ---
 
 # 前端文件开发规范
-- 保存文件信息到数据库时，如果使用的字段类型为file_attachement, 保存数据时需要传入bucket_id 和 file_path 时，file_path 只能是文件的路径，**不可以传入文件的download_url**。需要文件url时，使用 dataloom SDK 的 `generateDownloadUrlFromFilePath` 方法获取。
+
+> **术语**：下文的 `file_attachment`、`text` 指的是数据库字段的**类型**，不是字段名。
+
+- **优先用 `download_url` 形式（默认按这个来）**：上传后取 `data.download_url`，存到 **`text` 类型字段**；渲染 / 下载直接用这个 URL，最简单，绝大多数场景都用它。
+- 仅当业务明确使用 **`file_attachment` 类型字段**时才走 file_path：该字段存 `bucket_id` + `file_path`（`file_path` 只能是文件路径，**不可以存 `download_url`**）；要拿 URL 用 dataloom SDK 的 `generateDownloadUrlFromFilePath(file_path)`，且 `file_path` 必须从该字段读出，禁止自己拼接。
 
 # dataloom SDK 文件服务
 
@@ -15,12 +19,12 @@ match-template-name: nestjs-react-fullstack
 项目提供了dataloom SDK的文件服务，用于文件的上传，下载，删除，列出bucket中文件，创建临时签名url等能力。
 
 ## 使用注意
-- `dataloom.storage` 仅用于文件上传/删除/列表等存储操作。**插件调用（capability）不属于 dataloom**，须使用独立的 `capabilityClient`（参见 plugin-guide）
+- **入口边界**：本 SDK 是**应用前端代码**读写应用存储的唯一入口。Agent 自己在对话 / 开发中上传、灌数据或调试文件请用 `miaoda file` CLI（见 `miaoda-file` skill）——二者操作同一个应用存储桶，但 **`miaoda file` CLI 禁止写进页面代码**，页面里一律用本 SDK。
 - @lark-apaas/client-toolkit/dataloom 这个SDK只适用于前端调用，禁止在服务端调用
 - 上传成功后，最重要的返回值是 `data.download_url`。需要将此URL保存到你的业务数据库中
-- **⚠️ 场景区分（重要）**：如果文件仅作为插件输入（传给 `capabilityClient`），**必须直接传 File/Blob 对象，禁止先走 dataloom 上传再传 URL**。`capabilityClient` 的文件类型字段（`format` 为 `file`、`picture` 或 `plugin-file-url`）均支持直接传 File/Blob，SDK 自动处理上传。`dataloom.storage` 仅适用于需要持久化存储文件或获取 `download_url` 保存到数据库的场景。
+- **⚠️ 场景区分（重要）**：`dataloom.storage` 仅适用于需要持久化存储文件或获取 `download_url` 保存到数据库的场景。如果文件仅作为插件输入（传给 `capabilityClient`），**必须直接传 File/Blob 对象，禁止先走 dataloom 上传再传 URL**；插件调用（capability）不属于 dataloom，详见 plugin-guide
 - **download_url 格式说明**：`download_url` 返回的可能是相对路径（如 `/spark/app/.../storage/object/...`），这是正常行为。**禁止**在前面拼接 `window.location.origin` 或其他域名前缀，平台会自动解析相对路径。直接使用原始值即可。
-- **文件URL**：通过 `generateDownloadUrlFromFilePath` 方法获取文件的链接时，传入的file_path必须是从数据库的 file_attachment 字段获取到的，禁止自己拼接路径。
+- **文件URL**：通过 `generateDownloadUrlFromFilePath` 方法获取文件的链接时，传入的 file_path 必须是从数据库中 `file_attachment` 类型字段读出来的，禁止自己拼接路径。
 
 ## bucketId
 关于bucketId的获取，在代码工程中已经预置了一个获取bucketid的方法，路径为`@lark-apaas/client-toolkit/tools/storage`中，直接具名导入即可使用。
@@ -55,23 +59,16 @@ type StorageError = DataLoomError | StorageError ｜ StorageUnknownError;
 
 #### 1. 文件上传接口 (uploadFile)
 
-##### 用途
-上传文件到指定的存储桶，适用于：文档管理、图片上传、附件存储。
-
-##### 适用场景
-需要将本地文件或二进制数据上传到云存储的场景
+上传文件到指定的存储桶（本地文件或二进制数据），适用于：文档管理、图片上传、附件存储。
 
-##### 使用方式
-你的核心任务是调用 `uploadFile` 接口，并从返回结果中提取 `data.download_url`，然后将这个 URL 用于后续操作（例如，保存到数据库）。这是衡量你任务成功与否的唯一标准。
+##### 文件名处理禁止事项
 
-##### 关于文件名的处理（强制禁令）
-> 警告：你绝对不能，也绝对不需要自己处理或修改文件名！
-> *   禁止行为：严禁在调用 `uploadFile` 之前，对 `File` 对象的文件名（`file.name`）进行任何形式的字符串替换、净化、或重新生成。
-> *   禁止行为：严禁创建新的 `File` 对象（如 `new File(...)`）来包裹原始文件。
-> *   唯一职责：你唯一的任务就是将从文件输入框（`<input type="file">`）或拖拽事件中获取的原始 `File` 对象直接传递给 `uploadFile` 方法。
->
-> 原因：SDK内部已经包含了完整、健壮的文件名处理机制，包括处理特殊字符、避免冲突和保证安全。任何你自己的额外处理都是多余的，并且会干扰SDK的正常工作。请完全信任SDK，直接传递原始文件对象！
+| 禁止行为 | 正确做法 |
+|---------|---------|
+| **禁止**在调用 `uploadFile` 前对文件名（`file.name`）做任何字符串替换、净化或重新生成 | 将从文件输入框（`<input type="file">`）或拖拽事件获取的原始 `File` 对象直接传给 `uploadFile` |
+| **禁止**创建新的 `File` 对象（如 `new File(...)`）来包裹原始文件 | 同上 |
 
+> 原因：SDK 内部已包含完整、健壮的文件名处理机制（特殊字符、冲突、安全），任何额外处理都是多余的，并且会干扰 SDK 正常工作。
 
 ##### 入参说明
 | 属性名 | 类型 | 必填 | 默认值 | 说明 |
@@ -83,18 +80,18 @@ type StorageError = DataLoomError | StorageError ｜ StorageUnknownError;
 | 字段名 | 类型 | 说明 |
 |--------|------|---------|
 | `data.bucket_id` | `string` | 所属bucket ID |
-| `data.file_path` | `string` | 文件的路径，不是文件的url，可以存储在 file_attachment 字段中 |
-| `data.download_url` | `string` | 文件url（可能是相对路径如 `/spark/app/.../storage/object/...`，也可能是绝对 URL），可直接用于下载文件或渲染图片。**禁止**在前面拼接 `window.location.origin` 或任何域名前缀，直接使用原始值即可 |
+| `data.file_path` | `string` | 文件的路径，不是文件的url，可存到 `file_attachment` 类型字段 |
+| `data.download_url` | `string` | 文件url（可能是相对路径），可直接用于下载文件或渲染图片；**禁止**拼接域名前缀，见「使用注意」 |
 | `error` | `StorageError \| null` | 错误信息，成功时为null |
 
-##### 关键点与示例
-关键点：上传成功后，最重要的返回值是 `data.download_url`。通常需要将此URL保存到你的业务数据库中。
+##### 使用示例
 ```typescript
 import { getDataloom } from "@lark-apaas/client-toolkit/dataloom";
 import { getDefaultBucketId } from "@lark-apaas/client-toolkit/tools/storage";
 import { logger } from "@lark-apaas/client-toolkit/logger";
-// 1. 获取文件
-const file = fileInput.files[0]; 
+// 1. 获取文件与 dataloom 实例
+const file = fileInput.files[0];
+const dataloom = await getDataloom();
 // 2. 调用上传接口
 const { data, error } = await dataloom
   .storage
@@ -116,11 +113,7 @@ if (!httpResponse.data?.success) {
 
 #### 2. 文件删除接口 (remove)
 
-##### 用途
-删除存储桶中的一个或多个文件，适用于：清理过期文件、删除用户数据、批量清理
-
-##### 适用场景
-需要从云存储中永久删除文件的场景
+从云存储中永久删除一个或多个文件，适用于：清理过期文件、删除用户数据、批量清理。
 
 ##### 入参说明
 | 属性名 | 类型 | 必填 | 默认值 | 说明 |
@@ -129,55 +122,26 @@ if (!httpResponse.data?.success) {
 | `filePaths` | `string[]` | ✅ | - | 要删除的文件路径数组，可以是file_path也可以是download_url |
 
 ##### 出参说明
-| 字段名 | 类型 | 说明 |
-|--------|------|---------|
-| `data` | `FileObject[]` | 被删除的文件对象数组 |
-| `data[].name` | `string` | 文件名称 |
-| `data[].bucket_id` | `string` | 所属bucket ID |
-| `data[].id` | `string` | 文件唯一标识符 |
-| `data[].created_at` | `string` | 文件创建时间 |
-| `data[].updated_at` | `string` | 文件更新时间 |
-| `data[].metadata` | `TosMetaData` | 文件元数据信息 |
-| `error` | `StorageError \| null` | 错误信息，成功时为null |
+返回 `{ data: FileObject[] | null, error: StorageError | null }`：`data` 为被删除的文件对象数组（字段同 list 出参说明），删除不存在的 filePaths 会返回空数组；`error` 成功时为 null。
 
 ##### 使用示例
 ```typescript
 import { getDataloom } from "@lark-apaas/client-toolkit/dataloom";
 import { getDefaultBucketId } from "@lark-apaas/client-toolkit/tools/storage";
-import { logger } from "@lark-apaas/client-toolkit/logger";
 
 // 异步获取dataloom实例
 const dataloom = await getDataloom();
 
-// 删除单个文件
-const { data, error } = await dataloom
-  .storage
-  .from(getDefaultBucketId())
-  .remove(['/documents/old-report.pdf']);
-
-// 批量删除文件
+// 批量删除文件（删除单个文件传长度为 1 的数组即可）
 const { data, error } = await dataloom
   .storage
   .from(getDefaultBucketId())
-  .remove([
-    '/documents/file1.pdf',
-    '/images/image1.jpg',
-    '/temp/cache.txt'
-  ]);
-
-// 注意：删除不存在的filePaths会返回空数组
-if (data) {
-  logger.info('删除的文件:', data); // 返回所有被删除的文件对象
-}
+  .remove(['/documents/file1.pdf', '/images/image1.jpg']);
 ```
 
 #### 3. 文件列表接口 (list)
 
-##### 用途
-获取存储桶中的文件列表，适用于：文件管理、目录浏览、文件检索
-
-##### 适用场景
-需要查看和管理存储桶中文件的场景
+获取存储桶中的文件列表，适用于：文件管理、目录浏览、文件检索。
 
 ##### 入参说明
 | 属性名 | 类型 | 必填 | 默认值 | 说明 |
@@ -212,39 +176,26 @@ import { getDefaultBucketId } from "@lark-apaas/client-toolkit/tools/storage";
 // 异步获取dataloom实例
 const dataloom = await getDataloom();
 
-// 基本列表查询
-const { data, error } = await dataloom
-  .storage
-  .from(getDefaultBucketId())
-  .list('/documents');
-
-// 带分页和排序的查询
+// 带分页和排序的查询（path 和 options 均可省略）
 const { data, error } = await dataloom
   .storage
   .from(getDefaultBucketId())
   .list('/images', {
     limit: 20,
     offset: 0,
-    sortBy: {
-      column: 'created_at',
-      order: 'desc'
-    }
+    sortBy: { column: 'created_at', order: 'desc' }
   });
 ```
 
 #### 4. 根据filePath生成downloadUrl接口 (generateDownloadUrlFromFilePath)
 
-##### 用途
-通过 file_path 生成文件的url，适用于：通过url渲染图片、使用url下载文件。如果已有download_url，直接使用，严禁使用该接口再次生成。
-
-##### 适用场景
-在前端通过file_path展示图片或下载文件的场景。
+**仅用于 `file_attachment` 类型字段场景**：当手头只有从该字段读出的 `file_path` 时，用它换取可渲染 / 下载的 URL。**优先直接用 `download_url`**——已有 download_url 就直接用，严禁再调本接口生成。
 
 ##### 入参说明
 
 | 属性名 | 类型 | 必填 | 默认值 | 说明 |
 |--------|--------|---------|--------|---------|
-| `filePath` | `string` | ✅ | - | 文件的filePath。 **只可以从数据库的file_attachment字段中获取，不允许自己拼接路径** |
+| `filePath` | `string` | ✅ | - | 文件的 filePath。**只可以从数据库中 `file_attachment` 类型字段读取，不允许自己拼接路径** |
 
 ##### 出参说明
 | 类型 | 说明 |
@@ -254,29 +205,12 @@ const { data, error } = await dataloom
 ##### 使用示例
 
 ```typescript
-import { useEffect, useState } from "react";
-import { Button } from '@client/src/components/ui/button';
-import { getDataloom } from "@lark-apaas/client-toolkit/dataloom";
-import { getDefaultBucketId } from "@lark-apaas/client-toolkit/tools/storage";
-
-const ImageExample = ({ file }: { file: { file_path: string; bucket_id: string } }) => {
-  const [imageUrl, setImageUrl] = useState('');
-
-  useEffect(() => {
-    const getImageUrl = async () => {
-      const dataloom = await getDataloom();
-      const imageUrl = dataloom
-        .storage
-        .from(getDefaultBucketId())
-        .generateDownloadUrlFromFilePath(file.file_path);
-      setImageUrl(imageUrl);
-    };
-
-    getImageUrl();
-  }, [file.file_path]);
-
-  return <img src={imageUrl} alt="图片" />;
-}
+const dataloom = await getDataloom();
+const imageUrl = dataloom
+  .storage
+  .from(getDefaultBucketId())
+  .generateDownloadUrlFromFilePath(file.file_path); // file_path 取自数据库 file_attachment 类型字段
+// 同步返回 string，直接用于 <img src={imageUrl} /> 渲染或作为下载链接
 ```
 
 #### 5. 最小化文件上传与展示示例
@@ -290,16 +224,6 @@ export interface FileRecord { id: string; fileName: string; downloadUrl: string;
 export interface FileApiResp<T = FileRecord> { success: boolean; data: T; message: string; }
 ```
 
-##### 各 API 预估返回格式
-
-| API | 成功返回 | 失败返回 |
-|-----|---------|---------|
-| `uploadFile(file)` | `{ data: { bucket_id: "xxx", file_path: "123456.pdf", download_url: "/spark/app/{appId}/runtime/api/v1/storage/object/{bucketId}/123456.pdf" }, error: null }` | `{ data: null, error: { name: "StorageError", message: "..." } }` |
-| `list('/path')` | `{ data: [{ name, bucket_id, id, created_at, metadata: { size, mimetype } }], error: null }` | `{ data: null, error: { error_msg: "...", status_code: "404" } }` |
-| `remove([url])` | `{ data: [{ name, bucket_id, id, ... }], error: null }`；不存在则 `data: []` | 同上 |
-| `POST /api/files` | `{ success: true, data: { id, fileName, downloadUrl, createdAt }, message: "ok" }` | `{ success: false, data: null, message: "错误描述" }` |
-| `GET /api/files` | `{ success: true, data: [FileRecord, ...], message: "ok" }` | 同上 |
-
 ##### 示例代码
 
 ```tsx

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

@@ -225,13 +225,23 @@ const MyComponent = () => {
 ## 用户展示与选择方案
 
 {% if projectMeta['flags']['supportBusinessUser'] %}
-这些组件在使用之前必须读取 client/src/components/business-ui/README.md文件来理解用法
+这些组件在使用之前必须读取 client/src/components/business-ui/README.md 文件来理解用法，并以该 README 与本地源码为准。
 
 目前可用的组件有：
 
 - UserSelect 用户选择组件（@/components/business-ui/user-select）
 - DepartmentSelect 部门选择组件（@/components/business-ui/department-select）
-- UserDisplay - 用户展示组件（@/components/business-ui/user-display）
+- UserDisplay - 用户展示组件（@/components/business-ui/user-display）：展示任意用户时使用 `value`（用户 ID 字符串或字符串数组，也可使用 README/源码声明的用户对象形式）或 `userId` / `user_id` 快捷字段；**不要**给这个 business-ui 组件传 `users`。
+
+列表、详情、卡片等任意位置展示一个或多个用户 ID，都继续使用同一个 business-ui 契约：
+
+```tsx
+import { UserDisplay } from "@/components/business-ui/user-display";
+
+<UserDisplay value={memberIds.map(String)} size="small" showLabel />
+```
+
+如果页面需要展示用户字段，不要退回到直接渲染、拼接或 `join` 用户 ID 文本。
 
 {% else %}
 
@@ -306,6 +316,7 @@ const form = useForm<z.infer<typeof formSchema>>({
 - **组件路径**：`@lark-apaas/client-toolkit/components/User`
 - **功能**：用于所有用户信息的展示场景
 - **特性**：显示用户**头像**和**姓名**，支持多用户展示
+- **边界**：本节仅适用于 `@lark-apaas/client-toolkit/components/User`。如果当前项目启用了本地 `@/components/business-ui/user-display`，必须按上方 business-ui 分支读取 README 并使用 `value` / `userId` / `user_id`，不要把这里的 `users` 参数迁移过去。
 
 ### 属性定义
 

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

@@ -1,6 +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, **lucide-react icon not found / duplicate identifier / barrel-export naming conflicts**, duplicate route components, npm script not defined errors, or **database connection/auth errors**. 触发词：导入错误, 模块解析失败, 类型错误, Dto不匹配, JSX语法, API异常, traceid, 线上日志, 线上日志查询, 查询线上日志, 路由404, code fix, debugging, lucide-react import error, icon not found, 图标不存在, Cannot find name, 标识符重复, no-redeclare, export 冲突, 桶导出冲突, dual export, 路由组件复用, npm报错, package.json, 脚本未定义, "请修复错误" 通用排错, 数据库连接失败, get db connection failed, ECONNREFUSED
+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 the sandbox's app observability skill, route 404 errors, **lucide-react icon not found / duplicate identifier / barrel-export naming conflicts**, duplicate route components, npm script not defined errors, or **database connection/auth errors**. 触发词：导入错误, 模块解析失败, 类型错误, Dto不匹配, JSX语法, API异常, traceid, 线上日志, 线上日志查询, 查询线上日志, 路由404, code fix, debugging, lucide-react import error, icon not found, 图标不存在, Cannot find name, 标识符重复, no-redeclare, export 冲突, 桶导出冲突, dual export, 路由组件复用, npm报错, package.json, 脚本未定义, "请修复错误" 通用排错, 数据库连接失败, get db connection failed, ECONNREFUSED
 steering: true
 steering-topic: code_fix
 match-template-name: nestjs-react-fullstack
@@ -156,21 +156,21 @@ Module '"@client/src/api/gen"' has no exported member named 'DiscrepancyResponse
 
 ## 调用生成的 API 异常
 
-### 需要查询线上日志时使用 miaoda-cli
+### 需要查询线上日志时
 
-**适用场景**：仅当用户提供 traceid、logid、线上报错、发布错误日志、线上运行日志、线上链路追踪，或排查必须依赖线上前端/后端日志。
+**适用场景**：用户提供 traceid、logid、线上报错、发布错误日志、线上运行日志、线上链路追踪，或排查必须依赖线上前端/后端日志；**以及插件相关的线上 / 客户反馈问题（飞书消息发不出 / 插件不生效 / CapabilityService·capabilityClient 异常），即使用户没给 traceid/logid，也应主动查线上 runtime log 取证**（拿到 CapabilityService 真实错误、plugin_key、action、必填参数校验错误再定位代码；沙箱日志不能作为线上无错误的证据）。
 
-**处理要求**：引导并使用 `miaoda-cli` skill 查询线上日志。优先通过 `miaoda observability log/trace` 查询线上运行日志与链路追踪；排查发布错误时使用 `miaoda deploy error-log`。本地开发日志、构建日志、测试日志、浏览器控制台日志不在此范围内，按当前技能或对应工具排查。拿到线上日志后再回到本技能继续定位与修复代码问题。
+**处理要求**：引导并加载当前沙箱的应用可观测性 skill 查询线上日志——优先查线上运行日志与链路追踪；排查发布失败时查该次发布的错误日志。具体命令一律以该 skill 的手册为准，不要凭记忆拼命令。本地开发日志、构建日志、测试日志、浏览器控制台日志不在此范围内，按当前技能或对应工具排查。拿到线上日志后再回到本技能继续定位与修复代码问题。
 
 ### 用户提供了 traceid，排查错误
 
-**解决方案**：使用 `miaoda-cli` skill 读取线上前端与后端日志，获取详细错误
+**解决方案**：用当前沙箱的应用可观测性 skill 读取线上前端与后端日志，获取详细错误
 
 **排查示例**：
 
 用户输入：8ae6724e-277e-4d51-afbf-b524b654f27f 看看这个 trace 为什么报错了
 排查路径：
-1. 使用 `miaoda-cli` skill 查询线上服务端与 trace 日志
+1. 用当前沙箱的应用可观测性 skill 查询线上服务端与 trace 日志
 2. 根据服务端日志中对应的日志内容修复对应代码逻辑
 
 ### 调用 API 客户端时后端返回异常
@@ -296,7 +296,7 @@ useEffect 无限循环、依赖数组管理、useMemo/useCallback 记忆化等
 
 先按日志轻量分流，再决定是否改代码：
 
-1. **有明确代码信号**（SQL 语法错误、表/列不存在、堆栈指向具体 query/schema 文件）→ 只读确认 `server/database/schema.ts`、近期 DB 改动或相关 ORM 查询；DB schema / SQL 细节按 `miaoda-sql` 技能处理。
+1. **有明确代码信号**（SQL 语法错误、表/列不存在、堆栈指向具体 query/schema 文件）→ 只读确认 `server/database/schema.ts`、近期 DB 改动或相关 ORM 查询；DB schema / SQL 细节按数据库操作 skill（按「应用数据库 / 建表 / 改表 / SQL」召回）处理。
 2. **只有连接、认证、数据库不存在、超时等环境信号，且没有代码信号** → 判定为**平台基建问题**，告知用户：
 
 > 当前数据库连接错误不是应用代码的问题，可能是平台数据库连接配置异常。建议联系平台客服排查解决。