@lark-apaas/coding-steering 0.1.57 → 0.1.59

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

@@ -287,6 +287,40 @@ function MultiPluginStreamExample({ recordId }: { recordId: string }) {
 4. 若无法执行真实调用，必须明确写明阻塞原因，禁止直接标记“开发完成”
 5. 若用户触发 AI 生成的请求超时、连接断开或工具返回超时，必须判定为验收失败；只有触发请求快速返回、随后能通过页面或接口读到明确完成或失败终态和结果，才允许标记通过
 
+### 服务端 capability 手动 HTTP 调试与排障
+
+仅绕过 SDK 做请求级复测或排障时使用本节，应用业务代码仍调用 SDK：Client 侧 `capabilityClient.load(id).call(actionKey, input)` / `callStream(actionKey, input)`；Server 侧兜底 `capabilityService.load(id).call(actionKey, input)`。
+
+#### 1. 手动 HTTP/debug body 合同
+
+调试入口与 body：
+
+| 场景 | URL | body |
+|------|-----|------|
+| 运行态 unary | `POST /api/capability/<capabilityId>` | `{ "action": "<actionKey>", "params": { ... } }` |
+| 运行态 stream | `POST /api/capability/<capabilityId>/stream` | `{ "action": "<actionKey>", "params": { ... } }` |
+| 内部 debug unary | `POST /__innerapi__/capability/debug/<capabilityId>` | `{ "action": "<actionKey>", "params": { ... } }`，可按调试需要附带 `capability` |
+| 内部 debug stream | `POST /__innerapi__/capability/debug/<capabilityId>/stream` | `{ "action": "<actionKey>", "params": { ... } }`，可按调试需要附带 `capability` |
+
+- `action` 仍来自 `get_plugin_ai_json(...).actions[].key`；`params` 仍按 `actions[].inputSchema`。
+- HTTP body 用 action/params；禁止写成 `{ "actionKey": "...", "input": { ... } }`。
+- `Action 'undefined' not found` 先查 HTTP body 顶层字段：确认 body 顶层有 `action`，且插件输入放在 `params` 下；再查 action 名称是否存在。
+
+#### 2. 先读 server 日志再归因
+
+插件调用失败时，先读 `server` 日志，记录同一次请求的 `path`、`action`、`input`、`pluginName`、`actionName`、`status_code`、`detail.code`、`logID`。只看前端报错或只说“应检查日志”不算完成排障。
+
+按日志分层：
+
+| 日志信号 | 归因 |
+|----------|------|
+| `path` 命中 capability HTTP/debug 入口，`action` 为空或缺失，错误类似 `Action 'undefined' not found` | 协议错误：手动 HTTP body 没按 action/params 写 |
+| `action` 正确，但 `input` 缺必填字段、类型不符或数组/文件格式错误 | 参数错误：按 `inputSchema` 修正 `params` |
+| `pluginName` / `actionName` 已命中，`detail.code` 或下游日志指向插件服务、模型、TOS、限流等 | 插件后端错误：保留 `logID` 和下游错误码，避免改应用代码掩盖 |
+| capability 调用成功，但应用接口、持久化、状态流转或 UI 读取失败 | 应用代码错误：排查业务接口、数据库和前端状态，不改插件合同 |
+
+手动 HTTP/debug 复测只用于确认请求级合同和日志归因；最终实现仍回到 SDK 调用或既定 Server 侧编排。
+
 ### Server 侧调用方式（仅兜底场景）
 
 > 以下场景适合使用 Server 侧调用；若前端 `callStream` + 既有 CRUD 保存即可满足展示和持久化，不要优先引入后端后台任务。
@@ -332,7 +366,97 @@ Please make sure that the argument Function at index [0] is available in the Xxx
 
 同一规则适用于从 `@lark-apaas/fullstack-nestjs-core` 注入的其他平台服务（`AuthNPaasService`、`FileService` 等）。
 
-#### 3. 调用示例
+#### 3. Server 侧已持久化文件进入 AI capability
+
+Client 侧拿到用户刚选择的原始 `File` / `Blob` 时，直接传 `capabilityClient`，不要为了调用插件先上传到应用存储。文件/图片已作为业务数据持久化，且必须由 Server 侧 `CapabilityService` 调 `ai-doc-parser`、`ai-image-understanding` 或其它 `file` / `picture` / `plugin-file-url` / `plugin-image-url` 参数时，才在服务端把存储路径换成临时 http(s) URL 后传入插件。
+
+优先从业务记录读取存储 `file_path`；字段类型是 `file_attachment` 时，同时读取 `bucket_id` 与 `file_path`。旧记录只有标准 `/app` 或 `/spark/app/.../runtime/api/v1/storage/object/<bucket>/<key>` download URL 时，可以解析出 bucket 与 file path 后再签名；不能把它直接交给默认 `createSignedUrl()`，因为该入口只使用默认 bucket，不会使用 URL 里的 bucket。签名 URL 才能交给 AI plugin。禁止给标准路径拼接 `localhost`、`window.location.origin` 或 `/app/<app_id>`，否则会绕过内部路径解析并被当成不安全的外部 URL。非标准相对路径、前端展示 URL、非法 base64 data URL 不应作为 Server 侧插件稳定入参。
+
+```typescript
+import { FileService } from '@lark-apaas/fullstack-nestjs-core';
+
+type StoredFileRef = {
+  file_path?: string | null;
+  bucket_id?: string | null;
+  download_url?: string | null;
+};
+
+const STORAGE_DOWNLOAD_URL_RE =
+  /^\/(?:spark\/)?app\/app_[\w]+\/runtime\/api\/v1\/storage\/object\/([^/]+)\/(.+)$/;
+
+function parseStorageDownloadUrl(
+  downloadUrl: string,
+): { bucketId: string; filePath: string } | null {
+  const match = STORAGE_DOWNLOAD_URL_RE.exec(downloadUrl);
+  if (!match) return null;
+
+  try {
+    const bucketId = decodeURIComponent(match[1]);
+    const filePath = decodeURIComponent(match[2]);
+    return bucketId && !bucketId.includes('/') && filePath
+      ? { bucketId, filePath }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+async function createTemporaryFileUrl(
+  fileService: FileService,
+  file: StoredFileRef,
+): Promise<string | null> {
+  try {
+    let signedUrl: string;
+    if (file.file_path) {
+      signedUrl = file.bucket_id
+        ? await fileService
+          .from(file.bucket_id)
+          .createSignedUrl(file.file_path, 3600)
+        : await fileService.createSignedUrl(file.file_path, 3600);
+    } else {
+      const parsed = file.download_url
+        ? parseStorageDownloadUrl(file.download_url)
+        : null;
+      if (!parsed) return null;
+      signedUrl = await fileService
+        .from(parsed.bucketId)
+        .createSignedUrl(parsed.filePath, 3600);
+    }
+    return signedUrl || null;
+  } catch (error) {
+    // 这里不要返回伪成功 URL；由调用方把业务状态置为 failed/pending/null 等可见状态
+    return null;
+  }
+}
+```
+
+调用 AI 插件前先签名并校验 URL：
+
+```typescript
+const docParserPluginInstanceId = '<doc-parser-plugin-instance-id>';
+const signedUrl = await createTemporaryFileUrl(this.fileService, storedFile);
+if (!signedUrl) {
+  this.logger.warn('missing file path or create signed url failed before AI capability call', {
+    filePath: storedFile.file_path,
+    bucketId: storedFile.bucket_id,
+    hasDownloadUrl: Boolean(storedFile.download_url),
+    pluginInstanceId: docParserPluginInstanceId,
+    actionKey: 'parseDocToMarkdown',
+  });
+  await this.updateRecord(recordId, { parseStatus: 'failed', parsedText: null });
+  return;
+}
+
+const output = await this.capabilityService
+  .load(docParserPluginInstanceId)
+  .call('parseDocToMarkdown', {
+    fileUrl: [signedUrl], // 是否数组必须以 inputSchema 为准
+  });
+```
+
+稳定契约：已持久化文件统一使用签名函数返回的 URL，不要先下载后转 base64，也不要把原始 URL 作为备用值传给插件。缺少可识别的文件路径、签名失败或返回空 URL 时记录警告，写入 `failed` / `pending` / `null`，并停止调用插件。
+
+#### 4. 调用示例
 
 服务端 `CapabilityExecutor` 的**三个方法全都没有泛型参数**（`@lark-apaas/nestjs-capability`）：
 
@@ -366,11 +490,12 @@ try {
 }
 ```
 
-#### 4. Server 侧编排与容错原则
+#### 5. Server 侧编排与容错原则
 
 - PluginInstance 调用在 Server 侧通常属于 **外部依赖 / side-effect**
 - 除非业务明确要求强一致性，**默认不应阻塞主业务流程**
 - 已选择 Server 侧承接的高耗时 AI capability 必须有可观测状态：创建任务时记录处理进度、完成终态、失败终态、输入摘要、错误信息和结果引用；触发接口只返回任务标识与当前状态，前端通过短轮询读取进度和最终结果
+- 文件/图片签名 URL 生成失败时必须 `warn` 并把业务记录保持在 `failed` / `pending` / `null` 等用户可见状态，禁止构造假 URL 或写入“解析成功”
 
 推荐写法：异步触发 + catch 兜底：
 

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

@@ -1,177 +1,210 @@
----
-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。
-> **入口边界**：本 SDK 是**服务端代码**读写应用存储的入口；Agent 在对话 / 开发中自己上传或调试文件，先加载应用文件存储操作 skill（按「应用文件存储 / 文件上传 / 文件下载」召回），用其 CLI 命令操作，具体命令一律以该 skill 为准。二者与本 SDK 操作同一个应用存储桶，但**该 CLI 命令只供 Agent 在沙箱终端使用，禁止写进服务端代码**。
-
-## 使用场景
-
-| 场景 | 说明 |
-|------|------|
-| 服务端文件处理 | 下载文件到本地处理后重新上传，如图片格式转换、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[]` 数组 |
+---
+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。
+> **入口边界**：本 SDK 是**服务端代码**读写应用存储的入口；Agent 在对话 / 开发中自己上传或调试文件，先加载应用文件存储操作 skill（按「应用文件存储 / 文件上传 / 文件下载」召回），用其 CLI 命令操作，具体命令一律以该 skill 为准。二者与本 SDK 操作同一个应用存储桶，但**该 CLI 命令只供 Agent 在沙箱终端使用，禁止写进服务端代码**。
+
+## 展示 URL 边界
+
+- 服务端上传或读取文件元信息后，`FileMeta.downloadURL` 是前端展示 / 下载的权威 URL。普通 `text` / `varchar` / `JSON` 业务字段回显文件时，接口应返回这个 URL（字段名如 `fileUrl` / `downloadUrl`）。
+- 后台异步解析、格式转换等流程可保存稳定 `filePath` 作内部定位；列表 / 详情接口仍必须同时返回 `downloadURL`，或用 `getFileMetadata(filePath).downloadURL` 换出展示 URL。禁止只把普通 path 字段交给前端再生成 URL。
+- `filePath` 不是前端展示 URL，不得让前端手拼 `/runtime/api/v1/storage/object`、`/app/{appId}/runtime`、`/spark/app/{appId}/runtime`、`__runtime__` 等运行态前缀。只有数据库字段类型明确为 `file_attachment` 且保存 `bucket_id + file_path` 时，才由前端按 file_attachment 规则换 URL。
+
+## 使用场景
+
+| 场景 | 说明 |
+|------|------|
+| 服务端文件处理 | 下载文件到本地处理后重新上传，如图片格式转换、docx 格式转换等 |
+| 自动化任务生成文件 | 定时任务或事件触发后，根据数据库/插件内容生成文件并上传，如定时生成 PDF 报告、图片海报等 |
+
+## Quick Reference
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
+| `upload(file, options?)` | 上传文件 | `FileMeta` |
+| `download(path)` | 下载文件（≤50MB） | `FileDownloadBuilder` |
+| `createSignedUrl(filePath, expiresIn)` | 默认 bucket 下生成临时 http(s) 签名 URL | `string` |
+| `from(bucketId).createSignedUrl(filePath, expiresIn)` | 指定 bucket 生成临时 http(s) 签名 URL | `string` |
+| `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`
+
+`FileMeta.downloadURL` 可直接返回给前端展示 / 下载。业务需后台处理文件时，可同时保存 `filePath` 作内部定位；接口给前端的展示字段仍应是 `downloadURL`。
+
+**示例：**
+
+```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. 生成临时签名 URL
+
+服务端把应用存储中的文件/图片传给 AI capability（如 `ai-doc-parser`、`ai-image-understanding` 或 `plugin-file-url` / `plugin-image-url` 入参）时，不要把站内 download URL 直接作为插件最终入参。优先用数据库保存的 `file_path`，必要时带上 `bucket_id`。旧记录只有标准 `/app` 或 `/spark/app/.../runtime/api/v1/storage/object/<bucket>/<key>` download URL 时，先解析其中的 bucket 与 file path，再从对应 bucket 生成临时 http(s) 签名 URL。默认 `createSignedUrl()` 只使用默认 bucket；它即使能从 download URL 提取 file path，也不会使用 URL 里的 bucket。误拼 origin 的路径、非标准相对路径、前端展示 URL 或 base64 data URL 不作稳定输入。
+
+`download()` 是服务端自己读取文件内容的接口，不是给 AI capability 准备 URL 的默认方案；需要给插件一个可访问 URL 时用 `createSignedUrl()`。
+
+**示例：**
+
+```typescript
+// 默认 bucket
+const signedUrl = await this.fileService.createSignedUrl(filePath, 3600);
+
+// 指定 file_attachment 记录里的 bucket
+const signedUrl = await this.fileService
+  .from(bucketId)
+  .createSignedUrl(filePath, 3600);
+```
+
+签名失败时记录 `warn`，业务状态保持为 `failed`、`pending` 或结果字段 `null`，让前端能看到失败/待处理；禁止吞掉错误后写入“已解析成功”。
+
+### 4. 删除文件
+
+**入参：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `filePaths` | `string[]` | 是 | downloadURL 或文件存储路径数组 |
+
+**返回值：** `FileMeta[]` - 删除成功的文件元信息数组
+
+**示例：**
+
+```typescript
+// 推荐：使用 downloadURL
+const result = await this.fileService.remove([fileMeta.downloadURL]);
+
+// 也可以使用文件存储路径
+const result = await this.fileService.remove(['file1.pdf', 'file2.png']);
+```
+
+### 5. 获取文件元信息
+
+**入参：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `filePath` | `string` | 是 | downloadURL 或文件存储路径 |
+
+**返回值：** `FileMeta | null` - 文件元信息或 `null` 表示文件不存在或删除失败。内部已有 `filePath` 且需前端回显时，用 `getFileMetadata(filePath).downloadURL` 换出展示 URL，并随列表 / 详情接口返回。
+
+**示例：**
+
+```typescript
+// 推荐：使用 downloadURL
+const meta = await this.fileService.getFileMetadata(fileMeta.downloadURL);
+
+// 后台保存 filePath 时，先换出展示 URL 再返回前端
+const meta = await this.fileService.getFileMetadata('file.pdf');
+const fileUrl = meta?.downloadURL;
+```
+
+## Common Mistakes
+
+| 错误 | 正确做法 |
+|------|----------|
+| 直接 `await download()` 导致内存溢出 | 始终使用 `.asStream()` 流式下载 |
+| 把 `download()` 结果或站内 `downloadURL` 直接当作 AI capability 最终入参 | 优先用 `file_path + bucket_id` 签名；只有 download URL 时先解析 bucket 与 file path，再从对应 bucket 生成签名 URL |
+| 忘记设置 `contentType` 导致浏览器无法预览 | 上传时明确指定 `contentType` |
+| 直接 `new FileService()` 手动实例化 | 通过 NestJS DI 注入 `FileService` |
+| 在异步回调中调用 `download()` 导致上下文丢失 | 在请求处理函数中立即调用，SDK 内部已处理上下文捕获 |
+| 删除时传单个字符串 | `remove()` 参数为 `string[]` 数组 |
+| 普通业务字段只返回 filePath，让前端二次生成展示 URL | 接口另返 `downloadURL`，前端直接消费该 URL |

package/steering/nestjs-react-fullstack/skills_common/mcp-guide/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: mcp-guide
+description: "Use when 用户要把应用能力开放给外部 Agent / 工作伙伴 / MCP 客户端调用，新增或修改 MCP 工具，给工具结果加界面（MCP Apps / ui:// 资源），维护应用 Skill（server/mcp/skills/<name>/SKILL.md，SDK 注册为 MCP Prompt），要在开发态核对、调用、调试 MCP 工具，或要把本应用的 MCP 接到自己的 Agent 客户端上使用。触发词：MCP, MCP Server, MCP 工具, MCP Apps, ui://, @McpTools, @McpTool, @McpUiResource, McpToolError, readMcpUiTemplate, tools/list, tools/call, resources/read, prompts/list, prompts/get, mcp_inspect, 开放给 Agent, 工作伙伴调用, Agent 调用应用, 应用 Skill, server/mcp, server/mcp/ui, server/mcp/skills, 接入 MCP, 连接 MCP, 怎么用这个 MCP, MCP 客户端, Claude Code, Codex, mcp add, mcp login, config.toml, X-Mcp-Token, MCP 凭证, 可用范围, 连不上。不负责 HTTP 对外开放接口（走 openapi-guide）、自动化触发器（走 trigger-guide）。"
+steering: true
+steering-topic: mcp_guide
+match-template-name: nestjs-react-fullstack
+---
+
+# MCP 开发与调试
+
+应用的 MCP Server 是全栈工程里多出来的一层出口：同仓、同域名、同版本。SDK（`@lark-apaas/fullstack-nestjs-core` 重导出 `@lark-apaas/nestjs-mcp`）已经内置端点 `POST /__innerapi__/mcp`、Streamable HTTP 协议、zod 校验、身份读取、`ui://` 资源与应用 Skill（MCP Prompt）下发。你只写三种文件：工具类、界面入口、应用 Skill。
+
+**真值顺序**：工程内 `node_modules/@lark-apaas/nestjs-mcp/dist/index.d.ts` > 本文。装饰器选项、类型名、返回值形状以它为准；本文与它冲突时按包改，不按本文改。**读它、但不从它 import**：公开 API 一律从 `@lark-apaas/fullstack-nestjs-core` 导入，直接 import 会被 ESLint 判「不在 dependencies 中」，那时改 import 源、不要加进 `dependencies`。
+
+## 固定路径（不探测）
+
+| 路径 | 内容 |
+|---|---|
+| `server/mcp/tools/<域>.tools.ts` | 工具类：一个业务域一个文件，`@McpTools()` 类 + 多个 `@McpTool()` 方法 |
+| `server/mcp/ui/<entry>/index.html`（+ `main.tsx`）、`server/mcp/ui/tsconfig.json` | MCP Apps 界面源码：独立的浏览器代码，Vite 预设自动打成 `dist/mcp-ui/<entry>.html` |
+| `server/mcp/skills/<name>/SKILL.md` | 应用 Skill：一个业务流程一份，给消费方 Agent 看的用法说明，SDK 注册为同名 MCP Prompt |
+
+`server/mcp/` 不存在即为首次开通；开通只需建上述文件并把工具类注册为所属业务模块的 provider。`McpModule` 已由 `PlatformModule.forRoot()` 引入，SDK 启动时扫已加载模块的 provider 自动发现工具类——挂在已有业务模块上就不用动 `app.module.ts`，新建的模块仍要接进去，否则整个模块不会实例化、工具静默缺席；不写注册表，不写 `tools/index.ts`。
+
+两份同名的 SKILL.md 别混：本文教你写代码，`server/mcp/skills/*/SKILL.md` 是产物、教下游 Agent 用工具。不把本文复制成应用 Skill，应用 Skill 不加 `steering: true`。
+
+## 前置检查（一条命令）
+
+```bash
+ls -d node_modules/@lark-apaas/nestjs-mcp node_modules/@lark-apaas/coding-preset-vite-react/lib/plugins/mcp-ui.js
+```
+
+- 缺 `@lark-apaas/nestjs-mcp` → 当前 `@lark-apaas/fullstack-nestjs-core` 不含 MCP 层（`1.1.62` 起含）。告知用户升级 core，停止；不装 `@modelcontextprotocol/sdk`、不手写端点。
+- 缺 `mcp-ui.js` → 只能做工具、不能做界面（`@lark-apaas/coding-preset-vite-react` `1.0.23` 起含）。要做界面先让用户升级该预设。Rspack 预设不支持 MCP Apps。
+
+## 任务路由
+
+`$SKILL_DIR` 取技能清单里本 skill 的 location 所在目录。
+
+| 任务 | 读 |
+|---|---|
+| 新增 / 修改工具、开通 MCP、维护应用 Skill | `$SKILL_DIR/references/tool-authoring.md` |
+| 给工具结果加界面、改界面、界面与工具联动 | `$SKILL_DIR/references/mcp-apps.md` |
+| 用 `mcp_inspect` 核对与调用、按错误定位、本地模式调试 | `$SKILL_DIR/references/debugging.md` |
+| 用户要在自己的 Agent（Claude Code / Codex / 其它客户端）里连本应用的 MCP | `$SKILL_DIR/references/client-onboarding.md` |
+
+前三类是改代码，改完等 dev server 重启（定义有问题会在启动日志里报），再按 `$SKILL_DIR/references/debugging.md` 的回路用 `mcp_inspect` 验证。`mcp_inspect` 报「当前运行环境不支持」是本地 CLI 宿主，走该文件的本地模式。向用户汇报用业务表述（「找到 4 个演示航班」），不贴 JSON。
+
+## 不变量
+
+1. 一个工具对应一件用户说得出口的事（找订单、取消订单），不按库表铺增删改查；读和写分在不同工具里。
+2. schema 用 zod，提成常量放类上方；方法签名固定 `(input: Infer<typeof In>, ctx: McpContext)`，返回 `McpToolResult<typeof Out>`。签名写错在 `npm run type:check:server` 暴露。
+3. `description` 面向模型：用途、何时调用、参数来源、返回什么、失败怎样。每个 zod 字段 `.describe()`。消费方 Agent 只靠这些选工具、填参数。
+4. 四项 `annotations` 显式写出。只读工具必须 `readOnlyHint: true`：缺省会被当成可能写数据，调试时每次都要 `safe: true`，消费方也会额外确认。
+5. 声明了 `outputSchema` 就返回匹配的 `structuredContent`，对不上时 `mcp_inspect` 报「输出与其声明的 outputSchema 不符」；列表工具入参带 `limit`（默认不超过 20）与 `cursor`；写操作的幂等由 Service 保证，不引入幂等键字段。
+6. 返回值按消费方够用来裁：`structuredContent` 只放它推理或界面渲染要用的字段。SDK 不截断，返回多少对方就吃多少，详见 `$SKILL_DIR/references/tool-authoring.md` 的「返回体积」。
+7. 业务失败抛 `McpToolError(message, { code })`，Agent 原样收到；`message` 连下一步一起写（「订单不存在，用 order_search 按客户名重查一个有效 ID」），只陈述现象会让对方原样重试或直接放弃。其他异常只落日志、返回通用提示，Agent 看不到原因。
+8. 身份只从 `ctx.user` 读；权限与行级过滤留在 Service。工具类作为业务模块 provider 注册，单例——请求态（当前用户、本次入参、游标）只放方法内的局部变量，写进类字段会在并发请求间串号。
+9. 工具名 = `prefix + 方法名`，匹配 `^[A-Za-z0-9_.-]{1,128}$`，全应用唯一；用 `域_动作`。
+10. 界面源码只放 `server/mcp/ui/<entry>/`，TS 与 ESLint 配置从 `$SKILL_DIR/assets/` 拷、不手写（见 `$SKILL_DIR/references/mcp-apps.md`）。用 `@McpUiResource` + `readMcpUiTemplate('<entry>')` 下发，工具用 `ui: { resourceUri }` 关联。
+11. 新增、改名、删除工具后同步改对应的 `server/mcp/skills/<name>/SKILL.md`；frontmatter 的 `name` 必须等于目录名。
+
+## 禁止
+
+- 从入参接收用户 ID、token、连接串——身份来自网关，入参里的身份可伪造。
+- 自己拼一个 `x-larkgw-suda-webuser` 头来让调用通过——SDK 会把它当真实用户，写工具会以这个身份落库、发通知。
+- 把 `requireUser` 设为 `false` 绕开身份检查——SDK 只是跳过检查，方法照样执行，`ctx.user.userId` 是 undefined，跟着 `ctx.user.userId!` 一路进 Service 的权限过滤。
+- 服务端 import `server/mcp/ui/` 里的源码，或界面 import `client/`、`server/` 里的业务代码、工具类、Node 模块——子构建的边界检查直接报错，服务端只经 `readMcpUiTemplate` 读构建产物。
+- 界面里存凭证、直连业务系统——沙箱 iframe 是独立 origin，用户登录态带不进来；数据走宿主转发的工具调用。
+- `McpToolError.data` 与 `structuredContent` 里放密钥、内部连接信息——两者原样进 Agent 上下文。
+- 自己实现 MCP 协议、JSON-RPC、`/mcp` 路由、凭证校验——SDK 与网关已做，重复实现会与网关映射冲突。
+
+## 交付前核对
+
+1. `list_tools` 与源码里的工具、资源一一对应。
+2. 每个工具有面向模型的 `description`、四项 `annotations`；写工具有 `outputSchema`。
+3. 每个 `ui.resourceUri` 能 `read_resource` 读到，界面拿到 `structuredContent` 后能渲染；`npx tsc --noEmit -p server/mcp/ui/tsconfig.json` 与 `npx eslint -c eslint.mcp-ui.config.cjs server/mcp/ui` 通过。
+4. `server/mcp/skills/` 下每个业务流程一份 SKILL.md，合起来覆盖全部工具：何时调用、如何选工具、调用顺序、约束、失败处理、界面 URI；目录接口的 `prompts[]` 与目录一一对应。

package/steering/nestjs-react-fullstack/skills_common/mcp-guide/assets/eslint.mcp-ui.config.cjs

@@ -0,0 +1,19 @@
+const tseslint = require('typescript-eslint');
+const globals = require('globals');
+const hooks = require('eslint-plugin-react-hooks');
+const { builtinModules } = require('node:module');
+
+module.exports = tseslint.config({
+  files: ['server/mcp/ui/**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}'],
+  extends: [...tseslint.configs.recommended],
+  languageOptions: { globals: globals.browser },
+  plugins: { 'react-hooks': hooks },
+  rules: {
+    ...hooks.configs.recommended.rules,
+    'no-restricted-globals': ['error', 'process', 'Buffer', '__dirname', '__filename'],
+    'no-restricted-imports': ['error', {
+      paths: [...new Set(builtinModules.flatMap(name => [name, `node:${name.replace(/^node:/, '')}`]))],
+      patterns: ['@client/*', '@server/*', '@/*', '**/client/**'],
+    }],
+  },
+});