🧩 Refactor(Workflow): 控制流形态消歧+Models归位+表达式构建器收敛-代码组织重构阶段L14

Phase A - 低风险机械改动:
- BlockScriptServiceImpl -> BlockScriptService(消除唯一Impl后缀异常)
- BlueprintDebugger.cs -> Services/(运行时状态控制器,与RealPluginManager并列)
- BlueprintDebugContext内联进ControlFlowGraph(1字段DTO,DebugStatementToNodeId)
- 删除BlueprintToBlockScriptConverter死字段_cfg2bs
- 修复3处过时文档(BlockScriptSerializer/PipelineContext/ControlFlowMapping)

Phase B - CFGStatementKind控制流形态消歧(核心):
- FlowControlType重命名为图结构语义名: Branch->ConditionalJump, Loop->IterativeJump,
  Switch->IndexedDispatch, Break->LoopExit, ToLoopCond->LoopBackedge, Return->ScriptReturn
  (消除与builtin函数名同名混淆,命名按图/边语义而非函数)
- IBuiltinFunctionDefinition新增FlowControlShape(默认null),StatementKind改为派生
- CFGStatement新增FlowControlShape属性,LowerToCFG/合成语句时填充
- 所有控制流消费点改查FlowControlShape: CFG2CSConverter类型推断/BP2CFGConverter块分类
  与边语义/CFGConditionDuplicator/CFGBlock.EndsWithControlFlow/GetEdgeType/RegenerateBranchSource
- 删除6个registry迁移遗留死值: Print/Set/Get/Pause/PluginCallWithTarget/TryGetDevice
  (保留5个控制流Kind作派生诊断标签+Assignment/Expression/NextBlockAssignment值分类)
- ControlFlowMapping简化文档+明确ToFunctionName为唯一字符串源
- 新增控制流builtin只需设FlowControlShape,零enum改动零散弹

Phase C - Models提升:
- Abstractions/Models/ -> 根Models/(13文件,namespace Abstractions.Models->Models)
- Abstractions/回归接口本义(已证伪跨Contract边界说法:Dashboard走接口不碰模型)
- GlobalUsings+19文件显式引用更新

Phase D - 表达式构建器收敛+registry单例:
- CSEmitContext新增GetInvocation/PluginCallExpression/PluginCallWithTargetExpression
- 3个BuiltinFunctions从CFG2CSConverter.X(...)改ctx.X(...),消除叶子层反向依赖929行converter
- BuiltinFunctionRegistry新增Instance懒单例,CFG2CSConverter/CSCompiler改用之
  (消除4次Discover反射扫描与实例漂移)

Phase E - ExprUtils性能优化:
- ParseExpression/ParseStatement加ConcurrentDictionary memoize(热点路径,避免重复Roslyn解析)
- IsCharacterLiteral改用SyntaxFactory.ParseToken(比表达式树解析便宜得多)

清理: KitX.sln移除SyncCodes悬空Build配置行

验证: Workflow/Core.Contract/Test/Dashboard四个项目0错误构建通过
测试: A-W全部23个测试通过(含控制流K/L/M/N/P/Q/R/S/T/V)

BREAKING CHANGE: FlowControlType枚举值重命名(Branch->ConditionalJump等),外部引用需更新
Date: 2026-06-20
Author: StarInk

Author: StardustSeemsInk

KitX Clients/KitX Workflow/KitX.Workflow.Test/KcsCompileTest.cs

@@ -8,9 +8,9 @@
 using KitX.Workflow.BlockScripting;
 using KitX.Workflow.Compilation;
 using KitX.Workflow.Abstractions;
-using KitX.Workflow.Abstractions.Models;
-using KitX.Workflow.Abstractions.Models.Statements;
-using KitX.Workflow.Abstractions.Models.Results;
+using KitX.Workflow.Models;
+using KitX.Workflow.Models.Statements;
+using KitX.Workflow.Models.Results;
 using KitX.Workflow.Blueprint;
 using KitX.Workflow.CFG;
 using KitX.Workflow.Conversion;

KitX Clients/KitX Workflow/KitX.Workflow.Test/Program.cs

@@ -10,9 +10,9 @@
 using KitX.Workflow.BlockScripting;
 using KitX.Workflow.Compilation;
 using KitX.Workflow.Abstractions;
-using KitX.Workflow.Abstractions.Models;
-using KitX.Workflow.Abstractions.Models.Statements;
-using KitX.Workflow.Abstractions.Models.Results;
+using KitX.Workflow.Models;
+using KitX.Workflow.Models.Statements;
+using KitX.Workflow.Models.Results;
 using KitX.Workflow.Conversion;
 
 namespace KitX.Workflow.Test;

KitX Clients/KitX Workflow/KitX.Workflow/Abstractions/IBlockScriptExecutor.cs

@@ -2,7 +2,7 @@
 using System.Threading;
 using System.Threading.Tasks;
 using KitX.Core.Contract.Workflow;
-using KitX.Workflow.Abstractions.Models;
+using KitX.Workflow.Models;
 
 namespace KitX.Workflow.Abstractions;
 

KitX Clients/KitX Workflow/KitX.Workflow/Abstractions/IBlockScriptParser.cs

@@ -1,6 +1,6 @@
 using System.Threading.Tasks;
 using KitX.Core.Contract.Workflow;
-using KitX.Workflow.Abstractions.Models.Results;
+using KitX.Workflow.Models.Results;
 
 namespace KitX.Workflow.Abstractions;
 

KitX Clients/KitX Workflow/KitX.Workflow/Abstractions/IBlueprintConverters.cs

@@ -21,5 +21,5 @@ public interface IBlockScriptToBlueprintConverter
     /// </summary>
     /// <param name="script">Parsed BlockScript</param>
     /// <returns>Converted Blueprint</returns>
-    KitX.Core.Contract.Workflow.Blueprint Convert(KitX.Workflow.Abstractions.Models.BlockScript script);
+    KitX.Core.Contract.Workflow.Blueprint Convert(KitX.Workflow.Models.BlockScript script);
 }

KitX Clients/KitX Workflow/KitX.Workflow/Abstractions/IBlueprintToBlockScriptConverter.cs

@@ -18,5 +18,5 @@ public interface IBlueprintToBlockScriptConverter
     /// </summary>
     /// <param name="blueprint">Blueprint to convert</param>
     /// <returns>Parsed BlockScript</returns>
-    KitX.Workflow.Abstractions.Models.BlockScript ConvertToBlockScript(KitX.Core.Contract.Workflow.Blueprint blueprint);
+    KitX.Workflow.Models.BlockScript ConvertToBlockScript(KitX.Core.Contract.Workflow.Blueprint blueprint);
 }

KitX Clients/KitX Workflow/KitX.Workflow/Abstractions/IBuiltinFunctionDefinition.cs

@@ -30,13 +30,32 @@ public interface IBuiltinFunctionDefinition
     /// </summary>
     bool IsNonExtractable { get; }
 
-    // ─── 语句类型映射 ─────────────────────────────────
+    // ─── 控制流形态 ─────────────────────────────────
 
     /// <summary>
-    /// 对应的 CFGStatementKind。用于 BS2CFGConverter 确定语句类型，
-    /// 以及 CFG2BPConverter 选择节点创建策略。
+    /// 该内置函数产生的 CFG 控制流形态（图结构角色）。非控制流函数返回 null（默认）。
+    /// 这是控制流语义的权威来源——消费端（BP2CFGConverter/CFG2BPConverter/CFGConditionDuplicator/
+    /// CFG2CSConverter 的类型推断等）应查询此属性而非 switch(CFGStatementKind)。
+    /// 新增控制流内置函数只需覆写此属性，无需修改 CFGStatementKind 枚举或散弹式 switch。
     /// </summary>
-    CFGStatementKind StatementKind { get; }
+    FlowControlType? FlowControlShape => null;
+
+    // ─── 语句类型映射（派生）─────────────────────────
+
+    /// <summary>
+    /// 对应的 CFGStatementKind。现在由 <see cref="FlowControlShape"/> 派生：
+    /// 控制流形态映射到对应的 Kind；非控制流默认 Expression。
+    /// 保留供尚未迁移的旧消费点使用（见 Phase B.3 清理）。
+    /// </summary>
+    CFGStatementKind StatementKind => FlowControlShape switch
+    {
+        FlowControlType.ConditionalJump => CFGStatementKind.Branch,
+        FlowControlType.IterativeJump => CFGStatementKind.Loop,
+        FlowControlType.IndexedDispatch => CFGStatementKind.Switch,
+        FlowControlType.LoopBackedge => CFGStatementKind.ToLoopCond,
+        FlowControlType.LoopExit => CFGStatementKind.Break,
+        _ => CFGStatementKind.Expression
+    };
 
     /// <summary>
     /// 此内置函数在蓝图中物化为哪种节点类型。默认 <see cref="BuiltinNodeKind.BuiltinFunction"/>；
@@ -125,6 +144,7 @@ List<CFGStatement> LowerToCFG(
             {
                 BlockName = blockName,
                 Kind = StatementKind,
+                FlowControlShape = FlowControlShape,
                 FunctionName = FunctionName,
                 Arguments = expandedArgs.ToList(),
                 PubVarTarget = assignedVar,

KitX Clients/KitX Workflow/KitX.Workflow/Abstractions/Models/FlowControlType.cs

@@ -28,9 +28,9 @@ public static void LinkBlocksSequentially(BlockScript script)
             // A block ending with Branch/Loop should NOT fall through
             var lastStatement = currentBlock.Statements.LastOrDefault();
             if (lastStatement is FlowControlStatement flowStmt &&
-                (flowStmt.ControlType == FlowControlType.Branch ||
-                 flowStmt.ControlType == FlowControlType.Loop ||
-                 flowStmt.ControlType == FlowControlType.Return))
+                (flowStmt.ControlType == FlowControlType.ConditionalJump ||
+                 flowStmt.ControlType == FlowControlType.IterativeJump ||
+                 flowStmt.ControlType == FlowControlType.ScriptReturn))
             {
                 continue;
             }

KitX Clients/KitX Workflow/KitX.Workflow/BlockScripting/BlockLinker.cs

@@ -147,7 +147,7 @@ private void ExtractStatements(
                     {
                         LineNumber = returnStmt.GetLineNumber(),
                         SourceCode = returnStmt.ToFullString(),
-                        ControlType = FlowControlType.Return,
+                        ControlType = FlowControlType.ScriptReturn,
                         ConditionExpression = returnStmt.Expression?.ToString() ?? string.Empty
                     });
                     break;