.NET+AI | Workflow | 核心概念速通（1）

// ❌ 硬编码的流程，难以维护和扩展
var result1 = await agent1.ProcessAsync(input);
if (result1.Success)
{
    var result2 = await agent2.ProcessAsync(result1.Data);
    // ... 越来越复杂
}

// ✅ 声明式定义，清晰可维护
var workflow = new WorkflowBuilder(startExecutor)
    .AddEdge(executor1, executor2)
    .AddEdge(executor2, executor3, condition: x => x.Success)
    .Build();

// 来自 Executor.cs
public abstract class Executor : IIdentified
{
    // 唯一标识符
    public string Id { get; }
    
    // 配置消息路由（子类必须实现）
    protected abstract RouteBuilder ConfigureRoutes(RouteBuilder routeBuilder);
    
    // 执行消息处理
    public async ValueTask<object?> ExecuteAsync(
        object message, 
        TypeId messageType, 
        IWorkflowContext context, 
        CancellationToken cancellationToken = default)
    {
        // 记录调用事件
        await context.AddEventAsync(new ExecutorInvokedEvent(this.Id, message));
        
        // 路由消息到正确的处理器
        CallResult? result = await this.Router.RouteMessageAsync(message, context, ...);
        
        // 记录完成或失败事件
        ExecutorEvent executionResult = result?.IsSuccess is not false
            ? new ExecutorCompletedEvent(this.Id, result?.Result)
            : new ExecutorFailedEvent(this.Id, result.Exception);
            
        await context.AddEventAsync(executionResult);
        return result.Result;
    }
}

// 来自 Edge.cs
public enum EdgeKind
{
    Direct,   // 直连：一对一
    FanOut,   // 扇出：一对多
    FanIn     // 扇入：多对一
}

public sealed class Edge
{
    public EdgeKind Kind { get; init; }    // 边的类型
    public EdgeData Data { get; init; }    // 边的具体数据
}

// 来自 DirectEdgeData.cs - 直连边的数据
public sealed class DirectEdgeData : EdgeData
{
    public string SourceId { get; }        // 源 Executor ID
    public string SinkId { get; }          // 目标 Executor ID
    public Func<object?, bool>? Condition; // 可选的条件判断
}

// 来自 Workflow.cs
public class Workflow
{
    // 起始 Executor 的 ID
    public string StartExecutorId { get; }
    
    // 工作流名称（可选）
    public string? Name { get; internal init; }
    
    // 工作流描述（可选）
    public string? Description { get; internal init; }
    
    // Executor 绑定字典
    internal Dictionary<string, ExecutorBinding> ExecutorBindings { get; init; }
    
    // 边的集合（按源节点分组）
    internal Dictionary<string, HashSet<Edge>> Edges { get; init; }
    
    // 输出 Executor 集合
    internal HashSet<string> OutputExecutors { get; init; }
}

// 创建工作流示例
var workflow = new WorkflowBuilder(startExecutor)  // 指定起点
    .WithName("订单处理工作流")                      // 设置名称
    .WithDescription("处理电商订单的完整流程")       // 设置描述
    .AddEdge(receiveOrder, validateOrder)           // 添加边
    .AddEdge(validateOrder, processPayment, 
             condition: x => x.IsValid)             // 条件边
    .AddEdge(processPayment, sendNotification)
    .WithOutputFrom(sendNotification)               // 指定输出节点
    .Build();                                       // 构建工作流

// SuperStep 事件定义
public class SuperStepEvent(int stepNumber, object? data = null) : WorkflowEvent(data)
{
    // 超步的序号（从 0 开始）
    public int StepNumber => stepNumber;
}

// 来自 IWorkflowContext.cs
public interface IWorkflowContext
{
    // 添加工作流事件（在当前 SuperStep 结束时触发）
    ValueTask AddEventAsync(WorkflowEvent workflowEvent, CancellationToken cancellationToken = default);
    
    // 发送消息给下游 Executor（在下一个 SuperStep 处理）
    ValueTask SendMessageAsync(object message, string? targetId, CancellationToken cancellationToken = default);
    
    // 输出工作流结果
    ValueTask YieldOutputAsync(object output, CancellationToken cancellationToken = default);
    
    // 请求在当前 SuperStep 结束时停止工作流
    ValueTask RequestHaltAsync();
    
    // 读取状态
    ValueTask<T?> ReadStateAsync<T>(string key, string? scopeName = null, CancellationToken cancellationToken = default);
    
    // 读取或初始化状态
    ValueTask<T> ReadOrInitStateAsync<T>(string key, Func<T> initialStateFactory, string? scopeName = null, CancellationToken cancellationToken = default);
    
    // 更新状态（排队更新，在 SuperStep 结束时应用）
    ValueTask QueueStateUpdateAsync<T>(string key, T value, string? scopeName = null, CancellationToken cancellationToken = default);
}

// 来自 Run.cs
public sealed class Run : IAsyncDisposable
{
    // 运行实例的唯一标识符
    public string RunId => this._runHandle.RunId;
    
    // 获取当前执行状态
    public ValueTask<RunStatus> GetStatusAsync(CancellationToken cancellationToken = default);
    
    // 获取所有产生的事件
    public IEnumerable<WorkflowEvent> OutgoingEvents => this._eventSink;
    
    // 获取自上次访问后的新事件
    public IEnumerable<WorkflowEvent> NewEvents { get; }
    
    // 恢复执行（带外部响应）
    public async ValueTask<bool> ResumeAsync(IEnumerable<ExternalResponse> responses, CancellationToken cancellationToken = default);
}

public enum RunStatus
{
    NotStarted,      // 尚未开始
    Idle,            // 空闲（已暂停，无待处理请求）
    PendingRequests, // 等待外部响应
    Ended,           // 已结束
    Running          // 正在运行
}

// 来自 CheckpointInfo.cs
public sealed class CheckpointInfo
{
    // 运行实例的唯一标识符
    public string RunId { get; }
    
    // 检查点的唯一标识符
    public string CheckpointId { get; }
}

// 检查点的完整数据（来自 Checkpoint.cs）
internal sealed class Checkpoint
{
    public int StepNumber { get; }                                    // 超步编号
    public WorkflowInfo Workflow { get; }                             // 工作流信息
    public RunnerStateData RunnerData { get; }                        // 运行器状态
    public Dictionary<ScopeKey, PortableValue> StateData { get; }     // 状态数据
    public Dictionary<EdgeId, PortableValue> EdgeStateData { get; }   // 边状态数据
    public CheckpointInfo? Parent { get; }                            // 父检查点
}