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

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

MAF1.Web/Program.cs

@@ -1,3 +1,5 @@
+// 网页入口：Minimal API + wwwroot 静态文件。浏览器只调 REST，不接触 API Key。
+// 学习顺序建议：/api/catalog → 画布 → POST /api/run → 若 needsDecision 再 POST /api/run/{id}/decide。
 using MAF1.Decisions;
 using MAF1.Utils;
 using MAF1.Web;
@@ -16,6 +18,7 @@ WebApplication app = builder.Build();
 app.UseDefaultFiles();
 app.UseStaticFiles();
 
+// 左侧节点列表：系统内置 + 扫描到的插件。
 app.MapGet("/api/catalog", (AgentRuntime runtime) =>
 {
     var snapshot = runtime.Catalog.Load();
@@ -28,14 +31,17 @@ app.MapGet("/api/catalog", (AgentRuntime runtime) =>
         issues = snapshot.Issues,
     };
 });
+// 给下拉框用的凭据列表（不含原始 Key）。
 app.MapGet("/api/credentials", (AgentRuntime runtime) => runtime.Credentials.ListPublic());
 app.MapGet("/api/status", (AgentRuntime runtime) => new
 {
     weatherProvider = runtime.WeatherProvider,
     pluginsRoot = runtime.PluginsRoot,
 });
+// 提交画布 JSON。可能一次跑完，也可能返回 status=needsDecision。
 app.MapPost("/api/run", (WorkflowGraph graph, AgentRuntime runtime, CancellationToken cancellationToken)
     => runtime.Runner.RunAsync(graph, cancellationToken));
+// 超时后前端轮询最终结果。
 app.MapGet("/api/run/{runId}", (string runId, AgentRuntime runtime) =>
 {
     WorkflowRunResult? result = runtime.Runner.Get(runId);
@@ -43,6 +49,7 @@ app.MapGet("/api/run/{runId}", (string runId, AgentRuntime runtime) =>
         ? Results.NotFound(new WorkflowRunResult { Ok = false, Status = WorkflowRunStatus.Failed, Error = "找不到这次运行。" })
         : Results.Ok(result);
 });
+// 用户点确认：optionId=stop 或 query-cities（可带 text 城市名）。
 app.MapPost("/api/run/{runId}/decide", (string runId, DecisionAnswer answer, AgentRuntime runtime, CancellationToken cancellationToken)
     => runtime.Runner.DecideAsync(runId, answer, cancellationToken));