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

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

MAF1.Core/Tools/WeatherTools.cs

@@ -4,6 +4,10 @@ using System.Text.Json;
 
 namespace MAF1.Tools;
 
+/// <summary>
+/// 天气 HTTP 实现。Agent 通过 GetWeather 间接调用这里，而不是自己拼 URL。
+/// Provider=Wttr 免费无需 Key；OpenWeather 需要 ApiKey。
+/// </summary>
 public sealed class WeatherTools(WeatherOptions options, HttpClient http)
 {
     [Description("Look up live weather for a city or location. Always call this instead of guessing.")]
@@ -82,6 +86,7 @@ public sealed class WeatherTools(WeatherOptions options, HttpClient http)
             : $"{name}：{description}，气温 {temp:0.#}°C，湿度 {humidity}%";
     }
 
+    /// <summary>把 appsettings 里的 URL 模板换成真实地址。城市名要做 Uri.EscapeDataString。</summary>
     private string Expand(string template, string location, string? apiKey)
     {
         return template
@@ -90,6 +95,7 @@ public sealed class WeatherTools(WeatherOptions options, HttpClient http)
             .Replace("{apiKey}", apiKey ?? "", StringComparison.OrdinalIgnoreCase);
     }
 
+    /// <summary>带超时和 User-Agent。部分天气站点会拒绝没有 UA 的请求。</summary>
     public static HttpClient CreateHttpClient()
     {
         HttpClient http = new() { Timeout = TimeSpan.FromSeconds(20) };