smartmate/backend/services/memory/docs/legacy/第三步治理与观测落地计划.md

Memory 第三步治理与观测落地计划

1. 这份文档解决什么问题

这份文档只回答第三步要做什么，不再重复前两步已经完成的抽取、决策、召回细节。

第三步的目标很简单：

1. 把 memory 从“能跑”升级成“敢灰度、敢排障、敢清理、敢回滚”。
2. 把“日志打在哪里、我怎么看、会不会给接口”说清楚。
3. 把改动范围收敛在治理层，不再继续扩算法和能力边界。

一句人话总结：

前两步解决的是“有没有能力”，第三步解决的是“出了问题怎么查、怎么收、怎么退”。

---

2. 先说结论

第三步我会分成两块做：

1. 观测与切流
2. 用户管理与清理

为什么这么拆：

1. 现在第二步最小闭环已经通了，最怕的不是“能力不够多”，而是“出了问题不知道卡在哪一层”。
2. 如果没有统一日志、指标和开关，后面再继续加功能，只会让 memory 变成一个越来越难维护的黑箱。
3. 历史重复脏数据不先治理，后面读链路和注入链路的数据噪音会越来越重。

第三步不追求“更聪明”，追求“更稳、更可控”。

---

3. 你最关心的三个问题

3.1 日志会打在哪里

第三步不会把所有信息都塞进一个地方，而是分三层：

A. 运行日志

运行日志打到后端服务本身的标准日志，也就是当前 backend 进程控制台 / 容器 stdout。

这层主要看实时链路，适合排查：

1. 这次写入为什么是 ADD / UPDATE / DELETE / NONE
2. 这次召回为什么没命中
3. 这次注入为什么降级到 flat 或 legacy
4. 这次 worker 为什么走了 fallback

这层的形态参考当前 RAG 轻量 Observer 的做法，不单独造一套散装日志方案。

参考文件：

1. backend/cmd/start.go
2. backend/infra/rag/core/observer.go

B. 变更留痕

变更留痕继续落库，不只打终端。

当前已经有：

1. memory_audit_logs 表
2. backend/model/memory.go
3. backend/memory/repo/audit_repo.go

这层主要看“已经发生过的变更事实”，适合研发排查和后端自查：

1. 哪条记忆被删了
2. 删之前和删之后内容是什么
3. 这次 dedup 清理保留了哪条，归档了哪条
4. 某次 update / delete / restore 是谁触发的，原因是什么

C. 汇总指标

第一版不先上完整 Prometheus / Grafana 平台，而是先把关键指标打稳，再视需要接统一观测平台。

这层主要看趋势和健康度，适合回答：

1. 最近写入成功率怎么样
2. hybrid 召回到底有没有提升
3. 去重到底丢了多少垃圾数据
4. 是否频繁回滚到 legacy

---

3.2 我会怎么看

开发和联调阶段，推荐分两种看法：

看实时问题

直接看后端运行日志。

适合看：

1. 单次请求链路
2. 单次 worker 执行过程
3. fallback / 降级 / 回滚是否发生

看历史问题

直接查数据库留痕表和主表。

适合看：

1. 某条 memory 历史上被怎么改过
2. 某次清理动作具体处理了哪些记录
3. 当前 active / archived / deleted 分布

建议排查时优先查这几张表：

1. memory_jobs
2. memory_items
3. memory_audit_logs

第一版就够用了，不强依赖前端页面才能排查。

---

3.3 会不会提供接口

会，但原则上只补“面向当前用户管理自己记忆”的接口，不补“原始运行日志接口”，也不把 memory 先做成全项目唯一完整的审计后台。

原因很直接：

1. 原始日志噪音很大，不适合直接给前端看。
2. 原始日志字段会迭代，直接对外暴露会把内部实现绑死。
3. 原始日志可能带内部 trace、错误细节，不适合直接外露。

所以第三步对外提供的是“用户管理自己记忆”的接口，不是“把 stdout 原样吐给前端”，也不是“先给 memory 单独造一套管理后台接口”。

第三步建议优先补这几类用户接口：

第一组：当前用户查看自己的记忆

1. GET /api/v1/memory/items
   • 分页查看“我自己的记忆”
2. GET /api/v1/memory/items/:id
   • 查看“我自己的某条记忆”详情

第二组：当前用户主动维护自己的记忆

1. POST /api/v1/memory/items
   • 手动新增一条记忆
2. PATCH /api/v1/memory/items/:id
   • 修改自己的一条记忆
3. DELETE /api/v1/memory/items/:id
   • 删除自己的一条记忆

第三组：当前用户恢复误删内容

1. POST /api/v1/memory/items/:id/restore
   • 若底层采用软删或归档，可补恢复动作

这些接口都默认只允许操作“当前登录用户自己的记忆”，不支持跨用户查询和跨用户修改。

原则：

1. 原始日志看后端 stdout
2. 内部变更留痕优先给后端查表和排障使用，不急着做成前端正式能力
3. 对外先开放用户真正会用到的“我的记忆”增删改查

---

4. 第三步到底要做什么

4.1 观测与切流

这是第三步的第一优先级。

要做的事

1. 给写入决策链路补统一结构化日志
2. 给读侧召回链路补统一结构化日志
3. 给注入渲染链路补统一结构化日志
4. 给上述三条链路补关键计数指标
5. 把现有配置字段整理成清晰的切流顺序和回滚手册

为什么先做这个

因为第三步如果先做 dedup 清理，但没有日志和切流能力，一旦清错了，排查成本会很高。

---

4.2 用户管理与清理

这是第三步的第二优先级。

要做的事

1. 给“我的记忆”补完整增删改查语义
2. 给历史重复数据补离线 dedup 工具
3. 给关键变更动作补最小留痕
4. 把 dedup 保持在后端内部治理流程，不急着做成前端接口

为什么不一上来绑主 worker

因为第一版 dedup 的目标是“可留痕、可回滚”，不是“全自动”，也不是先给 memory 单独造一个很重的治理后台。

离线或手动触发更安全，出问题也更容易止血。

---

5. 具体改动计划

5.1 第一轮：先把观测底座补起来

目标

先让系统“可看见”。

预计改动

新增：

1. backend/memory/observe/log_fields.go

修改：

1. backend/memory/worker/decision_flow.go
2. backend/memory/worker/apply_actions.go
3. backend/memory/service/read_service.go
4. backend/memory/service/retrieve_merge.go
5. backend/service/agentsvc/agent_memory.go
6. backend/service/agentsvc/agent_memory_render.go

这一轮会补什么日志

写入决策日志

至少记录这些字段：

1. trace_id
2. user_id
3. conversation_id
4. job_id
5. fact_type
6. candidate_count
7. final_action
8. fallback_mode
9. success

读侧召回日志

至少记录这些字段：

1. trace_id
2. user_id
3. read_mode
4. query_len
5. legacy_hit_count
6. semantic_hit_count
7. dedup_drop_count
8. final_count
9. degraded

注入渲染日志

至少记录这些字段：

1. trace_id
2. user_id
3. inject_mode
4. input_count
5. rendered_count
6. token_budget
7. fallback

---

5.2 第二轮：补指标，不急着开 overview 接口

目标

先让系统“可量化”。

第一版建议补的指标

优先补这 8 个：

1. memory_job_success_rate
2. memory_job_retry_rate
3. memory_decision_distribution
4. memory_decision_fallback_rate
5. memory_retrieve_hit_count
6. memory_retrieve_dedup_drop_count
7. memory_inject_item_count
8. memory_rag_fallback_rate

暂不强求第一版就补：

1. memory_wrong_mention_rate
2. memory_user_correction_rate

因为这两个更依赖后续“用户纠错入口”。

这一轮先不做什么

这一轮先不单独新增 GET /api/v1/memory/overview。

原因不是这个接口没价值，而是现在别的模块还没有统一的观测面板和汇总接口规范。memory 这一轮先把指标打稳，后续如果全项目一起做观测面板，再统一收口更对称。

也就是说，这一轮优先把“数据先有”做出来，不急着把“看板接口先长出来”。

---

5.3 第三轮：补用户管理动作

目标

先让用户“能管理自己的记忆”。

预计改动

修改：

1. backend/memory/service/manage_service.go
2. backend/memory/repo/item_repo.go
3. backend/memory/utils/audit.go
4. backend/memory/module.go

新增：

1. backend/api/memory.go
2. 路由注册文件中的 memory 接线

要补的动作

1. list
2. detail
3. create
4. update
5. delete
6. 若底层保留软删语义，再补 restore

接口建议

新增：

1. GET /api/v1/memory/items
2. GET /api/v1/memory/items/:id
3. POST /api/v1/memory/items
4. PATCH /api/v1/memory/items/:id
5. DELETE /api/v1/memory/items/:id
6. POST /api/v1/memory/items/:id/restore
   • 仅在底层采用软删或归档方案时开放

设计要求

1. 所有接口默认只作用于“当前登录用户自己的记忆”
2. 后端仍保留最小变更留痕，但不把它包装成用户侧“审计接口”
3. 接口返回给前端的是“人能看懂的记忆内容和操作结果”，不是底层日志

---

5.4 第四轮：做离线 dedup 治理

目标

先让系统“可清理”。

预计新增

1. backend/memory/cleanup/dedup_runner.go
2. backend/memory/cleanup/dedup_policy.go

第一版治理规则

按以下维度扫描重复组：

1. user_id
2. memory_type
3. content_hash
4. status = active

每组处理规则：

1. 选一条主记录保留
2. 优先保留最近更新的
3. 若最近更新时间接近，则优先保留置信度更高的
4. 其余记录改为 archived
5. 每次治理动作都写最小变更留痕

接口建议

这一轮不对外新增 dedup 接口。

dedup 先保留为后端内部治理能力，必要时通过离线任务、后台命令或内部 job 触发，避免 memory 先演化成一个比其他模块更重的专用治理后台。

明确限制

第一版不做：

1. 直接危险 SQL 清表
2. 自动定时常驻清理
3. 无留痕的批量删除

---

6. 日志、留痕、接口分别给谁看

这个地方一定要分清，不然第三步会越做越乱。

运行日志

给研发和排障看。

特点：

1. 实时
2. 噪音大
3. 字段多
4. 不直接给前端

变更留痕

先给研发和后端排障使用。

特点：

1. 是持久化结果
2. 适合看历史
3. 这一轮不急着做成正式用户接口

用户接口

给用户和前端页面看。

特点：

1. 只暴露“我的记忆”内容和操作结果
2. 不暴露内部 raw log
3. 不承载平台级观测职责

---

7. 切流顺序

第三步不允许一刀切。

建议严格按下面顺序灰度：

1. 阶段 A：决策层 shadow
   • 真正写库仍然走 legacy
   • 新决策层只记日志，不生效
2. 阶段 B：决策层仅对显式记忆生效
3. 阶段 C：决策层对全部写入生效
4. 阶段 D：读侧切到 hybrid
5. 阶段 E：注入切到 typed_v2
6. 阶段 F：历史清理跑完，再考虑关闭 legacy 默认路径

这里的配置基础已经存在，关键是把切流顺序写清、用清、能回退。

参考文件：

1. backend/memory/model/config.go
2. backend/memory/service/config_loader.go

---

8. 回滚方案

第三步的回滚不应影响前两步代码保留，只回切开关。

最小回滚动作

1. 写侧回到 legacy
2. 读侧回到 legacy
3. 注入回到 flat
4. 停掉 dedup 清理任务

回滚原则

1. 先停治理动作，再回切主路径
2. 不做破坏性 schema 回滚
3. 不依赖人工热修逻辑判断

---

9. 第三步明确不做什么

为了防止范围失控，这一轮明确不做：

1. 不做图记忆
2. 不做多 Provider 工厂化
3. 不拆独立 memory 服务
4. 不在这一轮给 memory 先单独做完整审计后台
5. 不把 WebSearch 和 Memory 强行合并成一轮上线
6. 不再扩新的召回算法分支

---

10. 完成标准

满足以下条件，算第三步完成：

1. 能从日志看清某条记忆为什么被判成 ADD / UPDATE / DELETE / NONE
2. 能从指标看清召回命中、去重、降级、回滚情况
3. 用户能通过接口管理自己的记忆
4. 能对历史重复数据做可留痕清理
5. 出异常时能通过开关在分钟级切回 legacy
6. 文档和代码现状一致，不再靠口头传递

---

11. 如果只看一页，请看这个执行顺序

第三步不要散着做，建议按这个顺序推进：

1. 先补统一日志字段和结构化日志
2. 再补指标，把观测数据打稳
3. 再补“我的记忆”增删改查能力
4. 最后做离线 dedup 和内部清理能力

一句人话总结：

先让系统“看得见”，再让系统“能管理”，最后再让系统“敢清理”。