@ai-setting/roy-agent-core 1.0.0

package/src/env/workflow/extractor/workflow-converter.ts

@@ -0,0 +1,306 @@
+/**
+ * WorkflowConverter - 将装饰器类转换为 WorkflowDefinition
+ */
+
+import 'reflect-metadata';
+import { getWorkflowMetadata } from '../decorators/workflow';
+import { getNodeMetadatas } from '../decorators/node-as';
+import { getEdgeMetadatas } from '../decorators/edge';
+import type {
+  WorkflowMetadata,
+  NodeMetadata,
+  EdgeMetadata,
+  ValidationResult,
+  ConvertedWorkflowDefinition,
+  ConvertedNodeDefinition,
+} from '../types/decorators-types';
+
+// Note: createWorkflowFromClass is exported from ./utils/create-workflow
+// and re-exported from workflow-component.ts to avoid circular dependencies
+
+/**
+ * Workflow 转换器
+ * 
+ * 负责将使用装饰器定义的类转换为标准的 WorkflowDefinition
+ */
+export class WorkflowConverter {
+
+  /**
+   * 从装饰器类提取 Workflow 元数据
+   */
+  static extractWorkflowMetadata(targetClass: Function): WorkflowMetadata | undefined {
+    return getWorkflowMetadata(targetClass);
+  }
+
+  /**
+   * 从装饰器类提取所有 Node 元数据
+   */
+  static extractNodeMetadatas(targetClass: Function): NodeMetadata[] {
+    // 获取原型上的元数据（方法装饰器存储在原型上）
+    return getNodeMetadatas(targetClass.prototype);
+  }
+
+  /**
+   * 从装饰器类提取所有 Edge 元数据
+   */
+  static extractEdgeMetadatas(targetClass: Function): EdgeMetadata[] {
+    return getEdgeMetadatas(targetClass);
+  }
+
+  /**
+   * 将装饰器类转换为 WorkflowDefinition
+   */
+  static fromClass(
+    targetClass: new (...args: any[]) => any,
+    instance: any
+  ): ConvertedWorkflowDefinition {
+    // 1. 获取 Workflow 元数据
+    const workflowMeta = this.extractWorkflowMetadata(targetClass);
+    if (!workflowMeta) {
+      throw new Error('Class must be decorated with @Workflow');
+    }
+
+    // 2. 获取所有 Node 元数据
+    const nodeMetadatas = this.extractNodeMetadatas(targetClass);
+    if (nodeMetadatas.length === 0) {
+      throw new Error('At least one method must be decorated with @NodeAs');
+    }
+
+    // 3. 获取所有 Edge 元数据
+    const edgeMetadatas = this.extractEdgeMetadatas(targetClass);
+
+    // 4. 合并 Edge 到 Node 的 dependsOn
+    const nodeMap = this.buildNodeMap(nodeMetadatas, edgeMetadatas);
+
+    // 5. 转换为 NodeDefinition[]
+    const nodes: ConvertedNodeDefinition[] = Array.from(nodeMap.values()).map(meta => ({
+      id: meta.nodeId,
+      type: meta.nodeType,
+      name: meta.name,
+      config: {
+        ...meta.config,
+        _methodName: meta.methodName, // 存储方法名用于执行
+        _instance: instance,          // 存储实例引用用于执行
+      },
+      depends_on: meta.dependsOn,
+      condition: meta.condition,
+      retry: meta.retry,
+      timeout: meta.timeout,
+    }));
+
+    // 6. 确定入口节点
+    const entry = workflowMeta.entry || nodeMetadatas[0]?.nodeId || 'unknown';
+
+    // 7. 构建 WorkflowDefinition
+    return {
+      name: workflowMeta.name,
+      version: workflowMeta.version || '1.0',
+      description: workflowMeta.description,
+      config: workflowMeta.config || {},
+      nodes,
+      entry,
+      outputs: [],
+      metadata: {
+        tags: workflowMeta.tags || [],
+        author: workflowMeta.author,
+      },
+    };
+  }
+
+  /**
+   * 构建节点映射，并合并边依赖
+   */
+  private static buildNodeMap(
+    nodeMetadatas: NodeMetadata[],
+    edgeMetadatas: EdgeMetadata[]
+  ): Map<string, NodeMetadata> {
+    const nodeMap = new Map<string, NodeMetadata>();
+
+    // 初始化节点映射
+    for (const nodeMeta of nodeMetadatas) {
+      nodeMap.set(nodeMeta.nodeId, { ...nodeMeta });
+    }
+
+    // 从 Edge 元数据添加依赖和条件
+    for (const edge of edgeMetadatas) {
+      const targetNode = nodeMap.get(edge.to);
+      if (targetNode) {
+        // 添加依赖（如果不存在）
+        if (!targetNode.dependsOn.includes(edge.from)) {
+          targetNode.dependsOn = [...targetNode.dependsOn, edge.from];
+        }
+        
+        // 合并条件边：如果 @Edge 有 condition，将其与节点的 condition 合并
+        // 条件格式：${nodeId.field} 表示从哪个节点的输出获取条件值
+        if (edge.condition) {
+          // 如果节点已有条件，合并为 AND 关系
+          if (targetNode.condition) {
+            targetNode.condition = `(${targetNode.condition}) AND (${edge.condition})`;
+          } else {
+            targetNode.condition = edge.condition;
+          }
+        }
+      }
+    }
+
+    return nodeMap;
+  }
+
+  /**
+   * 验证装饰器类的有效性
+   */
+  static validateWorkflowClass(targetClass: Function): ValidationResult {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    // 1. 检查 @Workflow 装饰器
+    const workflowMeta = this.extractWorkflowMetadata(targetClass);
+    if (!workflowMeta) {
+      errors.push('Class must be decorated with @Workflow');
+      return { valid: false, errors, warnings };
+    }
+
+    // 2. 检查至少有一个 @NodeAs 节点
+    const nodeMetadatas = this.extractNodeMetadatas(targetClass);
+    if (nodeMetadatas.length === 0) {
+      errors.push('At least one method must be decorated with @NodeAs');
+      return { valid: false, errors, warnings };
+    }
+
+    // 3. 检查入口节点存在
+    const entry = workflowMeta.entry;
+    if (entry) {
+      const entries = Array.isArray(entry) ? entry : [entry];
+      for (const e of entries) {
+        if (!nodeMetadatas.find(n => n.nodeId === e)) {
+          errors.push(`Entry node '${e}' not found`);
+        }
+      }
+    }
+
+    // 4. 检查依赖节点存在
+    for (const node of nodeMetadatas) {
+      for (const dep of node.dependsOn) {
+        if (!nodeMetadatas.find(n => n.nodeId === dep)) {
+          errors.push(`Node '${node.nodeId}' depends on non-existent node '${dep}'`);
+        }
+      }
+    }
+
+    // 5. 检查循环依赖
+    if (this.hasCycle(nodeMetadatas)) {
+      errors.push('Workflow contains a cycle');
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    };
+  }
+
+  /**
+   * 检测是否存在循环依赖
+   * 
+   * dependsOn 语义：A 依赖 B 表示 A.dependsOn = [B]
+   * 这意味着 B 执行完成后才能执行 A，所以边是 B → A
+   * 
+   * 检测方法：构建反向邻接表（谁依赖我），然后 DFS 检测环
+   */
+  private static hasCycle(nodeMetadatas: NodeMetadata[]): boolean {
+    const visited = new Set<string>();
+    const recStack = new Set<string>();
+
+    // 构建反向邻接表：nodeId -> 依赖此 node 的节点列表
+    // 即：谁在我之后执行
+    const adjList = new Map<string, string[]>();
+    for (const node of nodeMetadatas) {
+      adjList.set(node.nodeId, []);
+    }
+    for (const node of nodeMetadatas) {
+      for (const dep of node.dependsOn) {
+        const deps = adjList.get(dep);
+        if (deps) {
+          deps.push(node.nodeId);
+        }
+      }
+    }
+
+    // DFS 检测环：从任意节点出发，如果能回到已在递归栈中的节点，则存在环
+    const dfs = (nodeId: string): boolean => {
+      visited.add(nodeId);
+      recStack.add(nodeId);
+
+      const neighbors = adjList.get(nodeId) || [];
+      for (const neighbor of neighbors) {
+        if (!visited.has(neighbor)) {
+          if (dfs(neighbor)) {
+            return true;
+          }
+        } else if (recStack.has(neighbor)) {
+          // 发现环：neighbor 已在递归栈中
+          return true;
+        }
+      }
+
+      recStack.delete(nodeId);
+      return false;
+    };
+
+    // 检查所有节点
+    for (const node of nodeMetadatas) {
+      if (!visited.has(node.nodeId)) {
+        if (dfs(node.nodeId)) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * 执行装饰器方法（用于 WorkflowEngine 调用）
+   */
+  static async executeNode(
+    nodeDef: ConvertedNodeDefinition,
+    context: {
+      input: any;
+      previousOutputs: Map<string, any>;
+    }
+  ): Promise<{ output: any; error?: Error }> {
+    const instance = nodeDef.config._instance;
+    const methodName = nodeDef.config._methodName;
+
+    if (!instance || !methodName) {
+      return { output: undefined, error: new Error('Missing method information') };
+    }
+
+    const method = (instance as any)[methodName as string];
+    if (typeof method !== 'function') {
+      return { output: undefined, error: new Error(`Method ${methodName} is not a function`) };
+    }
+
+    // 准备输入参数
+    const deps = nodeDef.depends_on || [];
+    let input = context.input;
+
+    if (deps.length > 0) {
+      // 从依赖节点输出构建输入
+      input = {};
+      for (const depId of deps) {
+        input[depId] = context.previousOutputs.get(depId);
+      }
+    }
+
+    try {
+      const result = await method.call(instance, input);
+      return { output: result };
+    } catch (error) {
+      return {
+        output: undefined,
+        error: error instanceof Error ? error : new Error(String(error))
+      };
+    }
+  }
+}

package/src/env/workflow/fixtures.ts

@@ -0,0 +1,380 @@
+/**
+ * Test Fixtures - Workflow Definitions for Integration Tests
+ */
+
+import type { WorkflowDefinition } from './types';
+
+// Helper to create workflow fixtures without strict type checking
+function createWorkflow<T extends object>(def: T): T {
+  return def;
+}
+
+/**
+ * Simple single-node workflow for basic testing
+ */
+export const singleNodeWorkflow = createWorkflow({
+  name: 'single-node-test',
+  version: '1.0.0',
+  description: 'A simple single-node workflow for testing',
+  nodes: [
+    {
+      id: 'node-1',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Hello from single-node workflow'
+        }
+      }
+    }
+  ],
+  entry: 'node-1'
+});
+
+/**
+ * Sequential workflow with three steps
+ */
+export const sequentialWorkflow = createWorkflow({
+  name: 'sequential-test',
+  version: '1.0.0',
+  description: 'Three-step sequential workflow',
+  nodes: [
+    {
+      id: 'step-1',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Step 1'
+        }
+      }
+    },
+    {
+      id: 'step-2',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Step 2'
+        }
+      },
+      depends_on: ['step-1']
+    },
+    {
+      id: 'step-3',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Step 3'
+        }
+      },
+      depends_on: ['step-2']
+    }
+  ],
+  entry: 'step-1'
+});
+
+/**
+ * Parallel workflow with two branches
+ */
+export const parallelWorkflow = createWorkflow({
+  name: 'parallel-test',
+  version: '1.0.0',
+  description: 'Parallel execution workflow with two branches',
+  nodes: [
+    {
+      id: 'start',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Start'
+        }
+      }
+    },
+    {
+      id: 'branch-a',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Branch A'
+        }
+      },
+      depends_on: ['start']
+    },
+    {
+      id: 'branch-b',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Branch B'
+        }
+      },
+      depends_on: ['start']
+    },
+    {
+      id: 'merge',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Merge'
+        }
+      },
+      depends_on: ['branch-a', 'branch-b']
+    }
+  ],
+  entry: 'start'
+});
+
+/**
+ * Diamond workflow - classic DAG pattern
+ *     start
+ *    /     \
+ *  left   right
+ *    \     /
+ *     merge
+ *      |
+ *     end
+ */
+export const diamondWorkflow = createWorkflow({
+  name: 'diamond-test',
+  version: '1.0.0',
+  description: 'Diamond pattern workflow',
+  nodes: [
+    {
+      id: 'start',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Diamond Start'
+        }
+      }
+    },
+    {
+      id: 'left',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Left Branch'
+        }
+      },
+      depends_on: ['start']
+    },
+    {
+      id: 'right',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Right Branch'
+        }
+      },
+      depends_on: ['start']
+    },
+    {
+      id: 'merge',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Merge'
+        }
+      },
+      depends_on: ['left', 'right']
+    },
+    {
+      id: 'end',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Diamond End'
+        }
+      },
+      depends_on: ['merge']
+    }
+  ],
+  entry: 'start'
+});
+
+/**
+ * Workflow with conditional execution
+ */
+export const conditionalWorkflow = createWorkflow({
+  name: 'conditional-test',
+  version: '1.0.0',
+  description: 'Workflow with conditional branching',
+  nodes: [
+    {
+      id: 'input',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'input'
+        }
+      }
+    },
+    {
+      id: 'check',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Check'
+        }
+      },
+      depends_on: ['input']
+    },
+    {
+      id: 'action-a',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Action A'
+        }
+      },
+      depends_on: ['check']
+    },
+    {
+      id: 'action-b',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Action B'
+        }
+      },
+      depends_on: ['check']
+    }
+  ],
+  entry: 'input'
+});
+
+/**
+ * Complex multi-level workflow
+ */
+export const complexWorkflow = createWorkflow({
+  name: 'complex-test',
+  version: '1.0.0',
+  description: 'Complex multi-level workflow',
+  nodes: [
+    {
+      id: 'level1-a',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Level 1 A'
+        }
+      }
+    },
+    {
+      id: 'level1-b',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Level 1 B'
+        }
+      }
+    },
+    {
+      id: 'level2-a',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Level 2 A'
+        }
+      },
+      depends_on: ['level1-a']
+    },
+    {
+      id: 'level2-b',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Level 2 B'
+        }
+      },
+      depends_on: ['level1-a', 'level1-b']
+    },
+    {
+      id: 'level3',
+      type: 'tool',
+      config: {
+        tool_name: 'echo',
+        tool_args: {
+          message: 'Level 3'
+        }
+      },
+      depends_on: ['level2-a', 'level2-b']
+    }
+  ],
+  entry: ['level1-a', 'level1-b']
+});
+
+/**
+ * Workflow that should fail (tool error)
+ */
+export const failingWorkflow = createWorkflow({
+  name: 'failing-test',
+  version: '1.0.0',
+  description: 'Workflow that intentionally fails',
+  nodes: [
+    {
+      id: 'fail-node',
+      type: 'tool',
+      config: {
+        tool_name: 'nonexistent-tool',
+        tool_args: {}
+      }
+    }
+  ],
+  entry: 'fail-node'
+});
+
+/**
+ * Workflow with timeout (long running)
+ */
+export const longRunningWorkflow = createWorkflow({
+  name: 'long-running-test',
+  version: '1.0.0',
+  description: 'Workflow with long running node',
+  nodes: [
+    {
+      id: 'sleep-node',
+      type: 'tool',
+      config: {
+        tool_name: 'bash',
+        tool_args: {
+          command: 'sleep 5 && echo "done"'
+        }
+      }
+    }
+  ],
+  entry: 'sleep-node'
+});
+
+/**
+ * All test workflows collection
+ */
+export const testWorkflows = {
+  singleNode: singleNodeWorkflow,
+  sequential: sequentialWorkflow,
+  parallel: parallelWorkflow,
+  diamond: diamondWorkflow,
+  conditional: conditionalWorkflow,
+  complex: complexWorkflow,
+  failing: failingWorkflow,
+  longRunning: longRunningWorkflow
+};

package/src/env/workflow/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Workflow Module
+ * 
+ * 提供基于装饰器的 Workflow 定义和执行能力
+ * 
+ * @example
+ * ```typescript
+ * import { Workflow, NodeAs, createWorkflowFromClass } from '@ai-setting/roy-agent-core';
+ * 
+ * @Workflow({ name: 'my-workflow', entry: 'step1' })
+ * @WorkflowEdges([{ from: 'step1', to: 'step2' }])
+ * class MyWorkflow {
+ *   @NodeAs({ nodeId: 'step1', nodeType: 'tool' })
+ *   async step1() { return { result: 'done' }; }
+ * 
+ *   @NodeAs({ nodeId: 'step2', dependsOn: 'step1' })
+ *   async step2() { return { result: 'processed' }; }
+ * }
+ * 
+ * const workflow = createWorkflowFromClass(MyWorkflow);
+ * ```
+ */
+
+// Decorators
+export { Workflow } from './decorators/workflow';
+export { NodeAs } from './decorators/node-as';
+export { Edge, WorkflowEdges } from './decorators/edge';
+export { DecoratorNode } from './decorators/decorator-node';
+
+// Converter
+export { WorkflowConverter } from './extractor/workflow-converter';
+export { createWorkflowFromClass } from './utils/create-workflow';
+
+// Component
+export { WorkflowComponent } from './workflow-component';
+
+// Types - re-export from types/index
+export * from './types/index';