docs: 为 CLI、网页编排器和插件协议补充学习向注释

在核心类型、图执行器、stdio 插件和前端入口写清职责与对照路径，不改运行行为。

MAF1.Core/Utils/AgentFactory.cs

@@ -8,6 +8,10 @@ using OpenAI.Chat;
 
 namespace MAF1.Utils;
 
+/// <summary>
+/// 创建聊天 Agent 的工厂。根据 Endpoint 判断走 Azure OpenAI 还是 OpenAI 兼容接口（DeepSeek 等）。
+/// 密钥优先级：appsettings Llm → 环境变量。浏览器永远拿不到 Key。
+/// </summary>
 public sealed class AgentFactory
 {
     private readonly ChatClient _chatClient;
@@ -48,11 +52,13 @@ public sealed class AgentFactory
             .GetChatClient(model);
     }
 
+    /// <summary>把 ChatClient 包成 Microsoft.Agents.AI 的 AIAgent，并挂上 tools。</summary>
     public AIAgent CreateAgent(string name, string instructions, IList<AITool>? tools = null)
     {
         return _chatClient.AsAIAgent(instructions: instructions, name: name, tools: tools);
     }
 
+    /// <summary>合并配置文件和环境变量。插件进程里环境变量通常由宿主写入。</summary>
     public static LlmOptions Load(IConfiguration config)
     {
         LlmOptions options = config.GetSection("Llm").Get<LlmOptions>() ?? new LlmOptions();
@@ -85,6 +91,7 @@ public sealed class AgentFactory
             || host.Contains("services.ai.azure.com", StringComparison.OrdinalIgnoreCase);
     }
 
+    /// <summary>OpenAI 兼容 API 要求 base URL 以 /v1 结尾，用户常只填到域名。</summary>
     private static Uri ToOpenAICompatibleEndpoint(string endpoint)
     {
         string trimmed = endpoint.TrimEnd('/');