smartmate/docs/backend/ROADMAP.md

# NewAgent 全链路改造计划

> 本文档面向后续 coding agent，描述当前 newAgent 的架构现状、改造计划，以及距离"会主动问用户问题、生成多个任务类、自己 ReAct 排日程的智能体"还差什么。

---

## 一、目标智能体行为

用户说："帮我安排下周的复习计划"。

期望的完整链路：

```
1. Chat 节点：LLM 主动追问
   - "这周有几门考试？"
   - "复习强度偏好？均匀分布还是集中在前几天？"
   - "有没有要排除的时段？"

2. Plan 节点：LLM 生成结构化计划
   - 识别意图为"批量安排任务类到日程"
   - 输出 needs_rough_build=true + task_class_ids
   - 或者：LLM 调用 create_task_class 工具创建新的任务类

3. Confirm 节点：展示计划，用户确认

4. RoughBuild 节点（新增）：确定性粗排
   - 调用 SmartPlanningRawItemsMulti() 算法
   - 结果写入 ScheduleState（pending tasks 预填 suggested slots）

5. Execute 节点：LLM 用读写工具微调
   - 查看 get_overview，发现粗排结果
   - 用 move/swap 调整不合理的安排
   - 用 place 处理粗排未能安排的任务
   - 每次写操作经 confirm 流程

6. Deliver 节点：生成最终总结
   - 变更持久化到 DB
   - 向用户展示排课结果
```

---

## 二、当前架构

### 图结构

```
Chat → Plan → Confirm → Execute(ReAct) → Deliver
```

### 已实现的能力

| 模块 | 文件 | 状态 |
|------|------|------|
| 图骨架 | `node/agent_nodes.go` | 已实现，6 个节点 |
| Chat 节点 | `node/chat.go` | 已实现，支持 confirm resume |
| Plan 节点 | `node/plan.go` + `prompt/plan.go` | 已实现，LLM 生成结构化 PlanStep |
| Confirm 节点 | `node/confirm.go` | 已实现，创建 PendingInteraction |
| Execute 节点 | `node/execute.go` + `prompt/execute.go` | 已实现，ReAct + correction + confirm 流 |
| Deliver 节点 | `node/deliver.go` | 已实现，LLM 生成总结 |
| 10 个读写工具 | `tools/read_tools.go` + `tools/write_tools.go` | 已实现，5 读 5 写 |
| 工具注册表 | `tools/registry.go` | 已实现 |
| ScheduleState 加载 | `conv/schedule_provider.go` + `conv/schedule_state.go` | 已实现，从 DB 加载日程+任务类 |
| Confirm 回路测试 | `node/execute_confirm_flow_test.go` | 7 个测试全通过 |
| 端到端排课测试 | `node/llm_tool_orchestration_test.go` | 5 个测试全通过 |
| JSON 协议修正 | `prompt/execute.go` | 已修复，LLM 输出严格 JSON |

### 已有数据流

```
ScheduleProvider.LoadScheduleState(userID)
  → ScheduleDAO.GetUserWeeklySchedule()     // 现有日程
  → TaskClassDAO.GetCompleteTaskClassesByIDs() // 任务类（含 Items）
  → LoadScheduleState()                      // 合并为 ScheduleState
     - existing tasks (source="event")
     - pending tasks (source="task_item", status="pending")
```

---

## 三、缺口分析

### 按优先级排列

#### P0：粗排接入（核心能力）

**问题**：新 agent 没有 `SmartPlanningRawItemsMulti` 的调用路径。让 LLM 一个个 place 效率极低且全局最优性差。

**改造内容**：

1. **Plan 节点输出扩展**
   - 文件：`model/plan_contract.go`（或 PlanDecision 所在文件）
   - PlanDecision 增加 `NeedsRoughBuild bool` 和 `TaskClassIDs []int`
   - `prompt/plan.go` 引导 LLM 判断意图：
     - 用户意图为"批量安排/智能排课/把任务类排进日程" → `needs_rough_build: true`
     - 从前端 `extra` 或对话中提取 `task_class_ids`
     - 其他意图 → `needs_rough_build: false`

2. **新增 RoughBuild 图节点**
   - 新文件：`node/rough_build.go`
   - 不调 LLM，纯确定性逻辑：
     ```
     输入：task_class_ids, userID
     步骤：
       1. 调 ScheduleService.HybridScheduleWithPlanMulti(ctx, userID, taskClassIDs)
          （内部调用 SmartPlanningRawItemsMulti 粗排）
       2. 将粗排结果写入 ScheduleState：
          - pending tasks 的 Slots 字段填入 suggested 位置
          - pending tasks 的 Status 保持 "pending"（LLM 可调整，也可以改为 "suggested" 区分）
       3. 推送状态给前端
     输出：ScheduleState 已填充粗排结果
     ```
   - 路由：`needs_rough_build=true` 时 Confirm 之后走 RoughBuild，否则跳过

3. **图路由修改**
   - 文件：`node/agent_nodes.go`
   - Confirm 之后、Execute 之前插入条件分支：
     ```go
     func (n *AgentNodes) branchAfterConfirm(st *AgentGraphState) string {
         plan := st.RuntimeState.PlanDecision
         if plan != nil && plan.NeedsRoughBuild {
             return "rough_build"
         }
         return "execute"
     }
     ```

4. **依赖注入**
   - 文件：`model/graph_run_state.go` AgentGraphDeps
   - 新增 `RoughBuildFunc` 闭包（和旧 agent 的 `HybridScheduleWithPlanMultiFunc` 同理）
   - 文件：`service/agentsvc/agent_newagent.go`
   - 注入 `ScheduleService.HybridScheduleWithPlanMulti` 到 AgentGraphDeps

**参考实现**：旧 agent 的 `agent/node/schedule_plan.go` 的 `runRoughBuildNode()` 函数。

---

#### P0：持久化 task_item 放置（必须）

**问题**：`conv/schedule_persist.go` 的 `applyPlaceChange` 只处理 `source="event"`，当 LLM place 一个 `source="task_item"` 的 pending 任务时会报错。

**改造内容**：

- 文件：`conv/schedule_persist.go`
- `applyPlaceChange` 增加 `source="task_item"` 分支：
  ```
  if source == "task_item":
    1. 创建 ScheduleEvent(type="task", rel_id=SourceID, name=change.Name)
    2. 为每个 NewCoord 创建 Schedule 记录
    3. 如果有嵌入关系（EmbedHost 非空）：
       - 找到宿主 schedule 记录
       - 设置 schedules.embedded_task_id = SourceID
    4. 更新 task_items.embedded_time（调用 TaskClassDAO.UpdateTaskClassItemEmbeddedTime）
    5. 更新 task_items.status = 2 (applied)
  ```
- `applyUnplaceChange` 也需要增加 `source="task_item"` 分支（反向清理）

**参考实现**：旧 agent 的 `service/task-class.go` 的 `BatchApplyPlans()` 函数（第 327-536 行）。

---

#### P1：TaskClass 约束元数据暴露给 LLM

**问题**：LLM 看到的 pending task 只有 name/category/duration，缺少 TaskClass 级别的调度约束。

**改造内容**：

1. **扩展 ScheduleState 结构**
   - 文件：`newAgent/tools/state.go`
   - 新增：
     ```go
     type TaskClassMeta struct {
         ID                int    `json:"id"`
         Name              string `json:"name"`
         Strategy          string `json:"strategy"`            // "steady" | "rapid"
         ExcludedSlots     []int  `json:"excluded_slots"`      // 排除的半天时段索引
         AllowFillerCourse bool   `json:"allow_filler_course"` // 是否允许嵌入水课
         TotalSlots        int    `json:"total_slots"`         // 总时间预算
     }
     ```
   - `ScheduleState` 增加 `TaskClasses []TaskClassMeta`

2. **LoadScheduleState 填充元数据**
   - 文件：`conv/schedule_state.go`
   - 在 Step 4（处理 pending task items）同时填充 `state.TaskClasses`

3. **读工具输出约束信息**
   - 文件：`tools/read_tools.go`
   - `get_overview` 输出中增加任务类约束描述
   - 示例：
     ```
     任务类约束：
     [学习] 策略=均匀分布, 总预算=12节, 允许嵌入水课=是, 排除时段=[3,4]
     ```

---

#### P2：任务类 ID 从前端传入

**问题**：前端请求需要在 `extra` 中传递 `task_class_ids`，后端需要接收并传递到图内部。

**改造内容**：

1. **API 层**：`api/agent.go` 的请求结构增加 `Extra map[string]any`
2. **Service 层**：`service/agentsvc/agent_newagent.go` 从 `extra` 中提取 `task_class_ids`，存入 RuntimeState 或 AgentGraphRequest
3. **Plan 节点**：从 RuntimeState/Request 中读取 `task_class_ids`，合并 LLM 从对话中提取的 IDs

**参考实现**：旧 agent 的 `agent/node/schedule_plan.go` 的 `normalizeTaskClassIDs()` 函数。

---

#### P3：LLM 主动追问能力增强

**问题**：当前 Chat 节点主要做"接收用户消息 + confirm resume"，缺少"LLM 主动收集排课需求"的能力。

**改造内容**：

- Chat 节点的 prompt 增强：
  - 引导 LLM 在信息不足时主动追问
  - 追问内容：考试科目、复习偏好、时段排除、强度偏好
  - 追问方式：通过 `ask_user` action 或直接在 speak 中提问
- 可能需要新增 ConversationContext 的"收集到的需求"字段
- 收集到的需求在 Plan 节点中被使用

---

#### P4：LLM 创建任务类工具（锦上添花）

**问题**：用户说"帮我安排复习"，但系统里没有对应的 TaskClass，LLM 无法创建。

**改造内容**：

1. **新增工具**：`create_task_class`
   - 参数：`name`, `strategy`, `total_slots`, `allow_filler_course`, `items: [{content, duration}]`
   - 行为：调用 TaskClassDAO 在 DB 中创建 TaskClass + Items
   - 返回：创建结果 + 新的 task_class_id

2. **新增工具**：`update_task_class`（可选）
   - 修改已有任务类的参数

3. **ScheduleState 动态刷新**
   - 创建后需要重新加载 ScheduleState 以反映新的 pending tasks

---

## 四、改造顺序建议

```
Phase 1（打通核心链路）
  ├── P0: 粗排接入（RoughBuild 节点 + 图路由 + 依赖注入）
  ├── P0: 持久化 task_item 放置
  └── P2: task_class_ids 从前端传入

Phase 2（提升排课质量）
  ├── P1: TaskClass 约束元数据暴露
  └── P1: 读工具输出优化（携带约束信息）

Phase 3（智能化）
  ├── P3: Chat 节点追问能力增强
  └── P4: create_task_class 工具
```

---

## 五、关键设计决策记录

1. **粗排由图节点驱动，不由 LLM 驱动**：粗排是确定性算法，浪费 LLM 调用不划算。
2. **粗排通过 Plan 节点的 `needs_rough_build` 标签触发**：不是所有请求都需要粗排，LLM 判断意图后打标签。
3. **粗排结果写入 ScheduleState 的 Slots 字段**：LLM 在 Execute 阶段看到的是"已粗排、可调整"的状态，用 move/swap 微调。
4. **task_class_ids 来源**：前端 `extra` 传入为主，LLM 从对话提取为辅。
5. **持久化用 Diff 模式**：对比 original 和 modified ScheduleState，只持久化变更部分。

---

## 六、关键文件索引

| 用途 | 文件 |
|------|------|
| 图骨架与路由 | `newAgent/node/agent_nodes.go` |
| Chat 节点 | `newAgent/node/chat.go` |
| Plan 节点 | `newAgent/node/plan.go` |
| Confirm 节点 | `newAgent/node/confirm.go` |
| Execute 节点 | `newAgent/node/execute.go` |
| Deliver 节点 | `newAgent/node/deliver.go` |
| Execute prompt | `newAgent/prompt/execute.go` |
| Plan prompt | `newAgent/prompt/plan.go` |
| 工具状态模型 | `newAgent/tools/state.go` |
| 读工具 | `newAgent/tools/read_tools.go` |
| 写工具 | `newAgent/tools/write_tools.go` |
| 工具注册表 | `newAgent/tools/registry.go` |
| 图运行态 | `newAgent/model/graph_run_state.go` |
| 公共状态 | `newAgent/model/common_state.go` |
| 日程状态加载 | `conv/schedule_provider.go` |
| DB→State 转换 | `conv/schedule_state.go` |
| Diff 算法 | `conv/schedule_state.go` (DiffScheduleState) |
| 持久化 | `conv/schedule_persist.go` |
| Service 集成 | `service/agentsvc/agent_newagent.go` |
| 粗排算法（旧，复用） | `logic/smart_planning.go` |
| 旧 agent 粗排节点（参考） | `agent/node/schedule_plan.go` |
| 旧 agent 批量应用（参考） | `service/task-class.go` BatchApplyPlans |