smartmate/agent2逐批搬迁实施细节.md

# agent2 逐批搬迁实施细节

## 1. 文档目的
- 本文档用于指导 `backend/agent -> backend/agent2` 的渐进式重构。
- 目标是“在逻辑不变的前提下重整结构、消除冗余、逐步切流”，而不是一次性重写。
- 该文档优先服务于施工过程，强调“怎么搬、先搬什么、如何验证、何时删除旧代码”。

## 2. 总体迁移原则

### 2.1 不直接改老目录，先并行维护
- 保持现有 `backend/agent` 不动，作为稳定对照组。
- 新建 `backend/agent2`，所有重构都先落在新目录。
- `backend/service/agentsvc` 在迁移期充当“总开关层”，决定某条链路接旧目录还是新目录。

### 2.2 先搬结构，再收冗余
- 第一优先级不是“顺手优化业务逻辑”，而是把职责边界搬顺。
- 迁移时允许短期存在“代码原样搬过去”的情况，但必须同步记录哪些地方后续要抽公共层。
- 严禁一边大改业务逻辑、一边改目录结构，否则回归问题无法定位。

### 2.3 新旧链路必须可对照
- 每搬完一个 skill，都要保证：
  - 老链路还能跑；
  - 新链路能独立接入；
  - service 层可以随时切回旧实现。
- 迁移期间所有新入口都必须保留 feature flag 或切换点。

### 2.4 先做“能收敛冗余”的迁移
- 优先搬那些已经出现明显重复代码的能力，不要先搬边缘功能。
- 迁移不是“把史山平移到新目录”，而是“借搬迁之机把重复公共件抽出来”。

---

## 3. agent2 目标结构

```text
backend/agent2/
  entrance.go

  router/
    route.go
    route_model.go

  graph/
    quicknote.go
    taskquery.go
    schedule.go

  node/
    quicknote.go
    taskquery.go
    schedule_plan.go
    schedule_refine.go

  llm/
    client.go
    json.go
    route.go
    quicknote.go
    taskquery.go
    schedule.go

  model/
    common.go
    route.go
    quicknote.go
    taskquery.go
    schedule.go

  prompt/
    route.go
    quicknote.go
    taskquery.go
    schedule.go

  stream/
    emitter.go
    openai.go

  shared/
    clone.go
    retry.go
    time.go
```

## 4. 各层职责约束

### 4.1 `entrance.go`
- 是整个 `agent2` 模块唯一总入口。
- 负责：
  - 接收请求上下文；
  - 调路由；
  - 调 skill graph；
  - 收口 token、SSE、持久化。
- 不负责：
  - 某个 skill 内部节点的业务实现；
  - 直接写 prompt；
  - 直接调用模型。

### 4.2 `router/`
- 只负责一级分流。
- 输出统一路由结果，例如：
  - `chat`
  - `quick_note_create`
  - `task_query`
  - `schedule_plan_create`
  - `schedule_plan_refine`
- 不负责 skill 内部二次判断。

### 4.3 `graph/`
- 只负责画 graph。
- 文件里应尽量只出现：
  - `AddLambdaNode`
  - `AddEdge`
  - `AddBranch`
- 不允许在 `graph/` 内直接写复杂业务逻辑、模型调用或数据转换。

### 4.4 `node/`
- 只负责每个节点内部的业务逻辑。
- 可以调用：
  - `llm/`
  - `shared/`
  - service/dao 注入依赖
- 不负责：
  - Graph 连线；
  - OpenAI chunk 输出格式；
  - 大段 prompt 常量定义。

### 4.5 `llm/`
- 专门负责和模型交互。
- 统一收口：
  - `GenerateText`
  - `GenerateJSON`
  - `Stream`
  - JSON 提取与解析
  - thinking/temperature/maxTokens 等参数
- 这一层的定位，等价于“模型数据访问层”。

### 4.6 `model/`
- 存放 agent 域模型，而不是数据库模型。
- 包括：
  - state
  - dto
  - route decision
  - tool result

### 4.7 `prompt/`
- 统一收口 prompt 文本。
- 禁止在 `node/` 和 `llm/` 中内联大段 prompt。

### 4.8 `stream/`
- 统一收口 SSE/OpenAI 兼容块输出。
- 所有阶段推送、单条 assistant 回复、finish chunk 都从这里走。

### 4.9 `shared/`
- 只放纯工具，不放业务编排。
- 当前预计优先放：
  - 深拷贝
  - 重试策略
  - 时间解析

---

## 5. 逐批搬迁顺序

## 第 0 批：先搭骨架，不接流量

### 目标
- 先把 `agent2` 目录骨架建起来。
- 不迁任何业务，只搭结构。

### 产物
- `backend/agent2/` 目录
- `entrance.go`
- `router/graph/node/llm/model/prompt/stream/shared` 空壳

### 验证
- 能编译通过。
- 不接任何线上/实际业务入口。

---

## 第 1 批：先迁公共能力，不迁 skill

### 目标
- 先抽最明显的公共重复件，给后续 skill 迁移打基础。

### 优先抽取的公共件
- `llm/json.go`
  - 统一 `GenerateJSON`
  - 统一 JSON object 提取
  - 统一空响应/解析失败错误
- `llm/client.go`
  - 统一 `GenerateText`
  - 统一 thinking/maxTokens/temperature 参数装配
- `stream/openai.go`
  - 迁入现有 `ToOpenAIStream`
  - 迁入 `ToOpenAIFinishStream`
- `stream/emitter.go`
  - 统一阶段推送
  - 统一单条 assistant completion 输出
- `shared/clone.go`
  - 抽 `cloneWeekSchedules`
  - 抽 `cloneHybridEntries`
  - 抽 `cloneTaskClassItems`

### 说明
- 这一批不碰 quicknote/taskquery/schedule 的业务语义。
- 只把公共重复代码先搬进 `agent2`。

---

## 第 2 批：迁 `quicknote`，作为样板 skill

### 目标
- 用最小 skill 验证三层结构是否顺手。

### 对应关系
- 旧：
  - `backend/agent/quicknote/graph.go`
  - `backend/agent/quicknote/nodes.go`
  - `backend/agent/quicknote/tool.go`
  - `backend/agent/quicknote/state.go`
  - `backend/agent/quicknote/prompt.go`
- 新：
  - `backend/agent2/graph/quicknote.go`
  - `backend/agent2/node/quicknote.go`
  - `backend/agent2/llm/quicknote.go`
  - `backend/agent2/model/quicknote.go`
  - `backend/agent2/prompt/quicknote.go`

### 迁移要求
- 逻辑不变。
- 原有测试优先复用。
- 如果出现可直接删除的冗余函数，必须当场删除，不允许“先复制一份以后再说”。

### 接入方式
- 在 `agentsvc` 里增加切换开关：
  - `run quicknote with agent`
  - `run quicknote with agent2`

---

## 第 3 批：迁 `taskquery`

### 目标
- 用第二个 skill 验证公共层抽取是否真的通用，而不是只服务于 quicknote。

### 核心检查点
- `taskquery` 是否能完全复用第 1 批抽出的 `llm/json.go`。
- fallback/retry 是否还能保持一致。
- 阶段推送是否已经不需要 skill 自己再包一层。

### 完成标准
- `taskquery` 不再保留自己私有的 JSON 调用封装。

---

## 第 4 批：迁 `route`

### 目标
- 把统一分流也纳入 `agent2`。

### 要求
- `entrance.go` 以后只依赖 `agent2/router`。
- `router` 只做一级分流，不再夹杂 skill 级 fallback。

---

## 第 5 批：迁 `scheduleplan`

### 目标
- 把排程首次创建链路迁入新结构。

### 迁移策略
- 不直接优化复杂业务。
- 先把它拆成：
  - `graph/schedule.go`
  - `node/schedule_plan.go`
  - `llm/schedule.go`
  - `model/schedule.go`
  - `prompt/schedule.go`

### 强制要求
- 不允许继续保留“节点文件里夹杂模型调用帮助函数”的写法。
- 不允许在 `node/` 里再内联 JSON parse helper。

---

## 第 6 批：迁 `schedulerefine`

### 目标
- 处理当前最重的史山。

### 原则
- 这一步不是“原样平移”。
- 这是第一次允许在迁移中顺手拆大文件。

### 最低拆分要求
- 旧 `nodes.go` 至少拆成：
  - `schedule_refine_contract`
  - `schedule_refine_plan`
  - `schedule_refine_react`
  - `schedule_refine_review`
  - `schedule_refine_summary`
- 旧 `tool.go` 至少拆成：
  - `tool_defs`
  - `tool_dispatch`
  - `tool_payload`
  - `tool_policy`

---

## 第 7 批：切流与删除旧目录

### 前提条件
- `quicknote`
- `taskquery`
- `route`
- `scheduleplan`
- `schedulerefine`

以上链路都已经切到 `agent2`，并经过回归验证。

### 操作顺序
- 1. service 层入口全部切到 `agent2`
- 2. 跑一轮完整回归
- 3. 删除旧 `backend/agent`
- 4. `backend/agent2` 改名为 `backend/agent`

### 注意
- 第 4 步必须最后做。
- 在此之前不要提前重命名，避免 review 和 diff 变得混乱。

---

## 6. 迁移过程中的强约束

### 6.1 逻辑不变优先于结构完美
- 只要旧逻辑还能清晰搬进新层次，就先搬。
- 不要在同一轮同时追求“换架构 + 换策略 + 换 prompt”。

### 6.2 每次只迁一个能力域
- 一次只动一个 skill 或一类公共件。
- 严禁“这一轮顺手把三个 skill 一起改了”。

### 6.3 旧代码不删前，新代码必须已接入验证
- 先搬
- 再切
- 再验
- 最后删

### 6.4 公共能力一旦发现第二处重复，就必须考虑抽层
- 不允许在 `agent2` 里继续复制第三份、第四份。
- `agent2` 的目标不是“新目录复刻旧史山”，而是“迁移过程中顺手收口公共能力”。

---

## 7. 每一批迁移完成后的检查项
- 是否出现了新的重复模型调用 helper？
- 是否出现了新的重复 JSON parse helper？
- 是否又把 prompt 写回节点文件里了？
- 是否又在 service 层偷偷加了一层业务桥接？
- 是否还能一眼看出：
  - 入口在哪
  - 分流在哪
  - 编排在哪
  - 节点逻辑在哪
  - 模型交互在哪

---

## 8. 当前最值得优先搬的公共件
- `GenerateJSON/GenerateText`
- JSON 提取与解析
- OpenAI 兼容 SSE 包装
- 阶段推送 emitter
- schedule 相关深拷贝工具
- schedule preview / snapshot 读写逻辑

---

## 9. 一句话版本
- 先建 `agent2` 骨架。
- 先抽公共层，再迁 skill。
- 先迁 `quicknote` 做样板，再迁 `taskquery` 验证复用，再动 `schedule`。
- 迁移期间新旧并存、随时可切回。
- 删除旧 `agent` 只能发生在所有 skill 全部切流并验证通过之后。