Version: 0.8.5.dev.260330
后端： 1.把node/plan的具体逻辑做完了,没仔细看，进入下一步之前需要仔细review 前端： 无改动 全仓库： 无改动
This commit is contained in:
Losita
@@ -1,6 +1,6 @@
|
||||
package model
|
||||
|
||||
// Phase 表示 agent 循环图当前所处的阶段。
|
||||
// Phase 表示 agent 主循环当前所处的大阶段。
|
||||
type Phase string
|
||||
|
||||
const (
|
||||
@@ -12,8 +12,14 @@ const (
|
||||
|
||||
const DefaultMaxRounds = 30
|
||||
|
||||
// CommonState 承载可持久化的主流程状态。
|
||||
//
|
||||
// 职责边界：
|
||||
// 1. 负责记录“当前处于哪个阶段、当前计划是什么、执行到了第几步、已经消耗了多少轮”；
|
||||
// 2. 负责提供最小必要的安全访问方法，避免 graph/node/prompt 层到处手写切片越界判断；
|
||||
// 3. 不负责承载对话历史、tool schema、pinned context 这类模型输入材料，它们仍然属于 ConversationContext。
|
||||
type CommonState struct {
|
||||
// 身份
|
||||
// 身份信息
|
||||
TraceID string
|
||||
UserID int
|
||||
ConversationID string
|
||||
@@ -21,8 +27,10 @@ type CommonState struct {
|
||||
// 流程阶段
|
||||
Phase Phase
|
||||
|
||||
// Plan
|
||||
PlanSteps []string
|
||||
// 计划状态
|
||||
// 1. 这里直接使用结构化的 PlanStep，避免 planning -> execute 之间丢失 done_when。
|
||||
// 2. CurrentStep 表示“当前 plan 步骤下标”，不是 execute 内部 ReAct 的思考轮次。
|
||||
PlanSteps []PlanStep
|
||||
CurrentStep int
|
||||
|
||||
// 安全边界
|
||||
@@ -40,53 +48,58 @@ func NewCommonState(traceID string, userID int, conversationID string) *CommonSt
|
||||
}
|
||||
}
|
||||
|
||||
// NextRound 消耗一轮并返回是否还有余量。
|
||||
// NextRound 消耗一轮预算，并返回当前是否仍在允许范围内。
|
||||
func (s *CommonState) NextRound() bool {
|
||||
s.RoundUsed++
|
||||
return s.RoundUsed <= s.MaxRounds
|
||||
}
|
||||
|
||||
// Exhausted 判断是否已耗尽轮次。
|
||||
// Exhausted 判断是否已经耗尽轮次预算。
|
||||
func (s *CommonState) Exhausted() bool {
|
||||
return s.RoundUsed >= s.MaxRounds
|
||||
}
|
||||
|
||||
// FinishPlan 标记 plan 完成，进入等待确认阶段。
|
||||
func (s *CommonState) FinishPlan(steps []string) {
|
||||
// FinishPlan 在 planning 完成后固化完整计划，并推进到待确认阶段。
|
||||
//
|
||||
// 步骤说明：
|
||||
// 1. 直接保存完整的 []PlanStep，避免 execute 阶段再去依赖 pinned context 回捞完成判定；
|
||||
// 2. 统一把 CurrentStep 重置到第 0 步，保证后续 confirm/execute 都从计划开头进入；
|
||||
// 3. 这里只负责状态切换，不负责刷新 ConversationContext 中的置顶 plan 文本。
|
||||
func (s *CommonState) FinishPlan(steps []PlanStep) {
|
||||
s.PlanSteps = steps
|
||||
s.CurrentStep = 0
|
||||
s.Phase = PhaseWaitingConfirm
|
||||
}
|
||||
|
||||
// ConfirmPlan 用户确认后进入执行阶段。
|
||||
// ConfirmPlan 表示用户已确认计划，流程进入执行阶段。
|
||||
func (s *CommonState) ConfirmPlan() {
|
||||
s.Phase = PhaseExecuting
|
||||
}
|
||||
|
||||
// RejectPlan 用户拒绝，回到规划阶段。
|
||||
// RejectPlan 表示用户拒绝当前计划，清空计划并回退到 planning。
|
||||
func (s *CommonState) RejectPlan() {
|
||||
s.PlanSteps = nil
|
||||
s.CurrentStep = 0
|
||||
s.Phase = PhasePlanning
|
||||
}
|
||||
|
||||
// AdvanceStep 推进到下一个 plan 步骤，返回是否还有剩余步骤。
|
||||
// AdvanceStep 推进到下一个计划步骤，并返回是否仍有剩余步骤。
|
||||
func (s *CommonState) AdvanceStep() bool {
|
||||
s.CurrentStep++
|
||||
return s.CurrentStep < len(s.PlanSteps)
|
||||
}
|
||||
|
||||
// Done 标记整个流程结束。
|
||||
// Done 标记整个任务流程已经结束。
|
||||
func (s *CommonState) Done() {
|
||||
s.Phase = PhaseDone
|
||||
}
|
||||
|
||||
// HasPlan 判断当前 state 是否已经持有一份可执行的 plan。
|
||||
// HasPlan 判断当前 state 是否已经持有一份完整计划。
|
||||
//
|
||||
// 职责边界：
|
||||
// 1. 负责把“外部直接判断 len(PlanSteps) > 0”的零散逻辑收口到 state 内部；
|
||||
// 2. 只回答“是否存在 plan”，不判断当前索引是否有效；
|
||||
// 3. 当 state 为空时返回 false，调用方可据此决定是否回退到重新规划。
|
||||
// 1. 负责收口“是否存在 plan”这一层判断，避免外层到处写 len(PlanSteps) > 0；
|
||||
// 2. 不判断 CurrentStep 当前是否有效，当前步骤是否合法由 HasCurrentPlanStep 回答；
|
||||
// 3. state 为空时统一返回 false，调用方可据此决定是否回退到 planning。
|
||||
func (s *CommonState) HasPlan() bool {
|
||||
if s == nil {
|
||||
return false
|
||||
@@ -94,40 +107,35 @@ func (s *CommonState) HasPlan() bool {
|
||||
return len(s.PlanSteps) > 0
|
||||
}
|
||||
|
||||
// CurrentPlanStep 返回当前正在执行的 plan 步骤文本。
|
||||
// CurrentPlanStep 返回当前正在执行的结构化计划步骤。
|
||||
//
|
||||
// 职责边界：
|
||||
// 1. 负责根据 CurrentStep 安全读取 PlanSteps，避免调用方重复写切片越界判断；
|
||||
// 2. 当 state 为空、plan 为空、或当前索引越界时，统一返回 ("", false)；
|
||||
// 1. 负责根据 CurrentStep 安全读取 PlanSteps，避免 graph/node/prompt 层重复写越界判断；
|
||||
// 2. 若 state 为空、plan 为空、或当前索引越界，则统一返回 (PlanStep{}, false)；
|
||||
// 3. 不负责推进步骤，也不负责修正 CurrentStep 的取值。
|
||||
func (s *CommonState) CurrentPlanStep() (string, bool) {
|
||||
func (s *CommonState) CurrentPlanStep() (PlanStep, bool) {
|
||||
if s == nil {
|
||||
return "", false
|
||||
return PlanStep{}, false
|
||||
}
|
||||
if s.CurrentStep < 0 || s.CurrentStep >= len(s.PlanSteps) {
|
||||
return "", false
|
||||
return PlanStep{}, false
|
||||
}
|
||||
return s.PlanSteps[s.CurrentStep], true
|
||||
}
|
||||
|
||||
// HasCurrentPlanStep 判断“当前步骤”是否存在且可安全读取。
|
||||
//
|
||||
// 职责边界：
|
||||
// 1. 负责给 graph / node 层提供一个更直白的布尔判断入口；
|
||||
// 2. 内部复用 CurrentPlanStep，避免两处维护相同的索引边界逻辑；
|
||||
// 3. 不返回步骤内容，只回答“当前是否还有可注入的步骤”。
|
||||
func (s *CommonState) HasCurrentPlanStep() bool {
|
||||
_, ok := s.CurrentPlanStep()
|
||||
return ok
|
||||
}
|
||||
|
||||
// PlanProgress 返回当前 plan 的执行进度。
|
||||
// PlanProgress 返回当前计划的执行进度。
|
||||
//
|
||||
// 输出语义：
|
||||
// 1. current 使用对人类更友好的 1-based 序号，适合直接写入 prompt 或日志；
|
||||
// 2. total 表示当前 plan 总步数；
|
||||
// 3. 若尚未生成 plan，则返回 (0, 0)；
|
||||
// 4. 若 CurrentStep 已越过末尾，则 current 会被收敛到 total，避免上层出现 total+1 这类噪音值。
|
||||
// 1. current 使用更适合给用户看的 1-based 序号；
|
||||
// 2. total 表示当前计划的总步数；
|
||||
// 3. 若当前还没有计划，则返回 (0, 0)；
|
||||
// 4. 若 CurrentStep 已越界到末尾之后，则把 current 收敛到 total，避免出现 total+1 这种噪音值。
|
||||
func (s *CommonState) PlanProgress() (current int, total int) {
|
||||
if s == nil {
|
||||
return 0, 0
|
||||
|
||||
193
backend/newAgent/model/graph_run_state.go
Normal file
193
backend/newAgent/model/graph_run_state.go
Normal file
@@ -0,0 +1,193 @@
|
||||
package model
|
||||
|
||||
import (
|
||||
"strings"
|
||||
|
||||
newagentllm "github.com/LoveLosita/smartflow/backend/newAgent/llm"
|
||||
newagentstream "github.com/LoveLosita/smartflow/backend/newAgent/stream"
|
||||
)
|
||||
|
||||
// AgentGraphRequest 描述一次 agent graph 运行的请求级输入。
|
||||
//
|
||||
// 职责边界：
|
||||
// 1. 这里只放“当前这次请求”天然携带的轻量数据，例如用户本轮输入；
|
||||
// 2. 不负责承载可持久化流程状态，流程状态仍归 AgentRuntimeState；
|
||||
// 3. 不负责承载 LLM / emitter / store 等依赖，这些统一放进 AgentGraphDeps。
|
||||
type AgentGraphRequest struct {
|
||||
UserInput string
|
||||
}
|
||||
|
||||
// Normalize 统一清洗请求级输入中的字符串字段。
|
||||
func (r *AgentGraphRequest) Normalize() {
|
||||
if r == nil {
|
||||
return
|
||||
}
|
||||
r.UserInput = strings.TrimSpace(r.UserInput)
|
||||
}
|
||||
|
||||
// AgentGraphDeps 描述 graph/node 层运行时真正依赖的可插拔能力。
|
||||
//
|
||||
// 设计目的：
|
||||
// 1. 让 graph 不再只拿到“裸状态”，而是能拿到上下文、模型和输出能力；
|
||||
// 2. Chat/Plan/Execute/Deliver 允许分别挂不同 client，但也允许先复用同一个 client；
|
||||
// 3. ChunkEmitter 统一承接阶段提示、正文、工具事件、确认请求等 SSE 输出。
|
||||
type AgentGraphDeps struct {
|
||||
ChatClient *newagentllm.Client
|
||||
PlanClient *newagentllm.Client
|
||||
ExecuteClient *newagentllm.Client
|
||||
DeliverClient *newagentllm.Client
|
||||
ChunkEmitter *newagentstream.ChunkEmitter
|
||||
}
|
||||
|
||||
// EnsureChunkEmitter 保证 graph 运行时始终有一个可用的 chunk 发射器。
|
||||
//
|
||||
// 步骤说明：
|
||||
// 1. 依赖为空时回退到 Noop emitter，避免骨架期因为没接前端而到处判空；
|
||||
// 2. 这里只兜底“能安全调用”，不负责填充真实 request_id / model_name；
|
||||
// 3. 后续 service 层一旦接上真实 emitter，会自然覆盖这里的空实现。
|
||||
func (d *AgentGraphDeps) EnsureChunkEmitter() *newagentstream.ChunkEmitter {
|
||||
if d == nil {
|
||||
return newagentstream.NewChunkEmitter(newagentstream.NoopPayloadEmitter(), "", "", 0)
|
||||
}
|
||||
if d.ChunkEmitter == nil {
|
||||
d.ChunkEmitter = newagentstream.NewChunkEmitter(newagentstream.NoopPayloadEmitter(), "", "", 0)
|
||||
}
|
||||
return d.ChunkEmitter
|
||||
}
|
||||
|
||||
// ResolveChatClient 返回 chat 阶段可用的模型客户端。
|
||||
func (d *AgentGraphDeps) ResolveChatClient() *newagentllm.Client {
|
||||
if d == nil {
|
||||
return nil
|
||||
}
|
||||
return d.ChatClient
|
||||
}
|
||||
|
||||
// ResolvePlanClient 返回 planning 阶段可用的模型客户端。
|
||||
//
|
||||
// 兜底策略：
|
||||
// 1. 优先使用显式注入的 PlanClient；
|
||||
// 2. 若未单独注入，则回退到 ChatClient；
|
||||
// 3. 这样在骨架期可先用一套 client 跑通，再按需拆分 strategist / worker。
|
||||
func (d *AgentGraphDeps) ResolvePlanClient() *newagentllm.Client {
|
||||
if d == nil {
|
||||
return nil
|
||||
}
|
||||
if d.PlanClient != nil {
|
||||
return d.PlanClient
|
||||
}
|
||||
return d.ChatClient
|
||||
}
|
||||
|
||||
// ResolveExecuteClient 返回 execute 阶段可用的模型客户端。
|
||||
func (d *AgentGraphDeps) ResolveExecuteClient() *newagentllm.Client {
|
||||
if d == nil {
|
||||
return nil
|
||||
}
|
||||
if d.ExecuteClient != nil {
|
||||
return d.ExecuteClient
|
||||
}
|
||||
if d.PlanClient != nil {
|
||||
return d.PlanClient
|
||||
}
|
||||
return d.ChatClient
|
||||
}
|
||||
|
||||
// ResolveDeliverClient 返回 deliver 阶段可用的模型客户端。
|
||||
func (d *AgentGraphDeps) ResolveDeliverClient() *newagentllm.Client {
|
||||
if d == nil {
|
||||
return nil
|
||||
}
|
||||
if d.DeliverClient != nil {
|
||||
return d.DeliverClient
|
||||
}
|
||||
if d.ExecuteClient != nil {
|
||||
return d.ExecuteClient
|
||||
}
|
||||
if d.PlanClient != nil {
|
||||
return d.PlanClient
|
||||
}
|
||||
return d.ChatClient
|
||||
}
|
||||
|
||||
// AgentGraphRunInput 是执行 newAgent 通用 graph 所需的完整入口参数。
|
||||
//
|
||||
// 字段说明：
|
||||
// 1. RuntimeState：可持久化流程状态与 pending interaction；
|
||||
// 2. ConversationContext：本轮喂给模型的上下文材料；
|
||||
// 3. Request：当前这次请求的轻量输入；
|
||||
// 4. Deps：graph/node 层真正依赖的可插拔能力。
|
||||
type AgentGraphRunInput struct {
|
||||
RuntimeState *AgentRuntimeState
|
||||
ConversationContext *ConversationContext
|
||||
Request AgentGraphRequest
|
||||
Deps AgentGraphDeps
|
||||
}
|
||||
|
||||
// AgentGraphState 是 graph 内部真正流转的运行态容器。
|
||||
//
|
||||
// 职责边界：
|
||||
// 1. 负责把“流程状态 + 对话上下文 + 请求输入 + 运行依赖”收口到同一个对象；
|
||||
// 2. 负责给 graph 分支和 node 提供最小必要的兜底访问方法；
|
||||
// 3. 不负责持久化，不负责真正业务执行。
|
||||
type AgentGraphState struct {
|
||||
RuntimeState *AgentRuntimeState
|
||||
ConversationContext *ConversationContext
|
||||
Request AgentGraphRequest
|
||||
Deps AgentGraphDeps
|
||||
}
|
||||
|
||||
// NewAgentGraphState 把入口参数整理成 graph 内部状态。
|
||||
func NewAgentGraphState(input AgentGraphRunInput) *AgentGraphState {
|
||||
st := &AgentGraphState{
|
||||
RuntimeState: input.RuntimeState,
|
||||
ConversationContext: input.ConversationContext,
|
||||
Request: input.Request,
|
||||
Deps: input.Deps,
|
||||
}
|
||||
st.Request.Normalize()
|
||||
st.EnsureRuntimeState()
|
||||
st.EnsureConversationContext()
|
||||
st.Deps.EnsureChunkEmitter()
|
||||
return st
|
||||
}
|
||||
|
||||
// EnsureRuntimeState 保证 graph 内部始终持有一份可用的运行态。
|
||||
func (s *AgentGraphState) EnsureRuntimeState() *AgentRuntimeState {
|
||||
if s == nil {
|
||||
return nil
|
||||
}
|
||||
if s.RuntimeState == nil {
|
||||
s.RuntimeState = NewAgentRuntimeState(nil)
|
||||
}
|
||||
s.RuntimeState.EnsureCommonState()
|
||||
return s.RuntimeState
|
||||
}
|
||||
|
||||
// EnsureFlowState 返回可持久化的主流程状态。
|
||||
func (s *AgentGraphState) EnsureFlowState() *CommonState {
|
||||
runtimeState := s.EnsureRuntimeState()
|
||||
if runtimeState == nil {
|
||||
return nil
|
||||
}
|
||||
return runtimeState.EnsureCommonState()
|
||||
}
|
||||
|
||||
// EnsureConversationContext 保证 graph 内部始终持有一份可用的会话上下文。
|
||||
func (s *AgentGraphState) EnsureConversationContext() *ConversationContext {
|
||||
if s == nil {
|
||||
return nil
|
||||
}
|
||||
if s.ConversationContext == nil {
|
||||
s.ConversationContext = NewConversationContext("")
|
||||
}
|
||||
return s.ConversationContext
|
||||
}
|
||||
|
||||
// EnsureChunkEmitter 返回 graph 可安全调用的 chunk 发射器。
|
||||
func (s *AgentGraphState) EnsureChunkEmitter() *newagentstream.ChunkEmitter {
|
||||
if s == nil {
|
||||
return newagentstream.NewChunkEmitter(newagentstream.NoopPayloadEmitter(), "", "", 0)
|
||||
}
|
||||
return s.Deps.EnsureChunkEmitter()
|
||||
}
|
||||
121
backend/newAgent/model/plan_contract.go
Normal file
121
backend/newAgent/model/plan_contract.go
Normal file
@@ -0,0 +1,121 @@
|
||||
package model
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// PlanAction 表示规划阶段单轮决策的动作类型。
|
||||
//
|
||||
// 设计原则：
|
||||
// 1. 规划阶段只关心“继续规划 / 追问用户 / 规划完成”这三类动作；
|
||||
// 2. 这里先不把工具调用塞进 contract，避免过早把 plan loop 复杂化；
|
||||
// 3. 规划层产出的是“自然语言计划”，不是执行层的工具动作。
|
||||
type PlanAction string
|
||||
|
||||
const (
|
||||
// PlanActionContinue 表示当前信息已足够，继续规划下一轮。
|
||||
PlanActionContinue PlanAction = "continue"
|
||||
|
||||
// PlanActionAskUser 表示当前规划缺少关键信息，需要中断并追问用户。
|
||||
PlanActionAskUser PlanAction = "ask_user"
|
||||
|
||||
// PlanActionDone 表示规划已经完成，可以进入 confirm 或下一阶段。
|
||||
PlanActionDone PlanAction = "plan_done"
|
||||
)
|
||||
|
||||
// PlanDecision 是 plan prompt 单轮产出的统一决策结构。
|
||||
//
|
||||
// 职责边界：
|
||||
// 1. Speak 是本轮先对用户说的话；若 action=ask_user，通常这里会承载要追问的问题；
|
||||
// 2. Action 是规划阶段的下一步动作类型；
|
||||
// 3. Reason 是给后端和日志看的简短解释；
|
||||
// 4. PlanSteps 只在 plan_done 时要求返回，表示本轮最终确认下来的完整自然语言计划。
|
||||
type PlanDecision struct {
|
||||
Speak string `json:"speak,omitempty"`
|
||||
Action PlanAction `json:"action"`
|
||||
Reason string `json:"reason,omitempty"`
|
||||
PlanSteps []PlanStep `json:"plan_steps,omitempty"`
|
||||
}
|
||||
|
||||
// Normalize 统一清洗规划决策中的字符串字段。
|
||||
func (d *PlanDecision) Normalize() {
|
||||
if d == nil {
|
||||
return
|
||||
}
|
||||
d.Speak = strings.TrimSpace(d.Speak)
|
||||
d.Action = PlanAction(strings.TrimSpace(string(d.Action)))
|
||||
d.Reason = strings.TrimSpace(d.Reason)
|
||||
for i := range d.PlanSteps {
|
||||
d.PlanSteps[i].Normalize()
|
||||
}
|
||||
}
|
||||
|
||||
// Validate 校验规划决策的最小合法性。
|
||||
//
|
||||
// 校验原则：
|
||||
// 1. 这里只校验“协议是否自洽”，不校验规划内容是否聪明、是否足够好；
|
||||
// 2. 只有 plan_done 允许返回完整 plan_steps；
|
||||
// 3. 真正的规划质量判断仍留给后续 node 层和用户确认环节。
|
||||
func (d *PlanDecision) Validate() error {
|
||||
if d == nil {
|
||||
return fmt.Errorf("plan decision 不能为空")
|
||||
}
|
||||
|
||||
d.Normalize()
|
||||
if d.Action == "" {
|
||||
return fmt.Errorf("plan decision.action 不能为空")
|
||||
}
|
||||
|
||||
switch d.Action {
|
||||
case PlanActionContinue, PlanActionAskUser:
|
||||
if len(d.PlanSteps) > 0 {
|
||||
return fmt.Errorf("%s 动作不应携带 plan_steps", d.Action)
|
||||
}
|
||||
return nil
|
||||
case PlanActionDone:
|
||||
if len(d.PlanSteps) == 0 {
|
||||
return fmt.Errorf("plan_done 动作必须携带完整 plan_steps")
|
||||
}
|
||||
for i := range d.PlanSteps {
|
||||
if err := d.PlanSteps[i].Validate(); err != nil {
|
||||
return fmt.Errorf("plan_steps[%d] 非法: %w", i, err)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
default:
|
||||
return fmt.Errorf("未知 plan action: %s", d.Action)
|
||||
}
|
||||
}
|
||||
|
||||
// PlanStep 表示规划阶段产出的一条自然语言步骤。
|
||||
//
|
||||
// 设计说明：
|
||||
// 1. Content 是步骤正文，后续可直接落到 CommonState.PlanSteps；
|
||||
// 2. DoneWhen 是可选的完成判定描述，用来给 execute 阶段提供最小退出条件；
|
||||
// 3. 这里仍然保持“自然语言优先”，不把 plan step 过度结构化。
|
||||
type PlanStep struct {
|
||||
Content string `json:"content"`
|
||||
DoneWhen string `json:"done_when,omitempty"`
|
||||
}
|
||||
|
||||
// Normalize 统一清洗 plan step 中的字符串字段。
|
||||
func (s *PlanStep) Normalize() {
|
||||
if s == nil {
|
||||
return
|
||||
}
|
||||
s.Content = strings.TrimSpace(s.Content)
|
||||
s.DoneWhen = strings.TrimSpace(s.DoneWhen)
|
||||
}
|
||||
|
||||
// Validate 校验单条 plan step 的最小合法性。
|
||||
func (s *PlanStep) Validate() error {
|
||||
if s == nil {
|
||||
return fmt.Errorf("plan step 不能为空")
|
||||
}
|
||||
s.Normalize()
|
||||
if s.Content == "" {
|
||||
return fmt.Errorf("plan step.content 不能为空")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
Reference in New Issue
Block a user