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)