digitalsee-ai-flow-cli 0.9.24-beta → 0.9.29-beta

package/dist/services/skillGenerator.js

@@ -37,10 +37,11 @@ exports.generateAllSkills = generateAllSkills;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const knowledge_1 = require("@/api/knowledge");
+const node_1 = require("@/api/node");
 const format_1 = require("@/utils/format");
 const output_1 = require("@/utils/output");
 const nodePackage_1 = require("@/utils/nodePackage");
-const classicNodePorts_1 = require("@/services/classicNodePorts");
+const fieldTypeRegistry_1 = require("@/services/fieldTypeRegistry");
 async function generateAllSkills(outputDir) {
     const progress = {
         totalCategories: 0,
@@ -50,22 +51,21 @@ async function generateAllSkills(outputDir) {
         totalActions: 0,
         processedActions: 0,
         skillsGenerated: 0,
-        builtinNodeTypes: 0,
         errors: [],
     };
-    // builtin-nodes.md：内置节点类型端口参考（纯本地数据，探针之前写入，
-    // 即使目标环境不支持 NodePackage 也能产出连线知识）
-    writeBuiltinNodesDoc(outputDir, progress);
     const categoryTypes = [
         { type: 'normal', scene: 'normal', trigger: false, label: '自动化' },
         { type: 'normal-trigger', scene: 'normal', trigger: true, label: '自动化触发器' },
         { type: 'mcp', scene: 'mcp', trigger: false, label: 'MCP' },
         { type: 'mcp-trigger', scene: 'mcp', trigger: true, label: 'MCP触发器' },
     ];
-    // 本版本统一使用 connectable API；服务端不支持时直接失败并给出降级建议，不再回退旧接口
-    const nodePackageSupported = await (0, nodePackage_1.checkAndCacheNodePackageSupport)();
-    if (!nodePackageSupported) {
-        throw new Error(`目标 baseUrl 不支持 NodePackage。${nodePackage_1.NODE_PACKAGE_DOWNGRADE_HINT}`);
+    // NodePackage 支持探测（走缓存），connectable 路径优先取 matched_actions
+    let nodePackageSupported = false;
+    try {
+        nodePackageSupported = await (0, nodePackage_1.checkAndCacheNodePackageSupport)();
+    }
+    catch {
+        nodePackageSupported = false;
     }
     for (const ct of categoryTypes) {
         try {
@@ -81,7 +81,7 @@ async function generateAllSkills(outputDir) {
             for (const category of categories) {
                 const categoryMdDir = path.join(mdDir, category.name);
                 fs.mkdirSync(categoryMdDir, { recursive: true });
-                await processCategory(category, categoryMdDir, progress, ct.trigger, ct.scene);
+                await processCategory(category, categoryMdDir, progress, ct.trigger, ct.scene, nodePackageSupported);
             }
         }
         catch (error) {
@@ -91,7 +91,7 @@ async function generateAllSkills(outputDir) {
     }
     return progress;
 }
-async function processCategory(category, mdDir, progress, trigger = false, scene = '') {
+async function processCategory(category, mdDir, progress, trigger = false, scene = 'normal', nodePackageSupported = false) {
     const categoryKey = String(category.name || '');
     const categoryLabel = String(category.label || categoryKey);
     try {
@@ -113,7 +113,7 @@ async function processCategory(category, mdDir, progress, trigger = false, scene
             const connectorBatchSize = 3;
             for (let i = 0; i < items.length; i += connectorBatchSize) {
                 const batch = items.slice(i, i + connectorBatchSize);
-                await Promise.all(batch.map((item) => processConnector(item.connector, category, mdDir, progress, trigger, scene)));
+                await Promise.all(batch.map((item) => processConnector(item.connector, category, mdDir, progress, trigger, scene, nodePackageSupported)));
                 progress.processedNodes += batch.length;
             }
             processedCount += items.length;
@@ -137,17 +137,30 @@ async function processCategory(category, mdDir, progress, trigger = false, scene
     }
     progress.processedCategories++;
 }
-async function processConnector(connector, category, mdDir, progress, trigger = false, scene = '') {
+async function processConnector(connector, category, mdDir, progress, trigger = false, scene = 'normal', nodePackageSupported = false) {
     try {
-        // connectable 按 link_id 重查，一次请求同时拿 connector 与 matched_actions（含 node_schema）
-        const result = await (0, knowledge_1.searchNodesByCategory)({
-            mode: 'independent',
-            scene,
-            trigger,
-            linkId: connector.id,
-        });
-        const exact = result.items.find((candidate) => candidate.connector.id === connector.id) ?? result.items[0];
-        const actions = (exact?.matched_actions ?? []) || [];
+        // NodePackage 连接器：connectable 按 link_id 重查，一次请求同时拿 connector
+        // 与 matched_actions（含 node_schema）；false 或请求失败回退 legacy getActions
+        let actions = null;
+        if (nodePackageSupported) {
+            try {
+                const result = await (0, knowledge_1.searchNodesByCategory)({
+                    mode: 'independent',
+                    scene,
+                    trigger,
+                    linkId: connector.id,
+                });
+                const exact = result.items.find((candidate) => candidate.connector.id === connector.id) ??
+                    result.items[0];
+                actions = (exact?.matched_actions ?? []) || [];
+            }
+            catch {
+                actions = null;
+            }
+        }
+        if (actions === null) {
+            actions = await (0, node_1.getActions)({ linkId: connector.id, trigger });
+        }
         progress.totalActions += actions.length;
         const actionBatchSize = 5;
         for (let i = 0; i < actions.length; i += actionBatchSize) {
@@ -178,7 +191,6 @@ async function generateSkillFile(action, category, connector, mdDir, progress) {
         action_type: action.action_type || 'action',
         action_key: hasNodeSchema ? action.node_schema?.key || action.action_key : action.action_key,
         action_ver: action.action_ver ?? action.node_schema?.version,
-        is_trigger: Boolean(action.is_trigger),
         connector_id: action.connector_id,
         link_id: connector.id,
         action_id: action.id,
@@ -198,9 +210,9 @@ async function generateSkillFile(action, category, connector, mdDir, progress) {
                 version: action.node_schema.version,
                 name: action.node_schema.name,
                 description: action.node_schema.description,
-                inputs: action.node_schema.inputs ?? [],
-                outputs: action.node_schema.outputs ?? [],
                 input_fields: (0, format_1.nodeSchemaToParams)(action.node_schema.input_fields),
+                // 原始 schema 兜底：保留 item_schema/item_type 等完整描述符，防归一化丢信息
+                raw_input_fields: action.node_schema.input_fields || [],
                 output_fields: (action.node_schema.output_fields || []).map((o) => ({
                     key: o.key,
                     label: o.label,
@@ -219,152 +231,6 @@ async function generateSkillFile(action, category, connector, mdDir, progress) {
         progress.errors.push(`写入 skill 文件 ${safeName} 失败: ${error.message}`);
     }
 }
-function renderClassicPortRow(port) {
-    return `| \`${port.name}\` | ${port.displayName} | \`${port.type ?? 'main'}\` | ${port.maxConnections !== undefined && port.maxConnections !== null
-        ? String(port.maxConnections)
-        : '不限'} |`;
-}
-function renderClassicPortsTable(ports) {
-    if (ports.length === 0)
-        return ['（无端口）', ''];
-    return [
-        '| 端口 | 显示名 | 类型/协议 | 最大连接数 |',
-        '|------|--------|-----------|------------|',
-        ...ports.map(renderClassicPortRow),
-        '',
-    ];
-}
-function renderClassicExampleCommands(descriptor) {
-    const lines = ['### 连线示例', '', '```bash'];
-    const firstOutput = descriptor.outputs[0];
-    const firstInput = descriptor.inputs[0];
-    if (firstOutput) {
-        // 目标侧描述该类型自己的输入桩（若有），否则提示连接下游节点
-        const targetPart = firstInput
-            ? `--target <目标节点ID> --target-handle ${firstInput.name}`
-            : '--target <下游节点ID> --target-handle input';
-        lines.push(`ai-flow flow edge connect --flow-id <flowId> --source <${descriptor.nodeType}的节点ID> ${targetPart} --source-handle ${firstOutput.name}`);
-    }
-    else if (firstInput) {
-        lines.push(`ai-flow flow edge connect --flow-id <flowId> --source <上游节点ID> --target <${descriptor.nodeType}的节点ID> --source-handle output --target-handle ${firstInput.name}`);
-    }
-    for (const rule of descriptor.autoConnect ?? []) {
-        lines.push(`# 自环边（必需结构）：`, `ai-flow flow edge connect --flow-id <flowId> --source <${descriptor.nodeType}的节点ID> --target <同节点ID> --source-handle ${rule.source} --target-handle ${rule.target}`);
-    }
-    // AI slave 桩（连线方向对齐 RCS 82b5976：slave 桩为源，指向 AI 子节点顶部 input 桩）
-    const slaveOutput = descriptor.outputs.find((p) => p.name.startsWith('ai_'));
-    if (slaveOutput) {
-        lines.push(`# AI 子节点接入（${descriptor.nodeType} 的 ${slaveOutput.name} 桩为连线源，AISubNode 顶部 input 桩为目标）：`, `ai-flow flow edge connect --flow-id <flowId> --source <${descriptor.nodeType}的节点ID> --source-handle ${slaveOutput.name} --target <AISubNode节点ID> --target-handle input`);
-    }
-    // 仍作为目标的 slave 入桩（如 BrowserNode ai_model）：协议匹配的源是 AgentNode 的 ai_model 出桩
-    const slaveInput = descriptor.inputs.find((p) => p.name.startsWith('ai_'));
-    if (slaveInput) {
-        lines.push(`# AI 子节点接入 ${slaveInput.name} 桩（源侧用 AgentNode 的同协议 ai_model 出桩）：`, `ai-flow flow edge connect --flow-id <flowId> --source <AgentNode节点ID> --source-handle ai_model --target <${descriptor.nodeType}的节点ID> --target-handle ${slaveInput.name}`);
-    }
-    lines.push('```', '');
-    return lines;
-}
-function builtinNodesDocToMarkdown() {
-    const lines = [
-        '# 内置节点类型端口参考（classic/legacy）',
-        '',
-        '非 NodePackage 节点的内置 handle 声明（数据源：CLI 内置端口表，与 `flow edge connect` / `flow validate` 的端口校验同源）。',
-        '',
-    ];
-    for (const descriptor of Object.values(classicNodePorts_1.CLASSIC_NODE_DESCRIPTORS)) {
-        lines.push(`## ${descriptor.nodeType}（${descriptor.label}）`, '', descriptor.description, '');
-        lines.push('### 输入端口', '', ...renderClassicPortsTable(descriptor.inputs));
-        lines.push('### 输出端口', '', ...renderClassicPortsTable(descriptor.outputs));
-        if (descriptor.nodeType === 'SwitchNode') {
-            lines.push('> 输出端口随 `properties.branches` 实例派生：端口名 = 分支 `id`（`branch` 前缀），显示名 = 分支 `name`；`default-branch` 固定兜底。', '');
-        }
-        if (descriptor.byProtocol && Object.keys(descriptor.byProtocol).length > 0) {
-            lines.push('### 协议变体', '');
-            for (const [protocol, override] of Object.entries(descriptor.byProtocol)) {
-                lines.push(`- 节点 protocol = \`${protocol}\` 时：`);
-                if (override.outputs) {
-                    lines.push(`  - 输出端口变为 ${override.outputs.length === 0 ? '（无）' : override.outputs.map((p) => `\`${p.name}\``).join('、')}`);
-                }
-                if (override.inputs) {
-                    lines.push(`  - 输入端口变为 ${override.inputs.length === 0 ? '（无）' : override.inputs.map((p) => `\`${p.name}\``).join('、')}`);
-                }
-            }
-            lines.push('');
-        }
-        if ((descriptor.autoConnect ?? []).length > 0) {
-            lines.push('### 自动连线', '', ...descriptor.autoConnect.map((rule) => `- \`${rule.source}\` → \`${rule.target}\`（自环边）`), '');
-        }
-        lines.push(...renderClassicExampleCommands(descriptor));
-    }
-    return lines.join('\n');
-}
-function writeBuiltinNodesDoc(outputDir, progress) {
-    try {
-        fs.mkdirSync(outputDir, { recursive: true });
-        fs.writeFileSync(path.join(outputDir, 'builtin-nodes.md'), builtinNodesDocToMarkdown(), 'utf-8');
-        progress.builtinNodeTypes = Object.keys(classicNodePorts_1.CLASSIC_NODE_DESCRIPTORS).length;
-    }
-    catch (error) {
-        progress.errors.push(`生成 builtin-nodes.md 失败: ${error.message}`);
-    }
-}
-const DEFAULT_INPUT_HANDLE = { name: 'input', display_name: '输入', type: 'main' };
-const DEFAULT_OUTPUT_HANDLE = {
-    name: 'output',
-    display_name: '输出',
-    type: 'main',
-};
-function formatHandleConstraints(port, direction) {
-    const allowed = direction === 'input' ? port.allowed_source_node_keys : port.allowed_target_node_keys;
-    const denied = direction === 'input' ? port.denied_source_node_keys : port.denied_target_node_keys;
-    const parts = [];
-    if ((allowed ?? []).length > 0)
-        parts.push(`仅允许 ${allowed.join('、')}`);
-    if ((denied ?? []).length > 0)
-        parts.push(`禁止 ${denied.join('、')}`);
-    return parts.length > 0 ? parts.join('；') : '-';
-}
-function renderHandleTable(ports, direction) {
-    if (ports.length === 0) {
-        return [`（无${direction === 'input' ? '输入' : '输出'} Handle）`, ''];
-    }
-    const lines = [
-        '| Handle | 显示名 | 类型/协议 | 必填 | 最大连接数 | 连接约束 |',
-        '|--------|--------|-----------|------|------------|----------|',
-    ];
-    for (const port of ports) {
-        const maxConnections = port.max_connections === undefined || port.max_connections === null
-            ? '不限'
-            : String(port.max_connections);
-        lines.push(`| \`${port.name}\` | ${port.display_name || port.name} | \`${port.type || 'main'}\` | ${port.required ? '是' : '否'} | ${maxConnections} | ${formatHandleConstraints(port, direction)} |`);
-    }
-    lines.push('');
-    return lines;
-}
-/**
- * 渲染连线的 input/output Handle 说明（连接点位的 wire 名称 + 连线命令示例）。
- * Handle 名称即 `flow edge connect` 的 `--source-handle` / `--target-handle` 取值。
- */
-function renderHandleSection(inputs, outputs, note) {
-    const lines = ['## 连接 Handle (Input / Output)', ''];
-    if (note)
-        lines.push(`> ${note}`, '');
-    lines.push('### 输入 Handle', '', ...renderHandleTable(inputs, 'input'));
-    lines.push('### 输出 Handle', '', ...renderHandleTable(outputs, 'output'));
-    if (inputs.length > 0 || outputs.length > 0) {
-        lines.push('```bash');
-        if (inputs.length > 0) {
-            const names = inputs.map((p) => `\`${p.name}\``).join('、');
-            lines.push(`# 作为下游节点连入（本节点 --target-handle 可选：${names}）`, `ai-flow flow edge connect --flow-id <flowId> --source <上游节点ID> --source-handle <上游输出Handle> --target <本节点ID> --target-handle ${inputs[0].name}`);
-        }
-        if (outputs.length > 0) {
-            const names = outputs.map((p) => `\`${p.name}\``).join('、');
-            lines.push(`# 作为上游节点连出（本节点 --source-handle 可选：${names}）`, `ai-flow flow edge connect --flow-id <flowId> --source <本节点ID> --source-handle ${outputs[0].name} --target <下游节点ID> --target-handle <下游输入Handle>`);
-        }
-        lines.push('```', '');
-    }
-    return lines;
-}
 function skillToMarkdown(skill) {
     const lines = [`# ${skill.name}`, ''];
     if (skill.description) {
@@ -380,18 +246,11 @@ function skillToMarkdown(skill) {
         if (ns.description)
             lines.push(`- **Description**: ${ns.description}`);
         lines.push('');
-        lines.push(...renderHandleSection(ns.inputs, ns.outputs, '连线时通过 `--source-handle` 选择输出 Handle、`--target-handle` 选择输入 Handle；Handle 即端口在流程数据中的 wire 名称。'));
         if (ns.input_fields.length > 0) {
             lines.push('## 配置参数 (Input Fields)', '');
-            lines.push('| 字段名 | 显示名 | 类型 | 必填 | 说明 | 默认值 | 可选值 |');
-            lines.push('|--------|--------|------|------|------|--------|--------|');
-            for (const param of ns.input_fields) {
-                const options = (param.options || [])
-                    ?.map((o) => (o.label !== o.key ? `\`${o.key}\` (${o.label})` : `\`${o.key}\``))
-                    .join(', ') || '-';
-                lines.push(`| \`${param.name}\` | ${param.display_name} | ${param.type} | ${param.required ? '是' : '否'} | ${param.description || '-'} | ${param.default ?? '-'} | ${options} |`);
-            }
+            renderParamsTable(lines, ns.input_fields);
             lines.push('');
+            renderNestedShapes(lines, ns.input_fields);
         }
         if (ns.output_fields.length > 0) {
             lines.push('## 输出字段', '');
@@ -403,22 +262,205 @@ function skillToMarkdown(skill) {
             lines.push('');
         }
     }
-    else {
-        lines.push(...renderHandleSection(skill.is_trigger ? [] : [DEFAULT_INPUT_HANDLE], [DEFAULT_OUTPUT_HANDLE], '本 Skill 未提供 NodePackage schema，以下为内置节点默认 Handle；其他内置节点类型的端口声明见 `builtin-nodes.md`。'));
-        if (skill.parameters.length > 0) {
-            lines.push('## 配置参数', '');
-            lines.push('| 字段名 | 显示名 | 类型 | 必填 | 说明 | 默认值 | 可选值 |');
-            lines.push('|--------|--------|------|------|------|--------|--------|');
-            for (const param of skill.parameters) {
-                const options = (param.options || [])
-                    ?.map((o) => (o.label !== o.key ? `\`${o.key}\` (${o.label})` : `\`${o.key}\``))
-                    .join(', ') || '-';
-                lines.push(`| \`${param.name}\` | ${param.display_name} | ${param.type} | ${param.required ? '是' : '否'} | ${param.description || '-'} | ${param.default ?? '-'} | ${options} |`);
-            }
-            lines.push('');
-        }
+    else if (skill.parameters.length > 0) {
+        lines.push('## 配置参数', '');
+        renderParamsTable(lines, skill.parameters);
+        lines.push('');
+        renderNestedShapes(lines, skill.parameters);
     }
     lines.push('## 原始数据', '', '```json', JSON.stringify(skill, null, 2), '```', '');
     return lines.join('\n');
 }
+/** 参数总表：字段名 / 显示名 / 类型（含注册表值形状）/ 必填 / 说明 / 默认值 / 可选值 / 约束 */
+function renderParamsTable(lines, params) {
+    lines.push('| 字段名 | 显示名 | 类型 | 必填 | 说明 | 默认值 | 可选值 | 约束 |');
+    lines.push('|--------|--------|------|------|------|--------|--------|------|');
+    for (const param of params) {
+        const options = (param.options || [])
+            ?.map((o) => (o.label !== o.key ? `\`${o.key}\` (${o.label})` : `\`${o.key}\``))
+            .join(', ') || '-';
+        const typeLabel = formatTypeLabel(param.type, param);
+        const constraints = formatConstraints(param);
+        lines.push(`| \`${param.name}\` | ${param.display_name} | ${typeLabel} | ${param.required ? '是' : '否'} | ${param.description || '-'} | ${formatDefaultValue(param.default)} | ${options} | ${constraints} |`);
+    }
+}
+/** 类型标签：注册表命中的类型附带值形状契约（kind → 值形状） */
+function formatTypeLabel(typeName, param) {
+    const contract = (0, fieldTypeRegistry_1.findFieldTypeContract)(typeName);
+    let label = contract || (0, fieldTypeRegistry_1.isKnownFieldType)(typeName) ? typeName : `${typeName} (宿主自定义类型)`;
+    if (contract) {
+        const shape = contractShapeLabel(contract);
+        if (shape)
+            label = `${label}: ${shape}`;
+    }
+    if (param) {
+        if (param.properties && param.properties.length > 0) {
+            label = `${label} {${param.properties.map((p) => p.name).join(', ')}}`;
+        }
+        else if (param.item_type) {
+            label = `${label} <${param.item_type}${param.item_fields && param.item_fields.length > 0 ? ` {${param.item_fields.map((f) => f.name).join(', ')}}` : ''}>`;
+        }
+        else if (typeName.toUpperCase() === 'KEYVALUE') {
+            label = `${label} {key,value}[]`;
+        }
+    }
+    return label;
+}
+/** 注册表契约的值形状描述（kind 分类 → 可构造值形状） */
+function contractShapeLabel(contract) {
+    switch (contract.kind) {
+        case 'stringArray':
+            return 'string[]';
+        case 'recordArray':
+            return 'object[]';
+        case 'keyValueArray':
+            return '{key,value}[]';
+        case 'record':
+            return 'object';
+        case 'array':
+            return 'array';
+        case 'object':
+            return 'object';
+        case 'boolean':
+            return 'boolean';
+        case 'number':
+            return 'number';
+        case 'string':
+            return 'string';
+        case 'time':
+            return 'HH:mm:00';
+        case 'code':
+            return 'string (代码，支持 ${...} 表达式编码)';
+        case 'token':
+            return 'string (自动生成的随机 token)';
+        case 'flowRef':
+            return '{flowId,input}';
+        case 'guardRules':
+            return 'GuardRule[]';
+        case 'orList':
+            return '{or_list:[{and_list:[...]}]}';
+        case 'orgNode':
+            return '{id,name}';
+        case 'multiRowExtract':
+            return 'object[]';
+        default:
+            return '';
+    }
+}
+/** 字段级约束摘要：required 之外的 pattern/min/max/长度/数量/变量/枚举提示 */
+function formatConstraints(param) {
+    const parts = [];
+    if (param.validation) {
+        const v = param.validation;
+        if (v.min !== undefined)
+            parts.push(`min=${v.min}`);
+        if (v.max !== undefined)
+            parts.push(`max=${v.max}`);
+        if (v.pattern)
+            parts.push(`pattern: \`${v.pattern}\``);
+        if (v.min_length !== undefined)
+            parts.push(`minLength=${v.min_length}`);
+        if (v.max_length !== undefined)
+            parts.push(`maxLength=${v.max_length}`);
+    }
+    if (param.min_items !== undefined && param.min_items !== null) {
+        parts.push(`minItems=${param.min_items}`);
+    }
+    if (param.max_items !== undefined && param.max_items !== null) {
+        parts.push(`maxItems=${param.max_items}`);
+    }
+    if (param.supports_variables)
+        parts.push('支持变量引用 {{N1.x}}/{{global.x}}');
+    if (param.options && param.options.length > 0)
+        parts.push('枚举值见可选值列');
+    return parts.length > 0 ? parts.join('; ') : '-';
+}
+function formatDefaultValue(value) {
+    if (value === undefined || value === null)
+        return '-';
+    if (typeof value === 'string')
+        return value || '-';
+    return JSON.stringify(value);
+}
+/**
+ * 嵌套字段形状明细：OBJECT 子字段 / ARRAY 元素形状 / KEYVALUE 键值对形状。
+ * 递归展开，直到无嵌套字段。
+ */
+function renderNestedShapes(lines, params) {
+    const sections = [];
+    collectNestedSections(sections, params, '', 0);
+    if (sections.length === 0)
+        return;
+    lines.push('## 嵌套字段形状', '');
+    lines.push('复杂类型字段（OBJECT / ARRAY / KEYVALUE 等）的值形状明细。构造 `--data` 时按下列形状填写 `properties` 中的对应字段：', '');
+    lines.push(...sections);
+}
+function collectNestedSections(sections, params, prefix, depth) {
+    if (depth > 5)
+        return; // 防御极深嵌套
+    for (const param of params) {
+        const path = prefix ? `${prefix}.${param.name}` : param.name;
+        const typeUpper = param.type.toUpperCase();
+        if (param.properties && param.properties.length > 0) {
+            sections.push(`### \`${path}\` (${param.type})`, '');
+            if (param.description)
+                sections.push(param.description, '');
+            sections.push('Object，包含以下子字段：', '');
+            sections.push('| 子字段 | 显示名 | 类型 | 必填 | 说明 | 默认值 |');
+            sections.push('|--------|--------|------|------|------|--------|');
+            for (const child of param.properties) {
+                const childType = formatTypeLabel(child.type, child);
+                sections.push(`| \`${child.name}\` | ${child.display_name} | ${childType} | ${child.required ? '是' : '否'} | ${child.description || '-'} | ${formatDefaultValue(child.default)} |`);
+            }
+            sections.push('');
+            collectNestedSections(sections, param.properties, path, depth + 1);
+        }
+        if (param.item_type || param.item_fields || typeUpper === 'KEYVALUE') {
+            sections.push(`### \`${path}\` (${param.type})`, '');
+            if (param.description)
+                sections.push(param.description, '');
+            const bounds = [];
+            if (param.min_items !== undefined && param.min_items !== null) {
+                bounds.push(`至少 ${param.min_items} 项`);
+            }
+            if (param.max_items !== undefined && param.max_items !== null) {
+                bounds.push(`至多 ${param.max_items} 项`);
+            }
+            if (typeUpper === 'KEYVALUE') {
+                const keyPh = param.key_placeholder || 'key';
+                const valPh = param.value_placeholder || 'value';
+                sections.push('键值对数组，每项形状：', '');
+                sections.push('```json');
+                sections.push(`[{"key": "${keyPh}", "value": "${valPh}"}]`);
+                sections.push('```', '');
+            }
+            else if (param.item_fields && param.item_fields.length > 0) {
+                sections.push(`数组${bounds.length > 0 ? `（${bounds.join('，')}）` : ''}，元素为 object，每个元素的字段：`, '');
+                sections.push('| 元素字段 | 显示名 | 类型 | 必填 | 说明 |');
+                sections.push('|----------|--------|------|------|------|');
+                for (const f of param.item_fields) {
+                    sections.push(`| \`${f.name}\` | ${f.display_name} | ${formatTypeLabel(f.type, f)} | ${f.required ? '是' : '否'} | ${f.description || '-'} |`);
+                }
+                sections.push('');
+            }
+            else if (param.item_type) {
+                sections.push(`数组${bounds.length > 0 ? `（${bounds.join('，')}）` : ''}，元素类型为 \`${param.item_type}\`：`, '');
+                sections.push('```json');
+                if (param.item_type.toUpperCase() === 'OBJECT') {
+                    sections.push('[{}]');
+                }
+                else if (param.item_type.toUpperCase() === 'NUMBER') {
+                    sections.push('[0]');
+                }
+                else if (param.item_type.toUpperCase() === 'BOOLEAN') {
+                    sections.push('[false]');
+                }
+                else {
+                    sections.push('[""]');
+                }
+                sections.push('```', '');
+            }
+        }
+    }
+}
 //# sourceMappingURL=skillGenerator.js.map