@blueking/chat-x 0.0.51-beta.5 → 0.0.52-dev.1

package/skills/blueking-chat-x/references/components/shortcut-btns.md

@@ -0,0 +1,266 @@
+# ShortcutBtns 快捷指令按钮组
+
+> 能力域：输入交互 ｜ 导入：`import { ShortcutBtns } from '@blueking/chat-x'` ｜ since 1.0.0
+
+快捷指令列表入口，内部组合多个 ShortcutBtn。 源码位置：src/components/ai-shortcut/shortcut-btns/shortcut-btns.vue。
+
+**关联**：shortcut-btn（列表中每一项由 ShortcutBtn 渲染）、chat-input（默认嵌入输入框底部附件区）、shortcut-render（表单类快捷指令选中后的表单渲染）
+
+---
+
+# ShortcutBtns 快捷指令按钮组
+## 源码事实
+
+- **源码位置**：`src/components/ai-shortcut/shortcut-btns/shortcut-btns.vue`
+- **能力域**：输入交互
+- **能力说明**：快捷指令列表入口，内部组合多个 ShortcutBtn。
+
+> **能力域**：输入交互
+
+快捷指令按钮列表，内置**响应式溢出收起**：根据容器实际宽度动态计算可见数量，超出部分自动收入"更多"下拉菜单。
+
+通常由 `ChatInput` 内部使用，一般不需要手动引入。
+
+## 组件结构
+
+```
+div.ai-shortcut-btns（flex，gap: 4px，width: 100%，min-width: 168px，max-width: 1000px，overflow: hidden）
+  │
+  ├── ShortcutBtn.ai-shortcut-btns-item × N（每个快捷指令）
+  │     height: 24px，padding: 0 6px，white-space: nowrap，background: #fff，border-radius: 4px
+  │     溢出时追加 .ai-shortcut-btns-item-hidden（position: absolute; visibility: hidden; pointer-events: none; opacity: 0）
+  │       注意：隐藏项仍在 DOM 中，仅通过 CSS 不可见，offsetWidth 仍可读
+  │
+  └── [hiddenShortcuts.length > 0] Tippy（trigger="manual"，append-to="body"，interactive）
+        │  offset=[0,6]，z-index=SHORTCUT_MENU_Z_INDEX，theme="ai-chat-box-light light"
+        ├── ShortcutBtn.ai-shortcut-btns-more（触发按钮）
+        │     MoreAgentIcon（rotate(90deg)） + "更多"
+        └── #content: div.ai-shortcut-menu
+              ShortcutBtn（mode="menu"） × 隐藏数量
+```
+
+## 响应式溢出机制（useObserverVisibleList）
+
+组件使用 `ResizeObserver` 监听容器宽度变化，自动计算可见按钮列表：
+
+```
+calculateVisibleMenuItems 执行逻辑：
+  1. 遍历 shortcuts（按顺序）
+  2. 每项计算：neededWidth = totalWidth + itemWidth + gap（非首项才加 gap）
+  3. 判断：neededWidth + gap + moreButtonWidth ≤ containerWidth
+       → true：加入 visibleItems，更新 totalWidth
+       → false：break（后续项全部进入"更多"菜单）
+  4. 触发时机：ResizeObserver 回调 / itemRefs 变化 / moreItemRef 变化
+```
+
+- `shortcuts` prop 通过 `computed(() => props.shortcuts)` 包装为 `ComputedRef` 传入 `useObserverVisibleList`，确保 items 变化时计算逻辑能访问到最新数据
+- `shortcuts` prop 更新时（深度 watch），`itemRefs` 重置为同等长度的 null 数组，再等待下一帧重新计算
+- 隐藏项 = `shortcuts.filter(s => !visibleItems.includes(s))`，保持原始顺序
+- `ResizeObserver` 在 `onScopeDispose` 时断开，无内存泄漏
+
+## 基础用法
+
+```vue
+<template>
+  <ShortcutBtns
+    :shortcuts="shortcuts"
+    @select-shortcut="handleSelectShortcut"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ShortcutBtns } from '@blueking/chat-x';
+  import type { Shortcut } from '@blueking/chat-x';
+
+  const shortcuts: Shortcut[] = [
+    { id: 'ask', name: '问问小鲸' },
+    { id: 'translate', name: '翻译' },
+    { id: 'summarize', name: '总结' },
+    { id: 'explain', name: '解释代码' },
+    { id: 'code-review', name: '代码审查' },
+  ];
+
+  const handleSelectShortcut = (shortcut: Shortcut) => {
+    console.log('选择了:', shortcut.name);
+  };
+</script>
+```
+
+## 带描述的快捷指令
+
+`description` 字段由 `ShortcutRender` 表单弹窗使用（悬浮提示或说明文字），本组件不直接渲染：
+
+```vue
+<template>
+  <ShortcutBtns
+    :shortcuts="shortcuts"
+    @select-shortcut="handleSelectShortcut"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ShortcutBtns } from '@blueking/chat-x';
+  import type { Shortcut } from '@blueking/chat-x';
+
+  const shortcuts: Shortcut[] = [
+    { id: 'translate', name: '翻译', description: '将文本翻译成指定语言' },
+    { id: 'summarize', name: '总结', description: '自动总结长文本的核心要点' },
+    { id: 'explain', name: '解释', description: '解释代码或概念' },
+  ];
+</script>
+```
+
+## 带表单的快捷指令
+
+配置 `components` 后，`@select-shortcut` 事件仍正常触发，**表单弹窗逻辑需由父组件配合 `ShortcutRender` 实现**：
+
+```vue
+<template>
+  <ShortcutBtns
+    :shortcuts="shortcuts"
+    @select-shortcut="handleSelectShortcut"
+  />
+  <ShortcutRender
+    v-if="activeShortcut"
+    :shortcut="activeShortcut"
+    @submit="handleFormSubmit"
+    @cancel="activeShortcut = null"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ShortcutBtns, ShortcutRender } from '@blueking/chat-x';
+  import type { Shortcut } from '@blueking/chat-x';
+
+  const activeShortcut = ref<Shortcut | null>(null);
+
+  const shortcuts: Shortcut[] = [
+    {
+      id: 'translate',
+      name: '翻译',
+      description: '将文本翻译成指定语言',
+      components: [
+        {
+          type: 'select',
+          key: 'targetLang',
+          name: '目标语言',
+          props: {
+            options: [
+              { label: '英文', value: 'en' },
+              { label: '中文', value: 'zh' },
+            ],
+          },
+        },
+        { type: 'textarea', key: 'content', name: '翻译内容', fillBack: true },
+      ],
+    },
+    {
+      id: 'code-gen',
+      name: '代码生成',
+      components: [
+        { type: 'input', key: 'language', name: '编程语言' },
+        { type: 'textarea', key: 'description', name: '功能描述', fillBack: true },
+      ],
+    },
+  ];
+
+  const handleSelectShortcut = (shortcut: Shortcut) => {
+    if (shortcut.components?.length) {
+      activeShortcut.value = shortcut; // 打开表单弹窗
+    } else {
+      sendMessage(shortcut); // 直接发送
+    }
+  };
+</script>
+```
+
+## 响应式溢出（"更多"菜单）
+
+当按钮数量超出容器可用宽度时，自动显示"更多"按钮，点击展开下拉菜单：
+
+> 该 Demo 容器较窄时会自动触发溢出收起效果。`manyShortcuts` 共 12 项，超出容器宽度的按钮进入"更多"下拉菜单。
+
+## API
+
+### Props
+
+| 属性名    | 类型         | 必填 | 说明                                                                |
+| --------- | ------------ | ---- | ------------------------------------------------------------------- |
+| shortcuts | `Shortcut[]` | 是   | 快捷指令列表；`v-for` 使用 `shortcut.key \|\| shortcut.id` 作为 key |
+
+### Events
+
+| 事件名          | 参数                   | 说明                                                                         |
+| --------------- | ---------------------- | ---------------------------------------------------------------------------- |
+| select-shortcut | `(shortcut: Shortcut)` | 点击任意快捷指令（含"更多"菜单中的项）时触发；从"更多"菜单选择后菜单自动关闭 |
+
+## 类型定义
+
+```typescript
+interface Shortcut {
+  id: string;
+  name: string;
+  key?: string; // 自定义 v-for key，优先于 id
+  description?: string;
+  icon?: string | VNode | ((h: typeof h) => Component | VNode);
+  components?: ShortcutComponent[];
+  formModel?: Record<string, unknown>;
+}
+
+type ShortcutComponent =
+  | InputShortcutComponent // type: 'input'
+  | TextareaShortcutComponent // type: 'textarea'
+  | NumberShortcutComponent // type: 'number'
+  | SelectShortcutComponent // type: 'select'
+  | CheckboxGroupShortcutComponent // type: 'checkboxGroup'
+  | RadioGroupShortcutComponent // type: 'radioGroup'
+  | SwitcherShortcutComponent // type: 'switcher'
+  | TextShortcutComponent; // type: 'text'（纯文本展示）
+
+interface BaseShortcutComponent<T> {
+  type: T;
+  key: string; // 表单字段 key，对应 formModel 中的属性名
+  name?: string; // 表单项 label
+  fillBack?: boolean; // true 时，该字段值在提交后回填至聊天输入框
+  props?: Record<string, any>; // 传给底层 bkui-vue 组件的 props
+  formItemProps?: Record<string, any>; // 传给 bkui-vue Form.Item 的 props
+}
+```
+
+### 表单组件类型
+
+| type 值         | 底层组件                  | 说明                                    |
+| --------------- | ------------------------- | --------------------------------------- |
+| `input`         | bkui-vue Input            | 单行文本输入                            |
+| `textarea`      | bkui-vue Input (textarea) | 多行文本输入                            |
+| `number`        | bkui-vue Input (number)   | 数字输入                                |
+| `select`        | bkui-vue Select           | 下拉选择，通过 `props.options` 配置选项 |
+| `checkboxGroup` | bkui-vue Checkbox.Group   | 多选框组                                |
+| `radioGroup`    | bkui-vue Radio.Group      | 单选框组                                |
+| `switcher`      | bkui-vue Switcher         | 开关                                    |
+| `text`          | 纯文本                    | 仅展示说明文字，不收集值                |
+
+## 样式说明
+
+| 类名                         | 样式                                                                       | 说明                                               |
+| ---------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------- |
+| `.ai-shortcut-btns`             | `width: 100%; min-width: 168px; max-width: 1000px; overflow: hidden`       | 容器，宽度撑满父元素，超出 1000px 截断             |
+| `.ai-shortcut-btns-item`        | `height: 24px; padding: 0 6px; background: #fff; border-radius: 4px`       | 每个快捷指令按钮的外层包装 class                   |
+| `.ai-shortcut-btns-item-hidden` | `position: absolute; visibility: hidden; pointer-events: none; opacity: 0` | 溢出按钮的隐藏态；仍在 DOM 中以便 offsetWidth 计算 |
+| `.ai-shortcut-btns-more`        | `flex-shrink: 0; padding: 0 6px`                                           | "更多"按钮，`MoreAgentIcon` 旋转 90°               |
+| `.ai-shortcut-menu`             | `@include menu.ai-common-menu-style`                                       | 下拉菜单容器样式                                   |
+
+## 注意事项
+
+1. **`key` 字段优先于 `id`**：`v-for` 使用 `shortcut.key || shortcut.id`，当多个指令 `id` 相同但代表不同实例时，可通过 `key` 字段区分
+2. **溢出项不可交互**：`.ai-shortcut-btns-item-hidden` 通过 `pointer-events: none` 屏蔽点击，不会误触发事件
+3. **"更多"菜单 Teleport 至 body**：Tippy 使用 `append-to="body"`，避免被父容器的 `overflow: hidden` 裁剪
+4. **容器宽度限制**：`min-width: 168px` 和 `max-width: 1000px` 来自 `$chat-input-min-width` / `$chat-input-max-width` 变量，与输入框宽度保持一致
+5. **表单流程在外部**：`ShortcutBtns` 只负责显示和触发事件，`components` 的表单弹窗逻辑需配合 `ShortcutRender` 实现（`ChatInput` 已内置此流程）
+
+## 关联组件
+
+- [ShortcutBtn](/components/input/shortcut-btn) — 列表项基础组件
+- [ChatInput](/components/input/chat-input) — 默认嵌入输入框底部
+- [ShortcutRender](/components/input/shortcut-render) — 表单类快捷指令的表单渲染

package/skills/blueking-chat-x/references/components/shortcut-render.md

@@ -0,0 +1,424 @@
+# ShortcutRender 快捷指令表单
+
+> 能力域：输入交互 ｜ 导入：`import { ShortcutRender } from '@blueking/chat-x'` ｜ since 1.0.0
+
+渲染快捷指令 components 表单并回传确认数据。 源码位置：src/components/ai-shortcut/shortcut-render/shortcut-render.vue。
+
+**关联**：shortcut-btn（与快捷指令 Shortcut 元数据一致，表单提交前在列表中选中入口）、chat-input（提交或取消后与输入框内容与状态联动）、chat-container（顶层聊天布局中承载快捷表单区域）
+
+---
+
+# ShortcutRender 快捷指令渲染器
+## 源码事实
+
+- **源码位置**：`src/components/ai-shortcut/shortcut-render/shortcut-render.vue`
+- **能力域**：输入交互
+- **能力说明**：渲染快捷指令 components 表单并回传确认数据。
+
+> **能力域**：输入交互
+
+快捷指令表单渲染组件，将 `Shortcut.components` 配置自动渲染为可交互表单（基于 bkui-vue 的 `Form`），支持 8 种控件类型、两列网格布局、必填校验和内置提交/取消操作。
+
+## 组件结构
+
+```
+┌─────────────────────────────────────────────────┐
+│  .ai-shortcut-render-header（渐变左边框）            │
+│  ✧ ThinkingIcon  快捷指令名称           ✕ Close  │
+├─────────────────────────────────────────────────┤
+│  .ai-shortcut-render-content（max-height: 424px，   │
+│   overflow-y: auto）                             │
+│  ┌─────────────┬─────────────┐                   │
+│  │ FormItem    │ FormItem    │  ← 两列网格        │
+│  ├─────────────┴─────────────┤                   │
+│  │    textarea（span 2）     │  ← 独占一行        │
+│  ├─────────────────────────── ┤                   │
+│  │  提交    取消（sticky）    │  ← 底部始终可见    │
+│  └─────────────────────────── ┘                   │
+└─────────────────────────────────────────────────┘
+```
+
+> 底部操作栏使用 `position: sticky; bottom: 1px`，滚动长表单时始终固定在底部可见区域。
+
+## 基础用法
+
+传入 `name` 和 `components` 即可渲染一个快捷指令表单：
+
+```vue
+<template>
+  <ShortcutRender
+    :name="shortcut.name"
+    :components="shortcut.components"
+    @close="handleClose"
+    @submit="handleSubmit"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ShortcutRender, type Shortcut } from '@blueking/chat-x';
+
+  const shortcut: Shortcut = {
+    id: 'translate',
+    name: '翻译',
+    components: [
+      {
+        type: 'select',
+        key: 'targetLang',
+        name: '目标语言',
+        default: 'en',
+        options: [
+          { label: '英文', value: 'en' },
+          { label: '中文', value: 'zh' },
+          { label: '日文', value: 'ja' },
+        ],
+      },
+      {
+        type: 'textarea',
+        key: 'content',
+        name: '翻译内容',
+        fillBack: true,
+        placeholder: '请输入要翻译的内容',
+        rows: 4,
+      },
+    ],
+  };
+
+  const handleClose = () => console.log('关闭');
+  const handleSubmit = (formModel: Record<string, unknown>) => {
+    // { targetLang: 'en', content: '...' }
+    console.log('提交:', formModel);
+  };
+</script>
+```
+
+**渲染效果**
+
+## 全部表单类型
+
+`ShortcutRender` 支持 8 种控件类型，通过 `type` 字段指定：
+
+```vue
+<script setup lang="ts">
+  import { type ShortcutComponent } from '@blueking/chat-x';
+
+  const components: ShortcutComponent[] = [
+    // 单行文本输入
+    { type: 'input', key: 'language', name: '编程语言', placeholder: '如：TypeScript、Python' },
+    // 数字输入（支持 min/max）
+    { type: 'number', key: 'maxLines', name: '最大行数', default: '50', min: 1, max: 500 },
+    // 下拉选择
+    {
+      type: 'select',
+      key: 'style',
+      name: '代码风格',
+      default: 'concise',
+      options: [
+        { label: '简洁', value: 'concise' },
+        { label: '详细注释', value: 'detailed' },
+      ],
+    },
+    // 单选组
+    {
+      type: 'radioGroup',
+      key: 'outputFormat',
+      name: '输出格式',
+      default: 'code',
+      options: [
+        { label: '代码块', value: 'code' },
+        { label: '文件', value: 'file' },
+      ],
+    },
+    // 多选组
+    {
+      type: 'checkboxGroup',
+      key: 'features',
+      name: '包含功能',
+      options: [
+        { label: '注释', value: 'comments' },
+        { label: '错误处理', value: 'error-handling' },
+      ],
+    },
+    // 开关
+    { type: 'switcher', key: 'async', name: '异步函数' },
+    // 多行文本（独占一行）
+    {
+      type: 'textarea',
+      key: 'description',
+      name: '功能描述',
+      fillBack: true,
+      rows: 3,
+      placeholder: '请详细描述需要生成的代码功能',
+    },
+  ];
+</script>
+```
+
+**渲染效果**
+
+## 表单初始值
+
+### 通过 `component.default`（推荐）
+
+直接在 `ShortcutComponent` 上设置 `default`，该字段在表单初始化时被优先使用：
+
+```typescript
+const components: ShortcutComponent[] = [
+  {
+    type: 'select',
+    key: 'lang',
+    name: '语言',
+    default: 'zh', // ← 初始选中"中文"
+    options: [
+      { label: '中文', value: 'zh' },
+      { label: '英文', value: 'en' },
+    ],
+  },
+];
+```
+
+### 通过 `formModel` prop
+
+`formModel` 适合传入**不在 `components` 中的额外字段**，或特殊场景下的外部初始值。
+
+```vue
+<template>
+  <ShortcutRender
+    name="搜索"
+    :components="components"
+    :form-model="initialValues"
+    @submit="handleSubmit"
+  />
+</template>
+
+<script setup lang="ts">
+  const components = [
+    { type: 'input', key: 'keyword', name: '关键词' },
+    {
+      type: 'select',
+      key: 'scope',
+      name: '范围',
+      options: [
+        { label: '全部', value: 'all' },
+        { label: '标题', value: 'title' },
+      ],
+    },
+  ];
+
+  // formModel 中与 components 同名的 key 会被 component.default 覆盖
+  // 若 component 没有设置 default，对应 formModel 的值也会被 undefined 覆盖
+  const initialValues = { keyword: 'Vue 3', scope: 'title' };
+</script>
+```
+
+**初始化优先级（`watchEffect` 执行顺序）**：
+
+```
+① 先写入 formModel 中的所有 key-value
+② 再遍历 components，对每个 component.key 写入：
+   component.default ?? component.props?.default ?? component.props?.modelValue
+```
+
+> **注意**：步骤 ② 会覆盖步骤 ① 的值。若某个 component 没有设置 `default`，该 key 会被写入 `undefined`，**formModel 中对应的值会丢失**。因此，当 component 和 formModel 存在同名 key 时，应在 component 上设置 `default`，而非依赖 `formModel`。
+
+## 必填校验（fillBack）
+
+`fillBack: true` 将表单项映射为 bkui-vue `Form.FormItem` 的 `required: true`，提交时若为空则阻止提交并展示错误提示：
+
+```typescript
+const components: ShortcutComponent[] = [
+  {
+    type: 'input',
+    key: 'title',
+    name: '标题',
+    fillBack: true, // 必填
+    placeholder: '请输入标题',
+  },
+  {
+    type: 'textarea',
+    key: 'content',
+    name: '内容',
+    fillBack: true, // 必填
+    rows: 5,
+  },
+  {
+    type: 'select',
+    key: 'category',
+    name: '分类', // 选填（无 fillBack）
+    options: [
+      { label: '技术', value: 'tech' },
+      { label: '业务', value: 'biz' },
+    ],
+  },
+];
+```
+
+> `fillBack` 同时具有语义作用：在 `ChatInput`/`UserMessage` 场景下，标记了 `fillBack: true` 的字段内容会被回填到对话输入框中。
+
+## 布局规则
+
+表单使用 **两列网格**（`grid-template-columns: repeat(2, 1fr)`）排列：
+
+| 情况                                                      | 占列数                    |
+| --------------------------------------------------------- | ------------------------- |
+| `type === 'textarea'`                                     | 始终 `span 2`（独占一行） |
+| 最后一个 item，且前面所有 item 累计列数为偶数（独占新行） | `span 2`                  |
+| 其他                                                      | `auto`（占 1 列）         |
+
+```
+┌─────────────┬─────────────┐
+│   input     │   number    │  ← 各占半行
+├─────────────┴─────────────┤
+│         textarea          │  ← 独占一行
+├─────────────┬─────────────┤
+│   select    │  switcher   │  ← 各占半行
+├─────────────┴─────────────┤
+│    最后一个（奇数起新行）  │  ← 自动独占
+└───────────────────────────┘
+```
+
+## 透传底层组件 props
+
+通过 `component.props` 可直接透传给 bkui-vue 底层控件，`component.props.options` 优先于 `component.options`：
+
+```typescript
+const components: ShortcutComponent[] = [
+  {
+    type: 'select',
+    key: 'lang',
+    name: '语言',
+    // 方式一：通过 component.options（常规）
+    options: [{ label: '中文', value: 'zh' }],
+    // 方式二：通过 component.props（优先级更高，覆盖 options）
+    props: {
+      options: [{ label: '英文', value: 'en' }], // 此处会覆盖上面的 options
+      clearable: true, // 透传给 bkui-vue Select 的其他 prop
+    },
+  },
+  {
+    type: 'input',
+    key: 'text',
+    name: '文本',
+    props: {
+      clearable: true, // 透传给 bkui-vue Input
+      maxlength: 100,
+    },
+  },
+];
+```
+
+通过 `component.formItemProps` 透传给 `Form.FormItem`：
+
+```typescript
+{
+  type: 'input',
+  key: 'email',
+  name: '邮箱',
+  formItemProps: {
+    description: '请输入有效的邮箱地址',  // bkui-vue FormItem 的 description prop
+  },
+}
+```
+
+## API
+
+### Props
+
+| 属性名      | 类型                      | 默认值 | 说明                                                                 |
+| ----------- | ------------------------- | ------ | -------------------------------------------------------------------- |
+| id          | `string`                  | —      | 快捷指令唯一标识（透传，不影响表单渲染）                             |
+| name        | `string`                  | —      | 表单标题，显示在头部栏                                               |
+| description | `string`                  | —      | 快捷指令描述（透传，组件内部不渲染）                                 |
+| components  | `ShortcutComponent[]`     | —      | 表单控件配置列表                                                     |
+| formModel   | `Record<string, unknown>` | —      | 外部初始值；与 `components` 同名 key 时，以 `component.default` 为准 |
+
+### Events
+
+| 事件名 | 参数                                   | 触发时机                                   |
+| ------ | -------------------------------------- | ------------------------------------------ |
+| close  | —                                      | 点击头部关闭图标 **或** 底部取消按钮时触发 |
+| submit | `(formModel: Record<string, unknown>)` | 表单校验通过后点击提交按钮触发             |
+
+## ShortcutComponent 配置项
+
+### 通用字段
+
+| 字段          | 类型                                 | 必填 | 说明                                                                                       |
+| ------------- | ------------------------------------ | ---- | ------------------------------------------------------------------------------------------ |
+| type          | 见[表单类型](#表单组件类型)          | ✓    | 控件类型；未知类型返回 `null`，不渲染                                                      |
+| key           | `string`                             | ✓    | 表单字段名；`submit` 事件返回对象以此为 key；同时作为校验 property                         |
+| name          | `string`                             | —    | 表单项标签；优先于 `formItemProps.label`，通过 `#label` 插槽渲染为 `.shortcut-render-form-label` |
+| default       | `string`                             | —    | 字段初始值；优先于 `formModel`，在 `watchEffect` 中覆盖写入                                |
+| fillBack      | `boolean`                            | —    | `true` 时映射为 `required: true`（必填校验），同时标记回填语义                             |
+| placeholder   | `string`                             | —    | 占位文本（`input` / `textarea` / `number` 可用）                                           |
+| rows          | `number`                             | —    | 文本行数（`textarea` 可用）                                                                |
+| min           | `number`                             | —    | 最小值（`number` 可用）                                                                    |
+| max           | `number`                             | —    | 最大值（`number` 可用）                                                                    |
+| options       | `{ label: string; value: string }[]` | —    | 选项列表（`select` / `radioGroup` / `checkboxGroup` 需要）；`component.props.options` 优先 |
+| props         | `object`                             | —    | 直接透传给底层 bkui-vue 控件的 props；`options` 优先于 `component.options`                 |
+| formItemProps | `object`                             | —    | 直接透传给 `Form.FormItem` 的 props                                                        |
+
+### 表单组件类型
+
+| `type`          | 底层控件               | 说明                         |
+| --------------- | ---------------------- | ---------------------------- |
+| `input`         | `Input`                | 单行文本输入框               |
+| `text`          | `Input`                | 同 `input`，兼容旧版写法     |
+| `textarea`      | `Input[type=textarea]` | 多行文本，**始终独占一行**   |
+| `number`        | `Input[type=number]`   | 数字输入，支持 `min` / `max` |
+| `select`        | `Select`               | 下拉选择，需配置 `options`   |
+| `radioGroup`    | `Radio.Group`          | 单选组，需配置 `options`     |
+| `checkboxGroup` | `Checkbox.Group`       | 多选组，需配置 `options`     |
+| `switcher`      | `Switcher`             | 开关，值为 `boolean`         |
+| 其他            | —                      | 返回 `null`，不渲染任何控件  |
+
+## 类型定义
+
+```typescript
+import type { Shortcut, ShortcutComponent } from '@blueking/chat-x';
+
+interface Shortcut {
+  id?: string;
+  name?: string;
+  description?: string;
+  icon?: string | VNode | ((h: typeof h) => Component | VNode);
+  components?: ShortcutComponent[];
+  formModel?: Record<string, unknown>;
+}
+
+// ShortcutComponent 是各具体类型的联合类型
+type ShortcutComponent =
+  | InputShortcutComponent
+  | TextShortcutComponent
+  | TextareaShortcutComponent
+  | NumberShortcutComponent
+  | SelectShortcutComponent
+  | RadioGroupShortcutComponent
+  | CheckboxGroupShortcutComponent
+  | SwitcherShortcutComponent;
+
+// 所有类型共有字段（BaseShortcutComponent）
+interface BaseShortcutComponent {
+  type: string;
+  key: string;
+  name?: string;
+  default?: string;
+  fillBack?: boolean;
+  placeholder?: string;
+  rows?: number;
+  min?: number;
+  max?: number;
+  options?: { label: string; value: string }[];
+  props?: Record<string, unknown>; // 透传给底层控件
+  formItemProps?: Record<string, unknown>; // 透传给 Form.FormItem
+}
+```
+
+## 样式说明
+
+表单项与控件会附加类型化 class，便于样式覆盖：`shortcut-render-form-item_{type}`（如 `_radio`、`_checkbox`），单选/多选项子项为 `shortcut-render-form-item_radio` / `shortcut-render-form-item_checkbox`。表单项标签使用 BEM 风格类名 `shortcut-render-form-label`。
+
+## 关联组件
+
+- [ShortcutBtn](/components/input/shortcut-btn) — 与 Shortcut 数据模型一致的入口按钮
+- [ChatInput](/components/input/chat-input) — 输入区与快捷指令流程联动
+- [ChatContainer](/components/setup/chat-container) — 顶层布局中挂载快捷表单