@ai-setting/roy-agent-core 1.0.0

package/src/env/workflow/decorators/decorator-node.ts

@@ -0,0 +1,229 @@
+/**
+ * DecoratorNode - 执行装饰器类方法的节点
+ * 
+ * 实现 Node 接口，用于执行使用 @Workflow/@NodeAs 装饰的类方法
+ */
+
+import type { Node, NodeDefinition, NodeExecutionContext, NodeExecutionResult } from '../types';
+
+/**
+ * DecoratorNode 节点配置
+ */
+export interface DecoratorNodeConfig extends NodeDefinition {
+  config: {
+    /** 方法名称 */
+    _methodName: string;
+    /** 类实例 */
+    _instance: any;
+    /** 用户自定义配置 */
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * DecoratorNode - 执行装饰器类方法的节点
+ * 
+ * 用于执行使用 @Workflow/@NodeAs 装饰器定义的类方法
+ * 
+ * @example
+ * ```typescript
+ * const definition: DecoratorNodeConfig = {
+ *   id: 'myNode',
+ *   type: 'decorator',
+ *   config: {
+ *     _methodName: 'myMethod',
+ *     _instance: myWorkflowInstance,
+ *   }
+ * };
+ * 
+ * const node = new DecoratorNode(definition);
+ * const result = await node.execute(context);
+ * ```
+ */
+export class DecoratorNode implements Node {
+  readonly type = 'decorator';
+  readonly id: string;
+
+  private readonly methodName: string;
+  private readonly instance: any;
+  private readonly dependsOn: string[];
+  private readonly timeout?: number;
+  private readonly retryConfig?: {
+    max_attempts?: number;
+    backoff?: 'fixed' | 'exponential';
+    initial_delay?: number;
+  };
+
+  constructor(definition: NodeDefinition) {
+    const config = definition.config as DecoratorNodeConfig['config'];
+    
+    this.id = definition.id;
+    this.methodName = config._methodName;
+    this.instance = config._instance;
+    this.dependsOn = definition.depends_on || [];
+    this.timeout = definition.timeout;
+    this.retryConfig = definition.retry;
+  }
+
+  /**
+   * 执行装饰器方法
+   */
+  async execute(context: NodeExecutionContext): Promise<NodeExecutionResult> {
+    const startTime = Date.now();
+
+    // 获取方法
+    const method = this.instance[this.methodName];
+    if (typeof method !== 'function') {
+      return {
+        success: false,
+        error: `Method '${this.methodName}' is not a function`,
+        duration: Date.now() - startTime,
+      };
+    }
+
+    // 准备输入参数
+    const input = this.prepareInput(context);
+
+    // 执行（带重试和超时）
+    const result = await this.executeWithRetry(input, (context as any).abort);
+
+    return {
+      success: !result.error,
+      output: result.output,
+      error: result.error,
+      duration: Date.now() - startTime,
+      metadata: {
+        methodName: this.methodName,
+      },
+    };
+  }
+
+  /**
+   * 准备输入参数
+   * 
+   * 根据依赖的节点 ID，从 nodeOutputs 中提取对应的输出
+   * 返回格式: { [depNodeId]: depOutput }
+   */
+  private prepareInput(context: NodeExecutionContext): any {
+    // nodeOutputs 可以是 Map 或普通对象
+    const nodeOutputs = context.nodeOutputs;
+    
+    // 如果没有依赖节点，直接使用全局 input
+    if (this.dependsOn.length === 0) {
+      return context.input || {};
+    }
+
+    // 根据依赖节点 ID 提取输出，构建输入对象
+    const input: Record<string, unknown> = {};
+    for (const depId of this.dependsOn) {
+      // 支持 Map 和普通对象
+      const depOutput = nodeOutputs instanceof Map 
+        ? nodeOutputs.get(depId) 
+        : nodeOutputs?.[depId];
+        
+      if (depOutput && typeof depOutput === 'object') {
+        // 如果是完整的 NodeExecutionResult，提取 output 字段
+        if ('output' in depOutput) {
+          input[depId] = (depOutput as any).output;
+        } else {
+          // 已经是裸对象
+          input[depId] = depOutput;
+        }
+      }
+    }
+
+    return input;
+  }
+
+  /**
+   * 带重试的执行
+   */
+  private async executeWithRetry(
+    input: any,
+    abort?: AbortSignal
+  ): Promise<{ output?: unknown; error?: string }> {
+    const maxAttempts = this.retryConfig?.max_attempts ?? 1;
+    const backoff = this.retryConfig?.backoff ?? 'exponential';
+    const initialDelay = this.retryConfig?.initial_delay ?? 1000;
+
+    let lastError: Error | undefined;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      // 检查中断信号
+      if (abort?.aborted) {
+        return { error: 'Execution aborted' };
+      }
+
+      try {
+        // 执行方法
+        const output = await this.executeWithTimeout(input, abort);
+        return { output };
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        
+        // 如果不是最后一次尝试，等待后重试
+        if (attempt < maxAttempts) {
+          const delay = this.calculateBackoff(backoff, initialDelay, attempt - 1);
+          await this.sleep(delay, abort);
+        }
+      }
+    }
+
+    return { error: lastError?.message || 'Unknown error' };
+  }
+
+  /**
+   * 带超时的执行
+   */
+  private async executeWithTimeout(
+    input: any,
+    abort?: AbortSignal
+  ): Promise<unknown> {
+    if (!this.timeout) {
+      // 无超时限制
+      return this.instance[this.methodName](input);
+    }
+
+    // 创建超时 Promise
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => {
+        reject(new Error(`Execution timeout after ${this.timeout}ms`));
+      }, this.timeout);
+    });
+
+    // 竞速执行
+    return Promise.race([
+      this.instance[this.methodName](input),
+      timeoutPromise,
+    ]);
+  }
+
+  /**
+   * 计算退避延迟
+   */
+  private calculateBackoff(
+    backoff: 'fixed' | 'exponential',
+    initialDelay: number,
+    attempt: number
+  ): number {
+    if (backoff === 'exponential') {
+      return initialDelay * Math.pow(2, attempt);
+    }
+    return initialDelay;
+  }
+
+  /**
+   * 睡眠
+   */
+  private sleep(ms: number, abort?: AbortSignal): Promise<void> {
+    return new Promise((resolve) => {
+      const timeout = setTimeout(resolve, ms);
+      
+      // 如果被中断，清除定时器
+      abort?.addEventListener('abort', () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+    });
+  }
+}

package/src/env/workflow/decorators/decorator.test.ts

@@ -0,0 +1,196 @@
+/**
+ * @fileoverview Workflow Decorator Integration Tests
+ */
+
+import { describe, test, expect } from 'bun:test';
+import 'reflect-metadata';
+import { Workflow, NodeAs, Edge, WorkflowEdges } from './index';
+import { WorkflowConverter } from '../extractor/workflow-converter';
+import { createWorkflowFromClass } from '../utils/create-workflow';
+import { getWorkflowMetadata, getNodeMetadatas, getEdgeMetadatas } from './index';
+
+describe('Workflow Decorators', () => {
+  
+  // ============ Test Workflow Class ============
+  
+  @Workflow({
+    name: 'test-workflow',
+    version: '1.0',
+    description: 'Test workflow for decorator functionality',
+    entry: 'step1',
+    config: { parallel_limit: 3 }
+  })
+  @WorkflowEdges([
+    { from: 'step2', to: 'step3' },
+    { from: 'step3', to: 'step4' }
+  ])
+  class TestWorkflow {
+    @NodeAs({ nodeId: 'step1', nodeType: 'tool' })
+    async step1(input: { message: string }) {
+      return { result: `Step1: ${input.message}` };
+    }
+
+    @NodeAs({ nodeId: 'step2', dependsOn: 'step1' })
+    async step2(input: { step1: any }) {
+      return { result: `Step2: ${input.step1.result}` };
+    }
+
+    @NodeAs({ nodeId: 'step3', dependsOn: 'step1' })
+    async step3(input: { step1: any }) {
+      return { result: `Step3: ${input.step1.result}` };
+    }
+
+    @NodeAs({ nodeId: 'step4', dependsOn: ['step2', 'step3'] })
+    async step4(input: { step2: any; step3: any }) {
+      return { 
+        result: `Step4: ${input.step2.result} & ${input.step3.result}` 
+      };
+    }
+  }
+
+  // ============ Tests ============
+
+  test('should extract workflow metadata', () => {
+    const metadata = getWorkflowMetadata(TestWorkflow);
+    
+    expect(metadata).toBeDefined();
+    expect(metadata?.name).toBe('test-workflow');
+    expect(metadata?.version).toBe('1.0');
+    expect(metadata?.description).toBe('Test workflow for decorator functionality');
+    expect(metadata?.entry).toBe('step1');
+  });
+
+  test('should extract node metadatas', () => {
+    const nodes = getNodeMetadatas(TestWorkflow.prototype);
+    
+    expect(nodes).toHaveLength(4);
+    
+    // Check step1
+    const step1 = nodes.find(n => n.nodeId === 'step1');
+    expect(step1).toBeDefined();
+    expect(step1?.nodeType).toBe('tool');
+    expect(step1?.dependsOn).toEqual([]);
+    expect(step1?.methodName).toBe('step1');
+    
+    // Check step2 (depends on step1)
+    const step2 = nodes.find(n => n.nodeId === 'step2');
+    expect(step2).toBeDefined();
+    expect(step2?.dependsOn).toEqual(['step1']);
+    
+    // Check step4 (depends on step2 and step3)
+    const step4 = nodes.find(n => n.nodeId === 'step4');
+    expect(step4).toBeDefined();
+    expect(step4?.dependsOn).toEqual(['step2', 'step3']);
+  });
+
+  test('should extract edge metadatas', () => {
+    const edges = getEdgeMetadatas(TestWorkflow);
+    
+    expect(edges).toHaveLength(2);
+    expect(edges).toContainEqual({ from: 'step2', to: 'step3' });
+    expect(edges).toContainEqual({ from: 'step3', to: 'step4' });
+  });
+
+  test('should validate workflow class', () => {
+    const result = WorkflowConverter.validateWorkflowClass(TestWorkflow);
+    
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  test('should convert to WorkflowDefinition', () => {
+    const workflow = createWorkflowFromClass(TestWorkflow);
+    
+    expect(workflow.name).toBe('test-workflow');
+    expect(workflow.version).toBe('1.0');
+    expect(workflow.nodes).toHaveLength(4);
+    
+    // Check nodes
+    const step1Node = workflow.nodes.find(n => n.id === 'step1');
+    expect(step1Node).toBeDefined();
+    expect(step1Node?.type).toBe('tool');
+    expect(step1Node?.depends_on).toEqual([]);
+    
+    const step4Node = workflow.nodes.find(n => n.id === 'step4');
+    expect(step4Node).toBeDefined();
+    expect(step4Node?.depends_on).toContain('step2');
+    expect(step4Node?.depends_on).toContain('step3');
+  });
+
+  test('should validate missing entry node', () => {
+    @Workflow({ name: 'broken-workflow', entry: 'nonexistent' })
+    class BrokenWorkflow {
+      @NodeAs({ nodeId: 'step1' })
+      async step1() { return {}; }
+    }
+
+    const result = WorkflowConverter.validateWorkflowClass(BrokenWorkflow);
+    
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes("Entry node 'nonexistent' not found"))).toBe(true);
+  });
+
+  test('should validate missing dependency', () => {
+    @Workflow({ name: 'broken-workflow-2' })
+    class BrokenWorkflow2 {
+      @NodeAs({ nodeId: 'step1', dependsOn: 'nonexistent' })
+      async step1() { return {}; }
+    }
+
+    const result = WorkflowConverter.validateWorkflowClass(BrokenWorkflow2);
+    
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes("depends on non-existent node"))).toBe(true);
+  });
+
+  test('should validate cycle detection', () => {
+    @Workflow({ name: 'cyclic-workflow' })
+    class CyclicWorkflow {
+      @NodeAs({ nodeId: 'a', dependsOn: 'c' })
+      async a() { return {}; }
+      
+      @NodeAs({ nodeId: 'b', dependsOn: 'a' })
+      async b() { return {}; }
+      
+      @NodeAs({ nodeId: 'c', dependsOn: 'b' })
+      async c() { return {}; }
+    }
+
+    const result = WorkflowConverter.validateWorkflowClass(CyclicWorkflow);
+    
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('cycle'))).toBe(true);
+  });
+
+  test('should execute decorator node method', async () => {
+    const workflow = createWorkflowFromClass(TestWorkflow);
+    const step1Node = workflow.nodes.find(n => n.id === 'step1')!;
+    
+    const result = await WorkflowConverter.executeNode(
+      step1Node,
+      { input: { message: 'hello' }, previousOutputs: new Map() }
+    );
+    
+    expect(result.output).toEqual({ result: 'Step1: hello' });
+    expect(result.error).toBeUndefined();
+  });
+
+  test('should handle node execution with dependencies', async () => {
+    const workflow = createWorkflowFromClass(TestWorkflow);
+    const step4Node = workflow.nodes.find(n => n.id === 'step4')!;
+    
+    const previousOutputs = new Map([
+      ['step2', { result: 'Step2: data2' }],
+      ['step3', { result: 'Step3: data3' }]
+    ]);
+    
+    const result = await WorkflowConverter.executeNode(
+      step4Node,
+      { input: {}, previousOutputs }
+    );
+    
+    expect(result.output).toEqual({ 
+      result: 'Step4: Step2: data2 & Step3: data3' 
+    });
+  });
+});

package/src/env/workflow/decorators/edge.ts

@@ -0,0 +1,82 @@
+/**
+ * @Edge 和 @WorkflowEdges 装饰器
+ * 
+ * 用于显式声明节点之间的边关系
+ */
+
+import 'reflect-metadata';
+import { EDGE_METADATA_KEY } from '../metadata/keys';
+import type { EdgeMetadata, EdgeOptions } from '../types/decorators-types';
+
+/**
+ * 声明一条边 (from -> to)
+ * 
+ * 这是一个方法装饰器，用于在方法上声明边关系
+ * 
+ * @param from - 起始节点 ID
+ * @param to - 目标节点 ID
+ * 
+ * @example
+ * ```typescript
+ * @Edge('nodeA', 'nodeB')
+ * static __edge_nodeA_to_nodeB__ = null;
+ * ```
+ */
+export function Edge(from: string, to: string): MethodDecorator {
+  return function (
+    target: Object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor
+  ): PropertyDescriptor {
+    const edge: EdgeMetadata = { from, to };
+
+    // 获取已存在的边元数据列表
+    const existingEdges: EdgeMetadata[] = Reflect.getMetadata(EDGE_METADATA_KEY, target) || [];
+
+    // 添加新边
+    existingEdges.push(edge);
+
+    // 存储元数据
+    Reflect.defineMetadata(EDGE_METADATA_KEY, existingEdges, target);
+
+    return descriptor;
+  };
+}
+
+/**
+ * 类级别装饰器，声明多条边
+ * 
+ * @param edges - 边数组
+ * 
+ * @example
+ * ```typescript
+ * @WorkflowEdges([
+ *   { from: 'A', to: 'B' },
+ *   { from: 'B', to: 'C' }
+ * ])
+ * @Workflow({ name: 'test' })
+ * class TestWorkflow { }
+ * ```
+ */
+export function WorkflowEdges(edges: EdgeOptions[]): ClassDecorator {
+  return function <T extends Function>(target: T): T {
+    // 将 EdgeOptions[] 转换为 EdgeMetadata[]
+    const edgeMetadatas: EdgeMetadata[] = edges.map(edge => ({
+      from: edge.from,
+      to: edge.to,
+      condition: edge.condition,
+    }));
+
+    // 存储元数据
+    Reflect.defineMetadata(EDGE_METADATA_KEY, edgeMetadatas, target);
+
+    return target;
+  };
+}
+
+/**
+ * 获取类上的所有边元数据
+ */
+export function getEdgeMetadatas(target: Function): EdgeMetadata[] {
+  return Reflect.getMetadata(EDGE_METADATA_KEY, target) || [];
+}

package/src/env/workflow/decorators/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Workflow Decorators Index
+ * 
+ * 导出所有装饰器相关的 API
+ */
+
+// Decorators
+export { Workflow, getWorkflowMetadata } from './workflow';
+export { NodeAs, getNodeMetadatas } from './node-as';
+export { Edge, WorkflowEdges, getEdgeMetadatas } from './edge';
+
+// Node
+export { DecoratorNode } from './decorator-node';
+export type { DecoratorNodeConfig } from './decorator-node';
+
+// Converter (需要单独导入，避免循环依赖)
+export { WorkflowConverter } from '../extractor/workflow-converter';
+export { createWorkflowFromClass } from '../utils/create-workflow';
+
+// Types
+export type {
+  WorkflowOptions,
+  NodeAsOptions,
+  EdgeOptions,
+  WorkflowMetadata,
+  NodeMetadata,
+  EdgeMetadata,
+  ValidationResult,
+  ConvertedWorkflowDefinition,
+  ConvertedNodeDefinition,
+} from '../types/decorators-types';

package/src/env/workflow/decorators/node-as.ts

@@ -0,0 +1,98 @@
+/**
+ * @NodeAs 装饰器
+ * 
+ * 用于将类方法声明为 Workflow 的 Node
+ */
+
+import 'reflect-metadata';
+import { NODE_METADATA_KEY } from '../metadata/keys';
+import type { NodeAsOptions, NodeMetadata } from '../types/decorators-types';
+
+/**
+ * 将方法声明为 Workflow 的 Node
+ * 
+ * @param options - Node 配置选项
+ * 
+ * @example
+ * ```typescript
+ * @Workflow({ name: 'my-workflow', entry: 'fetch' })
+ * class MyWorkflow {
+ *   @NodeAs({
+ *     nodeId: 'fetch',
+ *     nodeType: 'tool',
+ *     config: { tool: 'web_search' }
+ *   })
+ *   async fetch(input: { query: string }) {
+ *     return { data: [] };
+ *   }
+ * 
+ *   @NodeAs({
+ *     nodeId: 'process',
+ *     dependsOn: 'fetch'
+ *   })
+ *   async process(input: { data: any }) {
+ *     return { result: {} };
+ *   }
+ * }
+ * ```
+ */
+export function NodeAs(options: NodeAsOptions = {}): MethodDecorator {
+  return function (
+    target: Object,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor
+  ): PropertyDescriptor {
+    const methodName = String(propertyKey);
+
+    // 构建节点元数据
+    const nodeMetadata: NodeMetadata = {
+      nodeId: options.nodeId || methodName, // 默认使用方法名作为 nodeId
+      nodeType: options.nodeType || 'tool', // 默认类型为 tool
+      name: options.name,
+      // 标准化 dependsOn 为数组
+      dependsOn: normalizeDependsOn(options.dependsOn),
+      condition: options.condition,
+      retry: options.retry,
+      timeout: options.timeout,
+      config: options.config || {},
+      methodName,
+      method: descriptor.value, // 存储方法引用
+    };
+
+    // 获取已存在的节点元数据列表
+    const existingNodes: NodeMetadata[] = Reflect.getMetadata(NODE_METADATA_KEY, target) || [];
+    
+    // 检查是否已存在同名节点（同一方法不能被多次装饰）
+    const existingIndex = existingNodes.findIndex(n => n.methodName === methodName);
+    
+    if (existingIndex >= 0) {
+      // 更新已存在的节点元数据
+      existingNodes[existingIndex] = nodeMetadata;
+    } else {
+      // 添加新节点元数据
+      existingNodes.push(nodeMetadata);
+    }
+
+    // 存储元数据
+    Reflect.defineMetadata(NODE_METADATA_KEY, existingNodes, target);
+
+    return descriptor;
+  };
+}
+
+/**
+ * 标准化 dependsOn 为数组
+ */
+function normalizeDependsOn(dependsOn?: string | string[] | undefined): string[] {
+  if (!dependsOn) {
+    return [];
+  }
+  return Array.isArray(dependsOn) ? dependsOn : [dependsOn];
+}
+
+/**
+ * 获取类上所有方法的 Node 元数据
+ */
+export function getNodeMetadatas(target: Object): NodeMetadata[] {
+  return Reflect.getMetadata(NODE_METADATA_KEY, target) || [];
+}

package/src/env/workflow/decorators/workflow.ts

@@ -0,0 +1,54 @@
+/**
+ * @Workflow 装饰器
+ * 
+ * 用于声明一个类为 Workflow 类
+ */
+
+import 'reflect-metadata';
+import { WORKFLOW_METADATA_KEY } from '../metadata/keys';
+import type { WorkflowOptions, WorkflowMetadata } from '../types/decorators-types';
+
+/**
+ * 声明一个类为 Workflow 类
+ * 
+ * @param options - Workflow 配置选项
+ * 
+ * @example
+ * ```typescript
+ * @Workflow({
+ *   name: 'my-workflow',
+ *   version: '1.0',
+ *   entry: 'start'
+ * })
+ * class MyWorkflow {
+ *   @NodeAs({ nodeId: 'start' })
+ *   async start() { }
+ * }
+ * ```
+ */
+export function Workflow(options: WorkflowOptions): ClassDecorator {
+  return function <T extends Function>(target: T): T {
+    // 构建元数据对象
+    const metadata: WorkflowMetadata = {
+      name: options.name,
+      version: options.version || '1.0',
+      description: options.description,
+      entry: options.entry,
+      config: options.config,
+      tags: options.tags || [],
+      author: options.author,
+    };
+
+    // 使用 Reflect.metadata 存储元数据
+    Reflect.defineMetadata(WORKFLOW_METADATA_KEY, metadata, target);
+
+    return target;
+  };
+}
+
+/**
+ * 获取类上的 Workflow 元数据
+ */
+export function getWorkflowMetadata(target: Function): WorkflowMetadata | undefined {
+  return Reflect.getMetadata(WORKFLOW_METADATA_KEY, target);
+}