digitalsee-ai-flow-cli 0.9.15 → 0.9.23-beta

package/dist/services/skillGenerator.js

@@ -37,9 +37,10 @@ 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");
 async function generateAllSkills(outputDir) {
     const progress = {
         totalCategories: 0,
@@ -49,17 +50,30 @@ async function generateAllSkills(outputDir) {
         totalActions: 0,
         processedActions: 0,
         skillsGenerated: 0,
+        builtinNodeTypes: 0,
         errors: [],
     };
+    // builtin-nodes.md：内置节点类型端口参考（纯本地数据，探针之前写入，
+    // 即使目标环境不支持 NodePackage 也能产出连线知识）
+    writeBuiltinNodesDoc(outputDir, progress);
     const categoryTypes = [
-        { type: 'normal', trigger: false, label: '自动化' },
-        { type: 'normal-trigger', trigger: true, label: '自动化触发器' },
-        { type: 'mcp', trigger: true, label: 'MCP' },
-        { type: 'mcp-trigger', trigger: true, label: 'MCP触发器' },
+        { 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}`);
+    }
     for (const ct of categoryTypes) {
         try {
-            const categories = await (0, knowledge_1.getNodeCategories)({ trigger: ct.trigger });
+            const categories = await (0, knowledge_1.getNodeCategories)({
+                mode: 'independent',
+                scene: ct.scene,
+                trigger: ct.trigger,
+            });
             progress.totalCategories += categories.length;
             (0, output_1.printInfo)(`发现 ${categories.length} 个${ct.label}分类`);
             const mdDir = path.join(outputDir, ct.type);
@@ -67,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);
+                await processCategory(category, categoryMdDir, progress, ct.trigger, ct.scene);
             }
         }
         catch (error) {
@@ -77,17 +91,19 @@ async function generateAllSkills(outputDir) {
     }
     return progress;
 }
-async function processCategory(category, mdDir, progress, trigger = false) {
+async function processCategory(category, mdDir, progress, trigger = false, scene = '') {
     const categoryKey = String(category.name || '');
     const categoryLabel = String(category.label || categoryKey);
     try {
         const batchSize = 50;
         let page = 1;
-        let hasMore = true;
-        while (hasMore) {
+        let processedCount = 0;
+        while (true) {
             const result = await (0, knowledge_1.searchNodesByCategory)({
-                category_name: categoryKey,
+                mode: 'independent',
+                scene,
                 trigger,
+                categoryName: categoryKey,
                 page,
                 size: batchSize,
             });
@@ -97,15 +113,23 @@ async function processCategory(category, mdDir, progress, trigger = false) {
             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)));
+                await Promise.all(batch.map((item) => processConnector(item.connector, category, mdDir, progress, trigger, scene)));
                 progress.processedNodes += batch.length;
             }
-            if (items.length < batchSize) {
-                hasMore = false;
+            processedCount += items.length;
+            // items 为空即停的保护：防止 total 异常时死循环
+            if (items.length === 0) {
+                break;
+            }
+            // 健壮的终止条件：以 total 为准（后端返回不足一页但仍有下一页时也能继续翻页）
+            const total = Number(result.total) || 0;
+            if (total > 0 && processedCount >= total) {
+                break;
             }
-            else {
-                page++;
+            if (total <= 0 && items.length < batchSize) {
+                break;
             }
+            page++;
         }
     }
     catch (error) {
@@ -113,9 +137,17 @@ async function processCategory(category, mdDir, progress, trigger = false) {
     }
     progress.processedCategories++;
 }
-async function processConnector(connector, category, mdDir, progress, trigger = false) {
+async function processConnector(connector, category, mdDir, progress, trigger = false, scene = '') {
     try {
-        const actions = await (0, node_1.getActions)({ linkId: connector.id, trigger });
+        // 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 ?? []) || [];
         progress.totalActions += actions.length;
         const actionBatchSize = 5;
         for (let i = 0; i < actions.length; i += actionBatchSize) {
@@ -145,6 +177,8 @@ 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,
@@ -164,6 +198,8 @@ 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),
                 output_fields: (action.node_schema.output_fields || []).map((o) => ({
                     key: o.key,
@@ -183,6 +219,147 @@ 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 桩：源侧用 AISubNode 的 ai_model 出桩
+    const slaveInput = descriptor.inputs.find((p) => p.name.startsWith('ai_'));
+    if (slaveInput) {
+        lines.push(`# AI 子节点接入 ${slaveInput.name} 桩（源侧为 AISubNode 出桩）：`, `ai-flow flow edge connect --flow-id <flowId> --source <AISubNode节点ID> --target <${descriptor.nodeType}的节点ID> --source-handle ai_model --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) {
@@ -192,12 +369,13 @@ function skillToMarkdown(skill) {
         const ns = skill.node_schema;
         lines.push('## Node Package 信息', '');
         lines.push(`- **Schema Key**: \`${ns.key}\``);
-        lines.push(`- **Version**: ${ns.version}`);
+        lines.push(`- **Version**: ${skill.action_ver ?? ns.version}`);
         if (ns.name)
             lines.push(`- **Name**: ${ns.name}`);
         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('| 字段名 | 显示名 | 类型 | 必填 | 说明 | 默认值 | 可选值 |');
@@ -220,17 +398,20 @@ function skillToMarkdown(skill) {
             lines.push('');
         }
     }
-    else 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} |`);
+    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('');
         }
-        lines.push('');
     }
     lines.push('## 原始数据', '', '```json', JSON.stringify(skill, null, 2), '```', '');
     return lines.join('\n');