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

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

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

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

@@ -1,10 +1,12 @@
 ---
 name: wireframe
-description: Explore many ideas with wireframes and storyboards
-available-agents:
-  - CreativeDesign
+description: 用线框图和故事板探索多种想法。触发词：wireframe, storyboard, 线框图, 故事板, 分镜, 草图, 低保真, 方案探索, 设计探索
+metadata:
+  display-names:
+    zh-CN: 线框图
+    en-US: Wireframe
 ---
 
-# Wireframe
+# 线框图
 
-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.
+帮助用户快速探索设计想法。先访谈用户，再生成多个粗略的线框图，在锁定方向之前把设计空间勾勒出来。优先追求广度而非精细打磨：每个想法给出 3-5 种明显不同的方案。用简单的形状、占位文字和极少的颜色，把焦点留在结构和流程上。整体保持手绘草图的感觉——手写风格但清晰可读的字体；以黑白为主、点缀少量颜色；低保真、简洁。提供简单的微调控件（Tweaks）；选项占地小就并排展示，占地大就用 tab 控件切换。

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" />
 ```
 
 ## 使用注意事项