pull-apifox 1.0.0 → 1.1.1

package/README.md

@@ -10,7 +10,7 @@ npm install -g pull-apifox
 
 ## 快速开始
 
-### 1. 在项目根目录创建 `apifox.config.json`
+### 1. 创建配置文件 `apifox.config.json`
 
 ```json
 {
@@ -21,7 +21,11 @@ npm install -g pull-apifox
   "importPath": "@/utils/request",
 
   "pull": [
-    { "tags": ["移库单管理"], "name": "womeiTransfer", "prefix": "/chainova/womei" }
+    {
+      "tags": ["移库单管理"],
+      "name": "womeiTransfer",
+      "prefix": "/chainova/wms"
+    }
   ]
 }
 ```
@@ -34,45 +38,146 @@ pull-apifox
 pull-apifox ./path/to/apifox.config.json
 ```
 
-## 配置项
+## 配置文件
+
+### 顶层配置
 
 | 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `projectId` | string | **必填** | Apifox 项目 ID |
-| `accessToken` | string | — | Apifox 令牌，填了走云端 API |
+| `projectId` | string | **必填** | Apifox 项目 ID，从项目 URL 中获取 |
+| `accessToken` | string | — | Apifox 访问令牌，填了走云端 API，不填走本地客户端 |
 | `localPort` | number | `4523` | 本地客户端端口 |
-| `output` | string | `./src/apifox` | 输出目录 |
-| `showReturns` | boolean | `false` | 是否生成返回值 JSDoc |
-| `importPath` | string | `@/utils/request` | request 导入路径 |
-| `pull` | array | **必填** | 拉取任务列表 |
+| `output` | string | `./src/apifox` | 默认输出目录 |
+| `showReturns` | boolean | `false` | 是否在 JSDoc 中展开返回值类型 |
+| `importPath` | string | `@/utils/request` | 生成的 import 语句中的 request 路径 |
+| `pull` | array | **必填** | 拉取任务列表，每项生成一个 JS 文件 |
+
+### pull 筛选规则
+
+每项支持三个筛选维度，**folder 为 AND 划定范围，tags 与 apis 为 OR 取并集**：
+
+| 字段 | 类型 | 说明 | 示例 |
+|------|------|------|------|
+| `folder` | string | Apifox 接口文档 ID（数字）或 URL 路径前缀 | `"83863684"` 或 `"/movement-orders"` |
+| `tags` | string[] | Apifox 标签，支持层级模糊匹配 | `["移库单管理"]` 可匹配 `"沃美/移库单管理"` |
+| `apis` | string[] | 接口名关键词；以 `/` 开头时精确匹配路径 | `["login"]` 或 `["/storage/location/list"]` |
+
+### pull 输出配置
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `name` | string | 生成的文件名，如 `"user"` → `user.js`。指定后所有命中接口合并到此文件 |
+| `prefix` | string | 请求路径前缀，会加到每个 URL 前面 |
+| `output` | string | 可选的独立输出目录，覆盖顶层 `output` |
+
+### 筛选逻辑详解
+
+```
+folder AND (tags OR apis)
+```
+
+- **folder** 为 AND：先划定范围（接口文档 ID 通过 Apifox API scope 限定，路径字符串通过 URL 前缀匹配）
+- **tags 与 apis** 为 OR：只要满足任一条件即命中
+- 未指定的维度视为「全部匹配」
+
+**`apis` 匹配规则：**
+
+| 关键词格式 | 匹配方式 | 示例 |
+|-----------|---------|------|
+| 以 `/` 开头 | **精确路径** | `"/storage/location/list"` 只匹配该路径 |
+| 其他 | **模糊匹配** | `"login"` 匹配 operationId、summary、路径末段 |
+
+**`tags` 匹配规则：**
+
+Apifox 导出的标签通常包含层级路径，如 `沃美/移库单管理`。配置 `"移库单管理"` 即可匹配，支持：
+- 完全相等：`"移库单管理"` = `"移库单管理"`
+- 末级匹配：`"移库单管理"` 匹配 `"沃美/移库单管理"`
+- 中间层级：`"沃美"` 匹配 `"沃美/移库单管理"`
+
+**`folder` 规则：**
+
+- 纯数字（如 `"83863684"`）→ 作为 Apifox 接口文档 ID，通过 API scope 限定拉取范围；API 不支持时退化到全量拉取
+- 路径字符串（如 `"/movement-orders"`）→ URL 前缀匹配，子路径自动包含
+
+## 配置示例
+
+### 按接口文档 ID 拉取
+
+```json
+{
+  "projectId": "1577893",
+  "accessToken": "afxp_xxxxxx",
+  "output": "./src/apifox",
+
+  "pull": [
+    {
+      "folder": "83863684",
+      "tags": ["移库单管理"],
+      "apis": ["/storage/location/list"],
+      "name": "womeiTransfer",
+      "prefix": "/chainova/wms"
+    }
+  ]
+}
+```
+
+> `folder: "83863684"` 限定接口文档范围，`tags` + `apis` 在范围内取并集。
+
+### 按路径前缀拉取
+
+```json
+{
+  "pull": [
+    {
+      "folder": "/movement-orders",
+      "name": "movement",
+      "prefix": "/chainova/wms"
+    }
+  ]
+}
+```
 
-### pull 配置
+> 匹配所有 `/movement-orders/xxx` 下的接口。
 
-每项生成一个 JS 文件，三个筛选维度**取交集**：
+### 多组拉取
 
 ```json
 {
-  "tags": ["移库单管理"],        // Apifox 文件夹名，支持层级模糊匹配
-  "folder": "/movement-orders",  // URL 路径前缀匹配
-  "apis": ["login", "order"],    // 接口名关键词
-  "name": "womeiTransfer",       // 生成文件名
-  "prefix": "/chainova/womei"    // 请求路径前缀
+  "pull": [
+    {
+      "tags": ["移库单管理"],
+      "name": "womeiTransfer",
+      "prefix": "/chainova/wms"
+    },
+    {
+      "apis": ["/lite/logical/inventory/transaction/page"],
+      "name": "transaction",
+      "prefix": "/chainova/wms"
+    },
+    {
+      "tags": ["项目管理"],
+      "name": "projectManager",
+      "prefix": "/chainova/srm"
+    }
+  ]
 }
 ```
 
-> `tags` 对应 Apifox 文件夹层级路径（如 `沃美/移库单管理`），配 `"移库单管理"` 即可匹配。
+> 同 folder 的组会复用缓存，避免重复拉取。
 
-## 获取 Token
+## 获取 Access Token
 
-Apifox 网页 → 头像 → 账号设置 → 访问令牌 → 新建令牌。
+1. 打开 [Apifox](https://app.apifox.com)
+2. 右上角头像 → **账号设置** → **访问令牌**
+3. 点击 **新建令牌**，复制填入 `accessToken`
 
 ## 生成结果
 
 ```
 src/apifox/
-├── index.js            # 入口文件，聚合导出
+├── index.js                  # 入口，聚合导出
 └── api/
-    └── womeiTransfer.js  # 接口函数，带 JSDoc
+    └── womeiTransfer.js       # 接口函数，带完整 JSDoc
 ```
 
 ### 生成代码示例
@@ -93,17 +198,45 @@ import request from '@/utils/request';
  * @param {number} data.items[].quantity - 数量
  * @returns {Promise<object>} - 响应数据
  * @param {number} returns.code - 状态码
- * @param {string} returns.msg - 消息
+ * @param {string} returns.message - 返回消息
  */
 export function createMovementOrder(data) {
   return request({
-    url: '/chainova/womei/movement-orders/create',
+    url: '/chainova/wms/movement-orders/create',
     method: 'POST',
     data,
   });
 }
 ```
 
+### 函数参数命名规则
+
+| 参数位置 | 形参名 | 说明 |
+|----------|--------|------|
+| 路径参数 `{id}` | `id` | 直接展开为独立参数 |
+| 查询参数 `?page=1` | `params` | 所有 query 合并为一个 object |
+| 请求体 | `data` | body 对象 |
+
+## 在业务代码中使用
+
+```js
+// 从入口聚合导入
+import { createMovementOrder, getMovementOrderList } from '@/apifox';
+
+// 或按文件导入
+import { createMovementOrder } from '@/apifox/api/womeiTransfer';
+```
+
+## 更新接口
+
+Apifox 上接口变更后，重新运行即可覆盖生成文件：
+
+```bash
+pull-apifox
+```
+
+生成文件头部已标注 `由 pull-apifox 自动生成，请勿手动修改`。建议通过修改配置文件来调整输出，而不是直接改生成文件。
+
 ## License
 
 MIT

package/lib/index.js

@@ -53,10 +53,11 @@ async function fetchSpec(projectId, scope, config) {
   const token = config.accessToken;
 
   if (token) {
+    // 云端 API
     const url = `https://api.apifox.com/api/v1/projects/${projectId}/export-openapi`;
     console.log(`   📡 云端 API: ${projectId}`);
     const body = scope
-      ? { exportFormat: 'OpenAPI3.0', scope }
+      ? { exportFormat: 'OpenAPI3.0', scope: { type: 'SELECTED_FOLDERS', folderIds: [scope] } }
       : { exportFormat: 'OpenAPI3.0' };
 
     return request(url, {
@@ -68,6 +69,7 @@ async function fetchSpec(projectId, scope, config) {
       },
     });
   } else {
+    // 本地客户端
     const port = config.localPort || 4523;
     const url = `http://127.0.0.1:${port}/export/openapi/${projectId}?version=3.0`;
     console.log(`   📡 本地客户端: ${url}`);
@@ -75,7 +77,7 @@ async function fetchSpec(projectId, scope, config) {
     try {
       return await request(url, {
         method: 'POST',
-        body: scope ? { exportFormat: 'OpenAPI3.0', scope } : { exportFormat: 'OpenAPI3.0' },
+        body: scope ? { exportFormat: 'OpenAPI3.0', scope: { type: 'SELECTED_FOLDERS', folderIds: [scope] } } : { exportFormat: 'OpenAPI3.0' },
       });
     } catch {
       return request(url);
@@ -85,9 +87,20 @@ async function fetchSpec(projectId, scope, config) {
 
 // ======================== 筛选引擎 ========================
 
+/**
+ * 检查接口名是否匹配
+ * - 以 / 开头 → 精确路径匹配
+ * - 否则 → 模糊匹配 operationId / summary / 路径末段 / 完整路径
+ */
 function matchApiName(operation, route, keyword) {
   const kw = keyword.toLowerCase();
 
+  // 关键词以 / 开头 → 精确路径匹配
+  if (keyword.startsWith('/')) {
+    return route.toLowerCase() === kw;
+  }
+
+  // 模糊匹配
   if (operation.operationId && operation.operationId.toLowerCase().includes(kw)) return true;
   if (operation.summary && operation.summary.toLowerCase().includes(kw)) return true;
 
@@ -98,6 +111,10 @@ function matchApiName(operation, route, keyword) {
   return false;
 }
 
+/**
+ * 检查接口是否命中 tags 筛选
+ * 支持层级匹配："移库单管理" → 匹配 "沃美/移库单管理"
+ */
 function matchTags(operation, tags) {
   if (!tags || tags.length === 0) return true;
   const opTags = (operation.tags || []).map(t => t.toLowerCase());
@@ -107,22 +124,47 @@ function matchTags(operation, tags) {
   });
 }
 
+/**
+ * 检查接口路径是否在指定文件夹下
+ * - 数字 ID（如 "83863684"）→ 由 API scope 层面处理，此处直接放行
+ * - 路径字符串 → URL 前缀匹配（如 folder="/用户/登录" 匹配 /用户/登录/xxx）
+ */
 function matchFolder(route, folder) {
   if (!folder) return true;
+  // 数字 ID（Apifox 接口文档 ID），非 URL 路径，放行由 scope 处理
+  if (/^\d+$/.test(folder)) return true;
+  // URL 路径前缀匹配
   const normalizedRoute = route.startsWith('/') ? route : `/${route}`;
   const normalizedFolder = folder.startsWith('/') ? folder : `/${folder}`;
   return normalizedRoute === normalizedFolder || normalizedRoute.startsWith(normalizedFolder + '/');
 }
 
+/**
+ * 筛选逻辑：
+ * - folder 为 AND（划定范围，数字 ID 由 API scope 处理）
+ * - tags 与 apis 之间为 OR（取并集）
+ * - 两者都未指定时通过所有接口
+ */
 function matchAll(route, methodObj, operation, filters) {
+  // folder 筛选（AND）
   if (filters.folder && !matchFolder(route, filters.folder)) return false;
-  if (filters.tags && filters.tags.length > 0 && !matchTags(operation, filters.tags)) return false;
-  if (filters.apis && filters.apis.length > 0) {
-    if (!filters.apis.some(kw => matchApiName(operation, route, kw))) return false;
-  }
-  return true;
+
+  const hasTags = filters.tags && filters.tags.length > 0;
+  const hasApis = filters.apis && filters.apis.length > 0;
+
+  // 既没指定 tags 也没指定 apis → 全部通过
+  if (!hasTags && !hasApis) return true;
+
+  // tags 与 apis 取并集（OR）
+  const matchT = hasTags && matchTags(operation, filters.tags);
+  const matchA = hasApis && filters.apis.some(kw => matchApiName(operation, route, kw));
+
+  return matchT || matchA;
 }
 
+/**
+ * 对 OpenAPI spec 执行筛选，返回新的 spec
+ */
 function filterSpec(spec, filters) {
   const result = JSON.parse(JSON.stringify(spec));
   const allCount = Object.keys(result.paths || {}).length;
@@ -181,6 +223,139 @@ function toFuncName(operation, method, route) {
   return toCamel(`${method}_${route.replace(/[\/{}]/g, '_')}`);
 }
 
+/**
+ * 写入单个接口函数到 lines 数组
+ */
+function writeApiFunc(lines, route, method, operation, spec, showReturns, pathPrefix, reqImport) {
+  const funcName = toFuncName(operation, method, route);
+
+  const pathParams = (operation.parameters || []).filter(p => p.in === 'path').map(p => p.name);
+  const queryParams = (operation.parameters || []).filter(p => p.in === 'query').map(p => p.name);
+  const hasBody = ['POST', 'PUT', 'PATCH'].includes(method) && operation.requestBody;
+
+  const paramParts = [];
+  if (pathParams.length) paramParts.push(pathParams.join(', '));
+  if (queryParams.length) paramParts.push('params');
+  if (hasBody) paramParts.push('data');
+
+  lines.push(buildJSDoc(operation, method, route, funcName, spec, showReturns));
+  lines.push(`export function ${funcName}(${paramParts.join(', ')}) {`);
+
+  const fullPath = pathPrefix + route;
+  const urlExpr = pathParams.length
+    ? '`' + fullPath.replace(/\{(\w+)\}/g, '${$1}') + '`'
+    : `'${fullPath}'`;
+
+  lines.push(`  return request({`);
+  lines.push(`    url: ${urlExpr},`);
+  lines.push(`    method: '${method}',`);
+  if (queryParams.length) lines.push(`    params,`);
+  if (hasBody) {
+    const ct = Object.keys(operation.requestBody?.content || { 'application/json': {} })[0];
+    lines.push(`    data,`);
+    if (ct !== 'application/json') lines.push(`    headers: { 'Content-Type': '${ct}' },`);
+  }
+  lines.push(`  });`);
+  lines.push(`}\n`);
+}
+
+function generateJS(spec, outputDir, groupName, prefix, showReturns, importPath) {
+  const apiDir = path.join(outputDir, 'api');
+  fs.mkdirSync(apiDir, { recursive: true });
+
+  const paths = spec.paths || {};
+  const modules = {};
+  const pathPrefix = prefix || '';
+  const reqImport = importPath || '@/utils/request';
+
+  // 按 tag 分组；无 tag 时按路径首段分组
+  for (const [route, methods] of Object.entries(paths)) {
+    for (const [method, operation] of Object.entries(methods)) {
+      if (!operation || typeof operation !== 'object') continue;
+      let tags = operation.tags?.length ? operation.tags : null;
+      if (!tags) {
+        const seg = route.split('/').filter(Boolean)[0] || 'default';
+        tags = [seg];
+      }
+      for (const tag of tags) {
+        if (!modules[tag]) modules[tag] = [];
+        modules[tag].push({ route, method: method.toUpperCase(), operation });
+      }
+    }
+  }
+
+  const fileNames = [];
+
+  if (groupName) {
+    // 指定了 name → 所有接口合并到一个文件
+    const allApis = [];
+    const tagNames = [];
+    for (const [tag, apis] of Object.entries(modules)) {
+      allApis.push(...apis);
+      tagNames.push(tag);
+    }
+    fileNames.push(groupName);
+
+    const lines = [
+      '/**',
+      ` * ${tagNames.join(' / ')} 模块`,
+      ' * 由 pull-apifox 自动生成，请勿手动修改',
+      ' */',
+      '',
+      `import request from '${reqImport}';`,
+      '',
+    ];
+
+    for (const { route, method, operation } of allApis) {
+      writeApiFunc(lines, route, method, operation, spec, showReturns, pathPrefix, reqImport);
+    }
+
+    fs.writeFileSync(path.join(apiDir, `${groupName}.js`), lines.join('\n'), 'utf-8');
+    console.log(`   ✅ ${groupName}.js (${allApis.length} 个接口)`);
+  } else {
+    // 未指定 name → 每个 tag 一个文件
+    for (const [tag, apis] of Object.entries(modules)) {
+      let fileName;
+      if (isAscii(tag) && tag !== 'default') {
+        fileName = tag.replace(/[^a-zA-Z0-9]/g, '_');
+      } else {
+        fileName = deriveModuleName(apis);
+      }
+      fileNames.push(fileName);
+
+      const lines = [
+        '/**',
+        ` * ${tag} 模块`,
+        ' * 由 pull-apifox 自动生成，请勿手动修改',
+        ' */',
+        '',
+        `import request from '${reqImport}';`,
+        '',
+      ];
+
+      for (const { route, method, operation } of apis) {
+        writeApiFunc(lines, route, method, operation, spec, showReturns, pathPrefix, reqImport);
+      }
+
+      fs.writeFileSync(path.join(apiDir, `${fileName}.js`), lines.join('\n'), 'utf-8');
+      console.log(`   ✅ ${fileName}.js (${apis.length} 个接口)`);
+    }
+  }
+
+  // 入口文件
+  if (fileNames.length > 0) {
+    const indexLines = fileNames
+      .map(name => `export * from './api/${name}';`)
+      .join('\n');
+    fs.writeFileSync(path.join(outputDir, 'index.js'), indexLines + '\n', 'utf-8');
+  } else {
+    console.log('   ⚠ 没有匹配到接口，请检查筛选条件（folder/tags/apis）是否正确');
+  }
+}
+
+/**
+ * 解析 $ref 引用（支持 '#/components/schemas/XXX'）
+ */
 function resolveRef(schema, fullSpec) {
   if (!schema) return schema;
   if (schema.$ref) {
@@ -192,6 +367,9 @@ function resolveRef(schema, fullSpec) {
   return schema;
 }
 
+/**
+ * 将 OpenAPI schema 转为 JSDoc 类型字符串
+ */
 function toJSDocType(schema, fullSpec) {
   const resolved = resolveRef(schema, fullSpec);
   if (!resolved || !resolved.type) return 'any';
@@ -209,6 +387,9 @@ function toJSDocType(schema, fullSpec) {
   }
 }
 
+/**
+ * 为接口函数生成完整 JSDoc 注释
+ */
 function buildJSDoc(operation, method, route, funcName, fullSpec, showReturns) {
   const lines = [];
   const allParams = operation.parameters || [];
@@ -220,6 +401,7 @@ function buildJSDoc(operation, method, route, funcName, fullSpec, showReturns) {
     : null;
   const bodySchema = resolveRef(rawBodySchema, fullSpec);
 
+  // 响应体 schema
   const rawRespSchema = showReturns
     ? (operation.responses?.['200']?.content?.['application/json']?.schema
       || operation.responses?.['201']?.content?.['application/json']?.schema
@@ -229,6 +411,7 @@ function buildJSDoc(operation, method, route, funcName, fullSpec, showReturns) {
 
   lines.push('/**');
 
+  // 标题：优先 summary > description > funcName
   const title = operation.summary || operation.description || funcName;
   lines.push(` * ${title}`);
   if (operation.summary && operation.description && operation.description !== operation.summary) {
@@ -238,6 +421,7 @@ function buildJSDoc(operation, method, route, funcName, fullSpec, showReturns) {
   lines.push(' *');
   lines.push(` * ${method.toUpperCase()} ${route}`);
 
+  // --- 路径参数 ---
   const pathParamDefs = allParams.filter(p => p.in === 'path');
   for (const p of pathParamDefs) {
     const type = toJSDocType(p.schema, fullSpec);
@@ -245,6 +429,7 @@ function buildJSDoc(operation, method, route, funcName, fullSpec, showReturns) {
     lines.push(` * @param {${type}} ${p.name}${desc ? ` - ${desc}` : ''}`);
   }
 
+  // --- 查询参数 → 合并为 params 对象 ---
   if (queryParamDefs.length > 0) {
     const hasRequired = queryParamDefs.some(p => p.required === true);
     lines.push(` * @param {object} ${hasRequired ? '' : '['}params${hasRequired ? '' : ']'} - 查询参数`);
@@ -256,14 +441,18 @@ function buildJSDoc(operation, method, route, funcName, fullSpec, showReturns) {
     }
   }
 
+  // --- 请求体 → data 参数 ---
   if (hasBody) {
     const bodyRequired = operation.requestBody.required !== false;
     const bodyDesc = operation.requestBody.description || '请求体';
     const type = bodySchema ? toJSDocType(bodySchema, fullSpec) : 'object';
     lines.push(` * @param {${type}} ${bodyRequired ? '' : '['}data${bodyRequired ? '' : ']'} - ${bodyDesc}`);
+
+    // 递归展开 body 内部属性
     expandProperties(bodySchema, 'data', bodySchema?.required || [], fullSpec, lines, 0);
   }
 
+  // --- 返回值 ---
   if (showReturns && respSchema) {
     const respType = toJSDocType(respSchema, fullSpec);
     lines.push(` * @returns {Promise<${respType}>} - 响应数据`);
@@ -276,6 +465,9 @@ function buildJSDoc(operation, method, route, funcName, fullSpec, showReturns) {
   return lines.join('\n');
 }
 
+/**
+ * 递归展开 schema 属性，支持嵌套 object 和 object[] 类型
+ */
 function expandProperties(schema, prefix, requiredList, fullSpec, lines, depth) {
   if (depth > 3) return;
   const resolved = resolveRef(schema, fullSpec);
@@ -290,9 +482,12 @@ function expandProperties(schema, prefix, requiredList, fullSpec, lines, depth)
     const fullPath = prefix ? `${prefix}.${prop}` : prop;
     lines.push(` * @param {${propType}} ${req ? '' : '['}${fullPath}${req ? '' : ']'}${propDesc ? ` - ${propDesc}` : ''}`);
 
+    // 递归展开内嵌 object
     if (resolvedProp?.type === 'object' && resolvedProp.properties) {
       expandProperties(resolvedProp, fullPath, resolvedProp.required || [], fullSpec, lines, depth + 1);
-    } else if (resolvedProp?.type === 'array' && resolvedProp.items) {
+    }
+    // 递归展开数组中的对象 (T[])
+    else if (resolvedProp?.type === 'array' && resolvedProp.items) {
       const resolvedItems = resolveRef(resolvedProp.items, fullSpec);
       if (resolvedItems?.type === 'object' && resolvedItems.properties) {
         expandProperties(resolvedItems, fullPath + '[]', resolvedItems.required || [], fullSpec, lines, depth + 1);
@@ -301,100 +496,6 @@ function expandProperties(schema, prefix, requiredList, fullSpec, lines, depth)
   }
 }
 
-function generateJS(spec, outputDir, groupName, prefix, showReturns, importPath) {
-  const apiDir = path.join(outputDir, 'api');
-  fs.mkdirSync(apiDir, { recursive: true });
-
-  const paths = spec.paths || {};
-  const modules = {};
-  const pathPrefix = prefix || '';
-  const reqImport = importPath || '@/utils/request';
-
-  for (const [route, methods] of Object.entries(paths)) {
-    for (const [method, operation] of Object.entries(methods)) {
-      if (!operation || typeof operation !== 'object') continue;
-      let tags = operation.tags?.length ? operation.tags : null;
-      if (!tags) {
-        const seg = route.split('/').filter(Boolean)[0] || 'default';
-        tags = [seg];
-      }
-      for (const tag of tags) {
-        if (!modules[tag]) modules[tag] = [];
-        modules[tag].push({ route, method: method.toUpperCase(), operation });
-      }
-    }
-  }
-
-  const fileNames = [];
-
-  for (const [tag, apis] of Object.entries(modules)) {
-    let fileName;
-    if (groupName) {
-      fileName = groupName;
-    } else if (isAscii(tag) && tag !== 'default') {
-      fileName = tag.replace(/[^a-zA-Z0-9]/g, '_');
-    } else {
-      fileName = deriveModuleName(apis);
-    }
-    fileNames.push(fileName);
-
-    const lines = [
-      '/**',
-      ` * ${tag} 模块`,
-      ' * 由 pull-apifox 自动生成，请勿手动修改',
-      ' */',
-      '',
-      `import request from '${reqImport}';`,
-      '',
-    ];
-
-    for (const { route, method, operation } of apis) {
-      const funcName = toFuncName(operation, method, route);
-
-      const pathParams = (operation.parameters || []).filter(p => p.in === 'path').map(p => p.name);
-      const queryParams = (operation.parameters || []).filter(p => p.in === 'query').map(p => p.name);
-      const hasBody = ['POST', 'PUT', 'PATCH'].includes(method) && operation.requestBody;
-
-      const paramParts = [];
-      if (pathParams.length) paramParts.push(pathParams.join(', '));
-      if (queryParams.length) paramParts.push('params');
-      if (hasBody) paramParts.push('data');
-
-      lines.push(buildJSDoc(operation, method, route, funcName, spec, showReturns));
-      lines.push(`export function ${funcName}(${paramParts.join(', ')}) {`);
-
-      const fullPath = pathPrefix + route;
-      const urlExpr = pathParams.length
-        ? '`' + fullPath.replace(/\{(\w+)\}/g, '${$1}') + '`'
-        : `'${fullPath}'`;
-
-      lines.push('  return request({');
-      lines.push(`    url: ${urlExpr},`);
-      lines.push(`    method: '${method}',`);
-      if (queryParams.length) lines.push('    params,');
-      if (hasBody) {
-        const ct = Object.keys(operation.requestBody?.content || { 'application/json': {} })[0];
-        lines.push('    data,');
-        if (ct !== 'application/json') lines.push(`    headers: { 'Content-Type': '${ct}' },`);
-      }
-      lines.push('  });');
-      lines.push('}\n');
-    }
-
-    fs.writeFileSync(path.join(apiDir, `${fileName}.js`), lines.join('\n'), 'utf-8');
-    console.log(`   ✅ ${fileName}.js (${apis.length} 个接口)`);
-  }
-
-  if (fileNames.length > 0) {
-    const indexLines = fileNames
-      .map(name => `export * from './api/${name}';`)
-      .join('\n');
-    fs.writeFileSync(path.join(outputDir, 'index.js'), indexLines + '\n', 'utf-8');
-  } else {
-    console.log('   ⚠ 没有匹配到接口，请检查筛选条件（folder/tags/apis）是否正确');
-  }
-}
-
 // ======================== 主流程 ========================
 
 async function main() {
@@ -407,7 +508,7 @@ async function main() {
     console.log('  pull-apifox                       使用当前目录下的 apifox.config.json');
     console.log('  pull-apifox ./my-config.json      指定配置文件');
     console.log('');
-    console.log('配置文档: https://github.com/xxx/pull-apifox');
+    console.log('配置文档: https://github.com/fanwb1212/pull-apifox');
     process.exit(0);
   }
 
@@ -431,34 +532,63 @@ async function main() {
   console.log(`  拉取组数: ${config.pull.length}`);
   console.log('');
 
-  console.log('📥 拉取完整 OpenAPI 规范...');
-  const fullSpec = await fetchSpec(config.projectId, null, config);
-  const totalPaths = Object.keys(fullSpec.paths || {}).length;
-  console.log(`   📊 项目共有 ${totalPaths} 个接口\n`);
-
-  const allTags = new Set();
-  for (const methods of Object.values(fullSpec.paths || {})) {
-    for (const op of Object.values(methods)) {
-      (op.tags || []).forEach(t => allTags.add(t));
-    }
-  }
-
   const baseOutput = path.resolve(config.output || './src/apifox');
+  const specCache = {};  // 按 folder scope 缓存
 
+  // 逐组拉取 + 筛选 + 生成
   for (let i = 0; i < config.pull.length; i++) {
     const group = config.pull[i];
-    const filterLabel = group.folder || group.tags?.join(', ') || '全部接口';
-    console.log(`📦 [${i + 1}/${config.pull.length}] ${filterLabel}`);
+    const scope = group.folder || null;
+    const scopeLabel = group.folder || group.tags?.join(', ') || group.apis?.join(', ') || '全部接口';
+    console.log(`📦 [${i + 1}/${config.pull.length}] ${scopeLabel}`);
+
+    // 拉取（同 folder 复用缓存）
+    let spec;
+    const cacheKey = scope || '__full__';
+    if (specCache[cacheKey]) {
+      spec = specCache[cacheKey];
+      console.log(`   ♻ 复用缓存`);
+    } else {
+      // 先拉全量（作为回退）
+      const fullSpec = await fetchSpec(config.projectId, null, config);
+      const fullCount = Object.keys(fullSpec.paths || {}).length;
+
+      if (scope) {
+        // 尝试 scope 拉取
+        spec = await fetchSpec(config.projectId, scope, config);
+        const scopedCount = Object.keys(spec.paths || {}).length;
+        if (scopedCount < fullCount) {
+          console.log(`   📊 限定范围共 ${scopedCount} 个接口 (全量 ${fullCount})`);
+        } else {
+          console.log(`   ⚠ scope 无效，使用全量 ${fullCount} 个接口`);
+          spec = fullSpec;
+        }
+        // 缓存全量供后续无 folder 的组复用
+        specCache['__full__'] = fullSpec;
+      } else {
+        spec = fullSpec;
+        console.log(`   📊 项目共有 ${fullCount} 个接口`);
+      }
+      specCache[cacheKey] = spec;
+    }
 
-    const filtered = filterSpec(fullSpec, group);
+    // 筛选
+    const filtered = filterSpec(spec, group);
 
+    // 诊断
     if (Object.keys(filtered.paths || {}).length === 0) {
-      const kw = group.folder || group.apis?.[0] || group.tags?.[0] || '';
+      const kw = group.apis?.[0] || group.tags?.[0] || '';
       if (kw) {
-        const matchedPaths = Object.keys(fullSpec.paths || {}).filter(p => p.toLowerCase().includes(kw.toLowerCase()));
+        const matchedPaths = Object.keys(spec.paths || {}).filter(p => p.toLowerCase().includes(kw.toLowerCase()));
         if (matchedPaths.length > 0) {
           console.log(`   💡 路径中包含「${kw}」的接口: ${matchedPaths.slice(0, 10).join(', ')}${matchedPaths.length > 10 ? '...' : ''}`);
         }
+        const allTags = new Set();
+        for (const methods of Object.values(spec.paths || {})) {
+          for (const op of Object.values(methods)) {
+            (op.tags || []).forEach(t => allTags.add(t));
+          }
+        }
         const matchedTags = [...allTags].filter(t => t.toLowerCase().includes(kw.toLowerCase()));
         if (matchedTags.length > 0) {
           console.log(`   💡 标签中包含「${kw}」的: ${matchedTags.join(', ')}`);

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "pull-apifox",
-  "version": "1.0.0",
-  "description": "从 Apifox 拉取接口并生成带 JSDoc 的 JS 请求代码",
-  "keywords": ["apifox", "openapi", "codegen", "api", "jsdoc"],
+  "version": "1.1.1",
+  "description": "从 Apifox 拉取接口，按需筛选，自动生成带 JSDoc 的 JS 请求代码",
+  "keywords": [
+    "apifox",
+    "openapi",
+    "codegen",
+    "api",
+    "jsdoc"
+  ],
   "license": "MIT",
   "author": "fanwb1212",
   "main": "lib/index.js",