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

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

MAF1.Core/Tools/FileTools.cs

@@ -3,6 +3,10 @@ using System.Text;
 
 namespace MAF1.Tools;
 
+/// <summary>
+/// 给 LLM 调用的本地读文件工具。Description 属性会进工具 schema，模型据此决定何时调用。
+/// 路径解析会试当前目录、exe 目录、以及 MAF1_CONTENT_ROOT（插件进程由宿主注入）。
+/// </summary>
 public static class FileTools
 {
     [Description("Read the full UTF-8 text of a local file. Always call this before judging city names.")]
@@ -28,6 +32,7 @@ public static class FileTools
         return File.ReadAllText(resolved, Encoding.UTF8);
     }
 
+    /// <summary>相对路径时依次试 cwd、exe 目录、内容根、再往上两级父目录（适配 bin/Debug/netX）。</summary>
     private static string? Resolve(string path)
     {
         if (Path.IsPathRooted(path) && File.Exists(path))

MAF1.Core/Tools/WeatherOptions.cs

@@ -1,5 +1,6 @@
 namespace MAF1.Tools;
 
+/// <summary>对应 appsettings.json 的 Weather 段。CLI 和 Web 各自有一份配置文件。</summary>
 public sealed class WeatherOptions
 {
     public string Provider { get; set; } = "Wttr";

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) };