king-design-analyzer 2.1.9 → 2.2.0

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>
+```
+

package/docs_for_llm/useGetCopyAuthText.doc.md

@@ -0,0 +1,35 @@
+# 复制授权文案 (useGetCopyAuthText)
+
+根据服务名和策略名生成复制授权相关文案，适合复制账号权限说明或 AK/SK 授权提示。
+
+**关键词**: useGetCopyAuthText, 复制授权文案, policyName, AKSK, 权限说明, 授权提示
+
+## 导入语句
+```typescript
+import { useGetCopyAuthText } from '@ksyun-internal/versatile';
+```
+
+## 返回值
+```typescript
+(serviceNames: string | Record<string, string[]>, policyName: string) => string | undefined
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 策略名传入页面展示文案而不是实际 policyName
+> **错误用法**: `getCopyAuthText('KEC', '云服务器只读');`
+> **正确写法**: `getCopyAuthText('KEC', 'KecReadOnlyAccess');`
+> **说明**: 第二个参数应使用真实策略标识，而不是中文标题。
+
+## 使用示例
+### 生成复制授权提示
+根据服务和策略名输出授权说明文案
+
+```vue
+<script setup lang="ts">
+import { useGetCopyAuthText } from '@ksyun-internal/versatile';
+
+const getCopyAuthText = useGetCopyAuthText();
+const text = getCopyAuthText('KEC', 'KecReadOnlyAccess');
+</script>
+```
+

package/docs_for_llm/useGetUserPermission.doc.md

@@ -0,0 +1,43 @@
+# 用户权限判断 (useGetUserPermission)
+
+根据用户列表和目标权限集合计算当前数据是否具备权限，适合列表操作按钮、批量操作和详情页权限门禁判断。
+
+**关键词**: useGetUserPermission, 权限判断, 操作权限, 按钮禁用, auth, permission
+
+## 导入语句
+```typescript
+import { useGetUserPermission } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| users | `Ref<User[] | null | undefined>` | 是 | 用户或授权主体列表 |
+| permissions | `string[]` | 是 | 目标权限编码列表 |
+| key | `keyof User` | 否 | 权限字段所在的属性名，不传时使用默认字段 |
+
+## 返回值
+```typescript
+ComputedRef<boolean>
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 传入的 key 不是权限字段，导致结果始终错误
+> **错误用法**: `useGetUserPermission(users, ['instance:delete'], 'name');`
+> **正确写法**: `useGetUserPermission(users, ['instance:delete'], 'actions');`
+> **说明**: key 应指向用户对象中真正存放权限列表的字段。
+
+## 使用示例
+### 控制按钮是否可操作
+根据用户权限列表生成可直接用于模板的布尔值
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useGetUserPermission } from '@ksyun-internal/versatile';
+
+const users = ref([{ actions: ['instance:view', 'instance:delete'] }]);
+const canDelete = useGetUserPermission(users, ['instance:delete'], 'actions');
+</script>
+```
+

package/docs_for_llm/useGroup.doc.md

@@ -0,0 +1,48 @@
+# 数据分组映射 (useGroup)
+
+根据输入数据源和分组函数生成实体列表与分组结果，适合把接口返回的数据整理成按键聚合的展示结构。
+
+**关键词**: useGroup, 分组, grouped, entities, 数据整理, 聚合展示
+
+## 导入语句
+```typescript
+import { useGroup } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| packages | `(() => P[] | undefined) | Ref<P[] | undefined>` | 是 | 原始数据源，可传 getter 或 Ref |
+| forEach | `(pkg: P, fn: (key: K, data: T) => void) => void` | 是 | 遍历函数，用于从每个数据项中提取分组 key 和实体数据 |
+
+## 返回值
+```typescript
+{ entities: Ref<T[] | undefined>; grouped: Ref<Record<K, P[]> | undefined>; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### forEach 中没有调用回调函数，导致 grouped 为空
+> **错误用法**: `useGroup(packages, (pkg) => { console.log(pkg); });`
+> **正确写法**: `useGroup(packages, (pkg, push) => { push(pkg.status, pkg); });`
+> **说明**: hook 依赖回调函数收集 key 和 data，没有 push 就不会产生分组结果。
+
+## 使用示例
+### 按状态分组实例列表
+把列表数据转换成状态分组结构，便于生成统计和分段展示
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useGroup } from '@ksyun-internal/versatile';
+
+const packages = ref([
+  { id: '1', status: 'running', name: '实例1' },
+  { id: '2', status: 'stopped', name: '实例2' },
+]);
+
+const { entities, grouped } = useGroup(packages, (pkg, push) => {
+  push(pkg.status, pkg);
+});
+</script>
+```
+

package/docs_for_llm/useIdEntities.doc.md

@@ -0,0 +1,48 @@
+# ID 列表映射实体列表 (useIdEntities)
+
+根据多个 ID 从实体列表中映射出对应的实体数组，适合多选组件、批量操作和多实体回显场景。
+
+**关键词**: useIdEntities, 多选实体映射, ids, entity list, 批量回显, 多选
+
+## 导入语句
+```typescript
+import { useIdEntities } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| ids | `Ref<(string | number)[] | undefined | null>` | 是 | 选中的 ID 列表 |
+| list | `Ref<Entity[] | undefined | null>` | 是 | 实体源列表 |
+| key | `keyof Entity` | 是 | 用于匹配的实体主键字段 |
+| emit | `(entity: Entity[] | undefined) => void` | 否 | 实体数组变化时的回调 |
+
+## 返回值
+```typescript
+Ref<Entity[] | undefined>
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 把单个 ID 当作 ids 传入
+> **错误用法**: `useIdEntities(id, list, 'id');`
+> **正确写法**: `useIdEntities(ids, list, 'id');`
+> **说明**: 这个 hook 面向多值场景，首参应是 ID 数组 Ref。
+
+## 使用示例
+### 多选值回显实体数组
+根据选中的多个 ID 计算出完整对象列表
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useIdEntities } from '@ksyun-internal/versatile';
+
+const ids = ref(['ws-1', 'ws-2']);
+const list = ref([
+  { WorkspaceId: 'ws-1', WorkspaceName: '工作空间1' },
+  { WorkspaceId: 'ws-2', WorkspaceName: '工作空间2' },
+]);
+const entities = useIdEntities(ids, list, 'WorkspaceId');
+</script>
+```
+

package/docs_for_llm/useIdEntity.doc.md

@@ -0,0 +1,103 @@
+# ID 实体映射 (useIdEntity)
+
+根据 ID 从列表中查找对应的实体对象。当 ID 或列表变化时自动更新实体，并可选择性地触发回调。常用于 Select 等组件中需要根据选中 ID 获取完整对象信息的场景。
+
+**关键词**: useIdEntity, id, entity, 列表查找, 实体映射, select
+
+## 导入语句
+```typescript
+import { useIdEntity } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| id | `Ref<string | number | undefined | null>` | 是 | 要查找的实体 ID（响应式值） |
+| list | `Ref<Entity[] | undefined | null>` | 是 | 实体列表（响应式值） |
+| key | `keyof Entity` | 是 | 用于匹配的实体属性名（如 'id', 'WorkspaceId' 等） |
+| emit | `(entity: Entity | undefined) => void` | 否 | 实体变化时的回调函数 |
+| deps | `WatchSource[]` | 否 | 额外的依赖项，当这些依赖变化时也会触发重新查找 |
+| enable | `(item: Entity, index: number) => boolean` | 否 | 过滤函数，用于筛选可用的实体 |
+
+## 返回值
+```typescript
+Ref<Entity | undefined>
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### id 参数传入非响应式值
+> **错误用法**: `const entity = useIdEntity('ws-001', workspaceList, 'WorkspaceId');`
+> **正确写法**: `const id = ref('ws-001');
+const entity = useIdEntity(id, workspaceList, 'WorkspaceId');`
+> **说明**: id 参数必须是 Ref 类型，否则无法监听变化
+
+### key 参数与实体属性名不匹配
+> **错误用法**: `useIdEntity(id, workspaceList, 'id');  // 实体中是 WorkspaceId`
+> **正确写法**: `useIdEntity(id, workspaceList, 'WorkspaceId');`
+> **说明**: key 必须与实体对象中用作唯一标识的属性名完全匹配
+
+## 使用示例
+### 基础用法
+根据选中的 ID 获取对应的工作空间对象
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useIdEntity } from '@ksyun-internal/versatile';
+
+const selectedId = ref('ws-001');
+const workspaceList = ref([
+  { WorkspaceId: 'ws-001', WorkspaceName: '工作空间1' },
+  { WorkspaceId: 'ws-002', WorkspaceName: '工作空间2' },
+]);
+
+const selectedWorkspace = useIdEntity(selectedId, workspaceList, 'WorkspaceId');
+// selectedWorkspace.value = { WorkspaceId: 'ws-001', WorkspaceName: '工作空间1' }
+</script>
+```
+
+### 带回调函数
+当实体变化时触发回调
+
+```vue
+<script setup lang="ts">
+import { useToState, useIdEntity } from '@ksyun-internal/versatile';
+
+const props = defineProps<{ modelValue?: string }>();
+const emit = defineEmits<{ (e: 'update:modelValue', v?: string): void }>();
+
+const modelValue = useToState(props, 'modelValue', emit, '');
+const { workspaceList } = useWorkspaces();
+
+useIdEntity(modelValue, workspaceList, 'WorkspaceId', (entity) => {
+  emit('update:modelValue', entity?.WorkspaceId);
+});
+</script>
+```
+
+### 带过滤函数
+只在启用状态的实体中查找
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useIdEntity } from '@ksyun-internal/versatile';
+
+const selectedId = ref('item-1');
+const itemList = ref([
+  { id: 'item-1', name: '项目1', enabled: true },
+  { id: 'item-2', name: '项目2', enabled: false },
+]);
+
+// 只在 enabled: true 的项目中查找
+const entity = useIdEntity(
+  selectedId,
+  itemList,
+  'id',
+  undefined,
+  undefined,
+  (item) => item.enabled
+);
+</script>
+```
+

package/docs_for_llm/useInterval.doc.md

@@ -0,0 +1,43 @@
+# 可暂停定时器 (useInterval)
+
+对 setInterval 做响应式封装，提供 pause、resume 和 isActive，适合轮询、时钟和自动刷新场景。
+
+**关键词**: useInterval, 定时器, pause, resume, 自动刷新, 轮询
+
+## 导入语句
+```typescript
+import { useInterval } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| cb | `() => void` | 是 | 定时执行的回调 |
+| interval | `MaybeRefOrGetter<number>` | 否 | 时间间隔，默认值由上游实现决定 |
+| options | `UseIntervalOptions` | 否 | 定时器配置，可设置 immediate 和 immediateCallback |
+
+## 返回值
+```typescript
+{ isActive: Readonly<ShallowRef<boolean>>; pause: () => void; resume: () => void; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 暂停后修改了 interval，却以为 resume 会自动重建旧定时器逻辑
+> **错误用法**: `pause(); interval.value = 1000; resume();`
+> **正确写法**: `确认 interval 是响应式输入，或重新创建 useInterval。`
+> **说明**: 建议明确 interval 的响应式来源，避免把它当成一次性静态参数。
+
+## 使用示例
+### 自动刷新列表
+以固定间隔刷新列表数据，并可手动暂停
+
+```vue
+<script setup lang="ts">
+import { useInterval } from '@ksyun-internal/versatile';
+
+const { pause, resume, isActive } = useInterval(() => {
+  console.log('refresh');
+}, 5000, { immediate: true });
+</script>
+```
+