@cnbcool/cnb-api-generate 1.2.7 → 2.0.0

package/built/codegen/printer/printer-skills-client-core.js

@@ -43,6 +43,7 @@ const debug_1 = __importDefault(require("debug"));
 const get_skills_codegen_target_1 = require("../../utils/get-skills-codegen-target");
 const glob_1 = require("glob");
 const printer_ts_ast_to_js_file_1 = require("./printer-ts-ast-to-js-file");
+const generate_flat_options_1 = require("../../utils/generate-flat-options");
 const logger = (0, debug_1.default)('csg:cli-core');
 async function printerSkillsClientCore(helpData) {
     const packageDir = path.resolve(__dirname, '../../../');
@@ -66,4 +67,13 @@ async function printerSkillsClientCore(helpData) {
     const helpFile = path.join(skillScriptCoreDir, 'help.json');
     fs.writeFileSync(helpFile, JSON.stringify(helpData, null, 2));
     logger(`print ${helpFile}`);
+    // 输出扁平化参数数据
+    const { flatOptions, keyMapping } = (0, generate_flat_options_1.generateFlatOptions)(helpData);
+    const flatOptionsFile = path.join(skillScriptCoreDir, 'flat-options.json');
+    fs.writeFileSync(flatOptionsFile, JSON.stringify(flatOptions, null, 2));
+    logger(`print ${flatOptionsFile}`);
+    // 输出 key 映射表（displayKey → originalKey）
+    const keyMappingFile = path.join(skillScriptCoreDir, 'key-mapping.json');
+    fs.writeFileSync(keyMappingFile, JSON.stringify(keyMapping, null, 2));
+    logger(`print ${keyMappingFile}`);
 }

package/built/utils/clean-array-desc.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cleanArrayDesc = cleanArrayDesc;
+/** 当参数为数组类型时，清理描述中的 JSON 数组示例 */
+function cleanArrayDesc(desc) {
+    let cleaned = desc.replace(/`?\[("[^"]*"(?:\s*,\s*"[^"]*")*)\]`?/g, '');
+    cleaned = cleaned.replace(/[，,]?\s*(?:示例|例如|如|example)\s*[:：]\s*$/i, '');
+    return cleaned.trim();
+}

package/built/utils/collect-used-keys.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectUsedKeys = collectUsedKeys;
+/** 收集 path 和 query 中已使用的 key */
+function collectUsedKeys(pathDef, queryDef) {
+    const keys = new Set();
+    if (pathDef) {
+        for (const key of Object.keys(pathDef))
+            keys.add(key);
+    }
+    if (queryDef) {
+        for (const key of Object.keys(queryDef))
+            keys.add(key);
+    }
+    return keys;
+}

package/built/utils/flat-option.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/built/utils/flatten-array-object-options.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flattenArrayObjectOptions = flattenArrayObjectOptions;
+const trim_summary_1 = require("./trim-summary");
+const option_value_flag_1 = require("./option-value-flag");
+const to_display_key_1 = require("./to-display-key");
+/** 扁平化 array<object> 类型的子属性 */
+function flattenArrayObjectOptions(arrayKey, prop, isRequired, usedKeys) {
+    const options = [];
+    const itemProps = prop.items.properties;
+    const arrayDesc = (0, trim_summary_1.trimSummary)(prop.description || '');
+    const subPropNames = Object.keys(itemProps);
+    for (const [subKey, subProp] of Object.entries(itemProps)) {
+        const flatKey = `${arrayKey}@${subKey}`;
+        const optKey = usedKeys.has(flatKey) ? `d-${flatKey}` : flatKey;
+        const valuePlaceholder = (0, option_value_flag_1.optionValueFlag)(subProp.type || 'string');
+        const rawDesc = (0, trim_summary_1.trimSummary)(subProp.description || '') || subKey;
+        const peerHint = subPropNames
+            .filter((k) => k !== subKey)
+            .map((k) => `--${(0, to_display_key_1.toDisplayKey)(`${arrayKey}@${k}`)}`)
+            .join(', ');
+        const hint = `${rawDesc} (${arrayDesc}，可多次传入，按顺序与 ${peerHint} 对齐)`;
+        const desc = isRequired ? `[必填] ${hint}` : hint;
+        options.push({
+            optKey,
+            valuePlaceholder,
+            description: desc,
+            required: isRequired,
+            isArray: true,
+            source: 'body',
+            isArrayObject: true,
+        });
+    }
+    return options;
+}

package/built/utils/flatten-nested-object-options.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flattenNestedObjectOptions = flattenNestedObjectOptions;
+const trim_summary_1 = require("./trim-summary");
+const option_value_flag_1 = require("./option-value-flag");
+const is_nested_object_1 = require("./is-nested-object");
+const is_array_of_objects_1 = require("./is-array-of-objects");
+const flatten_array_object_options_1 = require("./flatten-array-object-options");
+/** 递归扁平化嵌套对象类型的子属性 */
+function flattenNestedObjectOptions(objectKey, prop, isRequired, usedKeys) {
+    const options = [];
+    const subProps = prop.properties;
+    const objectDesc = (0, trim_summary_1.trimSummary)(prop.description || '');
+    for (const [subKey, subProp] of Object.entries(subProps)) {
+        const flatKey = `${objectKey}@${subKey}`;
+        if ((0, is_nested_object_1.isNestedObject)(subProp)) {
+            options.push(...flattenNestedObjectOptions(flatKey, subProp, isRequired, usedKeys));
+            continue;
+        }
+        if ((0, is_array_of_objects_1.isArrayOfObjects)(subProp)) {
+            options.push(...(0, flatten_array_object_options_1.flattenArrayObjectOptions)(flatKey, subProp, isRequired, usedKeys));
+            continue;
+        }
+        const optKey = usedKeys.has(flatKey) ? `d-${flatKey}` : flatKey;
+        const valuePlaceholder = (0, option_value_flag_1.optionValueFlag)(subProp.type || 'string');
+        const rawDesc = (0, trim_summary_1.trimSummary)(subProp.description || '') || subKey;
+        const hint = `${rawDesc} (${objectDesc} 的子字段)`;
+        const desc = isRequired ? `[必填] ${hint}` : hint;
+        options.push({
+            optKey,
+            valuePlaceholder,
+            description: desc,
+            required: isRequired,
+            isArray: false,
+            source: 'body',
+            isNestedField: true,
+        });
+    }
+    return options;
+}

package/built/utils/flatten-tool-options.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flattenToolOptions = flattenToolOptions;
+const trim_summary_1 = require("./trim-summary");
+const option_value_flag_1 = require("./option-value-flag");
+const clean_array_desc_1 = require("./clean-array-desc");
+const is_array_of_objects_1 = require("./is-array-of-objects");
+const is_nested_object_1 = require("./is-nested-object");
+const collect_used_keys_1 = require("./collect-used-keys");
+const flatten_array_object_options_1 = require("./flatten-array-object-options");
+const flatten_nested_object_options_1 = require("./flatten-nested-object-options");
+/**
+ * 将单个 tool 的参数扁平化为 FlatOption 列表
+ * 逻辑与 register-modules.ts 中 registerToolOptions 完全一致
+ */
+function flattenToolOptions(toolInfo) {
+    var _a, _b, _c;
+    const options = [];
+    const parameter = (_a = toolInfo.help) === null || _a === void 0 ? void 0 : _a.parameter;
+    if (!parameter)
+        return options;
+    const { path: pathDef, query: queryDef, body: bodyDef } = parameter;
+    // path 参数
+    if (pathDef) {
+        for (const [key, param] of Object.entries(pathDef)) {
+            const valuePlaceholder = (0, option_value_flag_1.optionValueFlag)(param.type);
+            const rawDesc = (0, trim_summary_1.trimSummary)(param.description || '');
+            const desc = param.required ? `[必填] ${rawDesc}` : rawDesc;
+            options.push({
+                optKey: key,
+                valuePlaceholder,
+                description: desc,
+                required: !!param.required,
+                isArray: false,
+                source: 'path',
+            });
+        }
+    }
+    // query 参数
+    if (queryDef) {
+        for (const [key, param] of Object.entries(queryDef)) {
+            const valuePlaceholder = (0, option_value_flag_1.optionValueFlag)(param.type);
+            const rawDesc = (0, trim_summary_1.trimSummary)(param.description || '');
+            const desc = param.required ? `[必填] ${rawDesc}` : rawDesc;
+            const opt = {
+                optKey: key,
+                valuePlaceholder,
+                description: desc,
+                required: !!param.required,
+                isArray: false,
+                source: 'query',
+            };
+            if (param.enum)
+                opt.choices = param.enum;
+            if (param.default !== undefined)
+                opt.defaultValue = param.default;
+            options.push(opt);
+        }
+    }
+    // body 参数扁平化
+    if ((_b = bodyDef === null || bodyDef === void 0 ? void 0 : bodyDef.schema) === null || _b === void 0 ? void 0 : _b.properties) {
+        const usedKeys = (0, collect_used_keys_1.collectUsedKeys)(pathDef, queryDef);
+        const bodyRequired = new Set(bodyDef.schema.required || []);
+        for (const [key, prop] of Object.entries(bodyDef.schema.properties)) {
+            const isRequired = bodyRequired.has(key) || prop.required;
+            if ((0, is_array_of_objects_1.isArrayOfObjects)(prop)) {
+                options.push(...(0, flatten_array_object_options_1.flattenArrayObjectOptions)(key, prop, isRequired, usedKeys));
+                continue;
+            }
+            if ((0, is_nested_object_1.isNestedObject)(prop)) {
+                options.push(...(0, flatten_nested_object_options_1.flattenNestedObjectOptions)(key, prop, isRequired, usedKeys));
+                continue;
+            }
+            const optKey = usedKeys.has(key) ? `d-${key}` : key;
+            const isArray = prop.type === 'array';
+            const itemType = isArray ? ((_c = prop.items) === null || _c === void 0 ? void 0 : _c.type) || 'string' : prop.type;
+            const valuePlaceholder = (0, option_value_flag_1.optionValueFlag)(itemType);
+            const rawDesc = isArray
+                ? (0, clean_array_desc_1.cleanArrayDesc)((0, trim_summary_1.trimSummary)(prop.description || ''))
+                : (0, trim_summary_1.trimSummary)(prop.description || '');
+            const arrayHint = isArray ? ' (可多次传入)' : '';
+            const desc = isRequired
+                ? `[必填] ${rawDesc}${arrayHint}`
+                : `${rawDesc}${arrayHint}`;
+            const opt = {
+                optKey,
+                valuePlaceholder,
+                description: desc,
+                required: !!isRequired,
+                isArray,
+                source: 'body',
+            };
+            options.push(opt);
+        }
+    }
+    // body 存在时添加 --data fallback
+    if (bodyDef) {
+        options.push({
+            optKey: 'data',
+            valuePlaceholder: '<json>',
+            description: 'Request body (JSON 字符串或 @file 引用，可替代逐个 body 字段)',
+            required: false,
+            isArray: false,
+            source: 'body',
+        });
+    }
+    return options;
+}

package/built/utils/generate-flat-options.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateFlatOptions = generateFlatOptions;
+const to_display_key_1 = require("./to-display-key");
+const flatten_tool_options_1 = require("./flatten-tool-options");
+/**
+ * 模拟 Commander 对 --long-option 的 camelCase 转换
+ * 例如 "page-size" => "pageSize", "d-ext-type" => "dExtType"
+ */
+function commanderCamelCase(str) {
+    return str.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+/**
+ * 将 helpData 中所有 module 的 tool 参数预先扁平化
+ * 生成 flat-options.json，供 registerToolOptions 直接读取使用
+ * 同时生成 key-mapping.json，记录 Commander camelCase key → originalKey 的映射
+ * 格式: { moduleName: { toolName: { optKey: FlatOption, ... }, ... }, ... }
+ */
+function generateFlatOptions(helpData) {
+    const flatOptions = {};
+    const keyMapping = {};
+    const modulesHelp = helpData.modulesHelp || {};
+    for (const [moduleName, tools] of Object.entries(modulesHelp)) {
+        flatOptions[moduleName] = {};
+        keyMapping[moduleName] = {};
+        for (const [toolName, toolInfo] of Object.entries(tools)) {
+            const optionsList = (0, flatten_tool_options_1.flattenToolOptions)(toolInfo);
+            const optionsMap = {};
+            const toolKeyMapping = {};
+            for (const opt of optionsList) {
+                const originalKey = opt.optKey;
+                const displayKey = (0, to_display_key_1.toDisplayKey)(originalKey);
+                // Commander 会对 --page-size 做 camelCase 转换为 pageSize
+                const camelKey = commanderCamelCase(displayKey);
+                // 用 displayKey 作为 optKey 展示给用户
+                opt.optKey = displayKey;
+                optionsMap[displayKey] = opt;
+                // 仅当 camelKey 与 originalKey 不同时才记录映射
+                if (camelKey !== originalKey) {
+                    toolKeyMapping[camelKey] = originalKey;
+                }
+            }
+            flatOptions[moduleName][toolName] = optionsMap;
+            if (Object.keys(toolKeyMapping).length > 0) {
+                keyMapping[moduleName][toolName] = toolKeyMapping;
+            }
+        }
+    }
+    return { flatOptions, keyMapping };
+}

package/built/utils/is-array-of-objects.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isArrayOfObjects = isArrayOfObjects;
+/** 判断 body 属性是否为 array<object> 类型 */
+function isArrayOfObjects(prop) {
+    if (prop.type !== 'array' || !prop.items)
+        return false;
+    const { items } = prop;
+    return !!(items.properties && Object.keys(items.properties).length > 0);
+}

package/built/utils/is-nested-object.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNestedObject = isNestedObject;
+/** 判断 body 属性是否为嵌套对象类型 */
+function isNestedObject(prop) {
+    if (prop.type !== 'object')
+        return false;
+    return !!(prop.properties && Object.keys(prop.properties).length > 0);
+}

package/built/utils/option-value-flag.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.optionValueFlag = optionValueFlag;
+/** 将参数类型映射为 option 的值占位符 */
+function optionValueFlag(type) {
+    switch (type) {
+        case 'number':
+            return '<number>';
+        case 'boolean':
+            return '';
+        default:
+            return '<string>';
+    }
+}

package/built/utils/to-display-key.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toDisplayKey = toDisplayKey;
+/**
+ * 将 optKey 中的 '_' 和 '@' 统一替换为 '-'，生成 CLI 展示用的 key
+ * 例如 "page_size" => "page-size", "ext@type" => "ext-type"
+ */
+function toDisplayKey(optKey) {
+    return optKey.replace(/[_@]/g, '-');
+}

package/built/utils/trim-summary.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trimSummary = trimSummary;
+/** 去除 summary 中的英文部分（保留中文句号前的内容） */
+function trimSummary(summary) {
+    if (!summary)
+        return '';
+    const match = summary.match(/^(.*?[\u4e00-\u9fff].*?)[。.]\s*[A-Z]/);
+    if (match)
+        return match[1];
+    return summary;
+}