king-design-analyzer 2.1.9 → 2.2.1

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

package/docs_for_llm/useLayoutStandardList.doc.md

@@ -0,0 +1,38 @@
+# 标准列表页组合状态 (useLayoutStandardList)
+
+为 LayoutStandardList 组合分页、搜索、分组、排序、列设置和批量操作状态，适合标准列表页快速搭建。
+
+**关键词**: useLayoutStandardList, LayoutStandardList, 标准列表页, 分页 搜索 排序, 批量操作, 表格组合状态
+
+## 导入语句
+```typescript
+import { useLayoutStandardList } from '@ksyun-internal/versatile';
+```
+
+## 返回值
+```typescript
+{ layoutStandardListRef: Ref<any>; page: Ref<number>; limit: Ref<number>; searchValue: Ref<string>; searchItems: Ref<Record<string, any> | undefined>; group: Ref<Record<string, any>>; sort: Ref<TableSortValue>; checkedKeys: Ref<string[]>; tableRef: Ref<Table | undefined>; refetch: any; loading: any; isShowDialog: Ref<boolean>; showFilterTableFieldsDialog: Function; ... }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 在 LayoutStandardList 外又重复手写 useSearch/usePagination/useTableSort，导致状态来源分裂
+> **错误用法**: `const search = useSearch(); const pagination = usePagination(); const state = useLayoutStandardList();`
+> **正确写法**: `const state = useLayoutStandardList();`
+> **说明**: 如果页面主体就是 LayoutStandardList，优先复用这个组合 hook。
+
+## 使用示例
+### 标准列表页容器
+在 LayoutStandardList 外层持有组合状态和实例引用
+
+```vue
+<script setup lang="ts">
+import { LayoutStandardList, useLayoutStandardList } from '@ksyun-internal/versatile';
+
+const { layoutStandardListRef, page, limit, searchItems, checkedKeys } = useLayoutStandardList();
+</script>
+
+<template>
+  <LayoutStandardList ref="layoutStandardListRef" :use-list="() => ({ loading: false, dataSource: [], total: 0 })" />
+</template>
+```
+

package/docs_for_llm/useMessage.doc.md

@@ -0,0 +1,46 @@
+# 变更消息反馈 (useMessage)
+
+为 Apollo mutation 封装统一的成功/失败消息处理逻辑，适合删除、编辑、创建等需要标准化提示文案的请求场景。
+
+**关键词**: useMessage, mutation 提示, apollo, 成功失败消息, toast, 反馈
+
+## 导入语句
+```typescript
+import { useMessage } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| onError | `UseMutationReturn<TResult, TVariables>['onError']` | 是 | mutation 返回的错误监听函数 |
+| onDone | `UseMutationReturn<TResult, TVariables>['onDone']` | 否 | mutation 返回的完成监听函数 |
+| isSuccess | `(res: FetchResult<TResult>) => boolean` | 否 | 自定义成功判定逻辑 |
+| action | `string | (() => string)` | 否 | 操作名称，用于生成成功/失败提示文案 |
+| successCallback | `(res: FetchResult<TResult>) => any` | 否 | 成功后的额外回调 |
+| failedCallback | `(e: Error) => any` | 否 | 失败后的额外回调 |
+
+## 返回值
+```typescript
+void
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 接口返回结构不是标准成功态，但没有传 isSuccess，自定义失败被当成成功
+> **错误用法**: `useMessage(onError, onDone, undefined, '删除');`
+> **正确写法**: `useMessage(onError, onDone, (res) => res.data?.delete?.code === 200, '删除');`
+> **说明**: 如果后端不是默认成功结构，建议显式提供 isSuccess。
+
+## 使用示例
+### 统一处理 mutation 提示
+把创建、删除等 mutation 的消息提示收口到 hook
+
+```vue
+<script setup lang="ts">
+import { useMutation } from '@vue/apollo-composable';
+import { useMessage } from '@ksyun-internal/versatile';
+
+const { onError, onDone } = useMutation(CREATE_INSTANCE);
+useMessage(onError, onDone, undefined, '创建实例');
+</script>
+```
+

package/docs_for_llm/useModifyCache.doc.md

@@ -0,0 +1,37 @@
+# Apollo 缓存修改 (useModifyCache)
+
+返回一个可复用的 Apollo cache.modify 封装函数，适合在 mutation 后局部更新缓存而不重新发请求。
+
+**关键词**: useModifyCache, apollo cache, cache.modify, mutation, 局部更新缓存, graphql
+
+## 导入语句
+```typescript
+import { useModifyCache } from '@ksyun-internal/versatile';
+```
+
+## 返回值
+```typescript
+(identify: StoreObject | Reference, fields: Cache.ModifyOptions['fields']) => void
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### identify 对象缺少 Apollo 可识别的标识字段
+> **错误用法**: `modifyCache({ name: 'instance-1' }, { status: () => 'running' });`
+> **正确写法**: `modifyCache({ __typename: 'Instance', id: 'ins-1' }, { status: () => 'running' });`
+> **说明**: identify 需要能让 Apollo 唯一定位缓存实体。
+
+## 使用示例
+### 局部更新 Apollo 缓存
+在删除或编辑成功后直接修改缓存字段
+
+```vue
+<script setup lang="ts">
+import { useModifyCache } from '@ksyun-internal/versatile';
+
+const modifyCache = useModifyCache();
+modifyCache({ __typename: 'Instance', id: 'ins-1' }, {
+  name: () => 'new-name',
+});
+</script>
+```
+

package/docs_for_llm/useOpenDialog.doc.md

@@ -0,0 +1,41 @@
+# 表格操作弹窗 (useOpenDialog)
+
+针对表格单行操作和批量操作封装弹窗打开逻辑，统一维护当前操作项和批量操作项集合。
+
+**关键词**: useOpenDialog, 批量操作, 表格操作, dialog, 单行操作, tableRef
+
+## 导入语句
+```typescript
+import { useOpenDialog } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| tableRef | `Ref<Table | undefined>` | 否 | 表格实例引用，批量操作时可从表格中读取选中项 |
+
+## 返回值
+```typescript
+{ isShowDialog: Ref<boolean>; dialogRef: Ref<any>; opCols: Ref<T[] | undefined>; opCol: Ref<T | undefined>; show: Function; hide: Function; handleClickOpBtn: Function; handleClickBatchOpBtn: Function; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 批量操作场景未传入 tableRef，导致无法读取选中项
+> **错误用法**: `const dialog = useOpenDialog();`
+> **正确写法**: `const dialog = useOpenDialog(tableRef);`
+> **说明**: 如果需要 handleClickBatchOpBtn 读取表格选中项，应传入 tableRef。
+
+## 使用示例
+### 表格操作弹窗
+点击单行操作按钮时打开弹窗并记录当前行数据
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useOpenDialog } from '@ksyun-internal/versatile';
+
+const tableRef = ref();
+const { isShowDialog, opCol, handleClickOpBtn } = useOpenDialog(tableRef);
+</script>
+```
+

package/docs_for_llm/usePagination.doc.md

@@ -0,0 +1,60 @@
+# 分页状态管理 (usePagination)
+
+管理列表页常用的 page、limit、limits 以及分页变更回调，适合和 ProTable、PaginationPlus、Search 组合使用。
+
+**关键词**: usePagination, 分页, page, limit, PaginationPlus, 列表页
+
+## 导入语句
+```typescript
+import { usePagination } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| options | `{ page?: number; limit?: number; limits?: number[]; callback?: (v: PaginationChangeData) => void }` | 否 | 分页初始化配置，可预设页码、每页条数、可选 limits 及翻页后的回调 |
+
+## 返回值
+```typescript
+{ page: Ref<number>; limit: Ref<number>; limits: Ref<number[]>; pageChange: (pageParams: PaginationChangeData) => void; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 只绑定 page，没有同步维护 limit
+> **错误用法**: `const { page } = usePagination();`
+> **正确写法**: `const { page, limit } = usePagination();`
+> **说明**: 如果页面支持切换每页条数，应同时使用 hook 返回的 limit。
+
+## 使用示例
+### 基础分页用法
+通过 hook 统一管理列表页码和每页条数
+
+```vue
+<script setup lang="ts">
+import { PaginationPlus, usePagination } from '@ksyun-internal/versatile';
+
+const { page, limit, pageChange } = usePagination({
+  page: 1,
+  limit: 20,
+});
+</script>
+
+<template>
+  <PaginationPlus v-model="page" v-model:limit="limit" :total="200" @change="pageChange" />
+</template>
+```
+
+### 带回调的分页
+在分页变化后触发数据刷新或埋点逻辑
+
+```vue
+<script setup lang="ts">
+import { usePagination } from '@ksyun-internal/versatile';
+
+const fetchList = () => console.log('reload');
+const { page, limit, pageChange } = usePagination({
+  callback: () => fetchList(),
+});
+</script>
+```
+

package/docs_for_llm/usePersist.doc.md

@@ -0,0 +1,54 @@
+# 本地持久化 (usePersist)
+
+将响应式数据持久化到 localStorage 或 sessionStorage，适合保存列表筛选、用户偏好和表格配置。
+
+**关键词**: usePersist, localStorage, sessionStorage, 持久化, 列表偏好, 缓存状态
+
+## 导入语句
+```typescript
+import { usePersist } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| key | `string` | 是 | 存储键名 |
+| defaultValue | `T` | 是 | 初始化默认值 |
+| options | `PersistOptions<T>` | 否 | 持久化配置，可切换 storage、自定义序列化和 watch 行为 |
+
+## 返回值
+```typescript
+Ref<T>
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 使用会变化的 key，导致同一份状态被重复写入
+> **错误用法**: `usePersist(`table-${Date.now()}`, []);`
+> **正确写法**: `usePersist('instance-table-fields', []);`
+> **说明**: key 应保持稳定，否则无法复用持久化结果。
+
+## 使用示例
+### 持久化表格配置
+保存用户的列显隐或筛选配置
+
+```vue
+<script setup lang="ts">
+import { usePersist } from '@ksyun-internal/versatile';
+
+const tableFields = usePersist('table-fields', ['name', 'status']);
+</script>
+```
+
+### 使用 sessionStorage
+仅在当前会话内保留搜索状态
+
+```vue
+<script setup lang="ts">
+import { usePersist } from '@ksyun-internal/versatile';
+
+const searchState = usePersist('instance-search', { key: 'name', value: '' }, {
+  storage: sessionStorage,
+});
+</script>
+```
+

package/docs_for_llm/usePoll.doc.md

@@ -0,0 +1,41 @@
+# 查询轮询 (usePoll)
+
+包装 Apollo 查询结果并启用轮询场景，适合在列表页、详情页中持续刷新接口数据。
+
+**关键词**: usePoll, 轮询, apollo, useQuery, 自动刷新, 列表轮询
+
+## 导入语句
+```typescript
+import { usePoll } from '@ksyun-internal/versatile';
+```
+
+## 参数 (Params)
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| result | `UseQueryReturn<any, any>` | 是 | Apollo useQuery 返回的查询对象 |
+
+## 返回值
+```typescript
+UseQueryReturn<any, any>
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 传入普通 Promise 或自定义对象而不是 Apollo 查询返回值
+> **错误用法**: `const result = usePoll(fetchList());`
+> **正确写法**: `const result = usePoll(useQuery(GET_LIST));`
+> **说明**: usePoll 依赖 Apollo 的 UseQueryReturn 结构。
+
+## 使用示例
+### 轮询查询结果
+对 useQuery 返回值启用轮询式刷新
+
+```vue
+<script setup lang="ts">
+import { useQuery } from '@vue/apollo-composable';
+import { usePoll } from '@ksyun-internal/versatile';
+
+const queryResult = useQuery(GET_INSTANCE_LIST);
+const pollResult = usePoll(queryResult);
+</script>
+```
+

package/docs_for_llm/useRoutePlus.doc.md

@@ -0,0 +1,34 @@
+# 增强路由读取 (useRoutePlus)
+
+对 vue-router 的 route 做包装，直接返回 params、query 及其 refs，便于在组合式函数中按字段响应式使用。
+
+**关键词**: useRoutePlus, route params, query refs, vue-router, 详情页参数, 路由读取
+
+## 导入语句
+```typescript
+import { useRoutePlus } from '@ksyun-internal/versatile';
+```
+
+## 返回值
+```typescript
+{ $route: RouteLocationNormalizedLoadedGeneric; params: Record<string, string>; paramRefs: ToRefs<Record<string, string>>; query: LocationQuery; queryRefs: ToRefs<LocationQuery>; }
+```
+
+## 常见错误与正确用法 (Anti-Hallucination)
+### 直接修改 paramRefs/queryRefs，期望同步改写路由地址
+> **错误用法**: `paramRefs.id.value = '2';`
+> **正确写法**: `如需跳转，请配合 useRouterPlus 或 router.push。`
+> **说明**: 这个 hook 主要用于读取路由状态，不负责写回 URL。
+
+## 使用示例
+### 读取详情页路由参数
+把详情页 id 和 query 参数拆成可直接使用的 refs
+
+```vue
+<script setup lang="ts">
+import { useRoutePlus } from '@ksyun-internal/versatile';
+
+const { params, paramRefs, queryRefs } = useRoutePlus();
+</script>
+```
+