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

package/README.md

@@ -1412,6 +1412,8 @@ ai-flow knowledge actions <linkId> --json        # JSON 格式输出（含 outpu
 
 遍历所有分类下的所有节点和动作，为每个动作生成 Markdown 文档和 JSON 结构化数据文件，按分类类型和分类名组织存储。支持 `node_schema` 模式（包含 input/output fields 详情）。
 
+每个 Markdown 文档包含 **连接 Handle (Input / Output)** 章节，列出该节点的输入/输出连接点（Handle、显示名、类型/协议、必填、最大连接数、连接约束）及 `flow edge connect` 示例命令；Handle 名称即 `--source-handle` / `--target-handle` 的取值。`node_schema` 动作直接取自 schema 的 `inputs` / `outputs`；无 `node_schema` 的内置节点回退到默认 `input` / `output`（触发器无输入 Handle），完整的内置端口声明见同目录 `builtin-nodes.md`。
+
 ```bash
 ai-flow knowledge generate-skills ./docs
 ai-flow knowledge generate-skills ./docs --since "2026-01-01T00:00:00Z"   # 增量更新
@@ -1422,6 +1424,7 @@ ai-flow knowledge generate-skills ./docs --json
 输出：
 ```
 docs/
+├── builtin-nodes.md
 ├── normal/
 │   ├── HTTP/
 │   │   ├── HTTP_发送请求.md

package/dist/api/client.js

@@ -15,6 +15,20 @@ const https_1 = __importDefault(require("https"));
 const axios_1 = __importDefault(require("axios"));
 const config_1 = require("@/utils/config");
 const refresh_1 = require("@/api/refresh");
+/** 业务错误信封成功码：error/code 为这些值时视为成功（如 {error:"0", error_description:"SUCCESS"}） */
+const ENVELOPE_SUCCESS_CODES = new Set(['', '0', '200', 'SUCCESS']);
+function isEnvelopeBusinessError(body) {
+    if (body.result === false)
+        return true;
+    const code = String(body.error ?? body.code ?? '');
+    return code !== '' && !ENVELOPE_SUCCESS_CODES.has(code.toUpperCase());
+}
+function envelopeErrorMessage(body) {
+    const code = body.error ?? body.code;
+    return (body.error_description ||
+        body.message ||
+        (code !== undefined && code !== '' ? String(code) : JSON.stringify(body)));
+}
 let clientInstance = null;
 function classifyError(error) {
     if (error && typeof error === 'object') {
@@ -61,9 +75,11 @@ function classifyError(error) {
             }
             if (status === 400 || status === 422) {
                 const body = response.data;
-                const msg = body?.data?.message ||
-                    body?.data?.error ||
+                const msg = body?.error_description ||
+                    body?.data?.message ||
+                    response.data?.error_description ||
                     response.data?.message ||
+                    body?.error ||
                     response.data?.error ||
                     JSON.stringify(response.data);
                 return {
@@ -80,9 +96,11 @@ function classifyError(error) {
                 };
             }
             const body = response.data;
-            const msg = body?.data?.message ||
-                body?.data?.error ||
+            const msg = body?.error_description ||
+                body?.data?.message ||
+                response.data?.error_description ||
                 response.data?.message ||
+                body?.error ||
                 response.data?.error ||
                 JSON.stringify(response.data);
             return {
@@ -135,11 +153,16 @@ function buildClient() {
     });
     instance.interceptors.response.use((response) => {
         const body = response.data;
-        if (body && typeof body === 'object' && 'data' in body) {
-            response.data = body.data;
-            //钉钉网关可能会触发 code: -1, Access Denied
-            if (body.data === null && body.code === '-1') {
-                throw new Error(humanizeError(body.message ?? body));
+        if (body && typeof body === 'object' && !Array.isArray(body)) {
+            // HTTP 200 但业务失败的信封（如 {result:false, error:"1", error_description:"..."}，
+            // 或无 data 键的 {code:"202", message:"..."}）：抛错并优先透出 error_description，
+            // 避免错误被当成功放行（下游 undefined 崩溃 / "vnull" 之类的假成功）。
+            const looksLikeEnvelope = 'data' in body || 'result' in body || 'error' in body || 'code' in body;
+            if (looksLikeEnvelope && isEnvelopeBusinessError(body)) {
+                throw new Error(envelopeErrorMessage(body));
+            }
+            if ('data' in body) {
+                response.data = body.data;
             }
         }
         return response;
@@ -160,7 +183,10 @@ function buildClient() {
                 }
             }
         }
-        throw new Error(humanizeError(error));
+        const structured = classifyError(error);
+        const apiError = new Error(structured.message);
+        apiError.code = structured.code;
+        throw apiError;
     });
     return instance;
 }

package/dist/api/flowVersion.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishFlowVersion = publishFlowVersion;
+exports.getFlowVersions = getFlowVersions;
+exports.getFlowVersionDetail = getFlowVersionDetail;
+exports.rollbackFlowVersion = rollbackFlowVersion;
+exports.loadFlowVersionAsDraft = loadFlowVersionAsDraft;
+exports.getFlowVersionStatus = getFlowVersionStatus;
+exports.deleteFlowVersion = deleteFlowVersion;
+exports.offlineFlowVersion = offlineFlowVersion;
+const client_1 = require("@/api/client");
+const BASE = (flowId) => `/acm/flows/v2/${flowId}/versions`;
+/** 发布当前草稿为新的生效版本。 */
+async function publishFlowVersion(flowId, data) {
+    return (0, client_1.apiPost)(`${BASE(flowId)}/publish`, data);
+}
+/** 查询发布版本历史。 */
+async function getFlowVersions(flowId, params = { page: 1, size: 20 }) {
+    return (0, client_1.apiGet)(BASE(flowId), params);
+}
+/** 查询历史版本详情。 */
+async function getFlowVersionDetail(flowId, versionFlowId) {
+    return (0, client_1.apiGet)(`${BASE(flowId)}/${encodeURIComponent(versionFlowId)}`);
+}
+/** 将线上生效版本切换到指定历史版本（成功即隐式发布）。 */
+async function rollbackFlowVersion(flowId, versionFlowId) {
+    return (0, client_1.apiPost)(`${BASE(flowId)}/${encodeURIComponent(versionFlowId)}/rollback`, {});
+}
+/** 使用指定历史版本覆盖唯一草稿。 */
+async function loadFlowVersionAsDraft(flowId, versionFlowId) {
+    return (0, client_1.apiPost)(`${BASE(flowId)}/${encodeURIComponent(versionFlowId)}/load-draft`, {});
+}
+/** 查询草稿与线上生效版本的关系。 */
+async function getFlowVersionStatus(flowId) {
+    return (0, client_1.apiGet)(`${BASE(flowId)}/status`);
+}
+/** 删除发布版本。 */
+async function deleteFlowVersion(flowId, versionFlowId) {
+    return (0, client_1.apiDelete)(`${BASE(flowId)}/${encodeURIComponent(versionFlowId)}`);
+}
+/** 版本化下线（替代废弃的 op/v2/:id/OFFLINE 下线场景）。 */
+async function offlineFlowVersion(flowId) {
+    return (0, client_1.apiPost)(`${BASE(flowId)}/offline`);
+}
+//# sourceMappingURL=flowVersion.js.map

package/dist/api/knowledge.js

@@ -1,29 +1,70 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildConnectableRequestBody = buildConnectableRequestBody;
 exports.getNodeCategories = getNodeCategories;
 exports.searchNodesByCategory = searchNodesByCategory;
 exports.getConnectorDetail = getConnectorDetail;
 exports.getAllConnectors = getAllConnectors;
 const client_1 = require("@/api/client");
-async function getNodeCategories(params) {
-    return (0, client_1.apiPost)('/acm/node-package/categories/connectable', {
-        scene: params?.scene || 'normal',
-        trigger: params?.trigger || false,
-    });
-}
-async function searchNodesByCategory(params) {
+const connectable_1 = require("@/utils/connectable");
+const trimOptionalText = (value) => {
+    const normalized = value?.trim();
+    return normalized ? normalized : undefined;
+};
+const parsePositiveOption = (value) => {
+    if (value === undefined)
+        return undefined;
+    return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+};
+function buildConnectableRequestBody(query) {
     const body = {
-        scene: 'normal',
-        page: params.page || 1,
-        size: params.size || 50,
-        trigger: params.trigger,
+        // scene 默认空（对齐 RCS config.scene ?? ''；仅 MCP Server 画布场景传 'mcp'）
+        scene: trimOptionalText(query.scene) ?? '',
+        // 服务端要求 trigger 必填；undefined 会被 JSON 序列化丢弃导致 1010002 错误
+        trigger: query.trigger ?? false,
     };
-    if (params.keyword)
-        body.keyword = params.keyword;
-    if (params.category_name)
-        body.category_name = params.category_name;
-    const data = await (0, client_1.apiPost)('/acm/node-package/plugins/connectable', body);
-    return data || { items: [], total: 0, page: params.page || 1, size: params.size || 50 };
+    const categoryName = trimOptionalText(query.categoryName);
+    if (categoryName !== undefined)
+        body.category_name = categoryName;
+    const linkId = trimOptionalText(query.linkId);
+    if (linkId !== undefined)
+        body.link_id = linkId;
+    const keyword = trimOptionalText(query.keyword);
+    if (keyword !== undefined)
+        body.keyword = keyword;
+    const flowId = trimOptionalText(query.flowId);
+    if (flowId !== undefined)
+        body.flow_id = flowId;
+    const page = parsePositiveOption(query.page);
+    if (page !== undefined)
+        body.page = page;
+    const size = parsePositiveOption(query.size);
+    if (size !== undefined)
+        body.size = size;
+    if (query.mode === 'source') {
+        body.source_id = query.sourceId;
+        body.source_handle = query.sourceHandle;
+    }
+    else if (query.mode === 'target') {
+        body.target_id = query.targetId;
+        body.target_handle = query.targetHandle;
+    }
+    return body;
+}
+/**
+ * 节点分类只走 connectable API（POST /acm/node-package/categories/connectable），
+ * 本版本不兼容旧版接口与旧版入参（scene/trigger 裸参数形式已移除，统一 ConnectableQuery）。
+ */
+async function getNodeCategories(query) {
+    const data = await (0, client_1.apiPost)('/acm/node-package/categories/connectable', buildConnectableRequestBody(query));
+    return (0, connectable_1.normalizeConnectableCategories)(data);
+}
+async function searchNodesByCategory(query) {
+    const data = await (0, client_1.apiPost)('/acm/node-package/plugins/connectable', buildConnectableRequestBody(query));
+    if (data === null || data === undefined) {
+        return { items: [], total: 0, page: query.page || 1, size: query.size || 50 };
+    }
+    return (0, connectable_1.normalizeConnectablePluginPage)(data);
 }
 async function getConnectorDetail(connectorId) {
     return (0, client_1.apiGet)(`/acm/links/${connectorId}`);

package/dist/api/node.js

@@ -1,8 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getActionDetail = getActionDetail;
-exports.getActions = getActions;
-exports.searchActions = searchActions;
+exports.getActionNodeSchema = getActionNodeSchema;
 exports.isNodePackageSupported = isNodePackageSupported;
 exports.getNodeDetail = getNodeDetail;
 exports.createNode = createNode;
@@ -14,53 +13,92 @@ exports.cancelDebugNode = cancelDebugNode;
 const client_1 = require("@/api/client");
 const knowledge_1 = require("@/api/knowledge");
 const encoding_1 = require("@/utils/encoding");
+/**
+ * Legacy action detail lookup by numeric backend action id.
+ *
+ * Use `getActionNodeSchema(nodeKey, version)` instead for NodePackage nodes,
+ * whose persistent identity is `action_key + action_ver` — the path params
+ * there are the string action key and the numeric action version, not a
+ * backend id.
+ */
 async function getActionDetail(id, version) {
     return await (0, client_1.apiGet)(`/acm/actions/${id}${version ? '/' + version : ''}`);
 }
-async function getActions(params) {
-    const data = await (0, client_1.apiGet)('/acm/actions/v2', params);
-    if (Array.isArray(data))
-        return data;
-    if (data && Array.isArray(data.items))
-        return data.items;
-    if (data && Array.isArray(data.actions))
-        return data.actions;
-    if (data && Array.isArray(data.data))
-        return data.data;
-    return [];
+function parseMaybeJson(value) {
+    if (typeof value !== 'string') {
+        return value;
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
 }
-async function searchActions(params) {
-    const data = await (0, client_1.apiPost)('/acm/links/search', params);
-    const actions = [];
-    if (data && data.items && Array.isArray(data.items)) {
-        for (const item of data.items) {
-            if (item.matched_actions && Array.isArray(item.matched_actions)) {
-                actions.push(...item.matched_actions);
-            }
+function pickFirstDefined(...values) {
+    for (const value of values) {
+        if (value !== undefined && value !== null) {
+            return value;
         }
     }
-    return actions;
+    return undefined;
+}
+function normalizeActionNodeSchemaResponse(response, nodeKey, version) {
+    const parsedResponse = parseMaybeJson(response);
+    const rawSchema = parseMaybeJson(parsedResponse?.node_schema ?? parsedResponse?.nodeSchema ?? parsedResponse);
+    return {
+        ...rawSchema,
+        key: (pickFirstDefined(rawSchema?.key, parsedResponse?.action_key, parsedResponse?.node_key, parsedResponse?.nodeKey, nodeKey) ?? nodeKey),
+        version: (pickFirstDefined(rawSchema?.version, parsedResponse?.action_ver, parsedResponse?.node_ver, parsedResponse?.nodeVersion, version) ?? version),
+        name: (pickFirstDefined(rawSchema?.name, parsedResponse?.name, parsedResponse?.action_name, nodeKey) ?? nodeKey),
+        description: pickFirstDefined(rawSchema?.description, parsedResponse?.description),
+        inputs: Array.isArray(rawSchema?.inputs) ? rawSchema.inputs : [],
+        outputs: Array.isArray(rawSchema?.outputs) ? rawSchema.outputs : [],
+        input_fields: Array.isArray(rawSchema?.input_fields)
+            ? rawSchema.input_fields
+            : [],
+        output_fields: Array.isArray(rawSchema?.output_fields)
+            ? rawSchema.output_fields
+            : [],
+        credentials: Array.isArray(rawSchema?.credentials)
+            ? rawSchema.credentials
+            : [],
+    };
+}
+/**
+ * Fetch the authoritative NodePackage node schema.
+ *
+ * GET `/acm/actions/:nodeKey/:version` where `nodeKey` is the action_key
+ * string (e.g. `slack.sendMessage`) and `version` is the numeric action_ver.
+ * The response is normalized: the body may be a JSON string, the schema may
+ * be nested under `node_schema`/`nodeSchema`, and missing key/version/name
+ * fields fall back through the outer envelope down to the call arguments.
+ */
+async function getActionNodeSchema(nodeKey, version) {
+    const response = await (0, client_1.apiGet)(`/acm/actions/${encodeURIComponent(nodeKey)}/${version}`);
+    return normalizeActionNodeSchemaResponse(response, nodeKey, version);
 }
+/**
+ * Single-request probe for NodePackage support.
+ *
+ * Calls `getNodeCategories()` once: a successful array response (including an
+ * empty array) means the connectable API exists → true. A 404/NOT_FOUND (or a
+ * non-array payload) means unsupported → false. Any other error (network,
+ * auth, 5xx) is re-thrown so callers can distinguish transient failures from
+ * a definitive "unsupported" conclusion.
+ */
 async function isNodePackageSupported() {
+    let categories;
     try {
-        const categories = await (0, knowledge_1.getNodeCategories)();
-        const firstName = categories[0]?.name;
-        if (!firstName)
-            return false;
-        const { items } = await (0, knowledge_1.searchNodesByCategory)({
-            category_name: firstName,
-            trigger: true,
-            size: 1,
-        });
-        const linkId = items?.[0]?.connector?.id;
-        if (!linkId)
-            return false;
-        const actions = await getActions({ linkId });
-        return actions.some((action) => action.hasOwnProperty('node_schema'));
+        categories = await (0, knowledge_1.getNodeCategories)({ mode: 'independent', scene: 'normal', trigger: false });
     }
-    catch {
-        return false;
+    catch (error) {
+        if (error instanceof Error && error.code === 'NOT_FOUND') {
+            return false;
+        }
+        throw error;
     }
+    return Array.isArray(categories);
 }
 async function getNodeDetail(nodeId) {
     return (0, client_1.apiGet)(`/acm/flows/nodes/${nodeId}`);

package/dist/commands/flow/edge.js

@@ -37,6 +37,8 @@ exports.registerFlowEdge = registerFlowEdge;
 const fs = __importStar(require("fs"));
 const flow_1 = require("@/api/flow");
 const helpers_1 = require("@/commands/flow/helpers");
+const portValidator_1 = require("@/services/portValidator");
+const classicNodePorts_1 = require("@/services/classicNodePorts");
 const output_1 = require("@/utils/output");
 function registerFlowEdge(flowCmd) {
     const edgeCmd = flowCmd.command('edge').description('边（连接）操作');
@@ -49,6 +51,7 @@ function registerFlowEdge(flowCmd) {
         .option('--source-handle <handle>', '源节点输出句柄', 'output')
         .option('--target-handle <handle>', '目标节点输入句柄', 'input')
         .option('--edges-file <path>', '批量连边 JSON 文件路径')
+        .option('--force', '跳过 node_schema 端口校验，强制连接')
         .option('--json', '以 JSON 格式输出')
         .action(async (options) => {
         try {
@@ -70,12 +73,14 @@ function registerFlowEdge(flowCmd) {
             const flow = await (0, flow_1.getFlowDetail)(options.flowId);
             if ((0, helpers_1.checkFlowNotOnline)(flow, !!options.json))
                 return;
+            // 存量边读取时做废弃 handle 名迁移（对齐 RCS useDataLoading REPLACE_HANDLE_MAP，
+            // 迁移后的新名随本次保存写回后端）
             const existingEdges = (flow.edges || []).map((e) => ({
                 id: e.id,
                 source: e.source,
                 target: e.target,
-                sourceHandle: e.sourceHandle || 'output',
-                targetHandle: e.targetHandle || 'input',
+                sourceHandle: (0, classicNodePorts_1.normalizeLegacyHandleName)(e.sourceHandle) || 'output',
+                targetHandle: (0, classicNodePorts_1.normalizeLegacyHandleName)(e.targetHandle) || 'input',
                 type: e.type || 'main',
             }));
             let newEdges = [];
@@ -115,34 +120,87 @@ function registerFlowEdge(flowCmd) {
                     }
                     return;
                 }
-                newEdges = edgesData.map((e, i) => {
+                newEdges = await Promise.all(edgesData.map(async (e, i) => {
                     const edge = e;
                     if (!edge.source || !edge.target) {
                         throw new Error(`第 ${i + 1} 条边缺少 source 或 target`);
                     }
+                    const sourceHandle = String(edge.sourceHandle || 'output');
+                    const targetHandle = String(edge.targetHandle || 'input');
                     return {
                         id: `${String(edge.source)}-${String(edge.target)}-${Date.now() + i}`,
                         source: String(edge.source),
                         target: String(edge.target),
-                        sourceHandle: String(edge.sourceHandle || 'output'),
-                        targetHandle: String(edge.targetHandle || 'input'),
-                        type: String(edge.type || 'main'),
+                        sourceHandle,
+                        targetHandle,
+                        // 显式 type 优先（兼容手工构造的批量 JSON），否则按 NP schema 解析
+                        type: edge.type !== undefined && edge.type !== null && String(edge.type).trim() !== ''
+                            ? String(edge.type)
+                            : await (0, portValidator_1.resolveEdgeSaveType)(flow.nodes, {
+                                source: String(edge.source),
+                                target: String(edge.target),
+                                sourceHandle,
+                                targetHandle,
+                            }),
                     };
-                });
+                }));
             }
             else {
+                // 连线保存 type 对齐 RCS EdgeFactory：NodePackage handle 项的 type，否则 main
+                const sourceHandle = options.sourceHandle || 'output';
+                const targetHandle = options.targetHandle || 'input';
                 newEdges = [
                     {
                         id: `${options.source}-${options.target}-${Date.now()}`,
                         source: options.source,
                         target: options.target,
-                        sourceHandle: options.sourceHandle || 'output',
-                        targetHandle: options.targetHandle || 'input',
-                        type: 'main',
+                        sourceHandle,
+                        targetHandle,
+                        type: await (0, portValidator_1.resolveEdgeSaveType)(flow.nodes, {
+                            source: options.source,
+                            target: options.target,
+                            sourceHandle,
+                            targetHandle,
+                        }),
                     },
                 ];
             }
             const allEdges = [...existingEdges, ...newEdges];
+            // node_schema 端口级预检（legacy 节点自动跳过；--force 可跳过）
+            if (!options.force) {
+                const violations = [];
+                for (const edge of newEdges) {
+                    violations.push(...(await (0, portValidator_1.validateSingleEdge)({
+                        nodes: flow.nodes,
+                        existingEdges,
+                        newEdge: {
+                            source: edge.source,
+                            target: edge.target,
+                            sourceHandle: edge.sourceHandle,
+                            targetHandle: edge.targetHandle,
+                        },
+                    })));
+                }
+                if (violations.length > 0) {
+                    if (options.json) {
+                        (0, output_1.printStructuredResult)({
+                            ok: false,
+                            message: `端口校验未通过: ${violations.length} 个违规（可使用 --force 跳过）`,
+                            portViolations: violations,
+                        });
+                    }
+                    else {
+                        (0, output_1.printError)(`端口校验未通过: ${violations.length} 个违规（可使用 --force 跳过）:`);
+                        for (const v of violations) {
+                            (0, output_1.printError)(`  [${v.code}] ${v.edgeId}: ${v.message}`);
+                        }
+                    }
+                    return;
+                }
+            }
+            else {
+                (0, output_1.printWarning)('已使用 --force 跳过端口校验');
+            }
             const connections = (0, helpers_1.edgesToConnections)(allEdges);
             (0, output_1.printInfo)(`正在更新连接流（新增 ${newEdges.length} 条边）...`);
             await (0, flow_1.updateFlow)(options.flowId, {
@@ -188,14 +246,15 @@ function registerFlowEdge(flowCmd) {
             const flow = await (0, flow_1.getFlowDetail)(options.flowId);
             if ((0, helpers_1.checkFlowNotOnline)(flow, !!options.json))
                 return;
+            // 同 connect：存量边做废弃 handle 名迁移后写回
             const remainingEdges = (flow.edges || [])
                 .filter((e) => !edgeIds.includes(e.id))
                 .map((e) => ({
                 id: e.id,
                 source: e.source,
                 target: e.target,
-                sourceHandle: e.sourceHandle || 'output',
-                targetHandle: e.targetHandle || 'input',
+                sourceHandle: (0, classicNodePorts_1.normalizeLegacyHandleName)(e.sourceHandle) || 'output',
+                targetHandle: (0, classicNodePorts_1.normalizeLegacyHandleName)(e.targetHandle) || 'input',
                 type: e.type || 'main',
             }));
             const connections = (0, helpers_1.edgesToConnections)(remainingEdges);

package/dist/commands/flow/list.js

@@ -26,11 +26,12 @@ function registerFlowList(flowCmd) {
                 return;
             }
             (0, output_1.printHeader)(`连接流列表 (共 ${data.total} 条)`);
-            const headers = ['ID', '名称', '状态', '创建时间', '更新时间'];
+            const headers = ['ID', '名称', '状态', '生效版本', '创建时间', '更新时间'];
             const rows = data.items.map((item) => [
                 item.id,
                 item.name,
                 (0, helpers_1.formatOpStatus)(item.op_status),
+                item.effective_version_no != null ? String(item.effective_version_no) : '-',
                 (0, helpers_1.formatDate)(item.create_time),
                 (0, helpers_1.formatDate)(item.update_time),
             ]);