@lark-apaas/coding-steering 0.1.0-alpha.1 → 0.1.0

package/package.json

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

package/steering/vite-react/skills/plugin-guide/SKILL.md

@@ -0,0 +1,498 @@
+---
+name: plugin-guide
+description: "Use when 需要：(1) 创建或管理 PluginInstance 插件实例，(2) 调用 capabilityClient 生成插件调用代码，(3) 理解 Plugin、PluginInstance、PluginInstanceAIJson 三层关系，(4) 使用 get_plugin_ai_json 或 plugin_instance 工具。触发词：插件, plugin, 飞书消息, 飞书群组, 多维表格, AI生文, AI生图, 图片理解, capabilityClient, pluginInstance"
+steering: true
+steering-topic: plugin_guide
+---
+
+# Plugin 集成指南
+
+飞书/AI 新版插件集成规范与 Plugin 链路指南。支持的能力包括：飞书多维表格/Base操作（插入记录、更新记录、删除记录、查询记录）、发送飞书消息、创建飞书群组、AI智能生文、AI智能生图、AI图片理解等。本文档介绍插件实例配置、运行时投影（get_plugin_ai_json）的用法，以及 `capabilityClient` 调用入口；具体业务能力需以实际 available_plugin_instances 与对应 plugin.ai.json 为准。
+
+## ⚠️ 铁律：禁止 Mock 插件调用
+
+**当 AGENTS.md 包含「插件规划」时，所有规划的插件必须通过 `plugin_instance` 工具创建并通过 `capabilityClient` 真实调用。**
+
+| 禁止 | 正确 |
+|------|------|
+| ❌ `setTimeout` + 硬编码数据模拟 AI 返回 | ✅ `(capabilityClient as any).load(id)` → `(executor as any).call(actionKey, input)` |
+| ❌ `picsum.photos` / 随机图片替代 AI 生图 | ✅ `(capabilityClient as any).load(id)` → `(executor as any).call('textToImage', {...})` |
+| ❌ 注释掉 `capabilityClient` import 用 Mock 函数 | ✅ 真实 import 并调用（详见调用规范） |
+| ❌ AGENTS.md 规划了插件但 `shared/capabilities/` 为空 | ✅ 每个规划的插件都有对应 JSON 文件 |
+| ❌ `Math.random()` 替代 AI 分类/评分/推荐结果 | ✅ 使用插件返回值中的实际字段 |
+| ❌ `logger.log(input); return { success: true }` 占位通知 | ✅ 通过 `capabilityClient` 真实调用 send-feishu-message |
+| ❌ `const PRESET_DATA = [...]` 替代插件调用 | ✅ 调用插件获取真实结果 |
+
+> **与 Mock 展示数据的区别**：design_agent prompt 中的 "Mock 数据仅用于无附件的 prototype" 指的是表格示例行、卡片占位文本等**展示数据**。AI 生文/生图/翻译/结构化等**插件能力不属于 Mock 数据范围**，必须真实调用。
+
+## Quick Reference
+
+| 操作 | 方式 |
+|------|------|
+| 创建/更新 PluginInstance | 调用 `plugin_instance` 工具（禁止手动改文件） |
+| 获取运行时投影 | 调用 `get_plugin_ai_json(pluginInstanceId)` |
+| 非流式调用 | `const ex = (capabilityClient as any).load(id); await (ex as any).call(actionKey, input)` |
+| 流式调用 | `const ex = (capabilityClient as any).load(id); for await (const c of (ex as any).callStream(actionKey, input)) {}` |
+| capabilityClient 导入 | `import { capabilityClient } from '@lark-apaas/client-toolkit-lite'` |
+| 配置存储位置 | `shared/capabilities/<plugin_instance_id>.json` |
+
+> **capabilityClient 导入警告**：`capabilityClient` 是从 `@lark-apaas/client-toolkit-lite` 直接导入的独立对象，**不是**从 `getDataloom()` 上获取的。错误写法：`const dataloom = await getDataloom(); (dataloom as any).capability` — 这样写不会工作。正确且唯一的方式：`import { capabilityClient } from '@lark-apaas/client-toolkit-lite'`。
+>
+> **调用规范：双重 `as any` 强转**。lite 包暴露的 `capabilityClient` 类型是泛化合同（actionKey / input / output 都依赖运行时 `pluginInstance.ai.json`），直接调用编译器无法约束 schema。vite-react 项目里**canonical 写法是拆两步、各加一次 `as any`**：
+>
+> ```ts
+> import { capabilityClient } from '@lark-apaas/client-toolkit-lite';
+>
+> const executor = (capabilityClient as any).load('ai_image_generation_quality_1');
+> const result = await (executor as any).call('textToImage', {
+>   prompt: prompt.trim(),
+> });
+> ```
+>
+> 下方所有代码示例都遵守这个模式。链式 `(capabilityClient as any).load('id').call('action', input)` 也合法（一次 cast 让整条链路推导为 `any`），但拆步骤更便于打日志、错误处理和复用 executor。
+
+## Plugin 代码编写指南
+
+以下场景**必须**先读取 `references/plugin-coding-guide.md` 再编写代码：
+
+- 编写 `capabilityClient` 调用代码时（含导入路径、调用方式）
+- 处理流式输出（`outputMode = stream`），包括多插件并行流式、单插件 JSON 流式解析
+- 需要根据 `outputMode` 选择 `call()` 或 `callStream()` 时
+
+## 飞书多维表格（feishu-bitable）编码指南
+
+以下场景**必须**先读取 `references/table.md` 再编写代码：
+
+- 编写飞书多维表格 CRUD 代码时（searchRecords / getRecord / batchAddRecords / batchUpdateRecords / deleteRecords）
+- 需要了解 BizType 字段类型、读写格式差异时
+- 构建搜索过滤条件（filter / conditions）时
+- 使用多维表格相关 UI 组件（人员展示、超链接、单/多选下拉 等；vite-react 用 shadcn-ui 拼装）时
+
+## Plugin 链式调用（Plugin Chain）
+
+很多业务场景需要多个插件串联完成，**禁止用正则/字符串解析替代 AI 插件做结构化输出处理**（包括提取和生成场景）。
+
+### 插件能力分类
+
+| 类别 | 插件 | 输入→输出 |
+|------|------|----------|
+| **内容提取** | `ai-doc-parser` | 文档(PDF/DOC/PPTX/XLSX/CSV等9种)→纯文本 |
+| **内容提取** | `ai-speech-to-text` | 音频→纯文本 |
+| **内容提取** | `ai-image-understanding` | 图片→文本描述（流式，适合理解/问答） |
+| **结构化提取** | `ai-text-to-json` | 文本→结构化 JSON（最多20字段） |
+| **结构化提取** | `ai-image-to-json` | 图片→结构化 JSON（最多20字段，**单步直达**） |
+| **结构化提取** | `ai-categorization` | 文本→分类标签 |
+| **内容生成** | `ai-text-generate` | 提示词→文本（流式） |
+| **内容生成** | `ai-text-to-image` | 文字描述→图片 |
+| **内容生成** | `ai-text-summary` | 长文本→摘要（流式） |
+| **内容生成** | `ai-translate` | 文本→翻译（12种语言，流式） |
+| **内容生成** | `ai-search-summary` | 搜索词→网页摘要（流式） |
+| **内容生成** | `ai-speech-synthesis` | 文本→语音（44+音色） |
+| **图片处理** | `ai-image-matting` | 图片→抠图/去背景/去水印 |
+| **图片处理** | `ai-background-replace` | 主体图+背景→合成图 |
+| **图片处理** | `ai-image-to-image` | 参考图(1-5张)+描述→编辑/风格转换 |
+| **图片处理** | `ai-image-compare` | 两张图→对比分析（流式） |
+| **外部服务** | `feishu-bitable` | CRUD 飞书多维表格（5个Action） |
+| **外部服务** | `send-feishu-message` | 发送飞书卡片消息 |
+| **外部服务** | `feishu-group-create` | 创建飞书群组 |
+
+### 决策树：选择单步还是链式
+
+```
+输入是什么？
+├── 文档文件 → 必须先用 ai-doc-parser 提取文本，再根据目标选择下游插件：
+│   ├── 需要结构化数据 → ai-doc-parser → ai-text-to-json （2步链）
+│   ├── 需要摘要 → ai-doc-parser → ai-text-summary
+│   ├── 需要翻译 → ai-doc-parser → ai-translate
+│   ├── 需要分类 → ai-doc-parser → ai-categorization
+│   └── 仅需原文 → ai-doc-parser（单步）
+├── 图片 → ⚠️ 注意选择正确的插件：
+│   ├── 提取结构化数据（发票/名片/证件等）→ ai-image-to-json（⭐ 单步直达！）
+│   ├── 理解内容后提取结构化数据 → ai-image-understanding → ai-text-to-json（2步链）
+│   ├── 抠图后换背景 → ai-image-matting → ai-background-replace（2步链）
+│   └── 理解/问答/编辑/对比 → 对应单插件即可
+├── 音频
+│   ├── 需要结构化数据 → ai-speech-to-text → ai-text-to-json（2步链）
+│   └── 仅需文字 → ai-speech-to-text（单步）
+└── 纯文本
+    ├── 需要结构化数据 → ai-text-to-json（⭐ 单步直达！）
+    └── 摘要/翻译/分类/生成
+        ├── 输出包含多个独立字段（标题+正文+评分等）
+        │   → 拆成多个独立插件并行调用（⭐ 优先）或用 ai-text-to-json
+        │   → ⛔ 禁止用 ai-text-generate + 正则/split 解析多字段
+        └── 输出为单一文本（仅展示，不需解析）→ ai-text-generate
+```
+
+### 常见 Plugin Chain 组合
+
+| 链路 | 插件组合 | 场景举例 |
+|------|---------|---------|
+| 文档→结构化数据 | `ai-doc-parser` → `ai-text-to-json` | 简历PDF→员工档案、合同→结构化条款 |
+| 文档→摘要 | `ai-doc-parser` → `ai-text-summary` | 研报PDF→摘要、长文档→概要 |
+| 文档→翻译 | `ai-doc-parser` → `ai-translate` | 英文论文→中文翻译 |
+| 文档→分类 | `ai-doc-parser` → `ai-categorization` | 工单文档→类型标签 |
+| 图片→结构化数据 | `ai-image-to-json`（**单步**） | 发票→金额/日期、名片→联系人 |
+| 图片理解→结构化 | `ai-image-understanding` → `ai-text-to-json` | 复杂图表→数据、截图→字段 |
+| 音频→结构化数据 | `ai-speech-to-text` → `ai-text-to-json` | 会议录音→待办事项 |
+| 音频→翻译 | `ai-speech-to-text` → `ai-translate` | 外语录音→中文 |
+| 抠图→换背景 | `ai-image-matting` → `ai-background-replace` | 商品图→电商主图 |
+| 生成内容→通知 | `ai-text-generate` → `send-feishu-message` | AI生成报告→发送飞书通知 |
+| 提取数据→入库 | `ai-text-to-json` → `feishu-bitable` | 文本→结构化→写入多维表格 |
+
+### Plugin Chain 调用模式
+
+```typescript
+// 示例：文档 → 结构化数据（2步链）
+// Step 1: 内容提取（注意：fileUrl 通常为数组类型，必须按 inputSchema 传入）
+const docParser = (capabilityClient as any).load('doc_parser_instance');
+const rawResult = await (docParser as any).call('parseDocToMarkdown', { fileUrl: [docUrl] });
+
+// Step 2: AI 结构化提取
+const jsonExtractor = (capabilityClient as any).load('text_to_json_instance');
+const structured = await (jsonExtractor as any).call('textToJson', { text: rawResult.content });
+
+// Step 3: 使用结果（填入表单 / 写入数据库 / 写入多维表格等）
+```
+
+> **Client 侧提示**：`capabilityClient` 支持直接传 File/Blob 对象作为文件参数，无需先上传到 dataloom 获取 URL：
+>
+> ```typescript
+> // Client 侧：直接传 File 对象，SDK 自动处理上传
+> const docParser = (capabilityClient as any).load('doc_parser_instance');
+> const rawResult = await (docParser as any).call('parseDocToMarkdown', { fileUrl: [file] }); // file 为 File/Blob 对象
+> ```
+>
+> ⚠️ `capabilityClient` 支持此能力，SDK 自动处理文件上传。
+
+### 创建结构化提取 PluginInstance 的关键要求
+
+创建 `ai-text-to-json` 或 `ai-image-to-json` 类型的 PluginInstance 时：
+
+1. **必须一次性定义所有需要提取的字段**（参考数据库 schema / 表单定义 / UI 设计），宁多勿漏
+2. 字段类型仅支持 String / Number / Boolean，最多 20 个字段
+3. 先调用 `get_plugin_ai_json` 确认上游插件的 `outputSchema`，确保输入格式正确
+4. 图片→结构化数据场景，优先使用 `ai-image-to-json`（单步），避免不必要的链式调用
+
+## 核心概念
+
+新版链路中，**Plugin（插件）**、**PluginInstance（插件实例配置）**、**PluginInstanceAIJson（运行时投影：pluginInstance.ai.json）** 的关系如下：
+
+- **Plugin（插件）**：底层承载单元，包含插件元信息与表单定义（form.schema）。模型侧只感知插件及其表单字段，不感知插件内部实现细节。
+- **PluginInstance（插件实例配置）**：基于某个 Plugin 的表单做"业务封装"，以 **单文件 JSON** 的形式存储（每个插件实例一个文件，语义化 id）。
+  - 通过 `paramsSchema` 暴露业务入参
+  - 通过 `formValue` 将业务入参映射到插件表单字段（可常量或引用 `{{input.xxx}}`）
+- **PluginInstanceAIJson（pluginInstance.ai.json）**：工程转化层产物，是 pluginInstance 的**运行时投影 / 调用合同（Runtime Spec）**。
+  - 包含插件定位信息、actions 入口列表、input/output schema、outputMode、readme 等
+  - Code Agent 在生成**调用代码**前，必须读取它作为权威依据（使用 `capabilityClient` 调用）
+
+### 插件 Plugin
+
+插件是插件实例的承载单元，包含：
+ • 插件元信息（tags/name/description/version/...）
+ • 插件表单定义（form.schema），用于描述"这个插件需要哪些表单字段"。
+重要：模型侧只感知插件与其表单 schema，不感知插件内部实现（如 Action的实现、API 细节等）。
+
+Plugin 的具体内容以JSON格式给出，例如：
+
+```json
+{
+  "name": "plugin-key",        // 插件唯一标识
+  "displayName": "飞书群组创建", // 展示名称
+  "version": "1.0.0",
+  "form": {
+    "schema": {                 // 插件表单定义（PluginInstance 的 formValue 映射到此）
+      "type": "object",
+      "properties": {
+        "group_name": { "type": "string", "description": "群组名称" },
+        "members": { "type": "array", "description": "群成员id列表", "items": { "type": "string" } }
+      },
+      "required": ["group_name", "members"]
+    }
+  }
+}
+```
+
+### 插件实例 PluginInstance
+
+开发框架内置 `plugin` 工具，用于创建和管理基于 **Plugin（插件表单）** 的业务插件实例（PluginInstance）。
+
+**重要说明**：
+
+- PluginInstance 的配置以"单文件 JSON"形式存储在 `shared/capabilities/`（每个插件实例一个文件，逻辑上对应 shared/capabilities/<id>.json）。
+- 运行时调用前，Code Agent 需要通过 get_plugin_ai_json 获取对应插件实例的 pluginInstance.ai.json，再基于其中的 actions/schema/outputMode 生成调用代码。
+- 运行时调用入口统一走 SDK：`(capabilityClient as any).load(pluginInstanceId)` 拿到 executor，再 `(executor as any).call(actionKey, input)`（流式用 `callStream`，详见 SKILL.md 头部"调用规范"）
+
+PluginInstance 的配置以 JSON 形式输出，例如：
+
+```json
+{
+  "id": "create_feishu_group",       // 全局唯一语义化 ID
+  "pluginKey": "@xxx/feishu-group",  // 绑定的 Plugin name
+  "pluginVersion": "1.0.0",
+  "name": "任务创建时自动创建飞书群组",
+  "description": "根据任务名称自动生成飞书群组并设置初始成员",
+  "paramsSchema": {                  // 对外暴露的业务入参（仅 string / array<string> / picture / file）
+    "type": "object",
+    "properties": {
+      "group_name": { "type": "string", "description": "群组名称" },
+      "members": { "type": "array", "items": { "type": "string" }, "description": "成员ID列表" }
+    },
+    "required": ["group_name"]
+  },
+  "formValue": {                     // 映射到 Plugin form.schema 字段（常量或 {{input.xxx}}）
+    "group_name": "{{input.group_name}}",
+    "members": "{{input.members}}"
+  }
+}
+```
+
+**注意**paramsSchema 支持以下 4 种参数类型,需要按下面规定的格式进行填充：
+
+1. **文本** - 单行或多行文本输入
+
+   ```json
+   {
+     "type": "string",
+     "description": "文本参数描述"
+   }
+   ```
+
+2. **数组** - 字符串数组（如 ID 列表、标签列表等）
+
+   ```json
+   {
+     "type": "array",
+     "description": "数组参数描述",
+     "items": {
+       "type": "string",
+       "description": "数组元素描述"
+     }
+   }
+   ```
+
+3. **图片** - 图片资源（需指定 format 为 picture）
+
+   ```json
+   {
+     "type": "string",
+     "format": "picture",
+     "description": "图片参数描述"
+   }
+   ```
+
+4. **文件** - 文件资源（需指定 format 为 file）
+
+   ```json
+   {
+     "type": "string",
+     "format": "file",
+     "description": "文件参数描述"
+   }
+   ```
+
+> **注意**：`format: "file"` 和 `format: "picture"` 的字段支持直接传入 File/Blob 对象，`capabilityClient` SDK 会自动处理上传。
+>
+#### PluginInstanceAIJson（运行时投影 / 工程转化层产物：pluginInstance.ai.json）
+
+pluginInstance.ai.json 是从 PluginInstance 配置派生出的运行时插件实例说明（Runtime Spec），用于 Code Agent 动态生成调用代码。
+它包含：
+ • 插件实例元数据（id/pluginKey/pluginVersion/name/description）
+ • 可执行入口列表 actions[]（每个入口包含 key/inputSchema/outputSchema/outputMode）
+ • 详细说明 readme
+ • type：单入口/多入口（single_action | multi_action）
+
+**重要**：模型不能自行猜测某个插件实例有哪些 action、入参/出参结构；在生成调用代码前必须通过工具读取该 pluginInstance.ai.json。
+
+PluginInstanceAIJson 的配置以 JSON 形式输出，例如：
+
+  ```json
+{
+  "type": "multi_action", // 插件实例类型：single_action 表示仅 1 个 action；multi_action 表示多个 action（调用前需选择 actionKey）
+  "id": "********", // PluginInstance 的唯一标识（插件实例ID），用于后续通过 get_plugin_ai_json 获取详情、以及运行时调用定位插件实例
+  "pluginKey": "@*******", // 该插件实例绑定的插件ID（运行时用于定位具体插件实现）
+  "pluginVersion": "1.0.0", // 插件版本号（用于版本锁定/兼容性，避免插件升级导致 schema 或行为变化）
+  "name": "******", // 插件实例名称（面向人/模型展示，用于检索与选择插件实例）
+  "description": "...", // 插件实例描述（说明该插件实例解决什么业务问题、适用场景，用于帮助模型理解意图）
+  "actions": [ // 可执行入口列表
+    {
+      "key": "insertRecords", // action 标识（调用时作为 actionKey 使用）：插入记录/新增数据
+      "inputSchema": {}, // 该 action 的入参 JSON Schema（生成调用参数时必须严格遵循）
+      "outputSchema": {}, // 该 action 的出参 JSON Schema（解析返回值时按此结构读取字段）
+      "outputMode": "unary" // 输出模式：unary=一次性返回；stream=流式返回（决定代码生成的处理方式）
+    },
+    {
+      "key": "updateRecords", // action 标识：更新记录/修改数据
+      "inputSchema": {}, // 更新操作需要的入参结构定义（JSON Schema）
+      "outputSchema": {}, // 更新操作返回结构定义（JSON Schema）
+      "outputMode": "unary" // 输出模式（同上）
+    },
+    {
+      "key": "deleteRecord", // action 标识：删除记录（注意：有的插件实例会是 deleteRecords 表示批量删除）
+      "inputSchema": {}, // 删除操作需要的入参结构定义（JSON Schema）
+      "outputSchema": {}, // 删除操作返回结构定义（JSON Schema）
+      "outputMode": "unary" // 输出模式（同上）
+    }
+  ],
+  "readme": "", // 插件实例使用说明文档（可能包含特殊字段解释、限制、示例代码；优先参考它来生成调用逻辑）
+  "createdAt": 1764234360374, // 插件实例创建时间戳（毫秒），用于变更追踪/缓存刷新
+  "updatedAt": 1764234360374 // 插件实例更新时间戳（毫秒），用于变更追踪/缓存刷新
+}
+  ```
+
+## 可用的 Plugin
+
+```
+{{available_plugins}}
+```
+
+说明：先从可用的 PluginInstance 进行选择，如果无法满足需求，看可用的 Plugin，如果有满足的插件，调用插件生成工具进行生成，如果没有，直接拒答。
+
+## 可用的 PluginInstance
+
+```
+{{available_plugin_instances}}
+```
+
+### 使用方式
+
+1. **创建/修改 PluginInstance（配置层）**：调用 `plugin_instance` 工具生成/更新单文件 PluginInstance JSON（基于插件表单封装）。
+2. **查询已有 PluginInstance（配置层）**：优先使用可用的 PluginInstance；如仍需核对细节，再读取对应插件实例配置(调用'get_plugin_ai_json')。
+3. **生成运行时代码（调用层）**：
+   - 已确定使用某个 PluginInstance 后，先调用 `get_plugin_ai_json` 获取该插件实例的运行时投影（pluginInstance.ai.json）
+   - 基于返回的 `actions[].key/inputSchema/outputSchema/outputMode` 动态生成调用代码（使用 `capabilityClient`）
+   - 仔细阅读返回的 readme，必须严格遵循里面制定的规则
+
+### 典型场景示例
+
+- **消息通知类**：封装"发送飞书消息"相关插件为业务插件实例
+- **群组管理类**：封装"创建飞书群组"相关插件为业务插件实例
+- **AI 生成类**：封装"AI 生文/生图/图片理解"相关插件为业务插件实例
+
+### 使用限制
+
+- PluginInstance 必须通过 `plugin_instance` 工具创建/更新，不支持 agent 直接手改 `shared/capabilities/` 下的配置文件
+- 调用前必须通过 `get_plugin_ai_json` 获取权威 schema，禁止猜测入参/出参结构
+- PluginInstance 配置信息存储在 `shared/capabilities/` 目录
+- 运行时调用统一走 SDK，不再为每个插件实例预生成固定的 call 文件：`(capabilityClient as any).load(capabilityId)` → `(executor as any).call(actionKey, input)`（流式用 `callStream`）
+
+## PluginInstance 生成约束
+
+1. 非常**注意**，必须通过调用 `plugin_instance`工具 来创建、更新 PluginInstance，**绝对禁止**使用 `multi_edit`工具 和 `write`工具 来直接修改 `shared/capabilities/` 目录下的内容。
+2. PluginInstance 配置以单文件形式存储在 shared/capabilities/ 目录下（逻辑上为 shared/capabilities/<plugin_instance_id>.json），不再维护集中式的 capabilities.json。
+3. 用户可以手动修改 `shared/capabilities/<plugin_instance_id>.json` 文件中的配置，且用户修改完配置后一定会通知你（例如告诉你'刚刚更新了PluginInstance配置'），此时你需要根据用户修改后的配置，通过调用（必须，禁止使用其他工具来操作 PluginInstance）`plugin_instance`工具 来更新PluginInstance。
+4. 调用侧在生成调用代码前，**必须**通过 get_plugin_ai_json 获取该插件实例的运行时投影（plugin_Instance.ai.json），并以其作为入参/出参 schema 与 action 列表的唯一权威依据，禁止自行猜测。
+5. 若插件表单字段中包含 card_content 且其语义为飞书消息卡片，则生成/更新 PluginInstance 配置时，formValue.card_content 必须是 JSON Object，不能是转义字符串；并且卡片 DSL 的最后两个元素必须固定。
+
+---
+
+## GetPluginInstanceAIJson 工具使用指南
+
+`get_plugin_ai_json(pluginInstanceID)` — 读取插件实例的运行时投影，返回结构参见上文 PluginInstanceAIJson 示例。
+
+### 何时调用
+
+| 场景 | 是否调用 |
+|------|---------|
+| 已选定插件实例，需生成调用代码 | **必须调用** |
+| 需确认 actions / inputSchema / outputSchema / outputMode | **必须调用** |
+| 创建或修改 PluginInstance 配置 | 不需要（用 `plugin_instance` 工具） |
+| 只需插件实例列表概览 | 不需要（已在上下文中提供） |
+
+### 消费返回数据要点
+
+1. 根据 `actions[].key` 选择 actionKey，严格按 `inputSchema` 构造入参、按 `outputSchema` 解析出参
+2. `type = single_action` 时只有一个 action；`multi_action` 时需选择合适的 actionKey
+3. **务必阅读 `readme` 字段**，可能包含特殊参数说明、使用限制和示例代码
+4. 注意 `inputSchema` 中的类型定义（特别是 `type: array` 的字段，必须传数组而非字符串）
+
+## 开发流程要求
+
+### 第一步：检查现有 PluginInstance（复用优先）
+
+1. 用户描述需求后，优先基于上下文提供的插件实例列表检索是否已存在可复用插件实例。
+1. 若存在候选插件实例但你无法确认其是否满足需求，必须调用 `get_plugin_ai_json` 获取该插件实例的运行时投影（pluginInstance.ai.json），根据 `actions[].key` / `actions[].inputSchema / outputSchema` / `actions[].outputMode` 判断是否可复用以及如何调用。
+1. 禁止按旧链路去读取/维护 `shared/capabilities/capabilities.json` 来做复用判断。
+
+> 结论：**复用判断以插件实例列表 + get_plugin_ai_json 为准**，禁止猜测 action、入参/出参、输出模式。
+
+### 第二步：决策
+
+- 如果找到匹配的插件实例：直接进入「第三步：代码调用」，严禁为了"更贴合需求"而随意新建重复的插件实例。
+- 如果不存在合适插件实例，则基于上下文提供的插件列表进行判断：
+  - 需要创建：如果插件列表有更贴合需求的插件，调用 `plugin_instance` 工具（operType=CREATE）生成新的单文件 PluginInstance 配置。
+  - 需要调整已有插件实例：调用 `plugin_instance` 工具（operType=UPDATE）更新该插件实例配置。
+  - 其他情况：告知用户该需求目前无法满足
+
+**强制约束**：
+
+- 创建/更新 PluginInstance **必须**通过 `plugin_instance` 工具完成，绝对禁止直接修改 `shared/capabilities/` 下的配置文件。
+- UPDATE 场景严禁修改保护字段：`id / pluginKey / pluginVersion / createdAt`。
+
+### 第三步：生成调用代码
+
+1. **必须**先调用 `get_plugin_ai_json(pluginInstanceId)`
+2. 根据 `actions[].key` 选择正确的 actionKey
+3. 严格按 `inputSchema` 构造入参，严格按 `outputSchema` 解析出参
+4. 根据 `outputMode` 选择调用方式：
+   - `outputMode = unary` → `(executor as any).call(actionKey, input)`
+   - `outputMode = stream` → `(executor as any).callStream(actionKey, input)`（异步迭代）
+
+### 第四步：代码放置位置
+
+调用代码放在 `src/` 目录下的组件/hooks 中（vite-react flat 布局），由用户交互触发。
+
+## 常见错误（必须避免）
+
+| 错误做法 | 正确做法 |
+|---------|---------|
+| 为插件调用创建后端 API 中转 | 直接使用 `capabilityClient` 在前端调用 |
+| 未调用 `get_plugin_ai_json` 就猜测参数 | 先获取 runtime spec，再生成代码 |
+| Mock `capabilityClient` 返回值 | 必须真实调用 |
+| 猜测 actionKey 或参数结构 | 严格按 `get_plugin_ai_json` 返回的 schema |
+| `call()` 调用签名错误：`plugin.call(JSON.stringify({...}))` 或 `plugin.call({...})` | `call()` 第一个参数必须是 actionKey 字符串，第二个参数才是 input 对象：`plugin.call('actionKey', {...})` |
+| 用正则/字符串解析处理 AI 输出（提取或生成场景） | 提取用 `ai-text-to-json` / `ai-image-to-json`；多字段生成拆多插件或用 `ai-text-to-json` |
+| 创建 `ai-text-to-json` / `ai-image-to-json` PluginInstance 时只定义部分字段 | 分析需求中**全部**字段后一次性定义完整（最多20字段） |
+| 认为 `ai-doc-parser` 能直接输出结构化 JSON | `ai-doc-parser` 只输出纯文本，需链式调用 `ai-text-to-json` 做结构化 |
+| 图片提取结构化数据时用 `ai-image-understanding` → `ai-text-to-json` 两步链 | 优先用 `ai-image-to-json` 单步直达（发票/名片/证件等场景） |
+| 未读 `inputSchema` 就假设参数类型（如 string vs array） | 先调用 `get_plugin_ai_json` 查看 `inputSchema`，注意 `type: array` 字段 |
+| 通过 `getDataloom().capability` 或 `(dataloom as any).capability` 调用插件 | `capabilityClient` 是独立导入，不通过 dataloom 访问。dataloom 仅提供 storage 和 service |
+| 调用插件时，先通过 dataloom 上传文件拿 URL 再传给插件 | 可直接传 File/Blob 对象给 `capabilityClient`，SDK 自动处理上传 |
+| 前端调用插件后不保存结果到数据库，导致页面刷新后数据丢失 | 调用插件成功后，必须通过已有 CRUD 接口立即保存结果 |
+| 为保存插件结果单独新建 API 端点（如 `PATCH /api/xxx/ai-analysis`） | 优先复用已有的业务 CRUD 接口（create/update）扩展字段 |
+
+## 业务语义映射约定
+
+用户会用「AI 生文」「AI 生图」「发送飞书消息」等**业务语言**描述需求；这些关键词必须被识别为**待使用或待创建的 PluginInstance**。
+
+开发流程：
+
+1. 收到需求后，先看可用的 PluginInstance 是否有可以直接使用的插件实例
+2. 若有候选但不确定是否满足，调用 `get_plugin_ai_json` 查看其 actions/schema/outputMode 再决策
+3. 若无，立即调用 `plugin_instance` 工具新建
+4. 生成 `capabilityClient` 调用代码
+
+## 插件调用错误处理规范
+
+| 错误类型 | 应对策略 |
+|----------|---------|
+| `InputValidationError` | 修复参数后重试 |
+| `RateLimitError` | 指数退避重试（1s/2s/4s），最多 3 次 |
+| `ExecutionError` | 记录日志 + 降级方案 + 通知用户 |
+| 网络超时 | 重试 + 超时后降级 |
+
+**规则**: (1) 禁止静默吞异常，每个 catch 必须向用户展示错误或触发补偿；(2) 异步调用必须有终态（success/failed），前端不能永远 loading；(3) 通知类插件失败必须有补偿机制。
+
+## 缓存与幂等性
+
+- AI 类插件**没有请求级缓存**。同样输入返回相似结果是 LLM 低 temperature 下的正常行为。
+- **禁止**通过修改业务参数注入 UUID 来"绕缓存"，会污染 AI 输入导致输出包含垃圾文本。
+- 需要不同结果时：调整 temperature、修改 prompt 要求、或使用不同业务上下文。
+
+## 插件参数来源规范
+
+| 类型 | 来源 | 示例 |
+|------|------|------|
+| 业务数据 | DB 查询或前端传入 | 候选人姓名、简历内容 |
+| 运行时配置 | 配置/环境变量/平台 API | 接收人 user_id、阈值 |
+
+**禁止**硬编码运行时配置值（user_id、邮箱等），必须从配置表/平台 API/环境变量获取。

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

@@ -0,0 +1,143 @@
+## PluginInstance 代码编写指南
+
+### 核心原则
+
+**严禁** import ｛ capabilityClient ｝ from '@lark-apaas/client-capability'。
+**唯一指定**的导入方式是 import { capabilityClient } from '@lark-apaas/client-toolkit-lite';
+
+| 场景 | 调用方式 |
+|------|---------|
+| 非流式调用 | `const ex = (capabilityClient as any).load(id); await (ex as any).call(actionKey, input)` |
+| 流式输出场景 | `const ex = (capabilityClient as any).load(id); for await (const c of (ex as any).callStream(actionKey, input)) {}` |
+
+---
+
+### 调用方式
+
+#### 1. 调用前获取权威依据
+
+在为某个插件实例生成调用代码前，必须先通过 `get_plugin_ai_json` 工具获取该插件实例的运行时投影（plugin_Instance.ai.json），并以其中信息为准：
+
+- `actions[].key`：调用时要传的 `actionKey`
+- `actions[].inputSchema / outputSchema`：入参/出参结构
+- `actions[].outputMode`：`unary | stream`（决定调用与结果处理方式）
+
+#### call / callStream 函数签名
+
+```typescript
+.call(actionKey: string, input: object)       // 非流式，返回 Promise<output>
+.callStream(actionKey: string, input: object)  // 流式，返回 AsyncIterable<chunk>
+```
+
+- **第一个参数 `actionKey`**：必须是字符串，值来自 `get_plugin_ai_json` 返回的 `actions[].key`（如 `'sendFeishuMessage'`、`'textGenerate'`）
+- **第二个参数 `input`**：必须是对象，结构符合 `actions[].inputSchema`
+
+vite-react 侧 TS 类型偏泛，调用必须 `as any` 强转两次（一次给 `capabilityClient`，一次给 `load` 返回的 executor）：
+
+```typescript
+import { capabilityClient } from '@lark-apaas/client-toolkit-lite';
+
+const executor = (capabilityClient as any).load('plugin_instance_id');
+
+// ❌ 错误：把参数 JSON.stringify 后当作 actionKey
+(executor as any).call(JSON.stringify({ meeting_title: '...' }));
+// ❌ 错误：漏掉 actionKey，直接传参数对象
+(executor as any).call({ meeting_title: '...' });
+
+// ✅ 正确：第一个参数是 actionKey 字符串，第二个参数是 input 对象
+const result = await (executor as any).call('send_feishu_message', { meeting_title: '...' });
+```
+
+#### 2. 非流式调用（outputMode = "unary"）
+
+```typescript
+import { capabilityClient, logger } from '@lark-apaas/client-toolkit-lite';
+
+const executor = (capabilityClient as any).load('create_feishu_group');
+const result = await (executor as any).call('createGroup', {
+  group_name: '项目讨论群',
+  members: ['user_001', 'user_002'],
+});
+
+logger.info(result);
+```
+
+#### 3. 流式调用（outputMode = "stream"）
+
+##### 流式 chunk 字段速查表（必须遵守）
+
+capabilityClient `callStream` 返回的每个 chunk 是**扁平对象**，字段名与 `outputSchema` 一致。**禁止使用 `chunk.data?.text`、`chunk.choices[0]`、`chunk.message` 等非 capabilityClient 格式。**
+
+| 插件 | chunk 字段 | 正确写法 | 错误写法 |
+|------|-----------|---------|---------|
+| ai-text-generate | `content` | `chunk.content` | ~~`chunk.data?.text`~~ |
+| ai-translate | `translation` | `chunk.translation` | ~~`chunk.content`~~ ~~`chunk.text`~~ |
+| ai-text-summary | `summary` | `chunk.summary` | ~~`chunk.content`~~ ~~`chunk.data?.text`~~ |
+| ai-image-understanding | `content` | `chunk.content` | ~~`chunk.data?.text`~~ |
+| ai-search-summary | `content` | `chunk.content` | ~~`chunk.data?.text`~~ |
+
+> **⚠️ 同一应用多个页面调用同一插件时，所有页面必须使用一致的 chunk 字段名。** parallel_write 并发生成多页面时尤其注意。
+
+##### 场景判断与推荐方案
+
+| 场景 | 特征 | 推荐度 |
+|-----|------|-------|
+| **多插件并行流式** | 多个插件各返回单一输出，并行调用 |  **优先推荐** |
+| **单插件 JSON 流式解析** | 单插件返回结构化 JSON，需边接收边解析 | ⚠️ 仅在必要时 |
+
+**核心原则**：在插件设计阶段按「原子化拆解」拆分，避免单插件返回多字段 JSON。
+
+##### 推荐：多插件并行流式
+
+适用于需求涉及多种输出（标题、正文、图片等），各输出相对独立。
+
+```tsx
+import { capabilityClient, logger } from '@lark-apaas/client-toolkit-lite';
+
+function MultiPluginStreamExample() {
+  const [title, setTitle] = useState('');
+  const [content, setContent] = useState('');
+  const [coverUrl, setCoverUrl] = useState('');
+
+  const handleGenerate = async (keywords: string) => {
+    // 1. 封面图（非流式，异步不阻塞）
+    const coverExecutor = (capabilityClient as any).load('cover_generator');
+    (coverExecutor as any).call('textToImage', { keywords })
+      .then((res: { images?: string[] }) => res?.images?.[0] && setCoverUrl(res.images[0]))
+      .catch((err: unknown) => logger.warn('封面生成失败', err));
+
+    // 2. 标题（非流式）
+    const titleExecutor = (capabilityClient as any).load('title_generator');
+    (titleExecutor as any).call('textGenerate', { keywords })
+      .then((res: { content?: string }) => res?.content && setTitle(res.content));
+
+    // 3. 正文（流式，边生成边展示）
+    const contentExecutor = (capabilityClient as any).load('content_generator');
+    const contentStream = (contentExecutor as any).callStream('textGenerate', { keywords });
+
+    // 🎯 流式内容直接拼接，无需复杂解析
+    for await (const chunk of contentStream as AsyncIterable<{ content?: string }>) {
+      setContent(prev => prev + (chunk.content || ''));
+    }
+  };
+
+  return (/* 各字段独立渲染 */);
+}
+```
+
+**优点**：代码简洁、各插件独立、某个失败不影响其他。
+
+##### ⚠️ 兜底：单插件 JSON 流式解析
+
+当无法拆分为多插件时，需处理不完整 JSON 的逐字符到达，需实现 `parseStreamingStringField` 和 `extractJsonObject` 工具函数。**强烈建议在插件设计阶段拆分为多插件并行流式调用，避免此场景。**
+
+### outputMode 与调用方式
+
+先通过 `get_plugin_ai_json(pluginInstanceId)` 获取 `actions[].outputMode`：
+
+| outputMode | 调用方式 |
+|------------|---------|
+| `unary` | `const ex = (capabilityClient as any).load(id); await (ex as any).call(actionKey, input)` |
+| `stream` | `const ex = (capabilityClient as any).load(id); for await (const c of (ex as any).callStream(actionKey, input)) {}` |
+
+---

package/steering/vite-react/skills/plugin-guide/references/table.md

@@ -0,0 +1,501 @@
+# 飞书多维表格 (feishu-bitable)
+
+本插件提供了一整套与飞书多维表格进行交互（CRUD + 聚合查询）的接口。
+
+## 开发者注意事项
+
+**本文档是为 妙搭助手 设计的技术指南。**
+
+在查看本插件的 Action 时，你将同时获得两部分信息：
+
+1. **本文档 (README)**: 提供高级指引、业务逻辑、使用场景、重要约束。
+2. **Action 的 `inputSchema` 和 `outputSchema`**: 提供精确的 JSON Schema 格式的输入/输出结构。
+
+**请遵循以下原则：**
+
+- **以 `Schema` 为结构基准**：严格按照 `inputSchema` 构建你的输入对象，并参照 `outputSchema` 解析返回结果。
+- **以 `README` 为语义权威**：`README` 中的描述包含了 `Schema` 无法表达的关键信息。**必须优先遵循 `README` 中的指引和约束。**
+
+---
+
+## 重要提醒
+
+**禁止修改插件配置中的任何字段！即使出现字段类型错误或 Action 执行错误也不能修改。**
+
+使用前需读取配置中的 `fields` 字段，了解可操作的字段及其 `bizType`。
+
+## 字段使用规范
+
+1. **使用字段名称而非 ID**：所有操作必须使用 `fields.name`（字段名称），禁止使用字段 ID
+
+2. **选项字段必须严格匹配 enumValues**：`SingleSelect` 和 `MultiSelect` 类型的选项值必须完全参考配置中的 `enumValues`，禁止自行编造
+
+   ```json
+   // 示例：假设字段配置如下
+   {
+     "name": "状态",
+     "bizType": "SingleSelect",
+     "enumValues": ["待处理", "进行中", "已完成"]
+   }
+   // ✅ 正确：使用 enumValues 中的值
+   { "状态": "进行中" }
+   // ❌ 错误：使用不存在的选项
+   { "状态": "处理中" }
+   ```
+
+3. **字段名称可能包含中文或特殊字符**：必须使用括号表示法，禁止点表示法
+
+   ```javascript
+   // ✅ 正确
+   record['状态']
+   record['v1.0版本']
+   { '状态': '进行中', 'v1.0版本': '已发布' }
+
+   // ❌ 错误
+   record.状态        // 语法错误
+   record.v1.0版本    // 会被错误解析
+   ```
+
+4. **特殊字段需特化展示**：Progress（进度条）、Currency（货币符号）、Rating（星级）、DateTime（格式化日期）、Checkbox（勾选图标）、User（头像+名称）、Barcode（条码图形）
+5. **特殊字段需专用录入组件**：SingleSelect/MultiSelect（下拉选择器）、Checkbox（开关）、DateTime（日期选择器）、User（人员选择器）
+
+---
+
+## BizType 字段类型对照表
+
+| 字段类型 | BizType        | 字段类型     | BizType        | 字段类型 | BizType       |
+| -------- | -------------- | ------------ | -------------- | -------- | ------------- |
+| 文本     | `Text`         | 单选         | `SingleSelect` | 附件     | `Attachment`  |
+| 邮箱     | `Email`        | 多选         | `MultiSelect`  | 单向关联 | `SingleLink`  |
+| 条码     | `Barcode`      | 日期         | `DateTime`     | 双向关联 | `DuplexLink`  |
+| 数字     | `Number`       | 复选框       | `Checkbox`     | 查找引用 | `Lookup`      |
+| 进度     | `Progress`     | 人员         | `User`         | 公式     | `Formula`     |
+| 货币     | `Currency`     | 电话号码     | `Phone`        | 地理位置 | `Location`    |
+| 评分     | `Rating`       | 超链接       | `Url`          | 群组     | `GroupChat`   |
+| 创建时间 | `CreatedTime`  | 最后更新时间 | `ModifiedTime` | 创建人   | `CreatedUser` |
+| 修改人   | `ModifiedUser` | 自动编号     | `AutoNumber`   | 按钮     | `Button`      |
+
+---
+
+## BizType 读写格式对照表
+
+**重要**：读取和写入时的数据格式可能不同，必须严格按照下表处理。
+
+### 可写字段
+
+| BizType                                 | 写入格式         | 读取格式           | 说明                     |
+| --------------------------------------- | ---------------- | ------------------ | ------------------------ |
+| `Text`/`Email`/`Barcode`                | `string`         | `{ text: string }` | 写入纯字符串，读取为对象 |
+| `Phone`                                 | `string`         | `string`           | 读写均为字符串           |
+| `Number`/`Progress`/`Currency`/`Rating` | `number`         | `number`           | 数值类型                 |
+| `SingleSelect`                          | `string`         | `string`           | 必须匹配 enumValues      |
+| `MultiSelect`                           | `string[]`       | `string[]`         | 必须匹配 enumValues      |
+| `DateTime`                              | `number`         | `number`           | Unix 时间戳（毫秒）      |
+| `Checkbox`                              | `boolean`        | `boolean \| null`  | 读取时可能为 null        |
+| `User`                                  | `number[]`       | `number[]`         | suda user id 数组        |
+| `Url`                                   | `{ text, link }` | `{ text, link }`   | 读写格式一致             |
+| `Attachment`                            | `string[]`       | 复杂对象           | 写入文件 URL 数组        |
+
+### 只读字段
+
+| BizType                      | 读取格式                                       |
+| ---------------------------- | ---------------------------------------------- |
+| `CreatedTime`/`ModifiedTime` | `number`（时间戳）                             |
+| `CreatedUser`/`ModifiedUser` | `number[]`（user id 数组）                     |
+| `AutoNumber`                 | `{ text: string }`                             |
+| `Formula`                    | `{ bizType: string, value: any }`              |
+| `Location`                   | `{ fullAddress, provinceName, cityName, ... }` |
+| `GroupChat`                  | `[{ groupID, displayName, avatarImageUrl }]`   |
+
+---
+
+## Actions 概览
+
+| Action               | 说明                           |
+| -------------------- | ------------------------------ |
+| `searchRecords`      | 搜索记录，支持筛选、排序、分页 |
+| `getRecord`          | 根据 ID 查询单条记录           |
+| `batchAddRecords`    | 批量新增记录（最多 500 条）    |
+| `batchUpdateRecords` | 批量更新记录（最多 500 条）    |
+| `deleteRecords`      | 批量删除记录（最多 500 条）    |
+| `aggregateQuery`     | 聚合查询，支持分组、聚合计算、筛选、排序、分页 |
+
+> 注意：分析/统计类场景应优先使用 `aggregateQuery`，不要用 `searchRecords` 模拟统计。
+
+### Action 选择决策树
+
+```
+需要什么？
+├─ 查看/编辑单条记录 → getRecord / batchUpdateRecords
+├─ 列表分页浏览 → searchRecords（游标分页，pageToken 翻页）
+├─ 按条件筛选少量记录 → searchRecords + filter + pageSize
+├─ 排行榜 / TOP N → searchRecords + sort + pageSize=N
+├─ 统计数值（计数/求和/平均/最大最小） → aggregateQuery
+├─ 分组统计（按部门/状态等维度） → aggregateQuery + dimensions
+├─ 统计 + 明细下钻 → 聚合用 aggregateQuery，下钻用 searchRecords + filter
+├─ 新增数据 → batchAddRecords
+└─ 删除数据 → deleteRecords
+
+⚠️ 禁止模式：
+❌ searchRecords 拉全量 → 内存 reduce/filter 做统计 → 必须用 aggregateQuery
+❌ searchRecords 拉全量 → sort → slice 取 TOP N → 必须用 searchRecords + sort + pageSize
+❌ searchRecords 拉全量 → find 找单条 → 必须用 getRecord
+```
+
+## 数据分析类Action补充说明
+
+`aggregateQuery` 用于分组聚合统计，支持 dimensions（分组维度）和 measures（聚合计算）。
+
+### 输入参数
+
+- **dimensions 支持的 bizType**：`Text`、`Email`、`Barcode`、`Number`、`Progress`、`Currency`、`Rating`、`SingleSelect`、`MultiSelect`、`DateTime`、`CreatedTime`、`ModifiedTime`、`Checkbox`、`User`、`CreatedUser`、`ModifiedUser`
+
+### 输出结构
+
+- 返回 `{ result, hasMore, pageToken }`
+- `result` 是聚合结果数组，每个元素是对象，key 对应 dimensions/measures 中声明字段，value 结构为 `{ value: <actual_value> }`
+
+### dimensions value 类型（常见）
+
+- `Text` / `Email` / `Barcode`: `{ text: string }`
+- `Number`: `string`
+- `Progress`: `string`
+- `Currency`: `string`
+- `Rating`: `string`
+- `SingleSelect`: `string`
+- `MultiSelect`: `string[]`
+- `DateTime` / `CreatedTime` / `ModifiedTime`: `string`（按多维表格配置格式）
+- `Checkbox`: `string`（`"true"` / `"false"`）
+- `User`: `Array<{ id, name }>`
+- `CreatedUser` / `ModifiedUser`: `{ id, name }`
+
+### measures value 类型
+
+- 所有 measures 的 `value` 都是 `number`
+
+### measures 支持的 bizType
+
+| aggregation | 支持的 bizType | 不支持 |
+|-------------|---------------|--------|
+| `count` | 所有类型（但只统计非空值，统计总行数建议用不会为空的 Number 字段） | - |
+| `sum` / `avg` | `Number`、`Currency`、`Progress`、`Rating` | **`Formula`**、`Text` |
+| `max` / `min` | `Number`、`Currency`、`DateTime` | `Formula`、`Text` |
+
+### filter
+
+aggregateQuery 的 filter 格式与 searchRecords **完全相同**，遵循下方"搜索过滤条件规则"章节的所有规则。
+
+### expandArrayDimension
+
+- `expandArrayDimension=true` 时会先展开数组维度再聚合统计
+- 典型场景：`MultiSelect`、`User`
+
+---
+
+## 代码示例
+
+```typescript
+import { capabilityClient } from '@lark-apaas/client-toolkit-lite';
+
+// 推荐：load 一次 executor 后复用，每次 cast 两次（详见 SKILL.md 调用规范）
+const bitable = (capabilityClient as any).load('plugin_instance_id');
+
+// 搜索记录
+const response = await (bitable as any).call('searchRecords', {
+  filter: {
+    conjunction: 'and',
+    conditions: [{ fieldName: '状态', operator: 'is', value: ['进行中'] }],
+  },
+  pageSize: 20,
+});
+
+// ⚠️ 响应数据直接从 response 访问，不要加 .data 或 .output 前缀
+// ✅ 正确：response.records / response.hasMore / response.total / response.pageToken
+// ❌ 错误：response.data.records / response.data.output.records
+const { records, hasMore, total, pageToken } = response;
+console.log(`共 ${total} 条，本页 ${records.length} 条，还有更多: ${hasMore}`);
+
+// 获取单条记录
+const detail = await (bitable as any).call('getRecord', { recordID: 'recXXX' });
+// ✅ 正确：detail.id / detail.record
+// ❌ 错误：detail.data.output.id
+const title = detail.record['标题']?.text;
+
+// 批量新增（注意：写入时用写入格式，字段名必须用引号包裹）
+await (bitable as any).call('batchAddRecords', {
+  records: [
+    {
+      record: {
+        文本字段: '内容', // Text: string（非 { text: string }）
+        数字字段: 100, // Number: number
+        单选字段: '选项A', // SingleSelect: string（必须匹配 enumValues）
+        多选字段: ['标签1', '标签2'], // MultiSelect: string[]
+        复选框: true, // Checkbox: boolean
+        日期字段: Date.now(), // DateTime: number (毫秒时间戳)
+        人员字段: [123456, 789012], // User: number[] (suda user id)
+        超链接: { text: '链接文本', link: 'https://example.com' }, // Url
+      },
+    },
+  ],
+});
+
+// 批量更新
+await (bitable as any).call('batchUpdateRecords', {
+  records: [{ id: 'record_id', record: { 文本字段: '新内容' } }],
+});
+
+// 删除记录
+await (bitable as any).call('deleteRecords', { recordIDs: ['id1', 'id2'] });
+
+// 读取时注意格式差异
+const textValue = record.record['文本字段']?.text; // 读取时是 { text: string }
+const numberValue = record.record['数字字段']; // number
+const userIds = record.record['人员字段']; // number[]
+
+// 聚合查询
+const aggResp = await (bitable as any).call('aggregateQuery', {
+  dimensions: ['region'],
+  measures: [{ fieldName: 'order_id', aggregation: 'count', alias: 'order_count' }],
+  sort: [{ fieldName: 'region', desc: false }],
+  pageSize: 100,
+});
+
+const chartData =
+  aggResp.result?.map((item: Record<string, { value: unknown }>) => ({
+    region: String(item.region?.value || ''),
+    order_count: Number(item.order_count?.value || 0),
+  })) || [];
+```
+
+## 代码实现注意事项
+
+1. **响应数据直接访问，禁止猜测嵌套路径**。`capabilityClient.call()` 返回的就是最终数据，直接用 `response.records`、`response.total` 等。**禁止**加 `.data`、`.output`、`.data.output` 等前缀。如果不确定响应结构，先用 `console.log` 打印完整响应再编码，禁止凭猜测修改数据路径。
+2. 在进行写入操作时，比如确认提交时，应该有loading效果，禁止用户重复点击。
+3. 如果capabilityClient call失败，命中了error逻辑，要打印日志，同时把error message提示给用户。
+4. 在进行更新操作时，只更新需要更新的字段即可，不需要对全量字段进行更新。
+5. **分页必须使用游标分页，禁止全量拉取后切片**。先拉全部数据再 `slice` 会导致性能极差、浪费带宽和内存。每次只拉当前页数据，通过 `pageToken` 翻页：
+
+   ```typescript
+   const ex = (capabilityClient as any).load(pluginInstanceId);
+   const result = await (ex as any).call('searchRecords', {
+     pageSize: 10,
+     pageToken: cursor, // 上一页返回的 pageToken
+   });
+   // 返回：{ records, pageToken（下一页游标）, hasMore, total }
+   ```
+
+---
+
+## 推荐 UI 组件（vite-react / shadcn-ui）
+
+vite-react 用的是 shadcn-ui + Radix Primitives（无 spark UI 的 `<UserDisplay>` / `<UserSelect>` / `<Hyperlink>`）。下表按 shadcn 体系给出推荐组件，**核心读写格式跟 spark 是一致的**，差异在 UI 控件本身。
+
+| BizType                      | 展示                                                                 | 录入                                                |
+| ---------------------------- | -------------------------------------------------------------------- | --------------------------------------------------- |
+| `User`                       | `<Avatar>` + 名字（按需查询 `getCurrentUserProfile` 等接口）         | 自己拼：`<Select>` / `<Combobox>` 加搜索接口        |
+| `Url`                        | `<a href={val.link} target="_blank">{val.text}</a>`                  | 两个 `<Input>`（一个填 text，一个填 link）          |
+| `SingleSelect`/`MultiSelect` | 文本 / `<Badge>` 标签                                                | `<Select>` 选项来自 enumValues                      |
+| `DateTime`                   | `new Date(ts).toLocaleDateString()`                                  | `<Popover>` + `<Calendar>`（shadcn date picker）    |
+| `Checkbox`                   | `value ? '是' : '否'`                                                | `<Checkbox />`                                      |
+| `Currency`                   | `¥${value.toFixed(2)}`                                               | `<Input type="number" />`                           |
+| `Progress`                   | `<Progress value={value} />` 或 `${value}%`                          | `<Input type="number" min={0} max={100} />` 或 `<Slider />` |
+| `Rating`                     | `'★'.repeat(value) + '☆'.repeat(5-value)`                            | `<Input type="number" min={0} max={5} />`           |
+
+> spark 体系下的 `<UserDisplay>` / `<UserSelect>` / `<Hyperlink>` 在 vite-react 不可用。`@lark-apaas/client-toolkit-lite` 没有暴露这些组件 —— 需要自己用 shadcn 的 `<Avatar>` / `<Select>` / `<Combobox>` 拼装。人员数据的获取需要走业务 API（视具体 capability 而定）。
+
+### 组件代码示例
+
+```tsx
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
+import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
+import { Checkbox } from '@/components/ui/checkbox';
+
+// 单选下拉（选项必须来自 enumValues）
+<Select value={value} onValueChange={setValue}>
+  <SelectTrigger><SelectValue placeholder="请选择" /></SelectTrigger>
+  <SelectContent>
+    {enumValues.map(opt => (
+      <SelectItem key={opt} value={opt}>{opt}</SelectItem>
+    ))}
+  </SelectContent>
+</Select>
+
+// 人员展示（最小实现：Avatar + 名字）
+<div className="flex items-center gap-2">
+  <Avatar className="size-6">
+    <AvatarImage src={user.avatarUrl} />
+    <AvatarFallback>{user.name?.[0]}</AvatarFallback>
+  </Avatar>
+  <span>{user.name}</span>
+</div>
+
+// 超链接展示
+<a href={record['超链接']?.link} target="_blank" rel="noreferrer" className="text-primary underline">
+  {record['超链接']?.text}
+</a>
+```
+
+---
+
+## 表格列渲染示例
+
+```tsx
+const columns = [
+  // 文本字段 - 注意读取格式是 { text: string }
+  { title: '文本', dataIndex: ['record', '文本字段', 'text'], key: 'text' },
+  // 人员字段 - vite-react 自行用 Avatar + 名字渲染（数据来源走业务接口）
+  {
+    title: '负责人',
+    key: 'user',
+    render: (_, record) => {
+      const ids = (record.record['人员字段'] as number[]) || [];
+      return ids.map((id) => <UserChip key={id} userId={id} />);
+    },
+  },
+  // 日期字段 - 格式化显示
+  {
+    title: '创建日期',
+    dataIndex: ['record', '日期字段'],
+    key: 'date',
+    render: (v) => (v ? new Date(v).toLocaleDateString() : '-'),
+  },
+  // 货币 - 格式化显示
+  {
+    title: '金额',
+    dataIndex: ['record', '货币字段'],
+    key: 'currency',
+    render: (v) => (v != null ? `¥${v.toFixed(2)}` : '-'),
+  },
+  // 超链接 - vite-react 直接渲染 <a>
+  {
+    title: '链接',
+    key: 'hyperlink',
+    render: (_, record) => {
+      const v = record.record['超链接'] as { text?: string; link?: string } | undefined;
+      return v?.link ? (
+        <a href={v.link} target="_blank" rel="noreferrer" className="text-primary underline">
+          {v.text || v.link}
+        </a>
+      ) : '-';
+    },
+  },
+  // 多选 - 逗号分隔显示
+  {
+    title: '标签',
+    dataIndex: ['record', '多选字段'],
+    key: 'multiSelect',
+    render: (v) => v?.join(', ') || '-',
+  },
+];
+```
+
+---
+
+## 搜索过滤条件规则
+
+### 核心规则
+
+1. **value 始终是字符串数组**：数字需转为字符串，如 `["23.4"]`
+2. **空值判断**：`isEmpty`/`isNotEmpty` 时 value 填 `[]`
+3. **Formula 字段不支持筛选**
+4. **Text 字段 `is`/`isNot` 的 value 只能传一个元素**（见下方常见错误）
+
+### 各 BizType 的 value 格式与支持的操作符
+
+| BizType                                              | value 格式                                              | 支持的操作符                                                                                   |
+| ---------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `Text`/`Email`/`Barcode`/`Phone`                     | `["内容"]`（只能一个元素）                              | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `Number`/`Currency`/`Progress`/`Rating`/`AutoNumber` | `["23.4"]`（数字转字符串）                              | `is`, `isNot`, `isGreater`, `isGreaterEqual`, `isLess`, `isLessEqual`, `isEmpty`, `isNotEmpty` |
+| `SingleSelect`/`MultiSelect`                         | `["选项A", "选项B"]`（`is`/`isNot` 填一个，其他可多个） | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `Checkbox`                                           | `["true"]` 或 `["false"]`                               | `is`（仅此一个）                                                                               |
+| `User`/`CreatedUser`/`ModifiedUser`                  | `["123456"]`（suda user id）                            | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `Url`                                                | `["显示名称"]`（填显示文本，非 URL）                    | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `GroupChat`                                          | `["328472133423"]`（群组 ID）                           | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `Location`                                           | `["地址文本"]`（只能一个元素）                          | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `Attachment`                                         | `[]`（仅支持空值判断）                                  | `isEmpty`, `isNotEmpty`                                                                        |
+| `DateTime`/`CreatedTime`/`ModifiedTime`              | 见下方                                                  | `is`, `isEmpty`, `isNotEmpty`, `isGreater`, `isLess`                                           |
+
+### 日期字段 value
+
+| value                                                                     | 含义                   | operator 限制 |
+| ------------------------------------------------------------------------- | ---------------------- | ------------- |
+| `["ExactDate", "1702449755000"]`                                          | 具体日期（毫秒时间戳） | -             |
+| `["Today"]`/`["Tomorrow"]`/`["Yesterday"]`                                | 今天/明天/昨天         | -             |
+| `["CurrentWeek"]`/`["LastWeek"]`/`["CurrentMonth"]`/`["LastMonth"]`       | 本周/上周/本月/上月    | 仅 `is`       |
+| `["TheLastWeek"]`/`["TheNextWeek"]`/`["TheLastMonth"]`/`["TheNextMonth"]` | 过去/未来七天/三十天   | 仅 `is`       |
+
+### ⚠️ 常见错误（必读）
+
+#### 1. Text 字段 `is`/`isNot` 传多个 value → 查询返回空结果
+
+```typescript
+// ❌ 错误：Text 类型 is 只能传一个元素，传多个会静默返回空
+{ fieldName: '状态', operator: 'is', value: ['红色', '黑色'] }
+
+// ✅ 排除少数值：多条 isNot + conjunction: 'and'
+{
+  conjunction: 'and',
+  conditions: [
+    { fieldName: '进展', operator: 'isNot', value: ['已完成'] },
+    { fieldName: '进展', operator: 'isNot', value: ['已终止'] },
+  ],
+}
+
+// ✅ 匹配多个值：用 contains 模糊匹配（适合有公共子串的场景）
+{ fieldName: '进展', operator: 'contains', value: ['付款'] }  // 匹配"付款审批"和"付款动作"
+```
+
+#### 2. Formula 字段不支持 filter 和 sum/avg 聚合
+
+同一数据常有两个字段：原始 Number 字段（如 `金额`，单位元）和计算 Formula 字段（如 `金额(万元)`）。聚合和过滤**必须用 Number 字段**，在代码里做单位转换：
+
+```typescript
+// ❌ 错误：金额(万元) 是 Formula，不能聚合也不能过滤
+{ fieldName: '金额(万元)', aggregation: 'sum' }
+{ fieldName: '金额(万元)', operator: 'isGreater', value: ['0'] }
+
+// ✅ 正确：用 Number 类型的 金额 字段，代码里除以 10000 转万元
+{ fieldName: '金额', aggregation: 'sum', alias: 'total_amount' }
+// 结果处理：const amountWan = totalAmount / 10000;
+```
+
+#### 3. aggregateQuery 的 `isNot` 会排掉字段为空/null 的记录
+
+与 searchRecords 不同，aggregateQuery 中 `isNot` 会把字段值为空的记录也排除。如果很多记录的该字段为空，结果会远少于预期甚至为 0。
+
+解决方案：不在 filter 里用 `isNot` 排除 Text 值，改为在 dimensions 里加上该字段，在结果侧用 if 跳过不要的分组：
+
+```typescript
+// ❌ 错误：isNot 会把「目前进展」为空的记录也排掉
+filter: { conditions: [{ fieldName: '目前进展', operator: 'isNot', value: ['已完成'] }] }
+
+// ✅ 正确：不加 filter，在 dimensions 里加「目前进展」，结果侧排除
+dimensions: ['当前状态', '目前进展'],
+// 解析时：if (progress === '已完成' || progress === '已终止') continue;
+```
+
+#### 4. count 聚合只统计非空值
+
+统计总行数时用不会为空的 Number 字段（如"行号"），不要用可能为空的 Text 字段。
+
+### 筛选条件构建示例
+
+```typescript
+const filter = {
+  conjunction: 'and', // 或 'or'
+  conditions: [
+    { fieldName: '标题', operator: 'contains', value: ['关键词'] }, // 文本包含
+    { fieldName: '状态', operator: 'is', value: ['进行中'] }, // 单选匹配
+    { fieldName: '金额', operator: 'isGreater', value: ['1000'] }, // 数字比较
+    { fieldName: '创建日期', operator: 'is', value: ['Today'] }, // 日期-今天
+    { fieldName: '截止日期', operator: 'isLess', value: ['ExactDate', Date.now().toString()] }, // 日期-具体
+    { fieldName: '负责人', operator: 'is', value: ['123456'] }, // 人员筛选
+    { fieldName: '备注', operator: 'isEmpty', value: [] }, // 空值检查
+    { fieldName: '已归档', operator: 'is', value: ['true'] }, // 复选框
+  ],
+};
+
+const response = await capabilityClient
+  .load('plugin_instance_id')
+  .call<SearchResponse>('searchRecords', { filter, pageSize: 20 });
+```

package/steering/vite-react/tech.md

@@ -13,23 +13,64 @@
 
 ```
 my-app/
-├── client/
-│   ├── src/
-│   │   ├── components/   # 业务组件
-│   │   ├── ui/           # shadcn-ui 基础组件（不要直接改）
-│   │   ├── pages/        # 路由页面
-│   │   ├── hooks/        # 自定义 hooks
-│   │   └── lib/          # 工具函数
-│   ├── index.html
-│   └── public/
+├── src/
+│   ├── assets/         # 代码 import 的静态资源（图标、组件用图）
+│   ├── components/     # 业务组件
+│   │   └── ui/         # shadcn-ui 基础组件（不要直接改）
+│   ├── pages/          # 路由页面
+│   ├── hooks/          # 自定义 hooks
+│   └── lib/            # 工具函数
+├── public/             # 固定 URL 的公开静态资源（favicon 等）
+├── shared/
+│   ├── static/         # 鉴权访问的静态资源（私有源托管）
+│   └── capabilities/   # capabilities 声明
+├── index.html
 ├── vite.config.ts
-├── tsconfig.json
 └── package.json
 ```
 
+路径别名：
+
+- `@/*` → `./src/*`
+- `@shared/*` → `./shared/*`
+
+## 静态资源放哪——判定规则
+
+按问题树走，**从上往下选第一个 yes**：
+
+1. **代码里要 `import` 它吗？**（组件用的图标、被引用的图片、CSS 里的小图）
+   → `src/assets/`，用 `import url from '@/assets/foo.png'`。
+   Vite 会 hash + 优化，进 CDN。**绝大多数情况选这条。**
+
+2. **需要鉴权才能访问吗？**（仅登录用户可见的图片、PDF、配置）
+   → `shared/static/`。通过平台运行时 SDK 拿带 token 的 URL，**不要**用 `/shared/static/...` 这种相对路径直接引。
+
+3. **必须是固定 URL 文件名吗？**（favicon、被外部系统按 URL 抓取、第三方 SDK 写死路径）
+   → `public/`。
+   - HTML 里：`<link rel="icon" href="/favicon.svg" />`（Vite 自动重写到 BASE_URL）
+   - JSX/CSS 里**不要**写 `<img src="/foo.png" />`——绝对路径在生产会解析到 HTML 域名而不是 CDN，会 404。必须用 `${import.meta.env.BASE_URL}foo.png`。
+
+⚠️ 写代码默认走 `src/assets/`。`public/` 只在 1、2 都不适用时才用，并且必须用 `BASE_URL` 拼路径。
+
+## 动态选择一组资源（国旗、头像类）
+
+不要用 `public/flags/` + 拼字符串。用 `src/assets/` + `import.meta.glob`：
+
+```ts
+const flags = import.meta.glob('@/assets/flags/*.svg', {
+  eager: true,
+  query: '?url',
+  import: 'default',
+}) as Record<string, string>
+
+const url = flags[`/src/assets/flags/${code}.svg`]
+```
+
+这样能拿到 hash 后的 CDN URL，且 Vite 会 tree-shake 未引用项。
+
 ## 核心约定
 
-1. **shadcn-ui 组件不直接改源码**——需要变化时通过 className / variant props 控制
-2. **样式优先用 Tailwind utility**，避免写 CSS module
-3. **表单始终用 react-hook-form + zod**——不要直接操作 input value
-4. **图表 ECharts 优先 echarts-for-react**——React 18 严格模式下要小心 echarts instance 的初始化
+1. **shadcn-ui 组件不直接改源码**——需要变化时通过 `className` / `variant` props 控制。
+2. **样式优先用 Tailwind utility**，避免写 CSS module。
+3. **表单始终用 react-hook-form + zod**——不要直接操作 input value。
+4. **图表 ECharts 优先 echarts-for-react**——React 19 严格模式下注意 echarts instance 的初始化时机。