king-design-analyzer 2.1.9 → 2.2.0

package/hooks/useCRUD.json

@@ -0,0 +1,61 @@
+{
+  "id": "useCRUD",
+  "name": "useCRUD",
+  "displayName": "增删行状态管理",
+  "category": "form",
+  "description": "管理数组型表单项的新增与删除能力，并根据最大最小数量约束生成可直接用于按钮禁用态的结果。",
+  "importStatement": "import { useCRUD } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "models",
+      "type": "Ref<T[]>",
+      "required": true,
+      "description": "当前表单项数组"
+    },
+    {
+      "name": "initItem",
+      "type": "() => T",
+      "required": true,
+      "description": "新增项的初始化工厂函数"
+    },
+    {
+      "name": "maxInstanceNum",
+      "type": "number",
+      "required": false,
+      "description": "最大可新增数量"
+    },
+    {
+      "name": "minInstanceNum",
+      "type": "number",
+      "required": false,
+      "description": "最小保留数量"
+    }
+  ],
+  "returnType": "{ canAdd: ComputedRef<{ disabled: boolean; msg: string }>; canDelete: ComputedRef<{ disabled: boolean; msg: string }>; addItem: () => void; deleteItem: (index: number) => void; }",
+  "examples": [
+    {
+      "id": "dynamic_form_rows",
+      "title": "动态表单行增删",
+      "description": "控制实例配置行的新增与删除",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useCRUD } from '@ksyun-internal/versatile';\n\nconst models = ref([{ name: '', value: '' }]);\nconst { canAdd, canDelete, addItem, deleteItem } = useCRUD(\n  models,\n  () => ({ name: '', value: '' }),\n  5,\n  1\n);\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "shared_default_object",
+      "description": "直接复用同一个默认对象，导致新增项互相串值",
+      "wrongCode": "const defaultItem = { name: '', value: '' }; useCRUD(models, () => defaultItem);",
+      "correctCode": "useCRUD(models, () => ({ name: '', value: '' }));",
+      "explanation": "initItem 应返回新的对象实例，避免多个表单项共享引用。"
+    }
+  ],
+  "searchKeywords": [
+    "useCRUD",
+    "动态表单",
+    "新增 删除",
+    "数组项",
+    "canAdd",
+    "canDelete"
+  ]
+}

package/hooks/useCountdown.json

@@ -0,0 +1,49 @@
+{
+  "id": "useCountdown",
+  "name": "useCountdown",
+  "displayName": "倒计时",
+  "category": "timer",
+  "description": "管理秒级或自定义间隔的倒计时流程，提供 start、reset、stop 和 pause/resume 等控制能力。",
+  "importStatement": "import { useCountdown } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "initialCountdown",
+      "type": "MaybeRefOrGetter<number>",
+      "required": true,
+      "description": "初始倒计时值"
+    },
+    {
+      "name": "options",
+      "type": "UseCountdownOptions",
+      "required": false,
+      "description": "倒计时配置，可设置 interval、immediate、onTick 和 onComplete"
+    }
+  ],
+  "returnType": "{ remaining: ShallowRef<number>; isActive: Readonly<ShallowRef<boolean>>; pause: () => void; resume: () => void; reset: (countdown?: MaybeRefOrGetter<number>) => void; stop: () => void; start: (countdown?: MaybeRefOrGetter<number>) => void; }",
+  "examples": [
+    {
+      "id": "sms_countdown",
+      "title": "短信验证码倒计时",
+      "description": "点击发送验证码后开始倒计时",
+      "code": "<script setup lang=\"ts\">\nimport { useCountdown } from '@ksyun-internal/versatile';\n\nconst { remaining, start, stop } = useCountdown(60, {\n  immediate: false,\n  onComplete: () => console.log('倒计时结束'),\n});\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "expect_resume_reset",
+      "description": "把 resume 当作重新开始倒计时使用",
+      "wrongCode": "resume();",
+      "correctCode": "start(); // 或 reset(60) 后再 start()",
+      "explanation": "resume 只用于恢复暂停中的倒计时，不会重置剩余时间。"
+    }
+  ],
+  "searchKeywords": [
+    "useCountdown",
+    "倒计时",
+    "remaining",
+    "短信验证码",
+    "start stop",
+    "pause resume"
+  ]
+}

package/hooks/useDetail.json

@@ -0,0 +1,67 @@
+{
+  "id": "useDetail",
+  "name": "useDetail",
+  "displayName": "详情页状态守卫",
+  "category": "page",
+  "description": "围绕详情页数据、网络状态和路由跳转封装守卫逻辑，适合详情页数据为空、请求异常或需要回退列表页的场景。",
+  "importStatement": "import { useDetail } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "detailData",
+      "type": "Ref<T | null | undefined>",
+      "required": true,
+      "description": "详情数据响应式对象"
+    },
+    {
+      "name": "networkStatus",
+      "type": "Ref<number | undefined>",
+      "required": true,
+      "description": "网络状态响应式值"
+    },
+    {
+      "name": "routerName",
+      "type": "string | RouteLocationAsRelativeGeneric | RouteLocationAsPathGeneric",
+      "required": false,
+      "description": "异常时回退的路由信息"
+    },
+    {
+      "name": "refetch",
+      "type": "() => void",
+      "required": false,
+      "description": "重新拉取详情数据的方法"
+    },
+    {
+      "name": "tip",
+      "type": "string",
+      "required": false,
+      "description": "详情不存在或异常时展示的提示文案"
+    }
+  ],
+  "returnType": "void",
+  "examples": [
+    {
+      "id": "detail_guard",
+      "title": "详情页请求守卫",
+      "description": "在详情页请求为空或异常时统一处理跳转和重试",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useDetail } from '@ksyun-internal/versatile';\n\nconst detailData = ref();\nconst networkStatus = ref(7);\nconst refetch = () => console.log('retry');\n\nuseDetail(detailData, networkStatus, { name: 'instance-list' }, refetch, '实例不存在');\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "missing_network_status",
+      "description": "只传详情数据，没有把网络状态传给 hook，导致无法区分加载中和异常态",
+      "wrongCode": "useDetail(detailData);",
+      "correctCode": "useDetail(detailData, networkStatus, 'instance-list');",
+      "explanation": "networkStatus 是 hook 判断详情状态的重要输入。"
+    }
+  ],
+  "searchKeywords": [
+    "useDetail",
+    "详情页",
+    "networkStatus",
+    "详情守卫",
+    "异常跳转",
+    "refetch"
+  ]
+}

package/hooks/useDialog.json

@@ -0,0 +1,49 @@
+{
+  "id": "useDialog",
+  "name": "useDialog",
+  "displayName": "弹窗状态管理",
+  "category": "dialog",
+  "description": "为 VDialog 或 Dialog 表单场景封装显隐、校验、重置和确认按钮行为，减少弹窗表单模板中的重复状态代码。",
+  "importStatement": "import { useDialog } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "emit",
+      "type": "() => any",
+      "required": false,
+      "description": "父组件传入的 emit，用于联动弹窗显隐或外部事件"
+    },
+    {
+      "name": "isShowParentDialog",
+      "type": "Ref<boolean | undefined>",
+      "required": false,
+      "description": "父级弹窗显隐状态，适合嵌套弹窗场景"
+    }
+  ],
+  "returnType": "{ 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; }",
+  "examples": [
+    {
+      "id": "dialog_form",
+      "title": "弹窗表单",
+      "description": "配合 VDialog 管理弹窗显隐和表单校验",
+      "code": "<script setup lang=\"ts\">\nimport { VDialog, useDialog } from '@ksyun-internal/versatile';\n\nconst { isShowDialog, formRef, show, hide, handleClickValidOkBtn } = useDialog();\n</script>\n\n<template>\n  <VDialog v-model=\"isShowDialog\" :ok=\"handleClickValidOkBtn\">\n    <Form ref=\"formRef\"></Form>\n  </VDialog>\n</template>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "missing_form_ref",
+      "description": "调用 validate 或 handleClickValidOkBtn，但没有把 formRef 绑定到表单",
+      "wrongCode": "<Form></Form>",
+      "correctCode": "<Form ref=\"formRef\"></Form>",
+      "explanation": "校验相关方法依赖 formRef 指向真实表单实例。"
+    }
+  ],
+  "searchKeywords": [
+    "useDialog",
+    "VDialog",
+    "弹窗表单",
+    "dialog",
+    "validate",
+    "show hide"
+  ]
+}

package/hooks/useEntity.json

@@ -0,0 +1,61 @@
+{
+  "id": "useEntity",
+  "name": "useEntity",
+  "displayName": "基础实体映射",
+  "category": "state",
+  "description": "根据单个 ID 和基础列表做实体同步回调，适合简单的字符串或数字值映射场景。",
+  "importStatement": "import { useEntity } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "id",
+      "type": "Ref<string | number | undefined | null>",
+      "required": true,
+      "description": "当前选中的 ID"
+    },
+    {
+      "name": "list",
+      "type": "Ref<string[] | number[] | undefined | null>",
+      "required": true,
+      "description": "基础值列表"
+    },
+    {
+      "name": "emit",
+      "type": "(entity: string | number | null | undefined) => void",
+      "required": false,
+      "description": "值变化时的回调"
+    },
+    {
+      "name": "isNeedDefaultValue",
+      "type": "boolean",
+      "required": false,
+      "description": "是否需要默认值处理"
+    }
+  ],
+  "returnType": "void",
+  "examples": [
+    {
+      "id": "simple_entity_mapping",
+      "title": "基础值映射",
+      "description": "根据当前值从列表里查找对应实体并回调给外层",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useEntity } from '@ksyun-internal/versatile';\n\nconst id = ref('cn-beijing-6a');\nconst list = ref(['cn-beijing-6a', 'cn-shanghai-2a']);\nuseEntity(id, list, (entity) => console.log(entity));\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "expect_return_value",
+      "description": "把 useEntity 当成返回实体 Ref 的 hook 使用",
+      "wrongCode": "const entity = useEntity(id, list);",
+      "correctCode": "useEntity(id, list, (entity) => { current.value = entity; });",
+      "explanation": "该 hook 主要通过副作用回调同步值，本身不返回实体 Ref。"
+    }
+  ],
+  "searchKeywords": [
+    "useEntity",
+    "简单实体映射",
+    "id value",
+    "回调同步",
+    "基础列表",
+    "单值"
+  ]
+}

package/hooks/useEventListener.json

@@ -0,0 +1,61 @@
+{
+  "id": "useEventListener",
+  "name": "useEventListener",
+  "displayName": "事件监听封装",
+  "category": "event",
+  "description": "为 HTMLElement、window、document 或 Ref 目标统一注册事件监听，并支持 throttle、debounce 与原生 addEventListener 配置。",
+  "importStatement": "import { useEventListener } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "target",
+      "type": "HTMLElement | Window | Document | Ref<HTMLElement | null> | (() => HTMLElement | null)",
+      "required": true,
+      "description": "监听目标"
+    },
+    {
+      "name": "event",
+      "type": "string",
+      "required": true,
+      "description": "事件名"
+    },
+    {
+      "name": "handler",
+      "type": "EventListenerOrEventListenerObject",
+      "required": true,
+      "description": "事件处理函数"
+    },
+    {
+      "name": "options",
+      "type": "{ throttle?: number; debounce?: number; nativeOptions?: boolean | AddEventListenerOptions }",
+      "required": false,
+      "description": "监听配置，支持节流、防抖和原生监听选项"
+    }
+  ],
+  "returnType": "void",
+  "examples": [
+    {
+      "id": "window_resize",
+      "title": "监听窗口尺寸变化",
+      "description": "在页面中节流监听 resize 事件",
+      "code": "<script setup lang=\"ts\">\nimport { useEventListener } from '@ksyun-internal/versatile';\n\nuseEventListener(window, 'resize', () => {\n  console.log('resize');\n}, { throttle: 200 });\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "throttle_and_debounce_conflict",
+      "description": "同时配置 throttle 和 debounce，但没有明确预期",
+      "wrongCode": "useEventListener(window, 'scroll', onScroll, { throttle: 100, debounce: 100 });",
+      "correctCode": "根据场景二选一：节流滚动用 throttle，输入联想用 debounce。",
+      "explanation": "两者语义不同，建议根据业务场景明确选一种。"
+    }
+  ],
+  "searchKeywords": [
+    "useEventListener",
+    "事件监听",
+    "window resize",
+    "debounce",
+    "throttle",
+    "addEventListener"
+  ]
+}

package/hooks/useFalseUntilTruthy.json

@@ -0,0 +1,43 @@
+{
+  "id": "useFalseUntilTruthy",
+  "name": "useFalseUntilTruthy",
+  "displayName": "延迟转真布尔态",
+  "category": "state",
+  "description": "将任意响应式值映射成布尔值，并在首次变为 truthy 前始终保持 false，适合权限、异步加载完成态和懒渲染控制。",
+  "importStatement": "import { useFalseUntilTruthy } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "value",
+      "type": "MaybeRefOrGetter<any>",
+      "required": true,
+      "description": "任意响应式值、getter 或普通值"
+    }
+  ],
+  "returnType": "Readonly<Ref<boolean>>",
+  "examples": [
+    {
+      "id": "guard_render",
+      "title": "控制懒渲染",
+      "description": "在异步数据真正可用前保持 false，避免中间闪烁",
+      "code": "<script setup lang=\"ts\">\nimport { computed } from 'vue';\nimport { useFalseUntilTruthy } from '@ksyun-internal/versatile';\n\nconst dataReady = computed(() => true);\nconst canRender = useFalseUntilTruthy(dataReady);\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "expect_reset_false",
+      "description": "期望值在 truthy 之后再次回到 false",
+      "wrongCode": "const visible = useFalseUntilTruthy(flag); // 认为 flag 再次 false 时 visible 也会 false",
+      "correctCode": "如需双向切换，请直接使用 computed(() => !!flag.value)",
+      "explanation": "这个 hook 的语义是“在首次变为 truthy 前保持 false”，不是通用的布尔映射。"
+    }
+  ],
+  "searchKeywords": [
+    "useFalseUntilTruthy",
+    "false until truthy",
+    "懒渲染",
+    "加载完成",
+    "布尔态",
+    "权限准备"
+  ]
+}

package/hooks/useGetCopyAuthText.json

@@ -0,0 +1,36 @@
+{
+  "id": "useGetCopyAuthText",
+  "name": "useGetCopyAuthText",
+  "displayName": "复制授权文案",
+  "category": "auth",
+  "description": "根据服务名和策略名生成复制授权相关文案，适合复制账号权限说明或 AK/SK 授权提示。",
+  "importStatement": "import { useGetCopyAuthText } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [],
+  "returnType": "(serviceNames: string | Record<string, string[]>, policyName: string) => string | undefined",
+  "examples": [
+    {
+      "id": "copy_auth_text",
+      "title": "生成复制授权提示",
+      "description": "根据服务和策略名输出授权说明文案",
+      "code": "<script setup lang=\"ts\">\nimport { useGetCopyAuthText } from '@ksyun-internal/versatile';\n\nconst getCopyAuthText = useGetCopyAuthText();\nconst text = getCopyAuthText('KEC', 'KecReadOnlyAccess');\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "invalid_policy_name",
+      "description": "策略名传入页面展示文案而不是实际 policyName",
+      "wrongCode": "getCopyAuthText('KEC', '云服务器只读');",
+      "correctCode": "getCopyAuthText('KEC', 'KecReadOnlyAccess');",
+      "explanation": "第二个参数应使用真实策略标识，而不是中文标题。"
+    }
+  ],
+  "searchKeywords": [
+    "useGetCopyAuthText",
+    "复制授权文案",
+    "policyName",
+    "AKSK",
+    "权限说明",
+    "授权提示"
+  ]
+}

package/hooks/useGetUserPermission.json

@@ -0,0 +1,55 @@
+{
+  "id": "useGetUserPermission",
+  "name": "useGetUserPermission",
+  "displayName": "用户权限判断",
+  "category": "auth",
+  "description": "根据用户列表和目标权限集合计算当前数据是否具备权限，适合列表操作按钮、批量操作和详情页权限门禁判断。",
+  "importStatement": "import { useGetUserPermission } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "users",
+      "type": "Ref<User[] | null | undefined>",
+      "required": true,
+      "description": "用户或授权主体列表"
+    },
+    {
+      "name": "permissions",
+      "type": "string[]",
+      "required": true,
+      "description": "目标权限编码列表"
+    },
+    {
+      "name": "key",
+      "type": "keyof User",
+      "required": false,
+      "description": "权限字段所在的属性名，不传时使用默认字段"
+    }
+  ],
+  "returnType": "ComputedRef<boolean>",
+  "examples": [
+    {
+      "id": "permission_guard",
+      "title": "控制按钮是否可操作",
+      "description": "根据用户权限列表生成可直接用于模板的布尔值",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useGetUserPermission } from '@ksyun-internal/versatile';\n\nconst users = ref([{ actions: ['instance:view', 'instance:delete'] }]);\nconst canDelete = useGetUserPermission(users, ['instance:delete'], 'actions');\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "wrong_key_field",
+      "description": "传入的 key 不是权限字段，导致结果始终错误",
+      "wrongCode": "useGetUserPermission(users, ['instance:delete'], 'name');",
+      "correctCode": "useGetUserPermission(users, ['instance:delete'], 'actions');",
+      "explanation": "key 应指向用户对象中真正存放权限列表的字段。"
+    }
+  ],
+  "searchKeywords": [
+    "useGetUserPermission",
+    "权限判断",
+    "操作权限",
+    "按钮禁用",
+    "auth",
+    "permission"
+  ]
+}

package/hooks/useGroup.json

@@ -0,0 +1,49 @@
+{
+  "id": "useGroup",
+  "name": "useGroup",
+  "displayName": "数据分组映射",
+  "category": "data",
+  "description": "根据输入数据源和分组函数生成实体列表与分组结果，适合把接口返回的数据整理成按键聚合的展示结构。",
+  "importStatement": "import { useGroup } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "packages",
+      "type": "(() => P[] | undefined) | Ref<P[] | undefined>",
+      "required": true,
+      "description": "原始数据源，可传 getter 或 Ref"
+    },
+    {
+      "name": "forEach",
+      "type": "(pkg: P, fn: (key: K, data: T) => void) => void",
+      "required": true,
+      "description": "遍历函数，用于从每个数据项中提取分组 key 和实体数据"
+    }
+  ],
+  "returnType": "{ entities: Ref<T[] | undefined>; grouped: Ref<Record<K, P[]> | undefined>; }",
+  "examples": [
+    {
+      "id": "group_instances",
+      "title": "按状态分组实例列表",
+      "description": "把列表数据转换成状态分组结构，便于生成统计和分段展示",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useGroup } from '@ksyun-internal/versatile';\n\nconst packages = ref([\n  { id: '1', status: 'running', name: '实例1' },\n  { id: '2', status: 'stopped', name: '实例2' },\n]);\n\nconst { entities, grouped } = useGroup(packages, (pkg, push) => {\n  push(pkg.status, pkg);\n});\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "forget_push",
+      "description": "forEach 中没有调用回调函数，导致 grouped 为空",
+      "wrongCode": "useGroup(packages, (pkg) => { console.log(pkg); });",
+      "correctCode": "useGroup(packages, (pkg, push) => { push(pkg.status, pkg); });",
+      "explanation": "hook 依赖回调函数收集 key 和 data，没有 push 就不会产生分组结果。"
+    }
+  ],
+  "searchKeywords": [
+    "useGroup",
+    "分组",
+    "grouped",
+    "entities",
+    "数据整理",
+    "聚合展示"
+  ]
+}

package/hooks/useIdEntities.json

@@ -0,0 +1,61 @@
+{
+  "id": "useIdEntities",
+  "name": "useIdEntities",
+  "displayName": "ID 列表映射实体列表",
+  "category": "state",
+  "description": "根据多个 ID 从实体列表中映射出对应的实体数组，适合多选组件、批量操作和多实体回显场景。",
+  "importStatement": "import { useIdEntities } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "ids",
+      "type": "Ref<(string | number)[] | undefined | null>",
+      "required": true,
+      "description": "选中的 ID 列表"
+    },
+    {
+      "name": "list",
+      "type": "Ref<Entity[] | undefined | null>",
+      "required": true,
+      "description": "实体源列表"
+    },
+    {
+      "name": "key",
+      "type": "keyof Entity",
+      "required": true,
+      "description": "用于匹配的实体主键字段"
+    },
+    {
+      "name": "emit",
+      "type": "(entity: Entity[] | undefined) => void",
+      "required": false,
+      "description": "实体数组变化时的回调"
+    }
+  ],
+  "returnType": "Ref<Entity[] | undefined>",
+  "examples": [
+    {
+      "id": "multi_select_entities",
+      "title": "多选值回显实体数组",
+      "description": "根据选中的多个 ID 计算出完整对象列表",
+      "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { useIdEntities } from '@ksyun-internal/versatile';\n\nconst ids = ref(['ws-1', 'ws-2']);\nconst list = ref([\n  { WorkspaceId: 'ws-1', WorkspaceName: '工作空间1' },\n  { WorkspaceId: 'ws-2', WorkspaceName: '工作空间2' },\n]);\nconst entities = useIdEntities(ids, list, 'WorkspaceId');\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "single_id_instead_of_array",
+      "description": "把单个 ID 当作 ids 传入",
+      "wrongCode": "useIdEntities(id, list, 'id');",
+      "correctCode": "useIdEntities(ids, list, 'id');",
+      "explanation": "这个 hook 面向多值场景，首参应是 ID 数组 Ref。"
+    }
+  ],
+  "searchKeywords": [
+    "useIdEntities",
+    "多选实体映射",
+    "ids",
+    "entity list",
+    "批量回显",
+    "多选"
+  ]
+}

package/hooks/useInterval.json

@@ -0,0 +1,55 @@
+{
+  "id": "useInterval",
+  "name": "useInterval",
+  "displayName": "可暂停定时器",
+  "category": "timer",
+  "description": "对 setInterval 做响应式封装，提供 pause、resume 和 isActive，适合轮询、时钟和自动刷新场景。",
+  "importStatement": "import { useInterval } from '@ksyun-internal/versatile';",
+  "source": "@ksyun-internal/versatile",
+  "params": [
+    {
+      "name": "cb",
+      "type": "() => void",
+      "required": true,
+      "description": "定时执行的回调"
+    },
+    {
+      "name": "interval",
+      "type": "MaybeRefOrGetter<number>",
+      "required": false,
+      "description": "时间间隔，默认值由上游实现决定"
+    },
+    {
+      "name": "options",
+      "type": "UseIntervalOptions",
+      "required": false,
+      "description": "定时器配置，可设置 immediate 和 immediateCallback"
+    }
+  ],
+  "returnType": "{ isActive: Readonly<ShallowRef<boolean>>; pause: () => void; resume: () => void; }",
+  "examples": [
+    {
+      "id": "auto_refresh",
+      "title": "自动刷新列表",
+      "description": "以固定间隔刷新列表数据，并可手动暂停",
+      "code": "<script setup lang=\"ts\">\nimport { useInterval } from '@ksyun-internal/versatile';\n\nconst { pause, resume, isActive } = useInterval(() => {\n  console.log('refresh');\n}, 5000, { immediate: true });\n</script>"
+    }
+  ],
+  "commonMistakes": [
+    {
+      "id": "expect_resume_recreate",
+      "description": "暂停后修改了 interval，却以为 resume 会自动重建旧定时器逻辑",
+      "wrongCode": "pause(); interval.value = 1000; resume();",
+      "correctCode": "确认 interval 是响应式输入，或重新创建 useInterval。",
+      "explanation": "建议明确 interval 的响应式来源，避免把它当成一次性静态参数。"
+    }
+  ],
+  "searchKeywords": [
+    "useInterval",
+    "定时器",
+    "pause",
+    "resume",
+    "自动刷新",
+    "轮询"
+  ]
+}