smartmate/docs/backend/ARCHITECTURE.md

NewAgent 架构全景

本文档帮助读者建立对 newAgent 的完整心智模型，从宏观到微观逐层展开。

---

一、一句话概括

newAgent 是一个 状态机驱动的有向图：用户消息进入 Chat 节点，经过意图分类、计划生成、用户确认、工具执行、最终交付，每一步由 Phase 和 PendingInteraction 驱动路由。

---

二、宏观架构

2.1 目录结构

newAgent/
├── graph/           图骨架：节点注册、边连线、分支路由
├── model/           数据模型：状态、合约、接口定义
├── node/            节点实现：每个节点的业务逻辑
├── prompt/          提示词：每个阶段的 system prompt 和用户 prompt 构造
├── llm/             LLM 客户端：文本生成、JSON 解析、流式适配
├── stream/          SSE 输出：伪流式推送、OpenAI 兼容格式
├── tools/           工具层：10 个排程工具 + 注册表
├── shared/          公共工具：重试、时区
├── router/          路由（当前为空，路由逻辑在 graph/ 中）
├── ROADMAP.md       改造计划
└── ARCHITECTURE.md  本文档

2.2 图结构

START
  │
  v
 Chat ──────┬── 意图=chat ────→ END（直接回复）
  │         │
  │         └── 意图=task ──→ Plan ──┬── continue ──→ Plan（继续规划）
  │                                │      │
  │                                │      ├── ask_user ──→ Interrupt ──→ END
  │                                │      │
  │                                │      └── plan_done ──→ Confirm
  │                                │                │
  │                                │                ├── 有计划 → 确认卡片
  │                                │                │          │
  │                                │                │          v
  │                                │                │     Interrupt ──→ END
  │                                │                │
  │                                │                └── 有 PendingConfirmTool → 确认卡片
  │                                                       │
  │                                                       v
  │                                                  Interrupt ──→ END
  │
  │  [用户确认后重新进入图]
  │
  v
 Chat(resume) ──┬── accept → 恢复 PendingConfirmTool → Execute
               │
               └── reject → 回到 planning 或 executing

Execute ──┬── continue(读工具) ──→ Execute（继续 ReAct）
          ├── continue(无工具) ──→ Execute
          ├── confirm(写工具) ──→ Confirm ──→ Interrupt ──→ END
          ├── ask_user ──→ Interrupt ──→ END
          ├── next_plan ──┬── 有剩余步骤 → Execute
          │                └── 无剩余步骤 → Deliver
          ├── done ──→ Deliver
          └── 轮次耗尽 ──→ Deliver（强制）

Deliver ──→ END（最终总结，清理持久化快照）

2.3 一次完整排课的请求序列

请求1: 用户发 "帮我安排下周的复习"
  → Chat(intent=task) → Plan(plan_done, 2步计划) → Confirm → Interrupt → END
  前端展示确认卡片

请求2: 用户点 "确认"
  → Chat(resume, accept) → 确认通过 → Execute(读工具 get_overview)
  → Execute(读工具 find_free)
  → Execute(写工具 place → confirm) → Confirm → Interrupt → END
  前端展示写操作确认卡片

请求3: 用户点 "确认"
  → Chat(resume, accept) → Execute(执行 pending tool place) → 持久化
  → Execute(next_plan → 下一步)
  → Execute(done) → Deliver → END
  前端展示最终总结

---

三、状态模型

理解 newAgent 的关键在于理解 什么东西在什么时机变化。

3.1 三个核心状态对象

┌─────────────────────┐   持久化到 Redis
│   AgentRuntimeState  │   ← StateStore.Save/Load
│                     │
│  ┌───────────────┐  │
│  │ CommonState   │  │   ← 每个节点都可能修改
│  │ - Phase       │  │
│  │ - PlanSteps   │  │
│  │ - CurrentStep │  │
│  │ - RoundUsed   │  │
│  └───────────────┘  │
│                     │
│  PendingInteraction │   ← 确认/追问 的交互快照
│  PendingConfirmTool │   ← Execute→Confirm 的临时邮箱
└─────────────────────┘

┌─────────────────────────┐   不持久化，每次请求重建
│  ConversationContext    │
│  - SystemPrompt         │   ← 各节点 prompt 函数构造
│  - History []*Message   │   ← 对话历史（assistant+tool 配对）
│  - PinnedBlocks         │   ← 置顶上下文（计划、工具摘要）
│  - ToolSchemas          │   ← 工具 schema 注入
└─────────────────────────┘

┌─────────────────────────┐   懒加载，首次 Execute 时读取
│  ScheduleState          │
│  - Window (天数+映射)    │
│  - Tasks []ScheduleTask │   ← 工具操作的数据源
└─────────────────────────┘

3.2 Phase 状态转换

PhasePlanning       Plan 节点 plan_done + 用户确认后
    │
    v
PhaseExecuting      Execute 节点执行中
    │
    ├──→ PhaseWaitingConfirm   Execute 输出 action=confirm
    │        │
    │        v  用户确认
    │    PhaseExecuting          恢复继续执行
    │
    ├──→ PhaseDone              Execute 输出 done 或所有步骤完成
    │
    └──→ PhaseInterrupted       被中断（追问/确认等待用户输入）

3.3 PendingInteraction 生命周期

场景 A: 计划确认
  Plan → plan_done → Confirm 节点 → OpenConfirmInteraction(type="confirm")
  → Interrupt 展示 → END
  → 用户确认 → Chat(resume) → ResumeFromPending() → Phase=executing

场景 B: 写操作确认
  Execute → action=confirm → 设置 PendingConfirmTool → Confirm 节点
  → OpenConfirmInteraction(type="confirm", PendingTool=快照)
  → Interrupt 展示 → END
  → 用户确认 → Chat(resume) → PendingConfirmTool 从快照恢复 → Execute 执行工具

场景 C: 追问
  Execute → action=ask_user → OpenAskUserInteraction(question)
  → Interrupt 展示 → END
  → 用户回复 → Chat(resume) → Phase 回到 executing

3.4 PendingConfirmTool 临时邮箱

这个字段 不持久化，只在单次图运行中存在：

Execute(action=confirm)
  → PendingConfirmTool = {ToolName, ArgsJSON, Summary}
  → Phase = waiting_confirm
  → Confirm 节点读取 → 转入 PendingInteraction.PendingTool
  → PendingConfirmTool 被清空

用户确认后重新进入图：
  → Chat(resume) → 从 PendingInteraction.PendingTool 恢复到 PendingConfirmTool
  → Execute 发现 PendingConfirmTool 非空 → 直接执行工具 → 清空

---

四、各节点详解

4.1 Chat 节点 (node/chat.go)

职责：入口分流 + 中断恢复

两条路径：

1. 首次进入：调 LLM 做意图分类（"chat" / "task"），chat 直接回复，task 转到 Plan
2. 中断恢复：读取 PendingInteraction，根据类型（ask_user / confirm）走不同恢复路径

关键逻辑：

if HasPendingInteraction():
    handleChatResume()     // 不调 LLM
else:
    chatIntentDecision()   // 调 LLM 做意图分类

confirm resume 的 accept/reject 处理：

• accept：从 PendingInteraction.PendingTool 恢复 PendingConfirmTool，Phase=executing
• reject（有 PendingTool）：不恢复 PendingConfirmTool，Phase=executing（LLM 换方案）
• reject（无 PendingTool）：调用 RejectPlan()，Phase=planning（回到规划）

4.2 Plan 节点 (node/plan.go)

职责：LLM 生成结构化计划

两阶段 LLM 调用：

1. Phase 1 快速评估：temperature=0.2, max_tokens=1600, thinking=关闭
   • 输出 PlanDecision，判断 Complexity(simple/moderate/complex)
2. Phase 2 深度规划（仅 complex 任务触发）：thinking=开启, max_tokens=3200
   • 生成更详细的 PlanStep 列表（含 DoneWhen 完成判定条件）

三种 action：

• continue：继续规划（多轮对话中补充信息）
• ask_user：追问用户
• plan_done：规划完成，输出 PlanSteps

计划写入 PinnedBlocks：用 UpsertPinnedBlock 把计划文本注入 ConversationContext，后续 Execute 阶段自动带入。

4.3 Confirm 节点 (node/confirm.go)

职责：创建确认卡片，不调 LLM

两种确认：

1. 计划确认（Phase=waiting_confirm, PendingConfirmTool 为空）：格式化计划摘要，创建 PendingInteraction
2. 工具确认（PendingConfirmTool 非空）：格式化工具操作摘要，把 PendingTool 快照转入 PendingInteraction

关键：Confirm 节点执行后，PendingConfirmTool 被清空（数据已转移到 PendingInteraction.PendingTool）。

4.4 Execute 节点 (node/execute.go)

职责：LLM 主导的 ReAct 循环，这是最复杂的节点。

入口判断优先级：

1. PendingConfirmTool 非空 → executePendingTool() → 结束
2. 无有效 PlanStep → 报错
3. 正常 ReAct → 调 LLM → 处理决策

LLM 调用参数：temperature=0.3, max_tokens=1200, thinking=开启

JSON 解析失败处理（correction 机制）：

LLM 输出非 JSON:
  → ConsecutiveCorrections++
  → 追加修正消息到历史
  → return nil（图循环回来，LLM 看到修正消息后重试）
  → 连续 3 次失败 → 返回硬错误，终止

五种 action 处理：

action	行为	工具执行？
continue + tool_call	读工具直接执行	是，executeToolCall()
continue 无 tool	仅说话，继续循环	否
confirm	暂存 PendingConfirmTool	否，等用户确认
ask_user	打开追问	否
next_plan	推进步骤	否
done	结束所有步骤	否

工具执行后历史消息格式：

assistant message: {Role: "assistant", ToolCalls: [{ID, Function: {Name, Arguments}}]}
tool message:     {Role: "tool", ToolCallID: <匹配ID>, Content: "工具结果"}

这对消息必须配对，否则 OpenAI 兼容 API 会拒绝请求。

轮次预算：MaxRounds 默认 30，耗尽强制进入 Deliver。

4.5 Interrupt 节点 (node/interrupt.go)

职责：向用户展示消息后暂停图执行

三种类型：

• ask_user：伪流式展示 DisplayText
• confirm：展示确认状态
• 默认：展示通用中断信息

4.6 Deliver 节点 (node/deliver.go)

职责：生成最终总结

• 调 LLM（temperature=0.5, max_tokens=800）生成总结
• 失败时降级到机械格式化（逐条列出步骤 + 完成标记）
• 完成后调用 deleteAgentState() 清理 Redis 快照

---

五、LLM 交互模式

5.1 统一 JSON 协议

所有 LLM 输出都是严格 JSON，不是纯文本。每个阶段有自己的合约：

Plan 合约 (model/plan_contract.go)：

{
  "speak": "...",
  "action": "continue|ask_user|plan_done",
  "reason": "...",
  "complexity": "simple|moderate|complex",
  "need_thinking": false,
  "plan_steps": [{"content": "...", "done_when": "..."}]
}

Execute 合约 (model/execute_contract.go)：

{
  "speak": "...",
  "action": "continue|ask_user|confirm|next_plan|done",
  "reason": "...",
  "goal_check": "（next_plan/done 时必填）",
  "tool_call": {"name": "工具名", "arguments": {...}}
}

5.2 JSON 解析容错

llm/json.go 的 ParseJSONObject 能处理：

• LLM 在 JSON 前后附带文字 → 提取中间的 JSON 对象
• Markdown 代码块包裹（json ... ）→ 剥离
• 嵌套对象（大括号配对计数）

5.3 Correction 循环

当 LLM 输出非法 JSON 时：

1. 原始输出作为 assistant 消息追加到历史
2. 修正提示作为 user 消息追加到历史
3. return nil → 图循环回来
4. LLM 看到修正消息，下一轮输出合法 JSON
5. ConsecutiveCorrections 重置为 0
6. 连续 3 次失败 → 硬错误终止

---

六、工具系统

6.1 数据模型

ScheduleState 是工具操作的唯一数据源：

ScheduleState
├── Window                    时间窗口
│   ├── TotalDays             总天数（如 5 或 7）
│   └── DayMapping[]          day_index → (week, day_of_week) 映射
└── Tasks[]                   扁平任务列表
    ├── source="event"        来自日程表的已有课程/任务
    │   ├── Slots[]           压缩的时段范围
    │   ├── CanEmbed          是否允许嵌入
    │   └── Locked            是否锁定（不可移动）
    └── source="task_item"    来自任务类的待安排任务
        ├── Duration          需要的连续时段数
        ├── CategoryID        所属 TaskClass.ID
        └── Status="pending"  待安排

6.2 10 个工具

读工具（直接执行，不需要确认）：

工具	用途	典型调用时机
get_overview	全局概览：天数、占用统计、可嵌入、待安排	LLM 需要了解全局
query_range	查询指定天/时段的详情	LLM 需要具体位置信息
find_free	查找连续空闲时段	LLM 需要找空位放任务
list_tasks	按条件列出任务	LLM 需要筛选任务
get_task_info	单个任务详情（含嵌入关系）	LLM 需要具体任务信息

写工具（需用户确认）：

工具	用途	关键逻辑
place	放置 pending 任务到时段	自动检测嵌入（CanEmbed=true 的宿主）
move	移动已有任务到新位置	冲突检测（排除自身）
swap	交换两个等时长任务的时段	冲突时自动回滚
batch_move	批量移动多个任务	原子性：任一冲突全部回滚
unplace	取消放置，恢复 pending	清理双向嵌入关系

6.3 工具执行流程

读工具（action=continue + tool_call）：

Execute → executeToolCall() → registry.Execute() → 追加 assistant+tool 消息对 → return nil → 图循环

写工具（action=confirm）：

Execute → handleExecuteActionConfirm() → 暂存 PendingConfirmTool
→ Confirm 节点 → Interrupt → 用户确认
→ Chat(resume) → 恢复 PendingConfirmTool
→ Execute → executePendingTool() → registry.Execute() + persistor + 追加消息对

6.4 持久化路径

工具执行成功
  → DiffScheduleState(original, modified) → []ScheduleChange
  → PersistScheduleChanges(事务)
    → applyPlaceChange / applyMoveChange / applyUnplaceChange

当前限制：applyPlaceChange 只处理 source="event"，source="task_item" 会报错。详见 ROADMAP.md P0 缺口。

---

七、SSE 输出系统

7.1 ChunkEmitter

所有节点通过 ChunkEmitter 向前端推送事件：

EmitPseudoAssistantText()  → 伪流式文本（分段推送，模拟打字效果）
EmitStatus()                → 状态推送（"正在执行第2步"）
EmitConfirmRequest()        → 确认卡片
EmitFinish() / EmitDone()   → 结束标记

7.2 伪流式

LLM 的一次性文本输出通过 SplitPseudoStreamText 拆分成多个 chunk：

• 按中英文标点断句
• 每个 chunk 8~24 个字符
• 间隔 40ms 推送

7.3 OpenAI 兼容格式

stream/openai.go 定义了 OpenAI 兼容的 SSE 格式，通过 ext 字段扩展：

• reasoning_text：思考过程
• assistant_text：正文
• status：状态更新
• tool_call / tool_result：工具调用
• confirm_request：确认卡片
• interrupt：中断消息

---

八、持久化模型

8.1 三个持久化层次

层级	机制	何时触发	存什么
快照	AgentStateStore (Redis)	Plan/Confirm/Execute 节点后	AgentRuntimeState + ConversationContext
变更	SchedulePersistor (MySQL)	写工具执行后	ScheduleState 的 diff
历史	Redis + MySQL	图运行完成后	完整对话历史

8.2 快照恢复流程

用户发送新消息（图需要从中断恢复）
  → loadOrCreateRuntimeState()
    → StateStore.Load(conversationID)
    → 如果存在：恢复 RuntimeState + ConversationContext
    → 如果不存在：创建全新状态

快照在 Deliver 后被 deleteAgentState() 清理。

---

九、Prompt 体系

9.1 prompt 构造模式

所有阶段现在统一共享 buildUnifiedStageMessages() 函数：

msg0(system)    = 全局 system prompt + 阶段 system prompt + 工具简表
msg1(assistant) = 对话历史 + 归档摘要
msg2(assistant) = 阶段工作区
msg3(system)    = 阶段状态 + 记忆 + 本轮指令

统一构造由 StageMessagesConfig 驱动，具体阶段只负责填充各自的 Msg2Content、Msg3StageState 和 UserInstruction。

9.2 各阶段 prompt 要点

阶段	核心指令	关键约束
Chat	分类意图：chat vs task	保守默认为 task
Plan	两阶段：快速评估 + 深度规划	简单任务不开启 thinking
Execute	ReAct：思考→执行→观察	goal_check 为 next_plan/done 必填
Deliver	总结计划执行结果	失败降级到机械格式化

9.3 置顶上下文块

PinnedBlocks 是跨节点共享的上下文，通过 Key 去重：

execution_context  ← Execute 节点注入（当前步骤、完成判定等）
plan                ← Plan 节点注入（完整计划文本）
tool_summary        ← Execute 节点注入（可用工具摘要）

---

十、图路由逻辑 (graph/common_graph.go)

路由函数是图的核心控制逻辑，决定了每步之后走向哪个节点：

branchAfterChat

if PendingInteraction → Interrupt
else switch Phase:
  planning → Plan
  executing → Execute
  done → Deliver
  chatting → END

branchAfterPlan

if PendingInteraction → Interrupt
else switch Phase:
  waiting_confirm → Confirm
  planning → Plan（continue，继续规划）
  executing → Execute（不应该发生，但防御性路由）

branchAfterConfirm

if PendingInteraction → Interrupt
else → Execute（确认通过）

branchAfterExecute

if PendingInteraction → Interrupt
else switch Phase:
  executing → Execute（继续循环）
  done → Deliver
  waiting_confirm → Confirm（不应该发生，防御性路由）

关键保护机制

所有分支函数都以 branchIfInterrupted() 开头：

func branchIfInterrupted(st *AgentGraphState) string {
    if st.RuntimeState.HasPendingInteraction() {
        return "interrupt"
    }
    return ""
}

这确保任何节点设置了 PendingInteraction 后，图都会走向 Interrupt 节点展示给用户。

---

十一、Service 集成层 (service/agentsvc/agent_newagent.go)

入口函数：runNewAgentGraph

1. 规范化 conversationID, modelName
2. 确保会话存在（Redis 缓存 → DB）
3. 构建重试元数据
4. 加载或创建 RuntimeState（从 Redis 快照恢复）
5. 构建 AgentGraphRequest（ConfirmAction 从 extra 取）
6. 包装 Ark 客户端
7. 创建 SSE 适配器 + ChunkEmitter
8. 组装 AgentGraphDeps（注入所有依赖）
9. 调用 RunAgentGraph()
10. 持久化对话历史到 Redis + MySQL
11. 发送 [DONE] 标记，触发异步标题生成

依赖注入

cmd/start.go:
  → NewScheduleProvider(scheduleDAO, taskClassDAO)  → SetScheduleProvider()
  → NewSchedulePersistorAdapter(repoManager)         → SetSchedulePersistor()
  → NewDefaultRegistry()                              → SetToolRegistry()
  → NewRedisStateStore(cacheDAO)                      → SetAgentStateStore()

---

十二、如何调试

12.1 日志关键字

搜索关键字	含义
[DEBUG] execute LLM	Execute 节点的 LLM 原始输出和解析结果
[DEBUG] plan LLM	Plan 节点的 LLM 输出
[WARN] execute 决策不合法	LLM 输出合法 JSON 但 action 不合法
[DEBUG] execute LLM 输出解析失败	JSON 解析失败，触发 correction
PersistScheduleChanges	持久化调用
loadOrCreateRuntimeState	状态恢复/创建

12.2 常见问题排查

SSE 断开：

1. 检查 [DEBUG] execute LLM 日志，看 LLM 输出是否为合法 JSON
2. 如果输出 [NEXT_PLAN] 等纯文本 → prompt 问题（已修复，参考 execute.go 的 correction 机制）
3. 如果输出合法 JSON 但 action 不对 → 检查 prompt 的合约文本

工具不执行：

1. 检查 PendingConfirmTool 是否被正确设置和恢复
2. 检查 ScheduleState 是否为 nil（可能 ScheduleProvider 未注入）
3. 检查 history 中 assistant+tool 消息是否配对（ToolCallID 是否匹配）

图循环不退出：

1. 检查 ConsecutiveCorrections 计数（可能 LLM 反复输出非法 JSON）
2. 检查 RoundUsed 是否耗尽（MaxRounds 默认 30）
3. 检查 Phase 是否卡在某个状态

12.3 单元测试

node/execute_confirm_flow_test.go   → 7 个测试，覆盖完整 confirm 回路
node/llm_tool_orchestration_test.go → 5 个测试，覆盖真实排课场景

测试使用 mock LLM（预定义 JSON 响应序列）和 mock 工具注册表，不依赖外部服务。

---

十三、关键设计决策及理由

决策	理由
Phase 驱动路由而非硬编码序列	同一个图支持多种流程（直接聊天、排课、追问恢复），Phase 是最小状态信号
PendingInteraction 作为中断快照	图是无状态的（每次请求重新运行），需要一种机制跨请求传递"等用户回复"的上下文
PendingConfirmTool 作为临时邮箱	Execute 和 Confirm 之间不能直接传参（中间隔了 Interrupt+END+Chat），用运行态字段传递
JSON 协议而非文本标记	LLM 输出结构化数据，后端用泛型解析，避免正则匹配的不确定性
Correction 机制	LLM 不是 100% 可靠，需要给修正机会，但限制最大连续次数避免死循环
伪流式而非真流式	LLM API 的一次性返回更适合分段推送，真流式实现复杂且收益低
工具操作扁平 ScheduleState	避免嵌套数据结构，工具只需关心"在哪里放什么"
Diff 持久化	只持久化变更部分，减少 DB 操作，支持原子性
PinnedBlocks 注入上下文	计划、工具摘要等信息不需要每轮都重复，用置顶块注入一次即可

---

十四、关键文件速查

想了解...	看这个文件
图怎么连的	graph/common_graph.go
每个节点怎么被调用的	node/agent_nodes.go
Chat 怎么分类意图的	prompt/chat.go + node/chat.go
Plan 怎么生成计划的	prompt/plan.go + node/plan.go
Execute 的 ReAct 循环	node/execute.go
confirm 回路怎么转的	node/confirm.go + node/chat.go(handleConfirmResume)
LLM 输出什么格式	model/plan_contract.go + model/execute_contract.go
JSON 解析怎么容错的	llm/json.go
correction 怎么追回的	node/correction.go
工具怎么注册和执行的	tools/registry.go
工具操作什么数据	tools/state.go
SSE 输出什么格式	stream/openai.go
状态怎么持久化的	model/state_store.go + conv/schedule_persist.go
日程数据怎么加载的	conv/schedule_provider.go + conv/schedule_state.go
Service 怎么组装的	service/agentsvc/agent_newagent.go
API 怎么调用的	api/agent.go
距离全链路还差什么	ROADMAP.md