king-design-analyzer 2.1.9 → 2.2.1

package/docs_for_llm/vdialog.doc.md

@@ -0,0 +1,154 @@
+# 业务弹窗 (VDialog)
+
+在基础 Dialog 之上补充默认触发器、受控显隐和异步确认逻辑的业务弹窗组件，适合表单弹窗和危险操作确认。
+
+**关键词**: vdialog, dialog, 业务弹窗, 确认弹窗, 表单弹窗, trigger dialog
+
+**使用场景**: 表单弹窗、异步确认弹窗、通过按钮触发的操作弹窗
+
+## 导入语句
+```typescript
+import { VDialog } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| title | `string` | `""` | 否 | 弹窗标题 | - | - |
+| size | `string` | `undefined` | 否 | 弹窗尺寸 | - | - |
+| width | `string | number` | `undefined` | 否 | 弹窗宽度 | - | - |
+| loading | `boolean` | `false` | 否 | 确认按钮加载状态 | - | - |
+| disabledOk | `boolean` | `false` | 否 | 是否禁用确认按钮 | - | - |
+| okText | `string` | `"确定"` | 否 | 确认按钮文案 | - | - |
+| cancelText | `string` | `"取消"` | 否 | 取消按钮文案 | - | - |
+| ok | `() => Promise<boolean | void> | boolean | void` | `undefined` | 否 | 确认时的异步处理函数，可返回 false 阻止关闭 | - | - |
+| cancel | `() => void` | `undefined` | 否 | 取消时的回调逻辑 | - | - |
+| container | `string | Function` | `undefined` | 否 | 指定弹窗挂载容器 | - | - |
+| overlay | `boolean` | `true` | 否 | 是否显示遮罩层 | - | - |
+| closable | `boolean` | `true` | 否 | 点击遮罩层是否可关闭 | - | - |
+| terminate | `() => void` | `undefined` | 否 | 关闭动作统一回调 | - | - |
+| escClosable | `boolean` | `true` | 否 | 是否允许 ESC 关闭 | - | - |
+| hideClose | `boolean` | `false` | 否 | 是否隐藏右上角关闭按钮 | - | - |
+| draggable | `boolean` | `false` | 否 | 是否允许拖拽弹窗 | - | - |
+| mode | `string` | `undefined` | 否 | 弹窗展示模式 | - | - |
+| hideTrigger | `boolean` | `false` | 否 | 隐藏默认 trigger，作为受控弹窗使用 | - | - |
+| modelValue | `boolean | undefined` | `undefined` | 否 | 弹窗显示状态 | - | - |
+| btnProps | `ButtonProps` | `undefined` | 否 | 默认 trigger 按钮属性 | - | - |
+| btnText | `string` | `"打开对话框"` | 否 | 默认 trigger 按钮文案 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| open | `@open` | 弹窗打开后触发 | `-` | `<Dialog v-model="visible" @open="handleOpen">` |
+| close | `@close` | 弹窗关闭后触发，不管是什么原因导致的关闭 | `-` | `<Dialog v-model="visible" @close="handleClose">` |
+| ok | `@ok` | 点击确定按钮时触发 | `-` | `<Dialog v-model="visible" @ok="handleOk">` |
+| cancel | `@cancel` | 点击取消按钮时触发 | `-` | `<Dialog v-model="visible" @cancel="handleCancel">` |
+| terminate | `@terminate` | 用户强行关闭弹窗时触发：点击关闭按钮、点击遮罩层、按ESC键 | `-` | `<Dialog v-model="visible" @terminate="handleTerminate">` |
+| afterClose | `@after-close` | 弹窗退出动画执行完成后触发 | `-` | `<Dialog v-model="visible" @after-close="handleAfterClose">` |
+
+## 插槽 (Slots)
+| 插槽名 | 说明 | 模板写法 | 示例 |
+| --- | --- | --- | --- |
+| default | 弹窗主体内容（body区域） | `默认插槽` | `<Dialog v-model="visible">
+  <p>弹窗内容</p>
+</Dialog>` |
+| header | 扩展弹窗头部 | `#header` | `<Dialog v-model="visible">
+  <template #header>
+    <h2>自定义头部</h2>
+  </template>
+</Dialog>` |
+| footer | 扩展弹窗底部按钮区域 | `#footer` | `<Dialog v-model="visible">
+  <template #footer>
+    <Button @click="visible = false">关闭</Button>
+    <Button type="primary" @click="handleSubmit">提交</Button>
+  </template>
+</Dialog>` |
+| content | 定义整个弹窗体，包括header、body、footer | `#content` | `<Dialog v-model="visible">
+  <template #content>
+    <!-- 完全自定义弹窗结构 -->
+  </template>
+</Dialog>` |
+| trigger | 自定义触发按钮或触发区域 | `<template #trigger>...</template>` | `<VDialog>
+  <template <template #trigger>...</template>>
+    自定义trigger内容
+  </template>
+</VDialog>` |
+
+### 插槽参数说明
+**default**
+
+- 参数结构: 无参数
+
+**header**
+
+- 参数结构: 无参数
+
+**footer**
+
+- 参数结构: 无参数
+
+**content**
+
+- 参数结构: 无参数
+
+**trigger**
+
+- 参数结构: 无参数
+
+## 使用示例
+### 受控表单弹窗
+**场景**: 在页面中以受控方式打开一个承载业务表单的弹窗。
+
+通过 v-model 控制弹窗显隐，并在确认时执行异步逻辑。
+
+**使用的 API**: 属性: modelValue, title, ok, hideTrigger
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { VDialog, FormItemInput } from '@ksyun-internal/versatile';
+
+const visible = ref(false);
+const name = ref('');
+const handleOk = async () => {
+  console.log('submit', name.value);
+};
+</script>
+
+<template>
+  <button @click="visible = true">新建实例</button>
+  <VDialog v-model="visible" title="新建实例" :ok="handleOk" :hide-trigger="true">
+    <FormItemInput v-model="name" label="实例名称" placeholder="请输入实例名称" />
+  </VDialog>
+</template>
+```
+
+### 使用 trigger 插槽触发确认弹窗
+**场景**: 在操作列或详情页中用自定义按钮触发危险操作确认弹窗。
+
+通过 trigger 插槽自定义入口，用于危险操作前的二次确认。
+
+**使用的 API**: 属性: title, okText, ok
+
+```vue
+<script setup lang="ts">
+import { VDialog } from '@ksyun-internal/versatile';
+
+const handleOk = async () => {
+  console.log('release instance');
+};
+</script>
+
+<template>
+  <VDialog title="释放实例" ok-text="确认释放" :ok="handleOk">
+    <template #trigger>
+      <button>释放实例</button>
+    </template>
+    <div>释放后实例数据将被删除，且不可恢复。</div>
+  </VDialog>
+</template>
+```
+
+## 相关组件
+Dialog, VDrawer, useDialog
+

package/docs_for_llm/vdrawer.doc.md

@@ -0,0 +1,148 @@
+# 业务抽屉 (VDrawer)
+
+在基础 Drawer 之上补充默认触发器、受控显隐和异步确认逻辑的业务抽屉组件，适合编辑长表单和查看侧边详情。
+
+**关键词**: vdrawer, drawer, 业务抽屉, 侧边抽屉, 编辑抽屉, slot drawer
+
+**使用场景**: 侧边表单编辑、详情信息展示、通过按钮触发的抽屉
+
+## 导入语句
+```typescript
+import { VDrawer } from '@ksyun-internal/versatile';
+```
+
+## 属性 (Props)
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| title | `string` | `""` | 否 | 抽屉标题 | - | - |
+| placement | `"left" | "right" | "top" | "bottom"` | `"right"` | 否 | 抽屉弹出方向 | - | - |
+| size | `string` | `undefined` | 否 | 抽屉尺寸 | - | - |
+| width | `string | number` | `undefined` | 否 | 抽屉宽度 | - | - |
+| loading | `boolean` | `false` | 否 | 确认按钮加载状态 | - | - |
+| disabledOk | `boolean` | `false` | 否 | 是否禁用确认按钮 | - | - |
+| okText | `string` | `"确定"` | 否 | 确认按钮文案 | - | - |
+| cancelText | `string` | `"取消"` | 否 | 取消按钮文案 | - | - |
+| ok | `() => Promise<boolean | void> | boolean | void` | `undefined` | 否 | 确认时的异步处理函数，可返回 false 阻止关闭 | - | - |
+| cancel | `() => void` | `undefined` | 否 | 取消时的回调逻辑 | - | - |
+| hideClose | `boolean` | `false` | 否 | 是否隐藏右上角关闭按钮 | - | - |
+| overlay | `boolean` | `true` | 否 | 是否显示遮罩层 | - | - |
+| closable | `boolean` | `true` | 否 | 点击遮罩层是否可关闭 | - | - |
+| escClosable | `boolean` | `true` | 否 | 是否允许 ESC 关闭 | - | - |
+| draggable | `boolean` | `false` | 否 | 是否允许拖拽抽屉 | - | - |
+| terminate | `() => void` | `undefined` | 否 | 关闭动作统一回调 | - | - |
+| container | `string | Function` | `undefined` | 否 | 指定抽屉挂载容器 | - | - |
+| mode | `string` | `undefined` | 否 | 抽屉展示模式 | - | - |
+| hideTrigger | `boolean` | `false` | 否 | 隐藏默认 trigger，作为受控抽屉使用 | - | - |
+| modelValue | `boolean | undefined` | `undefined` | 否 | 抽屉显示状态 | - | - |
+| btnProps | `ButtonProps` | `undefined` | 否 | 默认 trigger 按钮属性 | - | - |
+| btnText | `string` | `"打开抽屉"` | 否 | 默认 trigger 按钮文案 | - | - |
+
+## 事件 (Events)
+| 事件名 | Vue事件名 | 说明 | 回调参数 | 示例 |
+| --- | --- | --- | --- | --- |
+| open | `@open` | 抽屉打开后触发 | `-` | `<Drawer @open="handleOpen">` |
+| close | `@close` | 抽屉关闭后触发，不管是什么原因导致的关闭 | `-` | `<Drawer @close="handleClose">` |
+| ok | `@ok` | 点击确定按钮时触发 | `-` | `<Drawer @ok="handleOk">` |
+| cancel | `@cancel` | 点击取消按钮时触发 | `-` | `<Drawer @cancel="handleCancel">` |
+| terminate | `@terminate` | 用户强行关闭抽屉时触发（点击关闭按钮、遮罩层或按 ESC） | `-` | `<Drawer @terminate="handleTerminate">` |
+| afterClose | `@afterClose` | 抽屉退出动画执行完成后触发 | `-` | `<Drawer @afterClose="handleAfterClose">` |
+
+## 插槽 (Slots)
+| 插槽名 | 说明 | 模板写法 | 示例 |
+| --- | --- | --- | --- |
+| default | 抽屉主体内容区域 | `<VDrawer>...</VDrawer>` | `<VDrawer>
+  <template <VDrawer>...</VDrawer>>
+    自定义default内容
+  </template>
+</VDrawer>` |
+| header | 自定义抽屉头部 | `<template #header>...</template>` | `<VDrawer>
+  <template <template #header>...</template>>头部内容</template>
+</VDrawer>` |
+| footer | 自定义抽屉底部操作区 | `<template #footer>...</template>` | `<VDrawer>
+  <template <template #footer>...</template>>底部内容</template>
+</VDrawer>` |
+| trigger | 自定义触发按钮或触发区域 | `<template #trigger>...</template>` | `<VDrawer>
+  <template <template #trigger>...</template>>
+    自定义trigger内容
+  </template>
+</VDrawer>` |
+
+### 插槽参数说明
+**default**
+
+- 参数结构: 无参数
+
+**header**
+
+- 参数结构: 无参数
+
+**footer**
+
+- 参数结构: 无参数
+
+**trigger**
+
+- 参数结构: 无参数
+
+## 使用示例
+### 侧边编辑抽屉
+**场景**: 在列表页右侧滑出编辑面板，保留用户当前上下文。
+
+用抽屉承载较长的编辑表单，避免打断列表上下文。
+
+**使用的 API**: 属性: modelValue, title, ok, hideTrigger
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { VDrawer, FormItemInput, Description } from '@ksyun-internal/versatile';
+
+const visible = ref(false);
+const name = ref('web-prod-01');
+const remark = ref('支付链路核心实例');
+const handleOk = async () => {
+  console.log('save', name.value, remark.value);
+};
+</script>
+
+<template>
+  <button @click="visible = true">编辑实例</button>
+  <VDrawer v-model="visible" title="编辑实例" :ok="handleOk" :hide-trigger="true">
+    <FormItemInput v-model="name" label="实例名称" />
+    <Description v-model="remark" />
+  </VDrawer>
+</template>
+```
+
+### 使用 trigger 和 footer 插槽自定义抽屉
+**场景**: 在详情预览场景下通过自定义触发器和底部按钮扩展抽屉交互。
+
+通过 trigger 和 footer 插槽自定义抽屉打开方式和底部操作区。
+
+**使用的 API**: 属性: modelValue, title, hideTrigger
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { VDrawer } from '@ksyun-internal/versatile';
+
+const visible = ref(false);
+</script>
+
+<template>
+  <VDrawer v-model="visible" title="实例详情" :hide-trigger="false">
+    <template #trigger>
+      <button>查看详情</button>
+    </template>
+    <div>这里可以放详情摘要、监控图表或操作记录。</div>
+    <template #footer>
+      <button @click="visible = false">关闭</button>
+      <button>导出详情</button>
+    </template>
+  </VDrawer>
+</template>
+```
+
+## 相关组件
+Drawer, VDialog
+

package/docs_for_llm/virtuallist.doc.md

@@ -12,28 +12,180 @@ import { VirtualList } from '@king-design/vue';
 ```
 
 ## 属性 (Props)
-| 属性名 | 类型 | 默认值 | 必填 | 说明 | 示例 |
-| --- | --- | --- | --- | --- | --- |
-| disabled | `boolean` | `false` | 否 | 是否禁用虚拟化，禁用后会渲染所有元素 | `<VirtualList disabled></VirtualList>` |
+| 属性名 | 类型 | 默认值 | 必填 | 说明 | 标签 | 示例 |
+| --- | --- | --- | --- | --- | --- | --- |
+| disabled | `boolean` | `false` | 否 | 是否禁用虚拟化，禁用后会渲染所有元素 | - | `<VirtualList disabled></VirtualList>` |
 
 ## 子组件 (Sub-Components)
 ### VirtualListContainer
 虚拟列表容器组件，用于组合式使用
 
+#### 组合示例
+##### 组合式使用
+**场景**: 使用子组件进行复杂布局
+
+使用子组件进行组合
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue';
+import { VirtualListContainer, VirtualListWrapper, VirtualListPhantom, VirtualListRows } from '@king-design/vue';
+
+const data = ref<{value: number; label: string}[]>([]);
+
+onMounted(() => {
+  const arr = [];
+  for (let i = 0; i < 10000; i++) {
+    arr.push({ value: i, label: `列表项 ${i}` });
+  }
+  data.value = arr;
+});
+</script>
+<template>
+  <div style="height: 400px;">
+    <VirtualListContainer>
+      <VirtualListPhantom />
+      <VirtualListWrapper tagName="ul">
+        <VirtualListRows>
+          <li v-for="item in data" :key="item.value" style="height: 40px; line-height: 40px;">
+            {{ item.label }}
+          </li>
+        </VirtualListRows>
+      </VirtualListWrapper>
+    </VirtualListContainer>
+  </div>
+</template>
+```
+
 ### VirtualListWrapper
 虚拟列表包装器组件，可通过 tagName 属性指定标签类型
 
+#### 属性 (Props)
 | 属性名 | 类型 | 说明 | 示例 |
 | --- | --- | --- | --- |
 | tagName | `string` | 指定渲染的标签名 | `<VirtualListWrapper tagName="ul"></VirtualListWrapper>` |
 
+#### 组合示例
+##### 组合式使用
+**场景**: 使用子组件进行复杂布局
+
+使用子组件进行组合
+
+**命中的子组件 API**: 属性: tagName
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue';
+import { VirtualListContainer, VirtualListWrapper, VirtualListPhantom, VirtualListRows } from '@king-design/vue';
+
+const data = ref<{value: number; label: string}[]>([]);
+
+onMounted(() => {
+  const arr = [];
+  for (let i = 0; i < 10000; i++) {
+    arr.push({ value: i, label: `列表项 ${i}` });
+  }
+  data.value = arr;
+});
+</script>
+<template>
+  <div style="height: 400px;">
+    <VirtualListContainer>
+      <VirtualListPhantom />
+      <VirtualListWrapper tagName="ul">
+        <VirtualListRows>
+          <li v-for="item in data" :key="item.value" style="height: 40px; line-height: 40px;">
+            {{ item.label }}
+          </li>
+        </VirtualListRows>
+      </VirtualListWrapper>
+    </VirtualListContainer>
+  </div>
+</template>
+```
+
 ### VirtualListPhantom
 占位组件，用于撑开滚动高度
 
+#### 组合示例
+##### 组合式使用
+**场景**: 使用子组件进行复杂布局
+
+使用子组件进行组合
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue';
+import { VirtualListContainer, VirtualListWrapper, VirtualListPhantom, VirtualListRows } from '@king-design/vue';
+
+const data = ref<{value: number; label: string}[]>([]);
+
+onMounted(() => {
+  const arr = [];
+  for (let i = 0; i < 10000; i++) {
+    arr.push({ value: i, label: `列表项 ${i}` });
+  }
+  data.value = arr;
+});
+</script>
+<template>
+  <div style="height: 400px;">
+    <VirtualListContainer>
+      <VirtualListPhantom />
+      <VirtualListWrapper tagName="ul">
+        <VirtualListRows>
+          <li v-for="item in data" :key="item.value" style="height: 40px; line-height: 40px;">
+            {{ item.label }}
+          </li>
+        </VirtualListRows>
+      </VirtualListWrapper>
+    </VirtualListContainer>
+  </div>
+</template>
+```
+
 ### VirtualListRows
 行渲染组件，包裹实际渲染的列表项
 
+#### 组合示例
+##### 组合式使用
+**场景**: 使用子组件进行复杂布局
+
+使用子组件进行组合
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue';
+import { VirtualListContainer, VirtualListWrapper, VirtualListPhantom, VirtualListRows } from '@king-design/vue';
+
+const data = ref<{value: number; label: string}[]>([]);
+
+onMounted(() => {
+  const arr = [];
+  for (let i = 0; i < 10000; i++) {
+    arr.push({ value: i, label: `列表项 ${i}` });
+  }
+  data.value = arr;
+});
+</script>
+<template>
+  <div style="height: 400px;">
+    <VirtualListContainer>
+      <VirtualListPhantom />
+      <VirtualListWrapper tagName="ul">
+        <VirtualListRows>
+          <li v-for="item in data" :key="item.value" style="height: 40px; line-height: 40px;">
+            {{ item.label }}
+          </li>
+        </VirtualListRows>
+      </VirtualListWrapper>
+    </VirtualListContainer>
+  </div>
+</template>
+```
+
 ## 常见错误与正确用法 (Anti-Hallucination)
+### 容器未设置高度
 > **错误用法**: `<VirtualList> <!-- 没有高度，无法滚动 -->
   <div v-for="item in data" :key="item.value">...</div>
 </VirtualList>`
@@ -42,10 +194,12 @@ import { VirtualList } from '@king-design/vue';
 </VirtualList>`
 > **说明**: VirtualList 容器必须设置固定高度才能正常工作
 
+### 列表项缺少 key
 > **错误用法**: `<div v-for="item in data">{{ item.label }}</div>`
 > **正确写法**: `<div v-for="item in data" :key="item.value">{{ item.label }}</div>`
 > **说明**: 每个列表项必须设置唯一的 key 以确保正确渲染
 
+### 数据量较小时启用虚拟化
 > **错误用法**: `const data = [1, 2, 3]; // 只有 3 条数据
 <VirtualList>...</VirtualList>`
 > **正确写法**: `const data = [1, 2, 3];

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"
+  ]
+}