feat(nl2sql): add a manual review function to support (alibaba#2392)

* feature(deepresearch)：The access of the MCP tool for codernode and researchnode

* format adjust

* add space

* Make adjustments by referring to the source code

* Reconfigure the MCP configuration

* format adjustment

* format adjust

* fix the  toolback injection problem

* delete unused tool

* feat(deepresearch): update McpAssignNodeAutoConfiguration

* delete unused package

* Update the AgentsConfiguration class

* fix(nl2sql): add methods for obtaining and setting optimization prompts to simplify the configuration management logic

* fix format

* feat(nl2sql): add a manual review function to support waiting for user decisions before implementing the plan

* refactor(nl2sql): Rewrite the human feedback nodes and related logic to support the manual review process

* refactor(nl2sql): 在中断前保存检查点并支持线程ID传递

* fix: frontend

Co-authored-by: VLSMB <2047857654@qq.com>

* fix: format frontend

Co-authored-by: VLSMB <2047857654@qq.com>

* fix: format code

Co-authored-by: VLSMB <2047857654@qq.com>

* feat: add highlight for json

Co-authored-by: VLSMB <2047857654@qq.com>

* feat: add scrollbar

Co-authored-by: VLSMB <2047857654@qq.com>

* refactor(nl2sql): 重构人类反馈处理逻辑，优化反馈节点与计划生成流程

* feat(nl2sql): 支持表的联合主键处理，优化主键设置逻辑

* fix format

* Revert "Merge remote-tracking branch 'origin/main' into Makoto-humanfeedback"

This reverts commit a2c931c, reversing
changes made to 33d884b.

* Reapply "Merge remote-tracking branch 'origin/main' into Makoto-humanfeedback"

This reverts commit c16b7b6.

* fix conflict

* 更新流式处理逻辑

* fix format

* fix format

---------

Co-authored-by: aias00 <liuhongyu@apache.org>
Co-authored-by: VLSMB <2047857654@qq.com>

Author: 3 people

spring-ai-alibaba-nl2sql/spring-ai-alibaba-nl2sql-chat/src/main/java/com/alibaba/cloud/ai/config/Nl2sqlConfiguration.java

@@ -155,6 +155,8 @@ public StateGraph nl2sqlGraph(ChatClient.Builder chatClientBuilder) throws Graph
 			// NL2SQL相关
 			keyStrategyHashMap.put(IS_ONLY_NL2SQL, new ReplaceStrategy());
 			keyStrategyHashMap.put(ONLY_NL2SQL_OUTPUT, new ReplaceStrategy());
+			// Human Review keys
+			keyStrategyHashMap.put(HUMAN_REVIEW_ENABLED, new ReplaceStrategy());
 			// Final result
 			keyStrategyHashMap.put(RESULT, new ReplaceStrategy());
 			return keyStrategyHashMap;
@@ -176,7 +178,8 @@ public StateGraph nl2sqlGraph(ChatClient.Builder chatClientBuilder) throws Graph
 			.addNode(PYTHON_EXECUTE_NODE, node_async(new PythonExecuteNode(codePoolExecutor)))
 			.addNode(PYTHON_ANALYZE_NODE, node_async(new PythonAnalyzeNode(chatClientBuilder)))
 			.addNode(REPORT_GENERATOR_NODE, node_async(new ReportGeneratorNode(chatClientBuilder, promptConfigService)))
-			.addNode(SEMANTIC_CONSISTENCY_NODE, node_async(new SemanticConsistencyNode(nl2SqlService)));
+			.addNode(SEMANTIC_CONSISTENCY_NODE, node_async(new SemanticConsistencyNode(nl2SqlService)))
+			.addNode("human_feedback", node_async(new HumanFeedbackNode()));
 
 		stateGraph.addEdge(START, QUERY_REWRITE_NODE)
 			.addConditionalEdges(QUERY_REWRITE_NODE, edge_async(new QueryRewriteDispatcher()),
@@ -203,6 +206,16 @@ public StateGraph nl2sqlGraph(ChatClient.Builder chatClientBuilder) throws Graph
 					// If validation passes, proceed to the correct execution node
 					SQL_EXECUTE_NODE, SQL_EXECUTE_NODE, PYTHON_GENERATE_NODE, PYTHON_GENERATE_NODE,
 					REPORT_GENERATOR_NODE, REPORT_GENERATOR_NODE,
+					// If human review is enabled, go to human_feedback node
+					"human_feedback", "human_feedback",
+					// If max repair attempts are reached, end the process
+					END, END))
+			// Human feedback node routing
+			.addConditionalEdges("human_feedback", edge_async(new HumanFeedbackDispatcher()), Map.of(
+					// If plan is rejected, go back to PlannerNode
+					PLANNER_NODE, PLANNER_NODE,
+					// If plan is approved, continue with execution
+					PLAN_EXECUTOR_NODE, PLAN_EXECUTOR_NODE,
 					// If max repair attempts are reached, end the process
 					END, END))
 			.addEdge(REPORT_GENERATOR_NODE, END)

spring-ai-alibaba-nl2sql/spring-ai-alibaba-nl2sql-chat/src/main/java/com/alibaba/cloud/ai/constant/Constant.java

@@ -139,4 +139,7 @@ public class Constant {
 
 	public static final String ONLY_NL2SQL_OUTPUT = "ONLY_NL2SQL_OUTPUT";
 
+	// 人类复核相关
+	public static final String HUMAN_REVIEW_ENABLED = "HUMAN_REVIEW_ENABLED";
+
 }

spring-ai-alibaba-nl2sql/spring-ai-alibaba-nl2sql-chat/src/main/java/com/alibaba/cloud/ai/dispatcher/HumanFeedbackDispatcher.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.alibaba.cloud.ai.dispatcher;
+
+import com.alibaba.cloud.ai.graph.OverAllState;
+import com.alibaba.cloud.ai.graph.action.EdgeAction;
+
+import static com.alibaba.cloud.ai.graph.StateGraph.END;
+
+/**
+ * Dispatcher for human feedback node routing.
+ *
+ * @author Makoto
+ */
+public class HumanFeedbackDispatcher implements EdgeAction {
+
+	@Override
+	public String apply(OverAllState state) throws Exception {
+		String nextNode = (String) state.value("human_next_node", END);
+
+		// 如果是等待反馈状态，返回END让图暂停
+		if ("WAIT_FOR_FEEDBACK".equals(nextNode)) {
+			return END;
+		}
+
+		return nextNode;
+	}
+
+}

spring-ai-alibaba-nl2sql/spring-ai-alibaba-nl2sql-chat/src/main/java/com/alibaba/cloud/ai/dispatcher/PlanExecutorDispatcher.java

@@ -42,7 +42,12 @@ public String apply(OverAllState state) {
 
 		if (validationPassed) {
 			logger.info("Plan validation passed. Proceeding to next step.");
-			return state.value(PLAN_NEXT_NODE, END);
+			String nextNode = state.value(PLAN_NEXT_NODE, END);
+			// 如果返回的是"END"，直接返回END常量
+			if ("END".equals(nextNode)) {
+				return END;
+			}
+			return nextNode;
 		}
 		else {
 			// Plan validation failed, check repair count and decide whether to retry or

spring-ai-alibaba-nl2sql/spring-ai-alibaba-nl2sql-chat/src/main/java/com/alibaba/cloud/ai/node/HumanFeedbackNode.java

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.alibaba.cloud.ai.node;
+
+import com.alibaba.cloud.ai.graph.OverAllState;
+import com.alibaba.cloud.ai.graph.action.NodeAction;
+import com.alibaba.cloud.ai.util.StateUtils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.util.StringUtils;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import static com.alibaba.cloud.ai.constant.Constant.*;
+
+/**
+ * Human feedback node for plan review and modification.
+ *
+ * @author Makoto
+ */
+public class HumanFeedbackNode implements NodeAction {
+
+	private static final Logger logger = LoggerFactory.getLogger(HumanFeedbackNode.class);
+
+	@Override
+	public Map<String, Object> apply(OverAllState state) throws Exception {
+		logger.info("Processing human feedback");
+		Map<String, Object> updated = new HashMap<>();
+
+		// 检查最大修复次数
+		int repairCount = StateUtils.getObjectValue(state, PLAN_REPAIR_COUNT, Integer.class, 0);
+		if (repairCount >= 3) {
+			logger.warn("Max repair attempts (3) exceeded, ending process");
+			updated.put("human_next_node", "END");
+			return updated;
+		}
+
+		// 等待用户反馈
+		OverAllState.HumanFeedback humanFeedback = state.humanFeedback();
+		if (humanFeedback == null) {
+			updated.put("human_next_node", "WAIT_FOR_FEEDBACK");
+			return updated;
+		}
+
+		// 处理反馈结果
+		Map<String, Object> feedbackData = humanFeedback.data();
+		boolean approved = (boolean) feedbackData.getOrDefault("feed_back", true);
+
+		if (approved) {
+			logger.info("Plan approved → execution");
+			updated.put("human_next_node", PLAN_EXECUTOR_NODE);
+			updated.put(HUMAN_REVIEW_ENABLED, false);
+		}
+		else {
+			logger.info("Plan rejected → regeneration (attempt {})", repairCount + 1);
+			updated.put("human_next_node", PLANNER_NODE);
+			updated.put(PLAN_REPAIR_COUNT, repairCount + 1);
+			updated.put(PLAN_CURRENT_STEP, 1);
+			updated.put(HUMAN_REVIEW_ENABLED, true);
+
+			// 保存用户反馈内容
+			String feedbackContent = feedbackData.getOrDefault("feed_back_content", "").toString();
+			updated.put(PLAN_VALIDATION_ERROR,
+					StringUtils.hasLength(feedbackContent) ? feedbackContent : "Plan rejected by user");
+			state.withoutResume();
+		}
+
+		return updated;
+	}
+
+}

spring-ai-alibaba-nl2sql/spring-ai-alibaba-nl2sql-chat/src/main/java/com/alibaba/cloud/ai/node/PlanExecutorNode.java

@@ -31,6 +31,7 @@
 import java.util.Set;
 
 import static com.alibaba.cloud.ai.constant.Constant.IS_ONLY_NL2SQL;
+import static com.alibaba.cloud.ai.constant.Constant.HUMAN_REVIEW_ENABLED;
 import static com.alibaba.cloud.ai.constant.Constant.ONLY_NL2SQL_OUTPUT;
 import static com.alibaba.cloud.ai.constant.Constant.PLANNER_NODE_OUTPUT;
 import static com.alibaba.cloud.ai.constant.Constant.PLAN_CURRENT_STEP;
@@ -106,7 +107,13 @@ public Map<String, Object> apply(OverAllState state) throws Exception {
 					"Validation failed: The plan is not a valid JSON structure. Error: " + e.getMessage());
 		}
 
-		// 2. Execute the Plan if validation passes
+		// 2. If开启人工复核，则在执行前暂停，跳转到human_feedback节点
+		Boolean humanReviewEnabled = state.value(HUMAN_REVIEW_ENABLED, false);
+		if (Boolean.TRUE.equals(humanReviewEnabled)) {
+			logger.info("Human review enabled: routing to human_feedback node");
+			return Map.of(PLAN_VALIDATION_STATUS, true, PLAN_NEXT_NODE, "human_feedback");
+		}
+
 		Plan plan = getPlan(state);
 		Integer currentStep = getCurrentStepNumber(state);
 		List<ExecutionStep> executionPlan = plan.getExecutionPlan();
@@ -140,6 +147,10 @@ private Map<String, Object> determineNextNode(String toolToUse) {
 			logger.info("Determined next execution node: {}", toolToUse);
 			return Map.of(PLAN_NEXT_NODE, toolToUse, PLAN_VALIDATION_STATUS, true);
 		}
+		else if ("human_feedback".equals(toolToUse)) {
+			logger.info("Determined next execution node: {}", toolToUse);
+			return Map.of(PLAN_NEXT_NODE, toolToUse, PLAN_VALIDATION_STATUS, true);
+		}
 		else {
 			// This case should ideally not be reached if validation is done correctly
 			// before.

spring-ai-alibaba-nl2sql/spring-ai-alibaba-nl2sql-chat/src/main/java/com/alibaba/cloud/ai/node/PlannerNode.java

@@ -55,44 +55,60 @@ public PlannerNode(ChatClient.Builder chatClientBuilder) {
 
 	@Override
 	public Map<String, Object> apply(OverAllState state) throws Exception {
-		logger.info("Entering {} node", this.getClass().getSimpleName());
 		String input = (String) state.value(INPUT_KEY).orElseThrow();
-		// load prompt template
-		String businessKnowledgePrompt = (String) state.value(BUSINESS_KNOWLEDGE).orElse("");
-		String semanticModelPrompt = (String) state.value(SEMANTIC_MODEL).orElse("");
-
-		// 是否为NL2SQL模式
 		Boolean onlyNl2sql = state.value(IS_ONLY_NL2SQL, false);
 
-		SchemaDTO schemaDTO = (SchemaDTO) state.value(TABLE_RELATION_OUTPUT).orElseThrow();
-		String schemaStr = PromptHelper.buildMixMacSqlDbPrompt(schemaDTO, true);
-
-		// Check if this is a repair attempt
+		// 检查是否为修复模式
 		String validationError = StateUtils.getStringValue(state, PLAN_VALIDATION_ERROR, null);
-		String userPrompt;
 		if (validationError != null) {
-			logger.warn("This is a plan repair attempt. Previous error: {}", validationError);
-			String previousPlan = StateUtils.getStringValue(state, PLANNER_NODE_OUTPUT, "");
-			userPrompt = String.format(
-					"The previous plan you generated failed validation with the following error: %s\n\nHere is the faulty plan:\n%s\n\nPlease correct the plan and provide a new, valid one to answer the original question: %s",
-					validationError, previousPlan, input);
+			logger.info("Regenerating plan with user feedback: {}", validationError);
 		}
 		else {
-			userPrompt = input;
+			logger.info("Generating initial plan");
 		}
 
+		// 构建提示参数
+		String businessKnowledge = (String) state.value(BUSINESS_KNOWLEDGE).orElse("");
+		String semanticModel = (String) state.value(SEMANTIC_MODEL).orElse("");
+		SchemaDTO schemaDTO = (SchemaDTO) state.value(TABLE_RELATION_OUTPUT).orElseThrow();
+		String schemaStr = PromptHelper.buildMixMacSqlDbPrompt(schemaDTO, true);
+
+		// 构建用户提示
+		String userPrompt = buildUserPrompt(input, validationError, state);
+
+		// 构建模板参数
 		Map<String, Object> params = Map.of("user_question", userPrompt, "schema", schemaStr, "business_knowledge",
-				businessKnowledgePrompt, "semantic_model", semanticModelPrompt);
-		// 根据模式选择planer的Prompt
+				businessKnowledge, "semantic_model", semanticModel, "plan_validation_error",
+				formatValidationError(validationError));
+
+		// 生成计划
 		String plannerPrompt = (onlyNl2sql ? PromptConstant.getPlannerNl2sqlOnlyTemplate()
 				: PromptConstant.getPlannerPromptTemplate())
 			.render(params);
-		Flux<ChatResponse> chatResponseFlux = chatClient.prompt().user(plannerPrompt).stream().chatResponse();
 
+		Flux<ChatResponse> chatResponseFlux = chatClient.prompt().user(plannerPrompt).stream().chatResponse();
 		var generator = StreamingChatGeneratorUtil.createStreamingGeneratorWithMessages(this.getClass(), state,
 				v -> Map.of(PLANNER_NODE_OUTPUT, v), chatResponseFlux, StreamResponseType.PLAN_GENERATION);
 
 		return Map.of(PLANNER_NODE_OUTPUT, generator);
 	}
 
+	private String buildUserPrompt(String input, String validationError, OverAllState state) {
+		if (validationError == null) {
+			return input;
+		}
+
+		String previousPlan = StateUtils.getStringValue(state, PLANNER_NODE_OUTPUT, "");
+		return String.format(
+				"IMPORTANT: User rejected previous plan with feedback: \"%s\"\n\n" + "Original question: %s\n\n"
+						+ "Previous rejected plan:\n%s\n\n"
+						+ "CRITICAL: Generate new plan incorporating user feedback (\"%s\")",
+				validationError, input, previousPlan, validationError);
+	}
+
+	private String formatValidationError(String validationError) {
+		return validationError != null ? String
+			.format("**USER FEEDBACK (CRITICAL)**: %s\n\n**Must incorporate this feedback.**", validationError) : "";
+	}
+
 }

spring-ai-alibaba-nl2sql/spring-ai-alibaba-nl2sql-chat/src/main/resources/prompts/planner-nl2sql-only.txt

@@ -4,6 +4,16 @@ You are a Senior NL2SQL Agent. Your primary function is to interpret a user's na
 
 **CRITICAL: You MUST only output a valid JSON object. Do not include any explanations, comments, or additional text outside the JSON structure.**
 
+# USER FEEDBACK HANDLING (CRITICAL PRIORITY)
+
+{plan_validation_error}
+
+**If user feedback is provided above:**
+1. **MANDATORY REQUIREMENT**: The feedback contains critical requirements that MUST be satisfied in the new plan
+2. **ABSOLUTE COMPLIANCE**: Every aspect of the user feedback must be incorporated into your plan
+3. **NO EXCEPTIONS**: If user says "需要用Python" (need to use Python), you MUST include PYTHON_GENERATE_NODE steps
+4. **PRIORITY OVERRIDE**: User feedback requirements take precedence over any default analysis approach
+
 # CORE TASK
 
 1.  **Understand the Question**: Analyze the user's natural language query to determine the required metrics, dimensions, and timeframes.

spring-ai-alibaba-nl2sql/spring-ai-alibaba-nl2sql-chat/src/main/resources/prompts/planner.txt

@@ -4,6 +4,16 @@ You are a Senior Data Analysis Agent. Your primary function is to interpret a us
 
 **CRITICAL: You MUST only output a valid JSON object. Do not include any explanations, comments, or additional text outside the JSON structure.**
 
+# USER FEEDBACK HANDLING (CRITICAL PRIORITY)
+
+{plan_validation_error}
+
+**If user feedback is provided above:**
+1. **MANDATORY REQUIREMENT**: The feedback contains critical requirements that MUST be satisfied in the new plan
+2. **ABSOLUTE COMPLIANCE**: Every aspect of the user feedback must be incorporated into your plan
+3. **NO EXCEPTIONS**: If user says "需要用Python" (need to use Python), you MUST include PYTHON_GENERATE_NODE steps
+4. **PRIORITY OVERRIDE**: User feedback requirements take precedence over any default analysis approach
+
 # CORE TASK
 
 1.  **Deconstruct the Request**: Deeply analyze the user's question to understand the core business objective, required metrics (e.g., conversion rates), dimensions (e.g., by region, by channel), and timeframes.

spring-ai-alibaba-nl2sql/spring-ai-alibaba-nl2sql-management/src/main/java/com/alibaba/cloud/ai/controller/AgentSchemaController.java

@@ -259,7 +259,9 @@ public Flux<ServerSentEvent<String>> agentChat(@PathVariable Long agentId,
 			log.info("Agent {} chat request: {}", agentId, query);
 
 			// Directly call streamSearch method of Nl2sqlForGraphController
-			return nl2sqlForGraphController.streamSearch(query.trim(), String.valueOf(agentId), response);
+			// 生成一个threadId用于图执行
+			String threadId = String.valueOf(System.currentTimeMillis());
+			return nl2sqlForGraphController.streamSearch(query.trim(), String.valueOf(agentId), threadId, response);
 
 		}
 		catch (Exception e) {