@qin-ui/antdv-next-pro 1.1.14 → 1.1.15

package/AI-CONTEXT.md

@@ -1,37 +1,284 @@
-# @qin-ui/antdv-next-pro
+# @qin-ui/antdv-next-pro — AI 上下文
 
-> 基于 antdv-next 的配置驱动表单和表格组件库。
+> Schema-driven Vue 3 高级组件库，基于 antdv-next。用 JavaScript 对象描述 UI，而非在模板中堆砌组件标签。
 
-## 安装
+---
 
-```bash
-npm install @qin-ui/antdv-next-pro antdv-next vue
+## 1. 架构概览
+
+### 1.1 三层架构
+
+```
+┌─────────────────────────────────────────────────┐
+│  Field[] 配置层（用户编写的 JS 对象）              │
+├─────────────────────────────────────────────────┤
+│  @qin-ui/antdv-next-pro（Schema 解析 + 属性分层）  │
+│  逐层剥离 → Grid→a-col, FormItem→a-form-item,     │
+│  剩余属性→输入控件                                  │
+├─────────────────────────────────────────────────┤
+│  antdv-next（Vue 3 组件库）                        │
+│  a-input / a-select / a-date-picker / a-table ... │
+└─────────────────────────────────────────────────┘
+```
+
+ProForm/ProTable 是**渲染引擎**，不是组件库。Field 属性被逐层剥离分发到不同层级的 antdv-next 组件。
+
+### 1.2 组件解析链
+
+```
+Field.component  →  componentMap[component]  →  antdv-next 组件
+  'input'         →  Input          (a-input)
+  'select'        →  Select         (a-select)
+  'switch'        →  Switch         (a-switch)
+  'custom'        →  VueComponent   (直接渲染)
+  'my-custom'     →  ProComponentProvider 注入的自定义组件
+```
+
+### 1.3 内置组件映射表
+
+| component           | antdv-next 组件 | 常用输入控件层透传 Props                                             |
+| :------------------ | :-------------- | :------------------------------------------------------------------- |
+| `input`             | Input           | placeholder, maxlength, allowClear, addonBefore, addonAfter, showCount |
+| `textarea`          | TextArea        | rows, maxlength, showCount, autoSize                                |
+| `input-password`    | InputPassword   | placeholder, maxlength, visibilityToggle                            |
+| `input-otp`         | InputOTP        | length, mask, separator                                             |
+| `input-search`      | InputSearch     | placeholder, loading, onSearch                                      |
+| `input-number`      | InputNumber     | min, max, step, precision, formatter, parser                        |
+| `select`            | Select          | **options**, mode, showSearch, allowClear, maxTagCount, loading     |
+| `auto-complete`     | AutoComplete    | **options**, filterOption, allowClear                               |
+| `cascader`          | Cascader        | **options**, fieldNames, showSearch, expandTrigger                  |
+| `date-picker`       | DatePicker      | picker, format, showTime, disabledDate, allowClear                  |
+| `range-picker`      | RangePicker     | format, showTime, disabledDate, allowClear                          |
+| `time-picker`       | TimePicker      | format, showSecond, allowClear, hourStep                            |
+| `time-range-picker` | TimeRangePicker | format, allowClear                                                  |
+| `checkbox-group`    | CheckboxGroup   | **options**, direction                                              |
+| `radio-group`       | RadioGroup      | **options**, direction, buttonStyle                                 |
+| `switch`            | Switch          | checkedChildren, unCheckedChildren, loading                         |
+| `slider`            | Slider          | min, max, step, marks, range, tooltip                               |
+| `tree-select`       | TreeSelect      | **treeData**, showSearch, treeCheckable                             |
+| `transfer`          | Transfer        | **dataSource**, **titles**, **targetKeys**, showSearch              |
+| `custom`            | 自定义          | component 传入 Vue 组件或 h() 渲染函数                              |
+
+> **写任何输入控件属性前，必须查阅 [antdv-next 文档](https://antdv-next.com/llms-full-cn.txt) 确认属性名和类型。**
+
+---
+
+## 2. 属性分层传递（核心规则）
+
+Field 属性逐层剥离，分发到渲染树的不同目标：
+
+```html
+<a-col :span="8">
+  <a-form-item label="城市" :rules="[...]">
+    <a-select placeholder="选择" :options="[...]" />
+  </a-form-item>
+</a-col>
+```
+
+### 属性归属
+
+**Grid 层 → `<a-col>`**（仅 grid 启用时生效）
+`span`, `order`, `offset`, `push`, `pull`, `flex`, `xs`, `sm`, `md`, `lg`, `xl`, `xxl`
+
+**FormItem 层 → `<a-form-item>`**
+`label`, `rules`, `colon`, `labelAlign`, `labelCol`, `wrapperCol`, `tooltip`, `extra`, `help`, `validateFirst`, `validateTrigger`, `valuePropName`, `normalize`, `formItemClass`, `formItemStyle`, `formItemContainer`, `formItemDataAttrs`
+
+**输入控件层 → 输入组件**
+其余所有属性（`disabled`, `placeholder`, `allowClear`, `options`, `showSearch`, `maxlength`, `mode`, `componentDataAttrs`, `componentClass`, `componentStyle` 等）
+
+**ProForm 消费（不绑定 DOM）：** `component`, `fields`, `hidden`, `slots`, `modelProp`, `valueFormatter`, `componentContainer`, `extraProps`
+
+### modelProp
+
+决定 `v-model:xxx` 绑定变量名：
+- 默认 `'value'` → `v-model:value`
+- Switch/Checkbox 使用 `'checked'`
+- **ProComponentProvider 已为 `switch` 预设 `modelProp: 'checked'`**，通常无需手动指定
+
+---
+
+## 3. 渐进式用法
+
+### 第一阶段：配置驱动
+
+**禁止在模板中手写 `<a-form-item>` 或 `<a-input>`。**
+
+```typescript
+import { ProForm, useForm } from '@qin-ui/antdv-next-pro';
+
+const form = useForm({ username: '', password: '' }, [
+  {
+    path: 'username',
+    component: 'input',
+    label: '用户名',
+    placeholder: '请输入用户名',
+    rules: [{ required: true, message: '请输入' }],
+  },
+  {
+    path: 'password',
+    component: 'input-password',
+    label: '密码',
+    placeholder: '请输入密码',
+    rules: [{ required: true, message: '请输入' }],
+  },
+]);
+```
+
+```html
+<template>
+  <ProForm :form="form" />
+</template>
 ```
 
-## 核心导出
+### 第二阶段：字段联动
 
-### 组件
+`disabled`、`hidden`、`rules` 等控制属性支持多种联动方式：
 
-- `ProForm` - 配置驱动表单组件
-- `ProTable` - 配置驱动表格组件
-- `ProComponentProvider` - 全局配置提供者
+```typescript
+import { computed, ref } from 'vue';
 
-### Hooks
+const form = useForm({ hasLimit: false, limitCount: undefined }, [
+  { path: 'hasLimit', component: 'switch', label: '开启限制' },
+  {
+    path: 'limitCount',
+    component: 'input-number',
+    label: '限制次数',
+    // 方式一：computed() — 声明式，推荐用于初始化时已知的联动
+    disabled: computed(() => !form.formData.hasLimit),
+    rules: computed(() => [
+      { required: form.formData.hasLimit, message: '请输入' },
+    ]),
+  },
+]);
 
-- `useForm<D>()` - 创建表单实例
-- `useFields<D>()` - 字段配置管理
-- `useFormRef()` - 表单组件引用
-- `useTable<D, T>()` - 创建表格实例
+// 方式二：ref() — 适合外部状态控制
+const isDisabled = ref(false); // disabled: isDisabled
 
-## 字段配置（Field）
+// 方式三：setField() — 命令式，适合运行时事件触发
+form.setField('limitCount', { disabled: true });
+```
+
+**选择：** 初始化联动 → `computed()`；运行时事件 → `setField()`；外部共享状态 → `ref()`。代码越简单越好。
+
+### 第三阶段：自定义扩展
+
+```typescript
+import { h } from 'vue';
+
+const form = useForm({ agreement: false }, [
+  {
+    path: 'agreement',
+    component: (p, ctx) => h(MyCheckbox, { ...p, ...ctx.attrs }),
+    modelProp: 'checked',
+    rules: [{ validator: (_, val) => val ? Promise.resolve() : Promise.reject('请同意') }],
+  },
+]);
+```
+
+```html
+<ProForm :form="form">
+  <!-- 同名插槽接管渲染，scoped 内置 value/checked 等绑定参数 -->
+  <template #agreement="scoped">
+    <a-checkbox v-bind="scoped">同意协议</a-checkbox>
+  </template>
+</ProForm>
+```
+
+---
+
+## 4. 反模式
+
+```ts
+// ❌ 不要手写 a-form-item — ProForm 自动渲染
+// ❌ 不要猜测属性名 — 必须查阅 antdv-next 文档
+{ path: 'city', component: 'select', searchable: true }    // 错：Select 没有 searchable
+{ path: 'city', component: 'select', showSearch: true }     // 对：查阅文档后使用 showSearch
+
+// ❌ path 必须精确对应 formData 中的键名，否则数据/校验丢失
+// ✅ 联动优先用 computed()，运行时用 setField()，不要过度设计
+```
+
+---
+
+## 5. ProComponentProvider：全局默认配置
+
+应用顶层统一配置所有子组件默认属性。
+
+**INJECT_CONFIG 预设默认值：**
+
+| 组件                                      | 预设默认值                                                                                                                              |
+| :---------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
+| `switch`                                  | `{ modelProp: 'checked' }`                                                                                                               |
+| `input`                                   | `{ maxlength: 100, allowClear: true, placeholder: '请输入' }`                                                                           |
+| `textarea`                                | `{ maxlength: 200, autoSize: {minRows:3,maxRows:6}, showCount: true, allowClear: true, placeholder: '请输入' }`                         |
+| `select` / `cascader` / `auto-complete`   | `{ allowClear: true, placeholder: '请选择', getPopupContainer }`                                                                        |
+| `input-number`                            | `{ max: 10^15, min: -(10^15), controls: false, placeholder: '请输入', style: {width:'100%'} }`                                          |
+| `date-picker` / `range-picker` / `time-*` | `{ allowClear: true, getPopupContainer, style: {width:'100%'} }`                                                                        |
+| `pro-table`                               | `{ pagination: {showTotal, showSizeChanger, showQuickJumper}, searchFormConfig: {layout:'grid'}, control: true, addIndexColumn: true }` |
+| `pro-form`                                | `{ grid: { gutter: {xs:8, sm:16, md:16, lg:24} } }`                                                                                     |
+| `pro-form-item`                           | `{ validateFirst: true, span: 8 }`                                                                                                      |
+
+**优先级：** Field 级别配置 > `componentVars` > `INJECT_CONFIG` 预设
+
+```vue
+<template>
+  <ProComponentProvider :component-vars="config">
+    <ProForm :form="form" />
+    <ProTable :table="table" />
+  </ProComponentProvider>
+</template>
+
+<script setup lang="ts">
+import { ProComponentProvider } from '@qin-ui/antdv-next-pro';
+
+const config = {
+  'pro-form-item': { validateFirst: true, span: 6 },
+  input: { maxlength: 200 },
+  select: { showSearch: true },
+  'pro-table': { addIndexColumn: false },
+};
+</script>
+```
+
+---
+
+## 6. ProTable 速览
+
+```vue
+<script setup lang="ts">
+import { ProTable, useTable } from '@qin-ui/antdv-next-pro';
+
+type Row = { id: number; name: string; status: string };
+
+const table = useTable<Row>({
+  columns: [
+    { title: 'ID', dataIndex: 'id', width: 80 },
+    { title: '姓名', dataIndex: 'name', width: 120 },
+    { title: '状态', dataIndex: 'status', width: 100 },
+  ],
+  // searchFields 格式与 ProForm fields 完全一致，支持相同的分层剥离机制
+  searchFields: [
+    { path: 'name', component: 'input', placeholder: '搜索姓名' },
+    { path: 'status', component: 'select', options: [...], placeholder: '状态' },
+  ],
+});
+
+// searchForm 是 ProForm 实例，可使用所有表单方法
+table.searchForm.setField('name', { placeholder: '请输入' });
+</script>
+
+<template>
+  <ProTable :table="table" :search="() => fetchData()" addIndexColumn immediateSearch />
+</template>
+```
 
-每个字段支持：`path`, `label`, `component`, `hidden`, `disabled`, `rules`, `valueFormatter`, `fields`, `grid`, `slots`, `componentStyle`, `componentClass`, `componentContainer`, `formItemStyle`, `formItemClass`, `formItemContainer`, `modelProp`
+---
 
-内置组件：input, textarea, input-search, input-password, input-number, select, cascader, date-picker, range-picker, time-picker, checkbox-group, radio-group, switch, slider, tree-select, transfer, custom
+## 7. 参考
 
-## 表格列配置（Column）
+按优先级查阅：
 
-- `dataIndex` - 数据路径（优先使用）
-- `key` - 列标识（dataIndex 不满足时使用）
-- `hidden` - 是否隐藏
-- 所有 antdv-next ColumnType 属性
+1. **`node_modules/@qin-ui/antdv-next-pro/api.json`** — 结构化 API 元数据（函数签名、类型定义、JSDoc 示例）
+2. **`node_modules/@qin-ui/antdv-next-pro/README.md`** — 完整使用文档和代码示例
+3. **`https://antdv-next.com/llms-full-cn.txt`** — antdv-next 全部组件 API（确认输入控件层属性时必查）
+4. **`https://antdv-next.com/llms-semantic-cn.md`** — antdv-next 组件语义化 DOM 结构（自定义样式时必查）

package/README.md

@@ -1,6 +1,6 @@
 # @qin-ui/antdv-next-pro
 
-> 基于 **antdv-next** 和 **Vue 3.x** 的二次封装高级组件库，提供高度可配置、Schema 驱动的 `ProForm`、`ProTable` 和 `ComponentProvider`。
+> 基于 **antdv-next**（Vue 3 组件库，对齐 Ant Design 设计规范）和 **Vue 3.x** 的二次封装高级组件库，提供高度可配置、Schema 驱动的 `ProForm`、`ProTable` 和 `ProComponentProvider`。
 
 <p align="center">
   <img src="https://img.shields.io/badge/antdv--next-v1.1%2B-blue" alt="antdv-next" />
@@ -65,7 +65,7 @@ const form = useForm<FormData>({}, [
 
 | 属性/方法                  | 类型                             | 说明                                                      |
 | :------------------------- | :------------------------------- | :-------------------------------------------------------- |
-| `formRef`                  | `Ref<FormInstance \| undefined>` | AntdvNext FormInstance 引用，支持直接调用 validate 等方法 |
+| `formRef`                  | `Ref<FormInstance \| undefined>` | **antdv-next 原生 [FormInstance](https://antdv-next.com/components/form-cn#api)** 引用，可直接调用 `validate()`、`resetFields()`、`validateFields([paths])`、`clearValidate([paths])` 等原生方法 |
 | `formData`                 | `Reactive<D>`                    | 响应式表单数据对象                                        |
 | `fields`                   | `Ref<Field<D>[]>`                | 响应式字段配置数组                                        |
 | `getFormData(path?)`       | `(path?) => any`                 | 读取表单字段或整个表单的值（支持深层路径）                |
@@ -75,11 +75,12 @@ const form = useForm<FormData>({}, [
 
 ### `ProForm` Props
 
-| 属性     | 类型                   | 默认值  | 说明                                    |
-| :------- | :--------------------- | :------ | :-------------------------------------- |
-| `form`   | `Form<D>`              | -       | `useForm` 返回的实例                    |
-| `grid`   | `boolean \| GridProps` | `false` | 是否启用 Grid 网格布局                  |
-| 其余属性 | `FormProps`            | -       | 继承并直接透传至 antdv-next `Form` 组件 |
+| 属性       | 类型                                          | 默认值  | 说明                                                         |
+| :--------- | :-------------------------------------------- | :------ | :----------------------------------------------------------- |
+| `form`     | `Form<D>`                                     | -       | `useForm` 返回的实例                                         |
+| `grid`     | `boolean \| GridProps`                        | `false` | 是否启用 Grid 网格布局                                       |
+| `disabled` | `boolean`                                     | `false` | 是否全局禁用整个表单                                         |
+| 其余属性   | 继承 antdv-next [`FormProps`](https://antdv-next.com/components/form-cn#api) | -       | 如 `labelCol`、`wrapperCol`、`labelAlign`、`colon` 等，直接透传至 antdv-next `Form` 组件 |
 
 ---
 
@@ -110,7 +111,7 @@ const form = useForm<FormData>({}, [
 | `componentContainer` | `Component`                         | 表单输入组件的外层包裹容器组件                            |
 | `componentDataAttrs` | `Record<string, string>`            | 附加到输入组件 DOM 节点上的自定义 data 属性               |
 | `valueFormatter`     | `ValueFormatter`                    | 字段值格式化与转换器（支持 get/set 双向处理器）           |
-| `modelProp`          | `string`                            | 双向绑定的数据名，默认 `'value'`                          |
+| `modelProp`          | `string`                            | 双向绑定的数据名，默认 `'value'`。Switch/Checkbox 使用 `'checked'`，**ProComponentProvider 已为 `switch` 预设此值** |
 
 > [!NOTE]
 > **响应式支持**：除了 `component`、`fields`、`slots`、`modelProp`、`formItemContainer`、`componentContainer`、`valueFormatter` 之外，所有属性均高度支持 `Ref` 或 `ComputedRef` 响应式数据。
@@ -221,7 +222,22 @@ const table = useTable<Row>({
 | `dataSource`   | `T[]`            | 静态初始数据源数组                                |
 | `pageParam`    | `PageParam`      | 初始分页参数（current, pageSize, total）          |
 | `searchParam`  | `DeepPartial<D>` | 搜索栏表单初始填充数据                            |
-| `searchFields` | `Fields<D>`      | 搜索栏字段 Schema 配置（格式与 ProForm 完全一致） |
+| `searchFields` | `Fields<D>`      | 搜索栏字段 Schema 配置，**格式与 ProForm 的 `fields` 完全一致**，同样支持配置驱动渲染和属性透传 |
+
+### `useTable` 返回值 (Table 实例)
+
+| 属性/方法             | 类型                      | 说明                                                                 |
+| :-------------------- | :------------------------ | :------------------------------------------------------------------- |
+| `columns`             | `Ref<Column<T>[]>`        | 响应式表格列配置数组                                                  |
+| `dataSource`          | `Ref<T[]>`                | 响应式表格数据源                                                      |
+| `pageParam`           | `Reactive<PageParam>`     | 响应式分页参数：`{ current, pageSize, total }`                        |
+| `searchForm`          | `Form<D>`                 | 搜索栏 ProForm 实例，可通过 `searchForm.formData` 获取搜索条件，也可调用其所有字段操作方法 |
+| `setColumn`           | `(path, col, opts?)`      | 动态合并/覆盖列配置（`opts.updateType: 'merge' \| 'rewrite'`）        |
+| `deleteColumn`        | `(path, opts?)`           | 根据 dataIndex 路径或查找函数删除列                                   |
+| `appendColumn`        | `(path, col, opts?)`      | 在指定列后追加新列                                                    |
+| `prependColumn`       | `(path, col, opts?)`      | 在指定列前插入新列                                                    |
+| `setPageParam`        | `(pageParam)`             | 更新分页参数（支持局部属性或函数式更新）                              |
+| `resetQueryParams`    | `()`                      | 重置分页状态和搜索表单数据至初始值                                    |
 
 ### `ProTable` Props
 
@@ -234,23 +250,24 @@ const table = useTable<Row>({
 | `control`          | `boolean \| { sizeControl, columnControl }` | `true`  | 是否展示表格右上角尺寸调节和列显示控制条          |
 | `searchFormConfig` | `SearchFormConfig`                          | -       | 搜索栏表单的排版布局及展开/收起配置参数           |
 | `tableContainer`   | `Component \| false`                        | -       | 表格区域外层自定义包裹组件                        |
+| 其余属性           | 继承 antdv-next [`TableProps`](https://antdv-next.com/components/table-cn#api) | -       | 如 `bordered`、`loading`、`size`、`pagination` 等，直接透传至 antdv-next `Table` 组件 |
 
 ---
 
-## ⚙️ ComponentProvider
+## ⚙️ ProComponentProvider
 
-全局或局部的默认配置提供者，通过在最外层包裹 `ComponentProvider`，传入 `componentVars` 属性，能够极其优雅地控制其所有子组件的默认配置。
+全局或局部的默认配置提供者，通过在最外层包裹 `ProComponentProvider`，传入 `componentVars` 属性，能够极其优雅地控制其所有子组件的默认配置。
 
 ```vue
 <template>
-  <ComponentProvider :component-vars="config">
+  <ProComponentProvider :component-vars="config">
     <ProForm :form="form" />
     <ProTable :table="table" />
-  </ComponentProvider>
+  </ProComponentProvider>
 </template>
 
 <script setup lang="ts">
-import { ComponentProvider } from '@qin-ui/antdv-next-pro';
+import { ProComponentProvider } from '@qin-ui/antdv-next-pro';
 
 const config = {
   'pro-form': { grid: { gutter: 24 } },

package/api.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-06-25T06:47:30.124Z",
+  "generatedAt": "2026-07-06T09:29:07.307Z",
   "name": "@qin-ui/antdv-next-pro",
   "api": [
     {
@@ -38,6 +38,13 @@
       "signature": "<SlotComponent>",
       "description": "插槽渲染辅助组件。用于在表单或表格的自定义插槽中动态渲染外部传入的 VNode、渲染函数或静态字符串。"
     },
+    {
+      "name": "BaseComponentMap",
+      "type": "type",
+      "package": "@qin-ui/antdv-next-pro",
+      "signature": "export type BaseComponentMap =",
+      "description": "内置组件映射表\nantdv-next 内置支持的组件类型映射。\n每个 key 对应 Field 配置中 `component` 可使用的字符串值，\nvalue 为实际渲染的 antdv-next 组件。"
+    },
     {
       "name": "ComponentMap",
       "type": "interface",
@@ -55,6 +62,13 @@
       "signature": "export type ComponentName =\n  | keyof BaseComponentMap\n  | keyof ComponentMap\n  | 'custom';",
       "description": "组件名称联合类型\n所有支持的组件名称"
     },
+    {
+      "name": "componentMap",
+      "type": "function",
+      "package": "@qin-ui/antdv-next-pro",
+      "signature": "export const componentMap: BaseComponentMap =",
+      "description": "组件名称到 antdv-next 组件的运行时映射\nProForm 通过此映射将 Field 配置中的 component 字符串解析为实际 Vue 组件。\n例如 `component: 'input'` → `Input`, `component: 'select'` → `Select`。"
+    },
     {
       "name": "useFormData",
       "type": "function",
@@ -137,6 +151,20 @@
         "```ts\nconst { formRef, setFormRef } = useFormRef()\nawait formRef.value?.validate()\nformRef.value?.resetFields()\n```"
       ]
     },
+    {
+      "name": "Base",
+      "type": "type",
+      "package": "@qin-ui/antdv-next-pro",
+      "signature": "export type Base<D extends Data = Data> =\n  | BaseWithFields<D>\n  | BaseWithoutFields<D>;",
+      "description": "字段配置的基础公共类型\n定义了 ProForm 字段配置的**保留属性**（由 ProForm 自身消费，不会透传给底层组件）：\n- path, label, component - 字段标识与渲染\n- hidden, disabled, rules - 字段状态与校验\n- span, slots, grid, fields - 布局与嵌套\n- modelProp, valueFormatter - 双向绑定与值转换\n- formItemStyle/Class/Container/DataAttrs - FormItem 容器样式\n- componentStyle/Class/Container/DataAttrs - 输入组件样式\n- extraProps - 自定义扩展属性\n**重要：所有未在此列出的属性将直接 v-bind 透传到底层 antdv-next 组件。**"
+    },
+    {
+      "name": "FieldTypeMap",
+      "type": "type",
+      "package": "@qin-ui/antdv-next-pro",
+      "signature": "export type FieldTypeMap<D extends Data = Data> =",
+      "description": "字段类型映射集合\n将每个 component 字符串映射到其对应的 antdv-next 组件 Props 类型。\n例如 `component: 'select'` 时，Field 获得 Select 组件的所有 Props（options, mode, showSearch 等）作为类型提示。\n`component: 'custom'` 支持通过渲染函数或直接传入 Vue 组件进行完全自定义渲染。"
+    },
     {
       "name": "Field",
       "type": "type",

package/bin/init-ai.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 
 /**
- * @qin-ui/* AI 上下文初始化 CLI 工具
+ * @qin-ui/antdv-next-pro AI 上下文初始化 CLI 工具
  *
- * 遵循 Agentic Collaboration Standard (ACS)，
- * 在消费方项目中自动生成统一的 .agents 规范配置文件。
+ * 在消费方项目中生成分层 AI 上下文文件，使 AI 工具能够：
+ * 1. 理解 @qin-ui/antdv-next-pro 的 Schema 驱动架构
+ * 2. 掌握属性透传规则（何时查阅 antdv-next 文档）
+ * 3. 快速获取完整 API 参考和 antdv-next 查阅指南
  *
  * 用法:
  *   npx @qin-ui/antdv-next-pro init-ai
@@ -28,43 +30,351 @@ const PKG_SHORT = PKG_NAME.replace(/^@qin-ui\//, '');
 
 // ==================== 终端颜色 ====================
 
-const green = (s) => `\x1b[32m${s}\x1b[0m`;
-const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
-const bold = (s) => `\x1b[1m${s}\x1b[0m`;
-const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const green = s => `\x1b[32m${s}\x1b[0m`;
+const cyan = s => `\x1b[36m${s}\x1b[0m`;
+const bold = s => `\x1b[1m${s}\x1b[0m`;
+const yellow = s => `\x1b[33m${s}\x1b[0m`;
+const dim = s => `\x1b[2m${s}\x1b[0m`;
 
-// ==================== 内容生成 ====================
+// ==================== 内容读取 ====================
 
-function getAiContextContent() {
-  const filePath = path.join(PKG_ROOT, 'AI-CONTEXT.md');
+function readPackageFile(filename) {
+  const filePath = path.join(PKG_ROOT, filename);
   if (fs.existsSync(filePath)) {
     return fs.readFileSync(filePath, 'utf-8').trim();
   }
-  return `# ${PKG_NAME}\n\n> 基于 Vue 3 的配置驱动组件库。`;
+  return null;
+}
+
+function getAiContextContent() {
+  return readPackageFile('AI-CONTEXT.md') || `# ${PKG_NAME}\n\n> 基于 Vue 3 的配置驱动组件库。`;
+}
+
+function getReadmeContent() {
+  return readPackageFile('README.md') || '';
+}
+
+function getApiJsonContent() {
+  try {
+    const raw = readPackageFile('api.json');
+    if (!raw) return null;
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
 }
 
-function getUnifiedAgentContent() {
+// ==================== 内容生成 ====================
+
+/**
+ * 生成 rules 文件内容（Instructions 层）
+ * 包含：架构关系、透传规则、反模式、antdv-next 资源链接
+ */
+function getRulesContent() {
   const aiContext = getAiContextContent();
-  const core = [
+
+  return [
+    '---',
+    `description: "${PKG_NAME} 组件库使用规范 — Schema 驱动、属性透传规则"`,
+    'globs: ["**/*.vue", "**/*.ts", "**/*.tsx"]',
+    'alwaysApply: false',
+    '---',
+    '',
     aiContext,
     '',
-    '## 完整 API 参考',
+    '---',
+    '',
+    '## 📌 本地参考文件',
     '',
-    `使用 \`${PKG_NAME}\` 时，请阅读以下文件获取完整的 API 定义、类型签名和使用示例：`,
-    `- \`node_modules/${PKG_NAME}/README.md\` — 详细使用文档和代码示例`,
-    `- \`node_modules/${PKG_NAME}/api.json\` — 结构化 API 元数据（组件、Hook、类型的签名和 JSDoc 示例）`,
+    '本规则文件提供了核心架构和用法指南。需要完整 API 参考时，请阅读以下文件：',
+    '',
+    `- **\`.agents/docs/${PKG_SHORT}-api.md\`** — 完整 API 文档（组件、Hooks、类型、Field 配置参考）`,
+    `- **\`.agents/docs/antdv-next-reference.md\`** — antdv-next 底层组件查阅指南（llms 链接、常用 Props 速查）`,
+    `- **\`node_modules/${PKG_NAME}/api.json\`** — 结构化 API 元数据（函数签名、类型定义）`,
     '',
   ].join('\n');
+}
+
+/**
+ * 生成 API 文档内容（Resources 层）
+ * 从 README.md + api.json 合并提取完整 API 参考
+ */
+function getApiDocContent() {
+  const readme = getReadmeContent();
+  const apiJson = getApiJsonContent();
 
-  // 包含兼容性的 Frontmatter（如 Cursor 支持的 globs 等）
+  const sections = [];
+
+  sections.push(`# ${PKG_NAME} — 完整 API 参考`, '');
+  sections.push(`> 自动生成自 README.md 和 api.json。版本: ${PKG_JSON.version}`, '');
+
+  // README 内容（已包含完整的使用文档）
+  if (readme) {
+    sections.push(readme);
+    sections.push('');
+  }
+
+  // 结构化 API 元数据
+  if (apiJson && apiJson.api && apiJson.api.length > 0) {
+    sections.push('---');
+    sections.push('');
+    sections.push('## 📊 结构化 API 元数据（自动提取自源码 JSDoc）');
+    sections.push('');
+
+    for (const item of apiJson.api) {
+      const typeLabel = {
+        component: '🧩 组件',
+        function: '🔧 函数/Hook',
+        type: '📐 类型',
+        interface: '📋 接口',
+        constant: '📌 常量',
+      }[item.type] || '📄';
+
+      sections.push(`### ${typeLabel} \`${item.name}\``);
+      sections.push('');
+      sections.push(`**类型:** ${item.type}`);
+      if (item.signature) {
+        sections.push('');
+        sections.push('```typescript');
+        sections.push(item.signature);
+        sections.push('```');
+      }
+      if (item.description) {
+        sections.push('');
+        sections.push(item.description);
+      }
+
+      if (item.typeParams && item.typeParams.length > 0) {
+        sections.push('');
+        sections.push('**泛型参数:**');
+        for (const tp of item.typeParams) {
+          const extras = [];
+          if (tp.extends) extras.push(`extends ${tp.extends}`);
+          if (tp.default) extras.push(`默认 ${tp.default}`);
+          const extra = extras.length ? ` (${extras.join(', ')})` : '';
+          sections.push(`- \`${tp.name}\`${extra}`);
+        }
+      }
+
+      if (item.params && item.params.length > 0) {
+        sections.push('');
+        sections.push('**参数:**');
+        sections.push('');
+        sections.push('| 参数名 | 类型 | 可选 | 描述 |');
+        sections.push('| :--- | :--- | :--- | :--- |');
+        for (const p of item.params) {
+          sections.push(`| \`${p.name}\` | \`${p.type}\` | ${p.optional ? '是' : '否'} | ${p.description} |`);
+        }
+      }
+
+      if (item.returns) {
+        sections.push('');
+        sections.push(`**返回值:** ${item.returns}`);
+      }
+
+      if (item.examples && item.examples.length > 0) {
+        sections.push('');
+        sections.push('**示例:**');
+        for (const ex of item.examples) {
+          sections.push('');
+          sections.push(ex);
+        }
+      }
+
+      sections.push('');
+      sections.push('---');
+      sections.push('');
+    }
+  }
+
+  return sections.join('\n');
+}
+
+/**
+ * 生成 antdv-next 查阅指南（Reference 层）
+ * 说明底层组件关系 + llms 资源 + 常用 Props 速查
+ */
+function getAntdvReferenceContent() {
   return [
+    '# antdv-next 底层组件查阅指南',
+    '',
+    `> ${PKG_NAME} 基于 **antdv-next**（Vue 3 组件库，对齐 Ant Design 设计规范）封装。`,
+    '> 所有在 Field 配置中编写的非保留属性，会经过 Grid→Col / FormItem→a-form-item 逐层剥离后，剩余属性透传给输入控件。',
+    '',
     '---',
-    `description: "${PKG_NAME} 组件库使用规范"`,
-    'globs: ["**/*.vue", "**/*.ts", "**/*.tsx"]',
-    'alwaysApply: false',
+    '',
+    '## 1. antdv-next 与 @qin-ui/antdv-next-pro 的关系',
+    '',
+    `${PKG_NAME} 是 **Schema 驱动渲染引擎**，antdv-next 是 **UI 组件实现**。`,
+    `查阅底层组件 API 时，请使用 antdv-next 官方文档（见第 2 节），而非 ant-design-vue 文档。`,
+    '',
+    'Field 配置中的属性通过两阶段分流：',
+    '',
+    '**第一阶段（GroupedFieldAttrs）：**',
+    '- 显式解构消费：path, fields, hidden, span, slots, formItemStyle/Class/Container 等',
+    '- 剩余属性按 key 名匹配：',
+    '  - 命中 antdv-next Col props → gridItemProps → `<a-col>`',
+    '  - 命中 antdv-next FormItem props → formItemProps → `<a-form-item>`',
+    '  - 其余 → componentProps → BaseField',
+    '',
+    '**第二阶段（BaseField）：**',
+    '- 解构消费：valueFormatter, modelProp, componentStyle/Class/Container, slots',
+    '- v-model 绑定消费：modelBindingProp + onUpdate 回调',
+    '- 其余（包括 disabled）→ v-bind 到输入组件',
+    '',
+    `例如 \`{ path:'city', component:'select', label:'城市', span:8, placeholder:'选择', options:[...] }\`：`,
+    `- span → 命中 Col props → \`<a-col :span="8">\``,
+    `- label → 命中 FormItem props → \`<a-form-item label="城市">\``,
+    `- placeholder, options → 均未命中 Col/FormItem props → BaseField → \`<a-select>\``,
+    '',
+    '**关键规则：编写 Field 属性前，务必查阅 antdv-next 文档确认属性的正确名称和所属组件。**',
+    '',
+    '---',
+    '',
+    '## 2. antdv-next 文档资源',
+    '',
+    '### 在线文档（AI 可直接 fetch）',
+    '',
+    '| 资源 | URL | 内容 |',
+    '|:--|:--|:--|',
+    '| llms.txt | https://antdv-next.com/llms.txt | 文档索引（轻量） |',
+    '| llms-full-cn.txt | https://antdv-next.com/llms-full-cn.txt | **完整组件 API 文档（中文）** |',
+    '| llms-semantic-cn.md | https://antdv-next.com/llms-semantic-cn.md | 组件语义化 DOM 结构 |',
+    '',
+    '### Agent Skills（推荐安装）',
+    '',
+    '```bash',
+    'npx skills add antdv-next/skills',
+    '```',
+    '',
+    '安装后 AI 获得三级按需加载能力：',
+    '- Level 1 (~100 tokens): 始终加载的元数据',
+    '- Level 2 (<5k tokens): 触发时加载的组件使用指南',
+    '- Level 3 (按需): 完整组件 API 文档',
+    '',
     '---',
     '',
-    core,
+    '## 3. 常用透传属性速查',
+    '',
+    '> ⚠️ 以下仅为高频使用的属性速查表，**并非完整列表**。',
+    '> 完整属性列表请查阅 [llms-full-cn.txt](https://antdv-next.com/llms-full-cn.txt)。',
+    '',
+    '### Input 系列 (input / textarea / input-password / input-search)',
+    '',
+    '| 属性 | 类型 | 说明 |',
+    '|:--|:--|:--|',
+    '| placeholder | string | 占位文本 |',
+    '| maxlength | number | 最大字符数 |',
+    '| allowClear | boolean | 是否显示清除按钮 |',
+    '| showCount | boolean | 是否显示字数统计 |',
+    '| addonBefore | string\\|slot | 前置标签 |',
+    '| addonAfter | string\\|slot | 后置标签 |',
+    '| prefix | string\\|slot | 前缀图标 |',
+    '| suffix | string\\|slot | 后缀图标 |',
+    '',
+    '### Select',
+    '',
+    '| 属性 | 类型 | 说明 |',
+    '|:--|:--|:--|',
+    '| options | {label,value}[] | 选项数据 |',
+    '| mode | \'multiple\'\\|\'tags\' | 选择模式 |',
+    '| showSearch | boolean | 是否支持搜索 |',
+    '| filterOption | function | 自定义过滤逻辑 |',
+    '| allowClear | boolean | 是否显示清除按钮 |',
+    '| maxTagCount | number | 最多显示标签数 |',
+    '| loading | boolean | 加载状态 |',
+    '| bordered | boolean | 是否有边框 |',
+    '',
+    '### DatePicker / RangePicker',
+    '',
+    '| 属性 | 类型 | 说明 |',
+    '|:--|:--|:--|',
+    '| picker | \'date\'\\|\'week\'\\|\'month\'\\|\'year\' | 选择器类型 (DatePicker) |',
+    '| format | string | 日期格式 |',
+    '| valueFormat | string | 值格式 |',
+    '| showTime | boolean\\|object | 是否显示时间选择 |',
+    '| disabledDate | function | 禁用日期 |',
+    '| allowClear | boolean | 是否显示清除按钮 |',
+    '',
+    '### InputNumber',
+    '',
+    '| 属性 | 类型 | 说明 |',
+    '|:--|:--|:--|',
+    '| min | number | 最小值 |',
+    '| max | number | 最大值 |',
+    '| step | number | 步长 |',
+    '| precision | number | 小数精度 |',
+    '| formatter | function | 格式化函数 |',
+    '| parser | function | 解析函数 |',
+    '',
+    '### Switch',
+    '',
+    '| 属性 | 类型 | 说明 |',
+    '|:--|:--|:--|',
+    '| checkedChildren | string\\|slot | 选中时内容 |',
+    '| unCheckedChildren | string\\|slot | 非选中时内容 |',
+    '| loading | boolean | 加载状态 |',
+    '| size | \'default\'\\|\'small\' | 尺寸 |',
+    '',
+    `> ⚠️ Switch 的 v-model 绑定属性是 \`checked\` 而非 \`value\`。`,
+    `> **但 ${PKG_NAME} 的 ProComponentProvider 已为 switch 预设了 \`modelProp: 'checked'\`，因此 Field 中通常无需手动指定。**`,
+    '',
+    '### Cascader',
+    '',
+    '| 属性 | 类型 | 说明 |',
+    '|:--|:--|:--|',
+    '| options | CascaderOption[] | 级联选项 |',
+    '| fieldNames | object | 自定义字段名 |',
+    '| showSearch | boolean | 是否支持搜索 |',
+    '| allowClear | boolean | 是否显示清除按钮 |',
+    '| expandTrigger | \'click\'\\|\'hover\' | 展开触发方式 |',
+    '',
+    '### TreeSelect',
+    '',
+    '| 属性 | 类型 | 说明 |',
+    '|:--|:--|:--|',
+    '| treeData | TreeNode[] | 树形数据 |',
+    '| showSearch | boolean | 是否支持搜索 |',
+    '| allowClear | boolean | 是否显示清除按钮 |',
+    '| treeCheckable | boolean | 是否显示复选框 |',
+    '| fieldNames | object | 自定义字段名 |',
+    '',
+    '### RadioGroup / CheckboxGroup',
+    '',
+    '| 属性 | 类型 | 说明 |',
+    '|:--|:--|:--|',
+    '| options | {label,value}[] | 选项数据 |',
+    '| direction | \'horizontal\'\\|\'vertical\' | 排列方向 (RadioGroup) |',
+    '| buttonStyle | \'outline\'\\|\'solid\' | 按钮样式 (RadioGroup) |',
+    '',
+    '---',
+    '',
+    '## 4. ProTable Column 属性（继承 antdv-next ColumnType）',
+    '',
+    `${PKG_NAME} 的 Column 类型继承自 antdv-next 的 ColumnType，支持所有原生列属性：`,
+    '',
+    '| 常用属性 | 类型 | 说明 |',
+    '|:--|:--|:--|',
+    '| dataIndex | Path<D> | 列数据字段路径（类型安全） |',
+    '| title | string | 列标题 |',
+    '| width | number\\|string | 列宽 |',
+    '| fixed | \'left\'\\|\'right\' | 固定列 |',
+    '| align | \'left\'\\|\'center\'\\|\'right\' | 对齐方式 |',
+    '| sorter | boolean\\|function | 排序 |',
+    '| customRender | function | 自定义渲染（antdv-next 中取代 slots） |',
+    '| hidden | boolean | 列显隐（@qin-ui 扩展属性） |',
+    '',
+    '> 更多属性查阅 [antdv-next Table 文档](https://antdv-next.com/llms-full-cn.txt)',
+    '',
+    '---',
+    '',
+    '## 5. 组件语义化 DOM 结构',
+    '',
+    'antdv-next 的每个组件都有明确的语义化 DOM 结构（如 `root`、`content`、`icon`、`popup` 等），',
+    '方便通过 CSS class 或 componentVars 进行精准样式覆盖。',
+    '',
+    '完整语义描述查阅：[llms-semantic-cn.md](https://antdv-next.com/llms-semantic-cn.md)',
+    '',
   ].join('\n');
 }
 
@@ -76,31 +386,44 @@ function ensureDir(dirPath) {
   }
 }
 
+function writeFileWithLog(filePath, content, label) {
+  const dir = path.dirname(filePath);
+  ensureDir(dir);
+  const existed = fs.existsSync(filePath);
+  fs.writeFileSync(filePath, content, 'utf-8');
+  const status = existed ? yellow('[更新]') : green('[创建]');
+  console.log(`  ${status} ${cyan(label)}`);
+}
+
 // ==================== CLI 入口 ====================
 
 function printHelp() {
   console.log(`
-${bold(`${PKG_NAME} CLI`)}
+${bold(`${PKG_NAME} CLI — AI 上下文初始化`)}
 
 ${bold('用法:')}
   npx ${PKG_NAME} init-ai
 
-${bold('命令:')}
-  init-ai    在当前项目中生成统一的 .agents 规范配置文件
+${bold('说明:')}
+  在项目中生成分层 AI 上下文文件，使 AI 工具能够深度理解和规范使用 ${PKG_NAME}。
+
+  生成的文件结构：
+    .agents/
+      rules/
+        ${PKG_SHORT}.md         规则文件（架构、透传规则、反模式）
+      docs/
+        ${PKG_SHORT}-api.md     API 参考（完整文档 + 结构化元数据）
+        antdv-next-reference.md antdv-next 底层组件查阅指南
 
 ${bold('选项:')}
   --help     显示帮助信息
-
-${bold('说明:')}
-  该命令将采用统一的 Agentic 标准，在项目的 .agents/rules/ 目录下
-  生成上下文文件。兼容支持读取 .agents 的主流 AI IDE 和 CLI 工具。
 `);
 }
 
 function main() {
   const args = process.argv.slice(2);
-  const subcommand = args.find((a) => !a.startsWith('-'));
-  const flags = args.filter((a) => a.startsWith('-'));
+  const subcommand = args.find(a => !a.startsWith('-'));
+  const flags = args.filter(a => a.startsWith('-'));
 
   if (!subcommand || flags.includes('--help') || flags.includes('-h')) {
     printHelp();
@@ -108,35 +431,67 @@ function main() {
   }
 
   if (subcommand !== 'init-ai') {
-    console.error(red(`\n  未知命令: ${subcommand}\n`));
+    console.error(`\n  ❌ 未知命令: ${subcommand}\n`);
     printHelp();
     process.exit(1);
   }
 
   console.log('');
-  console.log(bold(`📦 ${PKG_NAME} — AI 上下文初始化 (ACS 标准)`));
+  console.log(bold(`📦 ${PKG_NAME} — AI 上下文初始化 v${PKG_JSON.version}`));
+  console.log(dim(`   基于 antdv-next 的 Schema 驱动组件库`));
   console.log('');
-  
-  const content = getUnifiedAgentContent();
-  const dirPath = '.agents/rules';
-  const fileName = `${PKG_SHORT}.md`;
-  
-  const fullDir = path.join(process.cwd(), dirPath);
-  const fullPath = path.join(fullDir, fileName);
 
-  ensureDir(fullDir);
-  fs.writeFileSync(fullPath, content, 'utf-8');
+  // 1. 生成 Rules 文件
+  console.log(bold('📋 规则层 (Rules)'));
+  const rulesContent = getRulesContent();
+  writeFileWithLog(
+    path.join(process.cwd(), '.agents/rules', `${PKG_SHORT}.md`),
+    rulesContent,
+    `.agents/rules/${PKG_SHORT}.md`
+  );
+  console.log(dim('   → 架构概览、属性透传决策树、渐进用法、反模式'));
+  console.log('');
 
-  const relPath = path.join(dirPath, fileName);
-  console.log(`  ${green('✔')} ${cyan(relPath)}  ${green('[created/updated]')}`);
+  // 2. 生成 API 文档
+  console.log(bold('📖 参考层 (Docs)'));
+  const apiDocContent = getApiDocContent();
+  writeFileWithLog(
+    path.join(process.cwd(), '.agents/docs', `${PKG_SHORT}-api.md`),
+    apiDocContent,
+    `.agents/docs/${PKG_SHORT}-api.md`
+  );
+  console.log(dim('   → 完整 README 文档 + 结构化 API 元数据'));
+  console.log('');
 
+  // 3. 生成 antdv-next 查阅指南
+  const refContent = getAntdvReferenceContent();
+  writeFileWithLog(
+    path.join(process.cwd(), '.agents/docs', 'antdv-next-reference.md'),
+    refContent,
+    '.agents/docs/antdv-next-reference.md'
+  );
+  console.log(dim('   → antdv-next 关系说明、llms 资源链接、常用透传属性速查'));
   console.log('');
-  console.log(green('✅ 完成！已生成统一标准规则文件。'));
+
+  // 4. 完成提示
+  console.log(green('✅ 完成！已生成分层 AI 上下文文件。'));
+  console.log('');
+  console.log(`${bold('📂 生成的文件:')}`);
+  console.log(`   ${cyan('.agents/')}`);
+  console.log(`   ├── ${cyan('rules/')}`);
+  console.log(`   │   └── ${cyan(PKG_SHORT + '.md')}            ${dim('← 核心规则（AI 优先读取）')}`);
+  console.log(`   └── ${cyan('docs/')}`);
+  console.log(`       ├── ${cyan(PKG_SHORT + '-api.md')}        ${dim('← 完整 API 参考')}`);
+  console.log(`       └── ${cyan('antdv-next-reference.md')} ${dim('← antdv-next 查阅指南')}`);
+  console.log('');
+
+  console.log(`${bold('🔄 建议的下一步:')}`);
+  console.log(`   1. 提交 ${cyan('.agents/')} 目录到 Git 仓库，团队共享`);
+  console.log(`   2. ${bold('安装 antdv-next Agent Skills')}（强烈推荐）：`);
+  console.log(`      ${cyan('npx skills add antdv-next/skills')}`);
+  console.log(`   3. ${dim('（可选）下载 antdv-next 完整文档到本地：')}`);
+  console.log(`      ${dim('curl -o .agents/docs/antdv-next-full.txt https://antdv-next.com/llms-full-cn.txt')}`);
   console.log('');
-  console.log(`${bold('下一步:')}`);
-  console.log(
-    `  将 ${cyan(dirPath)} 目录提交到 Git，团队即可自动享受 AI 增强\n`
-  );
 }
 
 main();

package/es/index.d.ts

@@ -129,7 +129,19 @@ declare type AllowStringKey<T, Prefix extends string = ''> = {
 } extends infer Obj ? Obj[keyof Obj] : never;
 
 /**
- * @type {Object} Base - 基础公共字段类型
+ * 字段配置的基础公共类型
+ * @description 定义了 ProForm 字段配置的**保留属性**（由 ProForm 自身消费，不会透传给底层组件）：
+ * - path, label, component - 字段标识与渲染
+ * - hidden, disabled, rules - 字段状态与校验
+ * - span, slots, grid, fields - 布局与嵌套
+ * - modelProp, valueFormatter - 双向绑定与值转换
+ * - formItemStyle/Class/Container/DataAttrs - FormItem 容器样式
+ * - componentStyle/Class/Container/DataAttrs - 输入组件样式
+ * - extraProps - 自定义扩展属性
+ *
+ * **重要：所有未在此列出的属性将直接 v-bind 透传到底层 antdv-next 组件。**
+ *
+ * @public
  */
 declare type Base<D extends Data = Data> = BaseWithFields<D> | BaseWithoutFields<D>;
 
@@ -237,7 +249,11 @@ declare type BaseCommon<D extends Data = Data> = {
 
 /**
  * 内置组件映射表
- * @description antdv-next 内置支持的组件类型映射
+ * @description antdv-next 内置支持的组件类型映射。
+ * 每个 key 对应 Field 配置中 `component` 可使用的字符串值，
+ * value 为实际渲染的 antdv-next 组件。
+ *
+ * @public
  */
 declare type BaseComponentMap = {
     'input': typeof Input;
@@ -724,7 +740,12 @@ declare type FieldFindBy<D extends Data, F extends BaseField<D> = BaseField<D>>
 export declare type Fields<D extends Data = Data> = Array<Field<ComponentName, D>>;
 
 /**
- * @type {FieldTypeMap} 字段类型集合
+ * 字段类型映射集合
+ * @description 将每个 component 字符串映射到其对应的 antdv-next 组件 Props 类型。
+ * 例如 `component: 'select'` 时，Field 获得 Select 组件的所有 Props（options, mode, showSearch 等）作为类型提示。
+ * `component: 'custom'` 支持通过渲染函数或直接传入 Vue 组件进行完全自定义渲染。
+ *
+ * @public
  */
 declare type FieldTypeMap<D extends Data = Data> = {
     [K in ComponentName]: K extends 'custom' ? WithCommon<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qin-ui/antdv-next-pro",
-  "version": "1.1.14",
+  "version": "1.1.15",
   "description": "基于 antdv-next 的二次封装组件",
   "bin": {
     "antdv-next-pro": "./bin/init-ai.mjs"