@cnbcool/cnb-api-generate 2.11.8 → 2.12.0

package/built/codegen/interface/generate-interface-ast-node.js

@@ -45,6 +45,7 @@ const is_english_only_1 = require("../../utils/is-english-only");
 const generate_record_ast_node_1 = require("../record/generate-record-ast-node");
 const generate_interface_anchor_ast_node_1 = require("./generate-interface-anchor-ast-node");
 const comment_line_break_1 = require("../../utils/comment-line-break");
+const is_schema_like_1 = require("../../utils/is-schema-like");
 const logger = (0, debug_1.default)('cag:interface');
 function generateInterfaceASTNode(name, definitionsType, currProperties, definitions, defintionsMap, parentKey) {
     const currLoggerName = parentKey ? `${name}.${parentKey}` : name;
@@ -65,6 +66,9 @@ function generateInterfaceASTNode(name, definitionsType, currProperties, definit
         const { type, $ref, properties, additionalProperties, items, enum: _enum, oneOf, allOf, anyOf, example, description, default: _default, } = property;
         type && logger(`[${currLoggerName}] <${key}> is ${type}`);
         // 当存在oneOf、allOf、anyOf时，需要特殊处理
+        // Known limitation: 当 someOf 项引用一个 record definition（$ref 到 additionalProperties 型）时，
+        // 下面把 anchor.jsonData 塞到 properties 里可能产生 map 伪装形态。当前生产 swagger 里未使用
+        // someOf + record 组合，未修补。若未来触发，可参考 $ref 分支的 schema-aware 判定。
         if (oneOf || allOf || anyOf) {
             const someOfList = oneOf || allOf || anyOf || [];
             const someOfDataTypeFlag = [];
@@ -132,7 +136,17 @@ function generateInterfaceASTNode(name, definitionsType, currProperties, definit
                     interfaceJSONData[key] = anchorPointItem.jsonData;
                 }
                 else {
-                    interfaceJSONData[key] = { type: 'object', properties: anchorPointItem.jsonData };
+                    // anchor 的 jsonData 有两种形态：
+                    //   A) interface 型：{ fieldA: {schema...}, ... }  ← 需包成 { type: 'object', properties: ... }
+                    //   B) record/schema 型：{ type: 'object'|'array', additionalProperties|items|properties: ... }  ← 已是合法 schema，直接透传
+                    // 判定见 utils/is-schema-like.ts（要求 type 为字符串且含 additionalProperties/items/properties 之一）。
+                    const anchorJSON = anchorPointItem.jsonData;
+                    if ((0, is_schema_like_1.isSchemaLike)(anchorJSON)) {
+                        interfaceJSONData[key] = anchorJSON;
+                    }
+                    else {
+                        interfaceJSONData[key] = { type: 'object', properties: anchorJSON };
+                    }
                 }
                 keywordTypeNode = ts.factory.createTypeReferenceNode(ts.factory.createIdentifier(anchorPointItem.exportName), undefined);
                 // 定义Record
@@ -140,7 +154,13 @@ function generateInterfaceASTNode(name, definitionsType, currProperties, definit
             else if (additionalProperties) {
                 const { recordContent, recordDependency, descriptionMap, recordJSON } = (0, generate_record_ast_node_1.generateRecordASTNode)(name, definitionsType, additionalProperties, definitions, defintionsMap);
                 keywordTypeNode = recordContent;
-                interfaceJSONData[key] = { type: 'object', properties: recordJSON };
+                // recordJSON 本身就是合法 map schema：
+                //   { type: 'object', additionalProperties: {...} }  或
+                //   { type: 'array',  items: {...} }
+                // 直接透传即可；不要包成 { type: 'object', properties: recordJSON }，
+                // 否则 additionalProperties/items 会被下游 CLI 生成器误认为具名子字段，
+                // 产生 --env-type / --env-additionalProperties 这样的幻影 flag。
+                interfaceJSONData[key] = recordJSON;
                 // 合并依赖
                 interfaceDependency = new Set([
                     ...interfaceDependency,

package/built/codegen/record/generate-record-ast-node.js

@@ -61,7 +61,25 @@ function generateRecordASTNode(name, type, additionalProperties, swaggerDefiniti
         if (ref) {
             logger(`[${name}] is anchor point, $ref -> ${ref}`);
             const anchorPointItem = (0, generate_record_anchor_ast_node_1.generateRecordAnchorASTNode)(name, ref, swaggerDefinitions, defintionsMap, recordDependency);
-            jsonData.properties = anchorPointItem.jsonData;
+            // 生成合法的 JSON Schema map 结构：
+            //   数组元素为 $ref  → { type: 'array', items: { type: 'object', properties: {...} } }
+            //   对象值为  $ref  → { type: 'object', additionalProperties: { type: 'object', properties: {...} } }
+            // 注意：不要把 anchor 的 jsonData 直接塞到父级 properties，会产生
+            // {type,additionalProperties} 被误解为具名子字段的伪装结构。
+            if (additionalProperties.type === constants_1.DefinitionsType.ARRAY) {
+                jsonData.type = 'array';
+                jsonData.items = {
+                    type: 'object',
+                    properties: anchorPointItem.jsonData,
+                };
+            }
+            else {
+                jsonData.type = 'object';
+                jsonData.additionalProperties = {
+                    type: 'object',
+                    properties: anchorPointItem.jsonData,
+                };
+            }
             const typeReferenceNode = ts.factory.createTypeReferenceNode(ts.factory.createIdentifier(anchorPointItem.exportName), undefined);
             recordContent = [
                 ts.factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),

package/built/skills-tools/generate-skill-cli-help.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateSkillCliHelp = generateSkillCliHelp;
 const debug_1 = __importDefault(require("debug"));
 const get_defintion_name_1 = require("../utils/get-defintion-name");
+const is_schema_like_1 = require("../utils/is-schema-like");
 const logger = (0, debug_1.default)('csg:cli');
 function isBaseApiParamArrayData(schema) {
     return schema.type && schema.type === 'array';
@@ -106,14 +107,38 @@ function generateSkillCliHelp(requestMap, defintionsMap) {
                         if ($ref) {
                             const defintionName = (0, get_defintion_name_1.getDefinitionName)($ref);
                             const defintion = defintionsMap[defintionName];
-                            if (item.schema.type === 'array') {
-                                item.schema.items = {
-                                    type: 'object',
-                                    properties: { ...defintion.jsonData },
-                                };
+                            if (!defintion) {
+                                // $ref 无法在 defintionsMap 中命中（可能是 stale/未生成的 definition）；
+                                // 保底：回退到原始 parameter.schema，避免访问 undefined.jsonData 崩溃。
+                                logger(`[skip parameter schema] $ref not found in defintionsMap: ${$ref}`);
+                                item.schema = parameter.schema;
                             }
                             else {
-                                item.schema.properties = { ...defintion.jsonData };
+                                // definition.jsonData 有两种形态：
+                                //   A) interface 型：{ fieldA: {schema...}, fieldB: {...} }  ← 键 = 字段名
+                                //   B) record/顶层 schema 型：{ type: 'object'|'array', additionalProperties|items|properties: ... }
+                                // A 型应展开为 properties/items.properties；B 型是完整 schema，直接透传。
+                                // 判定见 utils/is-schema-like.ts。
+                                const jsonData = defintion.jsonData;
+                                if ((0, is_schema_like_1.isSchemaLike)(jsonData)) {
+                                    // record / array / primitive schema 本身作为 body
+                                    if (item.schema.type === 'array') {
+                                        item.schema.items = { ...jsonData };
+                                    }
+                                    else {
+                                        // 直接用 schema 覆盖 item.schema（保留 type/additionalProperties/items 等）
+                                        item.schema = { ...jsonData };
+                                    }
+                                }
+                                else if (item.schema.type === 'array') {
+                                    item.schema.items = {
+                                        type: 'object',
+                                        properties: { ...jsonData },
+                                    };
+                                }
+                                else {
+                                    item.schema.properties = { ...jsonData };
+                                }
                             }
                         }
                         else {
@@ -158,14 +183,30 @@ function generateSkillCliHelp(requestMap, defintionsMap) {
                         if ($ref) {
                             const defintionName = (0, get_defintion_name_1.getDefinitionName)($ref);
                             const defintion = defintionsMap[defintionName];
-                            if (item.schema.type === 'array') {
-                                item.schema.items = {
-                                    type: 'object',
-                                    properties: defintion.jsonData,
-                                };
+                            if (!defintion) {
+                                // $ref 未命中：跳过 schema 展开，保留 item.schema 已有的最小结构（type 已在上文赋值）。
+                                logger(`[skip response schema] $ref not found in defintionsMap: ${$ref}`);
                             }
                             else {
-                                item.schema.properties = defintion.jsonData;
+                                // 见上方（parameter 分支）注释：区分 interface 型 vs schema 型 jsonData
+                                const jsonData = defintion.jsonData;
+                                if ((0, is_schema_like_1.isSchemaLike)(jsonData)) {
+                                    if (item.schema.type === 'array') {
+                                        item.schema.items = { ...jsonData };
+                                    }
+                                    else {
+                                        item.schema = { ...jsonData };
+                                    }
+                                }
+                                else if (item.schema.type === 'array') {
+                                    item.schema.items = {
+                                        type: 'object',
+                                        properties: jsonData,
+                                    };
+                                }
+                                else {
+                                    item.schema.properties = jsonData;
+                                }
                             }
                         }
                         else {

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

@@ -5,6 +5,7 @@ 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 is_map_field_1 = require("./is-map-field");
 const flatten_array_object_options_1 = require("./flatten-array-object-options");
 /** 递归扁平化嵌套对象类型的子属性 */
 function flattenNestedObjectOptions(objectKey, prop, isRequired, usedKeys) {
@@ -21,6 +22,11 @@ function flattenNestedObjectOptions(objectKey, prop, isRequired, usedKeys) {
             options.push(...(0, flatten_array_object_options_1.flattenArrayObjectOptions)(flatKey, subProp, isRequired, usedKeys));
             continue;
         }
+        // 深层 map / 字典型：暂不为其生成 CLI flag（避免歧义），
+        // 让调用方走 `--data` fallback 传该字段。若未来需要，可扩展 KEY=VALUE 语义。
+        if ((0, is_map_field_1.isMapField)(subProp)) {
+            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;

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

@@ -6,6 +6,7 @@ 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 is_map_field_1 = require("./is-map-field");
 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");
@@ -72,6 +73,24 @@ function flattenToolOptions(toolInfo) {
                 options.push(...(0, flatten_array_object_options_1.flattenArrayObjectOptions)(key, prop, isRequired, usedKeys));
                 continue;
             }
+            // map / 字典型（swagger additionalProperties）：注册为 `--<key> NAME=VALUE`
+            // 可多次传入，运行时组装成对象。
+            if ((0, is_map_field_1.isMapField)(prop)) {
+                const optKey = usedKeys.has(key) ? `d-${key}` : key;
+                const rawDesc = (0, trim_summary_1.trimSummary)(prop.description || '');
+                const hint = ' (KEY=VALUE 格式，可多次传入)';
+                const desc = isRequired ? `[必填] ${rawDesc}${hint}` : `${rawDesc}${hint}`;
+                options.push({
+                    optKey,
+                    valuePlaceholder: '<KEY=VALUE>',
+                    description: desc,
+                    required: !!isRequired,
+                    isArray: true,
+                    source: 'body',
+                    isMapField: true,
+                });
+                continue;
+            }
             if ((0, is_nested_object_1.isNestedObject)(prop)) {
                 options.push(...(0, flatten_nested_object_options_1.flattenNestedObjectOptions)(key, prop, isRequired, usedKeys));
                 continue;

package/built/utils/is-map-field.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMapField = isMapField;
+exports.getMapValueType = getMapValueType;
+/**
+ * 判断 body schema property 是否为 map / 字典类型（swagger `additionalProperties`）。
+ *
+ * 合法形态：
+ *   { type: 'object', additionalProperties: { type: 'string' | 'number' | 'boolean' | 'any' } }
+ *
+ * 不同时具有具名 `properties` 才算 map；若同时具有 properties 则视为混合结构，
+ * 按嵌套对象处理，避免行为歧义。
+ *
+ * 注意：仅当 map value 是 primitive（string/number/boolean/integer/any）时才当作
+ * "可通过 `--<key> KEY=VALUE` 传入" 的 map；若 value 是 $ref 或嵌套 object/array，
+ * `KEY=VALUE` 语义无法表达复杂结构，此时不视为 CLI 层面的 map 字段（回退到 --data）。
+ *
+ * ⚠️ 调用顺序约束：必须先于 `isNestedObject` 调用（见 flatten-tool-options.ts /
+ * flatten-nested-object-options.ts）。原因：若 help.json 中存在「additionalProperties
+ * 被误塞进 properties」的伪装形态，`isNestedObject` 虽然通过 `looksLikeAdditionalPropertiesMisnested`
+ * 做了防御，但 `isMapField` 对这种伪装无法识别（此时 `prop.properties` 非空、
+ * `prop.additionalProperties` 缺失）。当前生成器已修复该伪装，但调用顺序仍作为
+ * 二次防御依赖被保留，反转顺序会导致伪装数据被错误分类。
+ */
+function isMapField(prop) {
+    if (!prop || prop.type !== 'object')
+        return false;
+    const ap = prop.additionalProperties;
+    if (!ap || typeof ap !== 'object')
+        return false;
+    // 有具名 properties 时不视为 map（保留嵌套对象语义）
+    if (prop.properties && Object.keys(prop.properties).length > 0)
+        return false;
+    // value 是 $ref / 嵌套 object 结构：CLI 层无法用 KEY=VAL 表达
+    if (ap.$ref)
+        return false;
+    if (ap.properties && Object.keys(ap.properties).length > 0)
+        return false;
+    return true;
+}
+/**
+ * 获取 map 型字段的 value 类型（默认 string）。
+ */
+function getMapValueType(prop) {
+    var _a;
+    const t = (_a = prop === null || prop === void 0 ? void 0 : prop.additionalProperties) === null || _a === void 0 ? void 0 : _a.type;
+    return typeof t === 'string' ? t : 'string';
+}

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

@@ -1,9 +1,58 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isNestedObject = isNestedObject;
-/** 判断 body 属性是否为嵌套对象类型 */
+/**
+ * 判断 body 属性是否为「真正的嵌套对象」（有具名子字段），
+ * 用于决定要不要把子字段扁平化成独立的 CLI 选项。
+ *
+ * 排除情况：map/字典型（swagger `additionalProperties`）。
+ * 某些 help.json 生成器会把 `additionalProperties` 误塞进 `properties`，
+ * 产生非法伪装结构，例如：
+ *   {
+ *     "type": "object",
+ *     "properties": {
+ *       "type": "object",                     // 字面量值，不是 schema
+ *       "additionalProperties": { "type": "string" }
+ *     }
+ *   }
+ * 这种情况下 `env` 本质是 `map[string]string`，不应展开出
+ * `--env-type` / `--env-additionalProperties` 这样的幻影 flag。
+ *
+ * ⚠️ 调用顺序约束：应在 `isMapField` 之后调用（见 flatten-tool-options.ts /
+ * flatten-nested-object-options.ts）。合法 map 字段（无 properties + 有 additionalProperties）
+ * 会被 `isMapField` 先行捕获；本函数只兜底伪装形态。反转顺序会导致合法 map 被误当作嵌套对象展开。
+ */
 function isNestedObject(prop) {
-    if (prop.type !== 'object')
+    if (!prop || prop.type !== 'object')
         return false;
-    return !!(prop.properties && Object.keys(prop.properties).length > 0);
+    // 显式声明为字典型（`additionalProperties` 是 schema 对象且无具名 properties）：直接排除
+    // 注意：`additionalProperties: true|false` 是合法 JSON Schema 布尔值（表示是否允许额外属性），
+    // 不构成"字典型"语义，这里只对 object 值排除。
+    if (prop.additionalProperties
+        && typeof prop.additionalProperties === 'object'
+        && (!prop.properties || Object.keys(prop.properties).length === 0)) {
+        return false;
+    }
+    if (!prop.properties || Object.keys(prop.properties).length === 0)
+        return false;
+    // 启发式：合法 properties 里每个值都应该是 schema 对象（object 类型）。
+    // 若出现字面量值（如 "type": "object"），说明是被误塞进来的 additionalProperties 结构。
+    if (looksLikeAdditionalPropertiesMisnested(prop.properties))
+        return false;
+    return true;
+}
+/**
+ * 识别「additionalProperties 被错误嵌入到 properties」的伪装结构。
+ * 判定条件（同时满足即认为是伪装）：
+ *   1) properties 中存在字面量 `type` 键（值不是对象）
+ *   2) properties 中存在 `additionalProperties` 键（值是对象）
+ * 这种组合在合法 JSON Schema 里不可能出现（子字段名不会是 "type"/"additionalProperties"
+ * 且值同时又是这种形态），因此可以稳妥地识别为伪装。
+ */
+function looksLikeAdditionalPropertiesMisnested(properties) {
+    const typeVal = properties.type;
+    const addVal = properties.additionalProperties;
+    const typeIsLiteral = typeof typeVal === 'string';
+    const addIsObject = addVal !== null && typeof addVal === 'object';
+    return typeIsLiteral && addIsObject;
 }

package/built/utils/is-schema-like.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSchemaLike = isSchemaLike;
+/**
+ * 判断 codegen 中间产物 `jsonData` 是「schema 本身」还是「interface 型字段映射」。
+ *
+ * 背景：在 codegen 过程中，anchor / $ref 指向的 definition 的 `jsonData` 存在两种形态：
+ *
+ *   A) interface 型：`{ fieldA: {schema...}, fieldB: {schema...}, ... }`
+ *      - 键为字段名，值为该字段的 schema 对象
+ *      - 顶层不含字面量 `type: 'object' | 'array'` 键
+ *
+ *   B) record / schema 型：`{ type: 'object' | 'array', additionalProperties?|items?|properties?: ... }`
+ *      - 本身就是一个完整合法的 JSON Schema
+ *      - 顶层 `type` 键为字符串字面量
+ *
+ * 消费侧（如 generate-interface-ast-node、generate-skill-cli-help）需要区分二者：
+ *   - A 型需包成 `{ type: 'object', properties: jsonData }`
+ *   - B 型可直接透传
+ *
+ * 判定策略（严格）：
+ *   同时满足以下条件才视为 B 型：
+ *     1) `type` 为字符串（'object' / 'array' / 'string' / ...）
+ *     2) 至少含有 `additionalProperties` / `items` / `properties` 之一
+ *        （避免"某个 interface 恰好有一个 string 类型的 type 字段"被误判为 B 型）
+ *
+ * 保守起见：不满足严格条件时按 A 型处理（interface 型），走 `{ type: 'object', properties: ... }` 包装，
+ * 与旧行为兼容。
+ */
+function isSchemaLike(jsonData) {
+    if (!jsonData || typeof jsonData !== 'object')
+        return false;
+    if (typeof jsonData.type !== 'string')
+        return false;
+    return (jsonData.additionalProperties !== undefined
+        || jsonData.items !== undefined
+        || jsonData.properties !== undefined);
+}

package/client/lib/format-params.ts

@@ -5,6 +5,8 @@ import { buildNestedFieldMap } from '../utils/build-nested-field-map';
 import type { NestedFieldMapping } from '../utils/build-nested-field-map';
 import { restoreOriginalKeys } from '../utils/restore-original-keys';
 import { matchArrayObjectField } from '../utils/match-array-object-field';
+import { isNestedObjectSchema } from '../utils/is-nested-object-schema';
+import { isMapField, getMapValueType } from '../utils/is-map-field';
 
 /**
  * 获取 tool 的参数定义（用于自动分发 --key value 到 path/query）
@@ -36,6 +38,20 @@ function filterIllegalChars(str: string): string {
   return str.replace(/\x00/g, '');
 }
 
+/**
+ * 将不受信任的字符串安全地转成日志片段：
+ *   - 转义 C0/DEL 控制字符（\r \n \t 及 ANSI 转义序列等），避免污染终端显示
+ *   - 截断到 80 字符，防止超长 item 刷屏
+ * 用于 console.warn 中拼接用户输入片段的场景。
+ */
+function sanitizeForLog(str: string): string {
+  const escaped = str.replace(/[\x00-\x1f\x7f]/g, (ch) => {
+    const code = ch.charCodeAt(0).toString(16).padStart(2, '0');
+    return `\\x${code}`;
+  });
+  return escaped.length > 80 ? `${escaped.slice(0, 80)}…` : escaped;
+}
+
 function assignBodyValue(
   target: Record<string, any>,
   key: string,
@@ -51,6 +67,72 @@ function assignBodyValue(
   }
 }
 
+/**
+ * 将 `--<key> NAME=VALUE`（可多次）收集到的字符串数组解析为对象，写入 body。
+ * 用法示例：`--env FOO=bar --env BAZ=qux` → `{ env: { FOO: 'bar', BAZ: 'qux' } }`
+ *
+ * value 侧类型转换（依据 additionalProperties.type）：
+ *   - number：Number(v)，NaN 时回退到原字符串（避免误吞非数字输入）
+ *   - boolean：仅 "true"/"false" 严格匹配转换，其他保留字符串
+ *   - 其他：保留原字符串（对 string 型做一次 shell 反解，与 assignBodyValue 一致）
+ *
+ * 兼容：单次传入时 commander 也可能给到字符串（isArray 会写数组，这里保底）。
+ */
+function assignMapField(
+  target: Record<string, any>,
+  key: string,
+  value: any,
+  valueType: string,
+): void {
+  const items = Array.isArray(value) ? value : [value];
+  const map: Record<string, any> = target[key] && typeof target[key] === 'object' && !Array.isArray(target[key])
+    ? target[key]
+    : {};
+
+  for (const item of items) {
+    if (typeof item !== 'string') continue;
+    const eq = item.indexOf('=');
+    if (eq <= 0) {
+      // 非 KEY=VALUE 形态：跳过并给个 stderr 提示，避免静默丢数据
+      // eslint-disable-next-line no-console
+      console.warn(`[cnb] --${key} 需要 KEY=VALUE 格式，已忽略: ${sanitizeForLog(item)}`);
+      continue;
+    }
+    const k = item.slice(0, eq);
+    // KEY 合法性校验：拒绝空、纯空白、含控制字符、以及前后带空白的 key。
+    // 若前后有空白（如 '  A '），trim 后写入会与 'A' 静默合并，非用户预期；直接拒绝。
+    // 与 value 侧的 filterIllegalChars 保持对称防御。
+    if (!k || k !== k.trim() || /[\x00-\x1f\x7f]/.test(k)) {
+      // eslint-disable-next-line no-console
+      console.warn(`[cnb] --${key} KEY 非法，已忽略: ${sanitizeForLog(item)}`);
+      continue;
+    }
+    const rawV = item.slice(eq + 1);
+    let v: any = rawV;
+    if (valueType === 'number') {
+      // 空字符串或非数字：保留原字符串（避免 Number('') === 0 的静默转换）
+      if (rawV.length === 0) {
+        v = rawV;
+      } else {
+        const n = Number(rawV);
+        v = Number.isNaN(n) ? rawV : n;
+      }
+    } else if (valueType === 'boolean') {
+      if (rawV === 'true') v = true;
+      else if (rawV === 'false') v = false;
+    } else {
+      // 与 assignBodyValue 不同：map value 不做 removeSlashes 反解。
+      // 原因：环境变量常见值（URL / Windows 路径 / JWT 等）中的反斜杠会被
+      // removeSlashes 无损伤规则误吞（如 "C:\path" → "C:path"）。
+      // shell 侧的转义（$VAR / 引号）用户已经掌控；这里仅过滤非法 NUL 字符。
+      v = filterIllegalChars(rawV);
+    }
+    map[k] = v;
+  }
+
+  target[key] = map;
+}
+
 /**
  * 格式化参数
  * 支持新的 --key value 扁平格式，同时向后兼容旧的 --path/--query JSON 格式。
@@ -132,10 +214,14 @@ export function formatParams(
     // 收集嵌套对象展开字段的临时存储（深层嵌套结构）：{ rootObjectKey: { nested: { path: value } } }
     const nestedObjectCollector: Record<string, Record<string, any>> = {};
 
+    // 记录已被 `--<key> KEY=VAL` flag 处理过的 map 字段名，
+    // 用于在 --data fallback 合并时对同名 map 字段做 shallow merge（避免 flag 覆盖 --data 的整个 map）。
+    const mapFieldKeysUsed = new Set<string>();
+
     // 预建所有嵌套对象字段的 camelCased flat key → pathKeys 映射表
     const nestedFieldMap = new Map<string, NestedFieldMapping>();
     for (const [rootKey, rootProp] of Object.entries(bodyProps) as [string, any][]) {
-      if (rootProp.type === 'object' && rootProp.properties && Object.keys(rootProp.properties).length > 0) {
+      if (isNestedObjectSchema(rootProp)) {
         const subMap = buildNestedFieldMap(rootProp.properties, rootKey, [rootKey]);
         for (const [k, v] of subMap) {
           nestedFieldMap.set(k, v);
@@ -226,7 +312,12 @@ export function formatParams(
       } else if (bodyProps[key]) {
         // body 字段（无冲突，直接用原 key）
         if (!formatted.data) formatted.data = {};
-        assignBodyValue(formatted.data, key, value, bodyProps[key].type);
+        if (isMapField(bodyProps[key])) {
+          assignMapField(formatted.data, key, value, getMapValueType(bodyProps[key]));
+          mapFieldKeysUsed.add(key);
+        } else {
+          assignBodyValue(formatted.data, key, value, bodyProps[key].type);
+        }
       } else {
         // 处理 d- 前缀（冲突时 CLI 以 d- 前缀传入）
         const stripped = (key.startsWith('d-') || key.startsWith('d_'))
@@ -276,7 +367,12 @@ export function formatParams(
           const originalKey = key.replace(/^d[-_]/, '');
           if (bodyProps[originalKey]) {
             if (!formatted.data) formatted.data = {};
-            assignBodyValue(formatted.data, originalKey, value, bodyProps[originalKey].type);
+            if (isMapField(bodyProps[originalKey])) {
+              assignMapField(formatted.data, originalKey, value, getMapValueType(bodyProps[originalKey]));
+              mapFieldKeysUsed.add(originalKey);
+            } else {
+              assignBodyValue(formatted.data, originalKey, value, bodyProps[originalKey].type);
+            }
           } else {
             if (!formatted.query) formatted.query = {};
             formatted.query[key] = typeof value === 'string' && !isNaN(Number(value)) ? Number(value) : value;
@@ -322,10 +418,23 @@ export function formatParams(
     // 合并 --data 提供的 body：
     //   - 数组 body：整体替换 formatted.data（数组 body 接口没有逐字段 flag，直接覆盖）
     //   - 对象 body：作为 base，逐个 body flag（如 --event）已写入 formatted.data，flag 优先
+    //     特殊：对 map 型字段（`--<key> KEY=VAL` flag 处理过的），做 shallow merge，
+    //     即 { ...dataBaseMap, ...flagMap }，避免 flag 传的单条 kv 覆盖 --data 中提供的整块 map。
     if (dataArrayFromFlag) {
       formatted.data = dataArrayFromFlag;
     } else if (dataBaseFromFlag) {
-      formatted.data = { ...dataBaseFromFlag, ...(formatted.data || {}) };
+      const mergedMapFields: Record<string, any> = {};
+      for (const mapKey of mapFieldKeysUsed) {
+        const baseVal = dataBaseFromFlag[mapKey];
+        const flagVal = (formatted.data || {})[mapKey];
+        // 显式判 `!= null`（同时排除 null 和 undefined），避免脏 --data 传入 null 时
+        // 短路失效的隐患；`Array.isArray` 兜底避免把数组当对象 merge。
+        if (baseVal != null && typeof baseVal === 'object' && !Array.isArray(baseVal)
+          && flagVal != null && typeof flagVal === 'object' && !Array.isArray(flagVal)) {
+          mergedMapFields[mapKey] = { ...baseVal, ...flagVal };
+        }
+      }
+      formatted.data = { ...dataBaseFromFlag, ...(formatted.data || {}), ...mergedMapFields };
     }
 
     // --body-file 优先级最高：覆盖 --body 逐字段值与 --data 中的 body，

package/client/utils/build-nested-field-map.ts

@@ -1,3 +1,6 @@
+import { isNestedObjectSchema } from './is-nested-object-schema';
+import { isMapField } from './is-map-field';
+
 export interface NestedFieldMapping {
   pathKeys: string[];       // schema 路径，如 ["testBody", "critical_count", "id"]
   leafSchema: any;          // 叶子节点的 schema 定义
@@ -21,12 +24,17 @@ export function buildNestedFieldMap(
     const flatKey = `${prefix}@${subKey}`;
     const currentPath = [...pathKeys, subKey];
 
-    if (subProp.type === 'object' && subProp.properties && Object.keys(subProp.properties).length > 0) {
+    if (isNestedObjectSchema(subProp)) {
       // 嵌套对象：继续递归
       const subMap = buildNestedFieldMap(subProp.properties, flatKey, currentPath);
       for (const [k, v] of subMap) {
         map.set(k, v);
       }
+    } else if (isMapField(subProp)) {
+      // 深层 map 字段：不作为叶子注册（CLI 层暂不为深层 map 生成 flag，
+      // 与 src/utils/flatten-nested-object-options.ts 保持一致）。
+      // 用户如需传值，应通过 --data 传整体 JSON。
+      continue;
     } else {
       // 叶子节点：注册 flat key
       const camelKey = flatKey;

package/client/utils/is-map-field.ts

@@ -0,0 +1,18 @@
+/**
+ * 运行时判断 body schema property 是否为 map / 字典类型（`additionalProperties`）。
+ * 与 src/utils/is-map-field.ts 保持一致。
+ */
+export function isMapField(prop: any): boolean {
+  if (!prop || prop.type !== 'object') return false;
+  const ap = prop.additionalProperties;
+  if (!ap || typeof ap !== 'object') return false;
+  if (prop.properties && Object.keys(prop.properties).length > 0) return false;
+  if (ap.$ref) return false;
+  if (ap.properties && Object.keys(ap.properties).length > 0) return false;
+  return true;
+}
+
+export function getMapValueType(prop: any): string {
+  const t = prop?.additionalProperties?.type;
+  return typeof t === 'string' ? t : 'string';
+}

package/client/utils/is-nested-object-schema.ts

@@ -0,0 +1,35 @@
+/**
+ * 判断 schema 属性是否为「真正的嵌套对象」（有具名子字段）。
+ * 用于运行期决定是否要为该字段构建 nestedFieldMap。
+ *
+ * 与 `src/utils/is-nested-object.ts` 保持一致的判定规则：
+ * 排除 map/字典型结构（swagger `additionalProperties`），
+ * 包括 help.json 生成器把 `additionalProperties` 误塞进 `properties`
+ * 的伪装形态（会产生非法子字段 `type` / `additionalProperties`）。
+ */
+export function isNestedObjectSchema(prop: any): boolean {
+  if (!prop || prop.type !== 'object') return false;
+
+  // 显式字典型（additionalProperties 是 schema 对象且无具名 properties）
+  if (
+    prop.additionalProperties
+    && typeof prop.additionalProperties === 'object'
+    && (!prop.properties || Object.keys(prop.properties).length === 0)
+  ) {
+    return false;
+  }
+
+  if (!prop.properties || Object.keys(prop.properties).length === 0) return false;
+
+  if (looksLikeAdditionalPropertiesMisnested(prop.properties)) return false;
+
+  return true;
+}
+
+function looksLikeAdditionalPropertiesMisnested(properties: Record<string, any>): boolean {
+  const typeVal = properties.type;
+  const addVal = properties.additionalProperties;
+  const typeIsLiteral = typeof typeVal === 'string';
+  const addIsObject = addVal !== null && typeof addVal === 'object';
+  return typeIsLiteral && addIsObject;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cnbcool/cnb-api-generate",
-  "version": "2.11.8",
+  "version": "2.12.0",
   "main": "./built/index.js",
   "module": "./src/index.ts",
   "types": "./src/index.ts",
@@ -24,6 +24,9 @@
     "lint:fix": "eslint src --fix",
     "test": "jest",
     "test:cover": "jest --coverage",
+    "test:cli": "node scripts/cli-smoke-test.js",
+    "test:cli:quick": "node scripts/cli-smoke-test.js --skip-gen",
+    "test:cli:live": "node scripts/cli-smoke-test.js --skip-gen --live",
     "gen:test": "npx swagger-typescript-api generate --path ./template/swagger.json --axios --extract-request-body --extract-response-body --extract-request-params --extract-response-error -o ./test"
   },
   "dependencies": {

package/built/test.js

@@ -1 +0,0 @@
-"use strict";