king-design-analyzer 2.1.9 → 2.2.0

package/docs_for_llm/form.doc.md

@@ -12,20 +12,35 @@ import { Form, FormItem } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| labelWidth | `string | number` | `undefined` | 否 | 定义所有子孙 FormItem 组件的 label 宽度 | `<Form :labelWidth="120"></Form>` |
-| layout | `"horizontal" | "vertical" | "inline"` | `"horizontal"` | 否 | 指定表单布局方式 | `<Form layout="vertical"></Form>` |
-| starOnRequired | `boolean` | `false` | 否 | 当 FormItem 必填时，是否在 label 前面展示 * | `<Form starOnRequired></Form>` |
-| size | `"default" | "small" | "mini"` | `"default"` | 否 | 定义表单之间的间隔大小 | `<Form size="small"></Form>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| labelWidth | `string | number` | `undefined` | 否 | 定义所有子孙 FormItem 组件的 label 宽度 | - | `<Form :labelWidth="120"></Form>` |
+| layout | `"horizontal" | "vertical" | "inline"` | `"horizontal"` | 否 | 指定表单布局方式 | - | `<Form layout="vertical"></Form>` |
+| starOnRequired | `boolean` | `false` | 否 | 当 FormItem 必填时，是否在 label 前面展示 * | - | `<Form starOnRequired></Form>` |
+| size | `"default" | "small" | "mini"` | `"default"` | 否 | 定义表单之间的间隔大小 | - | `<Form size="small"></Form>` |
+| acceptcharset | `string` | `undefined` | 否 | 原生 acceptcharset 属性，指定服务器可处理的字符编码 | `native` | `<Form acceptcharset="UTF-8"></Form>` |
+| autocomplete | `string` | `undefined` | 否 | 原生 autocomplete 属性，指定表单自动补全行为 | `native` | `<Form autocomplete="off"></Form>` |
+| name | `string` | `undefined` | 否 | 原生 name 属性 | `native` | `<Form name="loginForm"></Form>` |
+| rel | `string` | `undefined` | 否 | 原生 rel 属性，指定表单与目标资源的关系 | `native` | `<Form rel="external"></Form>` |
+| action | `string` | `undefined` | 否 | 原生 action 属性，指定表单提交地址 | `native` | `<Form action="/api/submit"></Form>` |
+| enctype | `string` | `undefined` | 否 | 原生 enctype 属性，指定表单提交编码类型 | `native` | `<Form enctype="multipart/form-data"></Form>` |
+| method | `"post" | "get" | "dialog"` | `undefined` | 否 | 原生 method 属性，指定表单提交方法 | `native` | `<Form method="post"></Form>` |
+| novalidate | `boolean` | `undefined` | 否 | 原生 novalidate 属性，提交时跳过原生表单校验 | `native` | `<Form novalidate></Form>` |
+| target | `string` | `undefined` | 否 | 原生 target 属性，指定表单响应的打开位置 | `native` | `<Form target="_blank"></Form>` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
 | --- | --- | --- | --- | --- |
 | submit | `@submit` | 当表单提交并且所有规则都验证通过时触发 | `event: Event` | `<Form @submit="handleSubmit"></Form>` |
 
-### 事件处理函数示例
-**submit**:
+### 事件参数说明
+**submit**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| event | `Event` | 是 | - | 原生表单提交事件对象 |
+
+事件处理示例:
 ```typescript
 const handleSubmit = (e: Event) => {
   console.log('表单验证通过，提交中...');
@@ -35,10 +50,10 @@ const handleSubmit = (e: Event) => {
 ## 方法 (Methods)
 | 方法名 | 说明 | 参数 | 返回值 |
 | --- | --- | --- | --- |
-| validate | 验证表单所有规则 | `` | `Promise<boolean>` |
-| reset | 重置表单验证状态 | `` | `void` |
-| getFirstInvalidFormItem | 获取第一条出错的 FormItem | `` | `FormItem` |
-| getAllInvalidFormItems | 获取所有校验失败的 FormItem | `` | `FormItem[]` |
+| validate | 验证表单所有规则 | `-` | `Promise<boolean>` |
+| reset | 重置表单验证状态 | `-` | `void` |
+| getFirstInvalidFormItem | 获取第一条出错的 FormItem | `-` | `FormItem` |
+| getAllInvalidFormItems | 获取所有校验失败的 FormItem | `-` | `FormItem[]` |
 
 ## 子组件 (Sub-Components)
 ### FormItem
@@ -63,6 +78,7 @@ const handleSubmit = (e: Event) => {
 - `undefined`: 往后面追加的内容
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### FormItem 配置了 rules 但未绑定 value
 > **错误用法**: `<FormItem label="用户名" :rules="{required: true}">
   <Input v-model="model.username" />
 </FormItem>`
@@ -71,14 +87,17 @@ const handleSubmit = (e: Event) => {
 </FormItem>`
 > **说明**: 使用验证规则时，必须通过 :value 属性绑定需要验证的数据，否则验证不会生效
 
+### 使用不存在的 layout 值
 > **错误用法**: `<Form layout="flex">`
 > **正确写法**: `<Form layout="horizontal">`
 > **说明**: Form 的 layout 只支持 horizontal, vertical, inline 三种值
 
+### rules 格式错误
 > **错误用法**: `<FormItem :rules="'required'">`
 > **正确写法**: `<FormItem :rules="{required: true}">`
 > **说明**: rules 必须是对象格式，key 为规则名，value 为规则参数（通常为 true 或具体值）
 
+### validate 方法未使用 await
 > **错误用法**: `const valid = form.value?.validate();
 if (valid) { /* ... */ }`
 > **正确写法**: `const valid = await form.value?.validate();
@@ -91,7 +110,7 @@ if (valid) { /* ... */ }`
 
 基本的表单验证用法
 
-**使用的 API**: 属性: label, value, rules | 事件: submit
+**使用的 API**: 属性: label, value, rules | 事件: submit | 方法: validate
 
 ```vue
 <script setup lang="ts">
@@ -271,7 +290,7 @@ const model = reactive({
 
 重置表单验证状态
 
-**使用的 API**: 属性: label, value, rules
+**使用的 API**: 属性: label, value, rules | 方法: reset
 
 ```vue
 <script setup lang="ts">

package/docs_for_llm/formiteminput.doc.md

@@ -0,0 +1,128 @@
+# 输入框表单项 (FormItemInput)
+
+带标题、必填、规则校验和辅助说明的输入框表单项，适合业务表单中承载实例名称、域名、备注等字段。
+
+**关键词**: form item input, business input, 输入框表单项, 表单输入, 名称输入
+
+**使用场景**: 常规文本输入、业务表单字段录入、高风险字段提示输入
+
+## 导入语句
+```typescript
+import { FormItemInput } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| type | `string` | `"text"` | 否 | 在原生 input 标签的 type 取值的基础上扩展了 textarea 值，当取该值时渲染成 <textarea> | `inherited:Input` | `<Input type="textarea" :rows="4" placeholder="请输入内容" />` |
+| name | `string` | `undefined` | 否 | 原生 input 标签的 name 属性 | `native`, `inherited:Input` | `<Input name="username" />` |
+| readonly | `boolean` | `false` | 否 | 是否只读 | `native`, `inherited:Input` | `<Input v-model="value" readonly />` |
+| autocomplete | `string` | `undefined` | 否 | 原生 autocomplete 属性，指定浏览器自动补全行为 | `native`, `inherited:Input` | `<Input autocomplete="username" />` |
+| autofocus | `boolean` | `undefined` | 否 | 原生 autofocus 属性，页面加载后自动聚焦输入框 | `native`, `inherited:Input` | `<Input autofocus />` |
+| form | `string` | `undefined` | 否 | 原生 form 属性，指定输入框关联的表单 id | `native`, `inherited:Input` | `<Input form="searchForm" />` |
+| maxlength | `number | string` | `undefined` | 否 | 原生 maxlength 属性，限制最大输入长度 | `native`, `inherited:Input` | `<Input :maxlength="50" showCount />` |
+| pattern | `string` | `undefined` | 否 | 原生 pattern 属性，指定输入值需要匹配的正则模式 | `native`, `inherited:Input` | `<Input pattern="[0-9]{6}" placeholder="请输入6位数字" />` |
+| required | `boolean` | `false` | 否 | 是否必填 | - | - |
+| clearable | `boolean` | `false` | 否 | 是否展示快速清除按钮 | `inherited:Input` | `<Input v-model="value" clearable />` |
+| disabled | `boolean` | `false` | 否 | 是否禁用 | `inherited:Input` | `<Input disabled placeholder="禁用状态" />` |
+| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 组件尺寸 | `inherited:Input` | `<Input size="large" placeholder="大尺寸输入框" />` |
+| rows | `number | string` | `2` | 否 | 当 type="textarea" 时，默认展示文本行数 | `native`, `inherited:Input` | `<Input type="textarea" :rows="6" />` |
+| cols | `number` | `undefined` | 否 | 原生 cols 属性，当 type="textarea" 时指定可见宽度 | `native`, `inherited:Input` | `<Input type="textarea" :cols="40" />` |
+| datalist | `string` | `undefined` | 否 | 原生 datalist 属性，关联 datalist 元素 id | `native`, `inherited:Input` | `<Input datalist="city-list" />` |
+| dirname | `string` | `undefined` | 否 | 原生 dirname 属性，提交时附带输入方向信息 | `native`, `inherited:Input` | `<Input dirname="comment.dir" />` |
+| wrap | `"hard" | "soft"` | `undefined` | 否 | 原生 wrap 属性，当 type="textarea" 时指定换行提交方式 | `native`, `inherited:Input` | `<Input type="textarea" wrap="hard" />` |
+| autoWidth | `boolean` | `false` | 否 | 是否宽度随输入的文本的长度变化而变化 | `inherited:Input` | `<Input autoWidth placeholder="宽度自适应" />` |
+| fluid | `boolean` | `false` | 否 | 是否宽度 100% | `inherited:Input` | `<Input fluid placeholder="宽度100%" />` |
+| width | `string | number` | `undefined` | 否 | 指定宽度，组件会加上单位 px | `inherited:Input` | `<Input :width="300" placeholder="宽度300px" />` |
+| stackClearIcon | `boolean` | `false` | 否 | 是否将清空按钮覆盖在 suffix 按钮上展示来节省空间 | `inherited:Input` | `<Input clearable stackClearIcon />` |
+| frozenOnInput | `boolean` | `false` | 否 | 是否在输入的过程中冻结 value 更新到视图 | `inherited:Input` | `<Input frozenOnInput />` |
+| inline | `boolean` | `false` | 否 | 是否展示内联模式 | `inherited:Input` | `<Input inline />` |
+| waveDisabled | `boolean` | `false` | 否 | 是否禁用点击波纹效果 | `inherited:Input` | `<Input waveDisabled />` |
+| resize | `"none" | "vertical" | "horizontal" | "both"` | `"vertical"` | 否 | 指定 textarea 输入框拖动调整大小的方向，默认只能垂直方向调整 | `inherited:Input` | `<Input type="textarea" resize="both" />` |
+| flat | `boolean` | `false` | 否 | 是否展示扁平样式 | `inherited:Input` | `<Input flat placeholder="扁平样式" />` |
+| showCount | `boolean` | `false` | 否 | 是否展示字符长度提示数字 | `inherited:Input` | `<Input showCount maxlength="50" />` |
+| showPassword | `boolean` | `false` | 否 | 当 type="password" 时，是否展示显隐密码按钮 | `inherited:Input` | `<Input type="password" showPassword />` |
+| modelValue | `string | null` | `undefined` | 否 | 当前输入值 | - | - |
+| hideLabel | `boolean` | `undefined` | 否 | 是否隐藏 label 区域 | - | - |
+| label | `string` | `""` | 否 | 表单项标题 | - | - |
+| placeholder | `string` | `undefined` | 否 | 输入框占位文案 | - | - |
+| tip | `string` | `undefined` | 否 | 输入框下方提示文案 | - | - |
+| warnTip | `string` | `undefined` | 否 | 警告提示文案 | - | - |
+| helper | `string` | `undefined` | 否 | 辅助说明文案 | - | - |
+| rules | `Record<string, any>` | `{}` | 否 | 表单校验规则 | - | - |
+| info | `string` | `undefined` | 否 | 信息提示文案 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| update:modelValue | `@update:modelValue` | 输入框值实时变化时触发，适合双向绑定表单字段。 | `value?: string | null` | - |
+| change:value | `@change:value` | 输入值完成一次确认变更时触发，通常用于失焦校验或联动查询。 | `value?: string | null` | - |
+
+### 事件参数说明
+**update:modelValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string | null` | 否 | - | 当前输入框中的值。 |
+
+**change:value**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string | null` | 否 | - | 本次确认后的输入值。 |
+
+## 使用示例
+### 实例名称输入项
+**场景**: 在创建实例表单中录入资源名称。
+
+结合 label、placeholder 和 tip 构造标准业务表单项。
+
+**使用的 API**: 属性: modelValue, label, placeholder, tip, required | 事件: update:modelValue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FormItemInput } from '@ksyun-internal/versatile';
+
+const instanceName = ref('web-prod-01');
+</script>
+
+<template>
+  <FormItemInput
+    v-model="instanceName"
+    label="实例名称"
+    placeholder="请输入实例名称"
+    tip="长度 2 到 63 个字符，支持字母、数字和中划线"
+    :required="true"
+  />
+</template>
+```
+
+### 带警告提示的输入项
+**场景**: 在高风险配置项旁直接展示风险和补充说明。
+
+在输入可能影响线上流量的字段时补充警告说明。
+
+**使用的 API**: 属性: modelValue, label, warnTip, info
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FormItemInput } from '@ksyun-internal/versatile';
+
+const domain = ref('api.example.com');
+</script>
+
+<template>
+  <FormItemInput
+    v-model="domain"
+    label="回源域名"
+    warn-tip="修改后可能影响现网回源路径"
+    info="请确保 DNS 已正确解析"
+  />
+</template>
+```
+
+## 相关组件
+Input, FormItemSpinner
+

package/docs_for_llm/formitemspinner.doc.md

@@ -0,0 +1,105 @@
+# 数字步进表单项 (FormItemSpinner)
+
+把数字步进器和表单项包装在一起的业务组件，适合 CPU 核数、带宽、节点数等带单位和范围限制的数值输入。
+
+**关键词**: form item spinner, number input, 数字步进, 表单项, 带单位输入
+
+**使用场景**: 数量输入、规格和配额设置、带精度控制的数值输入
+
+## 导入语句
+```typescript
+import { FormItemSpinner } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| disabled | `boolean` | `false` | 否 | 是否禁用 | `inherited:Spinner` | `<Spinner disabled />` |
+| max | `number` | `Infinity` | 否 | 最大值 | - | - |
+| min | `number` | `0` | 否 | 最小值 | - | - |
+| step | `number` | `1` | 否 | 步长 | - | - |
+| size | `"default" | "small" | "mini"` | `"default"` | 否 | 尺寸 | `inherited:Spinner` | `<Spinner size="small" />` |
+| vertical | `boolean` | `false` | 否 | 控制按钮是否竖直排列 | `inherited:Spinner` | `<Spinner vertical />` |
+| precision | `number` | `0` | 否 | 保留小数位数 | - | - |
+| formatter | `(value: number) => string` | `undefined` | 否 | 定义格式化展示值的函数 | `inherited:Spinner` | `<Spinner :formatter="(val) => `${val}%`" :parser="(val) => parseFloat(val)" /></Spinner>` |
+| parser | `(value: string) => number` | `undefined` | 否 | 与 formatter 结合使用，定义解析格式化的值的函数 | `inherited:Spinner` | `<Spinner :formatter="(val) => `${val}%`" :parser="(val) => parseFloat(val)" /></Spinner>` |
+| prefix | `string` | `undefined` | 否 | 定义展示的值的前缀，优先级低于 formatter | `inherited:Spinner` | `<Spinner prefix="¥" />` |
+| suffix | `string` | `undefined` | 否 | 定义展示的值的后缀，优先级低于 formatter | `inherited:Spinner` | `<Spinner suffix="元" />` |
+| width | `string | number` | `undefined` | 否 | 指定 Input 输入框的宽度 | `inherited:Spinner` | `<Spinner :width="150" />` |
+| forceStep | `boolean` | `false` | 否 | value 值除了边界值，都必须满足 min + step * n（n 为整数） | `inherited:Spinner` | `<Spinner :min="0" :step="5" forceStep />` |
+| modelValue | `number | null` | `undefined` | 否 | 当前数值 | - | - |
+| label | `string` | `undefined` | 否 | 表单项标题 | - | - |
+| required | `boolean` | `false` | 否 | 是否必填 | - | - |
+| rules | `Record<string, any>` | `{}` | 否 | 表单校验规则 | - | - |
+| helper | `string` | `undefined` | 否 | 辅助说明文案 | - | - |
+| info | `string` | `undefined` | 否 | 信息提示文案 | - | - |
+| unit | `string` | `undefined` | 否 | 数值单位 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| update:modelValue | `@update:modelValue` | 数值变化时触发，可用于实时计算价格、配额或资源总量。 | `value?: number | null` | - |
+
+### 事件参数说明
+**update:modelValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `number | null` | 否 | - | 当前数值输入结果。 |
+
+## 使用示例
+### 带宽数值表单项
+**场景**: 在购买页中配置带宽大小并联动价格。
+
+通过最小值、最大值和单位控制业务数值输入。
+
+**使用的 API**: 属性: modelValue, label, min, max, unit | 事件: update:modelValue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FormItemSpinner } from '@ksyun-internal/versatile';
+
+const bandwidth = ref(20);
+</script>
+
+<template>
+  <FormItemSpinner
+    v-model="bandwidth"
+    label="带宽峰值"
+    :min="1"
+    :max="200"
+    unit="Mbps"
+  />
+</template>
+```
+
+### 带精度控制的数值输入
+**场景**: 在高精度资源配置场景中输入支持小数的指标值。
+
+使用 step 和 precision 录入带小数的资源规格。
+
+**使用的 API**: 属性: modelValue, label, step, precision, unit
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FormItemSpinner } from '@ksyun-internal/versatile';
+
+const bandwidth = ref(1.5);
+</script>
+
+<template>
+  <FormItemSpinner
+    v-model="bandwidth"
+    label="弹性带宽"
+    :step="0.5"
+    :precision="1"
+    unit="Gbps"
+  />
+</template>
+```
+
+## 相关组件
+Spinner, FormItemInput, InstanceNum
+

package/docs_for_llm/formitemswitch.doc.md

@@ -0,0 +1,113 @@
+# 开关表单项 (FormItemSwitch)
+
+用于业务表单中录入布尔配置的开关表单项组件，补齐了 label、辅助说明和状态切换提示。
+
+**关键词**: form item switch, switch item, 开关表单项, 状态开关, 布尔配置
+
+**使用场景**: 启停开关、布尔配置项录入、紧凑型开关表单
+
+## 导入语句
+```typescript
+import { FormItemSwitch } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| trueValue | `any` | `true` | 否 | 开启时的值 | `inherited:Switch` | `<Switch trueValue="on" falseValue="off" />` |
+| falseValue | `any` | `false` | 否 | 关闭时的值 | `inherited:Switch` | `<Switch trueValue="1" falseValue="0" />` |
+| on | `string` | `undefined` | 否 | 开启时显示的文案 | `inherited:Switch` | `<Switch on="开" off="关" />` |
+| off | `string` | `undefined` | 否 | 关闭时显示的文案 | `inherited:Switch` | `<Switch on="ON" off="OFF" />` |
+| disabled | `boolean` | `false` | 否 | 是否禁用 | `inherited:Switch` | `<Switch disabled />` |
+| loading | `boolean` | `false` | 否 | 是否显示加载状态 | `inherited:Switch` | `<Switch :loading="isLoading" />` |
+| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 尺寸 | `inherited:Switch` | `<Switch size="small" />` |
+| width | `number | string` | `undefined` | 否 | 开关的宽度 | `inherited:Switch` | `<Switch :width="60" />` |
+| height | `number | string` | `undefined` | 否 | 开关的高度 | `inherited:Switch` | `<Switch :height="24" />` |
+| name | `string` | `undefined` | 否 | 开关的名称，用于表单提交 | `inherited:Switch` | `<Switch name="enable" />` |
+| beforeChange | `(from: any, to: any) => boolean | Promise<boolean>` | `undefined` | 否 | 切换前的拦截函数，返回 false 阻止切换，支持异步 | `inherited:Switch` | `<Switch :beforeChange="handleBeforeChange" />` |
+| modelValue | `boolean | string` | `undefined` | 否 | 当前开关值 | - | - |
+| hideLabel | `boolean` | `undefined` | 否 | 是否隐藏 label 区域 | - | - |
+| label | `string` | `""` | 否 | 表单项标题 | - | - |
+| tip | `string` | `undefined` | 否 | 辅助提示文案 | - | - |
+| helper | `string` | `undefined` | 否 | 说明文案 | - | - |
+| appendTip | `string` | `undefined` | 否 | 右侧追加提示文案 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| update:modelValue | `@update:modelValue` | 开关值变化时触发，适合直接同步布尔型配置。 | `value?: boolean | string` | - |
+| change:value | `@change:value` | 用户完成一次有效切换后触发，可用于触发联动逻辑。 | `value?: boolean | string` | - |
+| change:op | `@change:op` | 组件内部操作态变化时触发，适合跟踪启停类动作的执行过程。 | `value?: string` | - |
+
+### 事件参数说明
+**update:modelValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `boolean | string` | 否 | - | 当前开关值，可为布尔值或业务自定义值。 |
+
+**change:value**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `boolean | string` | 否 | - | 本次切换后的最终值。 |
+
+**change:op**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string` | 否 | - | 当前操作态标识，例如启用、关闭或处理中等业务态。 |
+
+## 使用示例
+### 公网访问开关
+**场景**: 在网络配置表单中控制是否开启公网能力。
+
+在表单中配置一个带说明文案的布尔开关项。
+
+**使用的 API**: 属性: modelValue, label, helper | 事件: update:modelValue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FormItemSwitch } from '@ksyun-internal/versatile';
+
+const enablePublicIp = ref(true);
+</script>
+
+<template>
+  <FormItemSwitch
+    v-model="enablePublicIp"
+    label="开启公网访问"
+    helper="关闭后实例将无法从公网直接访问"
+  />
+</template>
+```
+
+### 隐藏标题的开关项
+**场景**: 在配置卡片中以更紧凑的方式呈现布尔选项。
+
+在紧凑型表单里隐藏 label，仅保留辅助说明。
+
+**使用的 API**: 属性: modelValue, hideLabel, helper, appendTip
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FormItemSwitch } from '@ksyun-internal/versatile';
+
+const autoBackup = ref(false);
+</script>
+
+<template>
+  <FormItemSwitch
+    v-model="autoBackup"
+    :hide-label="true"
+    helper="开启后每天凌晨自动执行备份"
+    append-tip="将占用少量存储空间"
+  />
+</template>
+```
+
+## 相关组件
+Switch, FormItemInput
+

package/docs_for_llm/formitemtableconfigs.doc.md

@@ -0,0 +1,95 @@
+# 表格配置表单项 (FormItemTableConfigs)
+
+通过表格方式维护一组配置项的表单组件，适合批量录入实例规格、节点列表、挂载配置等多行数据。
+
+**关键词**: form item table configs, config table form, 配置表格, 实例配置, 批量表单行, 节点配置, 多行表单, 表格型表单项
+
+**使用场景**: 多实例配置表单、批量节点配置、确认步骤只读展示配置列表、通过表格维护一组配置项
+
+## 导入语句
+```typescript
+import { FormItemTableConfigs } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| modelValue | `any[]` | `[]` | 否 | 当前配置项数组 | - | - |
+| label | `string` | `undefined` | 否 | 表单项标题 | - | - |
+| maxInstanceNum | `number` | `undefined` | 否 | 允许添加的最大实例数 | - | - |
+| minInstanceNum | `number` | `1` | 否 | 允许保留的最小实例数 | - | - |
+| initInstanceModels | `() => Record<string, any>` | `undefined` | 是 | 初始化一条实例配置的工厂函数 | - | - |
+| addBtnText | `string` | `undefined` | 否 | 新增按钮文案 | - | - |
+| showAddBtnLabel | `boolean` | `false` | 否 | 是否显示新增按钮标签 | - | - |
+| helper | `string` | `undefined` | 否 | 辅助说明文案 | - | - |
+| info | `string` | `undefined` | 否 | 信息提示文案 | - | - |
+| fixHeader | `number` | `undefined` | 否 | 固定表头高度阈值 | - | - |
+| infinite | `boolean` | `undefined` | 否 | 是否启用无限模式 | - | - |
+| readonly | `boolean` | `undefined` | 否 | 是否为只读模式 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| update:modelValue | `@update:modelValue` | 配置项数组变化时触发，新增、删除或编辑行后都会返回最新列表。 | `value?: any[]` | - |
+
+### 事件参数说明
+**update:modelValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `any[]` | 否 | - | 当前配置项列表数组。 |
+
+## 使用示例
+### 节点配置列表维护
+**场景**: 在集群创建页面中维护多条节点或实例配置。
+
+在表单中维护多条节点或实例配置。
+
+**使用的 API**: 属性: modelValue, label, addBtnText, maxInstanceNum | 事件: update:modelValue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FormItemTableConfigs } from '@ksyun-internal/versatile';
+
+const nodes = ref([
+  { name: 'worker-01', spec: '2C4G' },
+]);
+</script>
+
+<template>
+  <FormItemTableConfigs
+    v-model="nodes"
+    label="节点配置"
+    add-btn-text="新增节点"
+    :max-instance-num="5"
+  />
+</template>
+```
+
+### 只读模式展示配置列表
+**场景**: 在提交前确认页只读展示用户已填写的表格配置。
+
+在审核或确认步骤中仅展示配置列表，不允许再编辑。
+
+**使用的 API**: 属性: modelValue, label, readonly
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { FormItemTableConfigs } from '@ksyun-internal/versatile';
+
+const instances = ref([
+  { name: 'node-01', spec: '4C8G' },
+  { name: 'node-02', spec: '4C8G' },
+]);
+</script>
+
+<template>
+  <FormItemTableConfigs v-model="instances" label="实例配置" :readonly="true" />
+</template>
+```
+
+## 相关组件
+InstanceList, InstanceNum, FormItemInput, FormItemSpinner
+

package/docs_for_llm/grid.doc.md

@@ -12,11 +12,11 @@ import { Row, Col } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| gutter | `string | number | object` | `undefined` | 否 | 栅格间距，单位 px。也可以传入对象设置响应式间距。 | `<Row :gutter="16"></Row>` |
-| justify | `"start" | "end" | "center" | "between" | "around" | "evenly"` | `undefined` | 否 | flex 布局下的水平排列方式 | `<Row justify="center"></Row>` |
-| align | `"top" | "bottom" | "middle" | "stretch" | "baseline"` | `undefined` | 否 | flex 布局下的垂直对齐方式 | `<Row align="middle"></Row>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| gutter | `string | number | object` | `undefined` | 否 | 栅格间距，单位 px。也可以传入对象设置响应式间距。 | - | `<Row :gutter="16"></Row>` |
+| justify | `"start" | "end" | "center" | "between" | "around" | "evenly"` | `undefined` | 否 | flex 布局下的水平排列方式 | - | `<Row justify="center"></Row>` |
+| align | `"top" | "bottom" | "middle" | "stretch" | "baseline"` | `undefined` | 否 | flex 布局下的垂直对齐方式 | - | `<Row align="middle"></Row>` |
 
 ## 子组件 (Sub-Components)
 ### Col
@@ -37,6 +37,7 @@ import { Row, Col } from '@king-design/vue';
 | xxl | `number | string | object` | ≥1600px 响应式栅格 | - |
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### span 总和超过 24
 > **错误用法**: `<Row>
   <Col :span="12">col-12</Col>
   <Col :span="13">col-13</Col>
@@ -47,6 +48,7 @@ import { Row, Col } from '@king-design/vue';
 </Row>`
 > **说明**: Grid 系统基于 24 栅格，一行中的 span 总和（加上 offset）不应超过 24，否则会换行。
 
+### gutter 导致的内容溢出
 > **错误用法**: `<div style="width: 100%; overflow: hidden;">
   <Row :gutter="20">...</Row>
 </div>`

package/docs_for_llm/header.doc.md

@@ -0,0 +1,85 @@
+# 顶部栏 (Header)
+
+页面级顶部栏组件，整合标题、返回、面包屑和文档入口，常用于列表页、详情页以及购买链路页的统一页头。
+
+**关键词**: header, page header, 顶部栏, 面包屑, 文档入口
+
+**使用场景**: 详情页顶部栏、列表页顶部栏、购买链路页面头部
+
+## 导入语句
+```typescript
+import { Header } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| title | `string` | `""` | 否 | 左侧标题文案 | - | - |
+| back | `() => any | RouteLocationRaw` | `undefined` | 否 | 返回配置，支持函数或路由跳转参数 | - | - |
+| doc | `DocParams` | `undefined` | 否 | 相关文档配置，通常包含中英文文档地址 | - | - |
+| docText | `string` | `"相关文档"` | 否 | 文档入口文案 | - | - |
+| newable | `boolean` | `false` | 否 | 是否启用购买链路顶部栏样式 | - | - |
+| breadcrumb | `Array<{ to: string, label: string }>` | `undefined` | 否 | 面包屑导航配置，元素格式为 { to, label } | - | - |
+
+## 插槽 (Slots)
+| 插槽名 | 说明 | 模板写法 | 示例 |
+| --- | --- | --- | --- |
+| title | 扩展顶部栏左侧标题处内容 | `<template #title>...</template>` | - |
+| titleAppend | 扩展顶部栏左侧标题后的追加内容 | `<template #titleAppend>...</template>` | - |
+| docPrepend | 扩展右侧文档入口前的内容 | `<template #docPrepend>...</template>` | - |
+| doc | 自定义右侧文档区域 | `<template #doc>...</template>` | - |
+
+## 使用示例
+### 详情页头部信息
+**场景**: 在详情页统一展示返回路径和文档入口。
+
+同时展示标题、面包屑和文档入口，形成统一的页面头部。
+
+**使用的 API**: 属性: title, breadcrumb, doc
+
+```vue
+<script setup lang="ts">
+import { Header } from '@ksyun-internal/versatile';
+
+const breadcrumb = [
+  { to: '/instance', label: '云服务器' },
+  { to: '/instance/list', label: '实例列表' },
+  { to: '/instance/detail', label: '实例详情' },
+];
+const doc = {
+  zh: 'https://docs.ksyun.com/documents/instance',
+};
+</script>
+
+<template>
+  <Header title="实例详情" :breadcrumb="breadcrumb" :doc="doc" />
+</template>
+```
+
+### 通过插槽扩展头部操作
+**场景**: 在页面头部追加状态标识和右侧快捷入口。
+
+使用 titleAppend 和 docPrepend 插槽扩展状态展示和快捷入口。
+
+**使用的 API**: 属性: title, docText
+
+```vue
+<script setup lang="ts">
+import { Header } from '@ksyun-internal/versatile';
+</script>
+
+<template>
+  <Header title="实例详情" doc-text="帮助文档">
+    <template #titleAppend>
+      <span style="margin-left: 8px; color: #18a058;">运行中</span>
+    </template>
+    <template #docPrepend>
+      <a href="/monitor">监控图表</a>
+    </template>
+  </Header>
+</template>
+```
+
+## 相关组件
+LayoutContent, LayoutListContent
+