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

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

MAF1.Core/Decisions/DecisionModels.cs

@@ -2,6 +2,10 @@ using MAF1.Agents;
 
 namespace MAF1.Decisions;
 
+/// <summary>
+/// 工作流暂停时发给人或 UI 的确认请求。必须带 DefaultOptionId，超时就采用它。
+/// CLI 和 Web 共用这一套，避免两套文案分叉。
+/// </summary>
 public sealed class DecisionRequest
 {
     public string Id { get; set; } = "";
@@ -14,6 +18,7 @@ public sealed class DecisionRequest
     public DateTimeOffset Deadline { get; set; }
 }
 
+/// <summary>一个可选项。RequiresText=true 时前端会显示输入框（例如改填城市）。</summary>
 public sealed class DecisionOption
 {
     public string Id { get; set; } = "";
@@ -24,6 +29,7 @@ public sealed class DecisionOption
     public bool IsDefault { get; set; }
 }
 
+/// <summary>人的选择或超时结果。TimedOut=true 时一律按默认方案处理，忽略 Text。</summary>
 public sealed class DecisionAnswer
 {
     public string OptionId { get; set; } = "";
@@ -31,12 +37,14 @@ public sealed class DecisionAnswer
     public bool TimedOut { get; set; }
 }
 
+/// <summary>缺城市场景下的两个方案 id，前后端都硬编码这两个字符串。</summary>
 public static class DecisionOptionIds
 {
     public const string Stop = "stop";
     public const string QueryCities = "query-cities";
 }
 
+/// <summary>工厂：生成「没有读到城市」这一类确认。网页 runner 和 CLI executor 都调用 Create。</summary>
 public static class EmptyCityDecision
 {
     public static DecisionRequest Create(string nodeId, string? reason, int timeoutSeconds)
@@ -72,6 +80,7 @@ public static class EmptyCityDecision
         };
     }
 
+    /// <summary>用户选「改查其它城市」且解析出至少一个城市名时返回 true。</summary>
     public static bool TryContinueWithCities(DecisionAnswer answer, out List<string> cities)
     {
         cities = [];