2026-05-22｜Plan-Execute 核心执行引擎开发

一、今日主要工作#

围绕智能体管理平台的核心执行能力，完成 Plan-and-Execute Agent 引擎 的 MVP 主体开发。
基于 Spring AI 思路，梳理并实现 Agent 从用户输入到计划生成、步骤执行、Skill 调用、结果汇总和执行轨迹记录的主链路。
完成 Agent 执行相关的领域实体、状态枚举、Mapper、配置初始化、应用服务、Planner、Executor、Skill 调用和 API 层开发。
完成管理端桥接工作，将 plan_execute 推理模式接入现有对话流，使前端可通过 Agent 选择器进入 Plan-and-Execute 执行链路。
梳理并沉淀《Spring AI 通用 Agent 平台 MVP 技术实施方案》和《Agent 工厂模块状态与后续规划》，记录当前模块完成情况、已验证能力、已知问题和后续开发路线。

二、核心完成内容#

1. 模块开发与功能实现#

今天的主要开发工作集中在 com.sangfor.agent.planexecute 模块。该模块是智能体管理平台的核心执行引擎，目标是让系统能够根据用户自然语言请求自动生成执行计划，并按照计划逐步调用 LLM、Local Skill 或 MCP Skill 完成任务。

本次开发重点围绕以下主链路展开：

1
AgentRunService
2
  → PlanGenerator
3
  → PlanAndExecuteService
4
  → StepExecutor
5
  → SkillMatcher
6
  → SkillInvoker
7
  → ResultSynthesizer

通过该链路，系统可以完成如下流程：

接收用户输入和 Agent 配置；
创建一次 AgentRun 执行记录；
由 PlanGenerator 调用 LLM 生成结构化 Plan；
保存 Plan 和 PlanStep；
按 step_index 顺序执行每个 Step；
根据 Step 类型选择 LLM 执行或 Skill 调用；
记录工具调用和执行过程；
汇总所有步骤结果，生成最终回复。

相比前一天完成的 MCP Client Gateway，今天的工作进一步向上推进到了 Agent 执行层，使平台从“具备工具接入能力”进入到“具备计划生成与执行内核”的阶段。

2. 领域模型与数据持久化开发#

今天完成了 Plan-and-Execute Agent 引擎相关的基础实体和数据库结构设计与开发，主要包括：

AgentProfileEntity：描述 Agent 基础配置；
AgentRunEntity：记录一次 Agent 执行过程；
AgentPlanEntity：记录一次任务规划；
AgentPlanStepEntity：记录计划中的具体执行步骤；
SkillDefinitionEntity：描述可调用 Skill；
AgentSkillBindEntity：维护 Agent 与 Skill 的绑定关系；
ToolCallRecordEntity：记录 Skill / Tool 调用日志。

同时完成了对应的状态枚举和模型对象，包括 RunStatus、PlanStatus、StepStatus、StepType、ToolCallStatus、SkillInvokeType、AgentRunResult、StepExecuteResult、SkillMetadata、SkillInvokeResult、PlanGenerateRequest 和 PlanStepResult。

这些基础结构为 Agent 执行过程中的状态流转、计划持久化、步骤追踪和调用审计提供了数据支撑。

3. Plan 生成与解析能力开发#

今天完成了 Planner 层核心组件开发，主要包括：

PlanGenerator；
PlanPromptBuilder；
PlanParser；
PlanFallbackFactory。

其中，PlanGenerator 负责根据用户输入、Agent 配置和可用 Skill 列表生成结构化执行计划；PlanPromptBuilder 负责构造计划生成 Prompt；PlanParser 负责解析 LLM 返回的 JSON 计划；PlanFallbackFactory 负责在解析失败时生成兜底计划。

在设计上，MVP 阶段要求 Plan 的步骤数量控制在 3 到 6 步，并将 Step 类型简化为以下几类：

INTENT_ANALYSIS：意图理解；
PARAM_EXTRACT：参数提取；
SKILL_CALL：调用 Skill；
LLM_PROCESS：纯 LLM 处理；
FINAL_RESPONSE：最终回复生成。

同时，为了提高计划生成的稳定性，PlanParser 中考虑了 JSON 解析容错逻辑，包括去除 Markdown 代码块、处理多余解释文字、校验 steps 是否为空、校验 stepIndex 是否连续、校验 stepType 是否在枚举范围内等。

4. Step 执行链路开发#

今天完成了 Step 执行相关组件开发，主要包括：

StepExecutor；
DefaultStepExecutor；
LlmStepExecutor；
SkillStepExecutor；
StepContextBuilder。

其中，DefaultStepExecutor 作为统一入口，根据 Step 类型决定交给 LLM 执行器还是 Skill 执行器：

对于 INTENT_ANALYSIS、PARAM_EXTRACT、LLM_PROCESS、FINAL_RESPONSE 等类型，由 LlmStepExecutor 执行；
对于 SKILL_CALL 类型，由 SkillStepExecutor 执行。

LlmStepExecutor 的职责是基于用户原始请求、当前 Plan、已完成步骤结果和当前 Step 目标构造上下文，并调用 LLM 完成当前步骤。SkillStepExecutor 则进一步拆分为 Skill 匹配、参数生成、Skill 调用和调用日志记录几个环节。

这种设计保证每个 Step 只完成当前阶段任务，避免模型在单个步骤中越权执行后续任务，也让整体执行链路更加可追踪。

5. Skill 调用与 MCP Gateway 适配#

今天完成了 Agent Skill 调用体系的开发，主要包括：

SkillInvoker 接口；
DefaultSkillInvoker；
LocalSkillInvoker；
McpSkillInvoker；
LocalSkillHandler；
SkillMatcher；
LlmSkillSelector；
SkillArgumentExtractor；
McpClientGatewayAdapter；
McpInvokeConfig。

MVP 阶段的 Skill 调用分为两类：

LOCAL_BEAN：调用本地 Java Skill；
MCP：通过已完成的 MCP Client Gateway 调用外部 MCP Tool。

其中，McpSkillInvoker 通过 McpClientGatewayAdapter 对接前一天完成的 MCP Client Gateway，实现从 Agent Step 到外部 MCP Tool 的适配路径。这样可以复用已有 MCP Gateway 的连接管理、工具调用、参数校验和审计能力，避免 Agent 层直接依赖 MCP SDK。

当前 MCP 类型 Skill 的适配结构已经完成，但文档中也明确记录：MCP 类型 Skill 全链路仍需要后续进一步实测。

6. 管理端桥接与 SSE 流式能力接入#

除 Agent 后端执行引擎外，今天还完成了部分管理端桥接工作，使 Plan-and-Execute Agent 能够接入现有管理端对话流。

主要改动包括：

在 AiAdminChatStreamService 中检测 reasoningMode=plan_execute，并路由到 AgentChatStreamService；
通过 AgentConfigController 提供 /api/ai/v1/agents 相关 Agent 配置 API；
在 AgentChatStreamService 中实现心跳、StepEventListener 和 OpenAI 原生流式输出；
在安全配置中放开 /api/ai/v1/**、/api/mcp/**、/api/agent-runs/** 等路径；
在主应用入口中补充 com.sangfor.agent 相关扫描；
扩展 AgentProfileEntity，增加 icon、category、reasoningMode、modelCardId、published、greeting 等字段；
在前端 ModelChatView 中加入 Agent 选择器，并完成基础 Vue 响应式接入。

当前已实现的 SSE 事件包括：

run_created；
plan_created；
step_started；
step_completed；
message；
done。

这使得 Plan-and-Execute 执行过程不仅能在后端运行，也可以逐步接入前端交互体验。

7. 执行轨迹与可观测能力#

今天还完成了 Agent 执行轨迹相关能力开发。系统可以将 Agent 执行过程中的核心信息落库，包括：

agent_run：记录一次执行；
agent_plan：记录生成的计划；
agent_plan_step：记录每个步骤的执行状态和输出；
agent_tool_call_record：记录 Skill / Tool 调用过程。

根据开发进度文档，目前已验证的能力包括：

Agent 管理 CRUD；
数字人配置落库；
Plan 生成；
Step 顺序执行；
Plan / Step SSE 实时推送；
最终回复 OpenAI 原生流式输出；
Plan 解析容错与兜底计划；
执行轨迹落库。

这部分能力为后续排查问题、查看运行过程、分析 Agent 执行质量提供了基础。

8. 技术文档与开发进度沉淀#

今天在开发过程中同步整理了两份重要文档：

《Spring AI 通用 Agent 平台 MVP 技术实施方案》
该文档明确了 MVP 的目标、边界、核心架构、执行流程、Plan-and-Execute 设计、Skill 调用机制、MCP Gateway 接入方式、数据库设计、接口设计、状态流转、开发顺序和后续扩展方向。
《Agent 工厂模块状态与后续规划》
该文档记录了截至 2026-05-22 的模块状态，包括 MCP Client Gateway、Plan-and-Execute Agent 引擎和管理端桥接的完成情况，同时梳理了已验证能力、已知问题、后续任务和关键文件索引。

这两份文档既是当天开发成果的沉淀，也为后续继续推进前端优化、MCP Skill 实测、本地 Mock Skill、集成测试和 Human-in-the-loop 等能力提供了明确路线。

三、今日工作产出#

完成 Plan-and-Execute Agent 引擎 MVP 主体开发，形成从用户输入到计划生成、步骤执行、Skill 调用和结果汇总的执行闭环。
完成 Agent 相关领域实体、状态枚举、Mapper、配置初始化和数据表设计，为执行轨迹落库提供基础。
完成 Planner 层能力，包括 PlanGenerator、PlanPromptBuilder、PlanParser 和 PlanFallbackFactory。
完成 Executor 层能力，包括 StepExecutor、LlmStepExecutor、SkillStepExecutor 和 StepContextBuilder。
完成 Skill 调用体系，包括 LocalSkillInvoker、McpSkillInvoker、SkillMatcher、SkillArgumentExtractor 和 MCP Gateway 适配组件。
完成管理端桥接，使 reasoningMode=plan_execute 的对话请求可以进入 AgentChatStreamService 执行链路。
完成 Agent 配置 API、SSE 状态事件推送、执行轨迹落库等能力。
沉淀《Spring AI 通用 Agent 平台 MVP 技术实施方案》和《Agent 工厂模块状态与后续规划》，形成可复用的开发和交接资料。

四、遇到的问题与解决情况#

1. Agent MVP 范围容易过大#

问题：Plan-and-Execute Agent 涉及计划生成、步骤执行、Skill 调用、MCP 适配、流式输出、状态追踪等多个模块，如果一次性做完整能力，开发范围容易失控。
处理：在技术方案中明确 MVP 边界，第一阶段只聚焦执行闭环，不做复杂多 Agent 协作、不做正式图编排、不做复杂 ReAct 无限循环、不做复杂 Human-in-the-loop。
结果：开发主线聚焦到 AgentRunService → PlanGenerator → PlanAndExecuteService → StepExecutor → SkillInvoker → ResultSynthesizer 的核心链路，降低了第一版实现复杂度。

2. LLM 生成 Plan 可能存在格式不稳定问题#

问题：PlanGenerator 依赖 LLM 输出结构化 JSON，实际使用中可能出现 Markdown 包装、额外解释文字、字段缺失或 stepType 不规范等问题。
处理：设计 PlanParser 容错策略，并加入 PlanFallbackFactory，在解析失败时生成默认兜底计划。
结果：提升了 Plan 生成链路的鲁棒性，避免单次 LLM 输出异常导致整个 Agent 执行失败。

3. 前端流式渲染仍需优化#

问题：当前前端流式渲染不够流畅，存在 Vue 响应式批处理与 SSE 逐 token 推送之间不完全匹配的问题。
处理：已在模块状态文档中将其列为 P0 问题，后续计划采用 requestAnimationFrame 或微小延迟优化逐 token 渲染。
结果：问题已明确定位并进入后续优化计划，不影响当前后端 Agent 主链路继续推进。

4. MCP 类型 Skill 仍需全链路实测#

问题：MCP Skill 适配组件已经完成，但从 Agent 生成 Plan 到匹配 MCP Skill，再通过 MCP Client Gateway 调用外部工具的全链路仍需进一步验证。
处理：当前先完成 McpSkillInvoker 和 McpClientGatewayAdapter 结构开发，将 MCP 对接测试列入后续 P1 任务。
结果：当前架构已具备 MCP 接入路径，后续可通过注册 MCP Server、同步工具、绑定 Agent、对话调用进行完整验证。

五、今日个人理解#

今天的开发让我对 Agent 装配工厂的核心执行层有了更清晰的认识。前一天完成 MCP Client Gateway 后，平台已经具备了“工具接入底座”；今天完成 Plan-and-Execute Agent 引擎后，平台进一步具备了“任务规划与执行内核”。

我理解的 Plan-and-Execute Agent 不是简单地让大模型直接回答用户，而是先把用户请求拆解成可追踪的计划，再按步骤执行。每个 Step 都有明确的目标、类型、状态和输出，Skill 调用也会被记录到 ToolCallRecord 中。这样一来，Agent 的执行过程就不再是黑盒，而是可以查看、追踪和后续优化的工程链路。

同时，我也进一步认识到 MVP 阶段的关键不是追求复杂能力，而是先跑通主链路。只要 Agent 能完成 Plan 生成、Step 顺序执行、Skill 调用、结果汇总和轨迹落库，后续再扩展 Human-in-the-loop、失败重试、知识库增强、多 Agent 协作和图编排才有基础。

六、后续待明确问题#

MCP 类型 Skill 是否能在真实外部 MCP Server 场景下完整跑通；
Local Mock Skill 是否需要补充标准测试场景；
前端 SSE 流式渲染如何进一步优化；
Qwen 推理模型是否需要关闭 thinking 模式，避免 token 集中输出；
Step 输出中嵌套 JSON / Markdown 包装如何进一步清洗；
PlanParser 容错测试和全链路集成测试是否需要补齐；
后续是否需要在 Plan 生成阶段也输出 LLM 思考过程；
Human-in-the-loop 节点应在什么版本中接入；
数字人广场、Agent 模板复制、版本管理等管理端能力如何安排开发优先级。

七、明日/后续计划#

优先优化前端流式渲染，使 Step 状态和最终回复能够更平滑地展示给用户。
在 OpenAI 兼容流式客户端中评估关闭 Qwen thinking 模式，减少 content 阶段 token 集中到达的问题。
补充 step_started 事件前端渲染，在等待过程中展示“正在执行”状态，提升交互反馈。
实现本地 Mock Skill，例如 MockPaymentStatusHandler，用于验证 LOCAL_BEAN Skill 调用链路。
推进 MCP 对接测试，完成注册 MCP Server、工具发现、绑定 Agent、对话中调用的完整验证。
补充 PlanParser 容错测试和 Plan-and-Execute 全链路集成测试。
继续完善模块状态文档，记录后续问题修复和能力扩展情况。

八、今日总结#

今天主要围绕智能体管理平台的 Plan-and-Execute Agent 引擎展开开发，完成了 Agent 执行入口、计划生成、步骤执行、Skill 调用、MCP Gateway 适配、SSE 状态推送和执行轨迹落库等核心能力。通过今天的工作，平台从“具备 MCP 工具接入能力”进一步升级为“具备 Agent 执行内核”，为后续完善 Skill 实测、前端流式体验、Human-in-the-loop 和多 Agent 扩展奠定了基础。