💾 Feat(BlockScript): 增强内置函数定义，支持语句类型映射与字段提取，彻底清理散弹式修改的旧方法

StardustSeemsInk · StardustSeemsInk · commit 11f86a1e0c94 · 2026-04-10T21:54:12.000+02:00
diff --git a/KitX Clients/KitX Core/KitX.Core.BluePrint.Test/Program.cs b/KitX Clients/KitX Core/KitX.Core.BluePrint.Test/Program.cs
@@ -5,6 +5,7 @@
 using KitX.Core.DI;
 using KitX.Core.Contract.Workflow;
 using KitX.Core.Workflow.Blueprint;
+using KitX.Core.Workflow.BlockScripting;
 
 namespace KitX.Core.BluePrint.Test;
 
@@ -52,7 +53,8 @@ public static void Main(string[] args)
             }
         };
 
-        var converter = new BlockScriptToBlueprintConverter(parser, nodeRegistry, layoutService);
+        var funcRegistry = sp.GetRequiredService<BuiltinFunctionRegistry>();
+        var converter = new BlockScriptToBlueprintConverter(parser, nodeRegistry, layoutService, funcRegistry);
 
         // ── Test A: Pre-expanded format (already in test script) ──
         Console.WriteLine("┌──────────────────────────────────────────┐");
diff --git a/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BlockStatementExtractor.cs b/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BlockStatementExtractor.cs
@@ -212,20 +212,8 @@ private void ExtractStatements(SyntaxNode root, BlockDefinition block, BlockType
                 {
                     var methodName = ExprUtils.GetMethodName(invoke);
 
-                    if (methodName == Branch)
-                    {
-                        block.Statements.Add(CreateFlowControlStatement(invoke, FlowControlType.Branch, exprStmt.GetLineNumber(), exprText));
-                    }
-                    else if (methodName == Loop)
-                    {
-                        block.Statements.Add(CreateFlowControlStatement(invoke, FlowControlType.Loop, exprStmt.GetLineNumber(), exprText));
-                    }
-                    else if (methodName == LoopBodyEnd)
-                    {
-                        block.Statements.Add(CreateFlowControlStatement(invoke, FlowControlType.LoopBodyEnd, exprStmt.GetLineNumber(), exprText));
-                    }
-                    // Try BuiltinFunctionRegistry for new/future functions (e.g. Flip)
-                    else if (_functionRegistry != null && _functionRegistry.Get(methodName) is { } funcDef)
+                    // Try BuiltinFunctionRegistry for all registered functions
+                    if (_functionRegistry != null && _functionRegistry.Get(methodName) is { } funcDef)
                     {
                         var stmt = funcDef.ExtractStatement(invoke, exprStmt.GetLineNumber(), exprText);
                         if (stmt != null)
@@ -256,20 +244,8 @@ private void ExtractStatements(SyntaxNode root, BlockDefinition block, BlockType
                         var methodName = ExprUtils.GetMethodName(assignInvoke);
                         Log.Debug("[BlockStatementExtractor]   assignment.Right is InvocationExpressionSyntax, methodName = {MethodName}", methodName);
 
-                        if (methodName == Branch)
-                        {
-                            block.Statements.Add(CreateFlowControlStatement(assignInvoke, FlowControlType.Branch, exprStmt.GetLineNumber(), exprText));
-                        }
-                        else if (methodName == Loop)
-                        {
-                            block.Statements.Add(CreateFlowControlStatement(assignInvoke, FlowControlType.Loop, exprStmt.GetLineNumber(), exprText));
-                        }
-                        else if (methodName == LoopBodyEnd)
-                        {
-                            block.Statements.Add(CreateFlowControlStatement(assignInvoke, FlowControlType.LoopBodyEnd, exprStmt.GetLineNumber(), exprText));
-                        }
-                        // Try BuiltinFunctionRegistry for new/future functions (e.g. Flip)
-                        else if (_functionRegistry != null && _functionRegistry.Get(methodName) is { } funcDef)
+                        // Try BuiltinFunctionRegistry for all registered functions
+                        if (_functionRegistry != null && _functionRegistry.Get(methodName) is { } funcDef)
                         {
                             var stmt = funcDef.ExtractStatement(assignInvoke, exprStmt.GetLineNumber(), exprText);
                             if (stmt != null)
diff --git a/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/BranchFunction.cs b/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/BranchFunction.cs
@@ -19,6 +19,7 @@ public class BranchFunction : IBuiltinFunctionDefinition
     public bool IsNonExtractable => false;
     public BlueprintNodeType? LegacyNodeType => BlueprintNodeType.Branch;
     public bool IsBlockTerminator => true;
+    public FormattedStatementKind StatementKind => FormattedStatementKind.Branch;
     public double NodeWidth => 120;
     public double NodeHeight => 80;
 
diff --git a/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/BreakFunction.cs b/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/BreakFunction.cs
@@ -14,8 +14,10 @@ public class BreakFunction : IBuiltinFunctionDefinition
     public string FunctionName => "Break";
     public string DisplayName => "Break";
     public bool IsFlowControl => true;
+    public bool IsBlockTerminator => true;
     public bool IsNonExtractable => true;
     public BlueprintNodeType? LegacyNodeType => BlueprintNodeType.Break;
+    public FormattedStatementKind StatementKind => FormattedStatementKind.Break;
     public double NodeWidth => 100;
     public double NodeHeight => 40;
 
diff --git a/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/FlipFunction.cs b/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/FlipFunction.cs
@@ -20,6 +20,7 @@ public class FlipFunction : IBuiltinFunctionDefinition
     public bool IsFlowControl => true;
     public bool IsNonExtractable => true;
     public bool IsBlockTerminator => true;
+    public FormattedStatementKind StatementKind => FormattedStatementKind.Branch;
     public double NodeWidth => 120;
     public double NodeHeight => 80;
 
diff --git a/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/GetFunction.cs b/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/GetFunction.cs
@@ -14,8 +14,9 @@ public class GetFunction : IBuiltinFunctionDefinition
     public string FunctionName => "Get";
     public string DisplayName => "Get";
     public bool IsFlowControl => false;
-    public bool IsNonExtractable => true;
+    public bool IsNonExtractable => false;
     public BlueprintNodeType? LegacyNodeType => BlueprintNodeType.Get;
+    public FormattedStatementKind StatementKind => FormattedStatementKind.Assignment;
     public double NodeWidth => 120;
     public double NodeHeight => 60;
 
@@ -74,11 +75,40 @@ public List<FormattedStatement> FormatInvocation(
 
     public BlueprintNode ConfigureNode(BlueprintNode node, FormattedStatement stmt)
     {
-        if (node is BuiltinFunctionNode bfn)
-            bfn.Properties["VarName"] = stmt.GetVarName ?? "";
+        var varName = stmt.GetVarName ?? (stmt.Arguments?.Count > 0 ? stmt.Arguments[0].Trim('"') : "");
+        if (node is GetNode gn)
+            gn.VarName = varName;
+        else if (node is BuiltinFunctionNode bfn)
+            bfn.Properties["VarName"] = varName;
         return node;
     }
 
+    public (string?, string?, string?) ExtractStatementFields(
+        InvocationExpressionSyntax invoke, List<string> expandedArgs,
+        string? assignedVar, PipelineContext context)
+    {
+        string? getVarName = null;
+        if (expandedArgs.Count > 0)
+        {
+            var firstArgExpr = invoke.ArgumentList.Arguments[0].Expression;
+            getVarName = ExprUtils.GetStringLiteralValue(firstArgExpr) ?? expandedArgs[0];
+        }
+
+        string? pubVarTarget;
+        if (string.IsNullOrEmpty(assignedVar) || !context.PubVarNames.Contains(assignedVar))
+        {
+            pubVarTarget = ExprUtils.GeneratePubVarName(context.NextPubVarCounter++);
+            if (!context.PubVarNames.Contains(pubVarTarget))
+                context.PubVarNames.Add(pubVarTarget);
+        }
+        else
+        {
+            pubVarTarget = assignedVar;
+        }
+
+        return (null, getVarName, pubVarTarget);
+    }
+
     public BlockStatement? ToStatement(BlueprintNode node, INodeExportHelper helper)
     {
         var varName = node switch
diff --git a/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/LoopBodyEndFunction.cs b/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/LoopBodyEndFunction.cs
@@ -17,6 +17,7 @@ public class LoopBodyEndFunction : IBuiltinFunctionDefinition
     public bool IsFlowControl => true;
     public bool IsNonExtractable => false;
     public bool IsBlockTerminator => true;
+    public FormattedStatementKind StatementKind => FormattedStatementKind.LoopBodyEnd;
     public double NodeWidth => 80;
     public double NodeHeight => 60;
 
diff --git a/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/LoopFunction.cs b/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/LoopFunction.cs
@@ -20,6 +20,7 @@ public class LoopFunction : IBuiltinFunctionDefinition
     public bool IsNonExtractable => false;
     public BlueprintNodeType? LegacyNodeType => BlueprintNodeType.Loop;
     public bool IsBlockTerminator => true;
+    public FormattedStatementKind StatementKind => FormattedStatementKind.Loop;
     public double NodeWidth => 120;
     public double NodeHeight => 80;
 
diff --git a/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/PauseFunction.cs b/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/PauseFunction.cs
@@ -16,6 +16,7 @@ public class PauseFunction : IBuiltinFunctionDefinition
     public bool IsFlowControl => false;
     public bool IsNonExtractable => true;
     public BlueprintNodeType? LegacyNodeType => BlueprintNodeType.Pause;
+    public FormattedStatementKind StatementKind => FormattedStatementKind.Pause;
     public double NodeWidth => 100;
     public double NodeHeight => 50;
 
diff --git a/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/PrintFunction.cs b/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/PrintFunction.cs
@@ -16,6 +16,7 @@ public class PrintFunction : IBuiltinFunctionDefinition
     public bool IsFlowControl => false;
     public bool IsNonExtractable => true;
     public BlueprintNodeType? LegacyNodeType => BlueprintNodeType.Print;
+    public FormattedStatementKind StatementKind => FormattedStatementKind.Print;
     public double NodeWidth => 100;
     public double NodeHeight => 50;
 
diff --git a/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/SetFunction.cs b/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/BuiltinFunctions/SetFunction.cs
@@ -16,6 +16,7 @@ public class SetFunction : IBuiltinFunctionDefinition
     public bool IsFlowControl => false;
     public bool IsNonExtractable => true;
     public BlueprintNodeType? LegacyNodeType => BlueprintNodeType.Set;
+    public FormattedStatementKind StatementKind => FormattedStatementKind.Set;
     public double NodeWidth => 120;
     public double NodeHeight => 60;
 
@@ -62,11 +63,28 @@ public List<FormattedStatement> FormatInvocation(
 
     public BlueprintNode ConfigureNode(BlueprintNode node, FormattedStatement stmt)
     {
-        if (node is BuiltinFunctionNode bfn)
-            bfn.Properties["VarName"] = stmt.SetVarName ?? "";
+        var varName = stmt.SetVarName ?? "";
+        if (node is SetNode sn)
+            sn.VarName = varName;
+        else if (node is BuiltinFunctionNode bfn)
+            bfn.Properties["VarName"] = varName;
         return node;
     }
 
+    public (string?, string?, string?) ExtractStatementFields(
+        InvocationExpressionSyntax invoke, List<string> expandedArgs,
+        string? assignedVar, PipelineContext context)
+    {
+        string? setVarName = null;
+        if (expandedArgs.Count > 0)
+        {
+            var firstArgExpr = invoke.ArgumentList.Arguments[0].Expression;
+            setVarName = ExprUtils.GetStringLiteralValue(firstArgExpr) ?? expandedArgs[0];
+            expandedArgs.RemoveAt(0);
+        }
+        return (setVarName, null, null);
+    }
+
     public BlockStatement? ToStatement(BlueprintNode node, INodeExportHelper helper)
     {
         var varName = node switch
diff --git a/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/IBuiltinFunctionDefinition.cs b/KitX Clients/KitX Core/KitX.Core/Workflow/BlockScripting/IBuiltinFunctionDefinition.cs
@@ -31,6 +31,32 @@ public interface IBuiltinFunctionDefinition
     /// </summary>
     bool IsNonExtractable { get; }
 
+    // ─── 语句类型映射 ─────────────────────────────────
+
+    /// <summary>
+    /// 对应的 FormattedStatementKind。用于 ScriptFormatter 确定语句类型，
+    /// 以及 NodeBuilder 选择节点创建策略。
+    /// </summary>
+    FormattedStatementKind StatementKind { get; }
+
+    // ─── 语句字段提取（可选，默认无操作）──────────────
+
+    /// <summary>
+    /// 从调用表达式中提取语句特定的字段（如 Set 的变量名、Get 的变量名和 PubVar）。
+    /// ScriptFormatter.FormatInvocation 在处理已注册函数时调用此方法获取 Kind 之外的特殊字段。
+    /// 默认实现不提取任何特殊字段。
+    /// </summary>
+    /// <param name="invoke">原始 Roslyn 调用表达式</param>
+    /// <param name="expandedArgs">已展开的参数列表（可被修改，如 Set 移除第一个参数）</param>
+    /// <param name="assignedVar">语句左侧的赋值变量名（可能为 null）</param>
+    /// <param name="context">管线上下文（可用于 PubVar 计数器等状态）</param>
+    (string? setVarName, string? getVarName, string? pubVarTarget) ExtractStatementFields(
+        InvocationExpressionSyntax invoke,
+        List<string> expandedArgs,
+        string? assignedVar,
+        PipelineContext context)
+        => (null, null, null);
+
     // ─── 节点布局 ───────────────────────────────────
 
     /// <summary>蓝图节点宽度</summary>
diff --git a/KitX Clients/KitX Core/KitX.Core/Workflow/Blueprint/Pipeline/ExprUtils.cs b/KitX Clients/KitX Core/KitX.Core/Workflow/Blueprint/Pipeline/ExprUtils.cs
@@ -16,39 +16,6 @@ namespace KitX.Core.Workflow.Blueprint.Pipeline;
 /// </summary>
 public static class ExprUtils
 {
-    /// <summary>
-    /// All known built-in function names. Prefer <see cref="BuiltinFunctionRegistry.AllFunctionNames"/> for new code.
-    /// </summary>
-    [Obsolete("Use BuiltinFunctionRegistry.AllFunctionNames instead. This set only covers legacy hardcoded functions.")]
-    public static readonly HashSet<string> BuiltinFunctions = new()
-    {
-        BlockScriptWellKnown.Functions.Get, BlockScriptWellKnown.Functions.Set,
-        BlockScriptWellKnown.Functions.Print, BlockScriptWellKnown.Functions.Pause,
-        BlockScriptWellKnown.Functions.Branch, BlockScriptWellKnown.Functions.Loop,
-        BlockScriptWellKnown.Functions.LoopBodyEnd, BlockScriptWellKnown.Functions.Break
-    };
-
-    /// <summary>
-    /// Functions that should not be extracted during argument expansion.
-    /// Prefer <see cref="BuiltinFunctionRegistry.NonExtractableNames"/> for new code.
-    /// </summary>
-    [Obsolete("Use BuiltinFunctionRegistry.NonExtractableNames instead. This set only covers legacy hardcoded functions.")]
-    public static readonly HashSet<string> NonExtractableFunctions = new()
-    {
-        BlockScriptWellKnown.Functions.Set, BlockScriptWellKnown.Functions.Print,
-        BlockScriptWellKnown.Functions.Pause
-    };
-
-    /// <summary>
-    /// Flow control function names. Prefer <see cref="BuiltinFunctionRegistry.FlowControlNames"/> for new code.
-    /// </summary>
-    [Obsolete("Use BuiltinFunctionRegistry.FlowControlNames instead. This set only covers legacy hardcoded functions.")]
-    public static readonly HashSet<string> FlowControlFunctions = new()
-    {
-        BlockScriptWellKnown.Functions.Branch, BlockScriptWellKnown.Functions.Loop,
-        BlockScriptWellKnown.Functions.LoopBodyEnd, BlockScriptWellKnown.Functions.Break
-    };
-
     /// <summary>Parses an expression string using Roslyn. Returns null on failure.</summary>
     public static ExpressionSyntax? ParseExpression(string expression)
     {
@@ -160,35 +127,6 @@ public static string GeneratePubVarName(int counter)
     }
 
     /// <summary>
-    /// Finds all nested invocation arguments in an invocation (non-builtin only).
-    /// Returns them in depth-first order (deepest first).
-    /// </summary>
-    public static List<InvocationExpressionSyntax> FindNestedInvocations(InvocationExpressionSyntax invoke)
-    {
-        var result = new List<InvocationExpressionSyntax>();
-        foreach (var arg in invoke.ArgumentList.Arguments)
-            CollectNested(arg.Expression, result);
-        return result;
-    }
-
-    private static void CollectNested(ExpressionSyntax expr, List<InvocationExpressionSyntax> result)
-    {
-        if (expr is InvocationExpressionSyntax invoke)
-        {
-            var funcName = GetMethodName(invoke);
-            // Recurse into arguments first (depth-first)
-            foreach (var arg in invoke.ArgumentList.Arguments)
-                CollectNested(arg.Expression, result);
-            // Only extract non-builtin, non-flow-control functions
-#pragma warning disable CS0618
-            if (!NonExtractableFunctions.Contains(funcName) && !FlowControlFunctions.Contains(funcName))
-#pragma warning restore CS0618
-                result.Add(invoke);
-        }
-        else if (expr is ParenthesizedExpressionSyntax paren)
-            CollectNested(paren.Expression, result);
-    }
-
     /// <summary>Computes a fingerprint string for a call expression for reuse detection.</summary>
     public static string ComputeFingerprint(string funcName, List<string> args)
         => $"{funcName}({string.Join(",", args.Select(a => a.Trim().Replace(" ", "")))})";
diff --git a/KitX Clients/KitX Core/KitX.Core/Workflow/Blueprint/Pipeline/NodeBuilder.cs b/KitX Clients/KitX Core/KitX.Core/Workflow/Blueprint/Pipeline/NodeBuilder.cs
diff --git a/KitX Clients/KitX Core/KitX.Core/Workflow/Blueprint/Pipeline/PipelineAssembler.cs b/KitX Clients/KitX Core/KitX.Core/Workflow/Blueprint/Pipeline/PipelineAssembler.cs
diff --git a/KitX Clients/KitX Core/KitX.Core/Workflow/Blueprint/Pipeline/ScriptFormatter.cs b/KitX Clients/KitX Core/KitX.Core/Workflow/Blueprint/Pipeline/ScriptFormatter.cs
