apifox-workspace-mcp 2.1.0 → 2.1.4

package/dist/core/generator/cursor-rules-loader.js

@@ -0,0 +1,200 @@
+/**
+ * Cursor Rules 加载器
+ * 读取并解析项目中的 Cursor Rules 规则，提取类型命名规范
+ *
+ * 规则来源（新优先级）：
+ * 1) 项目目录下 `.cursor/rules/*.mcd` （新的 Cursor Rules 规范）
+ * 2) 兼容性后备：根目录 `.cursorrules`（旧格式，已废弃）
+ */
+import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { join, extname } from 'path';
+import { logger } from '../../lib/logger.js';
+/**
+ * 从项目根目录读取 Cursor Rules
+ * @param projectRoot 项目根目录
+ * @returns 类型命名规范，如果文件不存在或解析失败则返回 null
+ */
+export function loadCursorRules(projectRoot) {
+    // 新规范：.cursor/rules/*.mcd
+    const rulesDir = join(projectRoot, '.cursor', 'rules');
+    const ruleFiles = [];
+    if (existsSync(rulesDir)) {
+        try {
+            const entries = readdirSync(rulesDir);
+            for (const entry of entries) {
+                const full = join(rulesDir, entry);
+                try {
+                    const stat = statSync(full);
+                    if (stat.isFile() && extname(entry).toLowerCase() === '.mcd') {
+                        ruleFiles.push(full);
+                    }
+                }
+                catch {
+                    // 忽略单个文件的错误
+                }
+            }
+        }
+        catch (error) {
+            logger.warn(`[cursor-rules] 读取规则目录失败: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    // 如果找到新的 .mcd 规则文件，合并解析
+    if (ruleFiles.length > 0) {
+        try {
+            const mergedContent = ruleFiles
+                .map((file) => {
+                try {
+                    return readFileSync(file, 'utf-8');
+                }
+                catch {
+                    return '';
+                }
+            })
+                .filter(Boolean)
+                .join('\n');
+            if (!mergedContent.trim()) {
+                return null;
+            }
+            logger.debug(`[cursor-rules] 使用 .cursor/rules/*.mcd 规则，共 ${ruleFiles.length} 个文件`);
+            return parseCursorRules(mergedContent);
+        }
+        catch (error) {
+            logger.warn(`[cursor-rules] 解析 .cursor/rules 下的规则失败: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    // 兼容：旧的 .cursorrules（已废弃，但保持向后兼容）
+    const legacyRulesFile = join(projectRoot, '.cursorrules');
+    if (existsSync(legacyRulesFile)) {
+        try {
+            const content = readFileSync(legacyRulesFile, 'utf-8');
+            logger.debug('[cursor-rules] 使用兼容的 .cursorrules 文件（已废弃格式）');
+            return parseCursorRules(content);
+        }
+        catch (error) {
+            logger.warn(`[cursor-rules] 读取 .cursorrules 文件失败: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
+    logger.debug('[cursor-rules] 未找到 Cursor Rules 配置（.cursor/rules/*.mcd 或 .cursorrules）');
+    return null;
+}
+/**
+ * 解析 Cursor Rules 内容
+ * @param content .cursorrules 文件内容
+ * @returns 类型命名规范
+ */
+function parseCursorRules(content) {
+    const rules = {};
+    // 解析接口命名风格
+    const interfaceStyleMatch = content.match(/(?:interface|type|命名).*?(?:style|风格).*?[:：]\s*(PascalCase|camelCase|snake_case|kebab-case)/i);
+    if (interfaceStyleMatch) {
+        rules.interfaceStyle = interfaceStyleMatch[1];
+    }
+    // 解析请求类型后缀
+    const requestSuffixMatch = content.match(/(?:request|请求).*?(?:suffix|后缀).*?[:：]\s*(\w+)/i);
+    if (requestSuffixMatch) {
+        rules.requestSuffix = requestSuffixMatch[1];
+    }
+    // 解析响应类型后缀
+    const responseSuffixMatch = content.match(/(?:response|响应).*?(?:suffix|后缀).*?[:：]\s*(\w+)/i);
+    if (responseSuffixMatch) {
+        rules.responseSuffix = responseSuffixMatch[1];
+    }
+    // 解析禁止使用的名称
+    const forbiddenMatch = content.match(/(?:forbidden|禁止|避免).*?(?:name|名称).*?[:：]\s*([^\n]+)/i);
+    if (forbiddenMatch) {
+        rules.forbiddenNames = forbiddenMatch[1]
+            .split(/[,，、]/)
+            .map((n) => n.trim())
+            .filter((n) => n.length > 0);
+    }
+    // 解析优先使用的业务语义
+    const preferredMatch = content.match(/(?:preferred|优先|推荐).*?(?:semantic|语义).*?[:：]\s*([^\n]+)/i);
+    if (preferredMatch) {
+        rules.preferredSemantics = preferredMatch[1]
+            .split(/[,，、]/)
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
+    }
+    return rules;
+}
+/**
+ * 应用 Cursor Rules 到类型名称
+ * @param typeName 原始类型名称
+ * @param rules 类型命名规范
+ * @param isRequest 是否为请求类型
+ * @returns 格式化后的类型名称
+ */
+export function applyCursorRules(typeName, rules, isRequest = false) {
+    if (!rules) {
+        return typeName;
+    }
+    let formattedName = typeName;
+    // 应用命名风格
+    if (rules.interfaceStyle) {
+        formattedName = applyNamingStyle(formattedName, rules.interfaceStyle);
+    }
+    // 应用后缀
+    if (isRequest && rules.requestSuffix) {
+        if (!formattedName.endsWith(rules.requestSuffix)) {
+            formattedName = formattedName + rules.requestSuffix;
+        }
+    }
+    else if (!isRequest && rules.responseSuffix) {
+        if (!formattedName.endsWith(rules.responseSuffix)) {
+            formattedName = formattedName + rules.responseSuffix;
+        }
+    }
+    // 检查禁止使用的名称
+    if (rules.forbiddenNames) {
+        for (const forbidden of rules.forbiddenNames) {
+            if (formattedName.includes(forbidden)) {
+                logger.warn(`[cursor-rules] 类型名称包含禁止使用的名称: ${forbidden}`);
+                // 可以在这里进行替换或警告
+            }
+        }
+    }
+    return formattedName;
+}
+/**
+ * 应用命名风格
+ * @param name 原始名称
+ * @param style 命名风格
+ * @returns 格式化后的名称
+ */
+function applyNamingStyle(name, style) {
+    switch (style) {
+        case 'PascalCase':
+            return pascalCase(name);
+        case 'camelCase':
+            return camelCase(name);
+        case 'snake_case':
+            return snakeCase(name);
+        case 'kebab-case':
+            return kebabCase(name);
+        default:
+            return name;
+    }
+}
+function pascalCase(input) {
+    return input
+        .replace(/[^a-zA-Z0-9]+(.)/g, (_, chr) => chr.toUpperCase())
+        .replace(/^[a-z]/, (chr) => chr.toUpperCase());
+}
+function camelCase(input) {
+    const pascal = pascalCase(input);
+    return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+function snakeCase(input) {
+    return input
+        .replace(/([A-Z])/g, '_$1')
+        .toLowerCase()
+        .replace(/^_/, '');
+}
+function kebabCase(input) {
+    return input
+        .replace(/([A-Z])/g, '-$1')
+        .toLowerCase()
+        .replace(/^-/, '');
+}
+//# sourceMappingURL=cursor-rules-loader.js.map

package/dist/core/generator/cursor-rules-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-rules-loader.js","sourceRoot":"","sources":["../../../src/core/generator/cursor-rules-loader.ts"],"names":[],"mappings":"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"}

package/dist/core/generator/index.d.ts

@@ -3,4 +3,7 @@
  */
 export { generateArtifact } from './artifact.js';
 export type { ArtifactInput, GeneratedArtifact, ArtifactType } from './artifact.js';
+export { transformTypeNames } from './type-transformer.js';
+export { loadCursorRules, applyCursorRules } from './cursor-rules-loader.js';
+export type { TypeNamingRules } from './cursor-rules-loader.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/generator/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/generator/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/generator/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC7E,YAAY,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/core/generator/index.js

@@ -2,4 +2,6 @@
  * 生成器模块
  */
 export { generateArtifact } from './artifact.js';
+export { transformTypeNames } from './type-transformer.js';
+export { loadCursorRules, applyCursorRules } from './cursor-rules-loader.js';
 //# sourceMappingURL=index.js.map

package/dist/core/generator/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/generator/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/generator/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/core/generator/type-transformer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 类型名称语义化转换器
+ * 将通用类型名称（如 "ApifoxModel"）转换为语义化名称（如 "CreateOrderRequest"）
+ */
+/**
+ * 转换类型定义中的类型名称
+ * @param typeCode 原始类型代码
+ * @param interfaceDetail 接口详情（name 等字段可能为 undefined）
+ * @returns 转换后的类型代码
+ */
+export declare function transformTypeNames(typeCode: string, interfaceDetail: {
+    id: string;
+    name?: string;
+    method?: string;
+    path?: string;
+    description?: string;
+}): string;
+//# sourceMappingURL=type-transformer.d.ts.map

package/dist/core/generator/type-transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-transformer.d.ts","sourceRoot":"","sources":["../../../src/core/generator/type-transformer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACA,MAAM,CAcR"}

package/dist/core/generator/type-transformer.js

@@ -0,0 +1,103 @@
+/**
+ * 类型名称语义化转换器
+ * 将通用类型名称（如 "ApifoxModel"）转换为语义化名称（如 "CreateOrderRequest"）
+ */
+/**
+ * 转换类型定义中的类型名称
+ * @param typeCode 原始类型代码
+ * @param interfaceDetail 接口详情（name 等字段可能为 undefined）
+ * @returns 转换后的类型代码
+ */
+export function transformTypeNames(typeCode, interfaceDetail) {
+    // 提取接口的语义化名称
+    const semanticName = generateSemanticName(interfaceDetail);
+    // 替换通用类型名称
+    let transformedCode = typeCode;
+    // 替换 "ApifoxModel" 为语义化名称
+    transformedCode = transformedCode.replace(/ApifoxModel/g, semanticName);
+    // 替换其他通用类型名称（如果它们出现在不合适的位置）
+    // 这里可以根据实际需要进行更复杂的替换逻辑
+    return transformedCode;
+}
+/**
+ * 根据接口信息生成语义化名称
+ * @param interfaceDetail 接口详情（name 等字段可能为 undefined）
+ * @returns 语义化名称（PascalCase）
+ */
+function generateSemanticName(interfaceDetail) {
+    const { name, method, path } = interfaceDetail;
+    // 从接口名称提取关键词
+    const nameKeywords = extractKeywords(name || '');
+    // 从路径提取关键词
+    const pathKeywords = extractKeywords(path || '');
+    // 根据 HTTP 方法确定操作类型
+    const operationType = getOperationType(method || 'GET');
+    // 组合生成语义化名称
+    let semanticName = '';
+    if (nameKeywords.length > 0) {
+        // 优先使用接口名称中的关键词
+        semanticName = nameKeywords.join('');
+    }
+    else if (pathKeywords.length > 0) {
+        // 其次使用路径中的关键词
+        semanticName = pathKeywords.join('');
+    }
+    else {
+        // 最后使用默认名称
+        semanticName = 'Api';
+    }
+    // 添加操作类型前缀（如果需要）
+    if (operationType && !semanticName.toLowerCase().includes(operationType.toLowerCase())) {
+        semanticName = operationType + semanticName;
+    }
+    return pascalCase(semanticName);
+}
+/**
+ * 从文本中提取关键词
+ * @param text 文本
+ * @returns 关键词数组（已转换为 PascalCase）
+ */
+function extractKeywords(text) {
+    // 移除特殊字符，保留中英文、数字
+    const cleaned = text.replace(/[^\u4e00-\u9fa5a-zA-Z0-9\s]/g, ' ');
+    // 分割为单词
+    const words = cleaned
+        .split(/\s+/)
+        .filter((w) => w.length > 0)
+        .map((w) => pascalCase(w));
+    return words;
+}
+/**
+ * 根据 HTTP 方法确定操作类型
+ * @param method HTTP 方法
+ * @returns 操作类型（如 "Create", "Update", "Get" 等）
+ */
+function getOperationType(method) {
+    const upperMethod = method.toUpperCase();
+    const operationMap = {
+        GET: 'Get',
+        POST: 'Create',
+        PUT: 'Update',
+        PATCH: 'Update',
+        DELETE: 'Delete',
+    };
+    return operationMap[upperMethod] || '';
+}
+/**
+ * 转换为 PascalCase
+ * @param input 输入字符串
+ * @returns PascalCase 字符串
+ */
+function pascalCase(input) {
+    if (!input)
+        return '';
+    // 处理中文：直接返回（中文通常不需要转换）
+    if (/[\u4e00-\u9fa5]/.test(input)) {
+        return input;
+    }
+    // 处理英文：转换为 PascalCase
+    return input
+        .replace(/[^a-zA-Z0-9]+(.)/g, (_, chr) => chr.toUpperCase())
+        .replace(/^[a-z]/, (chr) => chr.toUpperCase());
+}
+//# sourceMappingURL=type-transformer.js.map

package/dist/core/generator/type-transformer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-transformer.js","sourceRoot":"","sources":["../../../src/core/generator/type-transformer.ts"],"names":[],"mappings":"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"}

package/dist/server/handlers/generate-artifacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-artifacts.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/generate-artifacts.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EAIb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIxD,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,YAAY,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,aAAa,CAAC;IAC7B,SAAS,EAAE,SAAS,CAAC;IACrB,YAAY,EAAE,YAAY,CAAC;CAC5B;AAYD;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,qBAAqB,EAC3B,GAAG,EAAE,wBAAwB;;;;;;;;;;;GA6K9B"}
+{"version":3,"file":"generate-artifacts.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/generate-artifacts.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EAGb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIxD,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,YAAY,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,aAAa,CAAC;IAC7B,SAAS,EAAE,SAAS,CAAC;IACrB,YAAY,EAAE,YAAY,CAAC;CAC5B;AAYD;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,qBAAqB,EAC3B,GAAG,EAAE,wBAAwB;;;;;;;;;;;GAoK9B"}

package/dist/server/handlers/generate-artifacts.js

@@ -1,6 +1,6 @@
 import { writeFileSync } from 'fs';
 import { join } from 'path';
-import { generateArtifact, UnifiedCacheManager, parseInterfaceFromMd, } from '../../core/index.js';
+import { UnifiedCacheManager, generateArtifact, } from '../../core/index.js';
 import { resolveProjectInfo, buildTextResponse, buildMissingTokenResponse } from './utils.js';
 import { logger } from '../../lib/logger.js';
 /**
@@ -25,6 +25,7 @@ export async function handleGenerateArtifacts(args, ctx) {
     if (!accessToken) {
         return buildMissingTokenResponse();
     }
+    const cacheManager = new UnifiedCacheManager(projectRoot);
     let interfaceIds = (args.interfaceIds || []).filter(Boolean);
     // 尝试从选择中获取接口 ID
     if (interfaceIds.length === 0) {
@@ -50,43 +51,39 @@ export async function handleGenerateArtifacts(args, ctx) {
     }
     const artifacts = [];
     const errors = [];
-    const cacheManager = new UnifiedCacheManager(projectRoot);
-    let cacheHitCount = 0;
     let mcpCallCount = 0;
     for (const id of interfaceIds) {
         try {
-            let detail;
-            // 优化：优先从缓存的 md 文件读取接口详情
-            const cachedInterface = cacheManager.findInterface(projectInfo.projectName, id, projectInfo.projectId);
-            if (cachedInterface && cachedInterface.docUrl) {
-                logger.debug(`[generate_artifacts] 接口 ${id} 在缓存中，从 md 文件读取（不消耗 token）`);
+            // 生成类型文件时，始终调用 Apifox MCP Server 获取准确的接口详情
+            // 使用官方能力，确保类型信息的准确性和完整性
+            logger.debug(`[generate_artifacts] 调用 Apifox MCP Server 获取接口 ${id} 的详情（消耗 token）`);
+            const detail = await mcpBridge.getInterfaceDetailViaMcp(accessToken, projectInfo.projectName, projectInfo.projectId, id);
+            mcpCallCount++;
+            // 回写接口基础信息到缓存（docUrl 可能缺失，后续 llms 刷新补齐）
+            cacheManager.upsertInterfaceDetail(projectInfo.projectName, projectInfo.projectId, {
+                id: detail.id,
+                name: detail.name,
+            });
+            // 如果是生成类型文件，尝试从官方 MCP Server 获取 OpenAPI Spec
+            let rawTypeCode;
+            if (args.artifactType === 'ts_types') {
                 try {
-                    detail = await parseInterfaceFromMd(cachedInterface.docUrl);
-                    if (detail) {
-                        cacheHitCount++;
-                        logger.info(`[generate_artifacts] ✅ 从缓存 md 文件成功获取接口 ${id} 的详情`);
-                    }
-                    else {
-                        logger.warn(`[generate_artifacts] ⚠️ 从 md 文件解析接口 ${id} 失败，回退到 MCP Server`);
-                        throw new Error('从 md 文件解析失败');
-                    }
+                    logger.debug(`[generate_artifacts] 尝试从官方 MCP Server 获取 OpenAPI Spec...`);
+                    await mcpBridge.readOpenApiSpecViaMcp(accessToken, projectInfo.projectId);
+                    // 如果获取成功，尝试从 OpenAPI Spec 中提取该接口的类型定义
+                    // 注意：这里需要解析 OpenAPI Spec，暂时先跳过，使用原有逻辑
+                    // TODO: 实现 OpenAPI Spec 解析逻辑
+                    logger.debug(`[generate_artifacts] OpenAPI Spec 获取成功，但类型提取功能待实现`);
                 }
-                catch (mdError) {
-                    logger.warn(`[generate_artifacts] 从 md 文件读取接口 ${id} 失败: ${mdError instanceof Error ? mdError.message : String(mdError)}`);
-                    logger.debug(`[generate_artifacts] 回退到 MCP Server 获取接口 ${id} 的详情（消耗 token）`);
-                    // 回退到 MCP Server
-                    detail = await mcpBridge.getInterfaceDetailViaMcp(accessToken, projectInfo.projectName, projectInfo.projectId, id);
-                    mcpCallCount++;
+                catch (specError) {
+                    // OpenAPI Spec 读取失败，使用原有逻辑生成类型
+                    logger.debug(`[generate_artifacts] OpenAPI Spec 读取失败，使用接口详情生成类型: ${specError instanceof Error ? specError.message : String(specError)}`);
                 }
             }
-            else {
-                logger.debug(`[generate_artifacts] 接口 ${id} 不在缓存中，调用 MCP Server（消耗 token）`);
-                // 缓存中没有，调用 MCP Server
-                detail = await mcpBridge.getInterfaceDetailViaMcp(accessToken, projectInfo.projectName, projectInfo.projectId, id);
-                mcpCallCount++;
-            }
             artifacts.push(generateArtifact(args.artifactType ?? 'ts_types', {
                 interfaceDetail: detail,
+                projectRoot,
+                rawTypeCode,
             }));
         }
         catch (error) {
@@ -94,8 +91,8 @@ export async function handleGenerateArtifacts(args, ctx) {
         }
     }
     // 记录 token 消耗情况
-    if (cacheHitCount > 0 || mcpCallCount > 0) {
-        logger.info(`[generate_artifacts] Token 消耗统计: 缓存命中 ${cacheHitCount} 个，MCP 调用 ${mcpCallCount} 个（消耗 token）`);
+    if (mcpCallCount > 0) {
+        logger.info(`[generate_artifacts] Token 消耗统计: MCP 调用 ${mcpCallCount} 个接口（消耗 token）`);
     }
     if (errors.length > 0) {
         if (artifacts.length === 0) {

package/dist/server/handlers/generate-artifacts.js.map

@@ -1 +1 @@
-{"version":3,"file":"generate-artifacts.js","sourceRoot":"","sources":["../../../src/server/handlers/generate-artifacts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"generate-artifacts.js","sourceRoot":"","sources":["../../../src/server/handlers/generate-artifacts.ts"],"names":[],"mappings":"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"}

package/dist/server/handlers/get-interface-detail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-interface-detail.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/get-interface-detail.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EAQb,MAAM,qBAAqB,CAAC;AAU7B,MAAM,WAAW,sBAAsB;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,aAAa,CAAC;IAC7B,SAAS,EAAE,SAAS,CAAC;IACrB,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,sBAAsB,EAC5B,GAAG,EAAE,yBAAyB;;;;;;;;;;;;GAsR/B"}
+{"version":3,"file":"get-interface-detail.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/get-interface-detail.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EAOb,MAAM,qBAAqB,CAAC;AAU7B,MAAM,WAAW,sBAAsB;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,aAAa,CAAC;IAC7B,SAAS,EAAE,SAAS,CAAC;IACrB,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,sBAAsB,EAC5B,GAAG,EAAE,yBAAyB;;;;;;;;;;;;GAuP/B"}

package/dist/server/handlers/get-interface-detail.js

@@ -1,4 +1,4 @@
-import { generateArtifact, UnifiedCacheManager, parseApifoxUrl, isValidApifoxUrl, parseInterfaceFromMd, fetchAndParseLlmsWithHash, } from '../../core/index.js';
+import { generateArtifact, UnifiedCacheManager, parseApifoxUrl, isValidApifoxUrl, fetchAndParseLlmsWithHash, parseInterfaceFromMd, } from '../../core/index.js';
 import { logger } from '../../lib/logger.js';
 import { resolveProjectInfo, buildTextResponse, buildMissingTokenResponse, buildCurlSnippet, buildFetchSnippet, } from './utils.js';
 /**
@@ -62,78 +62,50 @@ export async function handleGetInterfaceDetail(args, ctx) {
             logger.info(`缓存已刷新: ${refreshResult.reason}`);
         }
     }
-    // 刷新后重新获取 cachedInterface（确保是最新的）
+    // 读取接口信息时，优先从 MD 文件读取（不消耗 Token）
+    // 仅在 MD 解析失败时回退到官方 MCP Server
     const cachedInterface = cacheManager.findInterface(projectInfo.projectName, args.interfaceId, projectInfo.projectId);
+    let detail;
     if (cachedInterface && cachedInterface.docUrl) {
         try {
-            const detail = await parseInterfaceFromMd(cachedInterface.docUrl);
+            // 优先从 MD 文件读取（不消耗 Token）
+            logger.debug(`[get_interface_detail] 接口 ${args.interfaceId} 在缓存中，从 MD 文件读取（不消耗 token）`);
+            detail = await parseInterfaceFromMd(cachedInterface.docUrl);
             if (detail) {
-                contextStore.setLastProject(projectInfo.projectName, projectInfo.projectId);
-                const tsArtifact = generateArtifact('ts_types', {
-                    interfaceDetail: detail,
-                });
-                const curlSnippet = buildCurlSnippet(detail);
-                const fetchSnippet = buildFetchSnippet(detail);
-                const description = detail.description ? `\n- 描述: ${detail.description}` : '';
-                // 构建详细的请求参数展示
-                const requestParts = [];
-                if (detail.request) {
-                    if (detail.request.headers && Object.keys(detail.request.headers).length > 0) {
-                        requestParts.push(`**请求头 (Headers):**\n\`\`\`json\n${JSON.stringify(detail.request.headers, null, 2)}\n\`\`\``);
-                    }
-                    if (detail.request.cookies && Object.keys(detail.request.cookies).length > 0) {
-                        requestParts.push(`**Cookie 参数:**\n\`\`\`json\n${JSON.stringify(detail.request.cookies, null, 2)}\n\`\`\``);
-                    }
-                    if (detail.request.query && Object.keys(detail.request.query).length > 0) {
-                        requestParts.push(`**查询参数 (Query):**\n\`\`\`json\n${JSON.stringify(detail.request.query, null, 2)}\n\`\`\``);
-                    }
-                    if (detail.request.path && Object.keys(detail.request.path).length > 0) {
-                        requestParts.push(`**路径参数 (Path):**\n\`\`\`json\n${JSON.stringify(detail.request.path, null, 2)}\n\`\`\``);
-                    }
-                    if (detail.request.body) {
-                        const bodyJson = JSON.stringify(detail.request.body, null, 2);
-                        requestParts.push(`**请求体 (Body):**\n\`\`\`json\n${bodyJson}\n\`\`\``);
-                    }
-                }
-                const requestSection = requestParts.length > 0
-                    ? `### 请求参数\n\n${requestParts.join('\n\n')}\n\n`
-                    : `### 请求参数\n\`\`\`json\n${JSON.stringify(detail.request || {}, null, 2)}\n\`\`\`\n\n`;
-                // 构建响应展示
-                const responseJson = JSON.stringify(detail.response || {}, null, 2);
-                const responseSection = `### 响应示例\n\`\`\`json\n${responseJson}\n\`\`\`\n\n`;
-                const text = `# ${detail.name || '未命名接口'}\n\n` +
-                    `**基本信息**\n` +
-                    `- 接口 ID: ${detail.id}\n` +
-                    `- 请求方法: ${detail.method || 'N/A'}\n` +
-                    `- 接口路径: ${detail.path || 'N/A'}\n` +
-                    `${description}\n\n` +
-                    `${requestSection}` +
-                    `${responseSection}` +
-                    `### curl 示例\n\`\`\`bash\n${curlSnippet}\n\`\`\`\n\n` +
-                    `### fetch 示例\n\`\`\`ts\n${fetchSnippet}\n\`\`\`\n\n` +
-                    `### TypeScript 类型草稿\n\`\`\`ts\n${tsArtifact.content}\n\`\`\`\n\n` +
-                    `如果需要，我还能继续为你生成 Mock 数据或请求封装。`;
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text,
-                        },
-                    ],
-                };
+                logger.info(`[get_interface_detail] ✅ 从缓存 md 文件成功获取接口 ${args.interfaceId} 的详情`);
+            }
+            else {
+                logger.warn(`[get_interface_detail] ⚠️ 从 md 文件解析接口 ${args.interfaceId} 失败，回退到 MCP Server`);
+                throw new Error('从 md 文件解析失败');
             }
         }
-        catch {
-            // 如果从 md 文件读取失败，继续使用 API 方式
+        catch (mdError) {
+            logger.warn(`[get_interface_detail] 从 md 文件读取接口 ${args.interfaceId} 失败: ${mdError instanceof Error ? mdError.message : String(mdError)}`);
+            logger.debug(`[get_interface_detail] 回退到官方 MCP Server 获取接口 ${args.interfaceId} 的详情（消耗 token）`);
+            // 回退到官方 MCP Server
+            const accessToken = configManager.getAccessToken();
+            if (!accessToken) {
+                return buildMissingTokenResponse();
+            }
+            detail = await mcpBridge.getInterfaceDetailViaMcp(accessToken, projectInfo.projectName, projectInfo.projectId, args.interfaceId);
         }
     }
-    // Fallback: 使用 API 方式获取接口详情
-    const accessToken = configManager.getAccessToken();
-    if (!accessToken) {
-        return buildMissingTokenResponse();
+    else {
+        // 缓存中没有，调用官方 MCP Server
+        logger.debug(`[get_interface_detail] 接口 ${args.interfaceId} 不在缓存中，调用官方 MCP Server（消耗 token）`);
+        const accessToken = configManager.getAccessToken();
+        if (!accessToken) {
+            return buildMissingTokenResponse();
+        }
+        detail = await mcpBridge.getInterfaceDetailViaMcp(accessToken, projectInfo.projectName, projectInfo.projectId, args.interfaceId);
     }
     try {
-        const detail = await mcpBridge.getInterfaceDetailViaMcp(accessToken, projectInfo.projectName, projectInfo.projectId, args.interfaceId);
+        // 回写接口基础信息到缓存（即便 docUrl 不存在，也先记录，后续刷新补齐）
+        cacheManager.upsertInterfaceDetail(projectInfo.projectName, projectInfo.projectId, {
+            id: detail.id,
+            name: detail.name,
+            docUrl: cachedInterface?.docUrl,
+        });
         contextStore.setLastProject(projectInfo.projectName, projectInfo.projectId);
         const tsArtifact = generateArtifact('ts_types', {
             interfaceDetail: detail,