@lark-apaas/coding-steering 0.1.39 → 0.1.40-alpha.20260826112015

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.39",
+  "version": "0.1.40-alpha.20260826112015",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [
     "steering"
   ],
+  "scripts": {
+    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
+  },
   "devDependencies": {
     "markdownlint-cli": "^0.47.0"
   },
@@ -17,8 +20,5 @@
     "miaoda",
     "coding-steering"
   ],
-  "license": "MIT",
-  "scripts": {
-    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
-  }
-}
+  "license": "MIT"
+}

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

@@ -446,7 +446,6 @@ await db.select().from(users).where(eq(users.adminUser, userId));
    async submitPublic(@Body() dto) { ... }
    ```
 8. **OpenAPI 文档同步**：改动 `*.openapi.controller.ts` 或其引用的 interface / service 返回值 / schema 字段时，加载 `openapi-guide` skill，同步更新 `docs/openapi.json`
-9. **服务端查用户信息（CRITICAL）**：**必须** `import { AuthNPaasService } from '@lark-apaas/fullstack-nestjs-core'` 并用 `listUsersByIds`（`PlatformModule.forRoot()` 已注册 global 的 `AuthNPaasModule`，**不要**加 `providers`、**不要**加直接依赖）。**禁止**复用应用内已有的用户 service、裸调平台接口、从库表 join 人名头像、依赖 `req.userContext.userId`（`/openapi` 下恒为空）、`try/catch` 吞掉 SDK 抛的平台错误、用 `getBatchLarkUserIds` 判断用户是否存在（外部用户无 employeeId）、拿不到的字段用 `''` 占位。搜人 / 搜部门 / 搜群、手机号职位工号上级服务端**拿不到**，走飞书开放平台。动手前加载 `contacts-service` skill 第六节
 
 ## 异常处理
 

package/steering/nestjs-react-fullstack/skills/contacts-service/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: contacts-service
-description: "Use when 搜人/选人/人员选择器/部门选择器/群组选择、获取或展示用户与部门信息、把用户/部门/群组 ID 传给飞书内置插件或飞书开放平台 API、人员字段入库或导出，以及在产物服务端 / OpenAPI 接口里按 ID 查用户信息。统一妙搭 ID 体系（miaoda_user_id / employee_id / open_department_id / open_chat_id；lark_* 内部 ID 禁用）、字段获取分级与权限引导、服务端可用与不可用的通讯录能力边界。触发词：搜人, 选人, 人员选择器, 部门选择器, 群组选择, UserSelect, DepartmentSelect, ChatSelect, 获取用户信息, 用户字段, 部门信息, 群组信息, employee_id, open_id, union_id, open_department_id, open_chat_id, miaoda_user_id, lark_id, 飞书用户ID, 飞书部门ID, 外部用户, 工号, 手机号, 直属上级, 人员入库, 人员导出, id_convert, 通讯录, 选负责人, 选审批人, 传插件, 传开放平台, 选中的人传给, 把选中的人, 服务端查用户, 后端查用户, OpenAPI 查用户, 批量查用户, 按ID查人, AuthNPaasService, listUsersByIds"
+description: "Use when 搜人/选人/人员选择器/部门选择器/群组选择、获取或展示用户与部门信息、把用户/部门/群组 ID 传给飞书内置插件或飞书开放平台 API、人员字段入库或导出。统一妙搭 ID 体系（miaoda_user_id / employee_id / open_department_id / open_chat_id；lark_* 内部 ID 禁用）、字段获取分级与权限引导。触发词：搜人, 选人, 人员选择器, 部门选择器, 群组选择, UserSelect, DepartmentSelect, ChatSelect, 获取用户信息, 用户字段, 部门信息, 群组信息, employee_id, open_id, union_id, open_department_id, open_chat_id, miaoda_user_id, lark_id, 飞书用户ID, 飞书部门ID, 外部用户, 工号, 手机号, 直属上级, 人员入库, 人员导出, id_convert, 通讯录, 选负责人, 选审批人, 传插件, 传开放平台, 选中的人传给, 把选中的人"
 steering: true
 steering-topic: contacts_service
 match-template-name: nestjs-react-fullstack
@@ -10,9 +10,7 @@ match-template-name: nestjs-react-fullstack
 
 > 本 Skill 定义妙搭 Agent 处理**用户 / 部门 / 群组信息**的完整规范：ID 体系、接口返回结构、ID 选择决策、字段获取分级与权限引导。
 >
-> **相关 skill**：当前登录用户（"我是谁"、useCurrentUserProfile、req.userContext）见 [`user-identity`](../user-identity/SKILL.md)；选择器/展示组件的 props 与用法见 [`client-builtins-user-service`](../client-builtins-user-service/SKILL.md)；飞书原生接口（通讯录 API、id_convert）见 [`feishu`](../../../feishu/SKILL.md)；对外开放接口的编码规范见 [`openapi-guide`](../openapi-guide/SKILL.md)。
->
-> **⚠️ 先分流**：一~五节讲的是**浏览器里**的搜人 / 选择器口径。代码跑在**产物服务端**（NestJS service / controller，尤其 `*.openapi.controller.ts`）时，能力边界完全不同——直接看[第六节](#六服务端--openapi-态怎么查通讯录)。
+> **相关 skill**：当前登录用户（"我是谁"、useCurrentUserProfile、req.userContext）见 [`user-identity`](../user-identity/SKILL.md)；选择器/展示组件的 props 与用法见 [`client-builtins-user-service`](../client-builtins-user-service/SKILL.md)；飞书原生接口（通讯录 API、id_convert）见 [`feishu`](../../../feishu/SKILL.md)。
 
 ## 命名约定（必读）
 
@@ -200,68 +198,7 @@ match-template-name: nestjs-react-fullstack
 
 ---
 
-## 六、服务端 / OpenAPI 态怎么查通讯录
-
-### 6.1 为什么服务端不一样
-
-前端靠 cookie，网关校验登录态后注入 `x-larkgw-suda-webuser`；OpenAPI 请求**没有 cookie**，`req.userContext.userId` 恒为空。所以判据很简单：**「返回什么取决于调用者是谁」的能力在 OpenAPI 态一律不可用，「给定 ID 取数据」的可用**。
-
-### 6.2 服务端能做什么
-
-> **强制规则**：服务端（尤其 `/openapi`）查用户信息，**唯一允许的实现是 `AuthNPaasService.listUsersByIds`**（禁止项见 6.4.0）。`import` 不到说明 core 版本没跟上，**报告阻塞**，不要加直接依赖绕过、也不要自实现。
-
-**按 ID 批量查人** —— 从项目统一入口 `@lark-apaas/fullstack-nestjs-core` 取 `AuthNPaasService`。`PlatformModule.forRoot()` 已注册 global 的 `AuthNPaasModule`，**不需要**在业务 module 加 `providers`，也**不需要**加直接依赖：
-
-```ts
-import { AuthNPaasService } from '@lark-apaas/fullstack-nestjs-core';
-
-@Injectable()
-export class TicketService {
-  constructor(private readonly authn: AuthNPaasService) {}
-
-  async attachAssignees(ids: string[]) {
-    // 返回与入参等长同序，未命中的位置是 null
-    const users = await this.authn.listUsersByIds(ids);
-    return users.map((u, i) => ({
-      miaoda_user_id: ids[i],
-      name: u?.name?.zh_cn ?? u?.name?.en_us ?? '',  // name 是 I18nText，不是字符串
-      avatar: u?.avatar?.image?.large ?? '',          // 头像 URL 在 image.large 上
-    }));
-  }
-}
-```
-
-- 入参是 **miaoda_user_id**，单次最多 **100** 个；返回 `(MiaodaUserInfo | null)[]`，与入参等长同序，不丢项也不错位
-- 只有 `miaodaUserID` / `name` / `avatar` 三个字段——**没有**邮箱、手机号、工号、部门
-- 平台出错抛 `HttpException`(502)，**不会**静默返回空数组——**不要 try/catch 吞掉**，「平台挂了」和「查无此人」必须能区分
-- 服务端拿不到的字段（部门 / 邮箱 / 工号 / 职位）**从响应类型里删掉**，别用 `''` 占位骗调用方；**并告诉用户**这些字段要走飞书开放平台通讯录 API（见 6.3），不是没实现
-
-**妙搭 ↔ 飞书 ID 转换** —— 同一个 `AuthNPaasService` 上的 `getBatchLarkUserIds()` / `getBatchMiaodaUserIds()`（双向批量，不依赖调用者身份）。**不要拿它判断用户是否存在**——外部用户本来就没有 employeeId，会被误判成「用户不存在」。判存在性用 `listUsersByIds` 的返回是不是 `null`。
-
-### 6.3 服务端做不到什么，改走哪里
-
-| 想做的事 | 服务端 | 替代路径 |
-|---|:---:|---|
-| 按 ID 批量查人 | ✅ | `AuthNPaasService.listUsersByIds` |
-| 妙搭 ↔ 飞书 ID 转换 | ✅ | `AuthNPaasService.getBatchLarkUserIds` / `getBatchMiaodaUserIds` |
-| 搜人 / 搜部门 / 搜群（按关键词） | ❌ | 飞书开放平台通讯录 API（应用身份 + 显式授权的通讯录范围） |
-| 取手机号 / 职位 / 工号 / 直属上级 | ❌ | 同上，字段 ↔ 权限映射见 [`feishu` › contacts.md](../../../feishu/references/contacts.md) |
-| 知道「当前调用者是谁」 | ❌ | OpenAPI 语义上没有当前用户；内部 `/api` 路由才有 `req.userContext.userId` |
-| 按 ID 批量查群 | ❌ | 暂无服务端能力；群信息在前端取，或走开放平台 IM API |
-
-**为什么搜索类不给服务端**：结果取决于「谁在搜」，而 OpenAPI 没有登录用户。若平台此时按租户全量返回，外部系统就能通过产物 OpenAPI 把整个企业通讯录搜穿。开放平台那条路的可见范围由租户授权决定，语义上正好匹配。
-
-### 6.4 服务端禁止行为
-
-0. **禁止用 `AuthNPaasService.listUsersByIds` 之外的任何方式在服务端查用户信息** —— 包括：复用应用内已有的用户 / 用户资料 service、自己写 HTTP 裸调平台通讯录接口、从数据库表 join 出人名头像。这条优先级最高，与下面各条冲突时以本条为准
-1. **禁止在 `*.openapi.controller.ts` 里依赖 `req.userContext.userId`** —— OpenAPI 态恒为空
-2. **禁止用 `getCurrentUserLarkUserId()`** —— 它读 `userId`，取不到只打日志返回 `null`、**不报错**，静默失效。要飞书 ID 一律用 `getBatchLarkUserIds()`
-3. **禁止把 `name` 当字符串**渲染或入库 —— 它是 `I18nText`，直接用会得到 `[object Object]`
-4. **禁止 catch 掉 SDK 抛的平台错误当空结果** —— 「平台挂了」和「查无此人」必须区分开
-
----
-
-## 七、禁止行为
+## 六、禁止行为
 1. **禁用兼容字段**：任何调用不得用 lark_id / lark_department_id / lark_chat_id
 2. **禁止混用废弃名**：不得用 userID / suda_user_id / larkUserId 等旧名
 3. **禁止给飞书内置插件传 employee_id**：插件入参必须是 miaoda_user_id
@@ -271,7 +208,7 @@ export class TicketService {
 
 ---
 
-## 八、错误处理
+## 七、错误处理
 | 错误场景 | Agent 行为 |
 |---|---|
 | 用户说"获取 user_id" | 追问：妙搭 miaoda_user_id 还是飞书 employee_id？ |

package/steering/nestjs-react-fullstack/skills/nestjs-cache/SKILL.md

@@ -4,6 +4,7 @@ description: Use when planning, adding, debugging, or reviewing NestJS cache log
 steering: true
 steering-topic: nestjs_cache
 match-template-name: nestjs-react-fullstack
+control-by-feature-ab: true
 ---
 
 # NestJS Caching 使用指南

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

@@ -17,7 +17,6 @@ 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`（见下文） |
 
@@ -60,80 +59,6 @@ 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/vite-react/skills/plugin-guide/SKILL.md

@@ -3,7 +3,6 @@ name: plugin-guide
 description: "Use when 需要：(1) 创建或管理 PluginInstance 插件实例，(2) 调用 capabilityClient 生成插件调用代码，(3) 理解 Plugin、PluginInstance、PluginInstanceAIJson 三层关系，(4) 使用 get_plugin_ai_json 或 plugin_instance 工具。触发词：插件, plugin, 飞书消息, 飞书群组, 多维表格, AI生文, AI生图, 图片理解, capabilityClient, pluginInstance"
 steering: true
 steering-topic: plugin_guide
-match-template-name: vite-react
 ---
 
 # Plugin 集成指南

package/steering/vite-react/skills/react-three-fiber/SKILL.md

@@ -3,7 +3,6 @@ name: react-three-fiber
 description: "Use when 实现 3D 场景 / 3D 游戏 / 3D 数据可视化, 用到 react-three-fiber (R3F) / three.js / @react-three/drei / @react-three/rapier / @react-three/postprocessing 时. 触发词：3D, R3F, react-three-fiber, three.js, threejs, Canvas, useFrame, useThree, OrbitControls, drei, mesh, geometry, useGLTF, GLTF, GLB, 3D 模型, 3D 场景, 3D 游戏, 3D 地球, shader, GLSL, 物理引擎, rapier, postprocessing, Bloom, 后处理, 着色器, 立体, 透视, 视角, 飞行射击, 空战, 探索"
 steering: true
 steering-topic: react_three_fiber
-match-template-name: vite-react
 ---
 
 {% raw %}