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

package/dist/services/portValidator.js

@@ -0,0 +1,304 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PORT_TYPE = void 0;
+exports.validateFlowPorts = validateFlowPorts;
+exports.validateSingleEdge = validateSingleEdge;
+exports.resolveEdgeSaveType = resolveEdgeSaveType;
+const nodeSchemaCache_1 = require("@/utils/nodeSchemaCache");
+const classicNodePorts_1 = require("@/services/classicNodePorts");
+exports.DEFAULT_PORT_TYPE = 'main';
+const normalizeNodeKeyList = (value) => Array.isArray(value)
+    ? value.filter((item) => typeof item === 'string' && Boolean(item.trim()))
+    : [];
+const normalizePort = (port) => ({
+    name: port.name,
+    displayName: port.display_name || port.name,
+    type: typeof port.type === 'string' && port.type.trim() ? port.type.trim() : exports.DEFAULT_PORT_TYPE,
+    required: Boolean(port.required),
+    maxConnections: port.max_connections !== undefined &&
+        port.max_connections !== null &&
+        Number.isFinite(port.max_connections)
+        ? Math.max(0, Math.trunc(port.max_connections))
+        : null,
+    allowedSourceNodeKeys: normalizeNodeKeyList(port.allowed_source_node_keys),
+    allowedTargetNodeKeys: normalizeNodeKeyList(port.allowed_target_node_keys),
+    deniedSourceNodeKeys: normalizeNodeKeyList(port.denied_source_node_keys),
+    deniedTargetNodeKeys: normalizeNodeKeyList(port.denied_target_node_keys),
+});
+const displayHandle = (handle) => handle || '(未指定)';
+const formatHandleList = (ports) => ports.length
+    ? ports
+        .map((p) => p.displayName && p.displayName !== p.name ? `${p.name}（${p.displayName}）` : p.name)
+        .join('、')
+    : '（无）';
+const includesKey = (keys, identity) => Boolean(identity && keys.includes(identity));
+const rejectedByAllowlist = (keys, identity) => Boolean(keys.length && !includesKey(keys, identity));
+/** 协议/type 列表交集匹配（大小写不敏感；对齐 RCS connectionCheck 多协议兼容逻辑） */
+function protocolListsOverlap(sourceType, targetType) {
+    const sourceList = sourceType.split(',').map((p) => p.trim().toLowerCase());
+    const targetList = targetType.split(',').map((p) => p.trim().toLowerCase());
+    return sourceList.some((sp) => targetList.includes(sp));
+}
+/** 端口间协议/白黑名单规则校验（不含 max_connections 与 required，二者按端口聚合检查） */
+function checkPortRules(sourcePort, targetPort, sourceIdentity, targetIdentity) {
+    // 协议/type 比较大小写不敏感，支持逗号分隔多协议列表交集（对齐 RCS connectionCheck）
+    if (sourcePort.type.toLowerCase() !== targetPort.type.toLowerCase() &&
+        !protocolListsOverlap(sourcePort.type, targetPort.type)) {
+        return 'PORT_TYPE_MISMATCH';
+    }
+    // 黑名单优先于白名单：同一个 node key 同时出现时必须拒绝
+    if (includesKey(targetPort.deniedSourceNodeKeys, sourceIdentity)) {
+        return 'SOURCE_NODE_DENIED';
+    }
+    if (includesKey(sourcePort.deniedTargetNodeKeys, targetIdentity)) {
+        return 'TARGET_NODE_DENIED';
+    }
+    if (rejectedByAllowlist(targetPort.allowedSourceNodeKeys, sourceIdentity)) {
+        return 'SOURCE_NODE_NOT_ALLOWED';
+    }
+    if (rejectedByAllowlist(sourcePort.allowedTargetNodeKeys, targetIdentity)) {
+        return 'TARGET_NODE_NOT_ALLOWED';
+    }
+    return null;
+}
+function describeRuleViolation(code, sourcePort, targetPort, sourceIdentity, targetIdentity) {
+    switch (code) {
+        case 'PORT_TYPE_MISMATCH':
+            return `端口类型不匹配：${sourcePort.type} 输出不能连接到 ${targetPort.type} 输入`;
+        case 'SOURCE_NODE_DENIED':
+            return `目标输入端口 ${targetPort.name} 禁止源节点 ${sourceIdentity}`;
+        case 'TARGET_NODE_DENIED':
+            return `源输出端口 ${sourcePort.name} 禁止目标节点 ${targetIdentity}`;
+        case 'SOURCE_NODE_NOT_ALLOWED':
+            return `源节点 ${sourceIdentity || '(未声明 node key)'} 不在目标输入端口 ${targetPort.name} 白名单中`;
+        case 'TARGET_NODE_NOT_ALLOWED':
+            return `目标节点 ${targetIdentity || '(未声明 node key)'} 不在源输出端口 ${sourcePort.name} 白名单中`;
+        default:
+            return code;
+    }
+}
+function countPortConnections(edges, nodeId, portName, side) {
+    return edges.filter((edge) => {
+        if (side === 'source') {
+            return edge.source === nodeId && (edge.sourceHandle || exports.DEFAULT_PORT_TYPE) === portName;
+        }
+        return (edge.target === nodeId &&
+            (edge.targetHandle || exports.DEFAULT_PORT_TYPE) === portName &&
+            // 自环边（source === target，如 auto_connections 声明的 retry -> main）
+            // 不占 target 端口 max_connections 名额
+            edge.source !== edge.target);
+    }).length;
+}
+async function resolveNodeSchemas(nodes) {
+    const entries = new Map();
+    const unresolved = [];
+    await Promise.all(nodes.map(async (node) => {
+        const nodeId = node.n_id || node.id;
+        const actionKey = node.action_key;
+        const actionVer = node.action_ver;
+        if (actionKey && actionVer !== undefined && actionVer !== null) {
+            // NodePackage 节点：远端 schema + switch 实例分支派生 + Loop/SelfLoop 自环兜底
+            let schema = await (0, nodeSchemaCache_1.getNodePackageSchema)(String(actionKey), Number(actionVer));
+            if (!schema) {
+                unresolved.push({ nodeId, actionKey: String(actionKey), actionVer: Number(actionVer) });
+                return;
+            }
+            schema = (0, classicNodePorts_1.applySwitchBranchesToSchema)(schema, node);
+            entries.set(nodeId, {
+                nodeId,
+                schemaKey: schema.key,
+                inputs: (schema.inputs || []).map(normalizePort),
+                outputs: (schema.outputs || []).map(normalizePort),
+                autoConnect: (0, classicNodePorts_1.getAutoConnectRulesForNodeType)(node.node_type),
+            });
+            return;
+        }
+        // classic/legacy 节点：内置端口表（未知 node_type 跳过，避免误报）
+        const classic = (0, classicNodePorts_1.resolveClassicNodeSchema)(node);
+        if (classic) {
+            entries.set(nodeId, {
+                nodeId,
+                schemaKey: classic.schemaKey,
+                inputs: classic.inputs.map(normalizePort),
+                outputs: classic.outputs.map(normalizePort),
+                autoConnect: classic.autoConnect,
+            });
+        }
+    }));
+    return { entries, unresolved };
+}
+function validateEdge(edge, sourceEntry, targetEntry, allEdges) {
+    const violations = [];
+    const base = {
+        edgeId: edge.id,
+        sourceNodeId: edge.source,
+        targetNodeId: edge.target,
+        sourceHandle: edge.sourceHandle,
+        targetHandle: edge.targetHandle,
+    };
+    if (edge.source === edge.target) {
+        // 自环边须命中节点声明的 autoConnect 配对（如 LOOP 的 loop → input）才放行
+        const allowed = sourceEntry.autoConnect.some((rule) => rule.source === edge.sourceHandle && rule.target === edge.targetHandle);
+        if (!allowed) {
+            const hint = sourceEntry.autoConnect.length
+                ? `；允许的自环端口对: ${sourceEntry.autoConnect
+                    .map((rule) => `${rule.source} → ${rule.target}`)
+                    .join('、')}`
+                : '';
+            violations.push({
+                ...base,
+                code: 'SELF_CONNECTION_NOT_ALLOWED',
+                message: `节点 ${edge.source} 不能连接到自身${hint}`,
+            });
+            return violations;
+        }
+        // 命中 autoConnect：放行并继续端口存在性 / type / max 校验
+    }
+    const sourcePort = sourceEntry.outputs.find((p) => p.name === (edge.sourceHandle || exports.DEFAULT_PORT_TYPE));
+    if (!sourcePort) {
+        violations.push({
+            ...base,
+            code: 'SOURCE_PORT_NOT_FOUND',
+            message: `源节点不存在输出端口 ${displayHandle(edge.sourceHandle)}，可用输出端口: ${formatHandleList(sourceEntry.outputs)}`,
+        });
+        return violations;
+    }
+    const targetPort = targetEntry.inputs.find((p) => p.name === (edge.targetHandle || exports.DEFAULT_PORT_TYPE));
+    if (!targetPort) {
+        violations.push({
+            ...base,
+            code: 'TARGET_PORT_NOT_FOUND',
+            message: `目标节点不存在输入端口 ${displayHandle(edge.targetHandle)}，可用输入端口: ${formatHandleList(targetEntry.inputs)}`,
+        });
+        return violations;
+    }
+    const ruleCode = checkPortRules(sourcePort, targetPort, sourceEntry.schemaKey, targetEntry.schemaKey);
+    if (ruleCode) {
+        violations.push({
+            ...base,
+            code: ruleCode,
+            message: describeRuleViolation(ruleCode, sourcePort, targetPort, sourceEntry.schemaKey, targetEntry.schemaKey),
+        });
+    }
+    // max_connections：按端口维度聚合已有边数量（校验当前 flow 全量边）
+    if (sourcePort.maxConnections !== null) {
+        const count = countPortConnections(allEdges, edge.source, sourcePort.name, 'source');
+        if (count > sourcePort.maxConnections) {
+            violations.push({
+                ...base,
+                code: 'SOURCE_MAX_CONNECTIONS_EXCEEDED',
+                message: `源输出端口 ${sourcePort.name} 连接数 ${count} 超过上限 ${sourcePort.maxConnections}`,
+            });
+        }
+    }
+    if (targetPort.maxConnections !== null) {
+        const count = countPortConnections(allEdges, edge.target, targetPort.name, 'target');
+        if (count > targetPort.maxConnections) {
+            violations.push({
+                ...base,
+                code: 'TARGET_MAX_CONNECTIONS_EXCEEDED',
+                message: `目标输入端口 ${targetPort.name} 连接数 ${count} 超过上限 ${targetPort.maxConnections}`,
+            });
+        }
+    }
+    return violations;
+}
+function validateRequiredInputs(entries, edges) {
+    const violations = [];
+    const connected = new Set(edges.map((e) => `${e.target}::${e.targetHandle || exports.DEFAULT_PORT_TYPE}`));
+    for (const entry of entries.values()) {
+        for (const port of entry.inputs) {
+            if (port.required && !connected.has(`${entry.nodeId}::${port.name}`)) {
+                violations.push({
+                    code: 'REQUIRED_INPUT_NOT_CONNECTED',
+                    message: `节点 ${entry.nodeId} 的必需输入端口 ${port.name} 没有连线`,
+                    targetNodeId: entry.nodeId,
+                    targetHandle: port.name,
+                });
+            }
+        }
+    }
+    return violations;
+}
+/** 边 handle 规范化：废弃 handle 名（chat_model/memory/tools 等）替换为新名（对齐 RCS 加载迁移） */
+function normalizeEdgeHandles(edges) {
+    return edges.map((edge) => ({
+        ...edge,
+        sourceHandle: (0, classicNodePorts_1.normalizeLegacyHandleName)(edge.sourceHandle),
+        targetHandle: (0, classicNodePorts_1.normalizeLegacyHandleName)(edge.targetHandle),
+    }));
+}
+/**
+ * 对 flow 全量 nodes + edges 做 node_schema 端口级校验。
+ *
+ * classic 节点（无 action_key/action_ver）按内置端口表（classicNodePorts）参与校验，
+ * 未知 node_type 的 legacy 节点跳过；NodePackage schema 拉取失败记入 unresolvedNodes 并跳过。
+ */
+async function validateFlowPorts(input) {
+    const { entries, unresolved } = await resolveNodeSchemas(input.nodes);
+    const edges = normalizeEdgeHandles(input.edges);
+    const violations = [];
+    for (const edge of edges) {
+        const sourceEntry = entries.get(edge.source);
+        const targetEntry = entries.get(edge.target);
+        // 只有两端都有 node_schema 时才做端口级校验（legacy 端跳过，避免误报）
+        if (sourceEntry && targetEntry) {
+            violations.push(...validateEdge(edge, sourceEntry, targetEntry, edges));
+        }
+    }
+    violations.push(...validateRequiredInputs(entries, edges));
+    return {
+        violations,
+        checkedNodeCount: entries.size,
+        unresolvedNodes: unresolved,
+    };
+}
+/**
+ * 单边预检：校验一条准备创建的边（尚未加入现有 edges）。
+ * 两端均可解析端口（NodePackage schema 或 classic 内置表）时才校验；
+ * 任一端为未知 node_type 的 legacy 节点返回空数组。
+ */
+async function validateSingleEdge(input) {
+    const { entries } = await resolveNodeSchemas(input.nodes);
+    const sourceEntry = entries.get(input.newEdge.source);
+    const targetEntry = entries.get(input.newEdge.target);
+    if (!sourceEntry || !targetEntry) {
+        return [];
+    }
+    const edge = {
+        id: '(new-edge)',
+        source: input.newEdge.source,
+        target: input.newEdge.target,
+        sourceHandle: (0, classicNodePorts_1.normalizeLegacyHandleName)(input.newEdge.sourceHandle),
+        targetHandle: (0, classicNodePorts_1.normalizeLegacyHandleName)(input.newEdge.targetHandle),
+    };
+    return validateEdge(edge, sourceEntry, targetEntry, [
+        ...normalizeEdgeHandles(input.existingEdges),
+        edge,
+    ]);
+}
+/**
+ * 解析连线的保存 type（对齐 RCS EdgeFactory ef7558b 语义）：
+ * 仅 NodePackage 节点的 handle 参与——源侧为 NP 时取其 schema 输出项的 type，
+ * 否则目标侧为 NP 时取其 schema 输入项的 type，都不是则 'main'。
+ * classic 节点的协议不写入连线 type。
+ */
+async function resolveEdgeSaveType(nodes, edge) {
+    const findNode = (id) => nodes.find((n) => (n.n_id || n.id) === id);
+    const sourceNode = findNode(edge.source);
+    if (sourceNode?.action_key && sourceNode.action_ver !== undefined) {
+        const schema = await (0, nodeSchemaCache_1.getNodePackageSchema)(String(sourceNode.action_key), Number(sourceNode.action_ver));
+        const port = schema?.outputs?.find((p) => p.name === ((0, classicNodePorts_1.normalizeLegacyHandleName)(edge.sourceHandle) || exports.DEFAULT_PORT_TYPE));
+        if (port?.type)
+            return port.type;
+    }
+    const targetNode = findNode(edge.target);
+    if (targetNode?.action_key && targetNode.action_ver !== undefined) {
+        const schema = await (0, nodeSchemaCache_1.getNodePackageSchema)(String(targetNode.action_key), Number(targetNode.action_ver));
+        const port = schema?.inputs?.find((p) => p.name === ((0, classicNodePorts_1.normalizeLegacyHandleName)(edge.targetHandle) || exports.DEFAULT_PORT_TYPE));
+        if (port?.type)
+            return port.type;
+    }
+    return exports.DEFAULT_PORT_TYPE;
+}
+//# sourceMappingURL=portValidator.js.map

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,152 @@ 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) {
@@ -192,12 +374,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 +403,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');