AutoGen for .NET - 架构学习指南

👋 嗨！欢迎来到 AutoGen for .NET 的学习之旅。我是你的架构教练，将带你从零开始，一步步揭开这个由微软打造的多智能体框架的神秘面纱。无论你是想快速上手，还是想深入理解其架构精髓，这份指南都将是你最好的伙伴。

🔍 第一部分：项目架构深度解析（像架构师一样俯瞰全景）

本部分目标： 帮助你站在架构师的高度，理解 AutoGen for .NET 的设计哲学、技术选型和核心概念，从而知其然更知其所以然。

🌟 1. 项目架构概览

📖 用通俗的类比理解 AutoGen

想象一下，你正在组建一个大型电影制作团队。在这个团队里：

演员（Agent）各司其职，每个人都有自己的角色和台词
导演（Orchestrator）负责协调各个演员的表演顺序
制片人（Runtime）管理整个剧组的资源调度
剧本（Message）是大家交流的主要方式
话题板（Topic）用来发布通知，让相关人员都能看到

AutoGen for .NET 就像这样一个精心设计的"智能体剧组管理系统"，让多个 AI 智能体能够协同工作，完成复杂任务。

🎯 核心设计特征

重要提示：AutoGen for .NET 目前包含两套并行的架构体系！

AutoGen.* 系列（0.2 版遗产） 📦
- 这是从 Python AutoGen 0.2 移植过来的经典版本
- 采用直接调用模式：Agent 之间通过方法调用直接通信
- 适合简单的双代理对话和群聊场景
- 正在逐步被新架构替代，但目前仍然稳定可用
Microsoft.AutoGen.* 系列（事件驱动的未来） 🚀
- 这是全新设计的下一代架构
- 采用事件驱动模式：Agent 通过发布/订阅消息进行通信
- 基于 Orleans 虚拟 Actor 模型，支持分布式部署
- 集成 .NET Aspire，提供现代化的云原生开发体验
- API 尚不稳定，但代表着项目的未来方向

💡 学习建议： 如果你是新手，我建议你从旧版 AutoGen. 开始，快速掌握智能体的基本概念；如果你的目标是构建生产级分布式系统，那么新版 Microsoft.AutoGen. 才是你应该深入研究的方向。

🏗️ 同类项目设计类比

AutoGen for .NET 与其他智能体框架的对比：

vs. LangChain/LangGraph：

AutoGen 更强调多智能体协作，而 LangChain 更注重单一 LLM 的链式调用
AutoGen 的群聊机制（Group Chat）是其独特优势，可以让多个 Agent 像开会一样讨论问题

vs. Semantic Kernel：

Semantic Kernel 是微软的另一个 LLM 编排框架，专注于插件生态
AutoGen 提供了 SemanticKernel 的集成包（AutoGen.SemanticKernel），可以把 SK 的强大插件能力带入多智能体场景
如果说 SK 是"单兵作战利器"，那么 AutoGen 就是"团队协作平台"

vs. Python AutoGen：

.NET 版本的独特优势：
- ✅ 类型安全的函数调用：通过 Source Generator 自动生成类型安全的函数定义
- ✅ dotnet-interactive 集成：可以在 Agent 中直接执行 C#、F#、PowerShell、Python 代码
- ✅ Orleans 加持：新版架构天生支持分布式部署和容错
- ✅ Aspire 现代化工具链：开箱即用的可观测性和本地开发体验

🛠️ 技术栈分析

核心框架层：

.NET 9.0 SDK：项目使用最新的 .NET 9.0（需要向下兼容 .NET 8.0 和 .NET Standard 2.0）
Orleans 9.0.1：微软的虚拟 Actor 框架，新版架构的基石
.NET Aspire 9.0：云原生开发工具链，提供服务发现、可观测性等能力

LLM 集成层：

OpenAI / Azure OpenAI：通过 Azure.AI.OpenAI 和 OpenAI SDK 集成
Anthropic Claude：提供 AutoGen.Anthropic 包
Google Gemini：支持 Google Gemini 和 Vertex AI
本地模型：支持 Ollama、LM Studio 等本地部署方案
Microsoft.Extensions.AI：微软的统一 AI 抽象层（9.5.0 版本）

通信与序列化：

gRPC：Agent 之间的高性能通信协议（跨语言支持）
Protocol Buffers：消息序列化格式
CloudEvents：云原生事件规范

测试与质量保障：

xUnit：单元测试框架
FluentAssertions：流式断言库
Moq：Mock 框架
ApprovalTests：快照测试工具

🌐 外部系统集成

必需的外部服务：

LLM API 服务
- OpenAI API（需要 OPENAI_API_KEY 环境变量）
- 或者 Azure OpenAI（需要 Endpoint 和 API Key）
- 或者本地 Ollama 服务（默认 http://localhost:11434）
Orleans 集群存储（仅新版架构需要）
- 开发环境：内存存储
- 生产环境：可选 Azure Cosmos DB、Azure Table Storage 等

可选的增强服务：

Redis：用于缓存和分布式锁
Application Insights：用于遥测和监控
Qdrant / 其他向量数据库：用于 RAG（检索增强生成）场景

🎬 架构流程描述

旧版 AutoGen.* 的典型流程：

┌─────────────┐         ┌─────────────┐
│ UserProxy   │ ───1──→ │ Assistant   │
│ Agent       │         │ Agent       │
└─────────────┘         └─────────────┘
      ↑                        │
      │                        │
      │          ┌──────────┐  │
      └────4─────┤ LLM API  │←─2
                 └──────────┘
                        │
                        3─→ Function Call

UserProxyAgent 发起对话，发送 IMessage 到 AssistantAgent
AssistantAgent 调用 LLM API 生成回复
如果需要，执行函数调用（Function Call）
返回结果给 UserProxyAgent，继续下一轮对话

新版 Microsoft.AutoGen.* 的典型流程：

┌─────────────┐       ┌─────────────┐       ┌─────────────┐
│  Client     │       │  Runtime    │       │  Agent A    │
│  (Program)  │       │  (Orleans)  │       │  (Grain)    │
└─────────────┘       └─────────────┘       └─────────────┘
      │                      │                      │
      │─── Publish Msg ────→│                      │
      │     to Topic         │                      │
      │                      │─── Deliver ────────→│
      │                      │                      │
      │                      │←─── IHandle<T> ─────│
      │                      │    HandleAsync       │
      │                      │                      │
      │                      │      Publish to      │
      │                      │←──── Another Topic ──│
      │                      │                      │
      │                      │      ┌─────────────┐ │
      │                      │─────→│  Agent B    │ │
      │                      │      │  (Grain)    │ │
      │                      │      └─────────────┘ │

客户端通过 AgentsApp.PublishMessageAsync() 发布消息到特定 Topic
Runtime（基于 Orleans）找到所有订阅了该 Topic 的 Agent
每个 Agent 通过实现 IHandle<TMessage> 接口处理消息
Agent 可以继续发布新消息到其他 Topic，形成事件驱动链

📂 2. 目录结构与核心流程

🗂️ 目录组织逻辑

项目采用按产品线分层 + 按功能模块划分的混合组织方式：

dotnet/
├── src/                          # 源代码
│   ├── AutoGen.*                 # 旧版本（直接调用模式）
│   │   ├── AutoGen.Core          # 🔵 核心抽象：IAgent, IMessage, GroupChat
│   │   ├── AutoGen.OpenAI        # 🟢 OpenAI 集成
│   │   ├── AutoGen.Anthropic     # 🟢 Anthropic 集成
│   │   ├── AutoGen.SemanticKernel# 🟢 SK 集成
│   │   └── AutoGen.SourceGenerator # 🔧 源生成器（函数调用）
│   │
│   └── Microsoft.AutoGen.*       # 新版本（事件驱动模式）
│       ├── Contracts             # 🔵 核心契约：IAgentRuntime, IHandle<T>
│       ├── Core                  # 🔵 核心实现：BaseAgent, InProcessRuntime
│       ├── Core.Grpc             # 🌐 gRPC 序列化和通信
│       ├── Agents                # 🤖 内置 Agent：InferenceAgent, ConsoleAgent
│       ├── RuntimeGateway.Grpc   # 🌉 分布式网关
│       └── AgentChat             # 💬 对话管理抽象
│
├── samples/                      # 示例项目
│   ├── Hello/                    # 💡 最简单的入门示例（新版）
│   ├── GettingStarted/           # 💡 入门示例（新版，无 Aspire）
│   ├── AgentChat/AutoGen.Basic.Sample/  # 💡 经典示例（旧版）
│   └── dev-team/                 # 🏢 复杂示例：AI 开发团队
│
├── test/                         # 测试项目
│   ├── AutoGen.Tests/            # 旧版单元测试
│   └── Microsoft.AutoGen.*.Tests/ # 新版单元测试
│
├── website/articles/             # 📚 文档
│   ├── getting-start.md
│   ├── Agent-overview.md
│   └── ...
│
├── AutoGen.sln                   # 解决方案文件
├── Directory.Packages.props      # 📦 集中式包版本管理
└── global.json                   # 🔧 SDK 版本锁定（9.0.100）

设计意图解析：

双轨制演进：AutoGen.* 和 Microsoft.AutoGen.* 并存，保证向后兼容的同时推进新架构
职责清晰：
- *.Core 包只包含抽象，不依赖任何 LLM 提供商
- *.OpenAI、*.Anthropic 等包是独立的插件，按需引用
Source Generator 独立：AutoGen.SourceGenerator 可以单独使用，即使不用 AutoGen 框架也能享受类型安全的函数调用生成

🔑 关键文件定位

如果你只有 5 分钟，先读这些：

📌 新手入门第一步：

README.md - 项目概览和快速开始
samples/Hello/README.md - 最简单的新版示例说明
website/articles/getting-start.md - 旧版入门教程

📌 理解旧版架构（AutoGen.*）：

src/AutoGen.Core/Agent/IAgent.cs - Agent 抽象接口
src/AutoGen.Core/Message/IMessage.cs - 消息类型系统
src/AutoGen.Core/GroupChat/GroupChat.cs - 群聊机制核心
samples/AgentChat/AutoGen.Basic.Sample/Example02_TwoAgent_MathChat.cs - 经典双代理示例

📌 理解新版架构（Microsoft.AutoGen.*）：

src/Microsoft.AutoGen/Contracts/IAgentRuntime.cs - Runtime 抽象
src/Microsoft.AutoGen/Contracts/IHandle.cs - 消息处理接口
src/Microsoft.AutoGen/Core/BaseAgent.cs - Agent 基类实现
samples/Hello/HelloAgent/HelloAgent.cs - 最小化可运行示例
samples/GettingStarted/Program.cs - 不依赖 Aspire 的入门示例

📌 理解包管理和依赖：

Directory.Packages.props - 查看所有依赖版本（关键！）
global.json - 确认需要的 .NET SDK 版本
website/articles/Installation.md - 包安装指南

🔗 模块依赖关系

旧版 AutoGen.* 的依赖关系（单向、清晰）：

┌─────────────────────────────────────────┐
│  应用层（你的代码）                       │
└─────────────────────────────────────────┘
                  ↓ 依赖
┌─────────────────────────────────────────┐
│  AutoGen.OpenAI                          │
│  AutoGen.Anthropic                       │
│  AutoGen.SemanticKernel                  │
│  （LLM 集成层，可按需选择）               │
└─────────────────────────────────────────┘
                  ↓ 依赖
┌─────────────────────────────────────────┐
│  AutoGen.Core                            │
│  （核心抽象：IAgent, IMessage）           │
└─────────────────────────────────────────┘

新版 Microsoft.AutoGen.* 的依赖关系（分层架构）：

┌─────────────────────────────────────────┐
│  应用层（你的 Agent 实现）                │
└─────────────────────────────────────────┘
                  ↓ 依赖
┌─────────────────────────────────────────┐
│  Microsoft.AutoGen.Core                  │
│  （BaseAgent, InProcessRuntime）          │
└─────────────────────────────────────────┘
                  ↓ 依赖
┌─────────────────────────────────────────┐
│  Microsoft.AutoGen.Contracts             │
│  （接口定义：IAgentRuntime, IHandle<T>）  │
└─────────────────────────────────────────┘
                  ↓ 可选依赖
┌─────────────────────────────────────────┐
│  Microsoft.Orleans                       │
│  （虚拟 Actor 运行时，分布式部署必需）     │
└─────────────────────────────────────────┘

跨版本集成：

AutoGen.Core 和 Microsoft.AutoGen.Core 完全独立，互不依赖
未来可能会有桥接包，但目前需要选择一个架构使用

⚠️ 注意潜在的耦合问题：

新版架构目前 API 不稳定，升级时可能需要大量代码修改
如果使用 Orleans，需要理解其分布式特性（如 Grain 生命周期、序列化要求）

🎭 典型业务流程：双代理数学教学对话（旧版）

让我选择一个最经典的场景：Teacher Agent 和 Student Agent 的数学问答对话。

场景描述： Teacher 出题，Student 答题，Teacher 检查答案，直到答对为止。

数据流和控制流：

sequenceDiagram
    participant User as 用户代码
    participant Student as StudentAgent
    participant Teacher as TeacherAgent
    participant LLM as OpenAI API

    User->>Student: InitiateChatAsync("请出题")
    activate Student

    Student->>LLM: 生成请求消息
    LLM-->>Student: "请出题给我"
    Student->>Teacher: GenerateReplyAsync([messages])
    activate Teacher

    Teacher->>LLM: "作为老师，出一道题"
    LLM-->>Teacher: "请问 2+3=?"
    Teacher-->>Student: TextMessage("请问 2+3=?")
    deactivate Teacher

    Student->>LLM: "作为学生，回答这道题"
    LLM-->>Student: "答案是 5"
    Student->>Teacher: TextMessage("答案是 5")
    activate Teacher

    Teacher->>LLM: "检查答案是否正确"
    LLM-->>Teacher: "[COMPLETE] 答案正确！"
    Teacher-->>Student: TextMessage("[GROUPCHAT_TERMINATE]")
    deactivate Teacher

    Student-->>User: 返回对话历史
    deactivate Student

实现文件索引：

步骤	核心文件	关键代码行
1. 定义 Teacher Agent	`samples/AgentChat/AutoGen.Basic.Sample/Example02_TwoAgent_MathChat.cs`	第 18-35 行
2. 定义 Student Agent	同上	第 38-44 行
3. 发起对话	同上	第 47-50 行
4. OpenAI 消息转换	`src/AutoGen.OpenAI/Middleware/OpenAIChatRequestMessageConnector.cs`	整个文件
5. 中间件链处理	`src/AutoGen.Core/Agent/MiddlewareAgent.cs`	`GenerateReplyAsync` 方法
6. 群聊终止检测	`src/AutoGen.Core/Extension/GroupChatExtension.cs`	`IsGroupChatTerminateMessage` 方法

关键代码片段解析：

// 🔸 步骤 1：创建 Teacher Agent
var teacher = new OpenAIChatAgent(
    chatClient: gpt4oMini,  // OpenAI 客户端
    name: "teacher",
    systemMessage: "你是老师，负责出题和检查答案"
)
.RegisterMessageConnector()  // 🔧 注册消息格式转换中间件
.RegisterMiddleware(async (msgs, option, agent, _) =>  // 🔧 注册终止检测中间件
{
   
    var reply = await agent.GenerateReplyAsync(msgs, option);
    if (reply.GetContent()?.Contains("COMPLETE") is true)
    {
   
        return new TextMessage(Role.Assistant, GroupChatExtension.TERMINATE, from: reply.From);
    }
    return reply;
})
.RegisterPrintMessage();  // 🔧 注册打印中间件（调试用）

// 🔸 步骤 2：发起对话
var conversation = await student.InitiateChatAsync(
    receiver: teacher,
    message: "请出题给我",
    maxRound: 10  // 最多 10 轮对话
);

深入理解中间件机制：

AutoGen 的强大之处在于其中间件管道（类似 ASP.NET Core 的中间件）：

[原始消息] → [MessageConnector] → [CustomMiddleware] → [PrintMessage] → [Agent.GenerateReplyAsync] → [LLM API]

每个 RegisterXXX 调用都在 Agent 外面包裹了一层处理逻辑，实现了：

✅ 消息格式转换（IMessage ↔ OpenAI ChatMessage）
✅ 函数调用自动执行
✅ 日志打印
✅ 异常处理
✅ 自定义业务逻辑

💻 3. 代码结构观察

🏗️ 代码组织模式

旧版 AutoGen.* 的设计模式：

接口抽象 + 中间件装饰者模式

核心接口非常简洁：

public interface IAgent
{
     
    string Name {
      get; }
    Task<IMessage> GenerateReplyAsync(
        IEnumerable<IMessage> messages,
        GenerateReplyOptions? options = null,
        CancellationToken cancellationToken = default);
}

通过 MiddlewareAgent 实现装饰者模式：

var agent = new OpenAIChatAgent(...)
    .RegisterMiddleware(middleware1)  // 第一层包装
    .RegisterMiddleware(middleware2)  // 第二层包装
    .RegisterMiddleware(middleware3); // 第三层包装

消息类型的多态设计

使用接口标记不同能力的消息：

public interface IMessage {
      string? From {
      get; set; } }
public interface IMessage<T> : IMessage {
      T Content {
      get; } }
public interface ICanGetTextContent : IMessage {
      string? GetContent(); }
public interface ICanGetToolCalls : IMessage {
      IEnumerable<ToolCall> GetToolCalls(); }

支持的消息类型：

TextMessage - 纯文本
ImageMessage - 图片
MultiModalMessage - 多模态
ToolCallMessage - 函数调用请求
ToolCallResultMessage - 函数调用结果
AggregateMessage<T1, T2> - 组合消息

Orchestrator（编排器）模式

用于控制群聊中的发言顺序：

public interface IOrchestrator
{
     
    Task<IAgent?> GetNextSpeakerAsync(
        OrchestrationContext context,
        CancellationToken cancellationToken = default);
}

内置实现：

RoundRobinOrchestrator - 轮流发言
RolePlayOrchestrator - 基于角色的动态选择

新版 Microsoft.AutoGen.* 的设计模式：

事件驱动 + 发布/订阅模式

Agent 通过实现 IHandle<TMessage> 来订阅消息类型：

[TypeSubscription("HelloTopic")]  // 🔖 订阅主题
public class HelloAgent : BaseAgent,
    IHandle<NewMessageReceived>,  // 🎧 处理新消息事件
    IHandle<ConversationClosed>,  // 🎧 处理对话关闭事件
    IHandle<Shutdown>             // 🎧 处理关闭事件
{
     
    public async ValueTask HandleAsync(NewMessageReceived item, MessageContext ctx)
    {
     
        Console.WriteLine(item.Message);
        await this.PublishMessageAsync(new ConversationClosed {
      ... }, new TopicId("HelloTopic"));
    }
}

虚拟 Actor 模式（基于 Orleans）

每个 Agent 实例是一个轻量级的 "Grain"（虚拟 Actor）：
- 🎭 位置透明：不需要知道 Agent 在哪台机器上
- 🔐 单线程保证：同一个 Agent 实例同一时刻只处理一个消息（无并发问题）
- 💾 状态持久化：可以自动保存和恢复状态
- 🌐 自动扩展：Orleans 负责负载均衡和故障转移

依赖注入 + 工厂模式

通过 AgentsAppBuilder 注册 Agent 类型：

var appBuilder = new AgentsAppBuilder();
appBuilder.UseInProcessRuntime();  // 或 UseGrpcRuntime()

appBuilder.AddAgent<Checker>("Checker");
appBuilder.AddAgent<Modifier>("Modifier");

var app = await appBuilder.BuildAsync();

Runtime 在需要时自动创建 Agent 实例。

🎨 设计模式识别

我在代码中观察到的设计模式：

设计模式	应用场景	文件位置
装饰者模式	中间件管道	`src/AutoGen.Core/Agent/MiddlewareAgent.cs`
策略模式	Orchestrator（编排器）	`src/AutoGen.Core/Orchestrator/IOrchestrator.cs`
工厂模式	Agent 创建	`Microsoft.AutoGen.Core/AgentsApp.cs`
观察者模式	事件发布/订阅	`Microsoft.AutoGen.Contracts/IHandle.cs`
Actor 模式	并发隔离	基于 Microsoft.Orleans
Builder 模式	Agent 配置构建	`AgentsAppBuilder`
模板方法模式	BaseAgent 基类	`Microsoft.AutoGen.Core/BaseAgent.cs`
Adapter 模式	LLM 消息转换	`src/AutoGen.OpenAI/Middleware/OpenAIChatRequestMessageConnector.cs`

特别关注：Source Generator（源生成器）

这是 .NET 平台的独特优势！

// ✍️ 你只需要写接口定义
public partial class WeatherFunction
{
   
    [Function]
    public async Task<string> GetWeather(string city)
    {
   
        return $"The weather in {city} is sunny.";
    }
}

// 🪄 编译时自动生成类型安全的 FunctionContract
// 位置: src/AutoGen.SourceGenerator/FunctionCallGenerator.cs

生成的代码会自动包含：

JSON Schema 定义
参数验证
类型转换
调用包装

📊 代码质量观察

优点：

✅ 接口设计简洁清晰

IAgent 只有一个核心方法
IHandle<T> 只有一个 HandleAsync 方法
符合接口隔离原则

✅ 中间件机制优雅

类似 ASP.NET Core 的中间件管道
易于扩展和组合
职责分离清晰

✅ 类型安全

使用了 C# 的 Nullable Reference Types
Source Generator 提供编译时类型检查
Orleans 的序列化类型检查

✅ 文档完善

每个公共 API 都有 XML 文档注释
website/articles/ 下有丰富的教程
示例代码覆盖各种场景

改进空间（学习机会）：

🔍 TODO 和 FIXME 搜索结果：

// Microsoft.AutoGen.Contracts/IAgentRuntime.cs:40
// TODO: Can we call this Resolve?

// Microsoft.AutoGen.Contracts/IAgentRuntime.cs:114-116
// TODO:
// public ValueTask<TAgent> TryGetUnderlyingAgentInstanceAsync<TAgent>(AgentId agentId);
// public void AddMessageSerializer(params object[] serializers);

💡 值得探索的重构机会：

消息路由的性能优化（针对有经验的学习者）
- 当前 BaseAgent.OnMessageAsync 使用反射查找处理器
- 可以考虑在启动时生成静态路由表
- 参考文件：src/Microsoft.AutoGen/Core/BaseAgent.cs:60-81
分布式追踪的增强（针对生产环境关注者）
- 当前使用 ActivitySource 进行追踪
- 可以集成 OpenTelemetry 的自动化注入
- 参考文件：src/Microsoft.AutoGen/Core/BaseAgent.cs:20
错误处理的统一（初学者友好的改进点）
- 部分代码使用 throw new Exception()
- 建议定义领域特定异常（如 AgentNotFoundException）
- 参考文件：观察 src/Microsoft.AutoGen/Contracts/AgentExceptions.cs
配置验证的加强
- LLM API Key 等敏感配置的验证时机可以提前
- 可以使用 IValidateOptions<T> 模式
- 学习机会：为 OpenAIConfig 添加启动时验证

代码风格一致性：

✅ 使用 .editorconfig 统一代码格式
✅ 启用了 TreatWarningsAsErrors（第 19 行，Directory.Build.props）
✅ 启用了代码分析器 EnableNetAnalyzers
⚠️ 部分旧代码使用 #pragma warning disable，但有明确的 CSNoWarn 配置

📚 第二部分：技能需求清单（你的学习弹药库）

本部分目标： 明确告诉你需要掌握哪些技能才能玩转 AutoGen for .NET，以及如何评估自己的技能水平。

1. 基础技能要求

🎯 必备技能（没有这些，寸步难行）

C# 语言特性：

✅ C# 8.0+ 语法：
- Nullable Reference Types（string?, #nullable enable）
- Async/Await 异步编程
- LINQ 查询表达式
- Extension Methods（扩展方法）
✅ C# 9.0+ 高级特性：
- Record Types（不可变数据类型）
- Pattern Matching（模式匹配）
- Top-level Statements（顶层语句）
✅ C# 10.0+ 新特性：
- Global Usings（全局引用）
- File-scoped Namespaces（namespace XX;）

💡 学习建议： 如果你还在用 C# 7.0 或更早的语法，强烈建议先花 2-3 天学习现代 C# 特性。推荐微软官方的 C# 文档。

.NET 平台基础：

✅ .NET SDK 使用：
- dotnet build / dotnet run / dotnet test
- NuGet 包管理
- 项目引用和依赖管理
✅ 依赖注入（DI）：
- Microsoft.Extensions.DependencyInjection
- 服务生命周期：Singleton / Scoped / Transient
- IServiceProvider 和 IServiceCollection
✅ 配置管理：
- appsettings.json 配置文件
- 环境变量读取
- IOptions<T> 模式

具体版本要求（来自 Directory.Packages.props）：

核心依赖	版本	说明
.NET SDK	9.0.100	从 `global.json` 查看，需要安装 .NET 9 SDK
Microsoft.Extensions.AI	9.5.0	微软的统一 AI 抽象层
Microsoft.Orleans	9.0.1	Orleans 虚拟 Actor 框架（新版架构）
Azure.AI.OpenAI	2.2.0-beta.4	Azure OpenAI 集成
Semantic Kernel	1.45.0	如果使用 SK 集成
Grpc.AspNetCore	2.67.0	gRPC 通信（新版架构）

⚠️ 版本兼容性提示：

项目同时支持 .NET Standard 2.0 和 .NET 8.0（见 Directory.Build.props:7）
但开发和运行建议使用 .NET 9.0
如果你的项目必须用 .NET 6/7，可以只引用旧版 AutoGen.Core

基础工具和概念：

✅ Git 版本控制：基本的 clone、branch、commit、pull request
✅ 命令行基础：PowerShell（Windows）或 Bash（Linux/Mac）
✅ HTTP/REST API 概念：理解请求/响应模型（调用 LLM API 需要）
✅ JSON 序列化：System.Text.Json 使用

🧪 LLM 和 AI 相关知识

必须理解的核心概念：

📖 Prompt Engineering（提示词工程）：
- System Message（系统消息）的作用
- Few-shot Learning（少样本学习）
- Chain-of-Thought（思维链）提示
📖 LLM 参数：
- Temperature（温度）：控制输出随机性
- Max Tokens（最大令牌数）：控制输出长度
- Top-p / Top-k：采样策略
📖 Function Calling（函数调用）：
- 什么是 Function Calling / Tool Use
- JSON Schema 如何描述函数签名
- 函数调用的执行流程

不需要深入，但应该知道：

🔹 Token 计费模型（按输入/输出 token 数量计费）
🔹 Embedding（向量嵌入）的基本原理（如果使用 RAG）
🔹 不同模型的能力差异（GPT-4 vs GPT-3.5 vs Claude）

💡 推荐学习资源：

2. 进阶技能要求

🏗️ 架构模式和设计原则

设计模式（项目中的实际应用）：

装饰者模式（Decorator Pattern）
- 💼 应用场景：中间件管道
- 📖 需要理解：如何动态地为对象添加职责
- 🎯 学习路径：先看 IMiddleware 接口定义，再看 MiddlewareAgent 实现
策略模式（Strategy Pattern）
- 💼 应用场景：IOrchestrator 编排器
- 📖 需要理解：如何在运行时选择不同的算法
- 🎯 学习路径：比较 RoundRobinOrchestrator 和 RolePlayOrchestrator
发布/订阅模式（Pub/Sub Pattern）
- 💼 应用场景：新版架构的事件驱动模型
- 📖 需要理解：解耦生产者和消费者
- 🎯 学习路径：从 IHandle<T> 接口开始，理解 TopicId 的作用
Actor 模型（Actor Model）
- 💼 应用场景：Orleans 的虚拟 Actor
- 📖 需要理解：无共享状态的并发模型
- 🎯 学习路径：先学习 Akka.NET 的概念，再看 Orleans 文档

SOLID 原则在项目中的体现：

原则	体现	示例
Single Responsibility	`IAgent` 只负责生成回复，中间件负责格式转换	`OpenAIChatRequestMessageConnector`
Open/Closed	通过中间件扩展功能，无需修改 Agent	`RegisterMiddleware()` 方法
Liskov Substitution	所有 `IAgent` 实现可以互换	`OpenAIChatAgent` / `AnthropicAgent`
Interface Segregation	`IHandle<T>` 只定义一个方法	`IHandle<NewMessageReceived>`
Dependency Inversion	Agent 依赖 `IAgentRuntime` 抽象	`BaseAgent` 构造器

架构风格（需要理解）：

🏛️ 分层架构（Layered Architecture）：旧版 AutoGen 的清晰分层
🎯 事件驱动架构（Event-Driven Architecture）：新版架构的核心
🌐 微服务架构（Microservices）：如果使用 Orleans 分布式部署

🔧 Orleans 虚拟 Actor 框架（新版架构必需）

如果你打算使用 Microsoft.AutoGen.* 新版架构，Orleans 是必须掌握的：

核心概念：

Grain（粒子）：Orleans 中的 Actor，类似于 AutoGen 的 Agent
Silo（筒仓）：Orleans 运行时的宿主进程
Cluster（集群）：多个 Silo 组成的分布式系统
Persistence（持久化）：Grain 状态的自动保存
Reminder（提醒器）：定时任务机制

💡 学习路径：

📖 阅读 Orleans 官方文档（中文）
🎯 完成 Orleans 的入门教程
🔍 回头看 AutoGen 的 Microsoft.AutoGen.Core/InProcessRuntime.cs，理解它如何封装 Orleans

不需要成为 Orleans 专家，但应该知道：

⚡ Grain 的单线程保证（不需要手动加锁）
🌐 位置透明性（不需要知道 Grain 在哪台机器上）
💾 状态持久化的配置方式
🔄 Grain 的激活和失活机制

🌐 gRPC 和 Protobuf（跨语言集成需要）

如果需要让 Python 和 .NET 的 Agent 互相通信，需要理解：

核心概念：

📝 Protocol Buffers：接口定义语言（IDL）
🔌 gRPC：高性能 RPC 框架
🌉 服务定义：.proto 文件的编写

学习路径：

查看 samples/Hello/protos/agent_events.proto 了解消息定义
理解 Microsoft.AutoGen.Core.Grpc 如何做序列化
如果需要，学习 gRPC 官方教程

🧪 测试驱动开发（TDD）

项目使用的测试工具：

xUnit：单元测试框架
FluentAssertions：流式断言库（conversation.Should().HaveCount(3)）
Moq：Mock 框架（模拟 LLM 响应）
ApprovalTests：快照测试（验证生成的代码）

学习机会：

📖 查看 test/AutoGen.Tests/TwoAgentTest.cs 学习如何测试 Agent 对话
📖 查看 test/AutoGen.OpenAI.Tests/OpenAIMessageTests.cs 学习消息转换测试
🎯 尝试为你自己的 Agent 编写单元测试

3. 技能掌握程度建议

🌱 初学者路线（2-4 周）

你的目标： 能够运行示例，修改提示词，创建简单的双代理对话。

必学技能：

✅ C# 基础语法（到 C# 8.0）
✅ Async/Await 异步编程
✅ .NET CLI 基本命令
✅ 理解 Prompt Engineering 基础

推荐学习顺序：

安装 .NET 9 SDK 和 Visual Studio / VS Code
运行 samples/AgentChat/AutoGen.Basic.Sample 中的示例
修改 Example02_TwoAgent_MathChat.cs 的 System Message
尝试创建自己的 Teacher 和 Student Agent
阅读 website/articles/getting-start.md

学习成果验证：

📝 能解释 IAgent 和 IMessage 的作用
💻 能修改示例代码的 System Message 并运行
🧪 能创建一个简单的双代理对话（如医生和患者）

🚀 有经验的开发者路线（1-2 周）

你的目标： 能够使用 AutoGen 集成到自己的应用中，实现复杂的群聊和函数调用。

必学技能：

✅ 依赖注入和配置管理
✅ 中间件和装饰者模式
✅ Function Calling 的工作原理
✅ 理解 GroupChat 和 Orchestrator

推荐学习顺序：

深入阅读 src/AutoGen.Core/ 的核心代码
学习 Example03_Agent_FunctionCall.cs 的函数调用
学习 Example04_Dynamic_GroupChat_Coding_Task.cs 的群聊机制
使用 Source Generator 创建类型安全的函数定义
阅读 website/articles/Middleware-overview.md

学习成果验证：

🏗️ 能解释中间件管道的工作原理
💻 能使用 RegisterMiddleware 添加自定义逻辑
🧪 能创建一个三人群聊（如项目经理、开发者、测试）
🔧 能使用 Source Generator 自动生成函数定义

🎯 意欲贡献代码的进阶者路线（3-4 周）

你的目标： 理解新版架构，能够为项目贡献代码或构建生产级分布式系统。

必学技能：

✅ Orleans 虚拟 Actor 框架
✅ gRPC 和 Protobuf
✅ .NET Aspire 开发工具链
✅ 分布式系统设计原则
✅ xUnit 单元测试和 Moq

推荐学习顺序：

完成 Orleans 官方教程（1-2 天）
学习 .NET Aspire 的快速入门（1 天）
深入阅读 src/Microsoft.AutoGen/Core/ 的源码
运行 samples/Hello/ 并理解其工作原理
运行 samples/dev-team/ 复杂示例
阅读 test/Microsoft.AutoGen.Core.Tests/ 的单元测试

学习成果验证：

🏛️ 能解释事件驱动架构和 Actor 模型的区别
💻 能从零创建一个基于新架构的 Agent
🌐 能配置 Orleans 的分布式集群
🧪 能为 Agent 编写完整的单元测试
🔍 能阅读项目源码并找到 bug 或改进点

🎯 第三部分：学习路径规划（你的专属教练计划）

本部分目标： 提供可立即执行的、分阶段的学习计划，让你从"能运行"到"能理解"再到"能扩展"。

💻 1. 项目运行入口定位（快速上手）

🚀 一键启动指南

环境准备清单（预计 15-30 分钟）：

✅ 步骤 1：安装 .NET 9 SDK

# Windows PowerShell
winget install Microsoft.DotNet.SDK.9

# 或者下载安装包：
# https://dotnet.microsoft.com/download/dotnet/9.0

# 验证安装
dotnet --version  # 应该显示 9.0.100 或更高

✅ 步骤 2：克隆项目

git clone https://github.com/microsoft/autogen.git
cd autogen/dotnet

✅ 步骤 3：配置 OpenAI API Key（必需）

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-your-key-here"

# 或者永久设置（推荐）
[System.Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'sk-your-key-here', 'User')

# Linux/Mac
export OPENAI_API_KEY="sk-your-key-here"
# 写入 ~/.bashrc 或 ~/.zshrc 永久保存

⚠️ 如果没有 OpenAI API Key：

方案 A：使用 Ollama 本地模型（见下文）
方案 B：使用 Azure OpenAI（需要修改配置）

✅ 步骤 4：一键运行示例（选择一个）

方案 A：运行旧版经典示例（推荐新手）

cd samples/AgentChat/AutoGen.Basic.Sample
dotnet run

# 程序会列出所有示例，选择 1 运行第一个示例
# 输入：1
# 输出：会看到 Assistant Agent 的自我介绍

方案 B：运行新版 Hello 示例（体验事件驱动）

cd samples/Hello/Hello.AppHost
dotnet run

# 会自动打开 Aspire Dashboard（浏览器）
# 在控制台查看 HelloAgent 的输出

方案 C：使用 Ollama 本地模型（无需 API Key）

# 1. 先安装 Ollama：https://ollama.com/download

# 2. 下载模型
ollama pull llama3.2

# 3. 运行 Ollama 示例
cd samples/AgentChat/AutoGen.Ollama.Sample
dotnet run

⚙️ 环境配置清单

必需项	版本要求	验证命令	下载链接
.NET SDK	9.0.100+	`dotnet --version`	下载
OpenAI API Key	-	`echo $env:OPENAI_API_KEY`	申请
Git	2.0+	`git --version`	下载

可选项	用途	安装方式
Visual Studio 2022	完整 IDE	下载
VS Code + C# Dev Kit	轻量编辑器	下载
Ollama	本地模型运行	下载
Docker Desktop	容器化部署	下载

🚨 最常见的配置陷阱及其解决方案

陷阱 1：OpenAI API 调用失败

错误信息：Unauthorized: Incorrect API key provided

解决方案：

# 检查环境变量是否设置
echo $env:OPENAI_API_KEY  # Windows
echo $OPENAI_API_KEY      # Linux/Mac

# 确保 Key 前缀是 sk-
# 确保 Key 没有多余的空格或引号

陷阱 2：.NET SDK 版本不匹配

错误信息：error NETSDK1045: The current .NET SDK does not support targeting .NET 9.0

解决方案：

# 检查 SDK 版本
dotnet --list-sdks

# 如果没有 9.0.x，重新安装 .NET 9 SDK
# 或者临时修改 global.json 使用现有版本（不推荐）

陷阱 3：Orleans Silo 启动失败（新版架构）

错误信息：Unable to start Orleans Silo

解决方案：

# 检查端口占用（Orleans 默认使用 11111 和 30000）
netstat -ano | findstr "11111"

# 关闭占用端口的进程或修改配置

陷阱 4：NuGet 包还原失败

错误信息：Unable to load the service index for source https://api.nuget.org/v3/index.json

解决方案：

# 清理 NuGet 缓存
dotnet nuget locals all --clear

# 重新还原包
dotnet restore

# 如果在中国大陆，配置镜像源
dotnet nuget add source https://nuget.cdn.azure.cn/v3/index.json --name AzureChinaCloud

✅ 验证成功标志

旧版示例（Example01_AssistantAgent）成功运行的标志：

Message from assistant
--------------------
content: Hello! I'm here to help you...
--------------------

新版 Hello 示例成功运行的标志：

Hello World
HelloAgent said Goodbye
Shutting down...

Aspire Dashboard 成功打开的标志：

浏览器自动打开 http://localhost:15201
能看到 "Resources" 和 "Traces" 面板
HelloAgent 显示为 "Running" 状态

📅 2. 循序渐进学习计划（四阶段法）

🌱 阶段一：环境搭建和项目启动（1-2 天）

目标： 成功运行项目并能打个断点，理解代码执行流程。

具体任务：

Day 1 上午：环境搭建

# 1. 安装 .NET 9 SDK
dotnet --version

# 2. 克隆项目
git clone https://github.com/microsoft/autogen.git
cd autogen/dotnet

# 3. 验证构建
dotnet build AutoGen.sln

Day 1 下午：运行第一个示例

# 4. 配置 API Key
$env:OPENAI_API_KEY = "sk-your-key-here"

# 5. 运行 Example01
cd samples/AgentChat/AutoGen.Basic.Sample
dotnet run

Day 2 上午：调试和断点

用 Visual Studio 或 VS Code 打开项目：

# 使用 VS Code
code .

# 或者使用 Visual Studio
start AutoGen.sln

在 Example01_AssistantAgent.cs 的以下位置打断点：

var reply = await assistantAgent.SendAsync("Hello");  // 👈 在这里打断点

按 F5 调试运行，观察：

assistantAgent 的类型和属性
SendAsync 方法的执行过程
reply 的内容和类型

Day 2 下午：理解消息流

在 src/AutoGen.Core/Agent/MiddlewareAgent.cs 打断点：

public async Task<IMessage> GenerateReplyAsync(...)
{
   
    // 👈 在这里打断点，观察中间件链的执行
    return await _middleware(messages, options, innerAgent, cancellationToken);
}

学习成果验证：

✅ 能运行至少 3 个不同的示例
✅ 能在关键方法打断点并观察变量
✅ 能解释 IAgent.GenerateReplyAsync 的参数含义
✅ 能修改 System Message 并看到不同的输出

🌿 阶段二：核心流程理解（3-5 天）

目标： 追踪一个完整业务流程，画出自己的流程图。

选择一个场景深入研究（三选一）：

场景 A：双代理数学教学（简单）

cd samples/AgentChat/AutoGen.Basic.Sample
# 研究 Example02_TwoAgent_MathChat.cs

场景 B：函数调用（Function Calling）（中等）

# 研究 Example03_Agent_FunctionCall.cs

场景 C：动态群聊（复杂）

# 研究 Example04_Dynamic_GroupChat_Coding_Task.cs

Day 3：源码追踪

以场景 A 为例，按照以下顺序阅读代码：

1️⃣ Example02_TwoAgent_MathChat.cs - 入口代码
2️⃣ src/AutoGen.OpenAI/Agent/OpenAIChatAgent.cs - Agent 实现
3️⃣ src/AutoGen.OpenAI/Middleware/OpenAIChatRequestMessageConnector.cs - 消息转换
4️⃣ src/AutoGen.Core/Agent/MiddlewareAgent.cs - 中间件执行
5️⃣ src/AutoGen.Core/Extension/AgentExtension.cs - InitiateChatAsync 实现

Day 4：绘制流程图

使用你喜欢的工具（Draw.io、Mermaid、手绘）绘制：

sequenceDiagram
    Student->>Teacher: "请出题"
    Teacher->>OpenAI: POST /v1/chat/completions
    OpenAI-->>Teacher: "2+3=?"
    Teacher-->>Student: TextMessage
    Student->>OpenAI: "作为学生回答"
    OpenAI-->>Student: "答案是 5"
    Student->>Teacher: TextMessage("5")
    Teacher->>OpenAI: "检查答案"
    OpenAI-->>Teacher: "[COMPLETE]"
    Teacher-->>Student: TERMINATE

Day 5-7：动手实践

创建你自己的双代理场景：

// 示例：医生和患者的诊断对话
var doctor = new OpenAIChatAgent(
    chatClient: gpt4,
    name: "doctor",
    systemMessage: "你是一位经验丰富的医生，负责询问患者症状并给出建议"
)
.RegisterMessageConnector()
.RegisterPrintMessage();

var patient = new OpenAIChatAgent(
    chatClient: gpt4,
    name: "patient",
    systemMessage: "你是一位患者，描述你的症状：头痛、发烧、咳嗽"
)
.RegisterMessageConnector()
.RegisterPrintMessage();

// 开始诊断对话
var conversation = await patient.InitiateChatAsync(
    receiver: doctor,
    message: "医生，我感觉不舒服",
    maxRound: 5
);

学习成果验证：

✅ 能画出完整的消息流程图
✅ 能解释中间件的执行顺序
✅ 能自己创建一个新的双代理对话场景
✅ 能解释 RegisterMessageConnector 的作用

🌳 阶段三：模块深入和定制开发（1-2 周）

目标： 能修改或扩展一个现有功能。

Week 1：深入中间件机制

任务 1：创建自定义中间件

创建一个"敏感词过滤"中间件：

using AutoGen.Core;

public class SensitiveWordFilterMiddleware
{
   
    private readonly string[] _sensitiveWords = {
    "password", "credit_card", "secret" };

    public async Task<IMessage> ProcessAsync(
        IEnumerable<IMessage> messages,
        GenerateReplyOptions? options,
        IAgent agent,
        CancellationToken cancellationToken)
    {
   
        // 1. 过滤输入消息
        var filteredMessages = messages.Select(m =>
        {
   
            if (m is IMessage<string> textMsg)
            {
   
                var content = textMsg.Content;
                foreach (var word in _sensitiveWords)
                {
   
                    content = content.Replace(word, "***", StringComparison.OrdinalIgnoreCase);
                }
                return new TextMessage(Role.User, content, from: m.From);
            }
            return m;
        });

        // 2. 调用下一个中间件
        var reply = await agent.GenerateReplyAsync(filteredMessages, options, cancellationToken);

        // 3. 过滤输出消息
        if (reply.GetContent() is string replyContent)
        {
   
            foreach (var word in _sensitiveWords)
            {
   
                replyContent = replyContent.Replace(word, "***", StringComparison.OrdinalIgnoreCase);
            }
            return new TextMessage(Role.Assistant, replyContent, from: reply.From);
        }

        return reply;
    }
}

// 使用方式
var agent = new OpenAIChatAgent(...)
    .RegisterMessageConnector()
    .RegisterMiddleware(async (msgs, opts, agent, ct) =>
    {
   
        var filter = new SensitiveWordFilterMiddleware();
        return await filter.ProcessAsync(msgs, opts, agent, ct);
    })
    .RegisterPrintMessage();

任务 2：实现函数调用（Function Calling）

使用 Source Generator 创建类型安全的函数：

// 1. 定义函数类
public partial class WeatherFunctions
{
   
    [Function]  // 🪄 Source Generator 会自动生成 FunctionContract
    public async Task<string> GetWeather(string city, string unit = "celsius")
    {
   
        // 模拟 API 调用
        await Task.Delay(100);
        return $"The weather in {city} is 25 {unit}, sunny.";
    }

    [Function]
    public async Task<string> GetForecast(string city, int days = 3)
    {
   
        await Task.Delay(100);
        return $"The {days}-day forecast for {city}: Sunny, Cloudy, Rainy";
    }
}

// 2. 在 Agent 中注册函数
var weatherFunctions = new WeatherFunctions();

var agent = new OpenAIChatAgent(
    chatClient: gpt4oMini,
    name: "assistant",
    systemMessage: "You are a helpful assistant that can get weather information."
)
.RegisterMessageConnector()
.RegisterMiddleware(async (msgs, opts, agent, ct) =>
{
   
    var functionCallMiddleware = new FunctionCallMiddleware(
        functions: [weatherFunctions.GetWeatherFunctionContract, weatherFunctions.GetForecastFunctionContract],
        functionMap: new Dictionary<string, Func<string, Task<string>>>
        {
   
            [weatherFunctions.GetWeatherFunctionContract.Name!] = weatherFunctions.GetWeatherWrapper,
            [weatherFunctions.GetForecastFunctionContract.Name!] = weatherFunctions.GetForecastWrapper
        }
    );
    return await functionCallMiddleware.InvokeAsync(new MiddlewareContext(msgs, opts), agent, ct);
})
.RegisterPrintMessage();

// 3. 测试函数调用
var reply = await agent.SendAsync("What's the weather in Beijing?");
// Agent 会自动调用 GetWeather 函数并返回结果

Week 2：深入群聊机制

任务 3：创建一个三人项目团队群聊

// 定义三个角色
var productManager = new OpenAIChatAgent(
    chatClient: gpt4oMini,
    name: "PM",
    systemMessage: "你是产品经理，负责定义需求和验收标准"
);

var developer = new OpenAIChatAgent(
    chatClient: gpt4oMini,
    name: "Dev",
    systemMessage: "你是开发工程师，负责技术方案设计和实现"
);

var tester = new OpenAIChatAgent(
    chatClient: gpt4oMini,
    name: "QA",
    systemMessage: "你是测试工程师，负责质量保证和bug发现"
);

// 创建群聊
var groupChat = new GroupChat(
    members: [productManager, developer, tester],
    admin: productManager  // PM 作为管理员
);

// 自定义发言顺序：PM -> Dev -> QA -> PM（循环）
var roundRobinOrchestrator = new RoundRobinGroupChat();

// 开始讨论
var chatHistory = await productManager.InitiateGroupChatAsync(
    members: [productManager, developer, tester],
    initialMessage: "我们需要开发一个用户登录功能，大家讨论一下方案",
    maxRound: 10,
    orchestrator: roundRobinOrchestrator
);

任务 4：实现动态发言者选择

// 创建自定义的 Orchestrator，让 AI 决定下一个发言者
public class AIPickOrchestrator : IOrchestrator
{
   
    private readonly IAgent _selectorAgent;

    public AIPickOrchestrator(IAgent selectorAgent)
    {
   
        _selectorAgent = selectorAgent;
    }

    public async Task<IAgent?> GetNextSpeakerAsync(
        OrchestrationContext context,
        CancellationToken cancellationToken = default)
    {
   
        // 让 AI 分析对话历史，选择下一个发言者
        var prompt = $@"根据以下对话历史，选择下一个最合适的发言者。
可选发言者：{string.Join(", ", context.Candidates.Select(a => a.Name))}

对话历史：
{
   string.Join("\n", context.ChatHistory.TakeLast(5).Select(m => $"{m.From}: {m.GetContent()}"))}

请只返回发言者的名字，不要有其他内容。";

        var reply = await _selectorAgent.GenerateReplyAsync([new TextMessage(Role.User, prompt)]);
        var selectedName = reply.GetContent()?.Trim();

        return context.Candidates.FirstOrDefault(a => a.Name == selectedName);
    }
}

// 使用
var selector = new OpenAIChatAgent(
    chatClient: gpt4oMini,
    name: "selector",
    systemMessage: "你是一个会议主持人，负责选择下一个发言者"
);

var orchestrator = new AIPickOrchestrator(selector);

学习成果验证：

✅ 能创建自定义中间件
✅ 能使用 Source Generator 生成函数定义
✅ 能配置群聊并自定义发言顺序
✅ 能实现自定义的 Orchestrator

🌲 阶段四：架构理解和贡献指南（2 周+）

目标： 能理解技术选型原因，并尝试修复一个简单 issue。

Week 1-2：深入新版架构

任务 1：理解事件驱动模型

# 1. 运行 GettingStarted 示例（不依赖 Aspire）
cd samples/GettingStarted
dotnet run

# 2. 阅读关键文件
code Modifier.cs  # 看 IHandle<CountMessage>
code Checker.cs   # 看 IHandle<CountUpdate>
code Program.cs   # 看消息发布

理解关键概念：

IHandle<T>：定义 Agent 如何处理特定类型的消息
TopicId：消息发布的"频道"，类似消息队列的 Topic
PublishMessageAsync：发布消息（异步、无返回值）
SendMessageAsync：发送消息（同步、等待回复）

任务 2：创建自己的事件驱动 Agent

// 定义消息类型
public record TaskAssigned(string TaskId, string Description);
public record TaskCompleted(string TaskId, string Result);

// 定义 Worker Agent
[TypeSubscription("WorkTopic")]
public class WorkerAgent : BaseAgent,
    IHandle<TaskAssigned>,
    IHandle<Shutdown>
{
   
    public WorkerAgent(AgentId id, IAgentRuntime runtime)
        : base(id, runtime, "Worker", null)
    {
   
    }

    public async ValueTask HandleAsync(TaskAssigned item, MessageContext ctx)
    {
   
        Console.WriteLine($"Received task: {item.TaskId} - {item.Description}");

        // 模拟工作
        await Task.Delay(2000);

        // 发布完成事件
        await this.PublishMessageAsync(
            new TaskCompleted(item.TaskId, "Successfully completed"),
            new TopicId("ResultTopic")
        );
    }

    public async ValueTask HandleAsync(Shutdown item, MessageContext ctx)
    {
   
        Console.WriteLine("Shutting down worker...");
    }
}

// 定义 Supervisor Agent
[TypeSubscription("ResultTopic")]
public class SupervisorAgent : BaseAgent,
    IHandle<TaskCompleted>
{
   
    private int _completedTasks = 0;

    public SupervisorAgent(AgentId id, IAgentRuntime runtime, IHostApplicationLifetime lifetime)
        : base(id, runtime, "Supervisor", null)
    {
   
        _lifetime = lifetime;
    }

    public async ValueTask HandleAsync(TaskCompleted item, MessageContext ctx)
    {
   
        Console.WriteLine($"Task {item.TaskId} completed: {item.Result}");
        _completedTasks++;

        if (_completedTasks >= 3)
        {
   
            Console.WriteLine("All tasks completed!");
            await this.PublishMessageAsync(new Shutdown(), new TopicId("WorkTopic"));
            _lifetime.StopApplication();
        }
    }
}

// 主程序
var appBuilder = new AgentsAppBuilder();
appBuilder.UseInProcessRuntime();

appBuilder.AddAgent<WorkerAgent>("Worker");
appBuilder.AddAgent<SupervisorAgent>("Supervisor");

var app = await appBuilder.BuildAsync();
await app.StartAsync();

// 发布任务
await app.PublishMessageAsync(
    new TaskAssigned("T1", "Process data"),
    new TopicId("WorkTopic")
);
await app.PublishMessageAsync(
    new TaskAssigned("T2", "Generate report"),
    new TopicId("WorkTopic")
);
await app.PublishMessageAsync(
    new TaskAssigned("T3", "Send email"),
    new TopicId("WorkTopic")
);

await app.WaitForShutdownAsync();

Week 3-4：阅读源码并贡献

任务 3：深入源码阅读

建议阅读顺序：

1. src/Microsoft.AutoGen/Contracts/IAgentRuntime.cs
   ↓ 理解 Runtime 的职责
2. src/Microsoft.AutoGen/Core/InProcessRuntime.cs
   ↓ 理解内存运行时的实现
3. src/Microsoft.AutoGen/Core/BaseAgent.cs
   ↓ 理解 Agent 基类的反射机制
4. src/Microsoft.AutoGen/Core.Grpc/
   ↓ 理解分布式通信的序列化
5. test/Microsoft.AutoGen.Core.Tests/AgentTests.cs
   ↓ 通过测试理解使用场景

任务 4：尝试修复 Issue

# 1. 在 GitHub 上找一个 "good first issue"
# https://github.com/microsoft/autogen/labels/good%20first%20issue

# 2. Fork 项目并克隆
git clone https://github.com/YOUR_USERNAME/autogen.git
cd autogen/dotnet

# 3. 创建新分支
git checkout -b fix-issue-1234

# 4. 运行测试确保现有功能正常
dotnet test

# 5. 修改代码并添加测试

# 6. 提交 Pull Request

学习成果验证：

✅ 能解释事件驱动和 Actor 模型的区别
✅ 能从零创建基于新架构的 Agent 系统
✅ 能理解 Orleans 在 AutoGen 中的作用
✅ 能为 Agent 编写单元测试（使用 xUnit + Moq）
✅ 能阅读源码并找到潜在的改进点

📈 3. 学习路径流程图

graph TD
    A[开始学习 AutoGen .NET] --> B{选择架构}
    B -->|初学者推荐| C[旧版 AutoGen.*]
    B -->|进阶/生产环境| D[新版 Microsoft.AutoGen.*]

    C --> C1[阶段1: 环境搭建<br/>1-2天]
    C1 --> C2[阶段2: 双代理对话<br/>3-5天]
    C2 --> C3[阶段3: 函数调用+群聊<br/>1-2周]
    C3 --> C4{需要分布式?}
    C4 -->|是| D1
    C4 -->|否| E[完成学习]

    D --> D1[学习 Orleans 基础<br/>1-2天]
    D1 --> D2[阶段1: Hello 示例<br/>1-2天]
    D2 --> D3[阶段2: 事件驱动模型<br/>3-5天]
    D3 --> D4[阶段3: Aspire 工具链<br/>1周]
    D4 --> D5[阶段4: 源码阅读+贡献<br/>2周+]
    D5 --> E

    E --> F{继续深入?}
    F -->|是| G[选择专项]
    F -->|否| H[开始实践项目]

    G --> G1[专项A: RAG + 向量数据库]
    G --> G2[专项B: 跨语言集成 gRPC]
    G --> G3[专项C: 生产化部署]
    G --> G4[专项D: 贡献开源]

    G1 --> H
    G2 --> H
    G3 --> H
    G4 --> H

    style C fill:#e1f5ff
    style D fill:#fff4e1
    style E fill:#d4edda
    style H fill:#d4edda

💡 第四部分：实践建议和进阶指导（从会用到精通）

本部分目标： 提供实战经验、避坑指南和进阶练习，帮助你从"能跑示例"到"能上生产"。

🐛 1. 调试技巧和常见陷阱

🔍 调试技巧

技巧 1：使用 RegisterPrintMessage 观察消息流

var agent = new OpenAIChatAgent(...)
    .RegisterMessageConnector()
    .RegisterPrintMessage();  // 👈 自动打印每条消息

// 输出示例：
// Message from user
// --------------------
// content: Hello
// --------------------

技巧 2：使用 Aspire Dashboard 观察分布式追踪

# 运行 Aspire 示例
cd samples/Hello/Hello.AppHost
dotnet run

# 打开 http://localhost:15201
# 点击 "Traces" 查看请求链路
# 点击 "Logs" 查看结构化日志

技巧 3：Mock LLM 响应进行单元测试

[Fact]
public async Task Agent_Should_Filter_Sensitive_Words()
{
   
    // Arrange
    var mockAgent = new Mock<IAgent>();
    mockAgent.Setup(a => a.GenerateReplyAsync(It.IsAny<IEnumerable<IMessage>>(), null, default))
             .ReturnsAsync(new TextMessage(Role.Assistant, "Your password is 12345"));

    var filterMiddleware = new SensitiveWordFilterMiddleware();

    // Act
    var reply = await filterMiddleware.ProcessAsync([], null, mockAgent.Object, default);

    // Assert
    reply.GetContent().Should().Be("Your *** is 12345");
}

⚠️ 常见陷阱（基于社区反馈）

陷阱 1：忘记注册 MessageConnector 导致类型转换失败

// ❌ 错误示例
var agent = new OpenAIChatAgent(...)
    // .RegisterMessageConnector()  // 忘记注册
    .RegisterPrintMessage();

var reply = await agent.SendAsync("Hello");
// 报错：Cannot convert IMessage to ChatRequestMessage

解决方案：

// ✅ 正确示例
var agent = new OpenAIChatAgent(...)
    .RegisterMessageConnector()  // 必须先注册
    .RegisterPrintMessage();

陷阱 2：Function Calling 的函数签名不匹配

// ❌ 错误：返回类型不是 Task<T>
[Function]
public string GetWeather(string city)  // 同步方法
{
   
    return "Sunny";
}

// ❌ 错误：参数没有默认值
[Function]
public async Task<string> GetWeather(string city, string unit)  // unit 没有默认值
{
   
    return $"25 {unit}";
}

解决方案：

// ✅ 正确
[Function]
public async Task<string> GetWeather(string city, string unit = "celsius")
{
   
    return $"25 {unit}";
}

陷阱 3：群聊中未正确终止导致死循环

// ❌ 错误：没有设置终止条件
var conversation = await agent.InitiateChatAsync(
    receiver: teacher,
    message: "Start",
    maxRound: int.MaxValue  // 危险！
);

解决方案：

// ✅ 正确：设置合理的 maxRound 或终止中间件
var agent = new OpenAIChatAgent(...)
    .RegisterMiddleware(async (msgs, opts, agent, ct) =>
    {
   
        var reply = await agent.GenerateReplyAsync(msgs, opts, ct);
        if (reply.GetContent()?.Contains("[DONE]") == true)
        {
   
            return new TextMessage(Role.Assistant, GroupChatExtension.TERMINATE);
        }
        return reply;
    });

陷阱 4：Orleans Agent 状态未持久化

// ⚠️ 问题：InProcessRuntime 重启后状态丢失

// 解决方案：配置状态持久化
var appBuilder = new AgentsAppBuilder();
appBuilder.UseInProcessRuntime();

// TODO: 当前版本 API 尚不稳定，查看最新文档了解状态持久化配置

陷阱 5：API 超时和重试

// ⚠️ OpenAI API 可能因网络问题超时

// 解决方案：配置重试策略（需要自定义 HttpClient）
var httpClient = new HttpClient(new SocketsHttpHandler
{
   
    PooledConnectionLifetime = TimeSpan.FromMinutes(2),
    ConnectTimeout = TimeSpan.FromSeconds(30)
});

// 使用 Polly 添加重试策略
// 详见 Microsoft.Extensions.Http.Resilience

🎯 2. 扩展练习建议

🌱 初级练习（完成 1-2 个）

练习 1：角色扮演对话

任务：创建一个 "侦探 vs 嫌疑人" 的审讯对话
要求：
- 侦探负责提问，收集线索
- 嫌疑人有时说实话，有时撒谎
- 对话 5 轮后，侦探给出结论

练习 2：翻译接力

任务：创建一个多语言翻译链
要求：
- Agent1: 中文 -> 英文
- Agent2: 英文 -> 日文
- Agent3: 日文 -> 韩文
- 比较原文和最终翻译的差异

🌿 中级练习（完成 2-3 个）

练习 3：智能客服系统

任务：创建一个三级客服系统
要求：
- L1 Agent: 处理常见问题（用规则引擎）
- L2 Agent: 处理复杂问题（调用 LLM）
- L3 Agent: 人工客服（模拟）
- 实现自动升级机制

练习 4：代码审查助手

任务：创建一个代码审查群聊
要求：
- 架构师 Agent: 检查设计
- 安全专家 Agent: 检查漏洞
- 性能专家 Agent: 检查性能
- 生成审查报告（Markdown 格式）

练习 5：文档问答（RAG）

任务：基于项目文档创建问答系统
要求：
- 使用 Embedding 将文档向量化
- 实现相似度搜索
- Agent 基于检索的文档回答问题
提示：可以使用 Semantic Kernel 的 Memory 插件

🌳 高级练习（选择 1 个深入）

练习 6：分布式任务编排

任务：使用新版架构创建分布式工作流
要求：
- 使用 Orleans 部署到多个 Silo
- 实现任务的并行执行
- 实现失败重试和补偿机制
- 集成 Aspire 的可观测性

练习 7：跨语言 Agent 通信

任务：让 .NET Agent 和 Python Agent 协同工作
要求：
- 定义 .proto 文件
- 实现 gRPC 服务端和客户端
- 实现双向消息传递
- 处理序列化和错误

练习 8：生产级聊天机器人

任务：构建可部署的聊天机器人
要求：
- 集成 ASP.NET Core Web API
- 实现会话管理和历史记录
- 添加用户认证和授权
- 实现 Rate Limiting
- 集成 Application Insights
- Docker 容器化

🤝 3. 参与贡献的途径

📍 社区位置

平台	链接	用途
GitHub Repository	microsoft/autogen	主仓库、Issue、PR
GitHub Discussions	Discussions	问答、讨论、分享
Discord	AutoGen Discord	实时交流
官方文档	AutoGen Docs	文档网站

🔍 如何寻找 Good First Issue

# 1. 访问 GitHub Issues
https://github.com/microsoft/autogen/issues

# 2. 筛选标签
Labels: "good first issue" + "dotnet"

# 3. 常见的 Good First Issue 类型
- 📝 文档补充或修正
- 🧪 添加单元测试覆盖
- 🐛 修复小 bug
- ✨ 添加示例代码
- 🌐 多语言支持

📋 代码规范要求

根据 Directory.Build.props 和 .editorconfig：

// ✅ 使用 Nullable Reference Types
#nullable enable

// ✅ 使用 File-scoped Namespace
namespace AutoGen.Core;

// ✅ 异步方法命名以 Async 结尾
public async Task<IMessage> GenerateReplyAsync(...)

// ✅ 接口以 I 开头
public interface IAgent {
    }

// ✅ 所有公共 API 需要 XML 文档注释
/// <summary>
/// Generates a reply based on the conversation history.
/// </summary>
/// <param name="messages">The conversation history.</param>
/// <returns>A task representing the generated reply.</returns>
public Task<IMessage> GenerateReplyAsync(IEnumerable<IMessage> messages);

// ✅ 使用 var 进行类型推断（明确时）
var agent = new OpenAIChatAgent(...);

// ✅ 私有字段以 _ 开头
private readonly ILogger _logger;

🚀 提交流程

# 1. Fork 并克隆
git clone https://github.com/YOUR_USERNAME/autogen.git
cd autogen/dotnet

# 2. 创建分支（使用描述性名称）
git checkout -b feature/add-retry-middleware

# 3. 开发并运行测试
dotnet test

# 4. 提交（使用 Conventional Commits 格式）
git commit -m "feat(middleware): add retry middleware for OpenAI API"
git commit -m "docs: update middleware documentation"
git commit -m "fix: correct typo in IAgent.cs"

# 5. 推送并创建 PR
git push origin feature/add-retry-middleware

# 6. 在 PR 描述中包含
- 🎯 解决的问题（链接 Issue）
- 🔧 实现方案简述
- ✅ 测试覆盖情况
- 📚 文档更新（如有）

PR 示例模板：

## Description
Add a retry middleware for handling transient failures when calling OpenAI API.

## Related Issue
Fixes #1234

## Changes
- Added `RetryMiddleware.cs` with exponential backoff
- Added unit tests in `RetryMiddlewareTests.cs`
- Updated `Middleware-overview.md` documentation

## Testing
- [x] All existing tests pass
- [x] Added new unit tests with 95% coverage
- [x] Manually tested with flaky network

## Checklist
- [x] Code follows the project's coding standards
- [x] Added XML documentation comments
- [x] Updated relevant documentation
- [x] No breaking changes

🌐 第五部分：技术栈学习指引（你的知识地图）

本部分目标： 为你识别出的关键技能提供高质量学习资源，构建完整的知识支持体系。

1. 官方文档定位（学习的基石）

📘 核心技术栈文档

技术栈	官方文档	重点章节	预计学习时间
.NET 9	docs.microsoft.com/dotnet	C# 9-12 新特性、Async/Await	3-5 天
Orleans	learn.microsoft.com/orleans	Grains、Persistence、Reminders	2-3 天
.NET Aspire	learn.microsoft.com/aspire	Service Discovery、Observability	1-2 天
gRPC	grpc.io/docs/languages/csharp	Protocol Buffers、Service Definition	1 天
OpenAI API	platform.openai.com/docs	Chat Completions、Function Calling	2-3 天

📗 项目自身文档

必读章节（按优先级）：

入门级（2-3 小时）
- README.md - 项目概览
- website/articles/Installation.md - 安装指南
- website/articles/getting-start.md - 快速开始
- samples/Hello/README.md - 新版架构入门
理解核心概念（1 天）
- website/articles/Agent-overview.md - Agent 概念
- website/articles/Built-in-messages.md - 消息类型
- website/articles/Middleware-overview.md - 中间件机制
- website/articles/Group-chat-overview.md - 群聊机制
实践进阶（2-3 天）
- website/articles/Function-call-overview.md - 函数调用
- website/articles/Create-type-safe-function-call.md - Source Generator
- website/articles/AutoGen.SemanticKernel/AutoGen-SemanticKernel-Overview.md - SK 集成
深入架构（1 周）
- 阅读 src/ 目录下的代码注释
- 阅读单元测试了解使用场景
- 查看 samples/dev-team/ 复杂示例

📕 权威技术书籍

书名	作者	适用阶段	推荐理由
C# 12 in a Nutshell	Joseph Albahari	基础	C# 语言权威参考
Concurrency in C# Cookbook	Stephen Cleary	进阶	Async/Await 最佳实践
Building Microservices with ASP.NET Core	Kevin Hoffman	进阶	微服务和 gRPC
Designing Data-Intensive Applications	Martin Kleppmann	高级	分布式系统设计
Prompt Engineering Guide	DAIR.AI	AI	提示词工程实战

2. 学习路径建议（社区智慧）

📚 技能学习顺序

路径 A：后端开发者快速上手（总计 2-3 周）

Week 1: C# 现代特性复习 + .NET 9 基础 + AutoGen 旧版
Week 2: Orleans 基础 + 事件驱动架构 + AutoGen 新版
Week 3: Prompt Engineering + Function Calling + 实战项目

路径 B：AI 工程师转 .NET（总计 3-4 周）

Week 1: C# 基础 + .NET SDK + 开发环境
Week 2: AutoGen 旧版 + 示例代码 + 双代理对话
Week 3: 群聊机制 + 函数调用 + Semantic Kernel
Week 4: RAG 实践 + 向量数据库 + 生产化部署

路径 C：全栈开发者构建应用（总计 4-5 周）

Week 1-2: AutoGen 基础（旧版+新版）
Week 3: ASP.NET Core + AutoGen WebAPI
Week 4: 前端集成（React/Vue + SignalR）
Week 5: Docker 部署 + 监控告警

🎯 核心概念优先级

🔴 必须掌握（基础）：

Agent 和 IMessage 接口
中间件（Middleware）机制
Async/Await 异步编程
Prompt Engineering 基础

🟡 建议掌握（进阶）：

GroupChat 和 Orchestrator
Function Calling / Tool Use
Orleans Grain 概念
依赖注入（DI）模式

🟢 可选掌握（专家）：

gRPC 和 Protobuf
Orleans 分布式集群
向量数据库和 RAG
OpenTelemetry 可观测性

💼 实践项目推荐

项目类型	难度	学习收获	参考示例
聊天机器人	⭐	双代理对话、消息流	`Example02_TwoAgent_MathChat`
智能客服	⭐⭐	群聊、函数调用	`Example04_Dynamic_GroupChat`
文档问答	⭐⭐⭐	RAG、Embedding	Semantic Kernel Memory
代码生成	⭐⭐⭐	复杂 Prompt、多轮对话	`samples/dev-team`
分布式系统	⭐⭐⭐⭐	Orleans、gRPC	`samples/Hello` (Aspire)

3. 工具与环境配置指南

🛠️ 开发环境搭建

推荐配置（Windows）：

# 1. 安装 Visual Studio 2022
# 选择工作负载：
# - .NET 桌面开发
# - ASP.NET 和 Web 开发
# - Azure 开发

# 2. 安装 .NET 9 SDK
winget install Microsoft.DotNet.SDK.9

# 3. 安装 Git
winget install Git.Git

# 4. 安装 Docker Desktop（可选）
winget install Docker.DockerDesktop

# 5. 安装 Ollama（可选）
# 下载: https://ollama.com/download

# 6. 配置 PowerShell 环境变量
[System.Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'sk-xxx', 'User')

推荐配置（Linux/Mac）：

# 1. 安装 .NET 9 SDK
wget https://dot.net/v1/dotnet-install.sh
bash dotnet-install.sh --version 9.0.100

# 2. 安装 VS Code
# 下载: https://code.visualstudio.com/

# 3. 安装 C# Dev Kit 扩展
code --install-extension ms-dotnettools.csdevkit

# 4. 配置环境变量
echo 'export OPENAI_API_KEY="sk-xxx"' >> ~/.bashrc
source ~/.bashrc

🔧 常用工具使用

Git 基础操作：

# 克隆项目
git clone https://github.com/microsoft/autogen.git

# 查看分支
git branch -a

# 切换到最新稳定分支
git checkout main

# 更新代码
git pull origin main

# 查看修改
git status
git diff

dotnet CLI 常用命令：

# 还原依赖
dotnet restore

# 编译项目
dotnet build

# 运行项目
dotnet run

# 运行测试
dotnet test

# 清理输出
dotnet clean

# 添加包引用
dotnet add package AutoGen.Core

# 查看项目信息
dotnet list package

Docker 基础操作：

# 构建镜像
docker build -t my-autogen-app .

# 运行容器
docker run -d -p 8080:8080 --name my-app my-autogen-app

# 查看日志
docker logs my-app

# 停止容器
docker stop my-app

# 删除容器
docker rm my-app

4. 进阶拓展方向

🌟 技术博客与专家观点

AutoGen 核心维护者：

Davor Runje (GitHub) - AutoGen 架构师
Chi Wang (GitHub) - AutoGen 创始人
关注 microsoft/autogen 的 Contributors

推荐技术博客：

.NET Blog - 微软官方博客
Orleans Blog - Orleans 官方博客
OpenAI Blog - OpenAI 最新动态
Anthropic Blog - Claude 技术文章

🎤 相关技术大会

大会名称	举办时间	关注方向	官网
.NET Conf	每年 11 月	.NET 最新技术	dotnetconf.net
Microsoft Build	每年 5 月	微软技术生态	build.microsoft.com
AI Engineer Summit	每年 10 月	AI 工程实践	ai.engineer
NeurIPS	每年 12 月	AI 学术前沿	neurips.cc

💬 社区与论坛

平台	用途	活跃度	链接
GitHub Discussions	问答、功能讨论	⭐⭐⭐⭐⭐	链接
Discord	实时交流、寻求帮助	⭐⭐⭐⭐	链接
Stack Overflow	技术问题	⭐⭐⭐	标签：`autogen` + `c#`
Reddit r/dotnet	.NET 社区讨论	⭐⭐⭐⭐	链接
Twitter/X	最新动态	⭐⭐⭐	关注 `#AutoGen` `#dotnet`

🔬 深入学习方向

方向 1：RAG（检索增强生成）

学习内容：
- 向量数据库（Qdrant, Milvus, Pinecone）
- Embedding 模型（OpenAI Ada-002, Sentence Transformers）
- 文档切分和索引策略
- Semantic Kernel Memory 插件

实践项目：
- 基于公司文档的智能问答系统
- 代码库搜索和推荐引擎

方向 2：多模态 AI（Vision + Text）

学习内容：
- GPT-4 Vision API
- 图像理解和描述
- OCR 和文档解析（PdfPig）
- 多模态 Prompt 设计

实践项目：
- 图片问答系统
- 文档智能处理（发票、合同）

方向 3：分布式 Agent 系统

学习内容：
- Orleans 集群部署
- gRPC 跨语言通信
- 消息队列（Azure Service Bus, RabbitMQ）
- 分布式追踪（OpenTelemetry）

实践项目：
- 大规模并发的客服系统
- 跨语言的 Agent 协作平台

方向 4：AI 安全和可靠性

学习内容：
- Prompt Injection 防护
- 内容安全过滤
- Rate Limiting 和成本控制
- 错误处理和重试策略

实践项目：
- 企业级 AI 网关
- 敏感信息脱敏系统

🎓 结语

恭喜你读到这里！🎉

这份指南就像一张藏宝图，标注了 AutoGen for .NET 的核心知识点和学习路径。但记住，真正的学习发生在实践中。

你的下一步行动清单 ✅

⬇️ 安装 .NET 9 SDK（如果还没装）
📥 克隆项目并运行第一个示例
🎯 选择一个学习路径（初学者/有经验/进阶）
💻 完成至少一个扩展练习
🤝 加入社区（Discord 或 GitHub Discussions）
🚀 构建你的第一个 Agent 应用

学习建议 💡

不要追求完美：先让代码跑起来，再慢慢优化
多读源码：AutoGen 的代码质量很高，是学习 C# 最佳实践的好材料
勤做笔记：记录你的踩坑经历和解决方案
积极提问：社区非常友好，不要害怕问"愚蠢"的问题
保持好奇：AI 技术日新月异，保持学习的热情

持续更新 🔄

这份指南基于 2025年10月 的项目状态编写。AutoGen for .NET 正在快速发展，建议：

📌 关注项目的 Release Notes
📌 订阅 .NET Blog 的 AutoGen 相关文章
📌 定期查看 samples/ 目录的新增示例

反馈与改进 📬

如果你发现指南中的错误或有改进建议，欢迎：

在 GitHub 上提 Issue
在 Discord 上分享你的学习心得
为项目贡献文档改进

祝你学习愉快，早日成为 AutoGen for .NET 的专家！
Let's build amazing AI agents together! 🤖✨

AutoGen for .NET - 架构学习指南

AutoGen for .NET - 架构学习指南

🔍 第一部分：项目架构深度解析（像架构师一样俯瞰全景）

🌟 1. 项目架构概览

📖 用通俗的类比理解 AutoGen

🎯 核心设计特征

🏗️ 同类项目设计类比

🛠️ 技术栈分析

🌐 外部系统集成

🎬 架构流程描述

📂 2. 目录结构与核心流程

🗂️ 目录组织逻辑

🔑 关键文件定位

🔗 模块依赖关系

🎭 典型业务流程：双代理数学教学对话（旧版）

💻 3. 代码结构观察

🏗️ 代码组织模式

🎨 设计模式识别

📊 代码质量观察

📚 第二部分：技能需求清单（你的学习弹药库）

1. 基础技能要求

🎯 必备技能（没有这些，寸步难行）

🧪 LLM 和 AI 相关知识

2. 进阶技能要求

🏗️ 架构模式和设计原则

🔧 Orleans 虚拟 Actor 框架（新版架构必需）

🌐 gRPC 和 Protobuf（跨语言集成需要）

🧪 测试驱动开发（TDD）

3. 技能掌握程度建议

🌱 初学者路线（2-4 周）

🚀 有经验的开发者路线（1-2 周）

🎯 意欲贡献代码的进阶者路线（3-4 周）

🎯 第三部分：学习路径规划（你的专属教练计划）

💻 1. 项目运行入口定位（快速上手）

🚀 一键启动指南

⚙️ 环境配置清单

🚨 最常见的配置陷阱及其解决方案

✅ 验证成功标志

📅 2. 循序渐进学习计划（四阶段法）

🌱 阶段一：环境搭建和项目启动（1-2 天）

🌿 阶段二：核心流程理解（3-5 天）

🌳 阶段三：模块深入和定制开发（1-2 周）

🌲 阶段四：架构理解和贡献指南（2 周+）

📈 3. 学习路径流程图

💡 第四部分：实践建议和进阶指导（从会用到精通）

🐛 1. 调试技巧和常见陷阱

🔍 调试技巧

⚠️ 常见陷阱（基于社区反馈）

🎯 2. 扩展练习建议

🌱 初级练习（完成 1-2 个）

🌿 中级练习（完成 2-3 个）

🌳 高级练习（选择 1 个深入）

🤝 3. 参与贡献的途径

📍 社区位置

🔍 如何寻找 Good First Issue

📋 代码规范要求

🚀 提交流程

🌐 第五部分：技术栈学习指引（你的知识地图）

1. 官方文档定位（学习的基石）

📘 核心技术栈文档

📗 项目自身文档

📕 权威技术书籍

2. 学习路径建议（社区智慧）

📚 技能学习顺序

🎯 核心概念优先级

💼 实践项目推荐

3. 工具与环境配置指南

🛠️ 开发环境搭建

🔧 常用工具使用

4. 进阶拓展方向

🌟 技术博客与专家观点

🎤 相关技术大会

💬 社区与论坛

🔬 深入学习方向

🎓 结语

你的下一步行动清单 ✅

学习建议 💡

持续更新 🔄

反馈与改进 📬

通义大模型