@ai-setting/roy-agent-core 1.0.0

package/src/env/workflow/types/workflow.ts

@@ -0,0 +1,195 @@
+import { z } from 'zod';
+
+// ==================== Schema 定义 ====================
+
+// 节点依赖配置
+export const DependsOnSchema = z.array(z.string());
+export type DependsOn = z.infer<typeof DependsOnSchema>;
+
+// 重试配置
+export const RetryConfigSchema = z.object({
+  max_attempts: z.number().min(1).default(1),
+  backoff: z.enum(['fixed', 'exponential']).default('exponential'),
+  initial_delay: z.number().min(0).default(1000),
+});
+export type RetryConfig = z.infer<typeof RetryConfigSchema>;
+
+// 节点定义 Schema
+export const NodeDefinitionSchema = z.object({
+  id: z.string().min(1, 'Node ID is required'),
+  type: z.string().min(1, 'Node type is required'),
+  name: z.string().optional(),
+  config: z.record(z.string(), z.unknown()).optional().default({}),
+  depends_on: z.array(z.string()).optional(),
+  condition: z.string().optional(),
+  retry: RetryConfigSchema.optional(),
+  timeout: z.number().optional(),
+});
+
+export type NodeDefinition = z.infer<typeof NodeDefinitionSchema>;
+
+// ==================== Node Interface ====================
+
+/**
+ * Node interface - base interface for all workflow nodes
+ */
+export interface Node {
+  /** Node type identifier */
+  readonly type: string;
+  /** Node unique identifier */
+  readonly id: string;
+  /** Execute the node with the given context */
+  execute(context: NodeExecutionContext): Promise<NodeExecutionResult>;
+}
+
+// Import types needed for Node interface (avoid circular dependency by using inline types)
+// These will be resolved at runtime via NodeExecutionContext import
+import type { NodeExecutionContext, NodeExecutionResult } from './run';
+
+// Workflow 配置
+export const WorkflowConfigSchema = z.object({
+  parallel_limit: z.number().nullable().optional(),
+  timeout: z.number().nullable().optional(),
+  retry: RetryConfigSchema.optional(),
+  debug: z.boolean().optional(),
+});
+export type WorkflowConfig = z.infer<typeof WorkflowConfigSchema>;
+
+// 输出定义
+export const OutputDefinitionSchema = z.object({
+  name: z.string(),
+  source: z.string(),
+  path: z.string(),
+});
+export type OutputDefinition = z.infer<typeof OutputDefinitionSchema>;
+
+// Workflow 元数据
+export const WorkflowMetadataSchema = z.object({
+  author: z.string().optional(),
+  taskId: z.number().optional(),  // 新增：关联的任务 ID
+  tags: z.array(z.string()).optional().default([]),
+  created_at: z.string().optional(),
+  updated_at: z.string().optional(),
+});
+export type WorkflowMetadata = z.infer<typeof WorkflowMetadataSchema>;
+
+// ==================== Workflow 定义 ====================
+
+export const WorkflowDefinitionSchema = z.object({
+  name: z.string().min(1, 'Workflow name is required'),
+  version: z.string().default('1.0'),
+  description: z.string().optional(),
+  config: WorkflowConfigSchema.optional().default({}),
+  nodes: z.array(NodeDefinitionSchema).min(1, 'At least one node is required'),
+  entry: z.union([z.string(), z.array(z.string())]).default('__default_entry__'),
+  outputs: z.array(OutputDefinitionSchema).optional().default([]),
+  metadata: WorkflowMetadataSchema.optional().default({}),
+});
+
+export type WorkflowDefinition = z.infer<typeof WorkflowDefinitionSchema>;
+
+// 扩展 Workflow 定义，自动计算入口节点
+export interface WorkflowDefinitionExtended extends WorkflowDefinition {
+  // 自动计算的入口节点列表
+  computedEntry: string[];
+  // 节点映射
+  nodeMap: Map<string, NodeDefinition>;
+  // 拓扑排序结果
+  topologicalOrder: string[];
+}
+
+// ==================== Workflow 实体 ====================
+
+export interface Workflow {
+  id: string;
+  name: string;
+  version: string;
+  description?: string;
+  definition: WorkflowDefinition;
+  config: WorkflowConfig;
+  metadata: WorkflowMetadata;
+  tags: string[];
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+// ==================== YAML/JSON 解析辅助 ====================
+
+export interface ParsedWorkflow {
+  format: 'yaml' | 'json';
+  definition: WorkflowDefinition;
+}
+
+// YAML parser placeholder - will be implemented with yaml package
+let yamlParser: typeof import('yaml') | null = null;
+
+async function getYamlParser() {
+  if (!yamlParser) {
+    yamlParser = await import('yaml');
+  }
+  return yamlParser;
+}
+
+/**
+ * 解析 Workflow 文件
+ * @param content 文件内容
+ * @param filename 文件名，用于自动检测格式
+ */
+export async function parseWorkflowFile(content: string, filename: string): Promise<ParsedWorkflow> {
+  const isYaml = filename.endsWith('.yaml') || filename.endsWith('.yml');
+  const isJson = filename.endsWith('.json');
+  
+  let definition: WorkflowDefinition;
+  
+  if (isYaml) {
+    const yaml = await getYamlParser();
+    definition = WorkflowDefinitionSchema.parse(yaml.parse(content));
+  } else if (isJson) {
+    definition = WorkflowDefinitionSchema.parse(JSON.parse(content));
+  } else {
+    // 尝试自动检测
+    try {
+      definition = WorkflowDefinitionSchema.parse(JSON.parse(content));
+    } catch {
+      const yaml = await getYamlParser();
+      definition = WorkflowDefinitionSchema.parse(yaml.parse(content));
+    }
+  }
+  
+  return {
+    format: isYaml ? 'yaml' : 'json',
+    definition
+  };
+}
+
+/**
+ * Synchronous version of parseWorkflowFile
+ * Uses JSON parsing only for auto-detection
+ */
+export function parseWorkflowFileSync(content: string, filename: string): ParsedWorkflow {
+  const isYaml = filename.endsWith('.yaml') || filename.endsWith('.yml');
+  const isJson = filename.endsWith('.json');
+  
+  let definition: WorkflowDefinition;
+  
+  if (isJson) {
+    definition = WorkflowDefinitionSchema.parse(JSON.parse(content));
+  } else if (isYaml) {
+    // For sync YAML parsing, we need the yaml package synchronously
+    // This will throw if yaml is not imported, but that's acceptable
+    // for production use where async parsing is preferred
+    throw new Error('Synchronous YAML parsing not supported. Use parseWorkflowFile() instead.');
+  } else {
+    // 尝试自动检测 JSON
+    try {
+      definition = WorkflowDefinitionSchema.parse(JSON.parse(content));
+    } catch {
+      throw new Error('Cannot auto-detect format. Please use .yaml, .yml, or .json extension.');
+    }
+  }
+  
+  return {
+    format: isJson ? 'json' : 'yaml',
+    definition
+  };
+}

package/src/env/workflow/types_compat.ts

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Workflow types compatibility layer
+ * Re-exports all types from types/index.ts for backward compatibility
+ */
+
+// Re-export from types/index.ts
+export type {
+  // Workflow types
+  Workflow,
+  WorkflowDefinition,
+  WorkflowDefinitionExtended,
+  WorkflowConfig,
+  WorkflowMetadata,
+  RetryConfig,
+  Node,
+  NodeDefinition,
+  NodeDefinitionSchema,
+  DependsOn,
+  DependsOnSchema,
+  OutputDefinition,
+  TemplateResolver,
+  ParsedWorkflow,
+} from './types';
+
+export { 
+  WorkflowDefinitionSchema, 
+  RetryConfigSchema,
+  WorkflowConfigSchema,
+  WorkflowMetadataSchema,
+  parseWorkflowFile,
+  parseWorkflowFileSync,
+} from './types/workflow';
+
+export { OutputDefinitionSchema } from './types/workflow';
+
+// Run types
+export type {
+  RunStatus,
+  RunOptions,
+  RunResult,
+  WorkflowRun,
+  NodeRun,
+  NodeStatus,
+  NodeExecutionContext,
+  NodeExecutionResult,
+} from './types';
+
+export { createNodeExecutionContext } from './types';
+
+// Other types
+export type { AgentSessionInfo } from './types';

package/src/env/workflow/utils/create-workflow.ts

@@ -0,0 +1,47 @@
+/**
+ * 便捷函数：createWorkflowFromClass
+ */
+
+import { WorkflowConverter } from '../extractor/workflow-converter';
+import type { ConvertedWorkflowDefinition } from '../types/decorators-types';
+
+/**
+ * 从装饰器类创建 WorkflowDefinition
+ * 
+ * 这是最常用的便捷函数，自动处理实例创建和转换
+ * 
+ * @param targetClass - 使用 @Workflow 装饰的类
+ * @param options - 可选配置
+ * @returns WorkflowDefinition
+ * 
+ * @example
+ * ```typescript
+ * @Workflow({ name: 'my-workflow', entry: 'start' })
+ * class MyWorkflow {
+ *   @NodeAs({ nodeId: 'start' })
+ *   async start() { return { done: true }; }
+ * }
+ * 
+ * // 方式一：自动创建实例
+ * const workflow = createWorkflowFromClass(MyWorkflow);
+ * 
+ * // 方式二：传入自定义实例
+ * const myInstance = new MyWorkflow(customDep);
+ * const workflow = createWorkflowFromClass(MyWorkflow, { instance: myInstance });
+ * ```
+ */
+export function createWorkflowFromClass(
+  targetClass: new (...args: any[]) => any,
+  options?: {
+    /** 自定义实例，不传则自动创建 */
+    instance?: any;
+    /** 构造函数参数 */
+    constructorArgs?: any[];
+  }
+): ConvertedWorkflowDefinition {
+  // 创建或使用提供的实例
+  const instance = options?.instance ?? new targetClass(...(options?.constructorArgs ?? []));
+
+  // 转换
+  return WorkflowConverter.fromClass(targetClass, instance);
+}

package/src/env/workflow/utils/execution-state.ts

@@ -0,0 +1,245 @@
+/**
+ * Execution State Builder
+ * 
+ * Builds execution state from session messages and workflow definition.
+ */
+
+import { TracedAs } from '../../log-trace/decorator';
+import { WorkflowDefinition } from '../types';
+import { SessionMessage } from '../../session/types';
+import type { ExecutionState } from './validation-rules';
+
+/**
+ * Builder for constructing ExecutionState from session data
+ */
+export class ExecutionStateBuilder {
+  
+  @TracedAs("recovery.builder.build", { recordParams: true, recordResult: true, log: true })
+  build(messages: SessionMessage[], definition: WorkflowDefinition): ExecutionState {
+    const state: ExecutionState = {
+      completedNodes: new Set<string>(),
+      inProgressNodes: new Set<string>(),
+      pendingNodes: new Set<string>(),
+      nodeOutputs: new Map<string, unknown>(),
+      nodeInputs: new Map<string, unknown>(),
+      variables: new Map<string, unknown>(),
+      loopCounts: new Map<string, number>(),
+    };
+    
+    // Parse messages to build state
+    this.parseMessages(messages, state);
+    
+    // Build DAG from definition to determine pending nodes
+    this.buildPendingNodes(definition, state);
+    
+    return state;
+  }
+  
+  /**
+   * Parse session messages to extract node states and outputs
+   */
+  @TracedAs("recovery.builder.parseMessages", { recordParams: true, recordResult: true, log: true })
+  private parseMessages(messages: SessionMessage[], state: ExecutionState): void {
+    let lastCallNodeId: string | null = null;
+    let lastCallInput: unknown = null;
+    
+    for (const msg of messages) {
+      const metadata = msg.metadata as Record<string, unknown> | undefined;
+      const msgType = metadata?.type as string | undefined;
+      
+      switch (msgType) {
+        case 'workflow.node.call': {
+          const nodeId = metadata?.workflowNodeId as string | undefined;
+          if (nodeId) {
+            lastCallNodeId = nodeId;
+            lastCallInput = this.extractInput(msg);
+            
+            // Mark as in-progress (might be completed later)
+            state.inProgressNodes.add(nodeId);
+            state.nodeInputs.set(nodeId, lastCallInput);
+          }
+          break;
+        }
+        
+        case 'workflow.node.result': {
+          if (lastCallNodeId) {
+            // Node completed successfully
+            state.inProgressNodes.delete(lastCallNodeId);
+            state.completedNodes.add(lastCallNodeId);
+            
+            // Extract output
+            const output = this.extractOutput(msg);
+            state.nodeOutputs.set(lastCallNodeId, output);
+            
+            // Extract variables from output
+            this.extractVariables(output, state);
+            
+            lastCallNodeId = null;
+            lastCallInput = null;
+          }
+          break;
+        }
+        
+        case 'workflow.node.interrupt': {
+          if (lastCallNodeId) {
+            // Node interrupted - still in progress
+            state.inProgressNodes.add(lastCallNodeId);
+          }
+          break;
+        }
+        
+        case 'workflow.node.resume': {
+          // User resumed after interrupt
+          if (lastCallNodeId) {
+            state.inProgressNodes.add(lastCallNodeId);
+          }
+          break;
+        }
+      }
+    }
+    
+    // If there's still a lastCallNodeId in progress without result, keep it as in-progress
+    // This means the workflow was interrupted mid-execution
+  }
+  
+  /**
+   * Build pending nodes from workflow definition
+   */
+  @TracedAs("recovery.builder.buildPendingNodes", { recordParams: true, recordResult: true, log: true })
+  private buildPendingNodes(definition: WorkflowDefinition, state: ExecutionState): void {
+    const nodeIds = new Set((definition.nodes || []).map(n => n.id));
+    const allNodeIds = Array.from(nodeIds);
+    
+    // Determine entry nodes
+    const entryNodes = this.getEntryNodes(definition);
+    
+    // For each entry node, traverse the DAG and mark nodes as pending
+    // if they are reachable from an in-progress node and not completed
+    for (const entryNode of entryNodes) {
+      if (!state.completedNodes.has(entryNode)) {
+        this.markPendingFromNode(entryNode, definition, state);
+      }
+    }
+    
+    // Also check if any completed node has unexecuted children
+    for (const completedId of state.completedNodes) {
+      const children = this.getDirectChildren(completedId, definition);
+      for (const childId of children) {
+        if (!state.completedNodes.has(childId) && !state.inProgressNodes.has(childId)) {
+          state.pendingNodes.add(childId);
+        }
+      }
+    }
+  }
+  
+  /**
+   * Get entry nodes from workflow definition
+   */
+  private getEntryNodes(definition: WorkflowDefinition): string[] {
+    const entry = definition.entry;
+    if (!entry) {
+      return [];
+    }
+    
+    if (Array.isArray(entry)) {
+      return entry;
+    }
+    
+    return [entry];
+  }
+  
+  /**
+   * Mark all nodes as pending starting from a given node
+   */
+  private markPendingFromNode(
+    startNodeId: string,
+    definition: WorkflowDefinition,
+    state: ExecutionState
+  ): void {
+    const visited = new Set<string>();
+    const queue: string[] = [startNodeId];
+    
+    while (queue.length > 0) {
+      const nodeId = queue.shift()!;
+      
+      if (visited.has(nodeId)) {
+        continue;
+      }
+      visited.add(nodeId);
+      
+      // Only add to pending if not completed
+      if (!state.completedNodes.has(nodeId)) {
+        state.pendingNodes.add(nodeId);
+      }
+      
+      // Queue children
+      const children = this.getDirectChildren(nodeId, definition);
+      for (const childId of children) {
+        if (!visited.has(childId)) {
+          queue.push(childId);
+        }
+      }
+    }
+  }
+  
+  /**
+   * Get direct children of a node
+   */
+  private getDirectChildren(nodeId: string, definition: WorkflowDefinition): string[] {
+    // Note: In the actual definition, edges might use 'source' and 'target'
+    // but for now we need to check both possible formats
+    const edges = (definition as any).edges || (definition as any).connections || [];
+    
+    return edges
+      .filter((edge: any) => edge.source === nodeId || edge.from === nodeId)
+      .map((edge: any) => edge.target || edge.to);
+  }
+  
+  /**
+   * Extract input from a workflow.node.call message
+   */
+  private extractInput(msg: SessionMessage): unknown {
+    try {
+      // Try parsing as JSON
+      return JSON.parse(msg.content);
+    } catch {
+      return msg.content;
+    }
+  }
+  
+  /**
+   * Extract output from a workflow.node.result message
+   */
+  private extractOutput(msg: SessionMessage): unknown {
+    try {
+      // Try parsing as JSON
+      return JSON.parse(msg.content);
+    } catch {
+      return msg.content;
+    }
+  }
+  
+  /**
+   * Extract variables from node output and add to state
+   */
+  private extractVariables(output: unknown, state: ExecutionState): void {
+    if (!output || typeof output !== 'object') {
+      return;
+    }
+    
+    const outputObj = output as Record<string, unknown>;
+    
+    // Add each top-level property as a potential variable
+    for (const [key, value] of Object.entries(outputObj)) {
+      // Skip internal properties
+      if (key.startsWith('_') || key.startsWith('$')) {
+        continue;
+      }
+      
+      // Add to variables if not already set
+      if (!state.variables.has(key)) {
+        state.variables.set(key, value);
+      }
+    }
+  }
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Workflow Utilities
+ */
+
+export { TemplateResolver, resolveTemplates, resolveTemplateString } from './template-resolver';
+export type { TemplateResolverOptions, ResolvedValue } from './template-resolver';
+
+// Recovery utilities
+export { RecoveryValidator } from './recovery-validator';
+export { ExecutionStateBuilder } from './execution-state';
+export {
+  ValidationError,
+  ValidationResult,
+  RecoveryPlan,
+  ValidationErrorType,
+  SuggestedAction,
+  ExecutionState,
+} from './validation-rules';

package/src/env/workflow/utils/node-registry-helper.ts

@@ -0,0 +1,58 @@
+/**
+ * NodeRegistry 集成辅助
+ * 
+ * 提供函数来帮助将 decorator 节点类型注册到 NodeRegistry
+ */
+
+import type { NodeRegistry } from '../engine/node-registry';
+import { DecoratorNode } from '../decorators/decorator-node';
+import { ConditionNode } from '../nodes/condition-node';
+import { MergeNode } from '../nodes/merge-node';
+
+/**
+ * 将所有内置节点类型注册到 NodeRegistry
+ * 
+ * @param registry - NodeRegistry 实例
+ * 
+ * @example
+ * ```typescript
+ * import { registerDecoratorNodeType } from '@roy-agent/workflow-decorators';
+ * 
+ * // 在 WorkflowComponent 初始化时调用
+ * registerDecoratorNodeType(registry);
+ * ```
+ */
+export function registerDecoratorNodeType(registry: NodeRegistry): void {
+  // 注册 decorator 节点类型
+  registry.register('decorator', (definition) => {
+    return new DecoratorNode(definition);
+  });
+  
+  // 注册 condition 节点类型
+  registry.register('condition', (definition) => {
+    return new ConditionNode(definition);
+  });
+  
+  // 注册 merge 节点类型
+  registry.register('merge', (definition) => {
+    return new MergeNode(definition);
+  });
+}
+
+/**
+ * 检查 WorkflowDefinition 是否包含 decorator 类型的节点
+ */
+export function hasDecoratorNodes(
+  nodes: Array<{ type: string }>
+): boolean {
+  return nodes.some(node => node.type === 'decorator');
+}
+
+/**
+ * 从 WorkflowDefinition 中提取所有 decorator 类型的节点
+ */
+export function getDecoratorNodes(
+  nodes: Array<{ type: string; id: string }>
+): Array<{ type: string; id: string }> {
+  return nodes.filter(node => node.type === 'decorator');
+}