king-design-analyzer 2.1.9 → 2.2.0

package/docs_for_llm/tag.doc.md

@@ -12,22 +12,28 @@ import { Tag, Tags } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| type | `"default" | "primary" | "success" | "warning" | "danger"` | `"default"` | 否 | 组件类型，决定标签的视觉样式 | `<Tag type="primary">主要标签</Tag>` |
-| closable | `boolean` | `false` | 否 | 是否可关闭，显示关闭按钮 | `<Tag closable @close="handleClose">可关闭标签</Tag>` |
-| closed | `boolean` | `false` | 否 | 是否已关闭（受控模式） | `<Tag closable :closed="isClosed" @close="handleClose">标签</Tag>` |
-| disabled | `boolean` | `false` | 否 | 是否展示禁用状态 | `<Tag disabled>禁用标签</Tag>` |
-| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 组件尺寸 | `<Tag size="small">小标签</Tag>` |
-| border | `"solid" | "dashed" | "none"` | `"none"` | 否 | 定义边框样式 | `<Tag border="solid">带边框标签</Tag>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| type | `"default" | "primary" | "success" | "warning" | "danger"` | `"default"` | 否 | 组件类型，决定标签的视觉样式 | - | `<Tag type="primary">主要标签</Tag>` |
+| closable | `boolean` | `false` | 否 | 是否可关闭，显示关闭按钮 | - | `<Tag closable @close="handleClose">可关闭标签</Tag>` |
+| closed | `boolean` | `false` | 否 | 是否已关闭（受控模式） | - | `<Tag closable :closed="isClosed" @close="handleClose">标签</Tag>` |
+| disabled | `boolean` | `false` | 否 | 是否展示禁用状态 | - | `<Tag disabled>禁用标签</Tag>` |
+| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 组件尺寸 | - | `<Tag size="small">小标签</Tag>` |
+| border | `"solid" | "dashed" | "none"` | `"none"` | 否 | 定义边框样式 | - | `<Tag border="solid">带边框标签</Tag>` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
 | --- | --- | --- | --- | --- |
 | close | `@close` | 标签关闭事件，点击关闭按钮时触发 | `e: MouseEvent` | `<Tag closable @close="handleClose">可关闭</Tag>` |
 
-### 事件处理函数示例
-**close**:
+### 事件参数说明
+**close**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| e | `MouseEvent` | 是 | - | 原生鼠标事件对象 |
+
+事件处理示例:
 ```typescript
 const handleClose = (e: MouseEvent) => {
   console.log('标签已关闭');
@@ -53,14 +59,17 @@ const handleClose = (e: MouseEvent) => {
 - `undefined`: 追加到后面的元素，不参与到Tags对Tag的管理中
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### 可关闭标签未使用受控模式
 > **错误用法**: `<Tag closable>标签</Tag>`
 > **正确写法**: `<Tag closable :closed="isClosed" @close="handleClose">标签</Tag>`
 > **说明**: closable 只显示关闭按钮，需要配合 closed 属性和 @close 事件来控制关闭行为
 
+### 使用不存在的 type 值
 > **错误用法**: `<Tag type="info">信息标签</Tag>`
 > **正确写法**: `<Tag type="primary">主要标签</Tag>`
 > **说明**: Tag 的 type 只支持 default, primary, success, warning, danger，不存在 info 值
 
+### 拖拽标签组未设置 key
 > **错误用法**: `<Tags draggable>
   <Tag v-for="tag in tags">{{ tag }}</Tag>
 </Tags>`

package/docs_for_llm/timeline.doc.md

@@ -0,0 +1,109 @@
+# 时间轴 (Timeline)
+
+时间轴组件，用于按时间顺序展示事件或流程记录。配合 TimelineItem 子组件使用，支持不同状态类型和自定义节点。
+
+**关键词**: timeline, 时间轴, 操作记录, 流程日志, TimelineItem, dot
+
+**使用场景**: 操作日志、订单轨迹、发布流程、任务执行记录
+
+## 导入语句
+```typescript
+import { Timeline, TimelineItem } from '@king-design/vue';
+```
+
+## 插槽 (Slots)
+| 插槽名 | 说明 | 模板写法 | 示例 |
+| --- | --- | --- | --- |
+| default | 时间轴内容，通常由多个 TimelineItem 组成。 | `<Timeline>...</Timeline>` | `<Timeline><TimelineItem>创建完成</TimelineItem><TimelineItem>审核通过</TimelineItem></Timeline>` |
+
+## 子组件 (Sub-Components)
+### TimelineItem
+时间轴节点项。
+
+| 属性名 | 类型 | 说明 | 示例 |
+| --- | --- | --- | --- |
+| type | `"primary" | "warning" | "danger" | "success"` | 节点状态类型。 | `<TimelineItem type="success">发布成功</TimelineItem>` |
+| size | `"large" | "default" | "small" | "mini"` | 节点尺寸。 | `<TimelineItem size="small">日志记录</TimelineItem>` |
+
+**插槽**:
+- `<template #dot>...</template>`: 自定义时间轴节点圆点。
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 在 Timeline 中直接写普通 div，而不是 TimelineItem
+> **错误用法**: `<Timeline><div>创建成功</div><div>发布完成</div></Timeline>`
+> **正确写法**: `<Timeline><TimelineItem>创建成功</TimelineItem><TimelineItem>发布完成</TimelineItem></Timeline>`
+> **说明**: Timeline 负责整体容器结构，具体节点应使用 TimelineItem 渲染，才能获得连线、圆点和状态样式。
+
+### 把 dot 插槽写在 Timeline 上
+> **错误用法**: `<Timeline><template #dot>1</template></Timeline>`
+> **正确写法**: `<Timeline><TimelineItem><template #dot>1</template>步骤一</TimelineItem></Timeline>`
+> **说明**: dot 是 TimelineItem 的插槽，不属于 Timeline 容器本身。
+
+## 使用示例
+### 基础用法
+**场景**: 展示任务处理过程
+
+按时间顺序展示操作记录。
+
+**使用的 API**: 属性: type | 插槽: default
+
+```vue
+<template>
+  <Timeline>
+    <TimelineItem>2026-04-20 10:00 创建任务</TimelineItem>
+    <TimelineItem>2026-04-20 10:10 分配负责人</TimelineItem>
+    <TimelineItem type="success">2026-04-20 10:30 处理完成</TimelineItem>
+  </Timeline>
+</template>
+```
+
+### 不同状态节点
+**场景**: 用时间轴展示状态变更
+
+用颜色区分不同阶段。
+
+**使用的 API**: 属性: type | 插槽: default
+
+```vue
+<template>
+  <Timeline>
+    <TimelineItem type="primary">等待执行</TimelineItem>
+    <TimelineItem type="warning">处理中</TimelineItem>
+    <TimelineItem type="danger">执行失败</TimelineItem>
+    <TimelineItem type="success">重新执行成功</TimelineItem>
+  </Timeline>
+</template>
+```
+
+### 自定义节点
+**场景**: 用图标增强时间轴状态表达
+
+通过 dot 插槽渲染图标或编号。
+
+**使用的 API**: 属性: type | 插槽: dot
+
+```vue
+<script setup lang="ts">
+import { Icon, Timeline, TimelineItem } from '@king-design/vue';
+</script>
+<template>
+  <Timeline>
+    <TimelineItem>
+      <template #dot>
+        <Icon class="k-icon-play-circle" />
+      </template>
+      服务启动
+    </TimelineItem>
+    <TimelineItem type="success">
+      <template #dot>
+        <Icon class="k-icon-check" />
+      </template>
+      健康检查通过
+    </TimelineItem>
+  </Timeline>
+</template>
+```
+
+## 相关组件
+Steps, Tag, Icon
+

package/docs_for_llm/timepicker.doc.md

@@ -12,26 +12,36 @@ import { Timepicker } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| value | `Value | Value[] | [Value, Value] | [Value, Value][]` | `""` | 否 | 当前选中的时间，可用 v-model 双向绑定。范围选择时为 [Value, Value] | `<Timepicker v-model="time" />` |
-| range | `boolean` | `false` | 否 | 是否选择时间范围 | `<Timepicker range />` |
-| multiple | `boolean` | `false` | 否 | 是否支持多选 | `<Timepicker multiple />` |
-| disabled | `boolean` | `false` | 否 | 是否禁用 | `<Timepicker disabled />` |
-| clearable | `boolean` | `false` | 否 | 是否可清空 | `<Timepicker clearable />` |
-| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 尺寸 | `<Timepicker size="small" />` |
-| placeholder | `string` | `"请选择时间"` | 否 | 占位文案 | `<Timepicker placeholder="选择开始时间" />` |
-| format | `string` | `"YYYY-MM-DD HH:mm:ss"` | 否 | 时间格式化字符串 | `<Timepicker format="HH:mm" />` |
-| valueFormat | `string` | `undefined` | 否 | value 值的格式化字符串 | `<Timepicker valueFormat="HH:mm:ss" />` |
-| showFormat | `string` | `undefined` | 否 | 展示的格式化字符串 | `<Timepicker showFormat="HH时mm分" />` |
-| step | `string` | `undefined` | 否 | 固定时间点的步长，如 "00:30" 表示每 30 分钟一个选项 | `<Timepicker step="00:30" />` |
-| min | `Value` | `undefined` | 否 | 最小可选时间 | `<Timepicker min="09:00:00" />` |
-| max | `Value` | `undefined` | 否 | 最大可选时间 | `<Timepicker max="18:00:00" />` |
-| hideIcon | `boolean` | `false` | 否 | 是否隐藏后面的图标 | `<Timepicker hideIcon />` |
-| fluid | `boolean` | `false` | 否 | 是否宽度 100% | `<Timepicker fluid />` |
-| inline | `boolean` | `false` | 否 | 是否展示内联模式 | `<Timepicker inline />` |
-| flat | `boolean` | `false` | 否 | 是否展示扁平样式 | `<Timepicker flat />` |
-| width | `number | string` | `undefined` | 否 | 指定宽度，自动添加单位 px | `<Timepicker :width="150" />` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| value | `Value | Value[] | [Value, Value] | [Value, Value][]` | `""` | 否 | 当前选中的时间，可用 v-model 双向绑定。范围选择时为 [Value, Value] | - | `<Timepicker v-model="time" />` |
+| range | `boolean` | `false` | 否 | 是否选择时间范围 | - | `<Timepicker range />` |
+| multiple | `boolean` | `false` | 否 | 是否支持多选 | - | `<Timepicker multiple />` |
+| filterable | `boolean` | `false` | 否 | 是否支持筛选输入 | - | `<Timepicker filterable />` |
+| loading | `boolean` | `false` | 否 | 数据加载状态 | - | `<Timepicker :loading="loading" />` |
+| disabled | `boolean` | `false` | 否 | 是否禁用 | - | `<Timepicker disabled />` |
+| name | `string` | `undefined` | 否 | 表单元素的 name 属性 | - | `<Timepicker name="startTime" />` |
+| clearable | `boolean` | `false` | 否 | 是否可清空 | - | `<Timepicker clearable />` |
+| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 尺寸 | - | `<Timepicker size="small" />` |
+| placeholder | `string` | `"请选择时间"` | 否 | 占位文案 | - | `<Timepicker placeholder="选择开始时间" />` |
+| format | `string` | `"YYYY-MM-DD HH:mm:ss"` | 否 | 时间格式化字符串 | - | `<Timepicker format="HH:mm" />` |
+| valueFormat | `string` | `undefined` | 否 | value 值的格式化字符串 | - | `<Timepicker valueFormat="HH:mm:ss" />` |
+| showFormat | `string` | `undefined` | 否 | 展示的格式化字符串 | - | `<Timepicker showFormat="HH时mm分" />` |
+| step | `string` | `undefined` | 否 | 固定时间点的步长，如 "00:30" 表示每 30 分钟一个选项 | - | `<Timepicker step="00:30" />` |
+| min | `Value` | `undefined` | 否 | 最小可选时间 | - | `<Timepicker min="09:00:00" />` |
+| max | `Value` | `undefined` | 否 | 最大可选时间 | - | `<Timepicker max="18:00:00" />` |
+| disabledDate | `(v: Dayjs) => boolean` | `undefined` | 否 | 禁用日期的函数，返回 true 表示禁用该日期 | - | `<Timepicker :disabledDate="(d) => d.day() === 0" />` |
+| hideIcon | `boolean` | `false` | 否 | 是否隐藏后面的图标 | - | `<Timepicker hideIcon />` |
+| fluid | `boolean` | `false` | 否 | 是否宽度 100% | - | `<Timepicker fluid />` |
+| inline | `boolean` | `false` | 否 | 是否展示内联模式 | - | `<Timepicker inline />` |
+| flat | `boolean` | `false` | 否 | 是否展示扁平样式 | - | `<Timepicker flat />` |
+| width | `number | string` | `undefined` | 否 | 指定宽度，自动添加单位 px | - | `<Timepicker :width="150" />` |
+| container | `string | ((parentDom: Element, anchor: Node | null) => Element)` | `undefined` | 否 | 指定弹出菜单追加的位置，默认 Dialog 组件会追加到 Dialog 中，其他追加到 body | - | `<Timepicker :container="() => document.body" />` |
+| show | `boolean` | `false` | 否 | 是否展示菜单项（受控模式） | - | `<Timepicker :show="visible" />` |
+| position | `Position | "left" | "bottom" | "right" | "top"` | `{my: 'left top+8', at: 'left bottom'}` | 否 | 菜单弹出的位置 | - | `<Timepicker position="top" />` |
+| nowrap | `boolean` | `false` | 否 | 选中值区域是否不换行展示，适合单行紧凑布局 | - | `<Timepicker nowrap />` |
+| draggable | `boolean` | `false` | 否 | 多选值是否支持拖动排序 | - | `<Timepicker multiple draggable />` |
+| virtual | `boolean` | `false` | 否 | 是否开启虚拟列表，用于大数据量场景 | - | `<Timepicker virtual />` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
@@ -39,48 +49,57 @@ import { Timepicker } from '@king-design/vue';
 | show | `@show` | 菜单弹出时触发 | `-` | `<Timepicker @show="handleShow" />` |
 | hide | `@hide` | 菜单隐藏时触发 | `-` | `<Timepicker @hide="handleHide" />` |
 | change | `@change` | 用户操作完成且值变化时触发 | `value: string` | `<Timepicker @change="handleChange" />` |
-| selecting | `@selecting` | 范围选择时，用户正在操作选择时触发 | `value: [Dayjs, Dayjs?]` | `<Timepicker range @selecting="handleSelecting" />` |
+| selecting | `@selecting` | 范围选择时，用户正在操作选择时触发 | `value: [Dayjs, Dayjs?], confirmed: boolean` | `<Timepicker range @selecting="handleSelecting" />` |
 
-### 事件处理函数示例
-**show**:
-```typescript
-const handleShow = () => {
-  console.log('时间选择器已打开');
-};
-```
+### 事件参数说明
+**change**
 
-**hide**:
-```typescript
-const handleHide = () => {
-  console.log('时间选择器已关闭');
-};
-```
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string` | 是 | - | 当前选择的时间值 |
 
-**change**:
+事件处理示例:
 ```typescript
 const handleChange = (value: string) => {
   console.log('选择的时间:', value);
 };
 ```
 
-**selecting**:
+**selecting**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `[Dayjs, Dayjs?]` | 是 | - | 当前选择的值 |
+| confirmed | `boolean` | 是 | - | 当前这次 selecting 是否已经进入确认完成态；常见交互过程中通常为 `false`。 |
+
+事件处理示例:
 ```typescript
-const handleSelecting = (value) => {
-  console.log('正在选择:', value);
+const handleSelecting = (value, confirmed) => {
+  console.log('正在选择:', value, confirmed);
 };
 ```
 
+## 方法 (Methods)
+| 方法名 | 说明 | 参数 | 返回值 |
+| --- | --- | --- | --- |
+| show | 主动展开时间选择面板。 | `-` | `void` |
+| hide | 主动关闭时间选择面板。 | `-` | `void` |
+| position | 重新计算时间选择面板的位置。 | `-` | `void` |
+
 ## 常见错误与正确用法 (Anti-Hallucination)
+### 范围选择时 value 类型错误
 > **错误用法**: `const time = ref('');
 <Timepicker v-model="time" range />`
 > **正确写法**: `const timeRange = ref<[string, string]>(['', '']);
 <Timepicker v-model="timeRange" range />`
 > **说明**: 当 range 为 true 时，value 必须是 [string, string] 数组
 
+### step 格式错误
 > **错误用法**: `<Timepicker step="30" /> <!-- 期望 30 分钟 -->`
 > **正确写法**: `<Timepicker step="00:30" />`
 > **说明**: step 应使用时间格式字符串，如 "00:30" 表示 30 分钟
 
+### min/max 格式与 format 不匹配
 > **错误用法**: `<Timepicker min="9:00" max="18:00" /> <!-- 缺少秒 -->`
 > **正确写法**: `<Timepicker min="09:00:00" max="18:00:00" />`
 > **说明**: min/max 应使用完整的时间格式

package/docs_for_llm/timerange.doc.md

@@ -0,0 +1,157 @@
+# 时间范围 (TimeRange)
+
+面向报表、监控和日志场景的时间范围选择组件，支持快捷区间、自定义起止时间以及时间戳格式输出。
+
+**关键词**: time range, date range, time filter, 时间范围, 时间筛选, 快捷时间, 监控时间段, 日志时间查询
+
+**使用场景**: 监控页时间筛选、报表页时间范围选择、日志页最近时间窗口查询、按快捷区间切换统计周期
+
+## 导入语句
+```typescript
+import { TimeRange } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| type | `"date" | "datetime" | "year" | "month"` | `"date"` | 否 | 组件类型 | `inherited:Datepicker` | `<Datepicker type="datetime" />` |
+| range | `boolean` | `false` | 否 | 是否选择日期范围 | `inherited:Datepicker` | `<Datepicker range />` |
+| multiple | `boolean` | `false` | 否 | 是否支持多选 | `inherited:Datepicker` | `<Datepicker multiple />` |
+| filterable | `boolean` | `false` | 否 | 是否支持筛选输入 | `inherited:Datepicker` | `<Datepicker filterable />` |
+| loading | `boolean` | `false` | 否 | 数据加载状态 | `inherited:Datepicker` | `<Datepicker :loading="loading" />` |
+| disabled | `boolean` | `false` | 否 | 是否禁用 | `inherited:Datepicker` | `<Datepicker disabled />` |
+| name | `string` | `undefined` | 否 | 表单元素的 name 属性 | `inherited:Datepicker` | `<Datepicker name="startDate" />` |
+| clearable | `boolean` | `false` | 否 | 是否可清空 | `inherited:Datepicker` | `<Datepicker clearable />` |
+| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 尺寸 | `inherited:Datepicker` | `<Datepicker size="small" />` |
+| placeholder | `string` | `"请选择日期"` | 否 | 占位文案 | `inherited:Datepicker` | `<Datepicker placeholder="选择开始日期" />` |
+| format | `string` | `"YYYY-MM-DD HH:mm:ss"` | 否 | 日期格式化字符串 | - | - |
+| valueFormat | `string` | `undefined` | 否 | value 值的日期格式化字符串 | `inherited:Datepicker` | `<Datepicker valueFormat="YYYY-MM-DD" />` |
+| showFormat | `string` | `undefined` | 否 | 展示的日期格式化字符串 | `inherited:Datepicker` | `<Datepicker showFormat="YYYY年MM月DD日" />` |
+| min | `Value` | `undefined` | 否 | 最小可选日期 | `inherited:Datepicker` | `<Datepicker min="2024-01-01" />` |
+| max | `Value` | `undefined` | 否 | 最大可选日期 | `inherited:Datepicker` | `<Datepicker max="2024-12-31" />` |
+| disabledDate | `(v: Dayjs) => boolean` | `undefined` | 否 | 禁用日期的函数，返回 true 表示禁用该日期 | `inherited:Datepicker` | `<Datepicker :disabledDate="(d) => d.day() === 0" />` |
+| shortcuts | `Shortcut[]` | `undefined` | 否 | 快捷方式配置 | `inherited:Datepicker` | `<Datepicker :shortcuts="shortcuts" />` |
+| hideIcon | `boolean` | `false` | 否 | 是否隐藏后面的图标 | `inherited:Datepicker` | `<Datepicker hideIcon />` |
+| fluid | `boolean` | `false` | 否 | 是否宽度 100% | `inherited:Datepicker` | `<Datepicker fluid />` |
+| inline | `boolean` | `false` | 否 | 是否展示内联模式 | `inherited:Datepicker` | `<Datepicker inline />` |
+| flat | `boolean` | `false` | 否 | 是否展示扁平样式 | `inherited:Datepicker` | `<Datepicker flat />` |
+| width | `number | string` | `undefined` | 否 | 指定宽度，自动添加单位 px | `inherited:Datepicker` | `<Datepicker :width="200" />` |
+| container | `Container` | `undefined` | 否 | 弹出层挂载容器 | - | - |
+| show | `boolean` | `false` | 否 | 是否展示菜单项（受控模式） | `inherited:Datepicker` | `<Datepicker :show="visible" />` |
+| position | `Position | "left" | "bottom" | "right" | "top"` | `{my: 'left top+8', at: 'left bottom'}` | 否 | 菜单弹出的位置 | `inherited:Datepicker` | `<Datepicker position="top" />` |
+| nowrap | `boolean` | `false` | 否 | 选中值区域是否不换行展示，适合单行紧凑布局 | `inherited:Datepicker` | `<Datepicker nowrap />` |
+| draggable | `boolean` | `false` | 否 | 多选值是否支持拖动排序 | `inherited:Datepicker` | `<Datepicker multiple draggable />` |
+| virtual | `boolean` | `false` | 否 | 是否开启虚拟列表，用于大数据量场景 | `inherited:Datepicker` | `<Datepicker virtual />` |
+| modelValue | `[number, number] | [string, string]` | `undefined` | 否 | 当前选中的时间范围 | - | - |
+| startTime | `string | number` | `undefined` | 否 | 当前时间范围的开始时间 | - | - |
+| endTime | `string | number` | `undefined` | 否 | 当前时间范围的结束时间 | - | - |
+| label | `string` | `""` | 否 | 组件标题文案 | - | - |
+| times | `(Time | number | 'today' | 'yesterday')[]` | `undefined` | 否 | 快捷时间范围配置，支持分钟数或 today / yesterday 等枚举 | - | - |
+| defaultValue | `number | 'today' | 'yesterday'` | `undefined` | 否 | 首次渲染时使用的默认快捷值 | - | - |
+| timestamp | `boolean` | `false` | 否 | 是否以时间戳格式返回值 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| update:modelValue | `@update:modelValue` | 整个时间范围值变化时触发，适合直接驱动查询参数。 | `value?: TimeModelType` | - |
+| update:startTime | `@update:startTime` | 开始时间变化时触发，可用于单独记录查询区间起点。 | `value?: string | number` | - |
+| update:endTime | `@update:endTime` | 结束时间变化时触发，可用于单独记录查询区间终点。 | `value?: string | number` | - |
+
+### 事件参数说明
+**update:modelValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `TimeModelType` | 否 | - | 当前完整时间范围，可能是时间戳元组或格式化后的字符串元组。 |
+
+**update:startTime**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string | number` | 否 | - | 当前开始时间值；`timestamp=true` 时通常是时间戳，否则为格式化字符串。 |
+
+**update:endTime**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `string | number` | 否 | - | 当前结束时间值；`timestamp=true` 时通常是时间戳，否则为格式化字符串。 |
+
+## 方法 (Methods)
+| 方法名 | 说明 | 参数 | 返回值 |
+| --- | --- | --- | --- |
+| setTimeValue | 按快捷值主动切换时间范围 | `value: number | 'today' | 'yesterday'` | `void` |
+| refetch | 刷新当前时间范围到最新时间 | `value?: number | 'today' | 'yesterday'` | `void` |
+
+### 方法参数说明
+**setTimeValue**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `number | 'today' | 'yesterday'` | 是 | - | 目标快捷值，可传分钟数或 `today`、`yesterday` 这类内置快捷标识。 |
+
+**refetch**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| value | `number | 'today' | 'yesterday'` | 否 | - | 可选的快捷值；传入后会先切换到该快捷区间，再把结束时间刷新到当前最新时刻。 |
+
+## 使用示例
+### 监控页时间筛选
+**场景**: 在监控和报表页面中切换查询时间范围。
+
+提供最近 1 小时、最近 24 小时等快捷时间范围。
+
+**使用的 API**: 属性: modelValue, label, times, timestamp | 事件: update:modelValue, update:startTime, update:endTime
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { TimeRange } from '@ksyun-internal/versatile';
+
+const timeRange = ref<[number, number] | undefined>();
+</script>
+
+<template>
+  <TimeRange
+    v-model="timeRange"
+    label="统计周期"
+    :times="[60, 360, 'today']"
+    :timestamp="true"
+  />
+</template>
+```
+
+### 刷新到最新时间窗口
+**场景**: 在日志和监控页面中一键把查询区间重置到最新时间窗口。
+
+通过组件方法把当前时间范围刷新到最新时刻，适合日志和监控实时查看场景。
+
+**使用的 API**: 属性: modelValue, times, defaultValue, timestamp | 事件: update:modelValue | 方法: refetch
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { TimeRange } from '@ksyun-internal/versatile';
+
+const rangeRef = ref<InstanceType<typeof TimeRange>>();
+const timeRange = ref<[number, number] | undefined>();
+const refreshLatest = () => {
+  rangeRef.value?.refetch(60);
+};
+</script>
+
+<template>
+  <button @click="refreshLatest">刷新最近 1 小时</button>
+  <TimeRange
+    ref="rangeRef"
+    v-model="timeRange"
+    :times="[60, 360, 1440]"
+    :default-value="60"
+    :timestamp="true"
+  />
+</template>
+```
+
+## 相关组件
+Datepicker, Duration
+

package/docs_for_llm/tip.doc.md

@@ -12,23 +12,29 @@ import { Tip } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| type | `"default" | "primary" | "success" | "warning" | "danger"` | `"default"` | 否 | 提示类型 | `<Tip type="warning">警告内容</Tip>` |
-| closable | `boolean` | `false` | 否 | 是否可关闭 | `<Tip closable>可关闭的提示</Tip>` |
-| closed | `boolean` | `false` | 否 | 是否已关闭，可用 v-model:closed 双向绑定 | `<Tip :closed="isClosed">提示</Tip>` |
-| showIcon | `boolean` | `false` | 否 | 是否展示图标 | `<Tip type="success" showIcon>成功</Tip>` |
-| disabled | `boolean` | `false` | 否 | 是否展示禁用状态 | `<Tip disabled>禁用状态</Tip>` |
-| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 组件尺寸 | `<Tip size="small">小尺寸提示</Tip>` |
-| border | `"solid" | "dashed" | "none"` | `"solid"` | 否 | 边框样式 | `<Tip border="dashed">虚线边框</Tip>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| type | `"default" | "primary" | "success" | "warning" | "danger"` | `"default"` | 否 | 提示类型 | - | `<Tip type="warning">警告内容</Tip>` |
+| closable | `boolean` | `false` | 否 | 是否可关闭 | - | `<Tip closable>可关闭的提示</Tip>` |
+| closed | `boolean` | `false` | 否 | 是否已关闭，可用 v-model:closed 双向绑定 | - | `<Tip :closed="isClosed">提示</Tip>` |
+| showIcon | `boolean` | `false` | 否 | 是否展示图标 | - | `<Tip type="success" showIcon>成功</Tip>` |
+| disabled | `boolean` | `false` | 否 | 是否展示禁用状态 | - | `<Tip disabled>禁用状态</Tip>` |
+| size | `"large" | "default" | "small" | "mini"` | `"default"` | 否 | 组件尺寸 | - | `<Tip size="small">小尺寸提示</Tip>` |
+| border | `"solid" | "dashed" | "none"` | `"solid"` | 否 | 边框样式 | - | `<Tip border="dashed">虚线边框</Tip>` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
 | --- | --- | --- | --- | --- |
 | close | `@close` | 关闭时触发 | `e: MouseEvent` | `<Tip closable @close="handleClose"></Tip>` |
 
-### 事件处理函数示例
-**close**:
+### 事件参数说明
+**close**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| e | `MouseEvent` | 是 | - | 原生鼠标事件 |
+
+事件处理示例:
 ```typescript
 const handleClose = (e: MouseEvent) => {
   console.log('提示已关闭');
@@ -36,14 +42,17 @@ const handleClose = (e: MouseEvent) => {
 ```
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### 使用 closable 但未处理关闭逻辑
 > **错误用法**: `<Tip closable>提示</Tip> <!-- 点击关闭按钮不会隐藏 -->`
 > **正确写法**: `<Tip closable :closed="closed" @close="handleClose">提示</Tip>`
 > **说明**: closable 只显示关闭按钮，需要监听 close 事件并设置 closed 来隐藏
 
+### type 值拼写错误
 > **错误用法**: `<Tip type="error">错误</Tip>`
 > **正确写法**: `<Tip type="danger">错误</Tip>`
 > **说明**: 错误类型应使用 danger 而非 error
 
+### showIcon 大小写错误
 > **错误用法**: `<Tip showicon>提示</Tip>`
 > **正确写法**: `<Tip showIcon>提示</Tip>`
 > **说明**: 属性名是 showIcon（驼峰命名）

package/docs_for_llm/tooltip.doc.md

@@ -12,58 +12,84 @@ import { Tooltip } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| content | `string | VNode` | `undefined` | 否 | 提示的内容 | `<Tooltip content="提示内容"></Tooltip>` |
-| trigger | `"hover" | "click" | "focus"` | `"hover"` | 否 | 触发方式 | `<Tooltip trigger="click"></Tooltip>` |
-| value | `boolean` | `false` | 否 | 是否展示弹层，可用 v-model 双向绑定 | `<Tooltip v-model="visible"></Tooltip>` |
-| disabled | `boolean` | `false` | 否 | 是否禁用提示 | `<Tooltip disabled></Tooltip>` |
-| position | `Position | "left" | "bottom" | "right" | "top"` | `{my: 'center bottom-10', at: 'center top', collision: 'flipfit'}` | 否 | 弹层弹出的位置，默认在触发器正上方 | `<Tooltip position="bottom"></Tooltip>` |
-| theme | `"dark" | "light"` | `"dark"` | 否 | 主题 | `<Tooltip theme="light"></Tooltip>` |
-| showArrow | `boolean` | `true` | 否 | 弹层是否展示箭头 | `<Tooltip :showArrow="false"></Tooltip>` |
-| hoverable | `boolean` | `false` | 否 | 对于悬浮触发方式，提示弹层是否在鼠标悬浮时仍然展示 | `<Tooltip hoverable></Tooltip>` |
-| always | `boolean` | `false` | 否 | 是否一直保持当前展示/隐藏状态 | `<Tooltip always></Tooltip>` |
-| size | `"default" | "small"` | `"default"` | 否 | 弹层尺寸 | `<Tooltip size="small"></Tooltip>` |
-| of | `"self" | "parent" | Event` | `"self"` | 否 | 弹出菜单的位置是相对当前触发元素还是父元素 | `<Tooltip of="parent"></Tooltip>` |
-| container | `string | ((parentDom: Element, anchor: Node | null) => Element)` | `undefined` | 否 | 指定弹出菜单追加的位置 | `<Tooltip :container="() => document.body"></Tooltip>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| content | `string | VNode` | `undefined` | 否 | 提示的内容 | - | `<Tooltip content="提示内容">` |
+| trigger | `"hover" | "click" | "focus"` | `"hover"` | 否 | 触发方式 | - | `<Tooltip trigger="click">` |
+| value | `boolean` | `false` | 否 | 是否展示弹层，可用 v-model 双向绑定 | - | `<Tooltip v-model="visible">` |
+| disabled | `boolean` | `false` | 否 | 是否禁用提示 | - | `<Tooltip disabled>` |
+| position | `Position | "left" | "bottom" | "right" | "top"` | `{my: 'center bottom-10', at: 'center top', collision: 'flipfit'}` | 否 | 弹层弹出的位置，默认在触发器正上方 | - | `<Tooltip position="bottom">` |
+| collison | `Collision | [Collision, Collision]` | `undefined` | 否 | 碰撞检测策略，控制弹层超出边界时的处理方式。注意源码字段名拼写为 collison。 | - | `<Tooltip :collison="'flipfit'">` |
+| theme | `"dark" | "light"` | `"dark"` | 否 | 主题 | - | `<Tooltip theme="light">` |
+| showArrow | `boolean` | `true` | 否 | 弹层是否展示箭头 | - | `<Tooltip :showArrow="false">` |
+| hoverable | `boolean` | `false` | 否 | 对于悬浮触发方式，提示弹层是否在鼠标悬浮时仍然展示 | - | `<Tooltip hoverable>` |
+| always | `boolean` | `false` | 否 | 是否一直保持当前展示/隐藏状态 | - | `<Tooltip always>` |
+| size | `"default" | "small"` | `"default"` | 否 | 弹层尺寸 | - | `<Tooltip size="small">` |
+| of | `"self" | "parent" | Event` | `"self"` | 否 | 弹出菜单的位置是相对当前触发元素还是父元素 | - | `<Tooltip of="parent">` |
+| container | `string | ((parentDom: Element, anchor: Node | null) => Element)` | `undefined` | 否 | 指定弹出菜单追加的位置 | - | `<Tooltip :container="() => document.body">` |
+| alwaysShowOnClick | `boolean` | `false` | 否 | 不管什么触发方式，重复点击触发器都不隐藏弹层 | - | `<Tooltip alwaysShowOnClick>` |
 
 ## 事件 (Events)
 | 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
 | --- | --- | --- | --- | --- |
-| show | `@show` | 弹层展示时触发 | `-` | `<Tooltip @show="handleShow"></Tooltip>` |
-| hide | `@hide` | 弹层隐藏时触发 | `-` | `<Tooltip @hide="handleHide"></Tooltip>` |
+| show | `@show` | 弹层展示时触发 | `-` | `<Tooltip @show="handleShow">` |
+| hide | `@hide` | 弹层隐藏时触发 | `-` | `<Tooltip @hide="handleHide">` |
+| positioned | `@positioned` | 提示弹层完成定位计算后触发，可用于读取最终落位结果。 | `feedback: Feedback` | `<Tooltip @positioned="handlePositioned">` |
 
-### 事件处理函数示例
-**show**:
-```typescript
-const handleShow = () => {
-  console.log('Tooltip 已展示');
-};
-```
+### 事件参数说明
+**positioned**
 
-**hide**:
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| feedback | `Feedback` | 是 | - | 定位反馈对象，描述当前 Tooltip 的最终 placement 和坐标信息。 |
+
+事件处理示例:
 ```typescript
-const handleHide = () => {
-  console.log('Tooltip 已隐藏');
+const handlePositioned = (feedback: Feedback) => {
+  console.log('Tooltip 最终位置', feedback.placement);
 };
 ```
 
-## 插槽 (Slots)
-| 插槽名 | 说明 | 模板写法 | 示例 |
+## 方法 (Methods)
+| 方法名 | 说明 | 参数 | 返回值 |
 | --- | --- | --- | --- |
-| content | 自定义提示内容 | `undefined` | - |
+| show | 主动显示提示弹层。 | `shouldFocus?: boolean` | `void` |
+| hide | 主动隐藏提示弹层。 | `immediately: boolean` | `void` |
+| position | 重新计算提示弹层的位置。 | `callback?: (feedback: Feedback) => void` | `void` |
+
+### 方法参数说明
+**show**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| shouldFocus | `boolean` | 否 | - | 显示后是否尝试把焦点移动到弹层内容。 |
+
+**hide**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| immediately | `boolean` | 是 | - | 是否立即隐藏，用于手动控制点击确认型 Tooltip 的关闭时机。 |
+
+**position**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| callback | `(feedback: Feedback) => void` | 否 | - | 定位完成后的回调，可读取最终 placement 和坐标。 |
 
 ## 常见错误与正确用法 (Anti-Hallucination)
+### 未提供触发元素
 > **错误用法**: `<Tooltip content="提示" />`
 > **正确写法**: `<Tooltip content="提示">
   <Button>触发器</Button>
 </Tooltip>`
 > **说明**: Tooltip 需要包裹一个子元素作为触发器
 
+### position 值拼写错误
 > **错误用法**: `<Tooltip position="buttom">`
 > **正确写法**: `<Tooltip position="bottom">`
 > **说明**: position 只支持 top, bottom, left, right，注意拼写
 
+### 使用 hoverable 但 content 不可交互
 > **错误用法**: `<Tooltip hoverable content="纯文本" /> <!-- hoverable 无意义 -->`
 > **正确写法**: `<Tooltip hoverable>
   <Button>触发</Button>