leaudit-platform-backend/docs/RAG/RAG会话自动标题开发任务拆解与接口变更清单.md

RAG 会话自动标题开发任务拆解与接口变更清单

最后整理：2026-05-19 对应方案：docs/RAG/RAG会话自动标题生成与重命名实施方案.md

1. 本期落地范围

本期目标不是做一个“前端点一下自动命名”的伪功能，而是完成第一版可稳定运行的后端自动标题链路：

1. 新会话首轮回答完成后，后端异步生成标题
2. 手动重命名后，不再被自动标题覆盖
3. 会话列表排序从“单纯 updated_at”收口到“最后消息时间优先”
4. 前端移除旧的假自动重命名逻辑

---

2. 任务拆解

2.1 后端数据层

任务：

1. 为 rag_conversation 增加标题状态字段
2. 增加 last_message_at
3. 增加相关索引

交付物：

1. scripts/创建sql/schema_rag_chat_auto_title.sql

验收点：

1. 老数据执行 SQL 不报错
2. 默认值正确
3. 索引存在

2.2 后端会话查询层

任务：

1. 会话列表返回 titleSource
2. 会话列表返回 lastMessageAt
3. 排序改为 COALESCE(last_message_at, updated_at) DESC

验收点：

1. 自动标题更新不会让会话无故跳到顶部
2. 真正发新消息的会话仍能上浮

2.3 后端消息完成链路

任务：

1. assistant 最终落库时同步更新 last_message_at
2. 首轮回答完成后调度自动标题任务

验收点：

1. 标题生成失败不影响主回答
2. 只在首轮完整回答后触发

2.4 后端自动标题生成器

任务：

1. 新增 _maybe_schedule_auto_title(...)
2. 新增 _run_auto_title_task(...)
3. 新增 _generate_conversation_title(...)
4. 新增 _sanitize_generated_title(...)
5. 新增 _build_fallback_title(...)

验收点：

1. 同一会话不会重复并发生成标题
2. 生成失败能记状态
3. 生成成功后能回写标题

2.5 后端手动重命名链路

任务：

1. RenameConversation() 改为写入 title_source = 'manual'
2. 清空最近一次标题生成错误

验收点：

1. 用户手动改名后，后续自动任务不再覆盖

2.6 前端聊天主链路

任务：

1. 移除 generateConversationName(...) 自动调用
2. 移除 sidebarRef.autoRename(...) 自动调用
3. 回答完成后轻量刷新会话列表，把后端自动标题同步回来

验收点：

1. 首轮问答完成后，会话名称自然更新
2. 前端不再双写标题

2.7 前端会话列表排序与本地更新

任务：

1. 会话排序优先用 last_message_at
2. 仅标题更新时不再强行覆盖 updated_at

验收点：

1. 手动重命名不会导致会话跳序
2. 自动重命名不会导致会话跳序

---

3. 接口变更清单

3.1 GET /api/v3/rag/chat/conversations

新增返回字段：

{
  "id": "conversation_id",
  "name": "烟草专卖法中的烟草定义",
  "introduction": "",
  "titleSource": "auto",
  "createdAt": 1779078161,
  "updatedAt": 1779078200,
  "lastMessageAt": 1779078200
}

兼容性说明：

1. 前端旧代码即使不消费新增字段也不会炸
2. 新前端会使用 last_message_at 改善排序

3.2 PATCH /api/v3/rag/chat/conversations/{ConversationId}

本期请求体不变：

{
  "name": "我手动改的标题"
}

但服务端语义变化为：

1. 更新标题
2. 将 title_source 切为 manual
3. 保护后续自动任务不覆盖

---

4. 数据字段说明

字段	说明
title_source	default / auto / manual
title_generation_status	idle / pending / running / succeeded / failed
title_generated_at	自动标题成功时间
first_question_message_id	预留，本期可暂不写
first_answer_message_id	记录首轮回答 message_id
title_generation_error	最近一次失败原因
last_message_at	最后一次消息完成时间

---

5. 本期已知边界

1. 自动标题目前走与 follow-up 相同的在线 LLM 依赖
2. 如果 LLM 配置错误，主回答可能正常但标题生成失败
3. 本期还未增加专门的 conversation_renamed SSE 事件
4. 前端目前通过“回答完成后刷新列表”同步标题，优先保证正确性

---

6. 后续增强建议

1. 新增 conversation_renamed SSE 事件，减少列表刷新
2. 增加后台补偿任务，扫描 failed 会话再重试
3. 引入标题生成提示词版本号，便于回溯
4. 对 first_question_message_id 也做持久化，补齐审计链路