Aevatar 是一个 多 Agent 协作系统（Multi-Agent Collaboration System）：以 Actor + Event 为运行内核，让多个角色 Agent 在同一任务中分工、并行、协商与收敛。
Workflow YAML 是 Aevatar 的默认编排方式：用 YAML 定义角色、步骤、路由与策略（如 llm_call、parallel、vote_consensus、connector_call），再通过 HTTP Chat 接口（SSE / WebSocket） 触发并流式观察整个协作过程。

Aevatar = 多 Agent 协作运行时 + Workflow YAML 编排层。

• 跑多 Agent 协作任务：启动内置 API 服务，用 POST /api/chat 传入提示词和 workflow，以 SSE 流接收角色协作过程与最终结果。
• 用 Workflow YAML 做编排：在 YAML 里声明 roles + steps + routes，无需写代码即可组合顺序、分支、循环、并行、投票与人工审批。
• 接 LLM 与外部能力：配置 API Key 和 Connector（HTTP/CLI/MCP），工作流里按名称调用。
• 扩展协作能力：需要自定义步骤、工具或协作策略时，可扩展框架模块与 Connector 配置。

不熟悉 .NET 也没关系：日常使用只需配置 + 启动 API + 发 HTTP 请求；涉及「仓库结构」「模块列表」时，按需查阅即可。

任选一种方式，让框架能调用 LLM（如 DeepSeek / OpenAI）：

在仓库根目录执行：

dotnet run --project src/workflow/Aevatar.Workflow.Host.Api

服务会加载应用目录与 ~/.aevatar 中的配置与工作流。 生产/统一入口推荐直接启动 Mainnet：

dotnet run --project src/Aevatar.Mainnet.Host.Api

Mainnet 仍保留旧 /api/scopes/{scopeId}/streaming-proxy/... route 以兼容既有客户端，但该 route 已软废弃并声明 Sunset: Wed, 25 Nov 2026 00:00:00 GMT。新的直接模型 streaming / tool / continuation 接入请使用 /v1/responses；StreamingProxy 的 room/fan-out/participant 语义不等价于 /v1/responses，不要为新客户端继续接入旧 route。

• 查看可用工作流：GET http://localhost:5100/api/workflows
• 发起对话：POST http://localhost:5100/api/chat，请求体示例：

{ "prompt": "你的问题或长文本", "workflow": "simple_qa" }

请求头带上 Accept: text/event-stream，响应为 SSE 流（运行开始、步骤完成、消息片段、运行结束等）。
示例（命令行）：

curl -X POST http://localhost:5100/api/chat \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"prompt": "什么是 MAKER 模式？", "workflow": "simple_qa"}'

运行结束后，仓库根目录的 artifacts/workflow-executions/ 下会生成本次运行的 JSON 与 HTML 报告。 （可通过 WorkflowExecutionProjection 配置开关控制）

• 使用 Aevatar.Workflow.Sdk 可快速接入 /api/chat 流式调用与 resume/signal。
• 接入文档见：docs/SDK_WORKFLOW_CHAT_DOTNET.md。

Mainnet 部署必须配置 NyxID 的两类公开地址：Aevatar:NyxId:Authority 只用于公开 OIDC issuer/discovery，Aevatar:NyxId:ApiBaseUrl 用于控制面 REST、LLM gateway、浏览器和 webhook 地址。Aevatar:NyxId:InternalApiBaseUrl 只用于 /api/v1/proxy/s/* 与 /api/v1/ssh/* 执行流量；Mainnet 默认使用公网，只有同时显式设置 Aevatar:NyxId:EnableInternalApiTransport=true 和合法的 internal URL 才启用内网 transport。控制面请求（包括 /user-services、/keys 和 /api-keys/scope-plan）始终走 ApiBaseUrl。执行请求在内网目标明确尚未建立连接时会改走 ApiBaseUrl 重试一次；此外，仅 GET/HEAD/OPTIONS 在内网响应头等待超过 Aevatar:NyxId:InternalApiFallbackTimeoutSeconds（默认 5 秒）时可向公网重放一次。mutation 超时、TLS、连接重置、调用方取消、重定向、任意 HTTP 响应，以及已收到响应头后的 body 读取失败都不会触发重放。完整配置与降级语义见 NyxID LLM Provider 集成指南。

Workflow 的 code_execute 是一个明确的例外：它的 durable /executions submit、status、result 和 cancel 请求始终使用 Aevatar:NyxId:ApiBaseUrl，不读取 InternalApiBaseUrl，也不使用 internal-to-public mutation fallback。一次 workflow step 不再持有长时间 HTTP 请求，而是持久化 operation receipt 后由 actor durable callback 发起有界的状态查询。timeout_secs 默认 180 秒、允许 1 到 600 秒，并由 Aevatar 在 submit 时显式发送。Workflow stop 会持久化一个不会被重投递延长的绝对取消截止时间；截止后不再启动新的 admission-ledger/provider 操作，但仍以有界 backoff 完成冻结的 terminal audit。已经到期的 callback 使用至少 1 ms 的正延迟进入 durable scheduler，只有审计事实可靠落库后才释放 stop。当前 Chrono Sandbox 部署使用单副本 ephemeral operation store：可以解除单次 HTTP 的 125 秒限制，但进程重启会丢失 operation/result，尚不提供跨副本读取。完整状态机和上线门槛见 Sandbox Execution。

2026-08-17 UTC 的生产验收确认了这条边界：Ready 的 Aevatar 镜像 9af2a379680cad37759e0628fae9712b12283e67 通过 public NyxID route 使用异步 Chrono Sandbox；130 秒脚本在 timeout_secs=180 下以 exit_code=0 完成，provider 记录的执行时间为 131124 ms，所有 submit/status/result 交换的观测最大值不超过 1 秒，same-key submit 收敛且没有 524。独立的 HR-01 webhook canary 只有一次基线后 delivery，Aevatar committed read model 以 102/102 steps、success=true 完成，Lark Approval API 回读的真实 PENDING 实例与合成记录一致。公开证据只保留 operation/run/approval/delivery 的 12 位 SHA-256 指纹：2231f328b39d、9c6531877445、043342b4a7c0、35362f37942c。这证明了 edge-timeout 解耦和已部署 adapter 路径，不把 ephemeral backend 描述成重启或跨副本 durable；运维约束见 chrono-sandbox#11，持久化替换目标见 chrono-sandbox#12。

• 协作内核（Multi-Agent Runtime）：WorkflowGAgent 作为根 Agent，按 YAML roles 派生 RoleGAgent 子 Agent，形成可持续运行的 Agent 树。
• 编排层（Workflow YAML）：通过声明式 YAML 定义协作拓扑、步骤执行策略、分支与收敛规则。
• Mainnet Host：Aevatar.Mainnet.Host.Api 作为默认统一入口，内置 Workflow Capability。
• Workflow Api：Aevatar.Workflow.Host.Api 只做协议适配（HTTP/SSE/WebSocket）并调用 Application 层，不直接编排工作流。
• Maker Extension：作为 Workflow 插件装配到 Mainnet，不再单独提供 Maker Host/API。
• Workflow Application：解析/创建 Actor、启动投影 run、发送请求事件、等待收敛并输出查询结果。
• 协作执行：根/子 Agent 通过事件流协作推进任务；步骤模块负责具体执行（LLM、并行、投票、Connector 等）。
• 结果：事件先进入统一 Projection Pipeline，再由 API 通过 SSE / WebSocket 推给你。

• 同一 Actor 多次运行时，默认不按 run 隔离事件流，客户端可收到该 Actor 的全量事件。
• 单次请求只在“当前 runId 的终止事件”到达时结束（RUN_FINISHED / RUN_ERROR）。
• RUN_STARTED 由 StartWorkflowEvent 投影统一生成，threadId 为发布该事件的 ActorId。
• runId 与内部 sessionId 都由服务端生成；客户端请求只需 prompt/workflow/agentId。

下面这张图概括了「宿主（API + 运行时 + LLM + Connector）」与「多 Agent 协作树 + Workflow 编排步骤」的关系。

%%{init: {"maxTextSize": 100000, "flowchart": {"useMaxWidth": false, "nodeSpacing": 10, "rankSpacing": 50}, "themeVariables": {"fontSize": "10px"}}}%%
flowchart TB
    subgraph host["宿主"]
        Runtime["运行时\n事件路由 / 存储 / 流"]
        Factory["步骤工厂\n步骤类型 → 执行模块"]
        LLM["LLM"]
        Connectors["Connector\nHTTP·CLI·MCP"]
    end

    subgraph agents["Agent 树"]
        Workflow["工作流 Agent"]
        RoleA["角色 A"]
        RoleB["角色 B"]
    end

    subgraph steps["工作流步骤"]
        M1["workflow_loop"]
        M2["llm_call"]
        M3["connector_call"]
        M4["parallel / vote"]
    end

    host --> agents
    Factory --> steps
    steps --> Workflow
    Workflow --> RoleA
    Workflow --> RoleB
    LLM --> M2
    Connectors --> M3

• 宿主：提供运行时、步骤执行能力、LLM、Connector。当前以 Mainnet/Workflow 两个 Host 为主；Maker 以插件方式装配到 Mainnet。
• Agent 树：工作流 Agent 为根，按 YAML 中的角色创建子 Agent；事件在父子之间按「方向」路由（当前节点 / 父 / 子）。
• 步骤模块：每一步对应一种类型（如 llm_call、connector_call），由框架内置或你扩展的模块执行。

下面这张图从 POST /api/chat 开始，展示通用工作流执行路径：Cognitive 加载 YAML、创建 roles、步骤执行、role 通过 connector 调外部服务、最后 SSE 返回结果。

%%{init: {"maxTextSize": 100000, "flowchart": {"useMaxWidth": false, "nodeSpacing": 10, "rankSpacing": 50}, "themeVariables": {"fontSize": "10px"}}}%%
sequenceDiagram
    participant User
    participant API as ChatAPI
    participant App as WorkflowApp
    participant Registry as WorkflowRegistry
    participant Runtime as IActorRuntime
    participant Projection as ProjectionService
    participant Workflow as WorkflowGAgent
    participant Engine as workflow_loop
    participant LlmStep as llm_call
    participant ConnStep as connector_call
    participant Role as RoleGAgent
    participant LLM
    participant External

    User->>API: POST /api/chat
    API->>App: ExecuteAsync(request)
    App->>Registry: resolve workflow yaml
    App->>Runtime: create or reuse workflow agent
    App->>Projection: StartAsync(actorId, workflowName, input)
    App->>Workflow: set yaml and activate
    Workflow->>Runtime: create role agents from workflow roles
    App->>Workflow: ChatRequestEvent
    Workflow->>Engine: StartWorkflowEvent

    rect rgb(240, 248, 255)
        Engine->>Engine: dispatch StepRequestEvent
        alt llm_call
            Engine->>LlmStep: step request
            LlmStep->>Role: send ChatRequestEvent to role
            Role->>LLM: call model
            LLM-->>Role: text tokens and final output
            Role-->>Engine: StepCompletedEvent
        else connector_call
            Engine->>ConnStep: step request
            Note over ConnStep: check role connector allowlist
            ConnStep->>External: invoke connector
            External-->>ConnStep: output or error
            ConnStep-->>Engine: StepCompletedEvent
        else other steps
            Engine-->>Engine: conditional parallel vote while
        end
        Note right of Engine: repeat for each step
    end

    Engine-->>Workflow: WorkflowCompletedEvent
    Workflow-->>App: completion events
    App->>Projection: wait + complete
    App-->>API: output frames + run report
    API-->>User: SSE stream to client

下面这张图是 maker sample 的同类流程：在通用 pipeline 上叠加 maker_recursive / maker_vote，并可在末尾通过 connector 做外部后处理。

%%{init: {"maxTextSize": 100000, "flowchart": {"useMaxWidth": false, "nodeSpacing": 10, "rankSpacing": 50}, "themeVariables": {"fontSize": "10px"}}}%%
sequenceDiagram
    participant User
    participant API as ChatAPI
    participant App as WorkflowApp
    participant Runtime as IActorRuntime
    participant Workflow as WorkflowGAgent
    participant Engine as workflow_loop
    participant Recursive as maker_recursive
    participant Parallel as parallel_fanout
    participant Vote as maker_vote
    participant Workers as WorkerRoleGAgents
    participant LLM
    participant Post as connector_call
    participant External

    User->>API: POST /api/chat maker_analysis
    API->>App: ExecuteAsync(request)
    App->>Runtime: create workflow agent
    App->>Workflow: set maker yaml and activate
    Workflow->>Runtime: create coordinator and worker roles
    App->>Workflow: ChatRequestEvent
    Workflow->>Engine: StartWorkflowEvent

    rect rgb(255, 248, 240)
        Engine->>Recursive: enter recursive stage
        Recursive->>Parallel: fan out subtasks
        Parallel->>Workers: llm_call for workers
        Workers->>LLM: generate candidates
        LLM-->>Workers: candidate outputs
        Workers-->>Parallel: StepCompletedEvent
        Parallel-->>Vote: aggregate candidates
        Vote-->>Engine: select winner
        alt needs deeper decomposition
            Engine->>Recursive: recurse on sub tasks
        else solved
            Engine-->>Engine: continue to next stage
        end
        Note right of Engine: repeat until all tasks solved
    end

    Engine->>Post: optional connector call by coordinator
    Post->>External: post process output
    External-->>Post: processed result
    Post-->>Engine: StepCompletedEvent

    Engine-->>Workflow: WorkflowCompletedEvent
    Workflow-->>App: final output events
    App-->>API: final output events
    API-->>User: SSE stream and final result

在 YAML 里给步骤填 type: xxx 即可。下面按用途分类，不必全记，用到时查即可。

更多细节与 Connector 配置见 Aevatar.Configuration。

• Foundation 内核与运行时
  • src/Aevatar.Foundation.Abstractions：基础契约（Agent/Actor/Event/Store）
  • src/Aevatar.Foundation.Core：GAgentBase、事件管线、上下文与状态守卫
  • src/Aevatar.Foundation.Runtime：本地运行时、路由、流、存储
  • src/Aevatar.Foundation.Runtime.*：Orleans/Streaming/Transport/Hosting 实现与装配
• AI 能力层
  • src/Aevatar.AI.Abstractions：LLM/Tool/Middleware 抽象
  • src/Aevatar.AI.Core：ChatRuntime、ToolLoop、可观测性中间件
  • src/Aevatar.AI.LLMProviders.*：LLM Provider 实现
  • src/Aevatar.AI.ToolProviders.*：MCP/Skills 工具提供者
• CQRS 与投影内核
  • src/Aevatar.CQRS.Core*：命令执行基础设施
  • src/Aevatar.CQRS.Projection.*：通用投影协调、订阅、生命周期
  • src/Aevatar.Foundation.Projection / src/Aevatar.AI.Projection：通用读侧模型与 AI 投影能力
• Workflow 主能力
  • src/workflow/Aevatar.Workflow.Core：工作流引擎与步骤模块（workflow_loop、llm_call、parallel、vote、connector_call 等）
  • src/workflow/Aevatar.Workflow.Application*：Run 请求编排、输出流聚合、查询服务
  • src/workflow/Aevatar.Workflow.Projection：Workflow read model 与实时输出事件
  • src/workflow/Aevatar.Workflow.Infrastructure：Workflow 的基础设施实现
  • src/workflow/Aevatar.Workflow.Presentation.AGUIAdapter：EventEnvelope -> AGUI 事件映射
• Workflow 扩展（插件）
  • src/workflow/extensions/Aevatar.Workflow.Extensions.Maker：Maker 扩展模块
  • src/workflow/extensions/Aevatar.Workflow.Extensions.AIProjection：AI 投影扩展
  • src/workflow/extensions/Aevatar.Workflow.Extensions.Hosting：Workflow Hosting 扩展装配
• 宿主与统一入口
  • src/Aevatar.Mainnet.Host.Api：默认统一入口（组合 Workflow 能力和扩展）
  • src/workflow/Aevatar.Workflow.Host.Api：Workflow 独立宿主（能力隔离入口）
  • src/Aevatar.Bootstrap / src/Aevatar.Bootstrap.Extensions.AI：能力装配入口
• 配套目录
  • apps/aevatar-console-web：前端控制台工作目录
  • test/：单元、集成、宿主测试

• 主链路统一为 Command -> Event -> Projection -> ReadModel。
• 编排能力统一落在 workflow 模块，不在 Foundation 维护第二套独立编排实现。
• Host/API 只做协议适配与能力组合，不直接写业务编排逻辑。
• Projection 相关运行态由 Actor/分布式状态承载，避免中间层进程内事实态字典。
• 扩展（如 Maker）通过插件挂载，不允许 Workflow 主能力反向依赖扩展。

你主要会接触：src/Aevatar.Mainnet.Host.Api 或 src/workflow/Aevatar.Workflow.Host.Api（启动服务）、apps/aevatar-console-web（前端控制台）、~/.aevatar/（配置、Connector 与工作流）。其余目录在二次开发或排查问题时按上面模块地图定位即可。

• 文档索引： docs/README.md — 全部文档自动生成索引。
• 底层设计： docs/canon/architecture.md — 事件模型与 Pipeline。
• 系统架构总览： docs/canon/overview.md — 分层、能力装配、宿主边界。
• CQRS 架构： docs/canon/cqrs-projection.md — 写侧/读侧、统一投影链路、接入约束。
• Conversation 与 Memory 语义： docs/canon/conversation-context-and-memory.md — transcript、execution state、prompt context 与 user memory 的所有权和 retention。
• CQRS 投影架构： src/Aevatar.CQRS.Projection.Core/README.md / src/workflow/Aevatar.Workflow.Projection/README.md — 统一 Projection Lifecycle、Coordinator 与 ReadModel。
• Role 与 Connector： docs/canon/role-model.md — Workflow YAML 中的角色、Connector 配置、把 MCP/CLI/API 当角色能力。
• Event Sourcing： docs/canon/event-sourcing.md — 如何开启事件溯源。
• Connector 配置详解： docs/canon/connector.md — 配置格式与示例。
• 项目拆分策略： docs/adr/0001-project-split-strategy.md — 分片与拆仓路径。

• 运行测试：dotnet test test/Aevatar.Foundation.Core.Tests/Aevatar.Foundation.Core.Tests.csproj
• 默认全量测试：dotnet test aevatar.slnx --nologo
• 按域构建：dotnet build aevatar.foundation.slnf / dotnet build aevatar.ai.slnf / dotnet build aevatar.cqrs.slnf / dotnet build aevatar.workflow.slnf / dotnet build aevatar.capabilities.slnf
• Agent 命名约定：带 GAgent 的类负责框架能力（事件分发、状态、路由）；业务逻辑放在基于 GAgent 的扩展或自定义步骤/Connector 里。