@@ -13,55 +13,219 @@ import (
llmservice "github.com/LoveLosita/smartflow/backend/services/llm"
)
// execute 阶段常量：
// 1. 统一约束 execute 节点在流式输出、上下文挂载、历史标记中的固定标识；
// 2. 这些值会在 prompt、stream、history、tool runtime 多处复用，集中定义可避免字符串散落；
// 3. 报告里可将其理解为 execute 节点的“协议层元数据”，负责让编排层、展示层和执行层说同一种语言。
const (
= "execute"
executeStatusBlockID = "execute.status"
executeSpeakBlockID = "execute.speak "
executePinnedKey = "execution_context"
toolAnalyzeHealth = "analyze_health"
executeHistoryKindKey = "newagent_history_kind"
// executeStageName 是 graph/node/stream 共同识别的执行阶段名。
// 调用目的：用于状态推送、日志埋点、终止态写入时标识“当前发生在 execute 阶段”。
executeStageName = "execute"
// executeStatusBlockID 是前端状态区块 ID。
// 调用目的：把“正在执行第几步”“工具执行中”等状态稳定写到同一个可更新区块，避免重复刷屏。
executeStatusBlockID = "execute.status"
// executeSpeakBlockID 是 execute 阶段可见回复文本的输出区块 ID。
// 调用目的：让模型在 execute 阶段产生的正文、补发文本、thinking 摘要归并到同一个展示区域。
executeSpeakBlockID = "execute.speak"
// executePinnedKey 是 execute 专属 pinned context 的 key。
// 调用目的： ，
executePinnedKey = "execution_context"
// toolAnalyzeHealth 是粗排后健康度分析工具名。
// 调用目的：在主动优化链路中复用固定工具标识，避免分支判断时手写魔法字符串。
toolAnalyzeHealth = "analyze_health"
// executeHistoryKindKey 是 execute 阶段写入 history extra 时使用的分类 key。
// 调用目的：给某些“无正文但有语义”的历史记录打标签，方便后续节点识别这是系统插入的流程标记。
executeHistoryKindKey = "newagent_history_kind"
// executeHistoryKindStepAdvanced 表示“计划步骤已推进”的历史标记值。
// 调用目的：在 next_plan 后往历史里写一个轻量哨兵，避免重复推进时无法判断上一步是否已切换。
executeHistoryKindStepAdvanced = "execute_step_advanced"
// maxConsecutiveCorrections 是 execute 阶段允许的最大连续纠错次数。
// 调用目的：限制模型在 JSON 解析失败、动作不合法、goal_check 缺失等异常情况下的自我修正轮数，防止无限空转。
maxConsecutiveCorrections = 3
)
// ExecuteNodeInput 描述 execute 节点单轮运行所需的全部输入依赖。
//
// 职责边界：
// 1. 负责承载 execute 节点真正运行时要读到的“状态 + 上下文 + 模型 + 工具 + 输出能力”；
// 2. 不负责 graph 拓扑与分支决策，这些仍由 compose.Graph 和 branchAfterExecute 管理；
// 3. 不负责具体工具实现或 LLM 协议细节，它只是 node 层与下游能力之间的依赖注入容器。
//
// 报告可重点说明：
// 1. 这个结构体体现了本项目如何把 Eino agent 的单节点执行显式建模为一个“有完整依赖注入边界”的入口；
// 2. 与把所有依赖散落在全局变量不同，这种做法更便于恢复执行、单测替身注入和不同模型/工具组合切换；
// 3. execute 节点能否安全回环，核心就在于这些输入把“状态、上下文、工具、输出”完整串起来了。
type ExecuteNodeInput struct {
* agentmodel . AgentRuntimeState
ConversationContext * agentmodel . ConversationContext
UserInput string
Client * llmservice . Client
ChunkEmit ter * agentstream . ChunkEmit ter
ResumeNode string
ToolRegistry * agenttools . ToolRegistry
ScheduleState * schedule . ScheduleState
CompactionStore agentmodel . CompactionStore
WriteSchedulePreview agentmodel . WriteSchedulePreviewFunc
// RuntimeState 是 execute 节点的主运行态容器。
// 1. 负责承载 CommonState、待确认工具、待追问交互等跨轮次状态；
// 2. execute 节点对 phase、round、plan step、pending interaction 的修改都会落到这里；
// 3. 若为空则无法恢复和推进 agent 执行，因此 prepareExecuteNodeInput 会把它视为必填依赖。
RuntimeSta te * agentmodel . AgentRuntimeSta te
// ConversationContext 是当前会话的统一上下文快照。
// 1. 负责保存历史消息、pinned block、工具 schema 等 prompt 装配素材；
// 2. execute 每一轮都会基于它重建 Eino message；
// 3. 它不是持久化存储本身，而是当前 graph 运行时使用的内存态上下文。
ConversationContext * agentmodel . ConversationContext
// UserInput 是本轮用户原始输入文本。
// 1. 主要用于让 execute 节点在必要时回看用户当前明确意图；
// 2. 不直接等价于最终 prompt，
// 3. 保留该字段是为了让 execute 在恢复、追问、纠错时仍能感知本轮入口意图。
UserInput string
// Client 是 execute 阶段专用 LLM 客户端。
// 1. 负责发起流式推理请求，生成结构化 SMARTFLOW_DECISION；
// 2. 它可以与 chat / plan / deliver 阶段使用不同模型配置；
// 3. 若未注入，
Client * llmservice . Client
// ChunkEmitter 是流式输出器。
// 1. 负责把状态、正文、thinking 摘要、工具调用过程实时推给前端；
// 2. execute 节点的大部分用户可见体验都经由它完成；
// 3. 即使外部没接真实前端，系统也会兜底一个 noop emitter，
ChunkEmitter * agentstream . ChunkEmitter
// ResumeNode 表示挂起交互恢复后应回到的节点名。
// 1. 主要用于 ask_user / confirm 之后恢复 graph 时定位回 execute；
// 2. 它是 pending interaction 与 graph 路由之间的衔接信息；
// 3. 当前通常写为 "execute"，便于中断后继续原执行链路。
ResumeNode string
// ToolRegistry 是 execute 阶段可调用工具的统一注册表。
// 1. 负责提供工具 schema、工具可见性判断和真正的工具执行入口；
// 2. execute 不直接依赖具体工具实现，而是通过注册表做统一调度；
// 3. 这让 agent 的工具能力可以按域动态裁剪，而不必修改 execute 主流程。
ToolRegistry * agenttools . ToolRegistry
// ScheduleState 是当前排程态快照。
// 1. 只有涉及日程构建、挪动、交换等排程工具时才会被真正消费；
// 2. 首轮 execute 会对它做必要初始化，后续轮次复用同一份内存状态；
// 3. 该字段为空时，依赖日程状态的工具会被阻止执行，避免工具在残缺状态上落地。
ScheduleState * schedule . ScheduleState
// CompactionStore 是消息压缩存储依赖。
// 1. 当上下文过长时，
// 2. 目的是在长链路中控制 token 成本，同时尽量保留关键执行语义；
// 3. 这是长流程 agent 可持续运行的重要辅助能力，而非核心业务状态。
CompactionStore agentmodel . CompactionStore
// WriteSchedulePreview 是排程预览写入函数。
// 1. 当 execute 阶段调用写排程工具后，可实时把最新预览写给前端/缓存；
// 2. 它只负责预览落盘，不负责真正修改 graph 路由或业务状态；
// 3. 这样用户在确认或微调过程中就能看到中间结果，而不必等到最终 deliver。
WriteSchedulePreview agentmodel . WriteSchedulePreviewFunc
// OriginalScheduleState 是进入本轮执行前的原始排程快照。
// 1. 主要用于需要对比、确认、恢复时保留“变更前基线”；
// 2. executePendingTool 等恢复场景可能会用到这份原始视角；
// 3. 它不是当前正在被修改的工作态，当前工作态仍是 ScheduleState。
OriginalScheduleState * schedule . ScheduleState
AlwaysExecute bool
ThinkingEnabled bool
// AlwaysExecute 表示是否跳过确认直接执行写工具。
// 1. 为 true 时，
// 2. 为 false 时，高风险写工具需先转成 pending confirm， ；
// 3. 这给不同入口场景（自动执行/显式确认）保留了统一的 execute 主流程。
AlwaysExecute bool
// ThinkingEnabled 控制 execute 阶段是否开启 reasoning/thinking 模式。
// 1. 它影响 LLM 请求时的推理模式选择；
// 2. 开启后系统会额外汇总 reasoning 摘要并推送给前端；
// 3. 该能力只影响模型推理表现，不改变 execute 节点的状态机协议。
ThinkingEnabled bool
// PersistVisibleMessage 是可见消息持久化函数。
// 1. 负责把应落库的 assistant 可见回复保存下来，供后续历史回放；
// 2. execute 不直接操作数据库，而是通过该函数把持久化职责下沉；
// 3. 这样 node 层仍保持“编排与调度”为主，不把存储细节耦合进来。
PersistVisibleMessage agentmodel . PersistVisibleMessageFunc
}
// ExecuteRoundObservation 描述 execute 阶段单轮观测结果。
//
// 职责边界：
// 1. 负责记录一轮 execute 中“模型做了什么决策、调用了什么工具、结果如何”；
// 2. 不负责承载完整上下文或最终业务结果，它更偏向调试、回放、分析视角；
// 3. 该结构体的价值在于把 agent 的单轮行为沉淀成可审计、可解释的数据切片。
type ExecuteRoundObservation struct {
int ` json:"round" `
StepIndex int ` json:"step_index" `
GoalCheck str ing ` json:"goal_check,omitempty " `
Decision string ` json:"decision,omitempty" `
ToolName string ` json:"tool_name,omitempty" `
ToolParams string ` json:"tool_params,omitempty" `
ToolSuccess bool ` json:"tool_success "`
ToolResult string ` json:"tool_result,omitempty" `
// Round 是执行轮次编号。
// 调用目的：标识这是第几轮 execute 回环，便于分析 agent 是否在某一步反复空转。
Round t ` json:"round " `
// StepIndex 是当前计划步骤索引。
// 调用目的：把本轮行为与 plan 中的具体步骤关联起来，支持“第几步发生了什么”这类复盘。
StepIndex int ` json:"step_index "`
// GoalCheck 是模型在 next_plan / done 时给出的完成性核验说明。
// 调用目的：保留“为什么它认为当前步骤已完成”的证据文本，增强 agent 行为可解释性。
GoalCheck string ` json:"goal_check,omitempty" `
// Decision 是本轮结构化决策动作摘要。
// 调用目的：记录 action 层面的选择结果，如 continue / confirm / ask_user / done。
Decision string ` json:"decision,omitempty" `
// ToolName 是本轮调用的工具名。
// 调用目的：标识 agent 在这一轮真正把哪项外部能力接入执行链。
ToolName string ` json:"tool_name,omitempty" `
// ToolParams 是工具调用参数的可读化快照。
// 调用目的：辅助排查“工具为什么执行出这个结果”，但它只保留观测视图，不替代真实原始参数对象。
ToolParams string ` json:"tool_params,omitempty" `
// ToolSuccess 表示工具是否执行成功。
// 调用目的：在轮次观测里快速区分“正常推进”与“工具失败/被阻断”的分支结果。
ToolSuccess bool ` json:"tool_success" `
// ToolResult 是工具返回结果的摘要文本。
// 调用目的：保留工具观察结果，供下一轮上下文构造、日志调试或报告中的执行链路说明使用。
ToolResult string ` json:"tool_result,omitempty" `
}
// RunExecuteNode 是 Eino agent graph 中 execute 节点的“单轮执行入口”。
//
// 职责边界：
// 1. 负责把 graph 层传入的运行态、会话上下文、工具目录、流式输出器等依赖整理成一次可执行的 execute 轮次。
// 2. 负责完成 execute 阶段的一次完整闭环：状态校准 -> 提示词装配 -> LLM 决策 -> 决策落地。
// 3. 不负责定义 Eino graph 的节点拓扑；节点注册、连边与回环由 graph/common_graph.go 中的 compose.Graph 统一管理。
// 4. 不负责具体工具实现和流式 JSON 解析细节；工具执行下沉到 tool_runtime.go，
//
// 报告可重点说明：
// 1. 这个函数体现了“Graph 负责编排、Node 负责单轮执行”的 Eino 接入方式。
// 2. execute 节点不是直接把用户请求一次性做完，而是以“轮次”为单位驱动 ReAct/Plan-and-Execute 风格的 agent 闭环。
// 3. 每一轮都会基于当前状态重建 Eino message， ，
func RunExecuteNode ( ctx context . Context , input ExecuteNodeInput ) error {
// 1. 先做 execute 节点入参归一化：
// 1.1 这里会兜底 RuntimeState / ConversationContext / ChunkEmitter，
// 1.2 execute 节点后续所有状态推进都依赖这三类对象，因此必须在第一步统一校准；
// 1.3 若最基础的依赖（如 RuntimeState、LLM Client） ， ，
runtimeState , conversationContext , emitter , err := prepareExecuteNodeInput ( input )
if err != nil {
return err
}
// 2. 取出 graph 内部跨节点共享的 CommonState。
// 2.1 Chat / Plan / RoughBuild / Execute 都围绕这份状态协作；
// 2.2 execute 节点真正关心的“当前阶段、计划步、轮次预算、工具域、终止态”等信息都挂在这里；
// 2.3 这也是 Eino graph 在多节点之间传递 agent 运行语义的核心载体。
flowState := runtimeState . EnsureCommonState ( )
// 3. 应用待生效的上下文 hook。
// 3.1 上游节点（如 plan / rough_build） ， ；
// 3.2 execute 节点在真正请求模型前统一消费这个 hook， ；
// 3.3 若这里不先同步，模型第一轮可能拿到旧工具域，导致它想做的动作与实际可见工具不一致。
applyPendingContextHook ( flowState )
// 4. 若当前存在“待确认写工具”，说明上一轮已经完成了 LLM 决策，本轮是用户确认后的恢复执行。
// 4.1 这时不应该再让模型重新思考，否则会破坏“确认后执行原工具”的事务语义；
// 4.2 因此这里直接短路进入 executePendingTool， ；
// 4.3 这也是本项目把“模型决策”和“高风险写操作落地”显式拆开的关键安全设计。
if runtimeState . PendingConfirmTool != nil {
return executePendingTool (
ctx ,
@@ -75,12 +239,24 @@ func RunExecuteNode(ctx context.Context, input ExecuteNodeInput) error {
)
}
// 5. 首轮进入 execute 且携带日程状态时，重置任务处理队列。
// 5.1 这样可以保证一次新的执行会话从干净的调度处理顺序开始；
// 5.2 只在 RoundUsed == 0 时重置，避免多轮 execute 回环过程中把中间状态反复抹掉；
// 5.3 这类“首轮初始化、后续轮次复用”的策略，是 agent 在长流程里保持状态连续性的基础。
if input . ScheduleState != nil && flowState . RoundUsed == 0 {
schedule . ResetTaskProcessingQueue ( input . ScheduleState )
}
// 6. 把 execute 阶段的关键信息同步到会话 pinned context。
// 6.1 这里会把执行模式、当前计划步、done_when、轮次预算等内容写成可复用的上下文块；
// 6.2 后续 BuildExecuteMessages 会把这些 pinned block 一并装配进 Eino message；
// 6.3 这样模型每轮都能看到“当前执行到哪一步、什么算完成”，避免在长对话里丢失阶段感。
syncExecutePinnedContext ( conversationContext , flowState )
// 7. 先向前端推送 execute 阶段状态，让用户看到 agent 当前正在做什么。
// 7.1 若当前处于 plan 模式，就明确展示“第几步 / 共几步 + 当前步骤摘要”；
// 7.2 若没有计划，则退化为通用“正在处理请求”文案；
// 7.3 这里的状态推送不影响 graph 路由，但会直接影响产品侧的可观察性与交互体验。
if flowState . HasCurrentPlanStep ( ) {
current , total := flowState . PlanProgress ( )
currentStep , _ := flowState . CurrentPlanStep ( )
@@ -105,6 +281,10 @@ func RunExecuteNode(ctx context.Context, input ExecuteNodeInput) error {
}
}
// 8. 进入真正的模型决策前，先消费一轮执行预算。
// 8.1 execute 节点在 Eino graph 中是允许回环的；
// 8.2 NextRound() 失败时，不再继续请求模型，而是把“达到安全轮次上限”的终止原因写入状态；
// 8.3 这样 deliver 节点后续收口时可以读取统一的 terminal outcome，
if ! flowState . NextRound ( ) {
flowState . Exhaust (
executeStageName ,
@@ -114,7 +294,16 @@ func RunExecuteNode(ctx context.Context, input ExecuteNodeInput) error {
return nil
}
// 9. 基于当前 flowState + ConversationContext 重新构建本轮要发给模型的消息。
// 9.1 BuildExecuteMessages 会产出 []*schema.Message，
// 9.2 消息里不仅有历史对话，还会带上 execute 专属系统提示词、计划步骤约束、工具 schema、pinned context；
// 9.3 这一步体现了本项目的核心思想：不是把 Agent 写死成 if/else，
messages := agentprompt . BuildExecuteMessages ( flowState , conversationContext )
// 10. 若上下文过长，则在真正调用模型前统一压缩消息。
// 10.1 压缩逻辑仍围绕统一的 Eino message 结构工作，不破坏后续模型调用接口；
// 10.2 这样既能控制 token 成本，又能尽量保住当前步骤、工具观察、关键 pinned 信息；
// 10.3 对长流程 agent 来说，这一步是“让多轮执行可持续”的关键工程补偿层。
messages = agentshared . CompactUnifiedMessagesIfNeeded ( ctx , messages , agentshared . UnifiedCompactInput {
Client : input . Client ,
CompactionStore : input . CompactionStore ,
@@ -124,8 +313,15 @@ func RunExecuteNode(ctx context.Context, input ExecuteNodeInput) error {
StatusBlockID : executeStatusBlockID ,
} )
// 11. 在发起模型请求前记录本轮 LLM 上下文快照，便于排查“为什么模型会做出这个动作”。
// 11.1 这类日志不参与业务逻辑，但对调试 agent prompt、状态迁移和工具选择非常重要；
// 11.2 尤其在 execute 回环链路里，它能帮助我们复盘每一轮看到的上下文是否一致。
agentshared . LogNodeLLMContext ( executeStageName , "decision" , flowState , messages )
// 12. 调用模型，流式采集 execute 决策。
// 12.1 下游会使用 Eino 风格的 message 输入向 LLM 发起 Stream 请求；
// 12.2 模型需要输出 <SMARTFLOW_DECISION>{...}</SMARTFLOW_DECISION> 结构化决策，再附带可见回答；
// 12.3 这里拿到的不是“最终答案”，而是 agent 下一步动作的机器可执行描述：继续读工具、请求确认、追问用户、推进计划或结束。
decisionOutput , err := collectExecuteDecisionFromLLM (
ctx ,
input ,
@@ -138,6 +334,10 @@ func RunExecuteNode(ctx context.Context, input ExecuteNodeInput) error {
return err
}
// 13. 把模型决策真正落到运行时。
// 13.1 handleExecuteDecision 会校验 action 合法性，并根据决策修改 flowState / runtimeState / conversation history；
// 13.2 若是 continue + tool_call， ； ， ； ， ；
// 13.3 至此，一次 execute 节点的“思考 + 行动”闭环完成， ，
return handleExecuteDecision (
ctx ,
input ,
Losita