@gadmin2n/schematics 0.0.144 → 0.0.145

package/dist/lib/application/files/gadmin2-game-angle-demo/web/src/routes/workflow/utils/validateWorkflowDsl.ts

@@ -0,0 +1,694 @@
+import Ajv, { type ErrorObject, type ValidateFunction } from 'ajv';
+import addFormats from 'ajv-formats';
+import type {
+  CallableWorkflowOption,
+  WorkflowDSL,
+  WorkflowEdge,
+  WorkflowNode,
+  WorkflowNodeType,
+} from '../types';
+import { isParameterBindingValid } from '../types/parameter-binding';
+
+export interface WorkflowDslValidationOptions {
+  nodeTypes?: WorkflowNodeType[];
+  referencedConfigs?: Record<string, Record<string, any>>;
+  callableWorkflows?: CallableWorkflowOption[];
+  validationMode?: 'draft' | 'publish';
+}
+
+export type WorkflowDslValidationResult =
+  | { ok: true; dsl: WorkflowDSL }
+  | { ok: false; error: string };
+
+const BRANCH_NODE_TYPES = new Set([
+  'if_else',
+  'switch',
+  'approval',
+  'human_approval',
+  'external_wait',
+]);
+const FOR_EACH_BODY_TYPES = new Set([
+  'http_request',
+  'code',
+  'db_execute',
+  'sub_workflow',
+]);
+const PARALLEL_BODY_TYPES = new Set([
+  ...FOR_EACH_BODY_TYPES,
+  'delay',
+  'if_else',
+  'switch',
+  'approval',
+  'human_approval',
+  'external_wait',
+]);
+const RUNTIME_PORTS: Record<string, { input: string; output: string }> = {
+  http_request: { input: 'request-in', output: 'response-out' },
+  code: { input: 'data-in', output: 'result-out' },
+};
+const configSchemaAjv = new Ajv({ allErrors: true, strict: false });
+addFormats(configSchemaAjv);
+const configSchemaValidators = new WeakMap<object, ValidateFunction>();
+
+export function validateWorkflowDsl(
+  value: unknown,
+  options: WorkflowDslValidationOptions = {},
+): WorkflowDslValidationResult {
+  try {
+    assertWorkflowDsl(value, options);
+    return { ok: true, dsl: value as WorkflowDSL };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function assertWorkflowDsl(
+  value: unknown,
+  options: WorkflowDslValidationOptions,
+): asserts value is WorkflowDSL {
+  const isPublishValidation = options.validationMode !== 'draft';
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    fail('DSL 根节点必须是对象');
+  const dsl = value as Partial<WorkflowDSL>;
+  if (!Array.isArray(dsl.nodes)) fail('DSL.nodes 必须是数组');
+  if (!Array.isArray(dsl.edges)) fail('DSL.edges 必须是数组');
+  if (isPublishValidation && dsl.nodes.length === 0)
+    fail('Workflow 至少需要一个节点');
+  const workflowDsl = dsl as WorkflowDSL;
+
+  if (
+    isPublishValidation &&
+    options.nodeTypes &&
+    options.nodeTypes.length === 0
+  )
+    fail('节点类型尚未加载，暂时无法校验 Workflow');
+  const nodeTypeMap = options.nodeTypes
+    ? new Map(options.nodeTypes.map((nodeType) => [nodeType.type, nodeType]))
+    : null;
+  const nodeIds = new Set<string>();
+  for (const [index, node] of dsl.nodes.entries()) {
+    if (!node || typeof node !== 'object') fail(`节点 [${index}] 必须是对象`);
+    if (typeof node.id !== 'string' || !node.id)
+      fail(`节点 [${index}] 缺少有效 id`);
+    if (nodeIds.has(node.id)) fail(`节点 id 重复：${node.id}`);
+    nodeIds.add(node.id);
+    if (typeof node.type !== 'string' || !node.type)
+      fail(`节点 ${node.id} 缺少有效 type`);
+    if (isPublishValidation && nodeTypeMap && !nodeTypeMap.has(node.type))
+      fail(`节点 ${node.id} 使用了未知类型：${node.type}`);
+    if (
+      !node.position ||
+      !Number.isFinite(node.position.x) ||
+      !Number.isFinite(node.position.y)
+    )
+      fail(`节点 ${node.id} 缺少有效位置`);
+    if (!isObject(node.config)) fail(`节点 ${node.id} 的 config 必须是对象`);
+    if (!isPublishValidation) continue;
+
+    const config = effectiveConfig(node, options.referencedConfigs);
+    if (!isObject(config)) fail(`节点 ${node.id} 的有效配置必须是对象`);
+    const nodeType = nodeTypeMap?.get(node.type);
+    if (nodeType) validateConfigSchema(node.label, nodeType, config);
+    if (node.type === 'sub_workflow') {
+      if (!isPositiveId(config.workflowId))
+        fail(`调用 Workflow 节点 ${node.id} 缺少有效 workflowId`);
+      if (!isPositiveId(config.workflowVersionId))
+        fail(`调用 Workflow 节点 ${node.id} 缺少有效 workflowVersionId`);
+      if (options.callableWorkflows) {
+        const workflow = options.callableWorkflows.find(
+          (item) => item.id === config.workflowId,
+        );
+        if (!workflow)
+          fail(
+            `调用 Workflow 节点 ${node.id} 选择了不存在或不可调用的 Workflow：${config.workflowId}`,
+          );
+        const version = workflow.versions.find(
+          (item) => item.id === config.workflowVersionId,
+        );
+        if (!version)
+          fail(
+            `调用 Workflow 节点 ${node.id} 选择的版本 ${config.workflowVersionId} 不属于 Workflow ${config.workflowId}`,
+          );
+        validateCallableInputBindings(node.id, version.inputParameters, config);
+      }
+    }
+  }
+
+  const triggers = dsl.nodes.filter((node) => node.type.endsWith('_trigger'));
+  if (isPublishValidation && triggers.length !== 1)
+    fail('Workflow 必须且只能包含一个触发节点');
+
+  const edgeIds = new Set<string>();
+  for (const [index, edge] of dsl.edges.entries()) {
+    if (!edge || typeof edge !== 'object') fail(`连线 [${index}] 必须是对象`);
+    if (typeof edge.id !== 'string' || !edge.id)
+      fail(`连线 [${index}] 缺少有效 id`);
+    if (edgeIds.has(edge.id)) fail(`连线 id 重复：${edge.id}`);
+    edgeIds.add(edge.id);
+    if (!nodeIds.has(edge.source)) fail(`连线 ${edge.id} 的起点不存在`);
+    if (!nodeIds.has(edge.target)) fail(`连线 ${edge.id} 的终点不存在`);
+    if (edge.source === edge.target) fail(`连线 ${edge.id} 不能连接节点自身`);
+    if (edge.kind && !['FLOW', 'CALL', 'RETURN'].includes(edge.kind))
+      fail(`连线 ${edge.id} 使用了不支持的类型：${edge.kind}`);
+    if (!edge.kind && edge.pairId)
+      fail(`普通 FLOW 连线 ${edge.id} 不能携带 pairId`);
+    if ((edge.kind === 'CALL' || edge.kind === 'RETURN') && !edge.pairId)
+      fail(`${edge.kind} 连线 ${edge.id} 缺少 pairId`);
+    if (edge.kind !== 'RETURN' && edge.valueType !== undefined)
+      fail(`只有 RETURN 连线可以设置 valueType：${edge.id}`);
+  }
+
+  if (!isPublishValidation) return;
+
+  const nodes = new Map(dsl.nodes.map((node) => [node.id, node]));
+  const flows = dsl.edges.filter((edge) => !edge.kind || edge.kind === 'FLOW');
+  const mainFlows = flows.filter((edge) => !edge.pairId);
+  const calls = dsl.edges.filter((edge) => edge.kind === 'CALL');
+  const returns = dsl.edges.filter((edge) => edge.kind === 'RETURN');
+
+  validateFlowDag(nodeIds, flows);
+  validateMainFlow(dsl.nodes, mainFlows, triggers[0].id);
+  validateHandles(flows, nodes, options);
+  validateOwnedPipelines(workflowDsl, calls, returns, nodes, options);
+  validateReachability(workflowDsl, triggers[0].id, calls);
+}
+
+function validateConfigSchema(
+  nodeLabel: string,
+  nodeType: WorkflowNodeType,
+  config: Record<string, any>,
+) {
+  const displayName = nodeLabel.trim() || nodeType.label;
+  if (
+    nodeType.runtimeKey === 'human_approval' &&
+    (!Array.isArray(config.subjects) || config.subjects.length === 0)
+  )
+    fail(`节点“${displayName}”必须至少设置一位固定审批人或动态审批人`);
+
+  const invalidBindingPath =
+    nodeType.type === 'if_else' ? findInvalidParameterBinding(config) : null;
+  if (invalidBindingPath)
+    fail(
+      `节点“${displayName}”的“${bindingLabel(
+        invalidBindingPath,
+      )}”没有填写有效的字段路径或固定值`,
+    );
+
+  const schema = nodeType.configSchema as object;
+  let validate = configSchemaValidators.get(schema);
+  try {
+    if (!validate) {
+      validate = configSchemaAjv.compile(schema);
+      configSchemaValidators.set(schema, validate);
+    }
+  } catch (error) {
+    fail(
+      `节点类型 ${nodeType.label} 的配置 Schema 无效：${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+  if (validate(config)) return;
+  fail(
+    `节点“${displayName}”的配置不符合 ${nodeType.label} 要求：${formatSchemaErrors(validate.errors ?? [])}`,
+  );
+}
+
+function findInvalidParameterBinding(
+  value: unknown,
+  path = '参数',
+): string | null {
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index++) {
+      const invalid = findInvalidParameterBinding(
+        value[index],
+        `${path}[${index}]`,
+      );
+      if (invalid) return invalid;
+    }
+    return null;
+  }
+  if (!isObject(value)) return null;
+
+  const bindingCandidate =
+    Object.prototype.hasOwnProperty.call(value, 'source') &&
+    (Object.prototype.hasOwnProperty.call(value, 'path') ||
+      Object.prototype.hasOwnProperty.call(value, 'valueType') ||
+      Object.prototype.hasOwnProperty.call(value, 'value'));
+  if (bindingCandidate && !isParameterBindingValid(value)) return path;
+
+  for (const [key, child] of Object.entries(value)) {
+    if (['body', 'inputSchema'].includes(key)) continue;
+    const invalid = findInvalidParameterBinding(child, `${path}.${key}`);
+    if (invalid) return invalid;
+  }
+  return null;
+}
+
+function bindingLabel(path: string): string {
+  const condition = /^参数\.conditions\[(\d+)]\.(left|right)$/.exec(path);
+  if (!condition) return path;
+  const side = condition[2] === 'left' ? '要判断的数据' : '用于比较的数据';
+  return `条件 ${Number(condition[1]) + 1} · ${side}`;
+}
+
+function formatSchemaErrors(errors: ErrorObject[]): string {
+  return errors
+    .map(
+      (error) => `${error.instancePath || '/'} ${error.message ?? '配置无效'}`,
+    )
+    .join('；');
+}
+
+function validateCallableInputBindings(
+  nodeId: string,
+  inputParameters: CallableWorkflowOption['versions'][number]['inputParameters'],
+  config: Record<string, any>,
+) {
+  const bindings = isObject(config.inputBindings) ? config.inputBindings : {};
+  const declaredKeys = new Set(
+    inputParameters.map((parameter) => parameter.key),
+  );
+  const extraParameter = Object.keys(bindings).find(
+    (key) => !declaredKeys.has(key),
+  );
+  if (extraParameter)
+    fail(`调用 Workflow 节点 ${nodeId} 包含未声明的参数：${extraParameter}`);
+  const invalidParameter = inputParameters.find(
+    (parameter) =>
+      (parameter.required || bindings[parameter.key] !== undefined) &&
+      !isParameterBindingValid(bindings[parameter.key]),
+  );
+  if (invalidParameter)
+    fail(
+      `调用 Workflow 节点 ${nodeId} 的参数来源无效：${
+        invalidParameter.label ?? invalidParameter.key
+      }`,
+    );
+}
+
+function validateMainFlow(
+  nodes: WorkflowNode[],
+  mainFlows: WorkflowEdge[],
+  triggerId: string,
+) {
+  for (const node of nodes) {
+    const incoming = mainFlows.filter((edge) => edge.target === node.id);
+    const outgoing = mainFlows.filter((edge) => edge.source === node.id);
+    if (node.id === triggerId && incoming.length > 0)
+      fail('触发节点不能有主流程输入');
+    if (incoming.length > 1) fail(`节点 ${node.id} 不能有多条主流程输入`);
+    if (!BRANCH_NODE_TYPES.has(node.type) && outgoing.length > 1)
+      fail(`节点 ${node.id} 不能有多条主流程输出`);
+    const handles = new Set<string>();
+    for (const edge of outgoing) {
+      const handle = edge.sourceHandle ?? '';
+      if (handles.has(handle)) fail(`节点 ${node.id} 的同一出口只能连接一次`);
+      handles.add(handle);
+    }
+  }
+}
+
+function validateHandles(
+  flows: WorkflowEdge[],
+  nodes: Map<string, WorkflowNode>,
+  options: WorkflowDslValidationOptions,
+) {
+  const typeMap = new Map(
+    (options.nodeTypes ?? []).map((nodeType) => [nodeType.type, nodeType]),
+  );
+  for (const edge of flows) {
+    const source = nodes.get(edge.source)!;
+    const target = nodes.get(edge.target)!;
+    const targetHandle = RUNTIME_PORTS[target.type]?.input;
+    if ((edge.targetHandle ?? '') !== (targetHandle ?? ''))
+      fail(
+        targetHandle
+          ? `连线 ${edge.id} 进入 ${target.type} 时必须使用 ${targetHandle}`
+          : `连线 ${edge.id} 的目标节点没有命名输入端口`,
+      );
+
+    const sourceHandles = outputHandles(
+      source,
+      typeMap.get(source.type),
+      options,
+    );
+    if (sourceHandles === null) continue;
+    if (sourceHandles.length === 0) {
+      if (edge.sourceHandle) fail(`连线 ${edge.id} 的起点没有命名输出端口`);
+      continue;
+    }
+    if (!edge.sourceHandle)
+      fail(`连线 ${edge.id} 必须选择 ${source.type} 的输出端口`);
+    if (!sourceHandles.includes(edge.sourceHandle))
+      fail(`连线 ${edge.id} 使用了无效输出端口：${edge.sourceHandle}`);
+  }
+}
+
+function outputHandles(
+  node: WorkflowNode,
+  nodeType: WorkflowNodeType | undefined,
+  options: WorkflowDslValidationOptions,
+): string[] | null {
+  const runtimeOutput = RUNTIME_PORTS[node.type]?.output;
+  if (runtimeOutput) return [runtimeOutput];
+  if (node.type === 'switch') {
+    const config = effectiveConfig(node, options.referencedConfigs);
+    const cases = Array.isArray(config.cases) ? config.cases : [];
+    return [
+      ...cases
+        .map((item) => (isObject(item) ? item.id : undefined))
+        .filter((id): id is string => typeof id === 'string' && id.length > 0),
+      'default',
+    ];
+  }
+  if (nodeType?.outputs === null) return null;
+  return nodeType?.outputs ?? null;
+}
+
+function validateOwnedPipelines(
+  dsl: WorkflowDSL,
+  calls: WorkflowEdge[],
+  returns: WorkflowEdge[],
+  nodes: Map<string, WorkflowNode>,
+  options: WorkflowDslValidationOptions,
+) {
+  const typeMap = new Map(
+    (options.nodeTypes ?? []).map((nodeType) => [nodeType.type, nodeType]),
+  );
+  const pairedFlows = dsl.edges.filter(
+    (edge) => edge.kind === 'FLOW' && edge.pairId,
+  );
+  for (const flow of pairedFlows) {
+    if (calls.filter((call) => call.pairId === flow.pairId).length !== 1)
+      fail(`管道 FLOW 连线 ${flow.id} 必须属于唯一 CALL`);
+  }
+  for (const result of returns) {
+    if (calls.filter((call) => call.pairId === result.pairId).length !== 1)
+      fail(`RETURN 连线 ${result.id} 必须属于唯一 CALL`);
+  }
+
+  const owners = new Map<string, Set<string>>();
+  for (const call of calls) {
+    const source = nodes.get(call.source);
+    if (!source || !['for_each', 'parallel'].includes(source.type))
+      fail(`CALL 连线 ${call.id} 只能从循环或并行节点发出`);
+    const ports = ownerPipelinePorts(source, call.sourceHandle, options);
+    if (!ports) fail(`CALL 连线 ${call.id} 必须使用有效的 START 端口`);
+    const pairedReturns = returns.filter(
+      (result) => result.pairId === call.pairId,
+    );
+    const pairFlows = pairedFlows.filter((edge) => edge.pairId === call.pairId);
+    let body: Set<string>;
+    if (source.type === 'for_each') {
+      if (pairedReturns.length !== 1)
+        fail(`CALL 管道 ${call.pairId} 必须且只能有一条 RETURN`);
+      const result = pairedReturns[0];
+      validatePipelineReturn(call, result, ports.end, nodes, typeMap, options);
+      body = linearBody(call.target, result.source, pairFlows, call.pairId!);
+    } else {
+      if (pairedReturns.length === 0)
+        fail(`并行分支管道 ${call.pairId} 的每个出口都必须返回 END`);
+      for (const result of pairedReturns)
+        validatePipelineReturn(
+          call,
+          result,
+          ports.end,
+          nodes,
+          typeMap,
+          options,
+        );
+      body = branchedBody(
+        call,
+        pairFlows,
+        pairedReturns,
+        nodes,
+        typeMap,
+        options,
+      );
+    }
+    for (const nodeId of body) {
+      const allowedTypes =
+        source.type === 'parallel' ? PARALLEL_BODY_TYPES : FOR_EACH_BODY_TYPES;
+      if (!allowedTypes.has(nodes.get(nodeId)?.type ?? ''))
+        fail(`节点 ${nodeId} 不能用于 START / END 处理链`);
+      if (
+        dsl.edges.some(
+          (edge) =>
+            (!edge.kind || edge.kind === 'FLOW') &&
+            !edge.pairId &&
+            (edge.source === nodeId || edge.target === nodeId),
+        )
+      )
+        fail(`START / END 处理链节点 ${nodeId} 不能同时属于主流程`);
+      const pairIds = owners.get(nodeId) ?? new Set<string>();
+      pairIds.add(call.pairId!);
+      owners.set(nodeId, pairIds);
+    }
+  }
+
+  for (const node of dsl.nodes.filter((item) => item.type === 'for_each')) {
+    if (calls.filter((call) => call.source === node.id).length !== 1)
+      fail(`循环节点 ${node.id} 必须拥有一条完整处理链`);
+  }
+  for (const node of dsl.nodes.filter((item) => item.type === 'parallel')) {
+    const config = effectiveConfig(node, options.referencedConfigs);
+    const branches = parallelBranches(config);
+    if (branches.length < 2) fail(`并行节点 ${node.id} 至少需要两个分支`);
+    const ownedCalls = calls.filter((call) => call.source === node.id);
+    if (ownedCalls.length !== branches.length)
+      fail(`并行节点 ${node.id} 的每个分支都必须连接完整 START / END 处理链`);
+    for (const branch of branches) {
+      if (
+        ownedCalls.filter((call) => call.sourceHandle === `${branch.id}-start`)
+          .length !== 1
+      )
+        fail(`并行节点 ${node.id} 的分支“${branch.label}”缺少 START 处理链`);
+    }
+  }
+  for (const [nodeId, pairIds] of owners) {
+    if (pairIds.size > 1)
+      fail(`节点 ${nodeId} 不能属于多个 START / END 处理链`);
+  }
+}
+
+function ownerPipelinePorts(
+  node: WorkflowNode,
+  sourceHandle: string | undefined,
+  options: WorkflowDslValidationOptions,
+): { end: string } | null {
+  if (node.type === 'for_each')
+    return sourceHandle === 'start' ? { end: 'end' } : null;
+  if (node.type !== 'parallel') return null;
+  const branches = parallelBranches(
+    effectiveConfig(node, options.referencedConfigs),
+  );
+  const branch = branches.find((item) => `${item.id}-start` === sourceHandle);
+  return branch ? { end: `${branch.id}-end` } : null;
+}
+
+function parallelBranches(
+  config: Record<string, any>,
+): Array<{ id: string; label: string }> {
+  return (Array.isArray(config.branches) ? config.branches : []).filter(
+    (item): item is { id: string; label: string } =>
+      isObject(item) &&
+      typeof item.id === 'string' &&
+      item.id.length > 0 &&
+      typeof item.label === 'string' &&
+      item.label.length > 0,
+  );
+}
+
+function assertPipelineBoundaryHandles(
+  call: WorkflowEdge,
+  result: WorkflowEdge,
+  nodes: Map<string, WorkflowNode>,
+  typeMap: Map<string, WorkflowNodeType>,
+  options: WorkflowDslValidationOptions,
+) {
+  const input = RUNTIME_PORTS[nodes.get(call.target)?.type ?? '']?.input;
+  if ((call.targetHandle ?? '') !== (input ?? ''))
+    fail(
+      input
+        ? `CALL 连线 ${call.id} 必须进入 ${input}`
+        : `CALL 连线 ${call.id} 的目标节点没有命名输入端口`,
+    );
+  const source = nodes.get(result.source)!;
+  const outputs = outputHandles(source, typeMap.get(source.type), options);
+  if (outputs === null) return;
+  if (outputs.length === 0 && result.sourceHandle)
+    fail(`RETURN 连线 ${result.id} 的起点没有命名输出端口`);
+  if (outputs.length > 0 && !outputs.includes(result.sourceHandle ?? ''))
+    fail(`RETURN 连线 ${result.id} 必须从有效输出端口返回`);
+}
+
+function validatePipelineReturn(
+  call: WorkflowEdge,
+  result: WorkflowEdge,
+  endHandle: string,
+  nodes: Map<string, WorkflowNode>,
+  typeMap: Map<string, WorkflowNodeType>,
+  options: WorkflowDslValidationOptions,
+) {
+  if (result.target !== call.source || result.targetHandle !== endHandle)
+    fail(`RETURN 连线 ${result.id} 必须返回对应的 END 端口`);
+  if (result.valueType !== 'JSON')
+    fail(`RETURN 连线 ${result.id} 必须使用 JSON valueType`);
+  assertPipelineBoundaryHandles(call, result, nodes, typeMap, options);
+}
+
+function branchedBody(
+  call: WorkflowEdge,
+  flows: WorkflowEdge[],
+  returns: WorkflowEdge[],
+  nodes: Map<string, WorkflowNode>,
+  typeMap: Map<string, WorkflowNodeType>,
+  options: WorkflowDslValidationOptions,
+): Set<string> {
+  const body = new Set([call.target]);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const edge of flows) {
+      if (!body.has(edge.source) || body.has(edge.target)) continue;
+      body.add(edge.target);
+      changed = true;
+    }
+  }
+  if (
+    flows.some((edge) => !body.has(edge.source) || !body.has(edge.target)) ||
+    returns.some((edge) => !body.has(edge.source))
+  )
+    fail(`并行分支管道 ${call.pairId} 包含断开的连线`);
+
+  for (const nodeId of body) {
+    const incoming = flows.filter((edge) => edge.target === nodeId);
+    if (
+      (nodeId === call.target && incoming.length > 0) ||
+      (nodeId !== call.target && incoming.length !== 1)
+    )
+      fail(`并行分支管道 ${call.pairId} 不能合流`);
+
+    const node = nodes.get(nodeId)!;
+    const outputs = outputHandles(node, typeMap.get(node.type), options);
+    const outgoing = [
+      ...flows.filter((edge) => edge.source === nodeId),
+      ...returns.filter((edge) => edge.source === nodeId),
+    ];
+    if (outputs === null || outputs.length <= 1) {
+      if (outgoing.length !== 1)
+        fail(`并行分支节点 ${nodeId} 必须连接一个后续节点或 END`);
+      continue;
+    }
+    for (const handle of outputs) {
+      if (outgoing.filter((edge) => edge.sourceHandle === handle).length !== 1)
+        fail(`并行分支节点 ${nodeId} 的每个出口都必须连接后续节点或 END`);
+    }
+    if (outgoing.length !== outputs.length)
+      fail(`并行分支节点 ${nodeId} 使用了重复或无效出口`);
+  }
+  return body;
+}
+
+function linearBody(
+  first: string,
+  last: string,
+  flows: WorkflowEdge[],
+  pairId: string,
+): Set<string> {
+  const body = new Set([first]);
+  let current = first;
+  while (current !== last) {
+    const next = flows.filter((edge) => edge.source === current);
+    if (next.length !== 1) fail(`循环处理链 ${pairId} 必须是一条连续直线`);
+    current = next[0].target;
+    if (body.has(current)) fail(`循环处理链 ${pairId} 不能形成回路`);
+    body.add(current);
+  }
+  if (flows.some((edge) => edge.source === last))
+    fail(`循环处理链 ${pairId} 必须在 RETURN 前结束`);
+  if (flows.length !== body.size - 1)
+    fail(`循环处理链 ${pairId} 包含断开的 FLOW 连线`);
+  return body;
+}
+
+function validateReachability(
+  dsl: WorkflowDSL,
+  triggerId: string,
+  calls: WorkflowEdge[],
+) {
+  const callablePairs = new Set(calls.map((edge) => edge.pairId));
+  const reachable = new Set([triggerId]);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const edge of dsl.edges) {
+      if (
+        edge.kind === 'RETURN' ||
+        (edge.kind === 'FLOW' &&
+          edge.pairId &&
+          !callablePairs.has(edge.pairId)) ||
+        !reachable.has(edge.source) ||
+        reachable.has(edge.target)
+      )
+        continue;
+      reachable.add(edge.target);
+      changed = true;
+    }
+  }
+  const unreachable = dsl.nodes
+    .map((node) => node.id)
+    .filter((id) => !reachable.has(id));
+  if (unreachable.length > 0)
+    fail(`存在未连接到触发节点的节点：${unreachable.join(', ')}`);
+}
+
+function validateFlowDag(nodeIds: Set<string>, flows: WorkflowEdge[]) {
+  const indegree = new Map([...nodeIds].map((id) => [id, 0]));
+  const adjacency = new Map([...nodeIds].map((id) => [id, [] as string[]]));
+  for (const edge of flows) {
+    indegree.set(edge.target, indegree.get(edge.target)! + 1);
+    adjacency.get(edge.source)!.push(edge.target);
+  }
+  const queue = [...indegree.entries()]
+    .filter(([, count]) => count === 0)
+    .map(([id]) => id);
+  let visited = 0;
+  while (queue.length > 0) {
+    const id = queue.shift()!;
+    visited++;
+    for (const next of adjacency.get(id) ?? []) {
+      const count = indegree.get(next)! - 1;
+      indegree.set(next, count);
+      if (count === 0) queue.push(next);
+    }
+  }
+  if (visited !== nodeIds.size) fail('Workflow FLOW 连线不能形成回路');
+}
+
+function effectiveConfig(
+  node: WorkflowNode,
+  referencedConfigs?: Record<string, Record<string, any>>,
+): Record<string, any> {
+  return node.instanceRef
+    ? (node.configOverride ??
+        referencedConfigs?.[node.instanceRef.instanceId] ??
+        node.config)
+    : node.config;
+}
+
+function isPositiveId(value: unknown): boolean {
+  return typeof value === 'string' && /^[1-9]\d*$/.test(value);
+}
+
+function isObject(value: unknown): value is Record<string, any> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function fail(message: string): never {
+  throw new Error(message);
+}