@qin-ui/element-plus-pro 1.1.2 → 1.1.3

package/api.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-07-13T07:57:16.966Z",
+  "generatedAt": "2026-07-15T06:31:48.872Z",
   "name": "@qin-ui/element-plus-pro",
   "api": [
     {
@@ -8,6 +8,20 @@
       "package": "@qin-ui/element-plus-pro",
       "signature": "<ProComponentProvider>",
       "description": "@qin-ui/element-plus-pro 全局配置提供者组件\n用于在组件树的顶层配置所有子组件的全局默认属性。",
+      "params": [
+        {
+          "name": "componentVars",
+          "type": "ComponentVars",
+          "optional": true,
+          "description": "组件全局配置变量"
+        },
+        {
+          "name": "componentMap",
+          "type": "Record<ComponentName, any>",
+          "optional": true,
+          "description": "自定义组件映射"
+        }
+      ],
       "examples": [
         "```vue\n<ProComponentProvider\n:componentVars=\"{ 'input': { placeholder: '请输入' } }\"\n>\n<ProForm :form=\"form\" />\n</ProComponentProvider>\n```"
       ]
@@ -25,6 +39,20 @@
       "package": "@qin-ui/element-plus-pro",
       "signature": "<ProForm>",
       "description": "@qin-ui/element-plus-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- 字段联动、嵌套字段、自定义组件、网格布局",
+      "params": [
+        {
+          "name": "form",
+          "type": "F",
+          "optional": true,
+          "description": "useForm 返回的表单实例"
+        },
+        {
+          "name": "grid",
+          "type": "boolean | GridProps",
+          "optional": true,
+          "description": "是否启用网格布局 (默认 false)"
+        }
+      ],
       "typeParams": [
         {
           "name": "F"
@@ -61,6 +89,14 @@
       "package": "@qin-ui/element-plus-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": [
         {
@@ -77,6 +113,14 @@
       "package": "@qin-ui/element-plus-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`，将泛型参数绑定为 Element Plus 的本地类型：\n- 字段类型 F -> `Field<ComponentName, D>`（支持 Element Plus 组件类型推导）\n- FormItem 实例 -> Element Plus 的 `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": [
         {
@@ -118,6 +162,26 @@
       "package": "@qin-ui/element-plus-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`，将泛型参数绑定为 Element Plus 的本地类型：\n- 字段类型 F -> `Field<ComponentName, D>`（支持 Element Plus 所有内置组件类型推导）\n- 表单实例 -> Element Plus 的 `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": [
         {
@@ -220,6 +284,36 @@
           "type": "object",
           "optional": false,
           "description": "表格配置参数"
+        },
+        {
+          "name": "params.columns",
+          "type": "Columns<T>",
+          "optional": true,
+          "description": "初始列配置数组"
+        },
+        {
+          "name": "params.data",
+          "type": "T[]",
+          "optional": true,
+          "description": "初始数据源（Element Plus 风格）"
+        },
+        {
+          "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/element-plus-pro AI 上下文初始化 CLI 工具
  *
- * 在消费方项目中生成分层 AI 上下文文件，使 AI 工具能够：
- * 1. 理解 @qin-ui/element-plus-pro 的 Schema 驱动架构
- * 2. 掌握属性透传规则（何时查阅 element-plus 文档）
- * 3. 快速获取完整 API 参考
+ * 在消费方项目中生成双载体 AI 上下文：
+ * 1. 根目录 AGENTS.md -- 核心使用规则，跨工具自动注入（主载体）
+ * 2. .agents/skills/{pkg}.md -- 完整 API 参考，支持 skills 发现的工具按需调取（参考载体）
  *
  * 用法:
  *   npx @qin-ui/element-plus-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,59 +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 层）
- * 包含：架构关系、透传规则、反模式、element-plus 资源链接
+ * 生成 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 元数据（函数签名、类型定义）`,
-    '',
-    '## element-plus 文档资源',
-    '',
-    '所有在 Field 配置中编写的非保留属性，最终会透传给 element-plus 组件。编写前务必查阅文档确认属性名：',
-    '',
-    '| 资源 | URL | 说明 |',
-    '|:--|:--|:--|',
-    '| element-plus 官网 | https://element-plus.org/ | 官方文档首页（中文/英文） |',
-    '| 组件文档 | https://element-plus.org/zh-CN/component/button | 组件 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('');
@@ -124,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 = {
@@ -198,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     显示帮助信息
@@ -256,48 +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(`   基于 element-plus 的 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. 查阅 element-plus 官方文档确认组件属性：`);
-  console.log(`      ${cyan('https://element-plus.org/')}`);
-  console.log(`   3. ${dim('（可选）将 element-plus 常用组件 API 速查加入项目文档')}`);
+  console.log(`${bold('🔄 说明:')}`);
+  console.log(`   - AGENTS.md 已用标记区块写入，重复执行 init-ai 可安全更新（不破坏其他库的指令）`);
+  console.log(`   - 编写 Field 中输入控件属性前，查阅 element-plus 官方文档：${cyan('https://element-plus.org')}`);
   console.log('');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qin-ui/element-plus-pro",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "基于 element-plus 的二次封装组件",
   "bin": {
     "element-plus-pro": "./bin/init-ai.mjs"
@@ -38,11 +38,11 @@
     "vue": "^3.5.0"
   },
   "dependencies": {
-    "@qin-ui/pro-components-core": "^1.0.2"
+    "vue-component-type-helpers": "^3.2.5",
+    "@qin-ui/pro-components-core": "^1.0.3"
   },
   "devDependencies": {
-    "element-plus": "^2.13.6",
-    "vue-component-type-helpers": "^3.2.5"
+    "element-plus": "^2.13.6"
   },
   "sideEffects": [
     "**/*.css",