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

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

MAF1.Core/Agents/FileCity/CityExtraction.cs

@@ -2,6 +2,9 @@ using System.Text.Json.Serialization;
 
 namespace MAF1.Agents.FileCity;
 
+/// <summary>
+/// FileCity Agent 约定输出的 JSON 形状。hasValidCities 会驱动边条件，也会触发「缺城市时等人确认」。
+/// </summary>
 public sealed class CityExtraction
 {
     [JsonPropertyName("hasValidCities")]

MAF1.Core/Agents/FileCity/FileCityAgent.cs

@@ -6,8 +6,13 @@ using Microsoft.Extensions.AI;
 
 namespace MAF1.Agents.FileCity;
 
+/// <summary>
+/// 「读文件抽城市」Agent。学习路径：Create 注册工具和系统提示 → RunAsync 调模型 → Parse 把模型文本收成结构化结果。
+/// CLI、网页系统节点、file-city 插件三处都调用同一套逻辑，避免各写一份 prompt。
+/// </summary>
 public static class FileCityAgent
 {
+    /// <summary>创建带 ReadTextFile 工具的聊天 Agent。模型必须先读文件，不能凭文件名猜内容。</summary>
     public static AIAgent Create(AgentFactory factory)
     {
         return factory.CreateAgent(
@@ -26,6 +31,7 @@ public static class FileCityAgent
             tools: [AIFunctionFactory.Create(FileTools.ReadTextFile)]);
     }
 
+    /// <summary>跑一轮：读 filePath 输入，把解析后的 cities / hasValidCities 放进 Outputs。</summary>
     public static async Task<AgentStepResult> RunAsync(
         AIAgent agent,
         IReadOnlyDictionary<string, object?> inputs,
@@ -50,6 +56,7 @@ public static class FileCityAgent
         };
     }
 
+    /// <summary>从模型原文里抠 JSON。模型偶尔会包 Markdown 代码块，所以先走 JsonText.UnwrapObject。</summary>
     public static CityExtraction Parse(string text)
     {
         try