czh-api 1.0.5 → 1.0.6

package/src/commands/build.ts

@@ -18,8 +18,8 @@ import { compile } from 'json-schema-to-typescript';
 import { Converter } from '@apiture/openapi-down-convert';
 
 // 统一的类型转换函数
-function convertOpenApiTypeToTypeScript(openApiType: string | undefined): string {
-    if (!openApiType) return 'any';
+function convertOpenApiTypeToTypeScript(openApiType: string | undefined): string {
+    if (!openApiType) return 'any';
     
     switch (openApiType) {
         case 'integer':
@@ -32,230 +32,230 @@ function convertOpenApiTypeToTypeScript(openApiType: string | undefined): string
             return 'boolean';
         case 'string':
             return 'string';
-        case 'number':
-            return 'number';
-        default:
-            return openApiType;
-    }
-}
+        case 'number':
+            return 'number';
+        default:
+            return openApiType;
+    }
+}
 
 // 改进类型定义的辅助函数
-function isValidTypeIdentifier(typeName: string | undefined): boolean {
-    if (!typeName) return false;
-    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(typeName);
-}
-
-function escapeRegex(value: string): string {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-function resolveInterfaceTargetType(typeName: string | undefined): string | null {
-    if (typeof typeName !== 'string' || typeName.length === 0) return null;
-    if (isValidTypeIdentifier(typeName)) return typeName;
-
-    const arrayMatch = typeName.match(/^([A-Za-z_$][A-Za-z0-9_$]*)\[\]$/);
-    if (arrayMatch) {
-        return arrayMatch[1];
-    }
-
-    return null;
-}
-
-function findInterfaceBlockRange(content: string, typeName: string): { start: number; end: number } | null {
-    const startRegex = new RegExp(`export interface ${escapeRegex(typeName)}\\s*\\{`);
-    const match = startRegex.exec(content);
-    if (!match) return null;
-
-    const start = match.index;
-    const openBraceIndex = start + match[0].lastIndexOf('{');
-    let depth = 0;
-
-    for (let i = openBraceIndex; i < content.length; i++) {
-        const ch = content[i];
-        if (ch === '{') {
-            depth++;
-        } else if (ch === '}') {
-            depth--;
-            if (depth === 0) {
-                return { start, end: i + 1 };
-            }
-        }
-    }
-
-    return null;
-}
-
-const TS_BUILTIN_TYPE_NAMES = new Set([
-    'string',
-    'number',
-    'boolean',
-    'null',
-    'undefined',
-    'void',
-    'any',
-    'unknown',
-    'never',
-    'object',
-    'Record',
-    'Array',
-    'Date',
-    'Promise',
-    'true',
-    'false',
-]);
-
-function extractTypeIdentifiers(typeExpr: string | undefined): string[] {
-    if (!typeExpr) return [];
-    const matches = typeExpr.match(/[A-Za-z_$][A-Za-z0-9_$]*/g) || [];
-    return [...new Set(matches.filter(name => !TS_BUILTIN_TYPE_NAMES.has(name)))];
-}
-
-function getSchemaNameFromRef(ref: string | undefined): string {
-    if (!ref) return '';
-    return ref.split('/').pop() || '';
-}
-
-function resolveSchemaTypeFromModuleSchemas(
-    schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined,
-    moduleSchemas: { [typeName: string]: OpenAPIV3.SchemaObject },
-    visitedRefs: Set<string> = new Set()
-): string {
-    if (!schema) return 'any';
-
-    if ((schema as OpenAPIV3.ReferenceObject).$ref) {
-        const refName = getSchemaNameFromRef((schema as OpenAPIV3.ReferenceObject).$ref);
-        return refName || 'any';
-    }
-
-    const schemaObj = schema as OpenAPIV3.SchemaObject;
-
-    if (schemaObj.anyOf && Array.isArray(schemaObj.anyOf) && schemaObj.anyOf.length > 0) {
-        const types = schemaObj.anyOf
-            .map(item => resolveSchemaTypeFromModuleSchemas(item as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, moduleSchemas, visitedRefs))
-            .filter(Boolean);
-        if (types.length > 0) {
-            return [...new Set(types)].join(' | ');
-        }
-    }
-
-    if (schemaObj.oneOf && Array.isArray(schemaObj.oneOf) && schemaObj.oneOf.length > 0) {
-        const types = schemaObj.oneOf
-            .map(item => resolveSchemaTypeFromModuleSchemas(item as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, moduleSchemas, visitedRefs))
-            .filter(Boolean);
-        if (types.length > 0) {
-            return [...new Set(types)].join(' | ');
-        }
-    }
-
-    if (schemaObj.type === 'array') {
-        const itemType = resolveSchemaTypeFromModuleSchemas(
-            schemaObj.items as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined,
-            moduleSchemas,
-            visitedRefs
-        );
-        return `${itemType || 'any'}[]`;
-    }
-
-    if (schemaObj.type === 'object' && schemaObj.additionalProperties) {
-        if (schemaObj.additionalProperties === true) {
-            return 'Record<string, any>';
-        }
-        const valueType = resolveSchemaTypeFromModuleSchemas(
-            schemaObj.additionalProperties as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
-            moduleSchemas,
-            visitedRefs
-        );
-        return `Record<string, ${valueType || 'any'}>`;
-    }
-
-    if (schemaObj.type === 'object' && schemaObj.properties && Object.keys(schemaObj.properties).length > 0) {
-        const requiredSet = new Set(schemaObj.required || []);
-        const inlineFields = Object.entries(schemaObj.properties).map(([key, value]) => {
-            const fieldType = resolveSchemaTypeFromModuleSchemas(
-                value as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
-                moduleSchemas,
-                visitedRefs
-            );
-            const optional = requiredSet.has(key) ? '' : '?';
-            return `${key}${optional}: ${fieldType || 'any'}`;
-        });
-        return `{ ${inlineFields.join('; ')} }`;
-    }
-
-    const baseType = convertOpenApiTypeToTypeScript(schemaObj.type);
-    if (!baseType) return 'any';
-    return schemaObj.nullable ? `${baseType} | null` : baseType;
-}
-
-function collectSchemaProperties(
-    schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined,
-    moduleSchemas: { [typeName: string]: OpenAPIV3.SchemaObject },
-    visitedRefs: Set<string> = new Set()
-): { properties: Record<string, OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject>; required: Set<string> } {
-    const collected: { properties: Record<string, OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject>; required: Set<string> } = {
-        properties: {},
-        required: new Set<string>(),
-    };
-    if (!schema) return collected;
-
-    if ((schema as OpenAPIV3.ReferenceObject).$ref) {
-        const ref = (schema as OpenAPIV3.ReferenceObject).$ref;
-        if (!visitedRefs.has(ref)) {
-            visitedRefs.add(ref);
-            const refName = getSchemaNameFromRef(ref);
-            const refSchema = moduleSchemas[refName];
-            if (refSchema) {
-                const nested = collectSchemaProperties(refSchema, moduleSchemas, visitedRefs);
-                Object.assign(collected.properties, nested.properties);
-                nested.required.forEach(field => collected.required.add(field));
-            }
-        }
-        return collected;
-    }
-
-    const schemaObj = schema as OpenAPIV3.SchemaObject;
-
-    if (schemaObj.allOf && Array.isArray(schemaObj.allOf)) {
-        schemaObj.allOf.forEach(item => {
-            const nested = collectSchemaProperties(item as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, moduleSchemas, visitedRefs);
-            Object.assign(collected.properties, nested.properties);
-            nested.required.forEach(field => collected.required.add(field));
-        });
-    }
-
-    if (schemaObj.properties) {
-        Object.entries(schemaObj.properties).forEach(([name, value]) => {
-            collected.properties[name] = value as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject;
-        });
-    }
-
-    (schemaObj.required || []).forEach(field => collected.required.add(field));
-    return collected;
-}
-
-function buildInterfaceDefinitionFromModuleSchemas(
-    typeName: string,
-    moduleSchemas: { [typeName: string]: OpenAPIV3.SchemaObject }
-): string | null {
-    const schema = moduleSchemas[typeName];
-    if (!schema) return null;
-
-    const { properties, required } = collectSchemaProperties(schema, moduleSchemas);
-    const entries = Object.entries(properties);
-    if (entries.length === 0) return null;
-
-    const lines = entries.map(([propName, propSchema]) => {
-        const optional = required.has(propName) ? '' : '?';
-        const propType = resolveSchemaTypeFromModuleSchemas(propSchema, moduleSchemas) || 'any';
-        const propDescription = (propSchema as OpenAPIV3.SchemaObject).description || '';
-        const comment = propDescription ? ` // ${propDescription}` : '';
-        return `  ${propName}${optional}: ${propType};${comment}`;
-    });
-
-    return `export interface ${typeName} {\n${lines.join('\n')}\n}`;
-}
-
-function improveTypeDefinitions(typesContent: string, endpoints: any[]): string {
+function isValidTypeIdentifier(typeName: string | undefined): boolean {
+    if (!typeName) return false;
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(typeName);
+}
+
+function escapeRegex(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function resolveInterfaceTargetType(typeName: string | undefined): string | null {
+    if (typeof typeName !== 'string' || typeName.length === 0) return null;
+    if (isValidTypeIdentifier(typeName)) return typeName;
+
+    const arrayMatch = typeName.match(/^([A-Za-z_$][A-Za-z0-9_$]*)\[\]$/);
+    if (arrayMatch) {
+        return arrayMatch[1];
+    }
+
+    return null;
+}
+
+function findInterfaceBlockRange(content: string, typeName: string): { start: number; end: number } | null {
+    const startRegex = new RegExp(`export interface ${escapeRegex(typeName)}\\s*\\{`);
+    const match = startRegex.exec(content);
+    if (!match) return null;
+
+    const start = match.index;
+    const openBraceIndex = start + match[0].lastIndexOf('{');
+    let depth = 0;
+
+    for (let i = openBraceIndex; i < content.length; i++) {
+        const ch = content[i];
+        if (ch === '{') {
+            depth++;
+        } else if (ch === '}') {
+            depth--;
+            if (depth === 0) {
+                return { start, end: i + 1 };
+            }
+        }
+    }
+
+    return null;
+}
+
+const TS_BUILTIN_TYPE_NAMES = new Set([
+    'string',
+    'number',
+    'boolean',
+    'null',
+    'undefined',
+    'void',
+    'any',
+    'unknown',
+    'never',
+    'object',
+    'Record',
+    'Array',
+    'Date',
+    'Promise',
+    'true',
+    'false',
+]);
+
+function extractTypeIdentifiers(typeExpr: string | undefined): string[] {
+    if (!typeExpr) return [];
+    const matches = typeExpr.match(/[A-Za-z_$][A-Za-z0-9_$]*/g) || [];
+    return [...new Set(matches.filter(name => !TS_BUILTIN_TYPE_NAMES.has(name)))];
+}
+
+function getSchemaNameFromRef(ref: string | undefined): string {
+    if (!ref) return '';
+    return ref.split('/').pop() || '';
+}
+
+function resolveSchemaTypeFromModuleSchemas(
+    schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined,
+    moduleSchemas: { [typeName: string]: OpenAPIV3.SchemaObject },
+    visitedRefs: Set<string> = new Set()
+): string {
+    if (!schema) return 'any';
+
+    if ((schema as OpenAPIV3.ReferenceObject).$ref) {
+        const refName = getSchemaNameFromRef((schema as OpenAPIV3.ReferenceObject).$ref);
+        return refName || 'any';
+    }
+
+    const schemaObj = schema as OpenAPIV3.SchemaObject;
+
+    if (schemaObj.anyOf && Array.isArray(schemaObj.anyOf) && schemaObj.anyOf.length > 0) {
+        const types = schemaObj.anyOf
+            .map(item => resolveSchemaTypeFromModuleSchemas(item as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, moduleSchemas, visitedRefs))
+            .filter(Boolean);
+        if (types.length > 0) {
+            return [...new Set(types)].join(' | ');
+        }
+    }
+
+    if (schemaObj.oneOf && Array.isArray(schemaObj.oneOf) && schemaObj.oneOf.length > 0) {
+        const types = schemaObj.oneOf
+            .map(item => resolveSchemaTypeFromModuleSchemas(item as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, moduleSchemas, visitedRefs))
+            .filter(Boolean);
+        if (types.length > 0) {
+            return [...new Set(types)].join(' | ');
+        }
+    }
+
+    if (schemaObj.type === 'array') {
+        const itemType = resolveSchemaTypeFromModuleSchemas(
+            schemaObj.items as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined,
+            moduleSchemas,
+            visitedRefs
+        );
+        return `${itemType || 'any'}[]`;
+    }
+
+    if (schemaObj.type === 'object' && schemaObj.additionalProperties) {
+        if (schemaObj.additionalProperties === true) {
+            return 'Record<string, any>';
+        }
+        const valueType = resolveSchemaTypeFromModuleSchemas(
+            schemaObj.additionalProperties as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
+            moduleSchemas,
+            visitedRefs
+        );
+        return `Record<string, ${valueType || 'any'}>`;
+    }
+
+    if (schemaObj.type === 'object' && schemaObj.properties && Object.keys(schemaObj.properties).length > 0) {
+        const requiredSet = new Set(schemaObj.required || []);
+        const inlineFields = Object.entries(schemaObj.properties).map(([key, value]) => {
+            const fieldType = resolveSchemaTypeFromModuleSchemas(
+                value as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
+                moduleSchemas,
+                visitedRefs
+            );
+            const optional = requiredSet.has(key) ? '' : '?';
+            return `${key}${optional}: ${fieldType || 'any'}`;
+        });
+        return `{ ${inlineFields.join('; ')} }`;
+    }
+
+    const baseType = convertOpenApiTypeToTypeScript(schemaObj.type);
+    if (!baseType) return 'any';
+    return schemaObj.nullable ? `${baseType} | null` : baseType;
+}
+
+function collectSchemaProperties(
+    schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined,
+    moduleSchemas: { [typeName: string]: OpenAPIV3.SchemaObject },
+    visitedRefs: Set<string> = new Set()
+): { properties: Record<string, OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject>; required: Set<string> } {
+    const collected: { properties: Record<string, OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject>; required: Set<string> } = {
+        properties: {},
+        required: new Set<string>(),
+    };
+    if (!schema) return collected;
+
+    if ((schema as OpenAPIV3.ReferenceObject).$ref) {
+        const ref = (schema as OpenAPIV3.ReferenceObject).$ref;
+        if (!visitedRefs.has(ref)) {
+            visitedRefs.add(ref);
+            const refName = getSchemaNameFromRef(ref);
+            const refSchema = moduleSchemas[refName];
+            if (refSchema) {
+                const nested = collectSchemaProperties(refSchema, moduleSchemas, visitedRefs);
+                Object.assign(collected.properties, nested.properties);
+                nested.required.forEach(field => collected.required.add(field));
+            }
+        }
+        return collected;
+    }
+
+    const schemaObj = schema as OpenAPIV3.SchemaObject;
+
+    if (schemaObj.allOf && Array.isArray(schemaObj.allOf)) {
+        schemaObj.allOf.forEach(item => {
+            const nested = collectSchemaProperties(item as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, moduleSchemas, visitedRefs);
+            Object.assign(collected.properties, nested.properties);
+            nested.required.forEach(field => collected.required.add(field));
+        });
+    }
+
+    if (schemaObj.properties) {
+        Object.entries(schemaObj.properties).forEach(([name, value]) => {
+            collected.properties[name] = value as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject;
+        });
+    }
+
+    (schemaObj.required || []).forEach(field => collected.required.add(field));
+    return collected;
+}
+
+function buildInterfaceDefinitionFromModuleSchemas(
+    typeName: string,
+    moduleSchemas: { [typeName: string]: OpenAPIV3.SchemaObject }
+): string | null {
+    const schema = moduleSchemas[typeName];
+    if (!schema) return null;
+
+    const { properties, required } = collectSchemaProperties(schema, moduleSchemas);
+    const entries = Object.entries(properties);
+    if (entries.length === 0) return null;
+
+    const lines = entries.map(([propName, propSchema]) => {
+        const optional = required.has(propName) ? '' : '?';
+        const propType = resolveSchemaTypeFromModuleSchemas(propSchema, moduleSchemas) || 'any';
+        const propDescription = (propSchema as OpenAPIV3.SchemaObject).description || '';
+        const comment = propDescription ? ` // ${propDescription}` : '';
+        return `  ${propName}${optional}: ${propType};${comment}`;
+    });
+
+    return `export interface ${typeName} {\n${lines.join('\n')}\n}`;
+}
+
+function improveTypeDefinitions(typesContent: string, endpoints: any[]): string {
     let improvedContent = typesContent;
     
     // 收集所有需要改进的类型定义
@@ -270,13 +270,13 @@ function improveTypeDefinitions(typesContent: string, endpoints: any[]): string
                 let type = param.type;
                 
                 // 处理联合类型，确保正确的 TypeScript 语法
-                if (type && type.includes(' | ')) {
-                    if (type.includes('null')) {
-                        type = type.replace(/\s*\|\s*null/g, ' | null');
-                    }
-                } else {
-                    type = convertOpenApiTypeToTypeScript(type);
-                }
+                if (type && type.includes(' | ')) {
+                    if (type.includes('null')) {
+                        type = type.replace(/\s*\|\s*null/g, ' | null');
+                    }
+                } else {
+                    type = convertOpenApiTypeToTypeScript(type);
+                }
                 
                 const comment = param.description ? ` // ${param.description}` : '';
                 return `  ${param.name}${optional}: ${type};${comment}`;
@@ -286,52 +286,52 @@ function improveTypeDefinitions(typesContent: string, endpoints: any[]): string
     
     endpoints.forEach(endpoint => {
         // 改进 params 类型 - 使用 paramsJsdocParams（仅包含 path/query 参数）
-        const requestParamsTypeName = endpoint.requestParamsTypeName;
-        if (requestParamsTypeName && isValidTypeIdentifier(requestParamsTypeName) && endpoint.paramsJsdocParams && endpoint.paramsJsdocParams.length > 0) {
-            const paramsFields = buildFieldsFromJsdocParams(endpoint.paramsJsdocParams);
-            
-            if (paramsFields) {
-                typeImprovements[requestParamsTypeName] = `export interface ${requestParamsTypeName} {
-${paramsFields}
-}`;
-            }
-        }
+        const requestParamsTypeName = endpoint.requestParamsTypeName;
+        if (requestParamsTypeName && isValidTypeIdentifier(requestParamsTypeName) && endpoint.paramsJsdocParams && endpoint.paramsJsdocParams.length > 0) {
+            const paramsFields = buildFieldsFromJsdocParams(endpoint.paramsJsdocParams);
+            
+            if (paramsFields) {
+                typeImprovements[requestParamsTypeName] = `export interface ${requestParamsTypeName} {
+${paramsFields}
+}`;
+            }
+        }
         
         // 改进 requestBody 类型 - 使用 dataJsdocParams（仅包含 requestBody 参数）
-        const requestBodyTypeName = endpoint.requestBodyTypeName;
-        if (requestBodyTypeName && isValidTypeIdentifier(requestBodyTypeName) && endpoint.dataJsdocParams && endpoint.dataJsdocParams.length > 0) {
-            const dataFields = buildFieldsFromJsdocParams(endpoint.dataJsdocParams);
-            
-            if (dataFields) {
-                typeImprovements[requestBodyTypeName] = `export interface ${requestBodyTypeName} {
-${dataFields}
-}`;
-            }
-        }
+        const requestBodyTypeName = endpoint.requestBodyTypeName;
+        if (requestBodyTypeName && isValidTypeIdentifier(requestBodyTypeName) && endpoint.dataJsdocParams && endpoint.dataJsdocParams.length > 0) {
+            const dataFields = buildFieldsFromJsdocParams(endpoint.dataJsdocParams);
+            
+            if (dataFields) {
+                typeImprovements[requestBodyTypeName] = `export interface ${requestBodyTypeName} {
+${dataFields}
+}`;
+            }
+        }
 
         // 改进 response 类型 - 使用 responseJsdocParams（包含响应字段信息）
-        const responseTargetType = resolveInterfaceTargetType(endpoint.responseTypeName);
-        if (responseTargetType && endpoint.responseTypeName !== 'void' && endpoint.responseJsdocParams && endpoint.responseJsdocParams.length > 0) {
-            const responseFields = buildFieldsFromJsdocParams(endpoint.responseJsdocParams);
-            
-            if (responseFields) {
-                typeImprovements[responseTargetType] = `export interface ${responseTargetType} {
-${responseFields}
-}`;
-            }
-        }
+        const responseTargetType = resolveInterfaceTargetType(endpoint.responseTypeName);
+        if (responseTargetType && endpoint.responseTypeName !== 'void' && endpoint.responseJsdocParams && endpoint.responseJsdocParams.length > 0) {
+            const responseFields = buildFieldsFromJsdocParams(endpoint.responseJsdocParams);
+            
+            if (responseFields) {
+                typeImprovements[responseTargetType] = `export interface ${responseTargetType} {
+${responseFields}
+}`;
+            }
+        }
     });
     
     // 替换现有的类型定义
     Object.entries(typeImprovements).forEach(([typeName, newDefinition]) => {
         // 查找并替换现有的接口定义
-        const blockRange = findInterfaceBlockRange(improvedContent, typeName);
-        if (blockRange) {
-            improvedContent =
-                improvedContent.slice(0, blockRange.start) +
-                newDefinition +
-                improvedContent.slice(blockRange.end);
-        } else {
+        const blockRange = findInterfaceBlockRange(improvedContent, typeName);
+        if (blockRange) {
+            improvedContent =
+                improvedContent.slice(0, blockRange.start) +
+                newDefinition +
+                improvedContent.slice(blockRange.end);
+        } else {
             // 如果没找到接口定义，添加到末尾
             improvedContent += '\n\n' + newDefinition;
         }
@@ -341,7 +341,7 @@ ${responseFields}
 }
 
 // 移除无用的类型别名
-function removeUselessTypeAliases(typesContent: string): string {
+function removeUselessTypeAliases(typesContent: string): string {
     let cleanedContent = typesContent;
     
     // 收集要删除的类型别名及其对应的基础类型
@@ -408,33 +408,57 @@ function removeUselessTypeAliases(typesContent: string): string {
     // 移除孤立的类型注释（没有对应类型定义的注释）
     cleanedContent = cleanedContent.replace(/\/\*\*\n \* [^\n]*\n \*\/\n(?!export)/g, '');
     
-    return cleanedContent;
-}
-
-function normalizeRef(refValue: string): string {
-    const match = refValue.match(/^#\/components\/schemas\/([^/]+)$/);
-    if (match) {
-        return `#/definitions/${match[1]}`;
-    }
-    return refValue;
+    return cleanedContent;
+}
+
+function normalizeRef(refValue: string): string {
+    const match = refValue.match(/^#\/components\/schemas\/([^/]+)$/);
+    if (match) {
+        return `#/definitions/${match[1]}`;
+    }
+    return refValue;
+}
+
+function normalizeSchemaRefs<T>(value: T): T {
+    if (Array.isArray(value)) {
+        return value.map(item => normalizeSchemaRefs(item)) as T;
+    }
+
+    if (value && typeof value === 'object') {
+        const obj = value as Record<string, unknown>;
+        const normalized: Record<string, unknown> = {};
+
+        for (const key in obj) {
+            const currentValue = obj[key];
+            if (key === '$ref' && typeof currentValue === 'string') {
+                normalized[key] = normalizeRef(currentValue);
+            } else {
+                normalized[key] = normalizeSchemaRefs(currentValue);
+            }
+        }
+
+        return normalized as T;
+    }
+
+    return value;
 }
 
-function normalizeSchemaRefs<T>(value: T): T {
+function stripNestedSchemaTitles<T>(value: T, depth: number = 0): T {
     if (Array.isArray(value)) {
-        return value.map(item => normalizeSchemaRefs(item)) as T;
+        return value.map(item => stripNestedSchemaTitles(item, depth + 1)) as T;
     }
 
     if (value && typeof value === 'object') {
         const obj = value as Record<string, unknown>;
         const normalized: Record<string, unknown> = {};
 
-        for (const key in obj) {
-            const currentValue = obj[key];
-            if (key === '$ref' && typeof currentValue === 'string') {
-                normalized[key] = normalizeRef(currentValue);
-            } else {
-                normalized[key] = normalizeSchemaRefs(currentValue);
+        for (const [key, currentValue] of Object.entries(obj)) {
+            // json-schema-to-typescript may generate invalid type aliases from nested title values
+            // (e.g. Chinese punctuation or numeric-leading titles), so keep only root-level titles.
+            if (key === 'title' && depth > 0) {
+                continue;
             }
+            normalized[key] = stripNestedSchemaTitles(currentValue, depth + 1);
         }
 
         return normalized as T;
@@ -442,8 +466,8 @@ function normalizeSchemaRefs<T>(value: T): T {
 
     return value;
 }
-
-interface IConfig {
+
+interface IConfig {
     url: string;
     outputDir: string;
     httpClientPath: string;
@@ -564,14 +588,16 @@ export const handleBuild = async () => {
             if (Object.keys(module.schemas).length > 0) {
                 console.log(chalk.blue(`正在为模块 "${moduleName}" 生成类型文件，包含 ${Object.keys(module.schemas).length} 个 schema`));
                 try {
-                    const normalizedModuleSchemas = normalizeSchemaRefs(module.schemas);
-                    const schemasWithTitles: { [key: string]: OpenAPIV3.SchemaObject } = {};
-                    for (const schemaName in normalizedModuleSchemas) {
-                        schemasWithTitles[schemaName] = {
-                            ...normalizedModuleSchemas[schemaName],
-                            title: schemaName, 
-                        };
-                    }
+                    const normalizedModuleSchemas = stripNestedSchemaTitles(
+                        normalizeSchemaRefs(module.schemas)
+                    );
+                    const schemasWithTitles: { [key: string]: OpenAPIV3.SchemaObject } = {};
+                    for (const schemaName in normalizedModuleSchemas) {
+                        schemasWithTitles[schemaName] = {
+                            ...normalizedModuleSchemas[schemaName],
+                            title: schemaName, 
+                        };
+                    }
         
                     const rootSchemaForCompiler = {
                         title: 'schemas',
@@ -622,10 +648,12 @@ export const handleBuild = async () => {
                         
                         // 尝试逐个验证 schema，过滤掉有问题的
                         const validSchemas: { [key: string]: OpenAPIV3.SchemaObject } = {};
-                        const invalidSchemas: string[] = [];
-                        const normalizedModuleSchemas = normalizeSchemaRefs(module.schemas);
+                        const invalidSchemas: string[] = [];
+                        const normalizedModuleSchemas = stripNestedSchemaTitles(
+                            normalizeSchemaRefs(module.schemas)
+                        );
                         
-                        for (const schemaName in normalizedModuleSchemas) {
+                        for (const schemaName in normalizedModuleSchemas) {
                             try {
                                 // 尝试单独编译每个 schema
                                 const testSchema = {
@@ -633,12 +661,12 @@ export const handleBuild = async () => {
                                     type: 'object',
                                     properties: {},
                                     additionalProperties: false,
-                                    definitions: { [schemaName]: normalizedModuleSchemas[schemaName] },
-                                    components: { schemas: { [schemaName]: normalizedModuleSchemas[schemaName] } }
+                                    definitions: { [schemaName]: normalizedModuleSchemas[schemaName] },
+                                    components: { schemas: { [schemaName]: normalizedModuleSchemas[schemaName] } }
                                 };
                                 await compile(testSchema as any, 'test', { unreachableDefinitions: true });
                                 validSchemas[schemaName] = {
-                                    ...normalizedModuleSchemas[schemaName],
+                                    ...normalizedModuleSchemas[schemaName],
                                     title: schemaName
                                 };
                             } catch (schemaError) {
@@ -712,8 +740,8 @@ export const handleBuild = async () => {
                         console.log(chalk.blue(`为模块 "${moduleName}" 生成基于 JSDoc 的类型定义...`));
                         
                         // 创建类型定义映射
-                        const typeDefinitions: { [typeName: string]: string } = {};
-                        const nestedReferencedTypes = new Set<string>();
+                        const typeDefinitions: { [typeName: string]: string } = {};
+                        const nestedReferencedTypes = new Set<string>();
                         
                         // 从 endpoints 中提取类型定义
                         module.endpoints.forEach(endpoint => {
@@ -724,88 +752,88 @@ export const handleBuild = async () => {
                                     const optional = !param.required ? '?' : '';
                                     let type = param.type;
                                     
-                                    if (type && type.includes(' | ')) {
-                                        if (type.includes('null')) {
-                                            type = type.replace(/\s*\|\s*null/g, ' | null');
-                                        }
-                                    } else {
-                                        type = convertOpenApiTypeToTypeScript(type);
-                                    }
-
-                                    extractTypeIdentifiers(type).forEach(typeName => {
-                                        if (isValidTypeIdentifier(typeName)) {
-                                            nestedReferencedTypes.add(typeName);
-                                        }
-                                    });
-                                    
-                                    const comment = param.description ? ` // ${param.description}` : '';
-                                    return `  ${param.name}${optional}: ${type};${comment}`;
-                                })
+                                    if (type && type.includes(' | ')) {
+                                        if (type.includes('null')) {
+                                            type = type.replace(/\s*\|\s*null/g, ' | null');
+                                        }
+                                    } else {
+                                        type = convertOpenApiTypeToTypeScript(type);
+                                    }
+
+                                    extractTypeIdentifiers(type).forEach(typeName => {
+                                        if (isValidTypeIdentifier(typeName)) {
+                                            nestedReferencedTypes.add(typeName);
+                                        }
+                                    });
+                                    
+                                    const comment = param.description ? ` // ${param.description}` : '';
+                                    return `  ${param.name}${optional}: ${type};${comment}`;
+                                })
                                 .join('\n');
 
                             // 处理 params 类型 - 使用 paramsJsdocParams
-                            const requestParamsTypeName = endpoint.requestParamsTypeName;
-                            if (requestParamsTypeName && isValidTypeIdentifier(requestParamsTypeName) && endpoint.paramsJsdocParams && endpoint.paramsJsdocParams.length > 0) {
-                                const paramsFields = buildFields(endpoint.paramsJsdocParams);
-                                
-                                if (paramsFields) {
-                                    typeDefinitions[requestParamsTypeName] = `export interface ${requestParamsTypeName} {
-${paramsFields}
-}`;
-                                }
-                            }
+                            const requestParamsTypeName = endpoint.requestParamsTypeName;
+                            if (requestParamsTypeName && isValidTypeIdentifier(requestParamsTypeName) && endpoint.paramsJsdocParams && endpoint.paramsJsdocParams.length > 0) {
+                                const paramsFields = buildFields(endpoint.paramsJsdocParams);
+                                
+                                if (paramsFields) {
+                                    typeDefinitions[requestParamsTypeName] = `export interface ${requestParamsTypeName} {
+${paramsFields}
+}`;
+                                }
+                            }
                             
                             // 处理 data 类型 (requestBody) - 使用 dataJsdocParams
-                            const requestBodyTypeName = endpoint.requestBodyTypeName;
-                            if (requestBodyTypeName && isValidTypeIdentifier(requestBodyTypeName) && endpoint.dataJsdocParams && endpoint.dataJsdocParams.length > 0) {
-                                const dataFields = buildFields(endpoint.dataJsdocParams);
-                                
-                                if (dataFields) {
-                                    typeDefinitions[requestBodyTypeName] = `export interface ${requestBodyTypeName} {
-${dataFields}
-}`;
-                                }
-                            }
+                            const requestBodyTypeName = endpoint.requestBodyTypeName;
+                            if (requestBodyTypeName && isValidTypeIdentifier(requestBodyTypeName) && endpoint.dataJsdocParams && endpoint.dataJsdocParams.length > 0) {
+                                const dataFields = buildFields(endpoint.dataJsdocParams);
+                                
+                                if (dataFields) {
+                                    typeDefinitions[requestBodyTypeName] = `export interface ${requestBodyTypeName} {
+${dataFields}
+}`;
+                                }
+                            }
 
                             // 处理 response 类型 - 使用 responseJsdocParams
-                            const responseTargetType = resolveInterfaceTargetType(endpoint.responseTypeName);
-                            if (responseTargetType && endpoint.responseTypeName !== 'void' && endpoint.responseJsdocParams && endpoint.responseJsdocParams.length > 0) {
-                                const responseFields = buildFields(endpoint.responseJsdocParams);
-                                
-                                if (responseFields) {
-                                    typeDefinitions[responseTargetType] = `export interface ${responseTargetType} {
-${responseFields}
-}`;
-                                }
-                            }
+                            const responseTargetType = resolveInterfaceTargetType(endpoint.responseTypeName);
+                            if (responseTargetType && endpoint.responseTypeName !== 'void' && endpoint.responseJsdocParams && endpoint.responseJsdocParams.length > 0) {
+                                const responseFields = buildFields(endpoint.responseJsdocParams);
+                                
+                                if (responseFields) {
+                                    typeDefinitions[responseTargetType] = `export interface ${responseTargetType} {
+${responseFields}
+}`;
+                                }
+                            }
                         });
                         
                         // 为没有定义的类型添加基本定义
-                        const fallbackReferencedTypes = [
-                            ...new Set([
-                                ...allReferencedTypes,
-                                ...Object.keys(module.schemas || {}),
-                                ...nestedReferencedTypes,
-                            ])
-                        ];
-                        fallbackReferencedTypes.forEach(typeName => {
-                            if (!isValidTypeIdentifier(typeName)) {
-                                return;
-                            }
-                            if (!typeDefinitions[typeName]) {
-                                const schemaBasedDefinition = buildInterfaceDefinitionFromModuleSchemas(
-                                    typeName,
-                                    module.schemas as { [typeName: string]: OpenAPIV3.SchemaObject }
-                                );
-                                if (schemaBasedDefinition) {
-                                    typeDefinitions[typeName] = schemaBasedDefinition;
-                                    return;
-                                }
-                                typeDefinitions[typeName] = `export interface ${typeName} {
-  [key: string]: any;
-}`;
-                            }
-                        });
+                        const fallbackReferencedTypes = [
+                            ...new Set([
+                                ...allReferencedTypes,
+                                ...Object.keys(module.schemas || {}),
+                                ...nestedReferencedTypes,
+                            ])
+                        ];
+                        fallbackReferencedTypes.forEach(typeName => {
+                            if (!isValidTypeIdentifier(typeName)) {
+                                return;
+                            }
+                            if (!typeDefinitions[typeName]) {
+                                const schemaBasedDefinition = buildInterfaceDefinitionFromModuleSchemas(
+                                    typeName,
+                                    module.schemas as { [typeName: string]: OpenAPIV3.SchemaObject }
+                                );
+                                if (schemaBasedDefinition) {
+                                    typeDefinitions[typeName] = schemaBasedDefinition;
+                                    return;
+                                }
+                                typeDefinitions[typeName] = `export interface ${typeName} {
+  [key: string]: any;
+}`;
+                            }
+                        });
                         
                         const basicTypesContent = `/* eslint-disable */
 /**
@@ -879,4 +907,4 @@ ${Object.values(typeDefinitions).join('\n\n')}
     } catch (error) {
         console.error(chalk.red('An error occurred during build process:'), error);
     }
-}; 
+};