@lark-apaas/coding-steering 0.1.21 → 0.1.22-alpha.20260724081248

package/steering/design-html/skills/visual-exposure/SKILL.md

@@ -1,10 +1,8 @@
 ---
 name: visual-exposure
 description: 用于制作可视化报告、专题视觉页、信息图、视觉长图、概念可视化、产品能力曝光、方案亮点展示等内容型 HTML 视觉作品。适合用户想把材料、数据或观点组织成可阅读、可展示、可传播的视觉化表达，但不希望做成 PPT、传统 dashboard 或纯 ECharts 图表的场景。触发词：可视化报告, 视觉报告, 可视化曝光, 视觉化曝光, 信息图, 长图, infographic, 视觉表达, 概念可视化, 亮点展示, 能力曝光
-metadata:
-  display-names:
-    zh-CN: 可视化报告
-    en-US: Visual Report
+available-agents:
+  - CreativeDesign
 ---
 
 # 可视化报告与专题表达
@@ -19,7 +17,7 @@ metadata:
 4. 按材料逻辑组织内容，而不是套固定目录、固定模块或固定视觉模板。参考样式只能启发表达方式，不能替代对当前材料的判断。
 5. 把材料拆成具体阅读任务：这一段要让读者完成什么判断、理解什么关系、记住什么事实、比较什么差异、追踪什么过程、相信什么证据。不要把这些任务名直接变成目录或模块标题。
 6. 为每个阅读任务现场生成合适的组件、视觉和布局：先说明这段内容需要什么表达方式，再落成具体 UI / 图形 / 排版 / 图表 / 截图 / 文字组合。可以创造新的结构和视觉隐喻，不受现有组件名限制；避免所有章节共享同一套组件组合。
-7. 先写风格 brief：主题隐喻、受众姿态、材料语言、配色逻辑和签名元素。财务报告可以像正式报告册，员工调研可以像组织研究档案，产品上市总结可以像品牌战报；这些只是启发，必须从用户材料里推导。
+7. 先写风格 brief：主题隐喻、受众姿态、材料语言、配色逻辑和视觉签名。财务报告可以像正式报告册，员工调研可以像组织研究档案，产品上市总结可以像品牌战报；这些只是启发，必须从用户材料里推导。
 8. 建立版式系统：画幅、栅格、字号层级、颜色、图标/线条语言、强调方式和章节节奏。版式系统必须说明不同章节如何变化，而不是所有章节都用同一种上下结构。
 9. 产出单个 HTML 文档。用户需求明确时直接做；只有主题、素材或交付形态完全无法判断时，才问少量必要问题。
 
@@ -52,7 +50,7 @@ metadata:
 - 默认平面化处理：内容区优先使用细边框、分隔线、浅底色、色块、表格斑马纹、编号和标签建立层级；不要给章节、卡片、图表容器加各种 `box-shadow`。
 - 少用装饰性渐变、发光、玻璃拟态。视觉效果要帮助分组、强调或引导视线。
 - 风格跟随内容、受众和品牌：可以正式、温和、技术、编辑化、品牌化或实验感，但不要从某个样例场景继承固定颜色、固定目录或固定组件。
-- 每份报告应有一个可解释的签名元素。签名元素要从用户主题、材料质感和阅读任务中生成，而不是复用固定手法；它可以是任何能组织内容、建立记忆点并保持一致性的视觉规则。
+- 每份报告应有一个可解释的视觉签名。视觉签名要从用户主题、材料质感和阅读任务中生成，而不是复用固定手法；它可以是任何能组织内容、建立记忆点并保持一致性的视觉规则。
 - 真实素材优先：用户给的截图、logo、图片、图标、数据片段要优先使用。没有素材时，用清楚的占位结构和可替换文案。
 - 允许少量动效，但只用于进入、强调或引导阅读，不做干扰理解的持续动画。
 - 可以包含数字、图表和表格，但它们服务于报告叙事；不要为了“可视化”而把所有内容都做成图。

package/steering/design-html/skills/wireframe/SKILL.md

@@ -1,12 +1,10 @@
 ---
 name: wireframe
-description: 用线框图和故事板探索多种想法。触发词：wireframe, storyboard, 线框图, 故事板, 分镜, 草图, 低保真, 方案探索, 设计探索
-metadata:
-  display-names:
-    zh-CN: 线框图
-    en-US: Wireframe
+description: Explore many ideas with wireframes and storyboards
+available-agents:
+  - CreativeDesign
 ---
 
-# 线框图
+# Wireframe
 
-帮助用户快速探索设计想法。先访谈用户，再生成多个粗略的线框图，在锁定方向之前把设计空间勾勒出来。优先追求广度而非精细打磨：每个想法给出 3-5 种明显不同的方案。用简单的形状、占位文字和极少的颜色，把焦点留在结构和流程上。整体保持手绘草图的感觉——手写风格但清晰可读的字体；以黑白为主、点缀少量颜色；低保真、简洁。提供简单的微调控件（Tweaks）；选项占地小就并排展示，占地大就用 tab 控件切换。
+Help the user explore design ideas quickly. Interview them, then generate multiple rough wireframes to map out the design space before committing to a direction. Prioritize breadth over polish: show 3-5 distinctly different approaches for each idea. Use simple shapes, placeholder text, and minimal color to keep the focus on structure and flow. Use a sketchy vibe -- handwritten but readable fonts; b&w with some color; low-fi and simple. Provide simple tweaks; show options side-by-side if small or using a tab control if large.

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

@@ -13,20 +13,27 @@ 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;
@@ -57,32 +64,202 @@ import { authClient } from "@lark-apaas/client-toolkit/auth";
 // authClient 是 SDK 内置的 singleton，零参可用，不需要异步初始化
 ```
 
-## 接口速查表
+## 鉴权服务接口
+
+#### 1. 登录跳转接口 (redirectToLogin)
+
+##### 用途
 
-| 方法                                      | 入参                           | 成功时 data 类型           | 说明                                           |
-| ----------------------------------------- | ------------------------------ | -------------------------- | ---------------------------------------------- |
-| `session.redirectToLogin(options?)`       | `SignInRedirectionOptions`     | `'success'`                | 跳转至 Dataloom 登录页（身份认证/单点登录）    |
-| `session.signOut()`                       | 无                             | `null`（异步）             | 退出登录，删除 cookie 中的登录态               |
-| `session.navigateToUserProfile(options?)` | `NavigateToUserProfileOptions` | `'success'`                | 跳转至当前登录用户详情页（头像/姓名点击进入）  |
-| `session.getUserInfo()`                   | 无                             | `UserInfoResponse`（异步） | 获取当前登录用户信息，未登录返回 `status: 401` |
+跳转至 Dataloom 登录页面，适用于：用户身份认证、单点登录、权限验证
 
-### 入参类型定义
+##### 适用场景
+
+需要用户进行身份认证的场景
+
+##### 入参说明
 
 ```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;
 }
 ```
 
-### getUserInfo 返回类型定义
+| 属性名   | 类型      | 必填 | 默认值  | 说明                           |
+| -------- | --------- | ---- | ------- | ------------------------------ |
+| `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)
+
+##### 用途
+
+根据当前登录态获取已登录的用户信息，适用于：用户资料展示、权限判断、个性化配置
+
+##### 适用场景
+
+需要获取当前登录用户详细信息的场景
+
+##### 数据类型定义
 
 ```typescript
 interface I18n {
@@ -114,39 +291,75 @@ 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
-import { authClient } from "@lark-apaas/client-toolkit/auth";
+/**
+ * 根据当前登陆态获取已登录的用户信息。
+ * @param {string} brand - 品牌id 例如：妙搭为 1.
+ * @param {string} appId - 运行态应用的id，由dataloom authn 服务下发。
+ * @return
+ */
+const res: Promise<DataloomServiceResponse<UserInfoResponse>> = await authClient.session.getUserInfo();
+
+// 使用示例
 import { logger } from "@lark-apaas/client-toolkit/logger";
 
-// 获取用户信息（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();
+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;
+    }
   }
-} 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();
+} catch (error) {
+  logger.error("获取用户信息异常:", error);
 }
-
-// 跳转当前用户详情页（新标签页打开）
-authClient.session.navigateToUserProfile({ newTab: true });
 ```
 
 ## 错误处理
 
+### 常见错误类型
+
 | 错误码 | 说明           | 处理建议               |
 | ------ | -------------- | ---------------------- |
 | `400`  | 请求参数错误   | 检查传入参数是否正确   |
@@ -155,19 +368,60 @@ authClient.session.navigateToUserProfile({ newTab: true });
 | `404`  | 资源不存在     | 检查请求的资源是否存在 |
 | `500`  | 服务器内部错误 | 稍后重试或联系技术支持 |
 
-统一处理建议：`401` 调用 `authClient.session.redirectToLogin()`（见综合示例）；`403`/`500` 用 toast（如 `sonner`）提示用户；其余情况展示 `error.message`。
+### 错误处理最佳实践
+
+```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);
+}
+```
 
 ## 注意事项
 
-1. **环境限制**：本 skill 涉及的 `@lark-apaas/client-toolkit/**` 能力只能在前端/浏览器环境中使用，服务端调用会返回环境不兼容错误；更重要的是，服务端代码中禁止 import 这些前端 SDK
-2. **跨域配置**：确保应用域名已在 Dataloom 后台配置白名单
-3. **安全性**：不要在客户端代码中暴露敏感的配置信息
+1. **环境限制**：部分接口只能在浏览器环境中使用，服务端调用会返回环境不兼容错误
+2. **登录状态**：获取用户信息前需要确保用户已登录，否则会返回401错误
+3. **跨域配置**：确保应用域名已在 Dataloom 后台配置白名单
+4. **安全性**：不要在客户端代码中暴露敏感的配置信息
+5. **错误处理**：建议对所有接口调用进行统一的错误处理
 
 # 用户系统前端相关规范
 
 ## 概述
 
-内置用户前端组件：UserSelect（单选/多选用户选择器，onChange 返回用户对象）、DepartmentSelect（部门选择组件，交互与受控规范与 UserSelect 一致）、UserDisplay（用户信息展示组件）。均基于统一的 userid 数据，用于用户相关的表单输入和数据展示场景。
+内置的用户前端组件规范，提供了 UserSelect（支持单选/多选的用户选择器）和 UserDisplay（用户信息展示组件）两个核心 React 组件，基于统一的userid数据，并且用户选择组件中会通过onchange返回User类型数据，专门用于处理用户相关的表单输入和数据展示场景。
+
+同时提供 DepartmentSelect（部门选择组件），用于部门字段的单选/多选选择，交互与受控规范与 UserSelect 保持一致。
 
 ## 类型定义
 
@@ -194,8 +448,17 @@ export type User = {
 
 ## 当前用户信息的获取方案
 
+### 常用场景
+
+- **用户信息展示**：在界面中显示当前用户名称和头像
+- **权限验证**：基于用户ID进行权限检查和控制
+- **数据关联**：在数据操作时关联当前用户信息
+- **日志记录**：记录用户操作日志时获取用户标识
+
 ### Hooks 方法: `useCurrentUserProfile` - 在 React 中获取当前用户信息
 
+### 基本信息
+
 - **文件路径**：`@lark-apaas/client-toolkit/hooks/useCurrentUserProfile`
 - **功能**：获取当前登录用户的个人信息（含飞书 user_id）
 - **返回值**：`Partial<IUserProfile>`（初始为空对象 `{}`，异步获取后填充完整字段）
@@ -210,18 +473,29 @@ export type User = {
 | `avatar`       | `string` | 用户头像 URL                                             |
 | `lark_user_id` | `string` | 飞书 user_id，通过额外异步请求获取，可能晚于其他字段就绪 |
 
-> ⚠️ **空值处理（CRITICAL）**：Hook 初始返回空对象 `{}`（truthy），**MUST** 用 `if (!userInfo?.user_id)` 判加载态（不是 `!userInfo`）；`lark_user_id` 可能为 `undefined`，使用前条件渲染。完整禁止行为清单与飞书 ID 转换指南（后端 `AuthNPaasService` 等）参见 `user-identity` skill。
+> ⚠️ **空值处理（CRITICAL）**：Hook 初始返回空对象 `{}`（truthy）、字段均 `undefined`。**MUST** 用可选链，并以 `if (!userInfo?.user_id)` 判加载态（不是 `!userInfo`）；`lark_user_id` 异步获取、可能为 `undefined`，使用前条件渲染。
+
+### 使用方法
 
 ```typescript
 import { useCurrentUserProfile } from "@lark-apaas/client-toolkit/hooks/useCurrentUserProfile";
 
 const MyComponent = () => {
   const userInfo = useCurrentUserProfile();
+
+  // 正确：安全访问 + 加载态处理
   if (!userInfo?.user_id) return <div>加载中...</div>;
-  return <p>{userInfo.name}</p>;
+  return (
+    <div>
+      <p>{userInfo.name}</p>
+      {userInfo.lark_user_id && <p>飞书 ID: {userInfo.lark_user_id}</p>}
+    </div>
+  );
 };
 ```
 
+> **飞书 ID 转换详细指南**（后端 `AuthNPaasService` 用法、自定义转换接口等）参见 `user-identity` skill。
+
 ## 用户展示与选择方案
 
 {% if projectMeta['flags']['supportBusinessUser'] %}
@@ -235,7 +509,7 @@ const MyComponent = () => {
 
 {% else %}
 
-## UserSelect - 用户选择组件
+##
 
 ### 基本信息
 
@@ -255,9 +529,14 @@ interface UserSelectProps {
 }
 ```
 
-值类型：单选模式（`mode="single"`）值为 userid、onChange 返回 `IUserProfile` 对象；多选模式（`mode="multiple"`）值为 userid 数组、onChange 返回 `IUserProfile` 数组。
+### 值类型说明
+
+- **单选模式** (`mode="single"`)：值为 userid，返回为`IUserProfile` 对象
+- **多选模式** (`mode="multiple"`)：值为 userid数组，返回为`IUserProfile` 数组
 
-### 使用示例（表单集成）
+### 使用示例
+
+#### 表单集成
 
 ```typescript
 import { useForm } from "react-hook-form";
@@ -266,8 +545,10 @@ 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>>({
@@ -293,8 +574,24 @@ const form = useForm<z.infer<typeof formSchema>>({
         </FormItem>
       )}
     />
-    {/* 多选字段差异仅：schema 用 z.array(z.string())，mode="multiple"，
-        onChange={(users) => field.onChange(users.map((u) => u.user_id))} */}
+
+    <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>
+      )}
+    />
   </form>
 </Form>
 ```
@@ -307,24 +604,41 @@ const form = useForm<z.infer<typeof formSchema>>({
 - **功能**：用于所有用户信息的展示场景
 - **特性**：显示用户**头像**和**姓名**，支持多用户展示
 
+IMPORTANT：当不传递showLabel时，组件会同时展示用户头像和姓名，如果只需要头像，则需要传递showLabel的值为false
+
 ### 属性定义
 
 ```typescript
 interface UserDisplayProps {
-  users: string[]; // 用户id数组（必需），单个用户传 [userId]
+  users: string[]; // 用户id数组（必需）
   size?: "small" | "medium" | "large"; // 头像尺寸
   className?: string; // 自定义样式类名
-  showLabel?: boolean; // 默认为true，同时展示头像和姓名；只需要头像时必须显式传 false
+  showLabel?: boolean; // 默认为true，会展示用户姓名，如果只需要展示头像则需要设置为false
 }
 ```
 
 ### 使用示例
 
+#### 基础用法
+
 ```jsx
 import { UserDisplay } from "@lark-apaas/client-toolkit/components/User";
-
-// 单个或多个用户展示：users 传用户 id 数组
-<UserDisplay users={project.participants} size="medium" className="project-members" />
+import { useEmployeeStore } from "@/models/employee";
+
+const { employeesId } = useEmployeeStore();
+
+// 单个用户展示
+<UserDisplay
+  users={[employeesId]}
+  size="small"
+/>
+
+// 多用户展示
+<UserDisplay
+  users={project.participants}
+  size="medium"
+  className="project-members"
+/>
 ```
 
 ## 使用注意事项