@lark-apaas/coding-steering 0.1.17-alpha.0 → 0.1.17

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.17-alpha.0",
+  "version": "0.1.17",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [
     "steering"
   ],
   "scripts": {
-    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**'"
+    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
   },
   "devDependencies": {
     "markdownlint-cli": "^0.47.0"

package/steering/design-html/skills/make-a-deck/SKILL.md

@@ -26,9 +26,7 @@ available-agents:
 
 - 先写完整标题序列放进 `scratchpad.md`。只读标题就应能看懂整份 deck 的逻辑（像书的目录）。检查是否形成清楚路径：背景 → 问题 → 洞察 → 方案 → 证据 → 下一步。
 - 选定一种标题语法并全程一致：要么名词短语（"市场机会""产品架构"），要么简短判断句（"新用户增长主要来自自然流量"）。
-- 大字号标题需要换行时，按语义短语断行，避免单字成行、标点出现在行首或拆开固定短语；可通过调整文本区、字号或断行位置修正失衡。
 - 每页正文只服务本页标题，不塞旁支。封面、章节页、转场页、结尾页也要服务故事，不做纯装饰。
-- 文字要有明确功能：保留承担信息、导航、出处或真实品牌识别作用的文字；不为营造风格或填补空间而编造、重复无信息价值的辅助文字。
 
 避免这些"AI 味"标题（它们会暴露 deck 是 AI 生成的）——标题的任务是**定位页面、推进叙事**，不是替演讲者甩结论 / 喊 punchline：
 
@@ -81,14 +79,13 @@ deck 每页先判断它要让观众完成什么阅读动作：抓结论、看证
 
 视觉服务演示场景，不是网页首页。
 
-- **主题与风格**：根据主题、受众和演示场景提炼视觉关键词，用它们决定配色、字体、图片类型和页面节奏；不把“干净、专业”默认等同于大量留白或通用企业风。
 - **明暗按需求选择**：根据品牌 / 主题 / 图片素材 / 演示场景选择浅色、暗色或混合背景。无论选择哪种，都要保证投影、截图和后排阅读的对比度。明暗切换应落在叙事节点上（章节转换、关键强调），不要无来由地跳变。
 - 字体克制（1-2 套）：展示字体可有个性，正文必须稳定可读；整体对比清楚、信息块边界明确。
 - 图片先判断内容和用途：摄影 / 氛围图可满版裁切；截图、图表、产品界面、架构图必须完整展示（aspect-fit），不能裁掉关键边界或文字；透明图 / 细线图放到有对比的底色上。图上压字用品牌常见方式保护可读性（遮罩、渐变、模糊或文字容器）。
 - 视觉要有节奏变化：全图页、大数字页、表格页、引用页、流程页、文字页交替出现；不要整套都是同一种卡片。也不要每页硬加描边卡片、固定结论框或装饰分割线——只有内容需要分组时才用容器。
 - 扁平基线：好的 deck 不依赖阴影和悬浮卡片堆叠。优先用全页背景、色带、分隔线、编号、表格网格、图片裁切、对比色块和尺度差建立层次。只有在需要表达真实物件、票券、照片或舞台层次时才少量使用阴影。
 - 不用 emoji、不临时手绘复杂假图；优先用用户素材、品牌资产、图标库或真实图片。
-- **空间重心**：页面元素应形成完整构图：留白有明确作用，独立元素与主体有可感知的关系，多栏内容在视觉重量和内容关系上协调。不预设内容必须集中在上方或占据固定比例。内容不足以独立成页时，合并、重构或升格为确有价值的观点页，不单纯放大数字、卡片或增加留白撑页。
+- **空间重心**：内容集中在上方 2/3、底部留白，通常是**正确**的 slide 构图。看到 `align-items: flex-start` 加底部留空就想改成 `center`——那是网页设计的条件反射，忍住，留白是有意的。但留白有下界：内容页的主内容应占版心高度约 2/3 以上，撑不满就升格版式——放大成大数字、大卡片，或重排为居中的宣言页，而不是把原内容原样居中或任其悬浮在顶部。空本身不是缺陷，不均才是：同一页一处大空、一处拥挤，要重排。双栏页两列视觉重量要对等，悬殊时改 7:5 / 8:4 不对称栅格或并回单栏。
 
 ## HTML 实现（deck-stage 外壳）
 
@@ -117,8 +114,7 @@ deck 每页先判断它要让观众完成什么阅读动作：抓结论、看证
 ## 交付前自检
 
 - 每页 16:9，无溢出 / 重叠 / 裁切；字号符合投影阅读（正文没有小到像网页）。
-- 构图完整：留白与主体关系明确，没有孤立漂浮、局部拥挤或失衡的多栏布局。
-- 页码、来源和固定页脚不与正文争用空间；逐页检查文字、图片和固定元素没有遮挡或碰撞。
+- 留白均匀：同一页没有一处大空、一处拥挤；内容页主内容占版心高度约 2/3 以上；双栏视觉重量对等。
 - 只读标题能讲通故事；标题语法全程一致，没有 punchline / takeaway 盒子。
 - 已建立 page-type map，并通过页型轮换避免单一上下布局。
 - 章节分隔页推动叙事，而不是只做装饰。

package/steering/nestjs-react-fullstack/skills/client-builtins-user-service/SKILL.md

@@ -13,27 +13,20 @@ match-template-name: nestjs-react-fullstack
 项目通过 `authClient`（来自 `@lark-apaas/client-toolkit/auth`）提供用户信息与鉴权服务，用于用户登录、登出、获取用户信息等身份认证相关功能。
 
 > **边界说明**：`authClient.session` 仅用于用户登录/登出/获取用户信息等鉴权操作。**插件调用（capability）不属于账户 SDK**，须使用独立的 `capabilityClient`（参见 plugin-guide）。
+>
+> **运行时边界**：本 skill 所有能力（`authClient`、`useCurrentUserProfile`、UserSelect/UserDisplay 等）仅限前端代码使用，**严禁在 `server/**` 中 import**。服务端获取用户身份用 `req.userContext` / `AuthNPaasService`（见 `user-identity` skill），完整边界规则见 coding-guide。
+
+## 怎么选（决策指引）
+
+- **React 组件内展示当前用户**（名称/头像/邮箱/飞书 ID）→ 用 `useCurrentUserProfile()`（见下文），不要手动调 `getUserInfo`
+- **登录/登出/跳转用户详情页，或非 React 上下文取用户信息** → `authClient.session.*`（本节）
+- **选人/选部门/展示任意用户** → UserSelect / DepartmentSelect / UserDisplay 组件（见下文）
 
 ## 统一响应结构
 
-### 响应类型定义
+所有 `authClient.session.*` 接口返回统一的 `DataloomServiceResponse<T>` 结构。在非浏览器环境调用会返回失败结构（`status: 400`，`error.message: 'Incompatible runtime environment'`）。
 
 ```typescript
-/**
- * 统一结果返回结构
- * 在非浏览器环境调用时返回示例：
- * {
- *   data: null,
- *   error: {
- *     code: 400,
- *     message: 'Incompatible runtime environment',
- *     hint: 'Please check if the current environment is browser.',
- *     details: 'This method can only be invoked in browser environment.',
- *   },
- *   status: 400,
- *   statusText: 'Bad Request',
- * }
- */
 interface DataloomServiceBase {
   status: number;
   statusText: string;
@@ -64,202 +57,32 @@ import { authClient } from "@lark-apaas/client-toolkit/auth";
 // authClient 是 SDK 内置的 singleton，零参可用，不需要异步初始化
 ```
 
-## 鉴权服务接口
-
-#### 1. 登录跳转接口 (redirectToLogin)
-
-##### 用途
+## 接口速查表
 
-跳转至 Dataloom 登录页面，适用于：用户身份认证、单点登录、权限验证
+| 方法                                      | 入参                           | 成功时 data 类型           | 说明                                           |
+| ----------------------------------------- | ------------------------------ | -------------------------- | ---------------------------------------------- |
+| `session.redirectToLogin(options?)`       | `SignInRedirectionOptions`     | `'success'`                | 跳转至 Dataloom 登录页（身份认证/单点登录）    |
+| `session.signOut()`                       | 无                             | `null`（异步）             | 退出登录，删除 cookie 中的登录态               |
+| `session.navigateToUserProfile(options?)` | `NavigateToUserProfileOptions` | `'success'`                | 跳转至当前登录用户详情页（头像/姓名点击进入）  |
+| `session.getUserInfo()`                   | 无                             | `UserInfoResponse`（异步） | 获取当前登录用户信息，未登录返回 `status: 401` |
 
-##### 适用场景
-
-需要用户进行身份认证的场景
-
-##### 入参说明
+### 入参类型定义
 
 ```typescript
 interface SignInRedirectionOptions {
-  /**
-   * 选填，登录成功后跳转回的页面。省略会默认用调用接口时页面的url。
-   */
+  /** 选填，登录成功后跳转回的页面。省略默认用当前页面 URL */
   returnUrl?: string;
-  /**
-   * 选填，是否在新浏览器tab上打开登录页。默认为false
-   */
+  /** 选填，是否在新浏览器 tab 打开登录页。默认 false */
   newTab?: boolean;
 }
-```
-
-| 属性名      | 类型      | 必填 | 默认值      | 说明                           |
-| ----------- | --------- | ---- | ----------- | ------------------------------ |
-| `returnUrl` | `string`  | ❌   | 当前页面URL | 登录成功后跳转回的页面         |
-| `newTab`    | `boolean` | ❌   | `false`     | 是否在新浏览器标签页打开登录页 |
-
-##### 出参说明
-
-| 字段名       | 类型        | 说明                   |
-| ------------ | ----------- | ---------------------- |
-| `data`       | `'success'` | 成功标识               |
-| `error`      | `null`      | 错误信息，成功时为null |
-| `status`     | `200`       | HTTP状态码             |
-| `statusText` | `'OK'`      | HTTP状态文本           |
-
-##### 使用示例
-
-```typescript
-/**
- * 跳转至dataloom登录页
- * @param {string} brand - 品牌id 例如：妙搭为 1.
- * @param {string} appId - 运行态应用的id，由dataloom authn 服务下发。
- * @return 成功返回示例：
- * {
- *   data: 'success',
- *   error: null,
- *   status: 200,
- *   statusText: 'OK',
- *  }
- */
-const res: DataloomServiceResponse<'success'> = authClient
-  .session
-  .redirectToLogin(options: SignInRedirectionOptions);
-
-// 基本使用
-const loginResult = authClient
-  .session
-  .redirectToLogin();
-
-// 带参数使用
-const loginResult = authClient
-  .session
-  .redirectToLogin({
-    returnUrl: 'https://example.com/dashboard',
-    newTab: true
-  });
-```
-
-#### 2. 退出登录接口 (signOut)
-
-##### 用途
-
-退出登录，删除cookie中的登录态，适用于：用户主动登出、会话清理、安全退出
-
-##### 适用场景
-
-需要清除用户登录状态的场景
-
-##### 入参说明
-
-无需传入参数
-
-##### 出参说明
-
-| 字段名       | 类型   | 说明                   |
-| ------------ | ------ | ---------------------- |
-| `data`       | `null` | 数据为空               |
-| `error`      | `null` | 错误信息，成功时为null |
-| `status`     | `200`  | HTTP状态码             |
-| `statusText` | `'OK'` | HTTP状态文本           |
-
-##### 使用示例
-
-```typescript
-/**
- * 退出登录，删除cookie中的登陆态
- * @return 成功返回示例：
- * {
- *   data: null,
- *   error: null,
- *   status: 200,
- *   statusText: 'OK',
- *  }
- */
-const res: Promise<DataloomServiceResponse<null>> = await authClient.session.signOut();
-
-// 使用示例
-import { logger } from "@lark-apaas/client-toolkit/logger";
-
-try {
-  const result = await authClient.session.signOut();
-
-  if (result.error) {
-    logger.error("退出登录失败:", result.error.message);
-  } else {
-    logger.info("退出登录成功");
-    // 跳转到登录页或首页
-    authClient.session.redirectToLogin();
-  }
-} catch (error) {
-  logger.error("退出登录异常:", error);
-}
-```
-
-#### 3. 跳转用户详情页接口 (navigateToUserProfile)
-
-##### 用途
-
-跳转至当前登录用户的详情页，适用于：查看个人资料、从用户头像/姓名点击进入详情页面
-
-##### 适用场景
-
-需要在应用中快速打开用户详情页面的场景
 
-##### 入参说明
-
-```typescript
 interface NavigateToUserProfileOptions {
-  /**
-   * 选填，是否在新浏览器tab上打开详情页。默认为false
-   */
+  /** 选填，是否在新浏览器 tab 打开详情页。默认 false */
   newTab?: boolean;
 }
 ```
 
-| 属性名   | 类型      | 必填 | 默认值  | 说明                           |
-| -------- | --------- | ---- | ------- | ------------------------------ |
-| `newTab` | `boolean` | ❌   | `false` | 是否在新浏览器标签页打开详情页 |
-
-##### 出参说明
-
-| 字段名       | 类型        | 说明                   |
-| ------------ | ----------- | ---------------------- |
-| `data`       | `'success'` | 成功标识               |
-| `error`      | `null`      | 错误信息，成功时为null |
-| `status`     | `200`       | HTTP状态码             |
-| `statusText` | `'OK'`      | HTTP状态文本           |
-
-##### 使用示例
-
-```typescript
-/**
- * 跳转至用户详情页
- * @return 成功返回示例：
- * {
- *   data: 'success',
- *   error: null,
- *   status: 200,
- *   statusText: 'OK',
- * }
- */
-const res: DataloomServiceResponse<"success"> = authClient.session.navigateToUserProfile();
-
-// 在新标签页打开
-const resNewTab = authClient.session.navigateToUserProfile({ newTab: true });
-```
-
-## 用户信息服务
-
-#### 4. 获取用户信息接口 (getUserInfo)
-
-##### 用途
-
-根据当前登录态获取已登录的用户信息，适用于：用户资料展示、权限判断、个性化配置
-
-##### 适用场景
-
-需要获取当前登录用户详细信息的场景
-
-##### 数据类型定义
+### getUserInfo 返回类型定义
 
 ```typescript
 interface I18n {
@@ -291,75 +114,39 @@ interface UserInfoResponse {
 }
 ```
 
-##### 入参说明
-
-无需传入参数
-
-##### 出参说明
-
-| 字段名                        | 类型           | 说明                   |
-| ----------------------------- | -------------- | ---------------------- |
-| `data.user_info`              | `UserBaseInfo` | 用户基本信息对象       |
-| `data.user_info.user_id`      | `number`       | 用户唯一标识符         |
-| `data.user_info.name`         | `I18ns`        | 用户名称（支持多语言） |
-| `data.user_info.avatar`       | `Avatar`       | 用户头像信息           |
-| `data.user_info.email`        | `string`       | 用户邮箱地址           |
-| `data.user_info.phone_number` | `string`       | 用户手机号码           |
-| `data.user_info.tenant_name`  | `string`       | 租户名称               |
-| `error`                       | `null`         | 错误信息，成功时为null |
-
-##### 使用示例
+### 综合示例
 
 ```typescript
-/**
- * 根据当前登陆态获取已登录的用户信息。
- * @param {string} brand - 品牌id 例如：妙搭为 1.
- * @param {string} appId - 运行态应用的id，由dataloom authn 服务下发。
- * @return
- */
-const res: Promise<DataloomServiceResponse<UserInfoResponse>> = await authClient.session.getUserInfo();
-
-// 使用示例
+import { authClient } from "@lark-apaas/client-toolkit/auth";
 import { logger } from "@lark-apaas/client-toolkit/logger";
 
-try {
-  const result = await authClient.session.getUserInfo();
-
-  if (result.error) {
-    logger.error("获取用户信息失败:", result.error.message);
-    // 可能需要重新登录
-    if (result.status === 401) {
-      // 跳转到登录页
-      authClient.session.redirectToLogin();
-    }
-  } else if (result.data?.user_info) {
-    const userInfo = result.data.user_info;
-    logger.info("用户信息:", userInfo);
-
-    // 显示用户名
-    const userName = userInfo.name?.[0]?.text || "未知用户";
-    document.getElementById("username").textContent = userName;
-
-    // 显示用户头像
-    const avatarUrl = userInfo.avatar?.image?.large;
-    if (avatarUrl) {
-      document.getElementById("avatar").src = avatarUrl;
-    }
-
-    // 显示用户邮箱
-    if (userInfo.email) {
-      document.getElementById("email").textContent = userInfo.email;
-    }
+// 获取用户信息（React 组件内展示当前用户请优先用 useCurrentUserProfile，见下文）
+const result = await authClient.session.getUserInfo();
+if (result.error) {
+  logger.error("获取用户信息失败:", result.error.message);
+  if (result.status === 401) {
+    // 未登录：跳转登录页（可传 returnUrl / newTab，默认回到当前页）
+    authClient.session.redirectToLogin();
   }
-} catch (error) {
-  logger.error("获取用户信息异常:", error);
+} else if (result.data?.user_info) {
+  const info = result.data.user_info;
+  const userName = info.name?.[0]?.text || "未知用户"; // 名称是多语言数组
+  const avatarUrl = info.avatar?.image?.large; // 头像 URL 可能不返回
+  // React 中通过 state 渲染上述字段，禁止 document.getElementById 等直接 DOM 操作
+}
+
+// 退出登录后回到登录页
+const signOutResult = await authClient.session.signOut();
+if (!signOutResult.error) {
+  authClient.session.redirectToLogin();
 }
+
+// 跳转当前用户详情页（新标签页打开）
+authClient.session.navigateToUserProfile({ newTab: true });
 ```
 
 ## 错误处理
 
-### 常见错误类型
-
 | 错误码 | 说明           | 处理建议               |
 | ------ | -------------- | ---------------------- |
 | `400`  | 请求参数错误   | 检查传入参数是否正确   |
@@ -368,60 +155,19 @@ try {
 | `404`  | 资源不存在     | 检查请求的资源是否存在 |
 | `500`  | 服务器内部错误 | 稍后重试或联系技术支持 |
 
-### 错误处理最佳实践
-
-```typescript
-import { toast } from "sonner";
-
-// 统一错误处理函数
-function handleDataloomError(response: DataloomServiceResponse<any>) {
-  if (response.error) {
-    switch (response.status) {
-      case 401:
-        // 未授权，跳转登录
-        authClient.session.redirectToLogin();
-        break;
-      case 403:
-        // 权限不足
-        toast.error("权限不足，请联系管理员");
-        break;
-      case 500:
-        // 服务器错误
-        toast.error("服务器错误，请稍后重试");
-        break;
-      default:
-        toast.error(`操作失败: ${response.error.message}`);
-    }
-    return false;
-  }
-  return true;
-}
-
-// 使用示例
-import { logger } from "@lark-apaas/client-toolkit/logger";
-
-const userInfoResult = await authClient.session.getUserInfo();
-if (handleDataloomError(userInfoResult)) {
-  // 处理成功逻辑
-  logger.info("用户信息:", userInfoResult.data);
-}
-```
+统一处理建议：`401` 调用 `authClient.session.redirectToLogin()`（见综合示例）；`403`/`500` 用 toast（如 `sonner`）提示用户；其余情况展示 `error.message`。
 
 ## 注意事项
 
-1. **环境限制**：部分接口只能在浏览器环境中使用，服务端调用会返回环境不兼容错误
-2. **登录状态**：获取用户信息前需要确保用户已登录，否则会返回401错误
-3. **跨域配置**：确保应用域名已在 Dataloom 后台配置白名单
-4. **安全性**：不要在客户端代码中暴露敏感的配置信息
-5. **错误处理**：建议对所有接口调用进行统一的错误处理
+1. **环境限制**：本 skill 涉及的 `@lark-apaas/client-toolkit/**` 能力只能在前端/浏览器环境中使用，服务端调用会返回环境不兼容错误；更重要的是，服务端代码中禁止 import 这些前端 SDK
+2. **跨域配置**：确保应用域名已在 Dataloom 后台配置白名单
+3. **安全性**：不要在客户端代码中暴露敏感的配置信息
 
 # 用户系统前端相关规范
 
 ## 概述
 
-内置的用户前端组件规范，提供了 UserSelect（支持单选/多选的用户选择器）和 UserDisplay（用户信息展示组件）两个核心 React 组件，基于统一的userid数据，并且用户选择组件中会通过onchange返回User类型数据，专门用于处理用户相关的表单输入和数据展示场景。
-
-同时提供 DepartmentSelect（部门选择组件），用于部门字段的单选/多选选择，交互与受控规范与 UserSelect 保持一致。
+内置用户前端组件：UserSelect（单选/多选用户选择器，onChange 返回用户对象）、DepartmentSelect（部门选择组件，交互与受控规范与 UserSelect 一致）、UserDisplay（用户信息展示组件）。均基于统一的 userid 数据，用于用户相关的表单输入和数据展示场景。
 
 ## 类型定义
 
@@ -448,17 +194,8 @@ export type User = {
 
 ## 当前用户信息的获取方案
 
-### 常用场景
-
-- **用户信息展示**：在界面中显示当前用户名称和头像
-- **权限验证**：基于用户ID进行权限检查和控制
-- **数据关联**：在数据操作时关联当前用户信息
-- **日志记录**：记录用户操作日志时获取用户标识
-
 ### Hooks 方法: `useCurrentUserProfile` - 在 React 中获取当前用户信息
 
-### 基本信息
-
 - **文件路径**：`@lark-apaas/client-toolkit/hooks/useCurrentUserProfile`
 - **功能**：获取当前登录用户的个人信息（含飞书 user_id）
 - **返回值**：`Partial<IUserProfile>`（初始为空对象 `{}`，异步获取后填充完整字段）
@@ -473,29 +210,18 @@ export type User = {
 | `avatar`       | `string` | 用户头像 URL                                             |
 | `lark_user_id` | `string` | 飞书 user_id，通过额外异步请求获取，可能晚于其他字段就绪 |
 
-> ⚠️ **空值处理（CRITICAL）**：Hook 初始返回空对象 `{}`（truthy）、字段均 `undefined`。**MUST** 用可选链，并以 `if (!userInfo?.user_id)` 判加载态（不是 `!userInfo`）；`lark_user_id` 异步获取、可能为 `undefined`，使用前条件渲染。
-
-### 使用方法
+> ⚠️ **空值处理（CRITICAL）**：Hook 初始返回空对象 `{}`（truthy），**MUST** 用 `if (!userInfo?.user_id)` 判加载态（不是 `!userInfo`）；`lark_user_id` 可能为 `undefined`，使用前条件渲染。完整禁止行为清单与飞书 ID 转换指南（后端 `AuthNPaasService` 等）参见 `user-identity` skill。
 
 ```typescript
 import { useCurrentUserProfile } from "@lark-apaas/client-toolkit/hooks/useCurrentUserProfile";
 
 const MyComponent = () => {
   const userInfo = useCurrentUserProfile();
-
-  // 正确：安全访问 + 加载态处理
   if (!userInfo?.user_id) return <div>加载中...</div>;
-  return (
-    <div>
-      <p>{userInfo.name}</p>
-      {userInfo.lark_user_id && <p>飞书 ID: {userInfo.lark_user_id}</p>}
-    </div>
-  );
+  return <p>{userInfo.name}</p>;
 };
 ```
 
-> **飞书 ID 转换详细指南**（后端 `AuthNPaasService` 用法、自定义转换接口等）参见 `user-identity` skill。
-
 ## 用户展示与选择方案
 
 {% if projectMeta['flags']['supportBusinessUser'] %}
@@ -509,7 +235,7 @@ const MyComponent = () => {
 
 {% else %}
 
-##
+## UserSelect - 用户选择组件
 
 ### 基本信息
 
@@ -529,14 +255,9 @@ interface UserSelectProps {
 }
 ```
 
-### 值类型说明
-
-- **单选模式** (`mode="single"`)：值为 userid，返回为`IUserProfile` 对象
-- **多选模式** (`mode="multiple"`)：值为 userid数组，返回为`IUserProfile` 数组
+值类型：单选模式（`mode="single"`）值为 userid、onChange 返回 `IUserProfile` 对象；多选模式（`mode="multiple"`）值为 userid 数组、onChange 返回 `IUserProfile` 数组。
 
-### 使用示例
-
-#### 表单集成
+### 使用示例（表单集成）
 
 ```typescript
 import { useForm } from "react-hook-form";
@@ -545,10 +266,8 @@ import * as z from "zod";
 import { Form, FormControl, FormField, FormItem, FormLabel } from "@/components/ui/form";
 import { UserSelect } from "@lark-apaas/client-toolkit/components/User";
 
-// 定义表单验证schema
 const formSchema = z.object({
   assignee: z.string(),
-  participants: z.array(z.string()).optional(),
 });
 
 const form = useForm<z.infer<typeof formSchema>>({
@@ -574,24 +293,8 @@ const form = useForm<z.infer<typeof formSchema>>({
         </FormItem>
       )}
     />
-
-    <FormField
-      control={form.control}
-      name="participants"
-      render={({ field }) => (
-        <FormItem>
-          <FormLabel>参与人（多选）</FormLabel>
-          <FormControl>
-            <UserSelect
-              mode="multiple"
-              placeholder="选择参与人员"
-              value={field.value}
-              onChange={(users) => field.onChange(users.map(user => user.user_id))}
-            />
-          </FormControl>
-        </FormItem>
-      )}
-    />
+    {/* 多选字段差异仅：schema 用 z.array(z.string())，mode="multiple"，
+        onChange={(users) => field.onChange(users.map((u) => u.user_id))} */}
   </form>
 </Form>
 ```
@@ -604,41 +307,24 @@ const form = useForm<z.infer<typeof formSchema>>({
 - **功能**：用于所有用户信息的展示场景
 - **特性**：显示用户**头像**和**姓名**，支持多用户展示
 
-IMPORTANT：当不传递showLabel时，组件会同时展示用户头像和姓名，如果只需要头像，则需要传递showLabel的值为false
-
 ### 属性定义
 
 ```typescript
 interface UserDisplayProps {
-  users: string[]; // 用户id数组（必需）
+  users: string[]; // 用户id数组（必需），单个用户传 [userId]
   size?: "small" | "medium" | "large"; // 头像尺寸
   className?: string; // 自定义样式类名
-  showLabel?: boolean; // 默认为true，会展示用户姓名，如果只需要展示头像则需要设置为false
+  showLabel?: boolean; // 默认为true，同时展示头像和姓名；只需要头像时必须显式传 false
 }
 ```
 
 ### 使用示例
 
-#### 基础用法
-
 ```jsx
 import { UserDisplay } from "@lark-apaas/client-toolkit/components/User";
-import { useEmployeeStore } from "@/models/employee";
-
-const { employeesId } = useEmployeeStore();
-
-// 单个用户展示
-<UserDisplay
-  users={[employeesId]}
-  size="small"
-/>
-
-// 多用户展示
-<UserDisplay
-  users={project.participants}
-  size="medium"
-  className="project-members"
-/>
+
+// 单个或多个用户展示：users 传用户 id 数组
+<UserDisplay users={project.participants} size="medium" className="project-members" />
 ```
 
 ## 使用注意事项