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

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

@@ -1,14 +1,16 @@
 ---
 name: plugin-guide
-description: 飞书/AI 新版插件集成规范与 Plugin 链路指南。支持飞书多维表格/Base操作、发送飞书消息、创建飞书群组、AI智能生文、AI智能生图、AI图片理解等。Use when 需要：(1) 创建或管理 PluginInstance 插件实例，(2) 调用 capabilityClient/CapabilityService 生成插件调用代码，(3) 理解 Plugin、PluginInstance、PluginInstanceAIJson 三层关系，(4) 使用 get_plugin_ai_json 或 plugin_instance 工具。触发词：插件, plugin, 飞书消息, 飞书群组, 多维表格, AI生文, AI生图, 图片理解, capabilityClient, CapabilityService, pluginInstance
+description: 飞书/AI 新版插件集成规范与 Plugin 链路指南——**给生成出来的应用写运行时代码用**，让应用跑起来后能访问飞书多维表格/Base、发送飞书消息、创建飞书群组，以及 AI 智能生文/生图/图片理解等。Use when 需要：(1) 创建或管理 PluginInstance 插件实例，(2) 调用 capabilityClient/CapabilityService 生成插件调用代码，(3) 理解 Plugin、PluginInstance、PluginInstanceAIJson 三层关系，(4) 使用 get_plugin_ai_json 或 plugin_instance 工具，(5) 排查插件相关报错或异常行为（调用报错、通知/消息发送失败、配置项不生效、参数类型与预期不符等）。NOT for Agent 自己在生成期读取飞书资源内容——用户给了多维表格/文档/表格/知识库链接、要求先读懂再建应用时，那是 lark-cli skill 的场景，用 bash 调 lark-cli 读；插件是写进应用代码、部署后由应用运行时调用的，不能拿来当 Agent 的读取工具。触发词：插件, plugin, 运行时访问飞书, 应用内发飞书消息, 应用内写多维表格, 飞书群组, AI生文, AI生图, 图片理解, capabilityClient, CapabilityService, pluginInstance, 插件报错, 配置不生效, 参数类型不匹配
 steering: true
 steering-topic: plugin_guide
 match-template-name: nestjs-react-fullstack
+gate-tools:
+  - tool: plugin_instance
 ---
 
 # Plugin 集成指南
 
-飞书/AI 新版插件集成规范与 Plugin 链路指南。支持的能力包括：飞书多维表格/Base操作（插入记录、更新记录、删除记录、查询记录）、发送飞书消息、创建飞书群组、AI智能生文、AI智能生图、AI图片理解等。本文档介绍插件实例配置、运行时投影（get_plugin_ai_json）的用法，以及 Server/Client 侧的统一调用入口；具体业务能力需以实际 available_plugin_instances 与对应 plugin.ai.json 为准。
+新版插件链路（Plugin / PluginInstance / PluginInstanceAIJson）集成规范，能力覆盖飞书多维表格 CRUD、发送飞书消息、创建飞书群组、AI 生文/生图/图片理解等，具体以 `available_plugin_instances` 与对应 plugin.ai.json 为准。用户用「AI 生文」「发送飞书消息」等业务语言描述需求时，必须识别为待使用/待创建的 PluginInstance。
 
 ## Quick Reference
 
@@ -16,103 +18,120 @@ match-template-name: nestjs-react-fullstack
 |------|------|
 | 创建/更新 PluginInstance | 调用 `plugin_instance` 工具（禁止手动改文件） |
 | 获取运行时投影 | 调用 `get_plugin_ai_json(pluginInstanceId)` |
-| Client 侧非流式调用 | `capabilityClient.load(id).call(actionKey, input)` |
-| Client 侧流式调用 | `capabilityClient.load(id).callStream(actionKey, input)` |
+| Client 侧调用 | `capabilityClient.load(id).call(actionKey, input)`（流式用 `callStream`） |
 | Server 侧调用（仅兜底） | `capabilityService.load(id).call(actionKey, input)` |
 | capabilityClient 导入 | `import { capabilityClient } from '@lark-apaas/client-toolkit'` |
 | CapabilityService 导入 | `import { CapabilityService } from '@lark-apaas/fullstack-nestjs-core';` |
-| CapabilityService 注入 | `@Inject() private readonly capabilityService: CapabilityService` |
-| 配置存储位置 | `server/capabilities/<plugin_instance_id>.json` |
 
-> **capabilityClient 导入警告**：`capabilityClient` 是从 `@lark-apaas/client-toolkit` 直接导入的独立对象，**不是**从 `getDataloom()` 上获取的。错误写法：`const dataloom = await getDataloom(); (dataloom as any).capability` — 这样写不会工作。正确且唯一的方式：`import { capabilityClient } from '@lark-apaas/client-toolkit'`。
+## 必读 references
 
-## Plugin 代码编写指南
+| 场景 | 必须先读 |
+|------|---------|
+| 编写调用代码：Client/Server 侧选择、流式 chunk 解构、NestJS 注入、持久化方案、Schema 摘录卡、失败日志、冒烟清单、错误分类应对 | `references/plugin-coding-guide.md` |
+| 飞书多维表格：CRUD Action、BizType 读写格式、filter 构造、数据架构选择、UI 组件 | `references/table.md` |
+
+## 核心概念（三层关系）
+
+- **Plugin（插件）**：底层承载单元 = 插件元信息 + 表单定义（form.schema）。模型只感知插件与其表单字段，不感知内部实现（Action 实现、API 细节）。
+- **PluginInstance（插件实例）**：对某个 Plugin 表单的业务封装，以单文件 JSON 存储于 `server/capabilities/<id>.json`（语义化 id）。通过 `paramsSchema` 暴露业务入参，通过 `formValue` 将入参映射到插件表单字段（常量或 `{% raw %}{{input.xxx}}{% endraw %}` 引用）。
+- **PluginInstanceAIJson（运行时投影 pluginInstance.ai.json）**：由 PluginInstance 派生的调用合同（Runtime Spec），经 `get_plugin_ai_json(id)` 获取。含实例元数据、`actions[]`（key / inputSchema / outputSchema / outputMode: unary|stream）、`readme`（特殊字段与限制，必须阅读并严格遵循）、`formSchema`（插件表单字段结构摘要，渐进式新增字段，部分环境未部署时缺失）、`type`（single_action / multi_action，后者需选择 actionKey）。**生成调用代码前必须读取它作为唯一权威依据，禁止猜测 action、入参/出参结构、输出模式。** 仅创建/修改配置（走 `plugin_instance` 工具）或只需实例列表概览（上下文已提供）时，无需调用 `get_plugin_ai_json`。
+
+**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` 是内部路径，插件服务端可能无法访问。
+
+## 可用的 Plugin
+
+```
+{{available_plugins}}
+```
 
-以下场景**必须**先读取 `references/plugin-coding-guide.md` 再编写代码：
+## 可用的 PluginInstance
 
-- 编写 `capabilityClient` 或 `CapabilityService` 调用代码时（含导入路径、调用方式）
-- 需要判断 Client 侧还是 Server 侧调用时
-- 处理流式输出（`outputMode = stream`），包括多插件并行流式、单插件 JSON 流式解析
-- 在 Server 侧进行 NestJS 注入或编排多个插件调用时
-- 需要根据 `outputMode` 选择 `call()` 或 `callStream()` 时
+```
+{{available_plugin_instances}}
+```
 
-## 飞书多维表格（feishu-bitable）编码指南
+选择顺序：可用 PluginInstance → 可用 Plugin（调 `plugin_instance` 工具创建实例）→ 都没有则直接拒答。
 
-以下场景**必须**先读取 `references/table.md` 再编写代码：
+## PluginInstance 管理铁律
 
-- 编写飞书多维表格 CRUD 代码时（searchRecords / getRecord / batchAddRecords / batchUpdateRecords / deleteRecords）
-- 需要了解 BizType 字段类型、读写格式差异时
-- 构建搜索过滤条件（filter / conditions）时
-- 使用多维表格相关 UI 组件（UserDisplay、Hyperlink、Select 等）时
+1. 创建/更新**必须**通过 `plugin_instance` 工具完成，**绝对禁止**用 `write` / `multi_edit` 等工具直接修改 `server/capabilities/` 下的配置文件。
+2. UPDATE 严禁修改保护字段：`id / pluginKey / pluginVersion / createdAt`。
+3. 用户手改 `server/capabilities/<id>.json` 后会通知你（如"刚刚更新了 PluginInstance 配置"），此时必须调 `plugin_instance`(UPDATE) 同步。
+4. 插件表单字段含 `card_content` 且语义为飞书消息卡片时，`formValue.card_content` 必须是 JSON Object（不能是转义字符串），且卡片 DSL 最后两个元素固定。
+5. 复用优先：已有可满足的实例直接用，严禁为"更贴合"新建重复实例。
 
-### 多维表格应用的数据架构选择
+## 开发流程
 
-当应用需要读取飞书多维表格数据时，根据**查询模式**选择架构：
+1. **检查复用**：基于上下文的 PluginInstance 列表检索候选；有候选但不确定 → 调 `get_plugin_ai_json` 按 actions/schema/outputMode 判断。禁止按旧链路读取 `server/capabilities/capabilities.json` 做复用判断。
+2. **决策**：可复用 → 进第 3 步；不可复用 → 有更贴合的 Plugin 则 `plugin_instance`(CREATE)，需调整已有实例则 UPDATE，否则告知用户无法满足。
+3. **生成调用代码（编码前闸门）**：
+   - 必须先调 `get_plugin_ai_json(pluginInstanceId)`，再产出 **Schema 摘录卡**（格式见 `references/plugin-coding-guide.md`）；摘录卡字段缺失禁止编码，`output.fields` 必须完整列出且每个输出字段在代码中被消费（持久化或展示）
+   - 按 `actions[].key` 选 actionKey；严格按 `inputSchema` 构造入参（`type: array` 字段必须传数组）、按 `outputSchema` 解析出参——流式 chunk 是**对象**（按字段解构如 `chunk.content`，禁止当字符串拼接），非流式同理按字段名读取；**务必阅读并遵循 `readme`**
+   - 调用侧：优先 Client（`unary` → `call()`，`stream` → `callStream()`）；触发器/定时任务、敏感凭证、强事务、结果需落库 → Server 侧
+4. **代码放置**：Client（默认，用户交互触发）→ `client/` 组件/hooks；Server（兜底）→ `server/` Service。
+5. **真实调用冒烟（完成前必须）**：至少成功调用一次 `call()` 或 `callStream()`（按 outputSchema 读 chunk）；失败日志含最小字段（字段清单见 `references/plugin-coding-guide.md`）。无冒烟结果不得宣告完成。
 
-| 查询模式 | 架构选择 | 实现方式 |
-|---------|---------|---------|
-| 展示/编辑单条记录 | 纯插件 | `getRecord` / `batchUpdateRecords` |
-| 列表分页浏览 | 纯插件 | `searchRecords` + `pageToken` 游标分页 |
-| 统计聚合（计数/求和/平均） | **纯插件 + aggregateQuery** | 禁止 searchRecords 全量拉取后内存计算 |
-| 统计 + 明细下钻 | 纯插件 | 聚合用 `aggregateQuery`，下钻用 `searchRecords` + filter |
-| 排行榜 / TOP N | 纯插件 | `searchRecords` + sort + pageSize=N |
-| 复杂排序/多表关联/全文搜索 | 插件同步 + 本地数据库 | 定时/Webhook 同步到 postgres，复杂查询走数据库 |
-| 高频写入 + 读取 | 本地数据库为主 | 多维表格仅作展示/备份 |
+### Plugin Chain 调用示例
 
-**快捷判断：**
-- 用户说"仪表盘/dashboard/驾驶舱/看板/统计" → **必须用 `aggregateQuery`**
-- 用户说"列表/明细/详情" → `searchRecords` 分页
-- 用户说"排行榜/TOP N" → `searchRecords` + sort + pageSize=N
-- 需要跨表关联或复杂计算 → 建本地数据库表 + 同步
+```typescript
+// 文档 → 结构化数据（2步链）；fileUrl 通常为数组类型，必须按 inputSchema 传入
+const raw = await capabilityClient
+  .load('doc_parser_instance')
+  .call('parseDocToMarkdown', { fileUrl: [docUrl] }); // Client 侧可直接传 File/Blob 对象
+const structured = await capabilityClient
+  .load('text_to_json_instance')
+  .call('textToJson', { text: raw.content });
+```
 
-## Plugin 链式调用（Plugin Chain）
+## 插件能力与链式选择
 
-很多业务场景需要多个插件串联完成，**禁止用正则/字符串解析替代 AI 插件做结构化输出处理**（包括提取和生成场景）。
+**禁止用正则/字符串解析替代 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` | 文档(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-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-text-summary / ai-translate / ai-categorization
 │   └── 仅需原文 → ai-doc-parser（单步）
 ├── 图片 → ⚠️ 注意选择正确的插件：
-│   ├── 提取结构化数据（发票/名片/证件等）→ ai-image-to-json（⭐ 单步直达！）
+│   ├── 提取结构化数据（发票/名片/证件等）→ 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-translate（2步链）
 │   └── 仅需文字 → ai-speech-to-text（单步）
 └── 纯文本
-    ├── 需要结构化数据 → ai-text-to-json（⭐ 单步直达！）
+    ├── 需要结构化数据 → ai-text-to-json（⭐ 单步直达）
     └── 摘要/翻译/分类/生成
         ├── 输出包含多个独立字段（标题+正文+评分等）
         │   → 拆成多个独立插件并行调用（⭐ 优先）或用 ai-text-to-json
@@ -120,533 +139,129 @@ match-template-name: nestjs-react-fullstack
         └── 输出为单一文本（仅展示，不需解析）→ 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 rawResult = await capabilityClient
-  .load('doc_parser_instance')
-  .call('parseDocToMarkdown', { fileUrl: [docUrl] });
-
-// Step 2: AI 结构化提取
-const structured = await capabilityClient
-  .load('text_to_json_instance')
-  .call('textToJson', { text: rawResult.content });
-
-// Step 3: 使用结果（填入表单 / 写入数据库 / 写入多维表格等）
-```
-
-> **Client 侧提示**：`capabilityClient` 支持直接传 File/Blob 对象作为文件参数，无需先上传到 dataloom 获取 URL：
-> ```typescript
-> // Client 侧：直接传 File 对象，SDK 自动处理上传
-> const rawResult = await capabilityClient
->   .load('doc_parser_instance')
->   .call('parseDocToMarkdown', { fileUrl: [file] }); // file 为 File/Blob 对象
-> ```
-> ⚠️ 仅 `capabilityClient`（Client 侧）支持此能力，Server 侧 `CapabilityService` 仅支持 URL 字符串。
-
-### 创建结构化提取 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`（单步），避免不必要的链式调用
+生成内容后可继续接外部服务：如 `ai-text-generate` → `send-feishu-message`（报告→通知）、`ai-text-to-json` → `feishu-bitable`（结构化→入库）。
 
-## 外部服务插件 fallback 规则（飞书/外部 IO 类必读）
+**创建 `ai-text-to-json` / `ai-image-to-json` 实例时**：必须一次性定义**所有**需提取字段（参考数据库 schema / 表单定义 / UI 设计），宁多勿漏；字段类型仅支持 String/Number/Boolean，最多 20 个；先调 `get_plugin_ai_json` 确认上游插件的 `outputSchema` 确保输入格式正确。
 
-以下 3 条规则适用于 **外部服务类插件**：`feishu-bitable` / `send-feishu-message` / `feishu-group-create` / `send-feishu-message-card` 等 plugin.ai.json `category=external-service` 的 PluginInstance。
+## 多维表格数据架构
 
-### 规则 1：飞书插件已内置 OAuth，禁止前端手写 OAuth URL
+应用需读取飞书多维表格数据时，按查询模式选架构（完整对照表见 `references/table.md`「数据架构选择」）。**快捷判断**：「仪表盘/dashboard/驾驶舱/看板/统计」→ 必须 `aggregateQuery`（禁止 searchRecords 全量拉取后内存计算）；「列表/明细/详情」→ `searchRecords` 分页；「排行榜/TOP N」→ `searchRecords` + sort + pageSize=N；跨表关联或复杂计算 → 本地数据库 + 同步。
 
-飞书 `feishu-*` 系列插件在 `capabilityClient.call()` 内部自动完成 OAuth 授权（基于服务端注册的 OAuth `FEISHU_APP_ID`/`FEISHU_APP_SECRET` env），**前端不需要、也禁止**手写以下任何字面量：
+## 外部服务插件规则（category=external-service 必读）
 
-- ❌ `https://open.feishu.cn/open-apis/authen/v1/index?app_id=...`
-- ❌ `https://open.feishu.cn/open-apis/authen/v1/authorize?app_id=...`
-- ❌ 把多维表格 `appToken`（如 `ZeHhbA4McaXT34s6sGLjiWLqpOd`，来源于用户填的 `/base/<appToken>` URL）当成 OAuth `app_id` 拼跳转 URL
+适用于 `feishu-bitable` / `send-feishu-message` / `feishu-group-create` 等 plugin.ai.json `category=external-service` 的实例。
 
-> **命名陷阱**：飞书 OAuth `app_id` 是飞书自建应用 ID（`cli_xxxxxxxxxx`，由开发者在飞书开放平台创建后填到后端 env）；多维表格 `appToken` 是 Bitable 文件 ID，来源是用户的多维表格 URL。两者完全不是同一概念，混淆会拼出空 / 错值导致用户看到"请求非法"。详见 `~/.claude/skills/miaoda-skills/feishu/references/oauth.md`。
+### OAuth 已内置，禁止前端手写
 
-### 规则 2：`plugin_instance` 工具创建失败时的标准 fallback
+飞书 `feishu-*` 系列插件在 `capabilityClient.call()` 内部自动完成 OAuth 授权（基于服务端注册的 `FEISHU_APP_ID`/`FEISHU_APP_SECRET` env）。前端**禁止**手写 `https://open.feishu.cn/open-apis/authen/...` 任何授权 URL，更禁止把多维表格 `appToken` 当 OAuth `app_id` 拼 URL。
 
-调用 `plugin_instance` 工具 CREATE 外部服务插件时，工具可能返回的失败语义包括：
+> **命名陷阱**：OAuth `app_id` 是飞书自建应用 ID（`cli_xxx`，填在后端 env）；多维表格 `appToken` 是 Bitable 文件 ID（来自 `/base/<appToken>` URL）。混淆会拼出空/错值导致"请求非法"。详见 `~/.claude/skills/miaoda-skills/feishu/references/oauth.md`。
 
-| 工具返回 content | 含义 | 正确响应 |
-|---|---|---|
-| "缺少必填配置（appToken、tableID）..." | 当前用户配置不全，平台引导用户去 UI 配置 | (a) 在应用 UI 给配置入口（自建配置表单，回写 plugin instance 配置）；(b) 代码保留 `capabilityClient.load(<pluginInstanceId>).call(...)` 引用；(c) 未配置态 UI 给清晰报错（`toast.error` + 配置入口跳转） |
-| "当前不支持集成该插件实例" | 该 plugin 当前未对接 / 未上架 | 在 UI 明确告知用户该能力暂不可用，**禁止**降级到手写 SDK / 手写 OAuth |
-| 其他 `status != "completed"` | 平台异常 | 重试一次后仍失败 → 同上："禁止降级到手写实现"，明示用户能力暂时不可用 |
+### 不支持场景：匿名写入多维表
 
-**铁律：`plugin_instance` 工具返回任何失败状态时，禁止 agent 在前端代码中实现替代方案（手写 OAuth / 手写 fetch / 手写 SDK 调用）**。这条规则的意义是：外部服务插件的鉴权、签名、token 刷新、错误处理由插件统一封装，agent 自己写一遍既不安全（token 暴露给前端）也不稳定（鉴权流程频繁变更）。
+公开链接、二维码、候选人/外部客户等未登录访客提交表单时，当前不支持直接写入飞书多维表。如需写入，必须先引导用户登录，再在登录态下触发写入。
 
-### 规则 3：业务功能依赖外部服务插件时，禁止用 `setTimeout` 模拟成功
+## 禁止 Mock —— 铁律
 
-当业务功能（如"数据同步到飞书多维表格"、"发送飞书消息通知"）依赖 `feishu-bitable` 等外部服务插件时，**禁止**写如下"模拟做事"代码：
-
-- ❌ `await new Promise(resolve => setTimeout(resolve, 300))` + 直接设 `successCount = totalRows`
-- ❌ `await fakeSyncToFeishu()` + 假装返回 `{status: 'success'}`
-- ❌ 任何不调 `capabilityClient.load(<id>).call(...)` 也不调真实后端 API 的"假同步"路径
-
-正确做法（二选一）：
-
-1. **调真 plugin**：`await capabilityClient.load(pluginInstanceId).call('batchAddRecords', { ... })`，捕获错误后给清晰 UI 反馈
-2. **明确报错**：plugin 未配置/未就绪时直接 `toast.error('未配置飞书多维表格，请前往设置页配置')` + 跳转配置页，**不**编一个假的"同步成功"
-
-## 核心概念
-新版链路中，**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 在生成**调用代码**前，必须读取它作为权威依据（Server 侧用 `CapabilityService`，Client 侧用 `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"形式存储在 `server/capabilities/`（每个插件实例一个文件，逻辑上对应 server/capabilities/<id>.json）。
-- 运行时调用前，Code Agent 需要通过 get_plugin_ai_json 获取对应插件实例的 pluginInstance.ai.json，再基于其中的 actions/schema/outputMode 生成调用代码。
-- 运行时调用入口统一走 SDK/Service：
-	- Server 侧：CapabilityService.load(pluginInstanceId).call(actionKey, input)
-	- Client 侧：capabilityClient.load(pluginInstanceId).call(actionKey, input)（流式用 callStream）
-
-
-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}}"
-  }
-}
-```
+**用户场景需要用到插件实例时，禁止 Mock，必须走真实调用链路。** 铁律覆盖 AI 类与**外部服务类**插件（feishu-bitable / send-feishu-message / wiki / docx 等），不属于"展示数据 mock"豁免范围；"速度优先 / 快速迭代"不豁免。禁止 Mock `capabilityClient` / `CapabilityService` 返回值、跳过实际调用直接构造结果；调用失败或参数不明确时反馈用户补齐。
 
-**注意**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`、`picture` 或 `plugin-file-url` 的字段在 Client 侧调用时均支持直接传入 File/Blob 对象，`capabilityClient` SDK 会自动处理上传；Server 侧 `CapabilityService` 仅支持 URL 字符串。**禁止**Client 侧先通过 dataloom 上传文件拿 URL 再传给插件——dataloom 的 `download_url` 是内部存储路径，插件服务端可能无法访问。
-#### 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` 动态生成调用代码（Server 用 CapabilityService，Client 用 capabilityClient）
-   - 仔细阅读返回的 readme，必须严格遵循里面制定的规则
-
-### 典型场景示例
-- **消息通知类**：封装"发送飞书消息"相关插件为业务插件实例
-- **群组管理类**：封装"创建飞书群组"相关插件为业务插件实例
-- **AI 生成类**：封装"AI 生文/生图/图片理解"相关插件为业务插件实例
-
-### 使用限制
-- PluginInstance 必须通过 `plugin_instance` 工具创建/更新，不支持 agent 直接手改 `server/capabilities/` 下的配置文件
-- 调用前必须通过 `get_plugin_ai_json` 获取权威 schema，禁止猜测入参/出参结构
-- PluginInstance 配置信息存储在 `server/capabilities/` 目录
-- 运行时调用统一走  SDK/Service，不再为每个插件实例预生成固定的 call 文件
-  -  Server 侧：CapabilityService.load(capabilityId).call(actionKey, input)
-  -	Client 侧：capabilityClient.load(capabilityId).call(actionKey, input)（流式用 callStream）
-
-## PluginInstance 生成约束
-
-1. 非常**注意**，必须通过调用 `plugin_instance`工具 来创建、更新 PluginInstance，**绝对禁止**使用 `multi_edit`工具 和 `write`工具 来直接修改 `server/capabilities/` 目录下的内容。
-2. PluginInstance 配置以单文件形式存储在 server/capabilities/ 目录下（逻辑上为 server/capabilities/<plugin_instance_id>.json），不再维护集中式的 capabilities.json。
-3. 用户可以手动修改 `server/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 的最后两个元素必须固定。
-
-## 严格的调用规则 - 禁止 Mock
-
-**当用户场景需要用到插件实例时，禁止 Mock，必须走真实插件实例调用链路。**
-
-- 禁止 Mock `capabilityClient` / `CapabilityService` 的返回值
-- 禁止使用假数据创建 mock 版本的 PluginInstance 调用
-- 禁止跳过实际方法调用而直接构造返回结果
-- 必须基于 `get_plugin_ai_json` 返回的 schema 生成真实调用代码
-- 如果调用失败或参数不明确，必须反馈给用户并补齐关键参数
-
-**特别禁止的 Mock 反模式**（以下代码特征命中任何一个即为违规）：
+**特别禁止的 Mock 反模式**（命中任一即违规）：
 
 | 代码特征 | 为什么错 |
 |---------|---------|
-| `setTimeout(() => resolve(硬编码数据))` | 用延时模拟 AI 响应，实际没调用插件 |
+| `setTimeout(() => resolve(硬编码数据))` / 假 sync 函数返回 `{status:'success'}` | 用延时/假函数模拟成功，实际没调插件 |
 | `Math.random()` 替代 AI 分类/评分/推荐结果 | 调了插件但丢弃返回值，用随机数代替 |
 | `logger.log(input); return { success: true }` | 通知方法是占位空壳，没调 CapabilityService |
-| `const PRESET_DATA = [...]` 替代插件调用 | 用硬编码预置数据架空 AI 能力 |
+| `const PRESET_DATA = [...]` / `sessionStorage` 替代插件调用 | 用硬编码预置数据架空能力 |
 
-> **铁律覆盖的插件范围**：除 AI 类（生文/生图/翻译/结构化等），**外部服务类插件**（feishu-bitable / send-feishu-message / feishu-group-create / wiki / docx 等）铁律同样适用，不属于"展示数据 mock"豁免范围。"速度优先 / 快速迭代" 不豁免铁律——用户明确请求接入实际能力时（飞书写入 / 消息通知 / AI 生图等），必须真实调用，不接受 `setTimeout` / `sessionStorage` / 硬编码作为 fallback。
->
-> **prototype 场景的精化豁免**：当用户在 prompt 中**显式**说明"原型 / 不接后端 / 不接业务 / 仅做 UI / 示例数据即可 / 占位图就行 / 纯前端"等表述时，整页 mock（含表格示例行、随机占位图、setTimeout 模拟同步）**允许保留**，**不要**仅因数据动词命中（如"同步""写入""导出"）就强行接入真实插件。判定优先级：用户明示的"原型/不接业务" > 数据动词暗示的"真实接入"。
+插件未配置/未就绪时的正确做法：`toast.error('未配置飞书多维表格，请前往设置页配置')` + 跳转配置入口，**不**编假的"同步成功"。
 
-## ⚠️ plugin_instance CREATE 失败的恢复路径（最高优先级）
+> **prototype 场景的精化豁免**：用户**显式**说"原型 / 不接后端 / 不接业务 / 仅做 UI / 示例数据即可 / 纯前端"时，整页 mock 允许保留，不要仅因数据动词（"同步""写入""导出"）就强行接真实插件。用户明示的"原型/不接业务" > 数据动词暗示的"真实接入"。
 
-**这是 CREATE-time 错误处理的最高优先级规则——优先于"速度优先 / 快速迭代 / 立刻给用户看效果"等任何主 prompt 通用约束。**
+## plugin_instance CREATE 失败的恢复路径（最高优先级）
 
-`plugin_instance` 工具 CREATE 返回平台**缺必填配置**类错误（如多维表格返回"请前往预览右边的插件配置页面配置多维表格插件并提交"、send-feishu-message 返回"缺少 receive_id"等），**严禁**：
+**这是 CREATE-time 错误处理的最高优先级规则——优先于"速度优先 / 立刻给用户看效果"等任何主 prompt 通用约束。** CREATE 失败时**严禁**：静默回退到 mock；假装"配置已生效"继续写下游代码；丢弃用户已提供的必填配置值；降级到手写 OAuth / fetch / SDK（外部服务插件的鉴权、签名、token 刷新由插件统一封装，自己写既不安全也不稳定）。
 
-- ❌ 静默回退到 `setTimeout` / `sessionStorage` / 硬编码 mock 实现
-- ❌ 假装"配置已生效"继续写下游代码
-- ❌ 把已知的必填配置值（用户在对话中提供的 AppToken / TableID / receive_id 等）丢弃
+按失败语义处理：
 
-**必须**按以下 4 步处理：
+- **"缺少必填配置（appToken、tableID）..."类** → 走下方 4 步恢复；应用 UI 可给配置入口 + 未配置态清晰报错；等待配置期间代码**保留** `capabilityClient.load(<pluginInstanceId>).call(...)` 真实调用引用，禁止移除或用占位替代
+- **"当前不支持集成该插件实例"**（未对接/未上架） → UI 明确告知能力暂不可用
+- **其他 `status != "completed"`**（平台异常） → 重试一次，仍失败则明示用户能力暂时不可用
 
-1. **原样转告** — 把平台返回的 actionable 错误信息**完整**呈现给用户（包括"请前往预览右边的插件配置页面..."这类操作指令）
-2. **等待用户在 UI 完成配置** — 用户配置完毕会通知 agent（典型用语："刚刚更新了 PluginInstance 配置" / "已经配置好了"）
-3. **重新调用** `plugin_instance(operType=UPDATE)` 拿到完整的 PluginInstance 配置
-4. **调** `get_plugin_ai_json` → 生成 `capabilityClient.load(id).call(...)` 或 `capabilityService.load(id).call(...)` 调用代码，**禁止跳过**
+缺配置类错误的 4 步恢复：
 
-> **已知必填配置值的传入**：如果用户在对话中已经给出必填配置值（如飞书 base URL 含 AppToken/TableID），调用 `plugin_instance(CREATE)` 时**必须**把这些值**显式列入** `requirementsSummary` 字段，让平台 LLM 能解析并装配到 formValue。例：`requirementsSummary: "创建飞书多维表格写入实例，appToken=ZeHhbA4MxxxX, tableID=tblMQ9OgxxxW, 用于把 Excel 行批量插入"`，而不是只说"配置写入数据到指定的表格"。
+1. **原样转告**——平台返回的 actionable 错误信息完整呈现给用户（含"请前往预览右边的插件配置页面..."类操作指令）
+2. **等待用户在 UI 完成配置**——配置完用户会通知 agent
+3. **重新调用** `plugin_instance(UPDATE)` 拿到完整配置
+4. **调 `get_plugin_ai_json`** → 生成真实调用代码，禁止跳过
 
----
+> **已知必填配置值的传入**：用户对话中已给出的必填配置（如飞书 base URL 含 AppToken/TableID），CREATE 时**必须显式列入 `requirementsSummary` 字段**让平台 LLM 装配到 formValue。例：`requirementsSummary: "创建飞书多维表格写入实例，appToken=ZeHhbA4MxxxX, tableID=tblMQ9OgxxxW, 用于把 Excel 行批量插入"`。
 
-## GetPluginInstanceAIJson 工具使用指南
+## 插件调用错误处理
 
-`get_plugin_ai_json(pluginInstanceID)` — 读取插件实例的运行时投影，返回结构参见上文 PluginInstanceAIJson 示例。
+错误分类与应对策略详见 `references/plugin-coding-guide.md`「调用错误分类与应对」。必须遵守：
 
-### 何时调用
+1. **禁止静默吞异常**：每个 `catch` 至少满足其一——向用户展示错误（toast/页面状态），或触发补偿机制（重试/降级/记录待处理列表）
+2. **异步操作必须有终态**：不阻塞主流程的插件调用须在 DB 维护状态（pending → success/failed），前端必须展示 failed，不能永远 loading
+3. **通知类插件失败必须有补偿**：如 `send-feishu-message` 失败，至少记录"待发送"列表或 UI 提示"通知发送失败，请手动联系"
+4. **配置完整性（load 前必查）**：`load(id)` 前确认实例已创建且 id 与代码完全匹配，否则抛 `CapabilityNotFoundError`（开发态 Top 错误）；load/call 失败时停止后续请求避免放大错误；**缓存 load 结果**，同一 id 不重复 load
+5. **线上/客户反馈的插件问题先查 runtime log 取证**：用户反馈「线上 / 已发布」的插件问题（飞书消息发不出 / 插件不生效 / capability 调用「用户收不到」）时，**先查线上 runtime log 再定位代码**——用 `miaoda observability log`（必要时 `trace`）看 CapabilityService 真实错误、plugin_key、action、必填参数/输入校验错误，拿到线上 ERROR/WARN 再读代码修复。**即使你已在代码里读到一个疑似原因，也不得据此直接下根因、跳过取证**——静态代码里的可疑点常不是运行时真正的失败点（线上真错误多为运行时入参为空 / 校验失败 / 授权态问题，代码静态看不出），runtime log 是这类问题下结论前的必经步。沙箱 `read_logs` 只覆盖 dev 态，**不能**作为「线上插件无错误」的证据；纯本地 dev 态插件报错仍用 `read_logs`
 
-| 场景 | 是否调用 |
-|------|---------|
-| 已选定插件实例，需生成调用代码 | **必须调用** |
-| 需确认 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` 的字段，必须传数组而非字符串）
-5. **流式输出必须按 `outputSchema` 解构 chunk**：`callStream` 返回的每个 chunk 是**对象**（结构与 `outputSchema` 一致），不是原始字符串。必须通过字段访问提取内容（如 `chunk.content`），禁止将 chunk 当作字符串直接拼接
-6. **非流式输出同样按 `outputSchema` 解析**：`call()` 的返回值是对象，必须按 `outputSchema` 的字段名读取（如 `result.content`、`result.images`），禁止假设返回值结构
-7. **先产出 Schema 摘录卡再编码**：未完成摘录卡（pluginInstanceId/actionKey/outputMode/required/output fields/readme约束）前，禁止进入代码编辑
-
-### 编码前闸门（必须通过）
-
-调用代码落盘前，先输出 **Schema 摘录卡**（来自 `get_plugin_ai_json`）：
-
-```markdown
-[Schema 摘录卡]
-- pluginInstanceId / actionKey / outputMode
-- input.required: [字段名: 类型, ...]
-- output.fields: [字段名: 类型, ...]（每个字段必须在代码中被消费，未消费需注释说明原因）
-- readme.constraints
-- 调用侧决策: Client | Server
-```
-
-字段缺失时禁止编码。摘录卡中的 output.fields **必须完整列出**，编码时每个输出字段都必须被消费（持久化或展示）。
-
-## 开发流程要求
-
-### 第一步：检查现有 PluginInstance（复用优先）
-
-1) 用户描述需求后，优先基于上下文提供的插件实例列表检索是否已存在可复用插件实例。  
-2) 若存在候选插件实例但你无法确认其是否满足需求，必须调用 `get_plugin_ai_json` 获取该插件实例的运行时投影（pluginInstance.ai.json），根据其中的：
-- `actions[].key`
-- `actions[].inputSchema / outputSchema`
-- `actions[].outputMode`
-来判断是否可复用以及如何调用。  
-3) 禁止按旧链路去读取/维护 `server/capabilities/capabilities.json` 来做复用判断。
+## 缓存与幂等性
 
-> 结论：**复用判断以插件实例列表 + get_plugin_ai_json 为准**，禁止猜测 action、入参/出参、输出模式。
+- AI 类插件**没有请求级缓存**。相同输入返回相似结果是低 temperature 下的正常 LLM 行为，不是缓存
+- **禁止**通过向业务参数注入 UUID/时间戳"绕缓存"——会污染 AI 输入产生垃圾文本
+- 确需不同结果：调实例的 `formValue.modelParams.temperature`、prompt 中加明确变化要求、或换业务上下文
 
-### 第二步：决策
+## 插件参数来源规范
 
-- 如果找到匹配的插件实例：直接进入「第三步：代码调用」，严禁为了"更贴合需求"而随意新建重复的插件实例。
-- 如果不存在合适插件实例，则基于上下文提供的插件列表进行判断：
-  - 需要创建：如果插件列表有更贴合需求的插件，调用 `plugin_instance` 工具（operType=CREATE）生成新的单文件 PluginInstance 配置。
-  - 需要调整已有插件实例：调用 `plugin_instance` 工具（operType=UPDATE）更新该插件实例配置。
-  - 其他情况：告知用户该需求目前无法满足
+- **业务数据**（简历内容、职位描述等）：从 DB 查询或前端传入，经 `input` 传递
+- **固定的运行时配置**（固定接收人等）：CREATE 时在 `formValue` 直接写死（如 `formValue.receiverUserList: ["1854102143505690"]`）
+- **动态的运行时配置**（按角色/条件变化）：从平台角色 API / 应用配置表 / 环境变量获取，经 `input` 传入（`{% raw %}formValue.receiverUserList: "{{input.receiverIds}}"{% endraw %}`）
 
-**强制约束**：
-- 创建/更新 PluginInstance **必须**通过 `plugin_instance` 工具完成，绝对禁止直接修改 `server/capabilities/` 下的配置文件。
-- UPDATE 场景严禁修改保护字段：`id / pluginKey / pluginVersion / createdAt `。
+**禁止**在业务代码中硬编码运行时配置值（如 `const userId = '185410...'`）。`formValue` 配置固定值 ≠ 代码硬编码：前者是声明式配置，修改不用改代码。
 
-### 第三步：生成调用代码
+### formValue 字段结构核对（报错排查）
 
-1. **必须**先调用 `get_plugin_ai_json(pluginInstanceId)`
-2. **必须**先输出 Schema 摘录卡（见上方“编码前闸门”），完成后才能写代码
-3. 根据 `actions[].key` 选择正确的 actionKey
-4. 严格按 `inputSchema` 构造入参，严格按 `outputSchema` 解析出参
-5. **优先选择 Client 侧调用**：
-   - `outputMode = unary` → `capabilityClient.load(id).call()`
-   - `outputMode = stream` → `capabilityClient.load(id).callStream()`
-6. **仅在必要时使用 Server 侧**（触发器、敏感凭证、强事务等场景）
+`formValue` 结构以插件本体 schema 为准，禁止凭经验猜测字段类型。运行时报错形如 `x.y: 期望 <type> 实际 <got>` 即字段结构不符，此时先调 `get_plugin_ai_json` 查看返回的 `formSchema` 确认真实结构再改（若返回中无 `formSchema` 字段，以插件 `readme` 为准；下方字段表仅是 `send-feishu-message` 的示例结构，其他插件不可套用），禁止反复试错式调整。
 
-### 第五步：真实调用冒烟验证（完成前必须）
+以 `send-feishu-message` 为例（其他插件同理，字段以各自插件的真实结构为准，不要照搬下表）：
 
-代码修改后，必须完成最小冒烟并记录：
+| 字段 | 结构 | 说明 |
+|------|------|------|
+| `title` | 对象 `{ title: string, titleColor?: string }` | `title` 必填，1-50 字符；`titleColor` 可选，默认 `'wathet'` |
+| `receiverUserList` | 数组，元素为 id 字符串或 id 数组 | 最多 200 个；**禁止用逗号拼接的字符串代替数组**——会被当成单个 ID 静默失败 |
+| `receiverGroupList` | 数组 | 最多 5 个 |
+| `sender` | 字符串 | 默认 `'bot'` |
+| `buttons` | 数组，每项含 `text`（必填，1-20 字符） | 最多 3 个 |
+| `content` | 字符串 | ≤5000 字符 |
 
-1. `unary` 场景：至少成功调用一个 `call()`
-2. `stream` 场景：至少成功调用一个 `callStream()`，并按 `outputSchema` 读取 chunk
-3. 失败日志最小字段：`pluginInstanceId` `actionKey` `outputMode` `inputKeys` `resultKeys` `firstChunkKeys` `error.message`
-4. 无冒烟结果，不得宣告完成
+**通过 `plugin_instance` 创建/修改实例时**：`requirementsSummary` 必须显式写明 formValue 关键字段的结构与内层键名（如"标题需为对象，内层键名是 title"），不能只描述业务值——配置生成器是独立运行的 LLM，读不到本文档，不写明结构会被按常识臆造键名。
 
-### 第四步：代码放置位置
+### 通知接收人动态解析
 
-| 调用侧 | 代码位置 | 适用场景 |
-|-------|---------|---------|
-| Client（默认） | `client/` 目录下的组件/hooks | 用户交互触发的调用 |
-| Server（兜底） | `server/` 目录下的 Service | 触发器、定时任务、敏感操作 |
+接收人（`receiverUserList`/`receiverGroupList` 等）按角色/条件变化时，必须实时查询角色成员经 `input` 传入（角色/成员的运行时查询写法见 `authz-guide` 技能），禁止硬编码或凭经验拼装 ID。如引入缓存，必须提供显式失效手段（如角色变更时清缓存）并明示 TTL，禁止无失效手段的常驻缓存导致接收人信息过期。通知发送失败的补偿要求见上文「插件调用错误处理」第 3 条铁律，不重复展开。
 
-## 常见错误（必须避免）
+## 飞书深链 URL 规范
 
-| 错误做法 | 正确做法 |
-|---------|---------|
-| 不涉及持久化时仍在 Server 侧写调用代码 | 不需要存储的场景（即时展示、发消息等），优先用 Client 侧 |
-| 为不涉及数据存储的插件调用创建后端 API 中转 | 纯展示场景前端直接调用 `capabilityClient`；涉及持久化时可在 Server 侧调用 |
-| 未调用 `get_plugin_ai_json` 就猜测参数 | 先获取 runtime spec，再生成代码 |
-| Mock `capabilityClient` / `CapabilityService` 返回值 | 必须真实调用 |
-| 猜测 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` 字段 |
-| 流式调用时将 chunk 当作字符串直接拼接（如 `text += chunk`） | chunk 是对象，必须按 `outputSchema` 解构字段：`text += chunk.content \|\| ''` |
-| 未按 `outputSchema` 解析返回值，猜测返回结构 | 严格按 `get_plugin_ai_json` 返回的 `outputSchema` 读取字段，流式和非流式均适用 |
-| 未输出 Schema 摘录卡就直接写调用代码 | 先完成“编码前闸门”中的摘录卡，再开始编码 |
-| 改完未做真实调用冒烟就宣告完成 | 至少完成一次 unary/stream 真实调用验证，并附最小日志字段 |
-| formValue 中用 `["{{input.xxx}}"]` 包装已经是 `type: array` 的 paramsSchema 参数 | 当 paramsSchema 定义为 array 时，formValue 应透传 `"{{input.xxx}}"`，不要再包一层数组 |
-| 通过 `getDataloom().capability` 或 `(dataloom as any).capability` 调用插件 | `capabilityClient` 是独立导入，不通过 dataloom 访问。dataloom 仅提供 storage 和 service |
-| Client 侧调用插件时，先通过 dataloom 上传文件拿 URL 再传给插件 | Client 侧可直接传 File/Blob 对象给 `capabilityClient`，SDK 自动处理上传。适用于所有文件类型字段（`format` 为 `file`/`picture`/`plugin-file-url`）。Server 侧仍需传 URL |
-| 前端调用插件后不保存结果到数据库，导致页面刷新后数据丢失 | 需要持久化时：优先在 Server 侧调用并直接落库（方案A）；若在 Client 侧调用，必须通过已有 CRUD 接口立即保存结果（方案B） |
-| 为保存插件结果单独新建 API 端点（如 `PATCH /api/xxx/ai-analysis`） | 优先复用已有的业务 CRUD 接口（create/update）扩展字段，或在 Server 侧 Service 中调用插件并直接落库 |
-| 创建了 PluginInstance 但未生成调用代码（只建不调） | CREATE 后**必须**接着调用 get_plugin_ai_json → 生成调用代码 → 集成到业务逻辑 |
-| 插件返回值用 `as any` 直接取字段，无类型保护 | 根据 outputSchema 生成 TypeScript interface，用类型断言替代 `as any` |
-| 插件调用失败后 `console.error` 静默吞异常 | 必须向用户展示错误或触发补偿机制（见"错误处理规范"章节） |
-| 向插件输入参数注入 UUID/时间戳来"绕缓存" | 禁止污染业务参数，AI 插件无请求级缓存（见"缓存与幂等性"章节） |
-| 通知类插件的接收人 ID 硬编码在**代码**中（如 `const userId = '185410...'`） | 固定接收人 → 在 plugin_instance CREATE 的 `formValue.receiverUserList` 中直接配置；动态接收人 → 从配置/平台 API/DB 获取（见"参数来源规范"章节） |
-
-## 业务语义映射约定
-
-用户会用「AI 生文」「AI 生图」「发送飞书消息」等**业务语言**描述需求；这些关键词必须被识别为**待使用或待创建的 PluginInstance**。
-
-开发流程：
-1. 收到需求后，先看可用的 PluginInstance 是否有可以直接使用的插件实例
-2. 若有候选但不确定是否满足，调用 `get_plugin_ai_json` 查看其 actions/schema/outputMode 再决策
-3. 若无，立即调用 `plugin_instance` 工具新建
-4. **在 Client 侧**生成调用代码（默认），仅在必要场景使用 Server 侧
-
-## 插件调用错误处理规范
-
-### 错误分类与应对
-
-| 错误类型 | 含义 | 应对策略 |
-|----------|------|---------|
-| `InputValidationError` | 入参不符合 schema | 修复参数后重试，不应出现在生产环境 |
-| `RateLimitError` | 触发限流 | 指数退避重试（1s/2s/4s），最多 3 次 |
-| `ExecutionError` | 插件执行失败 | 记录日志 + 降级方案（如规则计算）+ 通知用户 |
-| `OutputValidationError` | 返回值不符合 schema | 记录异常返回 + 使用默认值或降级 |
-| 网络超时 | 请求超时 | 重试 + 超时后降级 |
-| **CREATE-time 平台返回缺必填配置** | `plugin_instance(CREATE)` 返回"请前往预览右边的插件配置页面..."类错误 | 原样转告用户 + 等待用户在 UI 完成配置 + 用户通知后调 `plugin_instance(UPDATE)` 重试 + 调 `get_plugin_ai_json` → `capabilityClient` / `capabilityService` 真实调用；**严禁 mock fallback** |
-
-### 必须遵守的规则
-
-1. **禁止静默吞异常**: 每个 `catch` 块必须满足以下至少一项：
-   - 向用户展示错误提示（前端 toast / 页面状态标记）
-   - 触发补偿机制（重试 / 降级 / 记录待处理列表）
-2. **异步操作必须有终态**: 如果插件调用是异步的（不阻塞主流程），必须在 DB 中维护状态（pending → success / failed），前端必须展示 failed 状态，不能永远停在 pending/loading。
-3. **通知类插件失败必须有补偿**: 如 `send-feishu-message` 失败，至少记录到"待发送"列表，或在 UI 中提示"通知发送失败，请手动联系"。
-4. **CREATE 失败严禁 mock fallback**: `plugin_instance(CREATE)` 失败时（特别是平台返回"缺必填配置"类错误）必须按上表 CREATE-time 行的 4 步处理，不接受 `setTimeout` / `sessionStorage` / 硬编码作为应急 fallback。
-
-### 插件配置完整性（load 前必查）
-
-`capabilityClient.load(pluginInstanceId)` 前必须确认对应 PluginInstance 配置已存在（通过 `plugin_instance` 工具创建/更新，禁止手写 `server/capabilities/`），且 id 与代码中 `pluginInstanceId` 完全匹配；否则抛 `CapabilityNotFoundError`（开发态 Top 错误）。
+飞书通知/卡片插件中回链本应用页面的按钮深链，必须是**带 basePath 的绝对 URL**，Server 侧构造后作为 input 传给插件（capability 的 url 用 `{% raw %}{{input.xxx}}{% endraw %}` 引用）：
 
 ```typescript
-// ✅ load/call 失败时停止后续请求，避免重复 load 放大错误（单应用可达每页 4-6 次失败）
-try {
-  const result = await plugin.call('read_records', input);
-} catch (err) {
-  if (err.name === 'CapabilityNotFoundError') { setConfigError(true); return; }
-  throw err;
-}
+// req.hostname = 网关公网域名（trust proxy 已开），禁止用 req.headers.host
+// CLIENT_BASE_PATH = 平台注入的内置 env = /app/{appId}，最容易漏、缺它必 404
+const url = `https://${req.hostname}${process.env.CLIENT_BASE_PATH}${routePath}`;
 ```
 
-**缓存 load 结果**，同一 pluginInstanceId 不重复 load。
-
-## 缓存与幂等性
+**禁止**：相对路径、占位/硬编码域名、只拼域名漏 basePath、`FORCE_FRAMEWORK_DOMAIN_MAIN`（客户端编译期变量，服务端 undefined）——否则飞书点开是「404 资源不存在」。
 
-- AI 类插件（text-generate/text-to-json 等）**没有请求级缓存**。同样的输入可能返回相似结果，这是 LLM 在低 temperature 下的正常行为，不是缓存。
-- **禁止**通过修改业务参数（如在 job_description 中注入 UUID）来"绕缓存"。这会污染 AI 输入，导致输出包含垃圾文本。
-- 如果确实需要不同结果，正确做法：
-  1. 调整插件实例的 `formValue.modelParams.temperature`（提高随机性）
-  2. 在 prompt 中增加明确的变化要求（如"请生成与之前不同的版本"）
-  3. 使用不同的业务上下文（如不同的候选人简历）
+## 常见错误速查
 
-## 插件参数来源规范
-
-插件的 inputSchema 参数分为两类：
-
-| 类型 | 来源 | 示例 |
-|------|------|------|
-| 业务数据 | 从 DB 查询或前端传入 | 候选人姓名、简历内容、职位描述 |
-| 运行时配置 | 从配置/环境变量/平台 API 获取 | 接收人 user_id、通知模板、阈值 |
-
-**禁止**在业务代码中硬编码运行时配置值（如 `const userId = '185410...'`）。正确做法取决于值是否固定：
-
-| 场景 | 正确做法 | 示例 |
-|------|---------|------|
-| 需求明确的**固定**接收人/配置 | 在 `plugin_instance CREATE` 的 `formValue` 中直接写死 | `formValue.receiverUserList: ["1854102143505690"]` |
-| **动态**接收人/配置（按角色/条件变化） | 从配置/平台 API/DB 获取，传入 `input` 参数 | `formValue.receiverUserList: "{{input.receiverIds}}"` |
-
-> **关键区分**：`formValue` 中配置固定值 ≠ 代码中硬编码。`formValue` 是插件实例的声明式配置，修改不需要改代码；而代码中硬编码的值散落在业务逻辑中，难以维护。
-
-当接收人/配置值是动态的，获取途径：
-1. 通过平台角色 API 获取（如"所有 admin_hr 角色的用户"）
-2. 存入应用配置表，通过 API 读取
-3. 通过环境变量注入
+| 错误做法 | 正确做法 |
+|---------|---------|
+| 不涉及持久化仍在 Server 侧写调用代码 / 为纯展示场景建后端 API 中转 | 即时展示、发消息等优先 Client 侧直接调 `capabilityClient`；涉及持久化才走 Server 侧 |
+| `call()` 签名错误：`plugin.call(JSON.stringify({...}))` 或 `plugin.call({...})` | 第一个参数必须是 actionKey 字符串：`plugin.call('actionKey', {...})` |
+| 流式 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 接口保存 |
+| 创建了 PluginInstance 但只建不调 | CREATE 后必须接 `get_plugin_ai_json` → 生成调用代码 → 集成业务逻辑 |
+| 插件返回值 `as any` 直接取字段 | 按 outputSchema 生成 TypeScript interface |