@lark-apaas/coding-steering 0.1.57 → 0.1.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.57",
+  "version": "0.1.58",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [

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

@@ -12,6 +12,7 @@ match-template-name: nestjs-react-fullstack
 
 - **优先用 `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` 必须从该字段读出，禁止自己拼接。
+- 上传后的文件还要给后端 AI capability 解析/理解时，前端展示仍用 `download_url`；提交给后端的必须是 `file_path`（以及可用的 `bucket_id`）。后端用 `FileService.createSignedUrl(filePath, 3600)` 或 `fileService.from(bucketId).createSignedUrl(filePath, 3600)` 生成临时 http(s) URL 再传插件。前端不要构造 signed URL；普通展示/下载仍默认用 `download_url`。
 
 # dataloom SDK 文件服务
 
@@ -24,6 +25,7 @@ match-template-name: nestjs-react-fullstack
 - **沙箱 dev 限制**：`uploadFile` 打的 `/app/<appId>/__runtime__/api/v1/storage/object/<bucket>/pre_upload` **在沙箱 dev 下恒 404**，只有发布态可用。这是环境限制不是代码缺陷，按本 skill 写法即为正确，不要为它改代码；开发期要验证上传链路改走接口测试直接打后端接口，或复用库里已有的文件 URL。详见 coding-guide「沙箱 dev 不提供平台 runtime 接口」。
 - 上传成功后，最重要的返回值是 `data.download_url`。需要将此URL保存到你的业务数据库中
 - **⚠️ 场景区分（重要）**：`dataloom.storage` 仅适用于需要持久化存储文件或获取 `download_url` 保存到数据库的场景。如果文件仅作为插件输入（传给 `capabilityClient`），**必须直接传 File/Blob 对象，禁止先走 dataloom 上传再传 URL**；插件调用（capability）不属于 dataloom，详见 plugin-guide
+- **Server 侧 AI capability 边界**：文件已上传并持久化后，若由后端调用 `CapabilityService` 做文档解析/图片理解，不要把前端展示用 `download_url` 当插件入参；把 `file_path` 和 `bucket_id` 传给后端，由后端 `FileService` 签成临时 http(s) URL。
 - **download_url 格式说明**：`download_url` 返回的可能是相对路径（如 `/spark/app/.../storage/object/...`），这是正常行为。**禁止**在前面拼接 `window.location.origin` 或其他域名前缀，平台会自动解析相对路径。直接使用原始值即可。
 - **文件URL**：通过 `generateDownloadUrlFromFilePath` 方法获取文件的链接时，传入的 file_path 必须是从数据库中 `file_attachment` 类型字段读出来的，禁止自己拼接路径。
 
@@ -323,7 +325,7 @@ export default FileUploadDemo;
 
 | 要点 | 说明 |
 |------|------|
-| 上传流程 | `uploadFile(file)` → 取 `data.download_url` → POST 后端保存 |
+| 上传流程 | 展示/下载：`uploadFile(file)` → 取 `data.download_url` → POST 后端保存；后端 AI 解析：同时保存/提交 `data.file_path` 与 `data.bucket_id` 供后端签名 |
 | 文件对象 | 直接传原始 `File`，**禁止**包装或修改文件名 |
 | 组件依赖 | shadcn/ui `Button`/`Card` + `lucide-react` + `sonner` |
 | 请求实例 | 必须用 `axiosForBackend`，禁止 `fetch` |

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

@@ -40,7 +40,9 @@ gate-tools:
 
 **paramsSchema 仅支持 4 种参数类型**：文本 `{ "type": "string" }`、字符串数组 `{ "type": "array", "items": { "type": "string" } }`、图片 `{ "type": "string", "format": "picture" }`、文件 `{ "type": "string", "format": "file" }`，均需带 `description`。
 
-> **文件类参数**：`format` 为 `file` / `picture` / `plugin-file-url` 的字段，Client 侧可直接传 File/Blob（SDK 自动上传）；Server 侧仅支持 URL 字符串。**禁止** Client 侧先经 dataloom 上传拿 URL 再传插件——`download_url` 是内部路径，插件服务端可能无法访问。
+> **文件类参数**：`file` / `picture` / `plugin-file-url` / `plugin-image-url` 字段，Client 侧原始 File/Blob 直接传 `capabilityClient`。已持久化文件/图片由 Server 侧 `CapabilityService` 调 AI 插件时，取 `file_path`（或 `bucket_id + file_path`）用 `FileService.createSignedUrl(filePath, 3600)` / `fileService.from(bucketId).createSignedUrl(filePath, 3600)` 签成临时 http(s) URL 后传入。签名失败要 `warn`，业务状态保持 `failed` / `pending` / `null`，不写成功态。标准 `/app` 或 `/spark/app/.../runtime/api/v1/storage/object/<bucket>/<key>` 是可被平台 resolver 消费的内部路径，但不是 `createSignedUrl` 的 `filePath` 入参；禁止给它拼接 `localhost`、`window.location.origin` 或 `/app/<app_id>`。非标准相对路径、前端展示 URL、非法 data URL 不作稳定入参。
+>
+> **改造已有调用**：检查所有文档和图片插件调用点，统一使用上面的签名 URL。删除下载后转 base64 的旧逻辑。缺少 `file_path` 或签名失败时记录警告，写入 `failed` / `pending` / `null`，并停止调用插件；不得改用原始 URL。完整示例见 [Server 侧已持久化文件进入 AI capability](references/plugin-coding-guide.md#3-server-侧已持久化文件进入-ai-capability)。
 
 ## 可用的 Plugin
 
@@ -271,5 +273,6 @@ const url = `https://${req.hostname}${process.env.CLIENT_BASE_PATH}${routePath}`
 | 流式 chunk 当字符串拼接（`text += chunk`） | chunk 是对象，按 outputSchema 解构：`text += chunk.content \|\| ''` |
 | formValue 用 `{% raw %}["{{input.xxx}}"]{% endraw %}` 包装已是 array 的 paramsSchema 参数 | paramsSchema 为 array 时 formValue 透传 `{% raw %}"{{input.xxx}}"{% endraw %}`，不再包一层数组 |
 | 前端调插件后不保存结果（页面刷新丢失），或为保存结果单独新建 API 端点 | 需持久化时 Server 侧调用直接落库（优先），或 Client 侧调用后立即经**已有** CRUD 接口保存 |
+| Server 侧把非标准相对路径、误拼 origin 的 storage object path、前端展示 URL 或非法 base64 data URL 传给 `file` / `picture` / `plugin-file-url` / `plugin-image-url` 参数 | 已持久化文件用 `file_path` 或 `bucket_id + file_path` 生成 1h 签名 http(s) URL 后再传；标准 storage object path 原样经过平台 resolver 时可消费，但不能直接作为 `createSignedUrl` 的 `filePath` |
 | 创建了 PluginInstance 但只建不调 | CREATE 后必须接 `get_plugin_ai_json` → 生成调用代码 → 集成业务逻辑 |
 | 插件返回值 `as any` 直接取字段 | 按 outputSchema 生成 TypeScript interface |

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

@@ -332,7 +332,70 @@ 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`。`createSignedUrl` 接收的是 bucket 内的 `file_path`，不要把完整的 storage object path 直接传入。标准 `/app` 或 `/spark/app/.../runtime/api/v1/storage/object/<bucket>/<key>` 原样经过平台 resolver 时可以消费；禁止给它拼接 `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;
+};
+
+async function createTemporaryFileUrl(
+  fileService: FileService,
+  file: StoredFileRef,
+): Promise<string | null> {
+  if (!file.file_path) return null;
+
+  try {
+    if (file.bucket_id) {
+      return await fileService
+        .from(file.bucket_id)
+        .createSignedUrl(file.file_path, 3600);
+    }
+    return await fileService.createSignedUrl(file.file_path, 3600);
+  } 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,
+    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 作为备用值传给插件。
+- 缺少 `file_path` 或签名失败时记录警告，写入 `failed` / `pending` / `null`，并停止调用插件。
+
+#### 4. 调用示例
 
 服务端 `CapabilityExecutor` 的**三个方法全都没有泛型参数**（`@lark-apaas/nestjs-capability`）：
 
@@ -366,11 +429,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

@@ -24,10 +24,12 @@ match-template-name: nestjs-react-fullstack
 
 | 方法 | 说明 | 返回值 |
 |------|------|--------|
-| `upload(file, options?)` | 上传文件 | `FileMeta` |
-| `download(path)` | 下载文件（≤50MB） | `FileDownloadBuilder` |
-| `remove(filePaths)` | 删除文件 | `RemoveResponse` |
-| `getFileMetadata(filePath)` | 获取文件元信息 | `FileMeta` |
+| `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
 
@@ -123,10 +125,30 @@ const { content, metadata } = await this.fileService
   .asStream();
 
 // 不推荐：Blob 下载（限制 50MB，会将整个文件加载到内存）
-const { content, metadata } = await this.fileService.download(downloadURL);
-```
-
-### 3. 删除文件
+const { content, metadata } = await this.fileService.download(downloadURL);
+```
+
+### 3. 生成临时签名 URL
+
+服务端把应用存储中的文件/图片传给 AI capability（如 `ai-doc-parser`、`ai-image-understanding` 或 `plugin-file-url` / `plugin-image-url` 入参）时，不要把 `downloadURL`、前端展示 URL、非标准相对路径或 base64 data URL 当稳定入参。优先用数据库保存的 `file_path`，必要时带上 `bucket_id`，生成临时 http(s) 签名 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. 删除文件
 
 **入参：**
 
@@ -146,7 +168,7 @@ const result = await this.fileService.remove([fileMeta.downloadURL]);
 const result = await this.fileService.remove(['file1.pdf', 'file2.png']);
 ```
 
-### 4. 获取文件元信息
+### 5. 获取文件元信息
 
 **入参：**
 
@@ -170,8 +192,9 @@ const meta = await this.fileService.getFileMetadata('file.pdf');
 
 | 错误 | 正确做法 |
 |------|----------|
-| 直接 `await download()` 导致内存溢出 | 始终使用 `.asStream()` 流式下载 |
-| 忘记设置 `contentType` 导致浏览器无法预览 | 上传时明确指定 `contentType` |
+| 直接 `await download()` 导致内存溢出 | 始终使用 `.asStream()` 流式下载 |
+| 把 `download()` 结果或前端 `downloadURL` 当作 AI capability URL 入参 | 用 `createSignedUrl(filePath, 3600)` 生成临时 http(s) URL 后再传插件 |
+| 忘记设置 `contentType` 导致浏览器无法预览 | 上传时明确指定 `contentType` |
 | 直接 `new FileService()` 手动实例化 | 通过 NestJS DI 注入 `FileService` |
 | 在异步回调中调用 `download()` 导致上下文丢失 | 在请求处理函数中立即调用，SDK 内部已处理上下文捕获 |
 | 删除时传单个字符串 | `remove()` 参数为 `string[]` 数组 |

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

@@ -42,6 +42,8 @@ lark-cli apps --help 2>&1 | grep -q '+plugin-install' && echo "READY" || echo "M
 | 插件实例配置位置 | `server/capabilities/<instance_id>.json`（默认全栈应用）。见「配置目录」段 |
 
 > **capabilityClient 导入警告**：`capabilityClient` 是从 `@lark-apaas/client-toolkit` 直接导入的独立对象，**不是**从 `getDataloom()` 上获取的。正确且唯一的方式：`import { capabilityClient } from '@lark-apaas/client-toolkit'`。
+> **文件类参数**：Client 侧原始 `File` / `Blob` 直接传 `capabilityClient`。已持久化文件/图片由 Server 侧 `CapabilityService` 调 AI 插件时，取 `file_path`（或 `bucket_id + file_path`）用 `FileService.createSignedUrl(filePath, 3600)` / `fileService.from(bucketId).createSignedUrl(filePath, 3600)` 签成临时 http(s) URL 后传入。标准 `/app` 或 `/spark/app/.../runtime/api/v1/storage/object/<bucket>/<key>` 是可被平台 resolver 消费的内部路径，但不是 `createSignedUrl` 的 `filePath` 入参；禁止给它拼接 `localhost`、`window.location.origin` 或 `/app/<app_id>`。非标准相对路径、前端展示 URL、非法 data URL 不作稳定入参。签名失败要 `warn`，业务状态保持 `failed` / `pending` / `null`，不写成功态。
+> **改造已有调用**：检查所有文档和图片插件调用点，统一使用上面的签名 URL。删除下载后转 base64 的旧逻辑。缺少 `file_path` 或签名失败时记录警告，写入 `failed` / `pending` / `null`，并停止调用插件；不得改用原始 URL。
 
 ## Plugin 代码编写指南
 
@@ -567,6 +569,7 @@ npx @lark-apaas/miaoda-cli plugin list --id <instance_id>
 | Mock `capabilityClient` 返回值 | 必须真实调用 |
 | 通过 `getDataloom().capability` 调用插件 | `capabilityClient` 是独立导入 |
 | Client 侧先通过 dataloom 上传文件再传给插件 | 直接传 File/Blob 对象 |
+| Server 侧把非标准相对路径、误拼 origin 的 storage object path、前端展示 URL 或非法 base64 data URL 传给文件/图片参数 | 已持久化文件用 `file_path` 或 `bucket_id + file_path` 生成 1h 签名 http(s) URL 后再传；标准 storage object path 原样经过平台 resolver 时可消费，但不能直接作为 `createSignedUrl` 的 `filePath` |
 | 用正则/字符串解析处理 AI 输出 | 用 `ai-text-to-json` / `ai-image-to-json` |
 | 认为 `ai-doc-parser` 能直接输出结构化 JSON | 只输出纯文本，需链式调用 `ai-text-to-json` |
 | 图片提取结构化用两步链 | 优先 `ai-image-to-json` 单步直达 |