@qin-ui/antd-vue-pro 2.2.1 → 2.2.3

package/AI-CONTEXT.md

@@ -1,150 +1,194 @@
-# @qin-ui/antd-vue-pro — AI Context
+# @qin-ui/antd-vue-pro
 
-> Schema-driven component library wrapping **ant-design-vue v4** (`a-` prefix). Describe UIs as JS objects instead of template tag soup.
+基于 ant-design-vue v4（`a-` 前缀）封装的 Schema 驱动组件库。
+用 JS 配置对象描述 UI，不写 `<a-*>` 模板堆叠。ProForm/ProTable 是渲染引擎，所有真实 UI 来自 ant-design-vue。
 
----
-
-## 1. Architecture
-
-### 1.1 Three-layer rendering
+## 安装与注册
 
+```bash
+pnpm add @qin-ui/antd-vue-pro   # peerDeps: ant-design-vue ^4, vue ^3.5
 ```
-Field[] config layer       { path:'name', component:'input', span:8, label:'Name', placeholder:'...' }
-        │
-@qin-ui/antd-vue-pro       Schema parser — strips props layer by layer
-        │
-ant-design-vue v4          a-input / a-select / a-table / a-form-item / a-col  ...
-```
-
-ProForm/ProTable are **rendering engines**, not a component library. All actual UI comes from ant-design-vue. Field props are peeled off and dispatched to different DOM layers.
 
-### 1.2 Component resolution
-
-`Field.component` string → `componentMap` → ant-design-vue component.
-
-If not found in the built-in map, the string is resolved against `ProComponentProvider` injected components; a Vue component object is rendered directly (used by `'custom'` internally).
-
-### 1.3 Built-in component map
+```ts
+import AntdVuePro from '@qin-ui/antd-vue-pro';
+import '@qin-ui/antd-vue-pro/antd-vue-pro.css';
+app.use(AntdVuePro); // 全局注册 ProForm / ProTable / ProComponentProvider
+```
 
-| Field `component`  | ant-design-vue component | Key pass-through props (verify against https://antdv.com)                              |
-| :----------------- | :----------------------- | :------------------------------------------------------------------------------------- |
-| `'input'`          | Input                    | placeholder, maxlength, allowClear, addonBefore, addonAfter, prefix, suffix, showCount |
-| `'textarea'`       | TextArea                 | rows, maxlength, showCount, autoSize                                                   |
-| `'input-password'` | InputPassword            | placeholder, maxlength, visibilityToggle                                               |
-| `'input-search'`   | InputSearch              | placeholder, loading, onSearch                                                         |
-| `'input-number'`   | InputNumber              | min, max, step, precision, formatter, parser                                           |
-| `'select'`         | Select                   | **options**, mode, showSearch, filterOption, allowClear, loading                       |
-| `'cascader'`       | Cascader                 | **options**, fieldNames, showSearch, allowClear                                        |
-| `'date-picker'`    | DatePicker               | picker, format, showTime, disabledDate, valueFormat                                    |
-| `'range-picker'`   | RangePicker              | format, showTime, disabledDate, allowClear                                             |
-| `'time-picker'`    | TimePicker               | format, showSecond, hourStep, minuteStep                                               |
-| `'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, fieldNames                                    |
-| `'transfer'`       | Transfer                 | **dataSource**, **titles**, **targetKeys**, showSearch, render                         |
-| `'custom'`         | (user-supplied)          | component receives a Vue component or `h()` render function                            |
+## 两条核心心智模型
 
-> The prop column is illustrative. **Always verify prop names/types against [antdv.com](https://antdv.com).**
+**1. 配置驱动**：`useForm(数据, Field[])` / `useTable({ columns, searchFields })` 生成实例，组件接收实例。
 
----
+**2. 属性分层透传**（最关键）：Field 上的属性被"剥离到不同 DOM 层"，不是全塞给输入控件。写错层就失效：
 
-## 2. Property layering (core rule)
+| 属性                                                                                                                                                                                                    | 落到哪一层                       | 说明           |
+| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------- | :------------- |
+| `span`/`offset`/`push`/`pull`/`flex`/`xs..xxl`                                                                                                                                                          | `<a-col>` Grid 层                | 仅 grid 开启时 |
+| `label`/`rules`/`tooltip`/`colon`/`labelAlign`/`labelCol`/`wrapperCol`/`extra`/`help`/`validateFirst`/`validateTrigger`/`valuePropName`/`normalize`/`formItemClass`/`formItemStyle`/`formItemDataAttrs` | `<a-form-item>` 层               | 表单项         |
+| `disabled`/`placeholder`/`allowClear`/`options`/`mode`/`maxlength`/`componentClass`/`componentStyle`/`componentDataAttrs` + 该控件其余 ant 原生属性                                                     | 输入控件本身（a-input 等）       | 其余全部       |
+| `component`/`hidden`/`modelProp`/`valueFormatter`/`fields`/`slots`/`formItemContainer`/`componentContainer`/`extraProps`                                                                                | ProForm 逻辑消费，**不绑到 DOM** | 框架级         |
 
-Field props are **stripped in layers** and dispatched to different DOM targets.
+> 规则：`span` 给 Grid，`label`/`rules` 给 FormItem，其余给输入控件。
 
-```
-<a-col :span="8">                   ← Grid layer
-  <a-form-item label="City">        ← FormItem layer
-    <a-select placeholder="..." />  ← Input-control layer
-  </a-form-item>
-</a-col>
-```
+## component 映射（Field.component 字符串 -> ant-design-vue 组件）
 
-### 2.1 Layer dispatch
+`input`->Input · `textarea`->TextArea · `input-password`->InputPassword · `input-search`->InputSearch ·
+`input-number`->InputNumber · `select`->Select · `cascader`->Cascader · `date-picker`->DatePicker ·
+`range-picker`->RangePicker · `time-picker`->TimePicker · `checkbox-group`->CheckboxGroup ·
+`radio-group`->RadioGroup · `switch`->Switch · `slider`->Slider · `tree-select`->TreeSelect ·
+`transfer`->Transfer · `custom`->用户自定义组件
 
-**Grid layer → `<a-col>`** (only when grid is enabled):
-`span`, `order`, `offset`, `push`, `pull`, `flex`, `xs`, `sm`, `md`, `lg`, `xl`, `xxl`
+> 写 Field 中输入控件的具体属性前，**属性名/类型以 https://antdv.com 官方文档为准**。
 
-**FormItem layer → `<a-form-item>`**:
-`label`, `rules`, `colon`, `labelAlign`, `labelCol`, `wrapperCol`, `tooltip`, `extra`, `help`, `validateFirst`, `validateTrigger`, `valuePropName`, `normalize`, `formItemClass`→`class`, `formItemStyle`→`style`, `formItemContainer`, `formItemDataAttrs`→`data-*`
+## 隐式默认行为（INJECT_CONFIG，易踩坑）
 
-**Input-control layer → the input component** (everything else):
-`disabled`, `placeholder`, `allowClear`, `options`, `showSearch`, `maxlength`, `mode`, `componentClass`→`class`, `componentStyle`→`style`, `componentDataAttrs`→`data-*`, and any ant-design-vue props for that component.
+由 `ProComponentProvider` 注入，优先级低于 Field 配置。**不写也有这些默认值，需知晓以免行为与预期不符：**
 
-**Consumed by ProForm logic, not bound to DOM**: `component`, `fields`, `hidden`, `slots`, `modelProp`, `valueFormatter`, `componentContainer`, `extraProps`.
+| component                                      | 默认预设                                                                                                                                                                                          |
+| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `switch`                                       | `{ modelProp: 'checked' }` -> v-model 绑 `checked` 而非 `value`                                                                                                                                   |
+| `input` / `input-password`                     | `{ maxlength: 100, allowClear: true, placeholder: '请输入' }`                                                                                                                                     |
+| `textarea`                                     | `{ maxlength: 200, autoSize: {minRows:3,maxRows:6}, showCount: true, allowClear: true, placeholder: '请输入' }`                                                                                   |
+| `input-number`                                 | `{ max: 1e15-1, min: -(1e15+1), controls: false, placeholder: '请输入', style:{width:'100%'} }`                                                                                                   |
+| `select` / `cascader`                          | `{ allowClear: true, placeholder: '请选择', getPopupContainer }`                                                                                                                                  |
+| `date-picker` / `range-picker` / `time-picker` | `{ allowClear: true, getPopupContainer, style:{width:'100%'} }`                                                                                                                                   |
+| `pro-form`                                     | `{ grid: { gutter: {xs:8, sm:16, md:16, lg:24} } }`                                                                                                                                               |
+| `pro-form-item`                                | `{ validateFirst: true, span: 8 }`                                                                                                                                                                |
+| `pro-table`                                    | `{ pagination:{showTotal, showSizeChanger, pageSizeOptions:['10'..'100'], showQuickJumper:true}, searchFormConfig:{layout:'grid', expand:{minExpandRows:2}}, control:true, addIndexColumn:true }` |
 
-### 2.2 modelProp
+> `modelProp` 控制 v-model 绑定名，默认 `'value'`->`v-model:value`。
 
-Controls the `v-model:xxx` binding name.
+## useForm -- 表单实例
 
-- Default: `modelProp: 'value'` → `v-model:value`
-- Switch uses `checked` — **ProComponentProvider presets `modelProp: 'checked'` for `'switch'`** so you rarely set it manually.
-- Override per-field when using a custom component that expects a different v-model prop.
+```ts
+// 重载一（常用）：初始数据 + 字段配置
+const form = useForm<User>(
+  { name: '张三', age: 25 }, // initFormData
+  [
+    {
+      path: 'name',
+      label: '姓名',
+      component: 'input',
+      rules: [{ required: true }],
+    },
+  ] // Field[]
+);
+// 重载二：仅拿实例（root=true/false）
+const form = useForm<User>(true);
+```
 
----
+返回 `Form` 实例（**2.0+ `formData` 是 reactive 对象，不用 `.value`**）：
 
-## 3. Progressive usage
+| 成员                                                                                  | 说明                                                                                         |
+| :------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------- |
+| `form.formData`                                                                       | 响应式数据，可直接读写，支持深层路径 `formData.address.city`                                 |
+| `form.getFormData(path)` / `form.setFormData(path, value)`                            | 路径读写；setFormData 还支持 `setFormData(path, prev=>new)` 和 `setFormData({...})` 批量覆盖 |
+| `form.fields`                                                                         | 字段配置数组（Ref）                                                                          |
+| `form.getField(path)` / `form.setField(path, patch)`                                  | 字段增改查；setField 默认合并，`{updateType:'rewrite'}` 覆盖                                 |
+| `form.deleteField` / `form.appendField` / `form.prependField` / `form.getParentField` | 字段增删                                                                                     |
+| `form.formRef`                                                                        | 底层 ant Form 实例引用（Ref），`formRef.value?.validate()` / `.resetFields()`                |
 
-### Level 1: Config-driven (no hand-written a-\* tags)
+## ProForm 最小示例
 
-```ts
+```vue
+<script setup lang="ts">
 import { ProForm, useForm } from '@qin-ui/antd-vue-pro';
-
-const form = useForm({ username: '', password: '' }, [
+interface User {
+  username: string;
+  age: number;
+  gender: string;
+}
+const form = useForm<User>({ username: '', age: 18, gender: 'male' }, [
   {
     path: 'username',
     component: 'input',
     label: '用户名',
-    placeholder: '请输入',
     rules: [{ required: true }],
   },
+  { path: 'age', component: 'input-number', label: '年龄', min: 1, max: 150 },
   {
-    path: 'password',
-    component: 'input-password',
-    label: '密码',
-    placeholder: '请输入',
-    rules: [{ required: true }],
+    path: 'gender',
+    component: 'select',
+    label: '性别',
+    options: [
+      { label: '男', value: 'male' },
+      { label: '女', value: 'female' },
+    ],
   },
 ]);
+const submit = async () => {
+  await form.formRef.value?.validate();
+  console.log(form.formData);
+};
+</script>
+<template>
+  <ProForm :form="form" />
+  <a-button type="primary" @click="submit">提交</a-button>
+</template>
 ```
 
-```html
-<ProForm :form="form" />
-```
-
-### Level 2: Field linkage
+## 自定义组件（4 种方式）
 
-Control props (`disabled`, `hidden`, `rules`, etc.) support three reactivity patterns:
+`Field.component` 的解析优先级（高 -> 低）：
+`teleport 插槽注入` > `ProComponentProvider.componentMap` > `内置 componentMap` > `原始 component 值`
 
-```ts
-// A) computed() — declarative, for linkages known at init (preferred)
-disabled: computed(() => !form.formData.enabled),
-rules: computed(() => [{ required: form.formData.hasLimit, message: '必填' }]),
+### 方式 1：传入 SFC 单文件组件对象（推荐，单字段最常用）
 
-// B) ref() — external shared state
-const isDisabled = ref(false);
+`component` 直接传组件对象，**必须用 `markRaw` 包裹**。
 
-// C) setField() — imperative, for event-driven changes
-form.setField('limitCount', { disabled: true });
+```ts
+import { markRaw } from 'vue';
+import MyInput from './MyInput.vue';
+{ path: 'code', label: '验证码', component: markRaw(MyInput) }
 ```
 
-**Rule: pick the simplest. computed() for init-time, setField() for runtime events, ref() for external state.**
+> ⚠️ **必须 markRaw**：不包会被 Vue 当成响应式对象深度代理，触发性能警告甚至渲染异常。
+> 类型上 `component` 接受 `RenderComponentType | Raw<RenderComponentType>`，`Raw<T>` 即 markRaw 的类型标记。
+> 此字段不支持响应式（不能包 ref/computed）。
 
-### Level 3: Custom component
+### 方式 2：传入 render 函数（单字段，需动态拼装 props 时）
+
+`component` 传 `(props, ctx) => VNode`。`props` 含 v-model 绑定值与 path，`ctx.attrs` 含透传属性。
 
 ```ts
 import { h } from 'vue';
-import CustomInput from './CustomInput.vue';
+import MyInput from './MyInput.vue';
+{ path: 'code', label: '验证码', component: (p, ctx) => h(MyInput, { ...p, ...ctx.attrs }) }
+```
+
+### 方式 3：ProComponentProvider 注入 componentMap（全局复用，推荐多字段场景）
+
+在根用 `componentMap` 注册，Field 里用字符串引用。**可覆盖内置组件**（如 `input: MyInput` 替换全局 input）。
 
-// In field config:
-{ path: 'key', component: (p, ctx) => h(CustomInput, { ...p, ...ctx.attrs }) }
+```vue
+<script setup lang="ts">
+import { ProComponentProvider } from '@qin-ui/antd-vue-pro';
+import MyRichTextEditor from './components/MyRichTextEditor.vue';
+const componentMap = { 'rich-editor': MyRichTextEditor };
+</script>
+<template>
+  <ProComponentProvider :component-map="componentMap">
+    <ProForm :form="form" />
+  </ProComponentProvider>
+</template>
 ```
 
-Or via scoped slot in template (all binding params forwarded via `v-bind="scoped"`):
+**追加全局声明获取强类型补全**（项目任意 `.d.ts`）：
 
-```html
+```ts
+declare module '@qin-ui/antd-vue-pro' {
+  interface ComponentMap {
+    'rich-editor': typeof MyRichTextEditor;
+  }
+}
+// 之后 component: 'rich-editor' 即获精准属性类型联想
+```
+
+### 方式 4：模板 scoped slot（声明式，简单替换）
+
+插槽名 = 字段 `path`，绑定参数通过 `v-bind="scoped"` 转发（teleport 机制，优先级最高）。
+
+```vue
 <ProForm :form="form">
   <template #agreement="scoped">
     <a-checkbox v-bind="scoped">同意协议</a-checkbox>
@@ -152,85 +196,142 @@ Or via scoped slot in template (all binding params forwarded via `v-bind="scoped
 </ProForm>
 ```
 
----
+### 选择建议
 
-## 4. Anti-patterns
+- 单字段复用一个 SFC -> 方式 1（markRaw(SFC)）
+- 单字段、需动态拼装 props -> 方式 2（render 函数）
+- 多处复用 / 替换内置组件 -> 方式 3（componentMap + 声明扩充）
+- 简单声明式替换、不想写 h() -> 方式 4（scoped slot）
 
-- **Never hand-write `<a-form-item>` inside `<ProForm>`.** ProForm renders FormItems from Field config automatically.
-- **Never guess pass-through prop names.** Verify against [ant-design-vue docs](https://antdv.com).
-- **Don't confuse Grid props with input props.** `span` goes to `<a-col>`, not the input.
-- **Use `computed()` for reactive Field configs.** Plain values won't track dependencies.
-- **Prefer the simplest linkage pattern.** Don't use `setField()` when `computed()` suffices.
+### 自定义组件需遵守的约定
 
----
+- **v-model**：默认绑 `value`（`v-model:value`）。若组件用别的 prop（如 Switch 用 `checked`），通过字段 `modelProp` 指定，或在 componentVars 预设 `modelProp`
+- **接收 path**：组件会收到 `path` prop（字段路径）
+- **属性透传**：Field 上除框架级属性外（component/hidden/modelProp/valueFormatter/fields/slots/formItemContainer/componentContainer/extraProps 等），其余作为 attrs 透传给自定义组件
 
-## 5. ProComponentProvider — global defaults
+## valueFormatter -- 字段值转换
 
-Wrap your app to set defaults for all ProForm/ProTable instances. Merged with priority (highest first):
+控制表单值与组件值之间的转换（如日期 dayjs 与字符串互转）。**在 onUpdate:前执行**，支持两种形态：
 
-1. **Field-level config** (always wins)
-2. **`componentVars`** passed to ProComponentProvider
-3. **`INJECT_CONFIG`** built-in presets
+```ts
+// 函数形态：(新值, 旧值) => 转换后的值，写回 formData
+{ path: 'name', valueFormatter: (val, oldVal) => val?.trim() }
+
+// 对象形态：get 读出时转换，set 写入时转换
+{ path: 'birthday', component: 'date-picker',
+  valueFormatter: {
+    get: (val) => val ? dayjs(val) : null,      // formData -> 组件显示
+    set: (val) => val ? dayjs(val).format('YYYY-MM-DD') : null,  // 组件 -> formData
+  } }
+```
 
-### Built-in presets (INJECT_CONFIG)
+## useTable -- 表格实例
 
-| Component                                      | Preset                                                                                                                                  |
-| :--------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
-| `switch`                                       | `{ modelProp: 'checked' }`                                                                                                              |
-| `input`                                        | `{ maxlength: 100, allowClear: true, placeholder: '请输入' }`                                                                           |
-| `textarea`                                     | `{ maxlength: 200, autoSize: {minRows:3,maxRows:6}, showCount: true, allowClear: true, placeholder: '请输入' }`                         |
-| `select` / `cascader`                          | `{ allowClear: true, placeholder: '请选择', getPopupContainer }`                                                                        |
-| `input-number`                                 | `{ max: 10^15, min: -(10^15), controls: false, placeholder: '请输入', style: {width:'100%'} }`                                          |
-| `date-picker` / `range-picker` / `time-picker` | `{ 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 }`                                                                                                      |
+```ts
+const table = useTable<SearchParams, User>({
+  columns: [{ dataIndex: 'name', title: '姓名', width: 120 }],
+  dataSource: [],
+  pageParam: { current: 1, pageSize: 10, total: 0 },   // 默认值
+  searchParam: { keyword: '', status: '' },
+  searchFields: [                                        // 与 ProForm 同一套 Field[] 格式
+    { path: 'keyword', component: 'input', label: '关键词' },
+    { path: 'status', component: 'select', label: '状态', options: [...] },
+  ],
+});
+```
 
-### Override example
+返回 `Table` 实例：
 
-```vue
-<ProComponentProvider
-  :component-vars="{
-    'pro-form-item': { span: 6 },
-    input: { maxlength: 200 },
-    select: { showSearch: true },
-    'pro-table': { addIndexColumn: false },
-  }"
->
-  <ProForm :form="form" />
-  <ProTable :table="table" />
-</ProComponentProvider>
-```
+| 成员                                                                  | 说明                                                   |
+| :-------------------------------------------------------------------- | :----------------------------------------------------- |
+| `table.columns`                                                       | 列配置（Ref）                                          |
+| `table.dataSource`                                                    | 表格数据源（Ref）                                      |
+| `table.pageParam`                                                     | 分页参数（reactive）：`current` / `pageSize` / `total` |
+| `table.searchForm`                                                    | 搜索表单实例（Form 类型，所有 useForm 方法可用）       |
+| `table.setColumn` / `deleteColumn` / `appendColumn` / `prependColumn` | 列增删改查（用法同 setField）                          |
+| `table.setPageParam(patch)`                                           | 设置分页参数                                           |
+| `table.resetQueryParams()`                                            | 重置分页到第一页 + 恢复搜索条件到初始值                |
 
----
+## ProTable -- 配置驱动表格
 
-## 6. ProTable quick reference
+**关键：ProTable 透传所有 ant-design-vue TableProps**（`& TableProps`），可直接写 `row-key` / `bordered` / `scroll` / `row-selection` 等原生属性；`size`、`loading` 是 v-model。
 
-```ts
-import { ProTable, useTable } from '@qin-ui/antd-vue-pro';
+| prop               | 说明                                                            |
+| :----------------- | :-------------------------------------------------------------- |
+| `table`            | useTable 实例                                                   |
+| `search`           | 数据查询方法 `() => Promise`，ProTable 内部调用它（非自动触发） |
+| `addIndexColumn`   | 首列插入 index 列                                               |
+| `immediateSearch`  | onMounted 时立即触发一次 search                                 |
+| `control`          | 是否显示 size/列控制按钮，可 `{sizeControl, columnControl}`     |
+| `searchFormConfig` | 搜索栏配置，含 `hidden`（隐藏搜索区）、`container`              |
+| `tableContainer`   | 表格区容器                                                      |
+
+**数据流**：搜索->重置分页到第 1 页->调 `search()`；分页/排序变化->更新 `pageParam`->调 `search()`；重置->`resetQueryParams()`->调 `search()`。
+
+## Column -- 列配置
+
+继承 ant-design-vue `ColumnType`，**所有原生列属性可用**（`title` / `width` / `fixed` / `align` / `customRender` / `ellipsis`…）。新增：
 
-const table = useTable<Row>({
+- `dataIndex`：列数据路径（主用），类型安全，支持 `'name'` / `'address.city'` / `['address','city']`
+- `key`：辅助标识（dataIndex 不满足时用，优先级更低）
+- `hidden`：隐藏该列（配合列控制）
+
+## ProTable 最小示例
+
+```vue
+<script setup lang="ts">
+import { ProTable, useTable } from '@qin-ui/antd-vue-pro';
+interface User {
+  id: number;
+  name: string;
+  status: string;
+}
+interface Search {
+  keyword: string;
+}
+
+const table = useTable<Search, User>({
   columns: [
-    { title: 'ID', dataIndex: 'id', width: 80 },
-    { title: 'Name', dataIndex: 'name', width: 120 },
-  ],
-  // searchFields uses the same Field[] format as ProForm
-  searchFields: [
-    { path: 'name', component: 'input', placeholder: 'Search' },
-    { path: 'status', component: 'select', options: [...] },
+    { dataIndex: 'name', title: '姓名', width: 120 },
+    { dataIndex: 'status', title: '状态' },
   ],
+  searchFields: [{ path: 'keyword', component: 'input', label: '关键词' }],
 });
-// table.searchForm is a ProForm instance — all form methods available
+
+const fetchData = async () => {
+  // 组装查询参数：搜索条件 + 分页
+  const res = await api.list({
+    ...table.searchForm.formData,
+    ...table.pageParam,
+  });
+  table.dataSource.value = res.data;
+  table.setPageParam({ total: res.total });
+};
+</script>
+<template>
+  <ProTable :table="table" :search="fetchData" row-key="id" immediate-search />
+</template>
 ```
 
-```html
-<ProTable :table="table" :search="fetchData" addIndexColumn immediateSearch />
+## 响应式联动（三种模式，选最简的）
+
+```ts
+disabled: computed(() => !form.formData.enabled),   // A 声明式，初始化时已知（首选）
+const isDisabled = ref(false);                        // B 外部共享状态
+form.setField('limitCount', { disabled: true });      // C 命令式，事件驱动
 ```
 
----
+> **不支持响应式**（不能包 ref/computed）的属性：`component` / `formItemContainer` / `componentContainer` / `valueFormatter` / `fields` / `slots` / `modelProp`。
+
+## 反模式
+
+- ❌ 在 `<ProForm>` 内手写 `<a-form-item>` -- ProForm 从 Field 配置自动渲染。
+- ❌ 猜透传属性名 -- 先查 antdv.com。
+- ❌ 把 `span` 当输入控件属性。
+- ❌ 传 SFC 给 `component` 不用 `markRaw`。
+- ❌ 在 ProTable 上忘了传 `:search`，或期望它自动请求 -- 查询由你提供并驱动。
 
-## 7. References
+## 按需深查
 
-1. **`node_modules/@qin-ui/antd-vue-pro/api.json`** — Structured API metadata (signatures, types, JSDoc examples)
-2. **`node_modules/@qin-ui/antd-vue-pro/README.md`** — Full usage docs and code examples
-3. **[antdv.com](https://antdv.com)** — ant-design-vue component API reference (always check before writing pass-through props)
+- `node_modules/@qin-ui/antd-vue-pro/api.json` -- 结构化 API 元数据（函数签名、参数、类型）。
+- `node_modules/@qin-ui/antd-vue-pro/README.md` -- 完整用法与进阶示例。

package/README.md

@@ -38,6 +38,23 @@ pnpm add @qin-ui/antd-vue-pro
 
 ---
 
+## 🤖 AI 辅助开发
+
+本项目内置 AI 上下文初始化工具。安装后在项目根目录执行：
+
+```bash
+npx @qin-ui/antd-vue-pro init-ai
+```
+
+将在项目中生成双载体 AI 上下文，使 Cursor / Claude Code / Codex 等 AI 工具深度理解本库的 Schema 驱动用法与属性透传规则：
+
+- `AGENTS.md` — 核心使用规则（跨工具开放约定，会话时自动注入，AI 默认加载）
+- `.agents/skills/antd-vue-pro.md` — 完整 API 参考（支持 skills 发现的工具按需调取）
+
+> 生成的 `AGENTS.md` 使用标记区块写入，重复执行 `init-ai` 可安全更新，不影响项目内其他库的指令。建议将生成的文件提交到 Git 仓库，团队共享 AI 上下文。
+
+---
+
 ## 🚀 快速开始
 
 ### 1. 全局注册组件（可选）
@@ -119,6 +136,29 @@ const handleSubmit = async () => {
 
 ---
 
+## 🧱 属性分层透传（核心规则）
+
+ProForm/ProTable 是渲染引擎，所有真实 UI 来自 ant-design-vue。**Field 上的属性会被"剥离到不同 DOM 层"，不是全塞给输入控件**。写错层就会失效，这是最容易踩的坑：
+
+```
+<a-col :span="8">            ← Grid 层（仅 grid 开启时）
+  <a-form-item label="...">  ← FormItem 层
+    <a-input placeholder>     ← 输入控件层
+  </a-form-item>
+</a-col>
+```
+
+| 属性                                                                                                                                                                                                                   | 落到哪一层                       | 说明                 |
+| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------- | :------------------- |
+| `span` / `offset` / `push` / `pull` / `flex` / `xs`..`xxl`                                                                                                                                                             | `<a-col>` Grid 层                | 仅 `grid` 开启时生效 |
+| `label` / `rules` / `tooltip` / `colon` / `labelCol` / `wrapperCol` / `extra` / `help` / `validateTrigger` / `validateFirst` / `valuePropName` / `normalize` / `formItemStyle` / `formItemClass` / `formItemDataAttrs` | `<a-form-item>` 层               | 表单项相关属性       |
+| `disabled` / `placeholder` / `allowClear` / `options` / `mode` / `maxlength` / `componentStyle` / `componentClass` / `componentDataAttrs` + 该控件其余 ant-design-vue 原生属性                                         | 输入控件本身（`a-input` 等）     | 其余全部             |
+| `component` / `hidden` / `modelProp` / `valueFormatter` / `fields` / `slots` / `formItemContainer` / `componentContainer` / `extraProps`                                                                               | ProForm 逻辑消费，**不绑到 DOM** | 框架级属性           |
+
+> **规则**：`span` 给 Grid，`label`/`rules` 给 FormItem，其余给输入控件。输入控件的具体属性名/类型请以 [ant-design-vue 官方文档](https://antdv.com) 为准。
+
+---
+
 ## 📚 组件 API 说明
 
 ### 1. ProComponentProvider
@@ -131,6 +171,24 @@ const handleSubmit = async () => {
 | :--------------- | :-------------------------------------- | :-------------- | :----- |
 | `component-vars` | 需要全局 provide 给子组件的默认属性配置 | `ComponentVars` | -      |
 
+#### 内置默认预设（INJECT_CONFIG）
+
+ProComponentProvider 内置了一套默认属性预设，**即使不配置 `component-vars` 也会生效**。Field 配置优先级最高，会覆盖这些预设。以下为各组件的内置默认值（写代码时需知晓，避免行为与预期不符）：
+
+| component                                      | 默认预设                                                                                                                                                                                                         |
+| :--------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `switch`                                       | `{ modelProp: 'checked' }` —— v-model 绑定 `checked` 而非 `value`                                                                                                                                                |
+| `input` / `input-password`                     | `{ maxlength: 100, allowClear: true, placeholder: '请输入' }`                                                                                                                                                    |
+| `textarea`                                     | `{ maxlength: 200, autoSize: { minRows: 3, maxRows: 6 }, showCount: true, allowClear: true, placeholder: '请输入' }`                                                                                             |
+| `input-number`                                 | `{ max: 1e15-1, min: -(1e15+1), controls: false, placeholder: '请输入', style: { width: '100%' } }`                                                                                                              |
+| `select` / `cascader`                          | `{ allowClear: true, placeholder: '请选择', getPopupContainer }`                                                                                                                                                 |
+| `date-picker` / `range-picker` / `time-picker` | `{ allowClear: true, getPopupContainer, style: { width: '100%' } }`                                                                                                                                              |
+| `pro-form`                                     | `{ grid: { gutter: { xs: 8, sm: 16, md: 16, lg: 24 } } }`                                                                                                                                                        |
+| `pro-form-item`                                | `{ validateFirst: true, span: 8 }`                                                                                                                                                                               |
+| `pro-table`                                    | `{ pagination: { showTotal, showSizeChanger, pageSizeOptions: ['10'..'100'], showQuickJumper: true }, searchFormConfig: { layout: 'grid', expand: { minExpandRows: 2 } }, control: true, addIndexColumn: true }` |
+
+> `modelProp` 控制 v-model 绑定的属性名，默认 `'value'`（即 `v-model:value`）。`switch` 经预设绑定为 `checked`，通常无需手动设置。
+
 ---
 
 ### 2. ProForm
@@ -177,6 +235,32 @@ const handleSubmit = async () => {
 | `toolbar`     | 自定义工具栏区域（位于表格右上方控制按钮旁）       |
 | `table`       | 完全自定义渲染表格区域                             |
 
+#### 数据流
+
+ProTable 不会自动请求数据，**查询由你提供的 `search` 回调驱动**。内部串联逻辑：
+
+```
+点击搜索  -> 重置分页到第 1 页        -> 调用 search()
+分页/排序变化 -> 更新 pageParam        -> 调用 search()
+点击重置  -> resetQueryParams()       -> 调用 search()
+挂载(immediateSearch) -> 立即触发一次   -> 调用 search()
+```
+
+`search` 回调内通常组装查询参数并赋值数据源：
+
+```ts
+const fetchData = async () => {
+  const res = await api.list({
+    ...table.searchForm.formData, // 搜索条件
+    ...table.pageParam, // 分页
+  });
+  table.dataSource.value = res.data;
+  table.setPageParam({ total: res.total });
+};
+
+// 重置按钮（ProTable 内部已串联 resetQueryParams -> search，一般无需手动处理）
+```
+
 ---
 
 ## ⚙️ 核心 Hooks 说明
@@ -244,6 +328,16 @@ const table = useTable<D, T>({
 | `setPageParam(param)`     | 增量设置当前分页参数值，支持传入对象或更新函数            | `(param) => void`      |
 | `resetQueryParams()`      | 重置搜索参数，并恢复分页至第 1 页                         | `() => void`           |
 
+#### 列配置（Column）
+
+`columns` 数组中每一项为 `Column<T>` 类型，**继承 ant-design-vue `ColumnType`**，因此所有原生列属性（`title` / `width` / `fixed` / `align` / `customRender` / `ellipsis` 等）均可用。在此基础上新增：
+
+| 属性        | 说明                                                                                      | 类型                 | 默认值  |
+| :---------- | :---------------------------------------------------------------------------------------- | :------------------- | :------ |
+| `dataIndex` | 列数据路径（主要字段），类型安全，支持 `'name'` / `'address.city'` / `['address','city']` | `string \| string[]` | -       |
+| `key`       | 列字段标识（辅助），仅当 `dataIndex` 无法满足时使用，匹配优先级低于 `dataIndex`           | `string`             | -       |
+| `hidden`    | 是否隐藏该列（配合列动态控制）                                                            | `boolean`            | `false` |
+
 ---
 
 ## 📄 字段配置（`Field`）详解
@@ -275,6 +369,63 @@ const table = useTable<D, T>({
 | `fields`             | 嵌套子表单项的 Schema 数组配置（用于分组或复杂嵌套表单）                      | `Field[]`                     | -         |
 | `grid`               | 针对当前嵌套子表单项所使用的网格布局参数（仅当有 `fields` 时有效）            | `boolean \| GridProps`        | -         |
 
+#### `valueFormatter` 字段值转换
+
+控制表单值与组件值之间的转换（如日期 `dayjs` 与字符串互转）。在 `onUpdate:value` 之前执行，支持两种形态：
+
+```ts
+// 函数形态：(新值, 旧值) => 转换后的值，写回 formData
+{ path: 'name', component: 'input', valueFormatter: (val, oldVal) => val?.trim() }
+
+// 对象形态：get 读出时转换，set 写入时转换
+{
+  path: 'birthday',
+  component: 'date-picker',
+  valueFormatter: {
+    get: (val) => (val ? dayjs(val) : null),                          // formData -> 组件显示
+    set: (val) => (val ? dayjs(val).format('YYYY-MM-DD') : null),     // 组件 -> formData
+  },
+}
+```
+
+> ⚠️ `valueFormatter` 不支持响应式（不能包 `ref`/`computed`），与 `component` / `fields` / `slots` / `modelProp` 等同属不支持响应式的属性。
+
+---
+
+### 🔄 响应式联动
+
+控制类属性（`disabled` / `hidden` / `rules` 等）支持三种响应式模式，按场景选最简的：
+
+```ts
+// A. computed() 声明式 -- 初始化时已知的联动（首选）
+disabled: computed(() => !form.formData.enabled),
+rules: computed(() => form.formData.hasLimit ? [{ required: true, message: '必填' }] : []),
+
+// B. ref() -- 外部共享状态
+const isDisabled = ref(false);
+disabled: isDisabled,
+
+// C. setField() 命令式 -- 事件驱动的运行时变更
+form.setField('limitCount', { disabled: true });
+```
+
+> **规则**：初始化时已知的联动用 `computed()`，运行时事件触发的用 `setField()`，外部共享状态用 `ref()`。能用 `computed()` 解决就不要用 `setField()`。
+
+#### 不支持响应式的属性
+
+以下属性不能包 `ref`/`computed`（会失效或引发渲染异常），只能传静态值：
+
+| 属性                                       | 原因                                                |
+| :----------------------------------------- | :-------------------------------------------------- |
+| `component`                                | 组件对象/函数，响应式代理会破坏渲染（需 `markRaw`） |
+| `valueFormatter`                           | 纯转换函数，无需响应式                              |
+| `fields`                                   | 嵌套字段数组结构，响应式代理会干扰内部解析          |
+| `slots`                                    | 插槽内容，响应式代理会破坏渲染                      |
+| `modelProp`                                | 字符串标识，无需响应式                              |
+| `formItemContainer` / `componentContainer` | 容器组件，需 `markRaw`                              |
+
+> 动态切换 `component` 或 `slots` 时，用 `setField()` 命令式更新，而非包 `computed`。
+
 ---
 
 ### 内置组件映射（`component` 可选值）
@@ -303,9 +454,45 @@ const table = useTable<D, T>({
 
 ---
 
-### 🧩 扩充注册您的自定义组件
+### 🧩 自定义组件（4 种方式）
 
-#### 步骤 1：利用 ComponentProvider 全局注册
+`Field.component` 的解析优先级（高 -> 低）：
+
+`teleport 插槽注入` > `ProComponentProvider.componentMap` > `内置 componentMap` > `原始 component 值`
+
+#### 方式 1：传入 SFC 单文件组件对象（推荐，单字段最常用）
+
+`component` 直接传组件对象，**必须用 `markRaw` 包裹**：
+
+```ts
+import { markRaw } from 'vue';
+import MyInput from './MyInput.vue';
+
+const fields = [{ path: 'code', label: '验证码', component: markRaw(MyInput) }];
+```
+
+> ⚠️ **必须 `markRaw`**：不包会被 Vue 当成响应式对象深度代理，触发性能警告甚至渲染异常。类型上 `component` 接受 `RenderComponentType | Raw<RenderComponentType>`，`Raw<T>` 即 markRaw 的类型标记。此字段不支持响应式（不能包 `ref`/`computed`）。
+
+#### 方式 2：传入 render 函数（单字段，需动态拼装 props 时）
+
+`component` 传 `(props, ctx) => VNode`。`props` 含 v-model 绑定值与 path，`ctx.attrs` 含透传属性：
+
+```ts
+import { h } from 'vue';
+import MyInput from './MyInput.vue';
+
+const fields = [
+  {
+    path: 'code',
+    label: '验证码',
+    component: (p, ctx) => h(MyInput, { ...p, ...ctx.attrs }),
+  },
+];
+```
+
+#### 方式 3：ProComponentProvider 注入 componentMap（全局复用，推荐多字段场景）
+
+在根用 `componentMap` 注册，Field 里用字符串引用。**可覆盖内置组件**（如 `input: MyInput` 替换全局 `input`）。
 
 ```vue
 <script setup lang="ts">
@@ -324,9 +511,7 @@ const componentMap = {
 </template>
 ```
 
-#### 步骤 2：追加 TypeScript 全局声明获取强类型补全
-
-在项目任意 `.d.ts` 类型文件中写入以下代码：
+追加 TypeScript 全局声明获取强类型补全（项目任意 `.d.ts`）：
 
 ```ts
 declare module '@qin-ui/antd-vue-pro' {
@@ -336,7 +521,34 @@ declare module '@qin-ui/antd-vue-pro' {
 }
 ```
 
-现在，您在表单配置中写入 `component: 'rich-editor'` 时，将自动获得精准的属性类型联想与校验！
+之后 `component: 'rich-editor'` 即获精准属性类型联想与校验。
+
+#### 方式 4：模板 scoped slot（声明式，简单替换）
+
+插槽名 = 字段 `path`，绑定参数通过 `v-bind="scoped"` 转发（teleport 机制，优先级最高）：
+
+```vue
+<ProForm :form="form">
+  <template #agreement="scoped">
+    <a-checkbox v-bind="scoped">同意协议</a-checkbox>
+  </template>
+</ProForm>
+```
+
+#### 选择建议
+
+| 场景                         | 推荐方式                          |
+| :--------------------------- | :-------------------------------- |
+| 单字段复用一个 SFC           | 方式 1（`markRaw(SFC)`）          |
+| 单字段、需动态拼装 props     | 方式 2（render 函数）             |
+| 多处复用 / 替换内置组件      | 方式 3（componentMap + 声明扩充） |
+| 简单声明式替换、不想写 `h()` | 方式 4（scoped slot）             |
+
+#### 自定义组件需遵守的约定
+
+- **v-model**：默认绑 `value`（`v-model:value`）。若组件用别的 prop（如 Switch 用 `checked`），通过字段 `modelProp` 指定，或在 `componentVars` 预设 `modelProp`。
+- **接收 path**：组件会收到 `path` prop（字段路径），可用于透传或标识。
+- **属性透传**：Field 上除框架级属性外（`component` / `hidden` / `modelProp` / `valueFormatter` / `fields` / `slots` / `formItemContainer` / `componentContainer` / `extraProps` 等），其余作为 attrs 透传给自定义组件。
 
 ---
 

package/api.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-07-10T10:21:21.983Z",
+  "generatedAt": "2026-07-15T06:38:34.266Z",
   "name": "@qin-ui/antd-vue-pro",
   "api": [
     {
@@ -8,6 +8,20 @@
       "package": "@qin-ui/antd-vue-pro",
       "signature": "<ProComponentProvider>",
       "description": "@qin-ui/antd-vue-pro 全局配置提供者组件\n用于在组件树的顶层配置所有子组件的全局默认属性。\n支持配置 ProForm、ProTable、ProFormItem 以及所有内置组件的默认属性。",
+      "params": [
+        {
+          "name": "componentVars",
+          "type": "ComponentVars",
+          "optional": true,
+          "description": "组件全局配置变量"
+        },
+        {
+          "name": "componentMap",
+          "type": "Record<ComponentName, any>",
+          "optional": true,
+          "description": "自定义组件映射，用于替换或扩展内置组件"
+        }
+      ],
       "examples": [
         "```vue\n<template>\n<ProComponentProvider\n:componentVars=\"{\n'pro-form': { labelCol: { span: 4 } },\n'input': { placeholder: '请输入', maxlength: 200 },\n'select': { placeholder: '请选择' },\n}\"\n>\n<ProForm :form=\"form\" />\n</ProComponentProvider>\n</template>\n```"
       ]
@@ -32,6 +46,26 @@
       "package": "@qin-ui/antd-vue-pro",
       "signature": "<ProForm>",
       "description": "@qin-ui/antd-vue-pro 配置驱动表单组件\n架构设计说明 (Architecture Overview)\n[ 数据层 (Core) ]  =>  [ 绑定层 (ProForm) ]  =>  [ 渲染层 (BaseFormItem / BaseField) ]\n1. 数据隔离：ProForm 本身不负责存储和管理表单状态，所有核心状态（formData, fields, 校验规则）\n均交由底层的 `useForm`（@qin-ui/pro-components-core）驱动。\n2. 上下文透传：通过 `provide` 将核心状态下发给子组件，避免了深层嵌套的 Props 传递。\n3. 递归渲染：网格布局和具体字段的解析交由 `<BaseFormItem>` 递归完成，实现了 UI 布局与表单逻辑的解耦。\n通过配置驱动的方式快速构建表单，支持：\n- 字段联动（通过 setField、watch 等实现）\n- 嵌套字段（通过 fields 递归配置）\n- 自定义组件（通过 component 属性和 custom 类型）\n- 网格布局（通过 grid 属性）\n- 动态插槽（以字段 path 命名的插槽）\n- 全局配置注入（通过 ProComponentProvider）",
+      "params": [
+        {
+          "name": "form",
+          "type": "F",
+          "optional": true,
+          "description": "useForm 返回的表单实例"
+        },
+        {
+          "name": "grid",
+          "type": "boolean | GridProps",
+          "optional": true,
+          "description": "是否启用网格布局 (默认 false)"
+        },
+        {
+          "name": "...attrs",
+          "type": "...FormProps",
+          "optional": false,
+          "description": "Ant Design Vue Form 组件的其他属性"
+        }
+      ],
       "typeParams": [
         {
           "name": "F"
@@ -74,6 +108,14 @@
       "package": "@qin-ui/antd-vue-pro",
       "signature": "export const useFormData = <D extends Data = Data>(\n  initFormData?: ExtendWithAny<DeepPartial<D>>\n): UseFormDataReturn<D> =>",
       "description": "表单数据处理 Hook\n提供响应式表单数据的管理能力，支持：\n- 响应式数据存储（基于 Vue reactive）\n- 深层路径读写（支持点号分隔，如 'address.city'）\n- 类型安全的路径提示（传入泛型 D 后，path 参数可获得类型推导）\n- 父子表单自动注入（非根表单会从注入中获取数据）",
+      "params": [
+        {
+          "name": "initFormData",
+          "type": "ExtendWithAny<DeepPartial<D>>",
+          "optional": true,
+          "description": "初始表单数据"
+        }
+      ],
       "returns": "{UseFormDataReturn<D>} 表单数据操作对象",
       "typeParams": [
         {
@@ -90,6 +132,14 @@
       "package": "@qin-ui/antd-vue-pro",
       "signature": "export function useFields<D extends Data = Data>(\n  initFields?: Fields<D>\n): UseFieldsReturn<D, Field<ComponentName, D>, FormItemInstance>;",
       "description": "字段配置管理 Hook\n基于 `@qin-ui/pro-components-core` 的 `useFields`，将泛型参数绑定为 Ant Design Vue 的本地类型：\n- 字段类型 F -> `Field<ComponentName, D>`（支持 Ant Design Vue 组件类型推导）\n- FormItem 实例 -> Ant Design Vue 的 `FormItemInstance`\n提供对字段配置数组的增删改查操作，支持：\n- 通过路径字符串或查找函数定位字段\n- 深层嵌套字段的遍历和匹配\n- 字段配置的合并/覆盖更新\n- 字段的添加、插入、删除\n- 父级字段查找\n- `fields` - 字段配置数组（响应式 Ref\\<F[]\\>）\n- `getField(path)` - 获取字段配置，支持路径字符串或查找函数\n- `setField(path, field, options?)` - 更新字段配置，默认合并模式\n- `deleteField(path, options?)` - 删除字段配置\n- `appendField(path, field, options?)` - 在指定字段后追加\n- `prependField(path, field, options?)` - 在指定字段前插入\n- `getParentField(path, options?)` - 获取父级字段配置",
+      "params": [
+        {
+          "name": "initFields",
+          "type": "Fields<D>",
+          "optional": true,
+          "description": "初始字段配置数组"
+        }
+      ],
       "returns": "字段操作对象，包含以下属性：",
       "typeParams": [
         {
@@ -131,6 +181,26 @@
       "package": "@qin-ui/antd-vue-pro",
       "signature": "export function useForm<D extends Data = Data>(\n  initFormData?: ExtendWithAny<DeepPartial<D>>,\n  initFields?: Field<ComponentName, D>[],\n  root?: boolean\n): Form<D, Field<ComponentName, D>>;",
       "description": "创建表单实例的 Hook\n基于 `@qin-ui/pro-components-core` 的 `useForm`，将泛型参数绑定为 Ant Design Vue 的本地类型：\n- 字段类型 F -> `Field<ComponentName, D>`（支持 Ant Design Vue 所有内置组件类型推导）\n- 表单实例 -> Ant Design Vue 的 `FormInstance`（使 formRef 获得完整的类型提示）\n表单实例组合了三个子模块的能力：\n- **useFormData**：表单数据管理（响应式数据、读写、批量更新）\n- **useFields**：字段配置管理（增删改查字段配置，支持嵌套）\n- **useFormRef**：底层 Form 组件实例引用",
+      "params": [
+        {
+          "name": "initFormData",
+          "type": "ExtendWithAny<DeepPartial<D>>",
+          "optional": true,
+          "description": "初始表单数据"
+        },
+        {
+          "name": "initFields",
+          "type": "Field<ComponentName, D>[]",
+          "optional": true,
+          "description": "初始字段配置数组"
+        },
+        {
+          "name": "root",
+          "type": "boolean",
+          "optional": true,
+          "description": "是否为根表单。设为 `false` 时尝试从父组件注入获取表单实例 (默认 true)"
+        }
+      ],
       "returns": "{Form<D>} 表单实例，包含数据操作、字段操作和 ref 操作",
       "typeParams": [
         {
@@ -206,6 +276,36 @@
           "type": "object",
           "optional": false,
           "description": "表格配置参数"
+        },
+        {
+          "name": "params.columns",
+          "type": "Columns<T>",
+          "optional": true,
+          "description": "初始列配置数组"
+        },
+        {
+          "name": "params.dataSource",
+          "type": "T[]",
+          "optional": true,
+          "description": "初始数据源"
+        },
+        {
+          "name": "params.pageParam",
+          "type": "PageParam",
+          "optional": true,
+          "description": "初始分页参数，默认 `{ current: 1, pageSize: 10, total: 0 }`"
+        },
+        {
+          "name": "params.searchParam",
+          "type": "ExtendWithAny<DeepPartial<D>>",
+          "optional": true,
+          "description": "初始搜索参数"
+        },
+        {
+          "name": "params.searchFields",
+          "type": "Fields<D>",
+          "optional": true,
+          "description": "搜索表单字段配置"
         }
       ],
       "returns": "{Table<D, T>} 表格实例",

package/bin/init-ai.mjs

@@ -3,10 +3,9 @@
 /**
  * @qin-ui/antd-vue-pro AI 上下文初始化 CLI 工具
  *
- * 在消费方项目中生成分层 AI 上下文文件，使 AI 工具能够：
- * 1. 理解 @qin-ui/antd-vue-pro 的 Schema 驱动架构
- * 2. 掌握属性透传规则（何时查阅 ant-design-vue 文档）
- * 3. 快速获取完整 API 参考
+ * 在消费方项目中生成双载体 AI 上下文：
+ * 1. 根目录 AGENTS.md —— 核心使用规则，跨工具自动注入（主载体）
+ * 2. .agents/skills/{pkg}.md —— 完整 API 参考，支持 skills 发现的工具按需调取（参考载体）
  *
  * 用法:
  *   npx @qin-ui/antd-vue-pro init-ai
@@ -28,6 +27,10 @@ const PKG_JSON = JSON.parse(
 const PKG_NAME = PKG_JSON.name;
 const PKG_SHORT = PKG_NAME.replace(/^@qin-ui\//, '');
 
+// AGENTS.md 智能合并区块标记（支持多库共存，幂等更新）
+const BEGIN_MARKER = `<!-- BEGIN ${PKG_NAME} -->`;
+const END_MARKER = `<!-- END ${PKG_NAME} -->`;
+
 // ==================== 终端颜色 ====================
 
 const green = s => `\x1b[32m${s}\x1b[0m`;
@@ -64,56 +67,103 @@ function getApiJsonContent() {
   }
 }
 
-// ==================== 内容生成 ====================
+// ==================== 工具函数 ====================
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+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)}`);
+}
+
+// ==================== AGENTS.md（主载体，自动注入）====================
 
 /**
- * 生成 rules 文件内容（Instructions 层）
- * 包含：架构关系、透传规则、反模式、ant-design-vue 资源链接
+ * 生成 AGENTS.md 区块内容
+ * = AI-CONTEXT.md 全文（核心使用规则，AI 必然读到）
  */
-function getRulesContent() {
-  const aiContext = getAiContextContent();
-
-  return [
-    '---',
-    `description: "${PKG_NAME} 组件库使用规范 — Schema 驱动、属性透传规则"`,
-    'globs: ["**/*.vue", "**/*.ts", "**/*.tsx"]',
-    'alwaysApply: false',
-    '---',
-    '',
-    aiContext,
-    '',
-    '---',
-    '',
-    '## 本地参考文件',
-    '',
-    '本规则文件提供了核心架构和用法指南。需要完整 API 参考或底层组件文档时，请阅读以下资源：',
-    '',
-    `- **\`.agents/docs/${PKG_SHORT}-api.md\`** — 完整 API 文档（组件、Hooks、类型、Field 配置参考）`,
-    `- **\`node_modules/${PKG_NAME}/api.json\`** — 结构化 API 元数据（函数签名、类型定义）`,
-    '',
-    '## 底层组件文档',
-    '',
-    `${PKG_NAME} 基于 **ant-design-vue**（v4，\`a-\` 前缀）封装。编写 Field 中的输入控件属性前，请查阅 ant-design-vue 官方文档确认属性名和类型：`,
-    '',
-    '- **[ant-design-vue 官方文档](https://antdv.com)** — 组件 API 参考（中文）',
-    '',
-  ].join('\n');
+function getAgentsBlock() {
+  return getAiContextContent();
 }
 
 /**
- * 生成 API 文档内容（Resources 层）
- * 从 README.md + api.json 合并提取完整 API 参考
+ * 智能合并 AGENTS.md：
+ * - 文件不存在 -> 创建，内容 = 标记区块
+ * - 已有本库区块 -> 幂等替换区块内容（支持升级后更新）
+ * - 已有其他内容但无本库区块 -> 末尾追加区块（多库共存不冲突）
  */
-function getApiDocContent() {
+function writeAgentsMd(cwd) {
+  const agentsPath = path.join(cwd, 'AGENTS.md');
+  const blockContent = getAgentsBlock();
+  const newBlock = `${BEGIN_MARKER}\n${blockContent}\n${END_MARKER}`;
+
+  let existing = '';
+  if (fs.existsSync(agentsPath)) {
+    existing = fs.readFileSync(agentsPath, 'utf-8');
+  }
+
+  let result;
+  const hasBlock =
+    existing.includes(BEGIN_MARKER) && existing.includes(END_MARKER);
+
+  if (hasBlock) {
+    // 幂等替换已有区块
+    const blockRegex = new RegExp(
+      `${escapeRegExp(BEGIN_MARKER)}[\\s\\S]*?${escapeRegExp(END_MARKER)}`,
+      'g'
+    );
+    result = existing.replace(blockRegex, newBlock);
+  } else if (existing.trim()) {
+    // 已有其他内容，追加区块
+    result = `${existing.trimEnd()}\n\n${newBlock}\n`;
+  } else {
+    // 文件不存在或空
+    result = `${newBlock}\n`;
+  }
+
+  const existed = fs.existsSync(agentsPath);
+  fs.writeFileSync(agentsPath, result, 'utf-8');
+  const status = existed ? yellow('[更新]') : green('[创建]');
+  console.log(`  ${status} ${cyan('AGENTS.md')}`);
+}
+
+// ==================== Skills（参考载体，按需调取）====================
+
+/**
+ * 生成 skill 文件内容（完整 API 参考 + skill frontmatter）
+ * 供支持 skills 发现的工具按需调取，避免全量注入占 token
+ */
+function getSkillContent() {
   const readme = getReadmeContent();
   const apiJson = getApiJsonContent();
 
   const sections = [];
 
-  sections.push(`# ${PKG_NAME} — 完整 API 参考`, '');
+  // skill frontmatter
+  sections.push('---');
+  sections.push(`name: ${PKG_SHORT}`);
+  sections.push(
+    `description: ${PKG_NAME} 完整 API 参考 - 组件、Hooks、类型、Field/Column 配置。当需要精确的函数签名、参数类型或完整用法示例时调用。`
+  );
+  sections.push('---');
+  sections.push('');
+
+  sections.push(`# ${PKG_NAME} - 完整 API 参考`, '');
   sections.push(`> 自动生成自 README.md 和 api.json。版本: ${PKG_JSON.version}`, '');
 
-  // README 内容（已包含完整的使用文档）
+  // README 内容（完整使用文档）
   if (readme) {
     sections.push(readme);
     sections.push('');
@@ -121,10 +171,8 @@ function getApiDocContent() {
 
   // 结构化 API 元数据
   if (apiJson && apiJson.api && apiJson.api.length > 0) {
-    sections.push('---');
-    sections.push('');
-    sections.push('## 结构化 API 元数据（自动提取自源码 JSDoc）');
-    sections.push('');
+    sections.push('---', '');
+    sections.push('## 结构化 API 元数据（自动提取自源码 JSDoc）', '');
 
     for (const item of apiJson.api) {
       const typeLabel = {
@@ -195,41 +243,26 @@ function getApiDocContent() {
   return sections.join('\n');
 }
 
-// ==================== 文件写入 ====================
-
-function ensureDir(dirPath) {
-  if (!fs.existsSync(dirPath)) {
-    fs.mkdirSync(dirPath, { recursive: true });
-  }
-}
-
-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 — AI 上下文初始化`)}
+${bold(`${PKG_NAME} CLI - AI 上下文初始化`)}
 
 ${bold('用法:')}
   npx ${PKG_NAME} init-ai
 
 ${bold('说明:')}
-  在项目中生成分层 AI 上下文文件，使 AI 工具能够深度理解和规范使用 ${PKG_NAME}。
+  在项目中生成双载体 AI 上下文，使 AI 工具能够深度理解和规范使用 ${PKG_NAME}。
 
   生成的文件结构：
+    AGENTS.md                          核心使用规则（跨工具自动注入）
     .agents/
-      rules/
-        ${PKG_SHORT}.md         规则文件（架构、透传规则、反模式）
-      docs/
-        ${PKG_SHORT}-api.md     API 参考（完整文档 + 结构化元数据）
+      skills/
+        ${PKG_SHORT}.md                完整 API 参考（按需调取）
+
+  ${dim('AGENTS.md 是跨工具开放约定，Codex / Claude Code / Cursor 等会话时自动注入。')}
+  ${dim('.agents/skills/ 供支持 skills 发现的工具按需调取完整 API。')}
 
 ${bold('选项:')}
   --help     显示帮助信息
@@ -253,49 +286,37 @@ function main() {
   }
 
   console.log('');
-  console.log(bold(`📦 ${PKG_NAME} — AI 上下文初始化 v${PKG_JSON.version}`));
+  console.log(bold(`📦 ${PKG_NAME} - AI 上下文初始化 v${PKG_JSON.version}`));
   console.log(dim(`   基于 ant-design-vue 的 Schema 驱动组件库`));
   console.log('');
 
-  // 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('   → 架构概览、属性透传决策树、渐进用法、反模式'));
+  // 1. 生成 AGENTS.md（主载体）
+  console.log(bold('📋 主载体：AGENTS.md（自动注入）'));
+  writeAgentsMd(process.cwd());
+  console.log(dim('   -> 核心使用规则，Codex/Claude Code/Cursor 等会话自动加载'));
   console.log('');
 
-  // 2. 生成 API 文档
-  console.log(bold('📖 参考层 (Docs)'));
-  const apiDocContent = getApiDocContent();
+  // 2. 生成 Skills 参考（按需调取）
+  console.log(bold('📖 参考载体：.agents/skills/（按需调取）'));
   writeFileWithLog(
-    path.join(process.cwd(), '.agents/docs', `${PKG_SHORT}-api.md`),
-    apiDocContent,
-    `.agents/docs/${PKG_SHORT}-api.md`
+    path.join(process.cwd(), '.agents/skills', `${PKG_SHORT}.md`),
+    getSkillContent(),
+    `.agents/skills/${PKG_SHORT}.md`
   );
-  console.log(dim('   → 完整 README 文档 + 结构化 API 元数据'));
+  console.log(dim('   -> 完整 README + 结构化 API 元数据，skills 工具按需调取'));
   console.log('');
 
   // 3. 完成提示
-  console.log(green('✅ 完成！已生成分层 AI 上下文文件。'));
+  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('AGENTS.md')}                          ${dim('← 核心规则（AI 自动读取）')}`);
+  console.log(`   ${cyan('.agents/skills/')}`);
+  console.log(`       └── ${cyan(PKG_SHORT + '.md')}                ${dim('← 完整 API 参考（按需调取）')}`);
   console.log('');
-
-  console.log(`${bold('🔄 建议的下一步:')}`);
-  console.log(`   1. 提交 ${cyan('.agents/')} 目录到 Git 仓库，团队共享`);
-  console.log(`   2. 编写 Field 配置中的输入控件属性前，查阅 ant-design-vue 官方文档：`);
-  console.log(`      ${cyan('https://antdv.com')}`);
-  console.log(`   3. ${dim('（可选）查看完整 API 参考：')}`);
-  console.log(`      ${dim(`cat .agents/docs/${PKG_SHORT}-api.md`)}`);
+  console.log(`${bold('🔄 说明:')}`);
+  console.log(`   - AGENTS.md 已用标记区块写入，重复执行 init-ai 可安全更新（不破坏其他库的指令）`);
+  console.log(`   - 编写 Field 中输入控件属性前，查阅 ant-design-vue 官方文档：${cyan('https://antdv.com')}`);
   console.log('');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qin-ui/antd-vue-pro",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "二次封装antd vue组件",
   "bin": {
     "antd-vue-pro": "./bin/init-ai.mjs"
@@ -42,11 +42,11 @@
   },
   "dependencies": {
     "scroll-into-view-if-needed": "^3.1.0",
-    "@qin-ui/pro-components-core": "^1.0.1"
+    "vue-component-type-helpers": "^3.2.5",
+    "@qin-ui/pro-components-core": "^1.0.3"
   },
   "devDependencies": {
-    "ant-design-vue": "^4",
-    "vue-component-type-helpers": "^3.2.5"
+    "ant-design-vue": "^4"
   },
   "sideEffects": [
     "**/*.css",