@lark-apaas/coding-steering 0.1.32-dev.942e73f → 0.1.32-dev.a04167f

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

@@ -17,6 +17,7 @@ file-match-pattern:
 |------|----------------------|--------------------------|
 | 鉴权 | 写操作加 `@NeedLogin()` | **不加** `@NeedLogin()`，鉴权在网关层通过 API Key 完成 |
 | 用户身份 | `req.userContext.userId` 区分用户 | 统一走系统身份，不依赖 `userId` 做业务区分 |
+| 通讯录 | 前端搜人 / 选择器随便用 | **必须**用 `AuthNPaasService.listUsersByIds`（见下文「用户信息」强制规则），搜索类不可用 |
 | Controller 文件 | `xxx.controller.ts` | `xxx.openapi.controller.ts`，放在同一 module 下 |
 | OpenAPI 文档 | 不需要 | **必须**同步维护 `docs/openapi.json`（见下文） |
 
@@ -59,6 +60,80 @@ findAll(@Req() req: Request) {
 }
 ```
 
+## 用户信息（通讯录）—— 强制规则
+
+**`/openapi` 路由下查询用户信息，唯一允许的实现是 `AuthNPaasService.listUsersByIds`。没有例外。**
+
+```typescript
+// ✅ 唯一允许的写法。注意 import 自 fullstack-nestjs-core（项目统一入口）
+import { AuthNPaasService } from '@lark-apaas/fullstack-nestjs-core';
+
+@Controller('openapi/xxx')
+export class XxxOpenApiController {
+  constructor(private readonly authn: AuthNPaasService) {}
+
+  @Get(':id')
+  async get(@Param('id') id: string) {
+    // 不要 try/catch 吞掉——平台故障必须暴露给调用方，别降级成「查无此人」
+    const [user] = await this.authn.listUsersByIds([id]);
+    if (!user) throw new NotFoundException(`用户 ${id} 不存在`);
+    return {
+      miaodaUserId: id,
+      name: user.name?.zh_cn ?? user.name?.en_us ?? '',  // name 是 I18nText，不是字符串
+      avatar: user.avatar?.image?.large ?? '',           // 头像 URL 在 image.large 上
+    };
+  }
+}
+```
+
+**不要做这两件多余的事**（`PlatformModule.forRoot()` 已经注册了 global 的 `AuthNPaasModule`）：
+
+- ❌ 在业务 module 里写 `providers: [AuthNPaasService]` —— 会另建一个实例
+- ❌ 往 `package.json` 加 `@lark-apaas/nestjs-authnpaas` 直接依赖 —— 走 `fullstack-nestjs-core` 即可
+
+### 禁止（以下任一出现即为错误实现）
+
+| ❌ 禁止 | 为什么 |
+|---|---|
+| 复用应用里已有的用户 / 用户资料 service | 那些多半是给浏览器写的，依赖登录态；`/openapi` 下没有登录用户，会静默返回空 |
+| 自己写 HTTP 请求裸调平台通讯录接口 | 鉴权 / 重试 / 日志 / trace 都在 SDK 里，裸调必然漏 |
+| 用 `req.userContext.userId` 做用户查询 | `/openapi` 下**恒为空** |
+| 用 `AuthNPaasService.getCurrentUserLarkUserId()` | 它读 `userId`，取不到只打日志返回 `null`、**不报错**，故障静默 |
+| 从数据库表里 join 出人名 / 头像 | 通讯录不是应用数据，会过期且不 follow 权限 |
+| 按关键词搜人 / 搜部门 / 搜群 | 结果取决于「谁在搜」，`/openapi` 下没有调用者视角，**服务端不提供** |
+| `try/catch` 吞掉 `listUsersByIds` 抛的错、返回空值 | 「平台挂了」和「查无此人」是两回事，吞掉就没人知道故障 |
+| 用 `getBatchLarkUserIds` 判断用户是否存在 | 它是 ID 转换，**外部用户本来就没有 employeeId**，会把外部用户误判成不存在 |
+| 服务端拿不到的字段用 `''` 占位塞进响应 | 调用方会以为字段存在只是没值。拿不到就**从响应类型里删掉**，并告诉用户改走飞书开放平台通讯录 API |
+
+```typescript
+// ❌ 错误：包了一层应用现有的用户服务
+const profile = await this.userProfileService.findById(id);
+
+// ❌ 错误：OpenAPI 态搜不了人
+const users = await someSearchApi({ query: keyword });
+
+// ❌ 错误：读 userId，OpenAPI 态恒为空且失败不报错
+const larkId = await this.authn.getCurrentUserLarkUserId();
+
+// ❌ 错误：吞掉平台故障 + 拿不到的字段用空串占位
+let name = '';
+try {
+  const [u] = await this.authn.listUsersByIds([id]);
+  name = u?.name?.zh_cn ?? '';
+} catch { /* 平台挂了也当查无此人 */ }
+return { userId: id, name, department: '', email: '', jobTitle: '' };
+```
+
+### `AuthNPaasService` import 不到时
+
+说明当前 `@lark-apaas/fullstack-nestjs-core` 版本还没带上这个能力。**报告阻塞、请人升级 core 版本**——不要加 `@lark-apaas/nestjs-authnpaas` 直接依赖绕过去，也不要退回上面任何一种禁止写法或自己实现替代品。
+
+### 服务端拿不到的字段
+
+手机号 / 职位 / 工号 / 直属上级 / 在职状态、以及按 ID 查群 —— 服务端**没有**这些能力。需要就走飞书开放平台通讯录 API，或把该能力放回前端做，**不要**在 `/openapi` 里自己拼一个。
+
+完整能力边界与字段口径见 [`contacts-service` › 第六节](../contacts-service/SKILL.md)。
+
 ## 模块组织
 
 `/openapi` Controller 和 `/api` Controller 放在**同一个 module** 下，共享 Service 层。用文件名 `xxx.openapi.controller.ts` 区分。

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

@@ -20,8 +20,10 @@ gate-tools:
 | 获取运行时投影 | 调用 `get_plugin_ai_json(pluginInstanceId)` |
 | Client 侧调用 | `capabilityClient.load(id).call(actionKey, input)`（流式用 `callStream`） |
 | Server 侧调用（仅兜底） | `capabilityService.load(id).call(actionKey, input)` |
+| 长耗时 AI 结果 | 大体量/多字段/多份/多语言/文件或多模态串联等结构信号命中时，优先前端 `callStream` 渐进展示；需保存则流式结束后复用 CRUD 落库；仅在 Client 侧无法满足时使用后端任务记录 + 状态查询 + 结果读取；禁止单个 HTTP 请求等待完整结果后才返回 |
 | capabilityClient 导入 | `import { capabilityClient } from '@lark-apaas/client-toolkit'` |
 | CapabilityService 导入 | `import { CapabilityService } from '@lark-apaas/fullstack-nestjs-core';` |
+| CapabilityService 注入 | `@Inject(CapabilityService) private readonly capabilityService: CapabilityService`（**禁止空参 `@Inject()`**，会导致启动崩溃 502；业务 Module 无需 imports） |
 
 ## 必读 references
 
@@ -70,6 +72,7 @@ gate-tools:
    - 必须先调 `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 侧
+   - 高耗时 AI capability 闸门：若运行时投影或功能设计显示输出规模大、输出字段多、需要多份结果、多语言/长文本、文件或多模态输入后继续生成、多个 capability 串联、或结果需后续查看/落库，禁止把完整生成放进一个同步 HTTP 请求等待；能由前端承接时优先 `callStream` 渐进展示，需保存则流式结束后复用 CRUD 落库；仅在 Client 侧无法满足时后端创建任务记录后快速返回、由前端短轮询状态/结果，或拆成多个独立小调用
 4. **代码放置**：Client（默认，用户交互触发）→ `client/` 组件/hooks；Server（兜底）→ `server/` Service。
 5. **真实调用冒烟（完成前必须）**：至少成功调用一次 `call()` 或 `callStream()`（按 outputSchema 读 chunk）；失败日志含最小字段（字段清单见 `references/plugin-coding-guide.md`）。无冒烟结果不得宣告完成。
 
@@ -136,6 +139,9 @@ const structured = await capabilityClient
         ├── 输出包含多个独立字段（标题+正文+评分等）
         │   → 拆成多个独立插件并行调用（⭐ 优先）或用 ai-text-to-json
         │   → ⛔ 禁止用 ai-text-generate + 正则/split 解析多字段
+        ├── 输出规模大（多份结果、多语言、长正文、多章节或批量对象）
+        │   → 优先拆分为多个独立生成单元；需要汇总持久化时使用任务状态模型承接
+        │   → ⛔ 禁止一个后端 HTTP 请求同步等待所有生成结果后才响应
         └── 输出为单一文本（仅展示，不需解析）→ ai-text-generate
 ```
 
@@ -203,9 +209,9 @@ const structured = await capabilityClient
 
 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`
+3. **长耗时 AI 生成不得同步等完**：大体量、多字段、多份、多语言、文件/多模态串联或需要持久化的 AI capability 调用，触发接口必须快速返回任务状态或采用前端流式展示；若 `api_request`、浏览器操作或页面请求出现超时/连接断开，不能只凭服务端最终日志或数据库最终写入宣告成功，必须证明用户侧存在可读取的终态结果
+4. **通知类插件失败必须有补偿**：如 `send-feishu-message` 失败，至少记录"待发送"列表或 UI 提示"通知发送失败，请手动联系"
+5. **配置完整性（load 前必查）**：`load(id)` 前确认实例已创建且 id 与代码完全匹配，否则抛 `CapabilityNotFoundError`（开发态 Top 错误）；load/call 失败时停止后续请求避免放大错误；**缓存 load 结果**，同一 id 不重复 load
 
 ## 缓存与幂等性
 
@@ -240,7 +246,7 @@ const structured = await capabilityClient
 
 ### 通知接收人动态解析
 
-接收人（`receiverUserList`/`receiverGroupList` 等）按角色/条件变化时，必须实时查询角色成员经 `input` 传入（角色/成员的运行时查询写法见 `authz-guide` 技能），禁止硬编码或凭经验拼装 ID。如引入缓存，必须提供显式失效手段（如角色变更时清缓存）并明示 TTL，禁止无失效手段的常驻缓存导致接收人信息过期。通知发送失败的补偿要求见上文「插件调用错误处理」第 3 条铁律，不重复展开。
+接收人（`receiverUserList`/`receiverGroupList` 等）按角色/条件变化时，必须实时查询角色成员经 `input` 传入（角色/成员的运行时查询写法见 `authz-guide` 技能），禁止硬编码或凭经验拼装 ID。如引入缓存，必须提供显式失效手段（如角色变更时清缓存）并明示 TTL，禁止无失效手段的常驻缓存导致接收人信息过期。通知发送失败的补偿要求见上文「插件调用错误处理」第 4 条铁律，不重复展开。
 
 ## 飞书深链 URL 规范
 

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

@@ -2,15 +2,19 @@
 
 ### 核心原则：根据场景选择调用侧
 
-**默认优先在 Client 侧调用 capabilityClient；但当插件结果需要持久化到数据库时，应考虑在 Server 侧调用或确保前端调用后及时通过后端接口保存。**
+**默认优先在 Client 侧调用 capabilityClient；流式或高耗时 AI 生成优先 `callStream` 渐进展示。结果需要持久化时，优先在流式结束后通过已有后端接口保存；只有 Client 侧无法满足时才切到 Server 侧。**
+
+**高耗时 AI capability 先判调用形态**：只要输出规模大、输出字段多、需要多份结果、多语言/长文本、文件或多模态输入后继续生成、多个 capability 串联、或结果需后续查看/落库，就不得把完整 AI 结果塞进一个同步 HTTP 请求等待。能由前端承接时，优先用前端 `callStream` 渐进展示，并在流式结束后按需复用已有 CRUD 接口保存结果；只有 Client 侧无法满足（触发器/敏感凭证/强事务/必须由后端保证落库一致性等）时，才采用后端任务记录 + 状态/结果查询，避免把后台任务作为默认方案。
+
 **严禁** import ｛ capabilityClient ｝ from '@lark-apaas/client-capability'。
 **唯一指定**的导入方式是 import { capabilityClient } from '@lark-apaas/client-toolkit';
 
 | 优先级 | 场景 | 调用方式 |
 |-------|------|---------|
-| **首选** | 绝大多数场景 | `capabilityClient.load(id).call()` |
-| **首选** | 流式输出场景 | `capabilityClient.load(id).callStream()` |
-| **兜底** | Client 侧无法满足时 | `CapabilityService.load(id).call()` |
+| **首选** | 绝大多数即时展示场景 | `capabilityClient.load(id).call()` |
+| **首选** | 流式输出，或高耗时但可由前端承接的 AI 生成 | `capabilityClient.load(id).callStream()`（流式结束后按需持久化） |
+| **必要时** | 高耗时且 Client 侧无法满足：触发器、敏感凭证、强事务、必须由后端保证落库一致性 | 后端任务记录 + 后台调用 `CapabilityService.load(id).call()` + 前端短轮询状态/结果 |
+| **兜底** | Client 侧无法满足且单次调用可在交互边界内完成 | `CapabilityService.load(id).call()` |
 
 #### 什么情况下应使用 Server 侧？
 
@@ -19,7 +23,7 @@
 1. **涉及敏感凭证**：调用需要服务端私密 token/secret，不适合暴露给前端
 2. **必须后端编排**：多个插件调用之间有强事务依赖，需要后端统一编排
 3. **触发器/定时任务场景**：没有前端上下文，只能由后端发起
-4. **插件结果需要持久化**：调用结果需要保存到数据库，在 Server 侧可以在同一方法中完成调用+落库，保证数据一致性
+4. **插件结果需要持久化**：调用结果需要保存到数据库；能由前端承接时，优先前端 `callStream` 渐进展示并在结束后复用已有 CRUD 接口保存；只有 Client 侧无法满足或必须由后端保证落库一致性时，才在 Server 侧调用并落库。若此时输出规模大、字段多、结果多份或需多步能力串联，必须改为任务记录 + 后台执行 + 状态/结果查询，避免一个 HTTP 请求等待完整生成
 
 > **提示**：如果插件结果不需要存储、仅用于即时展示（如流式生成文本、发送消息），优先在前端调用。但当结果需要保存到数据库时，不要回避使用 Server 侧。
 
@@ -42,9 +46,13 @@
 
 ```
 插件结果是否需要持久化到数据库？
-├── 否（一次性即时展示）→ Client 侧调用（默认）
-└── 是 → 推荐方案 A：Server 侧调用，在 Service 中调用插件并在同一方法中落库
-         备选方案 B：Client 侧调用插件 → 成功后通过已有 CRUD 接口保存结果
+├── 否（一次性即时展示）
+│   ├── `outputMode=stream` 或内容生成较慢 → Client 侧 `callStream()` 渐进展示
+│   └── 单次短输出 → Client 侧 `call()`（默认）
+└── 是
+    ├── `outputMode=stream` 且前端可承接 → 推荐方案 A：Client 侧 `callStream()` 渐进展示，成功后通过已有 CRUD 接口保存结果
+    ├── 输出较小且可在交互边界内完成、且必须由后端保证一致性 → Server 侧调用并在同一方法中落库
+    └── Client 侧无法满足且输出规模大/多字段/多份/多语言/多步骤 → 方案 B：Server 侧创建任务记录，快速返回任务状态；后台调用插件并落库；前端短轮询状态/结果
 ```
 
 | 应避免的做法 | 推荐做法 |
@@ -79,12 +87,18 @@
 #### call / callStream 函数签名
 
 ```typescript
-.call(actionKey: string, input: object)       // 非流式，返回 Promise<output>
-.callStream(actionKey: string, input: object)  // 流式，返回 AsyncIterable<chunk>
+// 前端 capabilityClient（@lark-apaas/client-toolkit，实际类型来自 @lark-apaas/client-capability）
+.call<T = unknown>(actionKey: string, params?: Record<string, unknown>): Promise<T>              // 非流式
+.callStream<T = unknown>(actionKey: string, params?: Record<string, unknown>): AsyncIterable<T>  // 流式
 ```
 
 - **第一个参数 `actionKey`**：必须是字符串，值来自 `get_plugin_ai_json` 返回的 `actions[].key`（如 `'sendFeishuMessage'`、`'textGenerate'`）
-- **第二个参数 `input`**：必须是对象，结构符合 `actions[].inputSchema`
+- **第二个参数 `params`**：类型是 `Record<string, unknown>`，结构符合 `actions[].inputSchema`
+- 上面是**前端**签名，带泛型。**服务端 `CapabilityService` 的 `call` / `callStream` / `callStreamWithEvents` 都没有泛型**，两者不通用，详见「Server 侧调用方式」
+
+> **`Record<string, unknown>` 不接 `interface` 声明的对象**（interface 没有隐式索引签名），直接传会撞
+> `Argument of type 'XxxInput' is not assignable to parameter of type 'Record<string, unknown>'. Index signature for type 'string' is missing in type 'XxxInput'.`
+> 三种正确写法：① 直接传内联对象字面量；② 入参类型用 `type XxxInput = { ... }` 而非 `interface`（type 别名有隐式索引签名）；③ 已有 interface 时在调用点显式 `input as unknown as Record<string, unknown>`。**不要为此改用 `as any`。**
 
 ```typescript
 // ❌ 错误：把参数 JSON.stringify 后当作 actionKey
@@ -271,10 +285,11 @@ function MultiPluginStreamExample({ recordId }: { recordId: string }) {
 2. 一个 `stream` action 的真实调用结果（chunk 按 `outputSchema` 字段读取）
 3. 调用失败时的最小日志字段齐全
 4. 若无法执行真实调用，必须明确写明阻塞原因，禁止直接标记“开发完成”
+5. 若用户触发 AI 生成的请求超时、连接断开或工具返回超时，必须判定为验收失败；只有触发请求快速返回、随后能通过页面或接口读到明确完成或失败终态和结果，才允许标记通过
 
 ### Server 侧调用方式（仅兜底场景）
 
-> 以下场景适合使用 Server 侧调用，特别是涉及数据持久化时不要回避后端。
+> 以下场景适合使用 Server 侧调用；若前端 `callStream` + 既有 CRUD 保存即可满足展示和持久化，不要优先引入后端后台任务。
 
 #### 1. 何时适合用 Server 侧？
 
@@ -285,6 +300,7 @@ function MultiPluginStreamExample({ recordId }: { recordId: string }) {
 | 敏感凭证调用 | 凭证不能暴露给前端 | 调用需要 admin token 的 API |
 | 强事务编排 | 多步骤需要原子性 | 创建记录 → 发通知 → 更新状态必须全成功或全回滚 |
 | 插件结果需持久化 | 调用结果需保存到数据库 | AI 分类/摘要结果需落库、文档解析的结构化数据需入库、图片识别结果需关联业务记录、语音转文字结果需存档等 |
+| 高耗时 AI 生成需后续查看 | 请求不能长期占用用户交互链路 | 批量、多版本、多语言、长文本、多字段结构化生成，或文件/多模态分析后再生成内容 |
 
 #### 2. NestJS 注入方式
 
@@ -296,23 +312,49 @@ import { CapabilityService } from '@lark-apaas/fullstack-nestjs-core';
 export class XxxService {
   private readonly logger = new Logger(XxxService.name);
 
+  // 注入 token 必须显式写成 @Inject(CapabilityService)
   constructor(
-    @Inject() private readonly capabilityService: CapabilityService,
+    @Inject(CapabilityService) private readonly capabilityService: CapabilityService,
   ) {}
 }
 ```
 
+**禁止空参 `@Inject()`**。本 stack 的 `nest-cli.json` 用 `builder: swc`，空参 `@Inject()` 会把注入 token 置为 undefined，Nest 回退读 `design:type` 拿到 `Function`，服务端启动即崩溃、所有 `/api` 请求返回 502：
+
+```
+UnknownDependenciesException: Nest can't resolve dependencies of the XxxService (?).
+Please make sure that the argument Function at index [0] is available in the XxxModule context.
+```
+
+见到这段报错先查构造函数有没有空参 `@Inject()`，不要去改 Module 的 `imports` / `providers`。
+
+**业务 Module 不需要注册 CapabilityModule**。`PlatformModule` 是 `@Global()` 且已把 `CapabilityModule` 放进 `exports`，`CapabilityService` 全局可注入。不要在业务 Module 里写 `imports: [CapabilityModule.forRoot(...)]` 或 `imports: [PlatformModule.forRoot()]`。
+
+同一规则适用于从 `@lark-apaas/fullstack-nestjs-core` 注入的其他平台服务（`AuthNPaasService`、`FileService` 等）。
+
 #### 3. 调用示例
 
+服务端 `CapabilityExecutor` 的**三个方法全都没有泛型参数**（`@lark-apaas/nestjs-capability`）：
+
+```typescript
+call(actionName: string, input: unknown, context?: Partial<PluginActionContext>): Promise<unknown>;
+callStream(actionName: string, input: unknown, context?): AsyncIterable<unknown>;
+callStreamWithEvents(actionName: string, input: unknown, context?): AsyncIterable<StreamEvent<unknown>>;
+```
+
+写 `.call<T>(...)` / `.callStream<T>(...)` / `.callStreamWithEvents<T>(...)` 都会报「应有 0 个类型参数，但获得 1 个」。泛型只存在于前端 `capabilityClient`。注意服务端 `input` 是**必传**（没有 `?`），且类型是 `unknown` 而非前端的 `Record<string, unknown>`。服务端接 `unknown` 后在运行时收窄，禁止 `as any`：
+
 ```typescript
 const inputParams = {
   // 严格按 get_plugin_ai_json.actions[].inputSchema 构造
 };
 
 try {
-  const output = await this.capabilityService
+  const output: unknown = await this.capabilityService
     .load('')
     .call('', inputParams);
+  // 运行时收窄后再取字段，例如：
+  // if (typeof output === 'object' && output !== null && 'content' in output) { ... }
   return output;
 } catch (error) {
   this.logger.error('pluginInstance call failed', {
@@ -328,6 +370,7 @@ try {
 
 - PluginInstance 调用在 Server 侧通常属于 **外部依赖 / side-effect**
 - 除非业务明确要求强一致性，**默认不应阻塞主业务流程**
+- 已选择 Server 侧承接的高耗时 AI capability 必须有可观测状态：创建任务时记录处理进度、完成终态、失败终态、输入摘要、错误信息和结果引用；触发接口只返回任务标识与当前状态，前端通过短轮询读取进度和最终结果
 
 推荐写法：异步触发 + catch 兜底：
 

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

@@ -11,7 +11,7 @@ match-template-name: nestjs-react-fullstack
 在 NestJS 服务端代码中使用 `FileService` 进行文件上传、下载、删除和管理。
 
 > **使用注意**: 仅用于服务端文件处理场景，非必要文件上传下载场景请使用前端 `client-builtins-file-storage-service` skill。
-> **入口边界**：本 SDK 是**服务端代码**读写应用存储的入口；Agent 在对话 / 开发中自己上传或调试文件用 `miaoda file` CLI（见 `miaoda-file` skill）。二者与本 SDK 操作同一个应用存储桶，但 **`miaoda file` CLI 禁止写进服务端代码**。
+> **入口边界**：本 SDK 是**服务端代码**读写应用存储的入口；Agent 在对话 / 开发中自己上传或调试文件，先加载应用文件存储操作 skill（按「应用文件存储 / 文件上传 / 文件下载」召回），用其 CLI 命令操作，具体命令一律以该 skill 为准。二者与本 SDK 操作同一个应用存储桶，但**该 CLI 命令只供 Agent 在沙箱终端使用，禁止写进服务端代码**。
 
 ## 使用场景
 

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

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

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

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

package/steering/nestjs-react-fullstack/skills_common/mcp-guide/assets/ui-tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "allowJs": true,
+    "checkJs": true,
+    "types": ["react", "react-dom"],
+    "skipLibCheck": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "baseUrl": "../../..",
+    "paths": { "@shared/*": ["shared/*"] }
+  },
+  "include": ["./**/*.ts", "./**/*.tsx", "./**/*.js", "./**/*.jsx", "./**/*.mts", "./**/*.cts", "./**/*.mjs", "./**/*.cjs"]
+}

package/steering/nestjs-react-fullstack/skills_common/mcp-guide/references/client-onboarding.md

@@ -0,0 +1,82 @@
+# 接入：把本应用的 MCP 连到外部客户端
+
+适用于「应用已经有 MCP 工具，用户要在自己的 Agent（Claude Code / Codex / 其它 MCP 客户端）里调用它」。开发态自己验工具走 `debugging.md` 的 `mcp_inspect`，与本文无关。
+
+**产出是一条用户复制即可执行的命令，不是操作说明。**连接地址和凭证都由你查出来填好，不要让用户自己去界面上找。
+
+## 取连接配置
+
+```bash
+lark-cli apps +mcp-get --app-id "$app_id" --include-secret
+```
+
+`data.config` 里是完整的 `mcpServers` 对象，含连接地址与 `X-Mcp-Token`。不加 `--include-secret` 拿到的是脱敏展示（`data.redacted=true`），不能用于连接。
+
+命令语义、风险等级与权限要求以 `lark-apps-ops` 的 `references/lark-apps-mcp.md` 与各命令 `--help` 为准，本文不复述。两条只在这里强调：
+
+- **该命令会创建缺失的运行态凭证，风险是 `write`。**不要仅为「看看这应用开没开 MCP」而调用它。重复调用返回已有凭证，不轮换、不重置。
+- 拿不到命令（沙箱 CLI 版本不带该子命令）时如实告知用户，**不要自己拼连接地址兜底**——地址形如 `https://<租户域名>.<环境后缀>/mcp/app`，两段都不可推测。
+
+## 服务名你来起
+
+`<名字>` 会成为客户端里的工具前缀（`mcp__<名字>__<工具名>`），用户此后每次看到这些工具都要读它。**直接给一个贴合本 MCP 用途的名字，不要问用户要。**
+
+- 取材于这个 MCP 做什么：差旅审批叫 `travel-approval`，库存查询叫 `inventory`
+- 小写字母 + 数字 + `-` 或 `_`，两三个词以内；不要空格、点号、中文
+- 同一台机器内唯一。用户可能已经接过别的妙搭应用，泛指类的名字会撞上
+- server 声明的 `serverName` 一眼能看出这个 MCP 做什么时，直接用它，保持开发态与客户端一致
+- 给完顺带说一句名字可改，但不要停下来等用户确认
+
+## 落到客户端
+
+从 `data.config` 的 `mcpServers` 条目里取出连接地址与请求头，连同上面定好的名字填进下面对应模板，整条给用户。
+
+**Claude Code**
+
+```bash
+claude mcp add --transport http <名字> <连接地址> --header "X-Mcp-Token: <凭证>"
+claude mcp login <名字>
+```
+
+**Codex**
+
+```bash
+codex mcp add <名字> --url "<连接地址>?x-mcp-token=<凭证>"
+codex mcp login <名字>
+```
+
+`codex mcp add` 没有传请求头的参数，凭证走 query 参数。不要用 `--bearer-token-env-var`，它会走静态 token 分支把 OAuth 跳过去。
+
+## 为什么是两条命令
+
+`X-Mcp-Token` 认「连的是哪个应用」，第二条命令办的是「谁在调用」——浏览器里完成一次飞书授权，客户端拿到用户令牌并自行续期。两者缺一都连不上，也互相替代不了。应用凭证不是用户身份，查出凭证不等于用户已获授权。
+
+`login` 只服务 HTTP 传输。用户若报「only supported for streamable HTTP servers」，是配置成了本地 stdio 形态，按上面的模板改成 `url` 形式。
+
+## 两件命令解决不了的事
+
+凭证能提前建，但要真正调通还需要：
+
+| 条件 | 不满足时的表现 |
+|---|---|
+| 应用已发布且线上 MCP 已启用 | 连接失败；创建凭证不要求发布，所以拿到凭证不代表能连 |
+| 调用人在应用可用范围内 | 403，与凭证是否有效无关 |
+
+这两条你查不到也改不了，连不上时按下表对号，属于这两类就直接告诉用户去处理，不要反复重试。
+
+## 排错
+
+| 现象 | 原因 | 动作 |
+|---|---|---|
+| 401，reason `lark_oauth_client_mismatch` | 授权用的 client_id 与服务端元数据不一致 | 清掉客户端授权缓存重新 `login` |
+| 401，reason `lark_oauth_conf_unavailable` | 平台侧配置问题 | 告知用户找平台同学，不要让他反复重试 |
+| 401，无 reason | 凭证复制不全，或配的是预览态凭证 | 重新 `+mcp-get --include-secret` 取一次，整段替换 |
+| 403 `user is not in the visible scope of this app` | 不在可用范围，或授权账号不属于应用租户 | 前者找负责人放开范围；后者换应用租户内的账号授权 |
+| 404 | 应用没启用 MCP；或零工具零资源无应用 Skill（SDK 此时也返回 404） | 后者是正常状态不是故障，先确认本应用确实注册了工具 |
+| POST 被拒，CSRF 相关 | 旧模板应用对 POST 有 CSRF 双提交校验 | 平台侧已知未收口项，告知用户，不在客户端侧拼 cookie 绕 |
+
+## 凭证纪律
+
+- `--include-secret` 的输出只用于拼那条给用户的命令。**不写进项目任何文件、不进日志、不复述进汇报与摘要、不提交仓库。**
+- 保持客户端默认的 local scope；不要建议 `--scope project`——那会把凭证写进随代码提交的配置文件。
+- 用户自己贴出过凭证（聊天、issue、文档）时提醒他重置，旧值立即失效。

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

@@ -0,0 +1,81 @@
+# 调试：mcp_inspect、错误定位、本地模式
+
+本文说的「沙箱」= 工具清单里有 `mcp_inspect` 的环境（妙搭云端 code-agent）；「本地模式」= 没有 `mcp_inspect`、在开发者本机跑 `npm run dev` 的环境。先看自己有哪个，再读对应部分。
+
+## mcp_inspect
+
+云端沙箱里的开发态 MCP 调试工具。它经 MCP 网关连当前应用的开发态 MCP Server，以当前用户身份发起，与预览页里操作应用的身份一致。
+
+| action | 参数 | 返回 |
+|---|---|---|
+| `list_tools` | 无 | server 名、每个工具的 name / title / description / annotations / `_meta.ui` / inputSchema（长 schema 截断）、资源清单 |
+| `call` | `tool_name`（带 prefix 的完整名）、`arguments`（JSON 对象**字符串**，缺省 `{}`）、`safe` | 文本内容、`structuredContent`、`isError`、耗时；正文整体超 12k 字符时从尾部截断，`structuredContent` 的末尾最先被吃掉。脱敏后的完整结果超过 12k 字符时落盘到 `tmp/<会话>/tool/<调用ID>/result.json`，结果尾部给出路径，需要全量数据时 `read_file` 读它，不要缩小入参反复重调 |
+| `read_resource` | `resource_uri`（如 `ui://order/list`） | uri、mimeType、`_meta.ui`、正文前若干字符 |
+
+- `safe`：工具未声明 `annotations.readOnlyHint: true` 时，`call` 在发起前被拒为 `requires_safe`。只有这次调用影响的是你自建、且事后能自己清掉的数据时才传 `safe: true`；用户已有的真实数据未经明确要求不动。只读工具反复撞这条，是源码漏了 `readOnlyHint: true`，补注解而不是加 `safe`。
+- 单个子请求 60s 无动静即超时，整次动作 600s 硬上限。server 是无状态 JSON 模式（不开 SSE），`ctx.extra.sendNotification` 发的 `notifications/progress` 到不了客户端、不会重置计时；超时只能靠缩小单次处理范围。
+- 同一工具连续失败 4 次熔断 60s：先改代码或入参，不是等。`requires_safe`、`tool_not_found`、`aborted` 不计入熔断。
+- 失败或 `isError: true` 时结果尾部附 Trace-ID 对应的 `server.log` / `trace.log` 片段。
+
+**目录接口**：`GET http://localhost:<CLIENT_DEV_PORT><CLIENT_BASE_PATH>/__innerapi__/mcp/manifest`（`CLIENT_DEV_PORT` 默认 8080；`CLIENT_BASE_PATH` 沙箱里是平台下发的 `/app/<appId>`，漏了前缀拿不到 JSON，取值以 `.env.local` 或 dev server 启动日志为准）返回 `tools` / `resources` / `prompts` / `skills[]`（含 frontmatter 的完整正文）与源码定位，不要求身份，有无 `mcp_inspect` 都能 curl。应用 Skill 是 Prompt 不是资源，`mcp_inspect` 的三个动作都碰不到它，核对它只走这里。
+
+## 回路
+
+1. 改工具 / 资源 / 界面。
+2. 等 dev server 重启（`nest --watch` 会自动重启；界面改动由 `[mcp-ui]` 插件自动重建）。定义有问题会让应用起不来并打印「MCP 定义校验失败」，修完再往下走。
+3. `list_tools` 核对清单与源码一致（`visibility: ['app']` 的工具也在清单里，属正常）。
+4. `call` 逐个只读工具跑一次真实入参。写工具只在能自己清掉痕迹（有对应删除 / 撤销工具，或业务上可撤回）时才真调并随手清理；否则只验证入参校验与 `McpToolError` 分支，汇报里写明「写入链路未真实验证」。
+5. 带界面的工具 `read_resource`。
+6. 每个 `McpToolError` 分支构造一次触发（不存在的 ID、非法状态），确认 `isError: true` 且 `code` 与 `description` 预告一致。
+7. 更新 `server/mcp/skills/<name>/SKILL.md`，再 curl 目录接口（frontmatter 不合法这里会 500）：`skills[]` 有该 `name`、`content` 是最新正文，`prompts[]` 的 `description` 一致。
+
+## 错误分流
+
+| 现象 | 原因 | 动作 |
+|---|---|---|
+| 端点 404「当前工程可能尚未接入 MCP 层，或 dev server 尚未就绪」 | `server/mcp` 不存在；dev server 没起来；零工具零资源无应用 Skill（SDK 此时返回 404） | 确认三者；有工具但 404 看启动日志是否被校验阻断 |
+| `list_tools` 少了某个工具 | 类没进任何模块 `providers`，无任何日志提示 | 对照启动日志「已注册 N 个 MCP 工具：…」，缺的加进所属业务模块的 `providers` |
+| dev server 起不来，报「MCP 工具必须使用单例及单例依赖」 | 工具类或其依赖是 request / transient 作用域 | 改回单例，身份从 `ctx.user` 取 |
+| 启动日志「MCP 定义校验失败」 | 工具名不合法 / 重名、资源 URI 不以 `ui://` 开头 / 重名、`ui.resourceUri` 找不到 `@McpUiResource()`、同一方法同时标两个装饰器 | 按日志逐条列的问题逐个修 |
+| `tool_not_found` | 名字没带 prefix，或用了 `title` | 用 `list_tools` 里的 name |
+| `requires_safe` | 见上文 `safe` | 只读工具补注解；写工具按回路第 5 步——能清掉痕迹才 `safe: true`，否则只验错误分支 |
+| `isError` + `code: MCP_USER_REQUIRED`（`prompts/get` / `resources/read` 则是 JSON-RPC error） | 请求没带用户身份：有 `mcp_inspect` 的环境里 curl 直连 dev server / NestJS 端口就是这样 | 无身份的 curl 只做 `tools/list`、`prompts/list`、`resources/list` 与目录接口；`tools/call` / `resources/read` 走 `mcp_inspect`，Prompt 正文看目录接口的 `skills[].content`。不改 `requireUser`、不拼身份头 |
+| `isError` + 业务 `code` | 工具按设计抛了 `McpToolError` | 对照 `description` 检查是否预告了该 code；入参是否真的该触发 |
+| `isError` + 通用失败提示 | 方法抛了非 `McpToolError` 的异常 | 读结果尾部 Trace-ID 日志定位；该异常若是可预期的业务失败，改抛 `McpToolError` |
+| zod 校验错误 | 入参不符 inputSchema | 对照 `list_tools` 里的 schema 改 `arguments`；schema 本身不合理就改源码 |
+| 「工具已执行，但输出与其声明的 outputSchema 不符」 | `structuredContent` 与 `outputSchema` 对不上 | 工具已跑通：改返回值或改 schema，不重试同一调用 |
+| `timeout` | 单个子请求 60s 无动静，或整次超 600s | 收窄入参 / 分页 / 拆成「发起 + 查状态」两个工具；加进度通知无效（JSON 模式发不出去） |
+| `connect_failed` / `http_error` / `unauthorized` | 网关或预览环境问题；`http_error` 500 先对下面 frontmatter 那行，应用自己也会 500 | 看 statusCode；不是应用代码问题时告知用户，不改代码绕 |
+| `jsonrpc_error` + `data.code: MCP_APP_REVISION_MISMATCH` | 调用方带的应用修订与当前产物不一致（改代码、改界面、改应用 Skill、dev server 重启都会变），**本次业务未执行** | 重新 `list_tools` 取最新清单再调；不要原样重试，也不要把这当业务失败去改工具代码 |
+| `jsonrpc_error` + `data.code: MCP_APP_REVISION_UNAVAILABLE` | 产物是旧版构建、不带修订，而调用方带了预期修订 | 同步新版构建脚本后重新发布；在那之前不要启用依赖修订的绑定 |
+| 「已连续 4 次调用失败，已暂停对它的重复调用」 | 同一工具连续失败 4 次熔断 | 先修实现或入参，60s 后再验 |
+| 「当前运行环境不支持开发态 MCP 调试」 | 本地 CLI 宿主没有 `mcp_inspect` 后端 | 走下节本地模式 |
+| `read_resource` 报「读取 MCP Apps 界面产物失败」 | `dist/mcp-ui/<entry>.html` 不存在 | 入口名对齐 `readMcpUiTemplate('<entry>')`；确认 `server/mcp/ui/<entry>/index.html` 存在；看 `[mcp-ui]` 日志是否构建失败 |
+| dev server 日志 `[mcp-ui] 构建失败：MCP UI 不能引用应用或服务端代码 / Node.js 模块` | 界面 import 了 `client/`、`server/` 的业务代码或 Node 内置模块；HTML `src`、CSS `url()` 指到界面目录外也算 | 把依赖挪进 `server/mcp/ui/` 或 `shared/`；不改预设配置 |
+| `mcp_inspect` 任一动作 `http_error` 500、目录接口 500，server 日志有「处理 MCP 请求失败」、栈首行是「MCP Skill …」 | 某份 `server/mcp/skills/*/SKILL.md` frontmatter 不合法：缺 frontmatter、`name` 与目录名不等、`description` 空、重名、超限 | 按日志文案修 frontmatter |
+
+同一失败不原样重试。改完代码再验，每轮只改一个变量。
+
+## 本地模式（工具清单里没有 `mcp_inspect` 时才适用）
+
+本地开发（`MIAODA_LOCAL_DEV=1`，`npm run dev` 走 `dev-local.js`）没有 `mcp_inspect`，MCP 客户端是你自己或 IDE 里的 Agent。
+
+- 带身份的入口只有 dev server：`http://localhost:<CLIENT_DEV_PORT><CLIENT_BASE_PATH>/__innerapi__/mcp`（`CLIENT_BASE_PATH` 以 `.env.local` 为准，`+env-pull` 拉下来的是 `/app/<appId>`）。dev server 代理把 `+env-pull` 拉到的 `SUDA_WEBUSER` 注入为身份头，工具里的 `ctx.user` 就是开发者本人。直连 NestJS 端口没有身份，会撞 `MCP_USER_REQUIRED`。
+- 标准 MCP 客户端配置 Streamable HTTP、URL 填上面地址即可连接。
+- 看原始请求响应：`npx @modelcontextprotocol/inspector`，指向同一地址。
+- 快速验证：
+
+```bash
+curl -s -X POST 'http://localhost:<port><base>/__innerapi__/mcp' \
+  -H 'content-type: application/json' \
+  -H 'accept: application/json, text/event-stream' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+`accept` 必须同时含两种类型，否则 406。`GET` / `DELETE` 返回 405，端点只接受 `POST`；目录接口见上文。
+
+## 汇报
+
+- 用业务表述：「`order_search` 返回 3 条待支付订单」「取消不存在的订单返回 ORDER_NOT_FOUND，符合预期」；不贴整段 JSON。
+- 写工具真调过的，说明动了哪些数据、是否已清理；没真调的写明「写入链路未真实验证」。
+- 未验证的分支明说未验证，不写「已全部通过」。