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

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

MAF1.Core/Agents/AgentStepResult.cs

@@ -2,6 +2,10 @@ using System.Text.Json;
 
 namespace MAF1.Agents;
 
+/// <summary>
+/// 一次 Agent 执行的统一结果。网页编排器和进程外插件都用这套字段，方便画布把输出接到下一节点。
+/// Message 是给日志看的原文；Outputs 才是下游节点真正读取的端口数据。
+/// </summary>
 public sealed class AgentStepResult
 {
     public string Message { get; init; } = "";
@@ -9,8 +13,12 @@ public sealed class AgentStepResult
     public Dictionary<string, object?> Outputs { get; init; } = new(StringComparer.OrdinalIgnoreCase);
 }
 
+/// <summary>
+/// 从图 JSON / 插件 stdin 读入参。值可能是 string、数组，也可能是 System.Text.Json 反序列化后的 JsonElement。
+/// </summary>
 public static class AgentInputs
 {
+    /// <summary>按端口名读一个字符串；没有该键则返回 null。</summary>
     public static string? ReadString(IReadOnlyDictionary<string, object?> inputs, string key)
     {
         if (!inputs.TryGetValue(key, out object? value) || value is null)
@@ -26,6 +34,7 @@ public static class AgentInputs
         return value.ToString();
     }
 
+    /// <summary>读城市列表：支持 JSON 数组、["a","b"] 风格，或用顿号/逗号分隔的一串文字。</summary>
     public static List<string> ReadStringList(IReadOnlyDictionary<string, object?> inputs, string key)
     {
         if (!inputs.TryGetValue(key, out object? value) || value is null)

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

MAF1.Core/Agents/Weather/WeatherAgent.cs

@@ -5,8 +5,12 @@ using Microsoft.Extensions.AI;
 
 namespace MAF1.Agents.Weather;
 
+/// <summary>
+/// 「按城市查天气」Agent。真正的 HTTP 查询在 WeatherTools.GetWeather，模型只负责决定调几次工具并写成中文摘要。
+/// </summary>
 public static class WeatherAgent
 {
+    /// <summary>创建带 GetWeather 工具的 Agent。instructions 要求每个城市都调工具，禁止编造气温。</summary>
     public static AIAgent Create(AgentFactory factory, WeatherTools weatherTools)
     {
         return factory.CreateAgent(
@@ -19,6 +23,7 @@ public static class WeatherAgent
             tools: [AIFunctionFactory.Create(weatherTools.GetWeather)]);
     }
 
+    /// <summary>需要上游把 cities 连到本节点。空列表直接抛错，避免无意义地打 LLM。</summary>
     public static async Task<AgentStepResult> RunAsync(
         AIAgent agent,
         IReadOnlyDictionary<string, object?> inputs,