king-design-analyzer 2.1.9 → 2.2.1

package/docs_for_llm/treeselect.doc.md

@@ -12,75 +12,132 @@ import { TreeSelect } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| value | `any` | `""` | 否 | 当前选择的值，可用 v-model 双向绑定 | `<TreeSelect v-model="value"></TreeSelect>` |
-| data | `TreeDataItem[]` | `undefined` | 是 | 要渲染的树形数据 | `<TreeSelect :data="treeData"></TreeSelect>` |
-| multiple | `boolean` | `false` | 否 | 是否支持多选 | `<TreeSelect multiple></TreeSelect>` |
-| checkbox | `boolean` | `false` | 否 | 是否展示复选框 | `<TreeSelect checkbox></TreeSelect>` |
-| uncorrelated | `boolean` | `false` | 否 | 父子 checkbox 选中状态是否互不关联 | `<TreeSelect checkbox uncorrelated></TreeSelect>` |
-| filterable | `boolean` | `false` | 否 | 是否支持筛选 | `<TreeSelect filterable></TreeSelect>` |
-| filter | `(keywords: string, data: TreeDataItem) => boolean` | `undefined` | 否 | 自定义筛选规则函数 | `<TreeSelect filterable :filter="customFilter"></TreeSelect>` |
-| load | `(node: TreeNode) => Promise<void> | void` | `undefined` | 否 | 异步加载节点数据的函数 | `<TreeSelect :load="loadData"></TreeSelect>` |
-| defaultExpandAll | `boolean` | `false` | 否 | 是否默认展开所有节点 | `<TreeSelect defaultExpandAll></TreeSelect>` |
-| showLine | `boolean` | `true` | 否 | 是否展示 Tree 的对齐线 | `<TreeSelect :showLine="false"></TreeSelect>` |
-| disabled | `boolean` | `false` | 否 | 是否禁用 | `<TreeSelect disabled></TreeSelect>` |
-| clearable | `boolean` | `false` | 否 | 是否可清空 | `<TreeSelect clearable></TreeSelect>` |
-| loading | `boolean` | `false` | 否 | 数据加载状态 | `<TreeSelect :loading="isLoading"></TreeSelect>` |
-| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 尺寸 | `<TreeSelect size="small"></TreeSelect>` |
-| placeholder | `string` | `"请选择"` | 否 | 占位文案 | `<TreeSelect placeholder="请选择节点"></TreeSelect>` |
-| fluid | `boolean` | `false` | 否 | 是否宽度 100% | `<TreeSelect fluid></TreeSelect>` |
-| width | `number | string` | `undefined` | 否 | 指定宽度，自动添加单位 px | `<TreeSelect :width="300"></TreeSelect>` |
-| hideIcon | `boolean` | `false` | 否 | 是否隐藏后面的图标 | `<TreeSelect hideIcon></TreeSelect>` |
-| inline | `boolean` | `false` | 否 | 是否展示内联模式 | `<TreeSelect inline></TreeSelect>` |
-| flat | `boolean` | `false` | 否 | 是否展示扁平样式 | `<TreeSelect flat></TreeSelect>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| value | `any` | `""` | 否 | 当前选择的值，可用 v-model 双向绑定 | - | `<TreeSelect v-model="value">` |
+| data | `TreeDataItem[]` | `undefined` | 是 | 要渲染的树形数据 | - | `<TreeSelect :data="treeData">` |
+| multiple | `boolean` | `false` | 否 | 是否支持多选 | - | `<TreeSelect multiple>` |
+| checkbox | `boolean` | `false` | 否 | 是否展示复选框 | - | `<TreeSelect checkbox>` |
+| uncorrelated | `boolean` | `false` | 否 | 父子 checkbox 选中状态是否互不关联 | - | `<TreeSelect checkbox uncorrelated>` |
+| filterable | `boolean` | `false` | 否 | 是否支持筛选 | - | `<TreeSelect filterable>` |
+| filter | `(keywords: string, data: TreeDataItem) => boolean` | `undefined` | 否 | 自定义筛选规则函数 | - | `<TreeSelect filterable :filter="customFilter">` |
+| load | `(node: TreeNode) => Promise<void> | void` | `undefined` | 否 | 异步加载节点数据的函数 | - | `<TreeSelect :load="loadData">` |
+| defaultExpandAll | `boolean` | `false` | 否 | 是否默认展开所有节点 | - | `<TreeSelect defaultExpandAll>` |
+| showLine | `boolean` | `true` | 否 | 是否展示 Tree 的对齐线 | - | `<TreeSelect :showLine="false">` |
+| disabled | `boolean` | `false` | 否 | 是否禁用 | - | `<TreeSelect disabled>` |
+| name | `string` | `undefined` | 否 | 表单元素的 name 属性 | - | `<TreeSelect name="node">` |
+| clearable | `boolean` | `false` | 否 | 是否可清空 | - | `<TreeSelect clearable>` |
+| loading | `boolean` | `false` | 否 | 数据加载状态 | - | `<TreeSelect :loading="isLoading">` |
+| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 尺寸 | - | `<TreeSelect size="small">` |
+| placeholder | `string` | `"请选择"` | 否 | 占位文案 | - | `<TreeSelect placeholder="请选择节点">` |
+| fluid | `boolean` | `false` | 否 | 是否宽度 100% | - | `<TreeSelect fluid>` |
+| width | `number | string` | `undefined` | 否 | 指定宽度，自动添加单位 px | - | `<TreeSelect :width="300">` |
+| container | `string | ((parentDom: Element, anchor: Node | null) => Element)` | `undefined` | 否 | 指定弹出菜单追加的位置，默认 Dialog 组件会追加到 Dialog 中，其他追加到 body | - | `<TreeSelect :container="() => document.body">` |
+| hideIcon | `boolean` | `false` | 否 | 是否隐藏后面的图标 | - | `<TreeSelect hideIcon>` |
+| inline | `boolean` | `false` | 否 | 是否展示内联模式 | - | `<TreeSelect inline>` |
+| flat | `boolean` | `false` | 否 | 是否展示扁平样式 | - | `<TreeSelect flat>` |
+| show | `boolean` | `false` | 否 | 是否展示菜单项（受控模式） | - | `<TreeSelect :show="visible">` |
+| position | `Position | "left" | "bottom" | "right" | "top"` | `{my: 'left top+8', at: 'left bottom'}` | 否 | 菜单弹出的位置 | - | `<TreeSelect position="top">` |
+| nowrap | `boolean` | `false` | 否 | 选中值区域是否不换行展示，适合单行紧凑布局 | - | `<TreeSelect nowrap>` |
+| draggable | `boolean` | `false` | 否 | 多选值是否支持拖动排序 | - | `<TreeSelect multiple draggable>` |
+| virtual | `boolean` | `false` | 否 | 是否开启虚拟列表，用于大数据量场景 | - | `<TreeSelect virtual>` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
 | --- | --- | --- | --- | --- |
-| show | `@show` | 菜单弹出时触发 | `-` | `<TreeSelect @show="handleShow"></TreeSelect>` |
-| hide | `@hide` | 菜单隐藏时触发 | `-` | `<TreeSelect @hide="handleHide"></TreeSelect>` |
-
-### 事件处理函数示例
-**show**:
-```typescript
-const handleShow = () => {
-  console.log('下拉菜单已打开');
-};
-```
-
-**hide**:
-```typescript
-const handleHide = () => {
-  console.log('下拉菜单已关闭');
-};
-```
+| show | `@show` | 菜单弹出时触发 | `-` | `<TreeSelect @show="handleShow">` |
+| hide | `@hide` | 菜单隐藏时触发 | `-` | `<TreeSelect @hide="handleHide">` |
 
 ## 插槽 (Slots)
 | 插槽名 | 说明 | 模板写法 | 示例 |
 | --- | --- | --- | --- |
-| value | 自定义选择结果的展示 | `undefined` | - |
-| values | 自定义多选的选择结果的展示 | `undefined` | - |
-| prefix | 自定义输入框前面展示的内容 | `undefined` | - |
-| suffix | 自定义输入框后面展示的内容 | `undefined` | - |
-| menu | 自定义整个菜单的内容 | `undefined` | - |
+| value | 自定义单选模式下的已选值展示内容 | `#value="[value, label]"` | `<TreeSelect v-model="value" :data="treeData">
+  <template #value="[value, label]">
+    <span>{{ label }} ({{ value }})</span>
+  </template>
+</TreeSelect>` |
+| values | 自定义多选模式下的已选值展示内容 | `#values="[values, labels]"` | `<TreeSelect v-model="values" :data="treeData" multiple>
+  <template #values="[values, labels]">
+    <span>已选 {{ labels.length }} 项</span>
+  </template>
+</TreeSelect>` |
+| prefix | 扩展选择框前缀内容 | `#prefix` | `<TreeSelect :data="treeData">
+  <template #prefix>
+    <span class="k-icon-search"></span>
+  </template>
+</TreeSelect>` |
+| suffix | 扩展选择框后缀内容 | `#suffix` | `<TreeSelect :data="treeData">
+  <template #suffix>
+    <span class="suffix-tip">树</span>
+  </template>
+</TreeSelect>` |
+
+### 插槽参数说明
+**value**
+
+- 参数结构: #value="[value, label]"
+- 参数列表: `value: K`、`label: string`
+
+**values**
+
+- 参数结构: #values="[values, labels]"
+- 参数列表: `values: K[]`、`labels: string[]`
+
+**prefix**
+
+- 参数结构: 无参数
+
+**suffix**
+
+- 参数结构: 无参数
 
 ## 方法 (Methods)
 | 方法名 | 说明 | 参数 | 返回值 |
 | --- | --- | --- | --- |
+| show | 主动展开下拉树面板。 | `-` | `void` |
+| hide | 主动关闭下拉树面板。 | `-` | `void` |
+| position | 重新计算下拉树面板的位置。 | `-` | `void` |
 | expandAll | 展开所有节点 | `-` | `void` |
 
+### 方法调用示例
+**show**
+
+```typescript
+treeSelectRef.value?.show();
+```
+
+**hide**
+
+```typescript
+treeSelectRef.value?.hide();
+```
+
+**position**
+
+```typescript
+treeSelectRef.value?.position();
+```
+
+**expandAll**
+
+```typescript
+treeSelectRef.value?.expandAll();
+```
+
 ## 常见错误与正确用法 (Anti-Hallucination)
+### data 中缺少 key 属性
 > **错误用法**: `const data = [{ label: '节点1' }]; // 缺少 key`
 > **正确写法**: `const data = [{ label: '节点1', key: 'node1' }];`
 > **说明**: 每个节点必须有唯一的 key 属性，key 同时也是选中时的取值
 
+### 多选时 value 类型错误
 > **错误用法**: `const value = ref('');
 <TreeSelect v-model="value" multiple />`
 > **正确写法**: `const values = ref<string[]>([]);
 <TreeSelect v-model="values" multiple />`
 > **说明**: multiple 模式下 value 必须是数组类型
 
+### 混淆 checkbox 和 multiple
 > **错误用法**: `<TreeSelect checkbox multiple /> <!-- 通常不需要同时使用 -->`
 > **正确写法**: `<TreeSelect checkbox /> <!-- checkbox 已隐含多选 -->`
 > **说明**: checkbox 模式已经支持多选，通常不需要同时设置 multiple

package/docs_for_llm/upload.doc.md

@@ -12,74 +12,105 @@ import { Upload } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| action | `string` | `undefined` | 是 | 上传地址 | `<Upload action="/api/upload" />` |
-| files | `UploadFile[]` | `[]` | 否 | 已上传和待上传的文件列表，可用 v-model:files 双向绑定 | `<Upload v-model:files="fileList" />` |
-| type | `"select" | "drag" | "gallery"` | `"select"` | 否 | 组件风格 | `<Upload type="drag" />` |
-| accept | `string` | `undefined` | 否 | 支持上传的文件类型 | `<Upload accept=".jpg, .png, .gif" />` |
-| multiple | `boolean` | `false` | 否 | 是否支持多选文件 | `<Upload multiple />` |
-| maxSize | `number` | `undefined` | 否 | 最大上传文件大小限制(kb) | `<Upload :maxSize="500" />` |
-| limit | `number` | `undefined` | 否 | 最大上传文件数量限制 | `<Upload :limit="5" />` |
-| autoUpload | `boolean` | `true` | 否 | 是否选择文件后自动上传 | `<Upload :autoUpload="false" />` |
-| beforeUpload | `(file: UploadFile, files: UploadFile[]) => boolean | Promise<boolean>` | `undefined` | 否 | 上传前的回调函数，返回 false 取消上传，支持异步 | `<Upload :beforeUpload="handleBeforeUpload" />` |
-| beforeRemove | `(file: UploadFile, files: UploadFile[]) => boolean | Promise<boolean>` | `undefined` | 否 | 删除前的回调函数，返回 false 取消删除，支持异步 | `<Upload :beforeRemove="handleBeforeRemove" />` |
-| data | `object | ((file: UploadFile) => object)` | `undefined` | 否 | 上传附加的请求数据，可以是对象或函数 | `<Upload :data="{userId: '123'}" />` |
-| headers | `Record<string, string>` | `undefined` | 否 | 上传的请求头 | `<Upload :headers="{Authorization: 'Bearer token'}" />` |
-| name | `string` | `undefined` | 否 | 上传文件字段名 | `<Upload name="file" />` |
-| withCredentials | `boolean` | `false` | 否 | 跨域请求是否允许传送 cookie | `<Upload withCredentials />` |
-| directory | `boolean` | `false` | 否 | 是否支持上传文件夹 | `<Upload directory />` |
-| disabled | `boolean` | `false` | 否 | 是否禁用上传 | `<Upload disabled />` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| action | `string` | `undefined` | 是 | 上传地址 | - | `<Upload action="/api/upload" />` |
+| files | `UploadFile[]` | `[]` | 否 | 已上传和待上传的文件列表，可用 v-model:files 双向绑定 | - | `<Upload v-model:files="fileList" />` |
+| defaultFiles | `(Partial<UploadFile> & Pick<UploadFile, 'name' | 'url'>)[]` | `[]` | 否 | 默认文件列表，用于初始化已上传文件，不与 files 双向绑定 | - | `<Upload :defaultFiles="[{ name: 'demo.png', url: 'https://example.com/demo.png' }]" />` |
+| type | `"select" | "drag" | "gallery"` | `"select"` | 否 | 组件风格 | - | `<Upload type="drag" />` |
+| accept | `string` | `undefined` | 否 | 支持上传的文件类型 | - | `<Upload accept=".jpg, .png, .gif" />` |
+| multiple | `boolean` | `false` | 否 | 是否支持多选文件 | - | `<Upload multiple />` |
+| maxSize | `number` | `undefined` | 否 | 最大上传文件大小限制(kb) | - | `<Upload :maxSize="500" />` |
+| limit | `number` | `undefined` | 否 | 最大上传文件数量限制 | - | `<Upload :limit="5" />` |
+| autoUpload | `boolean` | `true` | 否 | 是否选择文件后自动上传 | - | `<Upload :autoUpload="false" />` |
+| beforeUpload | `(file: UploadFile, files: UploadFile[]) => boolean | Promise<boolean>` | `undefined` | 否 | 上传前的回调函数，返回 false 取消上传，支持异步 | - | `<Upload :beforeUpload="handleBeforeUpload" />` |
+| beforeRemove | `(file: UploadFile, files: UploadFile[]) => boolean | Promise<boolean>` | `undefined` | 否 | 删除前的回调函数，返回 false 取消删除，支持异步 | - | `<Upload :beforeRemove="handleBeforeRemove" />` |
+| data | `object | ((file: UploadFile) => object)` | `undefined` | 否 | 上传附加的请求数据，可以是对象或函数 | - | `<Upload :data="{userId: '123'}" />` |
+| headers | `Record<string, string>` | `undefined` | 否 | 上传的请求头 | - | `<Upload :headers="{Authorization: 'Bearer token'}" />` |
+| name | `string` | `undefined` | 否 | 上传文件字段名 | - | `<Upload name="file" />` |
+| withCredentials | `boolean` | `false` | 否 | 跨域请求是否允许传送 cookie | - | `<Upload withCredentials />` |
+| directory | `boolean` | `false` | 否 | 是否支持上传文件夹 | - | `<Upload directory />` |
+| disabled | `boolean` | `false` | 否 | 是否禁用上传 | - | `<Upload disabled />` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
 | --- | --- | --- | --- | --- |
-| progress | `@progress` | 文件上传过程中触发 | `event: ProgressEvent, xhr: XMLHttpRequest, file: UploadFile, files: UploadFile[]` | `<Upload @progress="handleProgress"></Upload>` |
-| success | `@success` | 文件上传成功时触发 | `res: any, xhr: XMLHttpRequest, file: UploadFile, files: UploadFile[]` | `<Upload @success="handleSuccess"></Upload>` |
-| error | `@error` | 文件超出限制或上传失败时触发 | `err: Error | RequestError, file: File | File[] | UploadFile, files: UploadFile[]` | `<Upload @error="handleError"></Upload>` |
+| progress | `@progress` | 文件上传过程中触发 | `event: ProgressEvent, xhr: XMLHttpRequest, file: UploadFile, files: UploadFile[]` | `<Upload @progress="handleProgress">` |
+| success | `@success` | 文件上传成功时触发 | `res: any, xhr: XMLHttpRequest, file: UploadFile, files: UploadFile[]` | `<Upload @success="handleSuccess">` |
+| error | `@error` | 文件超出限制或上传失败时触发 | `err: Error | RequestError, file: File | File[] | UploadFile, files: UploadFile[]` | `<Upload @error="handleError">` |
 
-### 事件处理函数示例
-**progress**:
+### 事件参数说明
+**progress**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| event | `ProgressEvent` | 是 | - | 进度事件 |
+| xhr | `XMLHttpRequest` | 是 | - | 请求对象 |
+| file | `UploadFile` | 是 | - | 当前文件 |
+| files | `UploadFile[]` | 是 | - | 所有文件列表 |
+
+事件处理示例:
 ```typescript
 const handleProgress = (e, xhr, file, files) => {
   console.log('进度:', file.percent);
 };
 ```
 
-**success**:
+**success**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| res | `any` | 是 | - | 服务器响应 |
+| xhr | `XMLHttpRequest` | 是 | - | 请求对象 |
+| file | `UploadFile` | 是 | - | 当前文件 |
+| files | `UploadFile[]` | 是 | - | 所有文件列表 |
+
+事件处理示例:
 ```typescript
 const handleSuccess = (res, xhr, file, files) => {
   console.log('上传成功:', res);
 };
 ```
 
-**error**:
+**error**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| err | `Error | RequestError` | 是 | - | 错误信息 |
+| file | `File | File[] | UploadFile` | 是 | - | 相关文件 |
+| files | `UploadFile[]` | 是 | - | 所有文件列表 |
+
+事件处理示例:
 ```typescript
 const handleError = (err, file, files) => {
   Message.error(err.message);
 };
 ```
 
-## 插槽 (Slots)
-| 插槽名 | 说明 | 模板写法 | 示例 |
-| --- | --- | --- | --- |
-| content | 组件展示的内容，当没有子元素时，默认会根据type展示不同的内容 | `undefined` | - |
-| tip | 组件展示的提示信息 | `undefined` | - |
-
 ## 方法 (Methods)
 | 方法名 | 说明 | 参数 | 返回值 |
 | --- | --- | --- | --- |
 | submit | 手动上传时，调用该方法开始上传 | `-` | `void` |
 
+### 方法调用示例
+**submit**
+
+```typescript
+uploadRef.value?.submit();
+```
+
 ## 常见错误与正确用法 (Anti-Hallucination)
+### 未设置 action 属性
 > **错误用法**: `<Upload /> <!-- 缺少上传地址 -->`
 > **正确写法**: `<Upload action="/api/upload" />`
 > **说明**: 必须设置 action 属性指定上传地址
 
+### maxSize 单位理解错误
 > **错误用法**: `<Upload :maxSize="1024 * 1024" /> <!-- 期望 1MB，实际是 1GB -->`
 > **正确写法**: `<Upload :maxSize="1024" /> <!-- 1MB = 1024KB -->`
 > **说明**: maxSize 单位是 KB，1MB = 1024KB
 
+### 设置 autoUpload 为 false 但忘记调用 submit
 > **错误用法**: `<Upload :autoUpload="false" /> <!-- 文件不会自动上传 -->`
 > **正确写法**: `<Upload ref="upload" :autoUpload="false" />
 // 需要手动调用 upload.value?.submit()`
@@ -195,7 +226,7 @@ const handleError = (err: any) => {
 
 手动控制上传时机
 
-**使用的 API**: 属性: action, autoUpload, multiple
+**使用的 API**: 属性: action, autoUpload, multiple | 方法: submit
 
 ```vue
 <script setup lang="ts">

package/docs_for_llm/useCRUD.doc.md

@@ -0,0 +1,49 @@
+# 增删行状态管理 (useCRUD)
+
+管理数组型表单项的新增与删除能力，并根据最大最小数量约束生成可直接用于按钮禁用态的结果。
+
+**关键词**: useCRUD, 动态表单, 新增 删除, 数组项, canAdd, canDelete
+
+## 导入语句
+```typescript
+import { useCRUD } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| models | `Ref<T[]>` | 是 | 当前表单项数组 |
+| initItem | `() => T` | 是 | 新增项的初始化工厂函数 |
+| maxInstanceNum | `number` | 否 | 最大可新增数量 |
+| minInstanceNum | `number` | 否 | 最小保留数量 |
+
+## 返回值
+```typescript
+{ canAdd: ComputedRef<{ disabled: boolean; msg: string }>; canDelete: ComputedRef<{ disabled: boolean; msg: string }>; addItem: () => void; deleteItem: (index: number) => void; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 直接复用同一个默认对象，导致新增项互相串值
+> **错误用法**: `const defaultItem = { name: '', value: '' }; useCRUD(models, () => defaultItem);`
+> **正确写法**: `useCRUD(models, () => ({ name: '', value: '' }));`
+> **说明**: initItem 应返回新的对象实例，避免多个表单项共享引用。
+
+## 使用示例
+### 动态表单行增删
+控制实例配置行的新增与删除
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useCRUD } from '@ksyun-internal/versatile';
+
+const models = ref([{ name: '', value: '' }]);
+const { canAdd, canDelete, addItem, deleteItem } = useCRUD(
+  models,
+  () => ({ name: '', value: '' }),
+  5,
+  1
+);
+</script>
+```
+

package/docs_for_llm/useCountdown.doc.md

@@ -0,0 +1,43 @@
+# 倒计时 (useCountdown)
+
+管理秒级或自定义间隔的倒计时流程，提供 start、reset、stop 和 pause/resume 等控制能力。
+
+**关键词**: useCountdown, 倒计时, remaining, 短信验证码, start stop, pause resume
+
+## 导入语句
+```typescript
+import { useCountdown } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| initialCountdown | `MaybeRefOrGetter<number>` | 是 | 初始倒计时值 |
+| options | `UseCountdownOptions` | 否 | 倒计时配置，可设置 interval、immediate、onTick 和 onComplete |
+
+## 返回值
+```typescript
+{ remaining: ShallowRef<number>; isActive: Readonly<ShallowRef<boolean>>; pause: () => void; resume: () => void; reset: (countdown?: MaybeRefOrGetter<number>) => void; stop: () => void; start: (countdown?: MaybeRefOrGetter<number>) => void; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 把 resume 当作重新开始倒计时使用
+> **错误用法**: `resume();`
+> **正确写法**: `start(); // 或 reset(60) 后再 start()`
+> **说明**: resume 只用于恢复暂停中的倒计时，不会重置剩余时间。
+
+## 使用示例
+### 短信验证码倒计时
+点击发送验证码后开始倒计时
+
+```vue
+<script setup lang="ts">
+import { useCountdown } from '@ksyun-internal/versatile';
+
+const { remaining, start, stop } = useCountdown(60, {
+  immediate: false,
+  onComplete: () => console.log('倒计时结束'),
+});
+</script>
+```
+

package/docs_for_llm/useDetail.doc.md

@@ -0,0 +1,48 @@
+# 详情页状态守卫 (useDetail)
+
+围绕详情页数据、网络状态和路由跳转封装守卫逻辑，适合详情页数据为空、请求异常或需要回退列表页的场景。
+
+**关键词**: useDetail, 详情页, networkStatus, 详情守卫, 异常跳转, refetch
+
+## 导入语句
+```typescript
+import { useDetail } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| detailData | `Ref<T | null | undefined>` | 是 | 详情数据响应式对象 |
+| networkStatus | `Ref<number | undefined>` | 是 | 网络状态响应式值 |
+| routerName | `string | RouteLocationAsRelativeGeneric | RouteLocationAsPathGeneric` | 否 | 异常时回退的路由信息 |
+| refetch | `() => void` | 否 | 重新拉取详情数据的方法 |
+| tip | `string` | 否 | 详情不存在或异常时展示的提示文案 |
+
+## 返回值
+```typescript
+void
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 只传详情数据，没有把网络状态传给 hook，导致无法区分加载中和异常态
+> **错误用法**: `useDetail(detailData);`
+> **正确写法**: `useDetail(detailData, networkStatus, 'instance-list');`
+> **说明**: networkStatus 是 hook 判断详情状态的重要输入。
+
+## 使用示例
+### 详情页请求守卫
+在详情页请求为空或异常时统一处理跳转和重试
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useDetail } from '@ksyun-internal/versatile';
+
+const detailData = ref();
+const networkStatus = ref(7);
+const refetch = () => console.log('retry');
+
+useDetail(detailData, networkStatus, { name: 'instance-list' }, refetch, '实例不存在');
+</script>
+```
+

package/docs_for_llm/useDialog.doc.md

@@ -0,0 +1,46 @@
+# 弹窗状态管理 (useDialog)
+
+为 VDialog 或 Dialog 表单场景封装显隐、校验、重置和确认按钮行为，减少弹窗表单模板中的重复状态代码。
+
+**关键词**: useDialog, VDialog, 弹窗表单, dialog, validate, show hide
+
+## 导入语句
+```typescript
+import { useDialog } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| emit | `() => any` | 否 | 父组件传入的 emit，用于联动弹窗显隐或外部事件 |
+| isShowParentDialog | `Ref<boolean | undefined>` | 否 | 父级弹窗显隐状态，适合嵌套弹窗场景 |
+
+## 返回值
+```typescript
+{ dialogRef: Ref<Dialog | undefined>; isShowDialog: Ref<boolean>; formRef: Ref<Form | undefined>; validate: Function; validateByScroll: Function; reset: Function; handleClickOkBtn: Function; handleClickValidOkBtn: Function; show: Function; hide: Function; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 调用 validate 或 handleClickValidOkBtn，但没有把 formRef 绑定到表单
+> **错误用法**: `<Form></Form>`
+> **正确写法**: `<Form ref="formRef"></Form>`
+> **说明**: 校验相关方法依赖 formRef 指向真实表单实例。
+
+## 使用示例
+### 弹窗表单
+配合 VDialog 管理弹窗显隐和表单校验
+
+```vue
+<script setup lang="ts">
+import { VDialog, useDialog } from '@ksyun-internal/versatile';
+
+const { isShowDialog, formRef, show, hide, handleClickValidOkBtn } = useDialog();
+</script>
+
+<template>
+  <VDialog v-model="isShowDialog" :ok="handleClickValidOkBtn">
+    <Form ref="formRef"></Form>
+  </VDialog>
+</template>
+```
+

package/docs_for_llm/useEntity.doc.md

@@ -0,0 +1,45 @@
+# 基础实体映射 (useEntity)
+
+根据单个 ID 和基础列表做实体同步回调，适合简单的字符串或数字值映射场景。
+
+**关键词**: useEntity, 简单实体映射, id value, 回调同步, 基础列表, 单值
+
+## 导入语句
+```typescript
+import { useEntity } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| id | `Ref<string | number | undefined | null>` | 是 | 当前选中的 ID |
+| list | `Ref<string[] | number[] | undefined | null>` | 是 | 基础值列表 |
+| emit | `(entity: string | number | null | undefined) => void` | 否 | 值变化时的回调 |
+| isNeedDefaultValue | `boolean` | 否 | 是否需要默认值处理 |
+
+## 返回值
+```typescript
+void
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 把 useEntity 当成返回实体 Ref 的 hook 使用
+> **错误用法**: `const entity = useEntity(id, list);`
+> **正确写法**: `useEntity(id, list, (entity) => { current.value = entity; });`
+> **说明**: 该 hook 主要通过副作用回调同步值，本身不返回实体 Ref。
+
+## 使用示例
+### 基础值映射
+根据当前值从列表里查找对应实体并回调给外层
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useEntity } from '@ksyun-internal/versatile';
+
+const id = ref('cn-beijing-6a');
+const list = ref(['cn-beijing-6a', 'cn-shanghai-2a']);
+useEntity(id, list, (entity) => console.log(entity));
+</script>
+```
+

package/docs_for_llm/useEventListener.doc.md

@@ -0,0 +1,44 @@
+# 事件监听封装 (useEventListener)
+
+为 HTMLElement、window、document 或 Ref 目标统一注册事件监听，并支持 throttle、debounce 与原生 addEventListener 配置。
+
+**关键词**: useEventListener, 事件监听, window resize, debounce, throttle, addEventListener
+
+## 导入语句
+```typescript
+import { useEventListener } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| target | `HTMLElement | Window | Document | Ref<HTMLElement | null> | (() => HTMLElement | null)` | 是 | 监听目标 |
+| event | `string` | 是 | 事件名 |
+| handler | `EventListenerOrEventListenerObject` | 是 | 事件处理函数 |
+| options | `{ throttle?: number; debounce?: number; nativeOptions?: boolean | AddEventListenerOptions }` | 否 | 监听配置，支持节流、防抖和原生监听选项 |
+
+## 返回值
+```typescript
+void
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 同时配置 throttle 和 debounce，但没有明确预期
+> **错误用法**: `useEventListener(window, 'scroll', onScroll, { throttle: 100, debounce: 100 });`
+> **正确写法**: `根据场景二选一：节流滚动用 throttle，输入联想用 debounce。`
+> **说明**: 两者语义不同，建议根据业务场景明确选一种。
+
+## 使用示例
+### 监听窗口尺寸变化
+在页面中节流监听 resize 事件
+
+```vue
+<script setup lang="ts">
+import { useEventListener } from '@ksyun-internal/versatile';
+
+useEventListener(window, 'resize', () => {
+  console.log('resize');
+}, { throttle: 200 });
+</script>
+```
+

package/docs_for_llm/useFalseUntilTruthy.doc.md

@@ -0,0 +1,41 @@
+# 延迟转真布尔态 (useFalseUntilTruthy)
+
+将任意响应式值映射成布尔值，并在首次变为 truthy 前始终保持 false，适合权限、异步加载完成态和懒渲染控制。
+
+**关键词**: useFalseUntilTruthy, false until truthy, 懒渲染, 加载完成, 布尔态, 权限准备
+
+## 导入语句
+```typescript
+import { useFalseUntilTruthy } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| value | `MaybeRefOrGetter<any>` | 是 | 任意响应式值、getter 或普通值 |
+
+## 返回值
+```typescript
+Readonly<Ref<boolean>>
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 期望值在 truthy 之后再次回到 false
+> **错误用法**: `const visible = useFalseUntilTruthy(flag); // 认为 flag 再次 false 时 visible 也会 false`
+> **正确写法**: `如需双向切换，请直接使用 computed(() => !!flag.value)`
+> **说明**: 这个 hook 的语义是“在首次变为 truthy 前保持 false”，不是通用的布尔映射。
+
+## 使用示例
+### 控制懒渲染
+在异步数据真正可用前保持 false，避免中间闪烁
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useFalseUntilTruthy } from '@ksyun-internal/versatile';
+
+const dataReady = computed(() => true);
+const canRender = useFalseUntilTruthy(dataReady);
+</script>
+```
+