Appearance
自主规划工作流详解
本文档详细描述
AiChatbotAgent.createAutonomousPlanningGraph()方法创建的自主规划工作流。 该流程实现类似 Claude Code / Manus 的自主规划能力。
工作流概览
┌─────────────────────────────────────────────────────────────────────────────┐
│ 自主规划 (Autonomous Planning) 工作流 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ START │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ load_config │ 加载Agent配置、LLM模型、子Agent、工具、知识库 │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ planning │ 分析用户需求，生成任务执行计划 │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────┐ │
│ │routeAfterPlanning │ │
│ └─────────┬─────────┘ │
│ │ │
│ ┌────────┴────────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────────┐ │
│ │final_response│ │ plan_execution │◄──────────────────┐ │
│ └──────┬──────┘ └────────┬────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌───────────────────┐ │ │
│ │ │routeAfterExecution│ │ │
│ │ └─────────┬─────────┘ │ │
│ │ │ │ │
│ │ ┌────────┴────────┐ │ │
│ │ │ │ │ │
│ │ ▼ │ │ │
│ │ ┌─────────────┐ │ │ │
│ │ │ reflection │ execute_next_task │ │
│ │ └──────┬──────┘ (还有更多任务) │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌────────────────────┐ │ │
│ │ │routeAfterReflection│ │ │
│ │ └─────────┬──────────┘ │ │
│ │ │ │ │
│ │ ┌──────┴──────┐ │ │
│ │ │ │ │ │
│ │ ▼ ▼ │ │
│ │ ┌────────┐ ┌─────────────┐ │ │
│ │ │planning│ │final_response│ │ │
│ │ │(重规划)│ └──────┬──────┘ │ │
│ │ └────┬───┘ │ │ │
│ │ │ │ │ │
│ │ └─────────────┼───────────────────────────┘ │
│ │ │ │
│ └────────────────────┴──────────────────► END │
│ │
└─────────────────────────────────────────────────────────────────────────────┘核心设计理念
Plan-Execute-Reflect 循环
┌─────────────────────────────────────────────────────┐
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ │ │ │ │ │ │
└───►│ PLAN ├────►│ EXECUTE ├────►│ REFLECT ├───┘
│ │ │ │ │ │
│ 制定计划 │ │ 执行任务 │ │ 评估结果 │
│ │ │ │ │ │
└──────────┘ └──────────┘ └──────────┘
│ │
│ │
▼ ▼
(无任务) (评估通过)
│ │
└───────────► END ◄──────────────┘节点详细说明
1. load_config - 加载配置节点
与标准 Chatbot 工作流相同，详见 chatbot-agent-workflow.md。
主要加载内容:
- Agent 基础配置 (systemPrompt, userPrompt 等)
- LLM 模型配置
- 子 Agent 列表
- 工具列表
- 知识库配置
2. planning - 任务规划节点
位置: PlanningNode.apply()
功能: 深度分析用户需求，自动生成结构化的任务执行计划。
┌─────────────────────────────────────────────────────────────────┐
│ 任务规划流程 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 用户输入 (userInput) │
│ │ │
│ ▼ │
│ ┌────────────────────┐ │
│ │ buildPlanningPrompt│ 构建规划提示词 │
│ └──────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────┐ │
│ │ 提示词内容: │ │
│ │ - 用户输入 │ │
│ │ - 可用子Agent (ID/名称/描述) │ │
│ │ - 可用工具 (名称/描述/参数Schema) │ │
│ │ - 可用知识库数量 │ │
│ │ - JSON输出格式要求 │ │
│ │ - 规划原则 │ │
│ └──────────────────┬──────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────┐ │
│ │ 调用 LLM 生成 │ 支持流式/非流式 │
│ │ 任务计划 │ 超时: 120秒 │
│ └──────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────┐ │
│ │parsePlanFromLlm │ 解析 JSON → TaskPlan │
│ │ Response │ │
│ └──────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────┐ │
│ │ TaskPlan │ │
│ │ - planId: 计划唯一ID │ │
│ │ - userIntent: 用户真实意图 │ │
│ │ - intentAnalysis: 意图分析 │ │
│ │ - summary: 计划概述 │ │
│ │ - complexity: 复杂度 (1-10) │ │
│ │ - steps: List<TaskStep> │ │
│ │ - status: created/executing/completed │ │
│ │ - replanCount: 重规划次数 │ │
│ └────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘LLM 返回的计划 JSON 格式
json
{
"userIntent": "用户真正想要达成的目标",
"intentAnalysis": "对用户意图的详细分析",
"summary": "执行计划概述",
"complexity": 5,
"steps": [
{
"name": "步骤名称",
"description": "步骤描述",
"actionType": "call_tool|call_sub_agent|rag_query|llm_generate|mcp_call|aggregate",
"targetResource": "工具名/子Agent ID/知识库ID等",
"parameters": {"参数名": "参数值"},
"dependencies": [0, 1],
"importance": 0.8,
"skippable": false
}
]
}TaskStep 结构
| 字段 | 类型 | 说明 |
|---|---|---|
stepIndex | int | 步骤索引 |
name | String | 步骤名称 |
description | String | 步骤描述 |
actionType | String | 动作类型 |
targetResource | String | 目标资源 |
parameters | Map | 执行参数 |
dependencies | List<Integer> | 依赖的步骤索引 |
status | String | pending/running/completed/failed/skipped |
importance | double | 重要性 (0-1) |
skippable | Boolean | 是否可跳过 |
动作类型 (actionType)
| 类型 | 常量 | 说明 |
|---|---|---|
call_tool | ACTION_CALL_TOOL | 调用工具 |
call_sub_agent | ACTION_CALL_SUB_AGENT | 调用子 Agent |
rag_query | ACTION_RAG_QUERY | RAG 知识库检索 |
llm_generate | ACTION_LLM_GENERATE | LLM 生成 |
mcp_call | ACTION_MCP_CALL | MCP 调用 |
aggregate | ACTION_AGGREGATE | 结果聚合 |
规划原则
- 目标导向: 明确用户最终想要达成的目标
- 最小化步骤: 只规划必要的步骤，避免冗余
- 合理分解: 复杂任务应分解为可执行的小步骤
- 依赖明确: 清晰标注步骤间的依赖关系
- 容错设计: 标记可跳过的步骤，提高执行鲁棒性
- 简单问题: 如果是简单问答类问题，steps 可以为空
3. plan_execution - 计划执行节点
位置: PlanExecutionNode.apply()
功能: 逐步执行任务计划中的每个步骤。
┌─────────────────────────────────────────────────────────────────┐
│ 计划执行流程 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ taskPlan + currentTaskIndex │
│ │ │
│ ▼ │
│ ┌────────────────────┐ │
│ │ 检查是否还有任务 │ │
│ │ currentIndex >= │ 是 → 进入反思节点 │
│ │ taskPlan.size() │ │
│ └──────────┬─────────┘ │
│ │ 否 │
│ ▼ │
│ ┌────────────────────┐ │
│ │ checkDependencies │ 检查依赖是否满足 │
│ └──────────┬─────────┘ │
│ │ │
│ ┌────────┴────────┐ │
│ │ 依赖未满足 │ 依赖已满足 │
│ ▼ ▼ │
│ ┌───────────┐ ┌──────────────┐ │
│ │ skippable?│ │ executeTask │ │
│ └─────┬─────┘ └──────┬───────┘ │
│ │ │ │
│ Yes │ No ▼ │
│ ▼ ▼ ┌──────────────┐ │
│ 跳过 抛异常 │ 根据actionType│ │
│ │ 执行具体任务 │ │
│ └──────────────┘ │
│ │ │
│ ┌─────────────┼─────────────┬─────────────┐ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │call_tool│ │call_sub │ │rag_query│ │llm_gen- │ │
│ │ │ │_agent │ │ │ │erate │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │
│ └────────────┴────────────┴────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ 更新任务状态和结果 │ │
│ │ - taskPlan[index].status = completed │ │
│ │ - taskResults.add(result) │ │
│ │ - currentTaskIndex++ │ │
│ └────────────────────┬─────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────┐ │
│ │ 判断下一步: │ │
│ │ - 还有任务? → execute_next_task │ │
│ │ - 全部完成? → reflect │ │
│ └────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘各类型任务执行
call_tool - 工具调用
java
private String executeToolCall(String toolName, Map<String, Object> params) {
// 1. 根据工具名获取工具配置
AiToolEntity toolEntity = aiToolService.getByToolName(toolName);
// 2. 根据 serviceType 获取执行器
ToolExecutor executor = executorFactory.getExecutor(toolEntity.getServiceType());
// 3. 执行工具
return executor.execute(toolEntity, params);
}call_sub_agent - 子 Agent 调用
java
private String executeSubAgentCall(String subAgentId, String userInput) {
Long agentId = Long.parseLong(subAgentId);
return agentExecutionService.executeAgent(agentId, userInput);
}rag_query - RAG 检索
java
private String executeRagQuery(Map<String, Object> params, ChatbotAgentState state) {
String query = (String) params.getOrDefault("query", state.userInput());
// 使用 RagExecutor 执行检索
var ragResult = ragExecutor.retrieve(query, state.datasetList(), state.retrievalConfig());
// 格式化检索结果
StringBuilder result = new StringBuilder();
result.append("检索到 ").append(ragResult.size()).append(" 条相关内容:\n\n");
// ...
}llm_generate - LLM 生成
java
private String executeLlmGenerate(Map<String, Object> params, ChatbotAgentState state) {
String prompt = (String) params.getOrDefault("prompt", state.userInput());
ChatModel chatModel = llmModelProvider.getChatModel(state.llmModelConfig());
return chatModel.chat(prompt);
}aggregate - 结果聚合
java
private String executeAggregate(Map<String, Object> params, ChatbotAgentState state) {
List<Map<String, Object>> taskResults = state.taskResults();
StringBuilder aggregated = new StringBuilder();
aggregated.append("执行结果汇总:\n\n");
for (Map<String, Object> result : taskResults) {
String status = (String) result.get("status");
String name = (String) result.get("name");
// 格式化输出
}
return aggregated.toString();
}4. reflection - 反思节点
位置: ReflectionNode.apply()
功能: 评估任务执行结果，决定是否需要重新规划。
┌─────────────────────────────────────────────────────────────────┐
│ 反思流程 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ taskResults + taskPlan │
│ │ │
│ ▼ │
│ ┌────────────────────┐ │
│ │ 统计执行结果 │ │
│ │ - completedTasks │ │
│ │ - failedTasks │ │
│ │ - skippedTasks │ │
│ └──────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────┐ │
│ │ 判断反思策略: │ │
│ │ │ │
│ │ 无任务执行 → 直接生成响应 │ │
│ │ │ │
│ │ 全部失败 → 调用 LLM 反思 │ │
│ │ → 判断是否需要重新规划 │ │
│ │ │ │
│ │ 有成功任务 → 简单评估，准备生成响应 │ │
│ └────────────────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────┐ │
│ │ performReflection() │ │
│ │ 调用 LLM 进行深度反思 │ │
│ └────────────────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────┐ │
│ │ ReflectionResult │ │
│ │ - analysis: 分析评估 │ │
│ │ - goalAchieved: 目标是否达成 │ │
│ │ - needReplan: 是否需要重新规划 │ │
│ │ - replanReason: 重规划原因 │ │
│ └────────────────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────┐ │
│ │ 决定下一步: │ │
│ │ - needReplan && canReplan → replan │ │
│ │ - 否则 → final_response │ │
│ └────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘反思 LLM 返回格式
json
{
"analysis": "对执行结果的分析评估",
"goalAchieved": true,
"needReplan": false,
"replanReason": "如果需要重新规划，说明原因",
"suggestions": ["改进建议列表"]
}重规划条件
java
private boolean canReplan(ChatbotAgentState state) {
// 检查重新规划次数限制
Integer loopCount = state.loopCount();
Integer maxLoops = state.maxLoops();
return loopCount < maxLoops; // 默认 maxLoops = 3
}5. final_response - 最终响应生成节点
位置: AiChatbotAgent.generateFinalResponse()
功能: 汇总所有执行结果，生成最终用户响应。
┌─────────────────────────────────────────────────────────────────┐
│ 最终响应生成流程 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ taskResults + userInput + userIntent + reflection │
│ │ │
│ ▼ │
│ ┌────────────────────┐ │
│ │ 收集执行结果 │ │
│ │ 遍历 taskResults │ │
│ │ 提取成功的结果 │ │
│ └──────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────┐ │
│ │ 构建响应上下文: │ │
│ │ - 用户问题 │ │
│ │ - 理解的意图 │ │
│ │ - 各任务执行结果 │ │
│ │ - 反思分析总结 │ │
│ └────────────────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────┐ │
│ │ buildFinalResponsePrompt() │ │
│ │ 构建最终响应提示词 │ │
│ │ - 语言简洁明了 │ │
│ │ - 结合执行结果给出有价值信息 │ │
│ │ - 如有失败，适当说明 │ │
│ │ - 使用友好语气 │ │
│ └────────────────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────┐ │
│ │ 调用 LLM 生成最终响应 │ │
│ │ 支持流式/非流式 │ │
│ └────────────────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ 存入 State: final_response │
│ │
└─────────────────────────────────────────────────────────────────┘状态数据流
自主规划特有的 State Key
| Key | 类型 | 说明 |
|---|---|---|
taskPlan | List<Map> | 任务计划列表 |
currentTaskIndex | Integer | 当前执行的任务索引 |
taskResults | List<Map> | 任务执行结果列表 |
planningMode | Boolean | 是否为规划模式 |
reflection | String | 反思内容 |
needReplan | Boolean | 是否需要重新规划 |
maxTaskIterations | Integer | 最大任务执行次数 (默认 20) |
Action 常量
| 常量 | 值 | 说明 |
|---|---|---|
ACTION_EXECUTE_NEXT_TASK | "execute_next_task" | 执行下一个任务 |
ACTION_REFLECT | "reflect" | 进入反思 |
ACTION_REPLAN | "replan" | 重新规划 |
ACTION_FINAL_RESPONSE | "final_response" | 生成最终响应 |
使用示例
流式执行
java
// 入口方法
aiChatbotAgent.autonomousPlanning(agentId, userId, sessionId, userInput, handler);
// 内部流程:
// 1. 获取会话
ChatSession session = sessionManager.getSession(sessionId);
// 2. 创建工作流
CompiledGraph<ChatbotAgentState> graph = createAutonomousPlanningGraph();
// 3. 初始化状态
Map<String, Object> initData = new HashMap<>();
initData.put(ChatbotAgentState.AGENT_ID_KEY, session.getAgentId());
initData.put(ChatbotAgentState.USER_INPUT_KEY, userInput);
initData.put(ChatbotAgentState.PLANNING_MODE_KEY, true);
initData.put(ChatbotAgentState.MAX_LOOPS_KEY, 3); // 最多重规划3次
initData.put(ChatbotAgentState.MAX_TASK_ITERATIONS_KEY, 20);
// 4. 流式执行
RunnableConfig config = RunnableConfig.builder()
.streamMode(CompiledGraph.StreamMode.VALUES)
.build();
StreamContext.setStreamHandler(handler);
var streamOutput = graph.stream(initData, config);
for (var output : streamOutput) {
String nodeName = output.node();
ChatbotAgentState state = output.state();
// 推送进度
handler.onNodeComplete(nodeName, state);
handler.onOverallProgress(current, total, progress);
}同步执行
java
String response = aiChatbotAgent.autonomousPlanningSync(agentId, userId, sessionId, userInput);流式事件
思维链事件
java
// 规划阶段
handler.onThinkingStageStart("planning", "任务规划");
handler.onThinkingContent("planning", "正在分析需求并制定执行计划...");
handler.onThinkingStageEnd("planning");
// 任务执行阶段
handler.onThinkingStageStart("task_execution", "执行任务");
handler.onThinkingContent("task_execution", "执行任务 1/3: 调用工具...");
handler.onThinkingStageEnd("task_execution");
// 反思阶段
handler.onThinkingStageStart("reflection", "执行反思");
handler.onThinkingContent("reflection", "评估执行结果...");
handler.onThinkingStageEnd("reflection");进度事件
java
// 整体进度
handler.onOverallProgress(currentStep, totalSteps, percentComplete);与标准工作流的对比
| 特性 | Chatbot 工作流 | 自主规划工作流 |
|---|---|---|
| 决策方式 | 单次意图识别 | 任务分解 + 规划 |
| 执行模式 | 单步执行 | 多步循环执行 |
| 容错机制 | 简单错误处理 | 依赖检查 + 可跳过 + 重规划 |
| 反思能力 | 无 | LLM 反思评估 |
| 适用场景 | 简单问答、单一任务 | 复杂任务、多步骤流程 |
相关代码文件
| 文件 | 说明 |
|---|---|
AiChatbotAgent.java | 主工作流定义 |
ChatbotAgentState.java | State 定义 |
PlanningNode.java | 任务规划节点 |
PlanExecutionNode.java | 计划执行节点 |
ReflectionNode.java | 反思节点 |
TaskPlan.java | 任务计划 DTO |
TaskStep.java | 任务步骤 DTO |
StreamHandler.java | 流式处理接口 |