smartmate/agent代码复用清单.md

Agent 代码复用清单（施工备忘）

1. 文档目的

• 这份文档只做一件事：记录当前 backend/agent 与 backend/service/agentsvc 中“明明可以复用、却被重复实现”的代码点。
• 目标不是立刻改代码，而是防止后续压缩上下文后忘记哪些地方最值得先收口。
• 这里优先关注“公共能力重复实现”，不讨论具体业务对错。

2. 当前最明显的重复结论

• 重复最严重的不是某一个 skill，而是“每个 skill 都在各自实现一套模型调用、JSON 解析、阶段推送、兜底、深拷贝、缓存快照读写、工具分发”。
• quicknote、taskquery、scheduleplan、schedulerefine 已经形成了“四套相似但不统一的 agent 基建”。
• service/agentsvc 里也开始出现重复胶水层逻辑，尤其是排程预览和连续微调相关读写。

---

3. 高优先级复用点

3.1 模型调用封装重复

现状

• quicknote 自己实现了 callModelForJSON / callModelForJSONWithMaxTokens。
• taskquery 自己实现了 callTaskQueryModelForJSON。
• scheduleplan 自己实现了 callScheduleModelForJSON。
• schedulerefine 自己实现了 callModelText，而且附带了一整套 JSON contract 变体。

证据

• quicknote/nodes.go
• taskquery/nodes.go
• scheduleplan/nodes.go
• schedulerefine/nodes.go

问题

• 都在做同一类事情：
  • 拼 system + user 消息
  • 关闭/开启 thinking
  • 设置 temperature/maxTokens
  • 调 Generate
  • 判空响应
  • 返回文本
• 现在每个模块一套，导致：
  • 参数风格不统一
  • 错误文案不统一
  • token 统计与 callback 复用也难进一步规范

建议抽取

• 抽到统一的 agent/core/modelx 或类似目录。
• 至少统一三个入口：
  • GenerateText
  • GenerateJSON
  • GenerateJSONWithContract

优先级

• P0

---

3.2 JSON 解析与对象提取重复

现状

• quicknote 自己实现了 parseJSONPayload + extractJSONObject。
• taskquery 有自己的 parseTaskQueryJSON。
• scheduleplan 有自己的 parseScheduleJSON。
• schedulerefine 有自己的 parseJSON，并且带重试解析逻辑。

证据

• quicknote/nodes.go
• taskquery/nodes.go
• scheduleplan/nodes.go
• schedulerefine/nodes.go

问题

• 都在解决“模型返回不是纯 JSON，需要做容错提取”。
• 解析失败后的兜底策略也高度相似，只是文案不同。

建议抽取

• 抽统一的 agent/core/jsonx：
  • ParseJSONObject[T]
  • ExtractJSONObject
  • ParseWithRetryHint（后续可选）

优先级

• P0

---

3.3 阶段推送（EmitStage）重复

现状

• quicknote/graph.go 自己封装 EmitStage 判空。
• taskquery/graph.go 自己写 runner.emit。
• scheduleplan/graph.go 自己包一层 emitStage。
• schedulerefine/graph.go 也自带一套。

证据

• quicknote/graph.go
• taskquery/graph.go
• scheduleplan/graph.go
• schedulerefine/graph.go

问题

• 所有 graph 都在做相同事情：封装一个 func(stage, detail string)，把 nil 判断藏起来。
• 这一层目前很轻，但 skill 一多就会持续复制。

建议抽取

• 抽统一的 agent/core/progress：
  • type Emitter func(stage, detail string)
  • func WrapEmitter(fn func(string, string)) Emitter
  • func NoopEmitter() Emitter

优先级

• P1

---

3.4 OpenAI 兼容流式包装能力重复调用方式不统一

现状

• 统一实现其实已经有了，在 chat/stream.go 里：
  • ToOpenAIStream
  • ToOpenAIFinishStream
• 但 agentsvc 侧又额外自己实现了“阶段推送器”和“单条 assistant completion 包装”。

证据

• chat/stream.go
• agent_quick_note.go

问题

• 现在虽然底层函数复用了，但“如何构造阶段消息 / 一次性正文 / finish chunk”的协议层仍散落在 service 层。
• 后续 schedule、memory、websearch 也大概率继续复制。

建议抽取

• 抽统一的 agent/core/streamx：
  • EmitReasoningStage
  • EmitSingleAssistantReply
  • EmitErrorChunk

优先级

• P1

---

3.5 深拷贝函数重复

现状

• agentsvc/agent_schedule_preview.go 有：
  • cloneWeekSchedules
  • cloneHybridEntries
  • cloneTaskClassItems
• schedulerefine/state.go 又复制了一份同类深拷贝函数。
• scheduleplan 侧也多处依赖同样的拷贝语义。

证据

• agent_schedule_preview.go
• schedulerefine/state.go

问题

• 这是非常典型的“纯工具函数”重复实现。
• 后面只要结构体字段一变，就容易出现一边更新一边漏更。

建议抽取

• 抽统一的 agent/core/clone 或 agent/core/snapshot。

优先级

• P0

---

3.6 预览快照读取/回填逻辑重复

现状

• runSchedulePlanFlow 自己在做：
  • 查 Redis 预览
  • miss 后查 MySQL snapshot
  • 回填 Redis
  • 清旧 preview
• runScheduleRefineFlow 又通过 loadSchedulePreviewContext 再做一套类似的逻辑。
• GetSchedulePlanPreview 也重复做：
  • 查 Redis
  • miss 查 MySQL
  • 回填 Redis

证据

• agent_schedule_plan.go
• agent_schedule_refine.go
• agent_schedule_preview.go

问题

• 这是同一个“排程预览仓储语义”，却被 service 层复制成了三种读法。
• 长期会导致缓存行为不一致。

建议抽取

• 抽成统一 schedule preview repository/gateway：
  • LoadPreviewContext
  • SavePreviewContext
  • DeletePreviewContext
  • LoadPreviewForRead

优先级

• P0

---

3.7 fallback 文案与早退逻辑重复

现状

• quicknote 有自己的 fallback reply / persisted 判定。
• taskquery 有 buildTaskQueryFallbackReply。
• scheduleplan 和 schedulerefine 里也散落大量“解析失败/模型失败/回退继续”的逻辑。

证据

• quicknote/nodes.go
• taskquery/nodes.go
• scheduleplan/nodes.go
• schedulerefine/nodes.go

问题

• 不是所有 fallback 文案都能共用，但 fallback 模式本身是共性的：
  • 模型失败 -> 本地兜底
  • JSON 失败 -> 本地兜底
  • 工具失败 -> 重试 / 降级

建议抽取

• 不建议直接抽“文案”。
• 但建议抽“失败策略框架”：
  • FallbackPolicy
  • RetryOrFallback
  • ParseOrFallback

优先级

• P1

---

3.8 时间解析能力重复 / 分散

现状

• quicknote/tool.go 内有一整套时间解析：
  • 相对时间
  • 中文时间
  • deadline hint
  • 默认时刻
• 排程链路后续也非常可能要继续用类似时间语义。

证据

• quicknote/tool.go

问题

• 目前还没出现“多份复制”，但这是非常明确的“已形成公共能力、却还放在 skill 私有目录”的情况。
• 如果不提前抽，schedule / memory / websearch 接进来后一定复制。

建议抽取

• 提前迁出到 agent/core/timeparse。

优先级

• P1

---

3.9 runner 形态重复

现状

• quicknote/runner.go
• scheduleplan/runner.go
• schedulerefine/runner.go

问题

• 本质都在做同一件事：把 graph 输入依赖注入到每个步骤函数。
• 结构相似，但没有统一约定。

建议抽取

• 不一定要抽通用基类。
• 但至少要统一 runner 模板风格，减少 skill 间阅读切换成本。

优先级

• P2

---

3.10 route 控制码能力与 skill 判定方式分裂

现状

• 统一路由已经在 route/route.go。
• 但 skill 内部仍有不少二次意图确认 / fallback 判定。

问题

• 这不是完全重复代码问题，而是“判定责任分裂”。
• 结果是：
  • route 做一遍
  • skill 首节点再做一遍
  • service 再决定回不回聊天

建议抽取

• 统一成：
  • route 只做一级分流
  • skill 只做 skill 内业务判定
  • service 不再写 skill 特有 fallback 判定

优先级

• P1

---

4. 中优先级复用点

4.1 Extra 参数解析工具只在 scheduleplan 私有

现状

• scheduleplan/tool.go 有 ExtraInt、ExtraIntSlice。

问题

• 这明显属于通用 agent 请求参数解析能力，不该锁死在某个 skill 下。

建议抽取

• 抽到 agent/core/extrax。

优先级

• P2

---

4.2 工具分发 dispatch 逻辑重复

现状

• scheduleplan/tools_react.go 有 dispatchReactTool、dispatchWeeklySingleActionTool。
• scheduleplan/daily_refine.go 有 dispatchDailyReactTool。
• schedulerefine/tool.go 有 dispatchRefineTool。

问题

• 都在做“执行工具调用 -> 应用结果 -> 返回标准结果”的模式。
• 虽然业务不同，但骨架高度类似。

建议抽取

• 抽公共的 tool dispatcher 框架，业务只实现 apply。

优先级

• P2

---

4.3 preview/snapshot DTO 映射重复

现状

• snapshotToSchedulePlanPreviewCache
• snapshotToSchedulePlanPreviewResponse
• buildSchedulePlanSnapshotFromState
• convertRefineStateToPlanState

问题

• 同一批结构在 service 层到处转来转去。
• 说明“排程预览状态”还没有独立成一个稳定模型层。

建议抽取

• 抽 schedule snapshot mapper。

优先级

• P2

---

5. 已经出现“文件承担过多职责”的区域

5.1 schedulerefine/nodes.go

• 3140 行。
• 当前同时承担：
  • 模型调用
  • JSON 解析
  • 规则归一化
  • planner
  • react loop
  • hard check
  • summary
• 这是最先需要拆的文件。

5.2 schedulerefine/tool.go

• 1768 行。
• 当前同时承担：
  • tool 定义
  • tool 分发
  • payload 解析
  • policy
  • fallback query
  • slot hint 构造
• 应拆成：
  • tool_defs
  • tool_dispatch
  • tool_payload
  • tool_policy

5.3 scheduleplan/nodes.go

• 713 行。
• 当前已经开始混：
  • plan
  • rough build
  • preview return
  • model call helper
• 现在还来得及拆。

---

6. 建议的第一批收口顺序

第一批（先抽公共层，不碰业务语义）

• P0-1 抽模型调用公共层。
• P0-2 抽 JSON 解析公共层。
• P0-3 抽深拷贝公共层。
• P0-4 抽排程预览加载/保存 gateway。

第二批（统一 skill 编排骨架）

• P1-1 统一 EmitStage。
• P1-2 统一流式阶段输出辅助。
• P1-3 统一 fallback/retry 框架。

第三批（拆超大文件）

• P2-1 拆 schedulerefine/nodes.go
• P2-2 拆 schedulerefine/tool.go
• P2-3 拆 scheduleplan/nodes.go

---

7. 可以考虑直接删除/合并的嫌疑区域

7.1 scheduleplan 与 schedulerefine 的边界可能切得过细

• 这两个包共享大量状态与工具语义。
• 后续大概率应该合并成一个 schedule 能力域，内部再区分 create/refine flow。

7.2 agentsvc 侧的排程桥接文件可能过多

• 当前已有：
  • agent_schedule_plan.go
  • agent_schedule_refine.go
  • agent_schedule_preview.go
• 这些文件后续应下沉部分逻辑到 gateway / repository / snapshot service。

---

8. 后续重构时的硬约束

• 先抽公共能力，再动 skill 业务逻辑，避免一边搬家一边改语义导致回归难查。
• 每抽一类公共件，都优先让 quicknote 和 taskquery 先接一次，确认不是只为 schedule 定制。
• 抽公共层时，不要先追求“最优抽象”，先追求“把四份重复收成一份”。

9. 一句话版本

• 当前 agent 代码最该先收口的 4 个点是：
  • 模型调用
  • JSON 解析
  • 深拷贝/快照
  • 排程预览缓存与快照读写
• 当前最该先拆的 2 个大文件是：
  • nodes.go
  • tool.go