@lark-apaas/coding-steering 0.1.13-alpha.0 → 0.1.13-alpha.1

package/package.json

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

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

@@ -29,7 +29,7 @@ lark-cli apps --help 2>&1 | grep -q '+plugin-install' && echo "READY" || echo "M
 |------|------|
 | 插件包管理（安装/卸载/查看） | 由 lark-apps skill 引导，参考其 plugin reference 文档 |
 | 创建实例 | 设计 paramsSchema/formValue → 自查规则 → 写入配置文件（见 Create 链路） |
-| 获取调用投影 | `npx @lark-apaas/miaoda-cli plugin list --id <id>`（见调用代码生成） |
+| 获取插件调用代码编写依据 | 按「插件调用代码编写依据」章流程获取 |
 | Client 侧非流式调用 | `capabilityClient.load(id).call(actionKey, input)` |
 | Client 侧流式调用 | `capabilityClient.load(id).callStream(actionKey, input)` |
 | Server 侧调用（仅兜底） | `capabilityService.load(id).call(actionKey, input)` |
@@ -234,6 +234,7 @@ const structured = await capabilityClient
 ```
 
 **关键区分**：
+
 - formValue 的 **key** = Plugin form.schema 的字段名（如 `prompt`、`content`、`fileUrl`）
 - formValue 的 **value** 中通过 `{{input.xxx}}` 引用 paramsSchema 定义的变量
 - 变量名（paramsSchema）与 form 字段名（form.schema）分属不同层，通常名称不同
@@ -243,21 +244,25 @@ const structured = await capabilityClient
 #### 支持的参数类型（仅 4 种）
 
 **文本**：
+
 ```json
 { "type": "string", "description": "文本参数描述" }
 ```
 
 **数组**：
+
 ```json
 { "type": "array", "description": "描述", "items": { "type": "string", "description": "元素描述" } }
 ```
 
 **图片**：
+
 ```json
 { "type": "array", "format": "plugin-image-url", "description": "描述", "items": { "type": "string" } }
 ```
 
 **文件**：
+
 ```json
 { "type": "array", "format": "plugin-file-url", "description": "描述", "items": { "type": "string" } }
 ```
@@ -341,16 +346,19 @@ const structured = await capabilityClient
 #### 各场景 Prompt 模板
 
 **文本生成类**：
+
 ```json
 "prompt": "你是一位资深的[平台名]内容创作专家。\n\n请根据以下关键词生成一篇文案：\n关键词：{{input.keywords}}\n\n内容要求：\n1. 标题（15-25字）\n2. 正文（300-500字）\n3. 结尾设置互动问题"
 ```
 
 **图片理解类**：
+
 ```json
 "prompt": "你是一位专业的图像分析专家。\n\n请对提供的图片进行深度分析：\n1. 基础信息：图片类型、主体内容\n2. 细节描述：颜色、构图、关键元素\n3. 语义理解：含义、情感、用途\n\n{{input.additional_requirements}}"
 ```
 
 **文生图类**：
+
 ```json
 "prompt": "请生成一张高质量图片：\n\n主题内容：{{input.subject}}\n\n画面要求：风格、构图、光线、色调\n质量要求：画面清晰、主体突出"
 ```
@@ -393,23 +401,22 @@ const structured = await capabilityClient
 5. **自查规则** — 写入前逐条对照 §一致性铁律 检查：变量引用是否对称、类型是否允许、是否使用了禁止的模板语法、数组是否有 items。发现违规立即修正，超过 3 次仍未通过则上报用户
 6. **写入实例配置** — 将以下结构写入 `server/capabilities/<id>.json`（或步骤 3 确定的路径）：
 
-```json
-{
-  "id": "<id>",
-  "pluginKey": "<pluginKey>",
-  "pluginVersion": "<version>",
-  "name": "<实例名称>",
-  "description": "<实例描述>",
-  "paramsSchema": { ... },
-  "formValue": { ... },
-  "createdAt": <unix毫秒>,
-  "updatedAt": <unix毫秒>
-}
-```
-
-7. **获取调用投影** — `npx @lark-apaas/miaoda-cli plugin list --id <id>`
-   → 合并 manifest actions 与实例配置，输出含 `actions[]` 的完整投影
-8. **编写调用代码** — 基于投影 + `references/plugin-coding-guide.md`。**禁止凭记忆猜测**
+   ```json
+   {
+     "id": "<id>",
+     "pluginKey": "<pluginKey>",
+     "pluginVersion": "<version>",
+     "name": "<实例名称>",
+     "description": "<实例描述>",
+     "paramsSchema": { ... },
+     "formValue": { ... },
+     "createdAt": <unix毫秒>,
+     "updatedAt": <unix毫秒>
+   }
+   ```
+
+7. **获取插件调用代码编写依据** — 必须按「插件调用代码编写依据」章的获取流程执行（含多级 Fallback）。未成功获取 → 禁止进入步骤 8
+8. **编写调用代码** — 基于步骤 7 的结果，**禁止凭记忆猜测**
 
 大 JSON 场景先写临时文件再读取，避免命令行转义问题。
 
@@ -420,8 +427,8 @@ const structured = await capabilityClient
 1. `cat server/capabilities/<id>.json` → 查看当前实例配置
 2. 读 manifest + 设计修改方案（改 name / formValue / paramsSchema）
 3. 改后逐条对照 §一致性铁律 自查，修正后写回配置文件，更新 `updatedAt`
-4. paramsSchema 变化 → `grep -rn "load('${id}')" <project-path>/` 扫描代码引用并更新
-5. 重新获取调用投影：`npx @lark-apaas/miaoda-cli plugin list --id <id>`
+4. **获取插件调用代码编写依据** — 按「插件调用代码编写依据」章的获取流程执行
+5. paramsSchema 变化 → 基于步骤 4 的结果扫描代码引用并更新
 
 ### Delete 链路
 
@@ -438,7 +445,7 @@ const structured = await capabilityClient
 | 所有实例概览 | `ls server/capabilities/` |
 | 单个实例完整配置 | `cat server/capabilities/<id>.json` |
 | 插件的 actions/schema | `cat node_modules/<pluginKey>/manifest.json` |
-| 获取调用投影 | `npx @lark-apaas/miaoda-cli plugin list --id <id>` |
+| 获取插件调用代码编写依据 | 按「插件调用代码编写依据」章流程获取 |
 
 ### 常见违规及修正
 
@@ -452,9 +459,9 @@ const structured = await capabilityClient
 
 ---
 
-## 调用代码生成
+## 插件调用代码编写依据
 
-### 调用前获取权威依据（每次编写/修改调用代码前必做）
+### 获取调用依据（每次编写/修改调用代码前必须执行）
 
 **首次尝试**：
 
@@ -491,6 +498,7 @@ npx @lark-apaas/miaoda-cli plugin list --id <instance_id>
 | 全栈应用（NestJS + React） | Client 侧（首选）或 Server 侧 |
 
 **Server 侧仅在以下场景使用**：
+
 1. 涉及敏感凭证（token/secret 不能暴露给前端）
 2. 多步骤强事务编排
 3. 触发器/定时任务（无前端上下文）
@@ -501,6 +509,7 @@ npx @lark-apaas/miaoda-cli plugin list --id <instance_id>
 ### 持久化决策
 
 以下任一条件成立时，插件结果**必须**保存到数据库：
+
 1. 结果会在其他页面展示
 2. 结果供后续功能消费
 3. 用户再次访问时需要看到结果
@@ -513,7 +522,6 @@ npx @lark-apaas/miaoda-cli plugin list --id <instance_id>
 
 ---
 
-
 | 错误类型 | 含义 | 应对策略 |
 |----------|------|---------|
 | `InputValidationError` | 入参不符合 schema | 修复参数后重试 |
@@ -522,6 +530,7 @@ npx @lark-apaas/miaoda-cli plugin list --id <instance_id>
 | `OutputValidationError` | 返回值不符合 schema | 记录异常返回 + 使用默认值 |
 
 **规则**：
+
 1. **禁止静默吞异常**：每个 `catch` 块必须向用户展示错误或触发补偿
 2. **异步操作必须有终态**：DB 中维护状态（pending → success / failed）
 3. **插件失败必须有补偿**：至少记录到待处理列表或提示用户重试
@@ -565,7 +574,7 @@ npx @lark-apaas/miaoda-cli plugin list --id <instance_id>
 1. **写入实例配置前必须自查** — 逐条对照 §一致性铁律 检查参数定义与引用的对称性、类型合法性、模板语法限制。自查通过后再写入配置文件。
 2. **先装包再建实例** — 创建插件实例前必须确保插件包已安装。
 3. **校验失败走重试** — max 3 次，3 次仍失败上报用户。
-4. **写代码前获取调用投影** — `npx @lark-apaas/miaoda-cli plugin list --id <id>` 或手动合并 manifest + capability JSON。禁止凭记忆猜测 actionKey / inputSchema / outputMode。
+4. **写代码前获取插件调用代码编写依据** — 必须按「插件调用代码编写依据」章流程获取。禁止凭记忆猜测 actionKey / inputSchema / outputMode。
 5. **禁止用 `npm install` 安装插件包** — 插件包和 npm 包是两套独立机制。
 6. **禁止 Mock** — 必须走真实插件实例调用链路。
 7. **formValue 禁止 Handlebars 控制语法** — 仅允许 `{{input.xxx}}`。

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

@@ -47,7 +47,9 @@
 ### Client 侧调用方式（默认首选）
 
 #### 1. 调用前获取权威依据
+
 在为某个插件实例生成调用代码前，必须先通过 `get_plugin_ai_json` 工具获取该插件实例的运行时投影（plugin_Instance.ai.json），并以其中信息为准：
+
 - `actions[].key`：调用时要传的 `actionKey`
 - `actions[].inputSchema / outputSchema`：入参/出参结构
 - `actions[].outputMode`：`unary | stream`（决定调用与结果处理方式）
@@ -150,7 +152,7 @@ function readFirstStringField(
 
 **核心原则**：在插件设计阶段按「原子化拆解」拆分，避免单插件返回多字段 JSON。
 
-#####  推荐：多插件并行流式
+##### 推荐：多插件并行流式
 
 适用于需求涉及多种输出（标题、正文、图片等），各输出相对独立。
 
@@ -312,6 +314,7 @@ this.somePluginInstanceSideEffect(input).catch(error => {
 | 任意（兜底场景） | Server 侧 | `capabilityService.load(id).call(actionKey, input)` |
 
 **选择原则**：
+
 - 不涉及持久化时，优先在 Client 侧直接调用
 - `outputMode = stream` 时，Client 侧使用 `callStream` 做渐进式渲染
 - 涉及持久化、触发器、敏感凭证、事务编排等场景时，使用 Server 侧

package/steering/design-stack/skills_local/plugin-guide/SKILL.md

@@ -1,316 +0,0 @@
----
-name: plugin-guide
-description: AI 新版插件集成规范与 Plugin 链路指南。支持AI智能生文、AI智能生图、AI图片理解、AI文档解析、AI结构化提取、AI图片处理等。Use when 需要：(1) 创建或管理 PluginInstance 插件实例，(2) 调用 capabilityClient 生成插件调用代码，(3) 编写 capabilityClient 调用代码。触发词：插件, plugin, AI生文, AI生图, 图片理解, 文档解析, 结构化提取, capabilityClient, pluginInstance
-compatibility: "requires: lark-cli with plugin commands (apps +plugin-install, +plugin-uninstall, +plugin-list). If not met, tell user: lark-cli 当前版本不支持插件能力，请升级到最新版本"
-when_to_use: "lark-cli apps +plugin-* commands are available. If not, tell user: lark-cli 当前版本不支持插件能力，请升级到最新版本"
-steering: true
-steering-topic: plugin_guide
-match-template-name: design-stack
----
-
-# Plugin 集成指南
-
-AI 新版插件集成规范与 Plugin 链路指南。支持的能力包括：AI智能生文、AI智能生图、AI图片理解、AI文档解析（PDF/DOC/PPTX等）、AI结构化提取（文本→JSON、图片→JSON）、AI内容摘要、AI翻译、AI语音合成与识别、AI图片处理（抠图/换背景/风格转换）等。本文档介绍插件实例配置、调用投影的获取方式，以及 `capabilityClient` 调用入口。
-
-## ⚠️ 前置门禁
-
-本 skill 依赖 lark-cli 的插件管理能力。开始前先确认当前环境是否可用：
-
-```bash
-lark-cli apps --help 2>&1 | grep -q '+plugin-install' && echo "READY" || echo "MISSING"
-```
-
-- **READY** → 继续
-- **MISSING** → 当前 lark-cli 版本不支持插件命令，请更新到最新版后重试：
-
-## ⚠️ 铁律：禁止 Mock 插件调用
-
-**当 AGENTS.md 包含「插件规划」时，所有规划的插件必须创建实例并通过 `capabilityClient` 真实调用。**
-
-| 禁止 | 正确 |
-|------|------|
-| ❌ `setTimeout` + 硬编码数据模拟 AI 返回 | ✅ `capabilityClient.load(id).call(actionKey, input)` |
-| ❌ `picsum.photos` / 随机图片替代 AI 生图 | ✅ `capabilityClient.load(id).call('textToImage', {...})` |
-| ❌ 注释掉 `capabilityClient` import 用 Mock 函数 | ✅ 真实 import 并调用 |
-| ❌ AGENTS.md 规划了插件但 `server/capabilities/` 为空 | ✅ 每个规划的插件都有对应 JSON 文件 |
-
-> **与 Mock 展示数据的区别**：design_agent prompt 中的 "Mock 数据仅用于无附件的 prototype" 指的是表格示例行、卡片占位文本等**展示数据**。AI 生文/生图/翻译/结构化等**插件能力不属于 Mock 数据范围**，必须真实调用。
-
-## Quick Reference
-
-| 操作 | 方式 |
-|------|------|
-| 插件包管理（安装/卸载/查看） | 由 lark-apps skill 引导，参考其 plugin reference 文档 |
-| 创建实例 | 设计 paramsSchema/formValue → 自查规则 → 写入配置文件（见 Create 链路） |
-| 获取调用投影 | `npx @lark-apaas/miaoda-cli plugin list --id <id>`（见调用代码生成） |
-| 非流式调用 | `capabilityClient.load(id).call(actionKey, input)` |
-| 流式调用 | `capabilityClient.load(id).callStream(actionKey, input)` |
-| capabilityClient 导入 | `import { capabilityClient } from '@lark-apaas/client-toolkit'` |
-| 插件实例配置位置 | `server/capabilities/<instance_id>.json`（默认纯前端应用 / appType=3）。见「配置目录」段 |
-
-> **capabilityClient 导入警告**：`capabilityClient` 是从 `@lark-apaas/client-toolkit` 直接导入的独立对象，**不是**从 `getDataloom()` 上获取的。错误写法：`const dataloom = await getDataloom(); (dataloom as any).capability` — 这样写不会工作。正确且唯一的方式：`import { capabilityClient } from '@lark-apaas/client-toolkit'`。
-
-## Plugin 代码编写指南
-
-以下场景**必须**先读取 `references/plugin-coding-guide.md` 再编写代码：
-
-- 编写 `capabilityClient` 调用代码时（含导入路径、调用方式）
-- 处理流式输出（`outputMode = stream`），包括多插件并行流式、单插件 JSON 流式解析
-- 需要根据 `outputMode` 选择 `call()` 或 `callStream()` 时
-
-## 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` | 两张图→对比分析（流式） |
-
-### 决策树：选择单步还是链式
-
-```
-输入是什么？
-├── 文档文件 → 必须先用 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（⭐ 单步直达！）
-    └── 摘要/翻译/分类/生成 → 对应单插件即可
-```
-
-### 常见 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` | 商品图→电商主图 |
-
-### 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` 支持此能力，SDK 自动处理文件上传。
-
-### 创建结构化提取 PluginInstance 的关键要求
-
-创建 `ai-text-to-json` 或 `ai-image-to-json` 类型的 PluginInstance 时：
-1. **必须一次性定义所有需要提取的字段**（参考数据库 schema / 表单定义 / UI 设计），宁多勿漏
-2. 字段类型仅支持 String / Number / Boolean，最多 20 个字段
-3. 先获取调用投影确认上游插件的 `outputSchema`，确保输入格式正确
-4. 图片→结构化数据场景，优先使用 `ai-image-to-json`（单步），避免不必要的链式调用
-
-## 核心概念
-
-- **插件包（Plugin Package）**：npm 格式的功能包，安装到 `node_modules/`，含 `manifest.json` 描述 actions 和 form.schema。
-- **插件实例（Plugin Instance / Capability）**：基于插件包创建的业务配置，存储在 `server/capabilities/{id}.json`（默认纯前端应用，路径规则见「配置目录」），定义 `paramsSchema`（业务入参）和 `formValue`（表单映射，通过 `{{input.xxx}}` 引用 paramsSchema 参数）。
-- **变量映射**：`调用方传值 → paramsSchema 定义变量 → formValue 消费变量 {{input.xxx}} → Plugin form.schema 接收`。
-
-### 插件包 ≠ npm 包（必读）
-
-| | 插件包 | npm 依赖 |
-|------|------|------|
-| 写入字段 | `package.json` → **`actionPlugins`** | `package.json` → `dependencies` / `devDependencies` |
-| 用途 | 妙搭平台 AI 能力 | 项目依赖库 |
-| **禁止** | ❌ 不能用 `npm install` 装插件包 | ❌ 不能用 `npm install` 管理插件包 |
-
-两套机制完全独立。混淆会导致运行时找不到插件。
-
-### 插件实例配置目录
-
-插件实例配置文件（`<instance_id>.json`）存放在 capabilities 目录下。按以下优先级确定路径：
-
-1. 环境变量 `MIAODA_CAPABILITIES_DIR` → 直接使用
-2. 环境变量 `MIAODA_APP_TYPE` 或 `.env.local` 中的 `MIAODA_APP_TYPE`：
-   - `6` → `shared/capabilities/`（纯前端应用 appType=6）
-   - 其他 → `server/capabilities/`（Design 应用 appType=3）
-3. 以上都未设置 → 默认 `server/capabilities/`
-
-目录不存在时 `mkdir -p` 创建。
-
-### 插件实例配置结构
-
-写入 `server/capabilities/<id>.json` 的 JSON 结构：
-
-```json
-{
-  "id": "<语义化ID>",
-  "pluginKey": "<pluginKey>",
-  "pluginVersion": "<version>",
-  "name": "<实例名称>",
-  "description": "<实例描述>",
-  "paramsSchema": { ... },
-  "formValue": { ... },
-  "createdAt": <unix毫秒>,
-  "updatedAt": <unix毫秒>
-}
-```
-
-**paramsSchema 支持 4 种参数类型**：
-
-1. **文本**：`{ "type": "string", "description": "..." }`
-2. **数组**：`{ "type": "array", "description": "...", "items": { "type": "string" } }`
-3. **图片**：`{ "type": "array", "format": "plugin-image-url", "description": "...", "items": { "type": "string" } }`
-4. **文件**：`{ "type": "array", "format": "plugin-file-url", "description": "...", "items": { "type": "string" } }`
-
-只允许 string 和 array 两种 type。array 必须有 items。format 只允许 `plugin-image-url` 或 `plugin-file-url`。
-
-> **注意**：`format: "plugin-image-url"` 和 `format: "plugin-file-url"` 的字段支持直接传入 File/Blob 对象，`capabilityClient` SDK 会自动处理上传。
-
----
-
-## CRUD 链路
-
-### Create 链路
-
-创建一个**插件实例**，即能力目录下的 `<id>.json` 配置文件。
-
-1. **安装插件包** — 由 lark-apps skill 引导完成
-2. **读 manifest** — `cat node_modules/<pluginKey>/manifest.json`
-3. **确定配置目录** — 按上方「插件实例配置目录」规则确定，不存在则 `mkdir -p` 创建
-4. **设计实例配置** — 确定 id / name / paramsSchema / formValue
-5. **自查规则** — 写入前逐条检查：变量引用对称、类型合法、禁止模板控制语法、array 有 items。违规修正，超过 3 次上报用户
-6. **写入配置文件** — 按上方 JSON 结构写入
-7. **获取调用投影** — `npx @lark-apaas/miaoda-cli plugin list --id <id>`
-8. **编写调用代码** — 基于投影。**禁止凭记忆猜测**
-
-### Update 链路
-
-1. `cat server/capabilities/<id>.json` → 查看当前配置
-2. 读 manifest + 设计修改方案。不修改 id / pluginKey / pluginVersion / createdAt
-3. 改后自查规则，修正后写回，更新 `updatedAt`
-4. paramsSchema 变化 → `grep -rn "load('${id}')"` 扫描代码引用并更新
-5. 重新获取调用投影：`npx @lark-apaas/miaoda-cli plugin list --id <id>`
-
-### Delete 链路
-
-1. `cat server/capabilities/<id>.json` → 确认实例存在
-2. `grep -rn "load('${id}')"` → 扫描代码引用，有则先清理
-3. `rm server/capabilities/<id>.json`
-
----
-
-## 调用投影
-
-### 获取调用投影（每次编写/修改调用代码前必做）
-
-```bash
-npx @lark-apaas/miaoda-cli plugin list --id <instance_id>
-```
-
-输出含 `actions[].key`、`inputSchema`、`outputSchema`、`outputMode`，是编写调用代码的唯一依据。
-
-### 充血 Fallback 链
-
-`npx @lark-apaas/miaoda-cli plugin list --id <id>` → 失败则 `npx fullstack-cli capability list --id <id>` → 失败则 `node .agents/skills/plugin-guide/scripts/plugin-hydrate.js <pluginKey> <instanceId>` → 失败则手动合并 manifest + capability JSON。
-
-### 无 Node.js 环境
-
-1. 告知用户未安装 Node.js
-2. 手动合并 manifest + capability JSON
-3. 如果插件有 `{dynamic: true}`：读插件源码推导逻辑 → 基于推导编写代码 → 运行正确则成立，报错则上报用户
-
-### 调用代码
-
-根据 `actions[].outputMode` 选择调用方式：
-- `unary` → `capabilityClient.load(id).call(actionKey, input)`
-- `stream` → `capabilityClient.load(id).callStream(actionKey, input)`
-
-**必读**：`references/plugin-coding-guide.md`
-
-### 代码放置
-
-调用代码放在 `client/` 目录下的组件/hooks 中，由用户交互触发。
-
----
-
-
-## 业务语义映射约定
-
-用户会用「AI 生文」「AI 生图」「AI 摘要」等**业务语言**描述需求；这些关键词必须被识别为**待使用或待创建的 PluginInstance**。
-
-开发流程：
-1. 收到需求后，先 `ls server/capabilities/` 看是否有可复用的实例
-2. 若有候选但不确定是否满足，获取调用投影查看其 actions/schema/outputMode 再决策
-3. 若无，按 Create 链路新建实例
-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/design-stack/skills_local/plugin-guide/references/plugin-coding-guide.md

@@ -1,126 +0,0 @@
-## PluginInstance 代码编写指南
-
-### 核心原则
-
-**严禁** import ｛ capabilityClient ｝ from '@lark-apaas/client-capability'。
-**唯一指定**的导入方式是 import { capabilityClient } from '@lark-apaas/client-toolkit';
-
-| 场景 | 调用方式 |
-|------|---------|
-| 非流式调用 | `capabilityClient.load(id).call()` |
-| 流式输出场景 | `capabilityClient.load(id).callStream()` |
-
----
-
-### 调用方式
-
-#### 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`
-
-```typescript
-// ❌ 错误：把参数 JSON.stringify 后当作 actionKey
-plugin.call(JSON.stringify({ meeting_title: '...' }));
-// ❌ 错误：漏掉 actionKey，直接传参数对象
-plugin.call({ meeting_title: '...' });
-
-// ✅ 正确：第一个参数是 actionKey 字符串，第二个参数是 input 对象
-plugin.call('send_feishu_message', { meeting_title: '...' });
-```
-
-#### 2. 非流式调用（outputMode = "unary"）
-
-```typescript
-import { capabilityClient } from '@lark-apaas/client-toolkit';
-import { logger } from "@lark-apaas/client-toolkit/logger";
-
-const result = await capabilityClient
-  .load('create_feishu_group')
-  .call('createGroup', {
-    group_name: '项目讨论群',
-    members: ['user_001', 'user_002'],
-  });
-
-logger.info(result);
-```
-
-#### 3. 流式调用（outputMode = "stream"）
-
-##### 场景判断与推荐方案
-
-| 场景 | 特征 | 推荐度 |
-|-----|------|-------|
-| **多插件并行流式** | 多个插件各返回单一输出，并行调用 |  **优先推荐** |
-| **单插件 JSON 流式解析** | 单插件返回结构化 JSON，需边接收边解析 | ⚠️ 仅在必要时 |
-
-**核心原则**：在插件设计阶段按「原子化拆解」拆分，避免单插件返回多字段 JSON。
-
-#####  推荐：多插件并行流式
-
-适用于需求涉及多种输出（标题、正文、图片等），各输出相对独立。
-
-```tsx
-import { logger } from "@lark-apaas/client-toolkit/logger";
-
-function MultiPluginStreamExample() {
-  const [title, setTitle] = useState('');
-  const [content, setContent] = useState('');
-  const [coverUrl, setCoverUrl] = useState('');
-
-  const handleGenerate = async (keywords: string) => {
-    // 1. 封面图（非流式，异步不阻塞）
-    capabilityClient
-      .load('cover_generator')
-      .call<{ images: string[] }>('textToImage', { keywords })
-      .then(res => res?.images?.[0] && setCoverUrl(res.images[0]))
-      .catch(err => logger.warn('封面生成失败', err));
-
-    // 2. 标题（非流式）
-    capabilityClient
-      .load('title_generator')
-      .call<{ content: string }>('textGenerate', { keywords })
-      .then(res => res?.content && setTitle(res.content));
-
-    // 3. 正文（流式，边生成边展示）
-    const contentStream = capabilityClient
-      .load('content_generator')
-      .callStream<{ content: string }>('textGenerate', { keywords });
-
-    // 🎯 流式内容直接拼接，无需复杂解析
-    for await (const chunk of contentStream) {
-      setContent(prev => prev + (chunk.content || ''));
-    }
-  };
-
-  return (/* 各字段独立渲染 */);
-}
-```
-
-**优点**：代码简洁、各插件独立、某个失败不影响其他。
-
-##### ⚠️ 兜底：单插件 JSON 流式解析
-
-当无法拆分为多插件时，需处理不完整 JSON 的逐字符到达，需实现 `parseStreamingStringField` 和 `extractJsonObject` 工具函数。**强烈建议在插件设计阶段拆分为多插件并行流式调用，避免此场景。**
-
-### outputMode 与调用方式
-
-先通过 `get_plugin_ai_json(pluginInstanceId)` 获取 `actions[].outputMode`：
-
-| outputMode | 调用方式 |
-|------------|---------|
-| `unary` | `capabilityClient.load(id).call(actionKey, input)` |
-| `stream` | `capabilityClient.load(id).callStream(actionKey, input)` |
-
----