图_6Agent状态管理模块 · 详细实现
对应 [[6_代码实现_Agent 状态管理]]。按图 1 模板粒度，只写主要实现步骤。
读图方式
- 蓝底是文件，紫底是类，灰底是函数；标题与主要步骤分开，框宽随文字收紧。简单函数一句，复杂函数按主要处理阶段分步。
- 实线箭头表示调用（含 LangGraph 的节点调度），虚线箭头表示数据或对象传递。远距离用
〔调用 F07〕/〔传递 F07:2〕引用，避免拉长线。 - F / C / P 分别表示函数、类、文件；冒号后的数字指目标步骤。编号只用于定位，不表示执行次序。
- 省略普通返回、逐字段转换和重复异常处理；保留会影响业务走向的降级、HITL、终止等分支。
文件与函数索引
P01 · backend/schemas/chat.py
会话、Trace 与 HITL 数据协议。
- F01
_normalize_chunks()（源码 116 行）：规范证据列表。 - F02
_normalize_trace_fields()（源码 129 行）：规范 Trace 公共字段。 - F03
normalize_rag_sub_trace()（源码 142 行）：规范子问题 Trace。 - F04
normalize_rag_trace()（源码 149 行）：规范主 Trace 与嵌套子 Trace。 - C01
StrictSchema：协议基类。 - C02
RetrievedChunk：Trace 中的单条证据。 - C03
RagTraceFields：主 / 子 Trace 公共字段。 - C04
RagSubTrace：单个子问题的 Trace。 - C05
RagTrace：完整问题的 Trace。 - C06
HitlResumeState：最小恢复快照。 - C07
PendingHitlState：等待用户补充的任务。 - C08
ChatRequest：问答请求。 - C09
ChatResponse：问答结果。 - C10
MessageInfo：历史消息。 - C11
SessionMessagesResponse：会话消息列表。 - C12
SessionInfo：会话摘要。 - C13
SessionListResponse：会话列表。 - C14
SessionDeleteResponse：会话删除结果。
P02 · backend/chat/request_context.py
一次请求共享的运行状态。
- F05
ChatRequestContext.for_sync()（源码 47 行）：创建同步请求 ctx。 - F06
ChatRequestContext.for_stream()（源码 32 行）：创建流式请求 ctx。 - F07
ChatRequestContext.emit_rag_step()（源码 55 行）：向 SSE 队列发送检索步骤。 - F08
ChatRequestContext.store_rag_trace()（源码 98 行）：暂存本轮 Trace 与快照。 - F09
ChatRequestContext.take_rag_trace()（源码 110 行）：取走本轮检索记录。 - F10
ChatRequestContext.peek_rag_trace()（源码 116 行）：只读查看本轮检索记录。 - F11
ChatRequestContext.reset_knowledge_tool_budget()（源码 120 行）：重置知识工具预算。 - F12
ChatRequestContext.acquire_knowledge_tool_slot()（源码 124 行）：限制一轮只检索一次。 - F13
ChatRequestContext.close()（源码 131 行）：关闭本轮 ctx。 - C15
ChatRequestContext：请求内的状态与事件容器。
P03 · backend/chat/storage.py
PostgreSQL 会话存储与 Redis 缓存。
- F14
ConversationStorage._messages_cache_key()（源码 15 行）：生成消息缓存键。 - F15
ConversationStorage._sessions_cache_key()（源码 19 行）：生成会话列表缓存键。 - F16
ConversationStorage._to_langchain_messages()（源码 23 行）：把历史记录转为模型消息。 - F17
ConversationStorage._normalize_message_records()（源码 37 行）：规范历史消息 Trace。 - F18
ConversationStorage.save()（源码 45 行）：覆盖保存会话与全量历史。 - F19
ConversationStorage.load()（源码 108 行）：读取供模型使用的历史。 - F20
ConversationStorage.load_with_meta()（源码 117 行）：读取历史与会话元数据。 - F21
ConversationStorage.list_sessions()（源码 136 行）：获取会话 ID 列表。 - F22
ConversationStorage.list_session_infos()（源码 139 行）：读取会话摘要列表。 - F23
ConversationStorage.get_session_messages()（源码 173 行）：读取完整历史消息记录。 - F24
ConversationStorage.delete_session()（源码 214 行）：删除用户会话及缓存。 - C16
ConversationStorage：会话存储与缓存接口。
P04 · backend/chat/runtime.py
共享模型与按请求创建 Agent。
- F25
create_agent_for_request()（源码 50 行）：装配本轮 Agent。
调用与对象传递对照
| 出发位置 | 目标 | 类型 | 关系 |
|---|---|---|---|
| F04 · 第 1 步 | F02 _normalize_trace_fields |
实线 · 调用 | 调用 |
| F04 · 第 2 步 | F03 normalize_rag_sub_trace |
实线 · 调用 | 调用 |
| F03 · 第 1 步 | F02 _normalize_trace_fields |
实线 · 调用 | 调用 |
| F02 · 第 2 步 | F01 _normalize_chunks |
实线 · 调用 | 调用 |
| C02 · 第 1 步 | F01:1 _normalize_chunks |
虚线 · 传递 | 证据字段协议 |
| F08 · 第 1 步 | F04 normalize_rag_trace |
实线 · 调用 | Trace 规范化调用 |
| F08 · 第 1 步 | C06 HitlResumeState |
实线 · 调用 | 恢复快照校验 |
| F19 · 第 1 步 | F23 ConversationStorage.get_session_messages |
实线 · 调用 | 调用 |
| F19 · 第 2 步 | F16 ConversationStorage._to_langchain_messages |
实线 · 调用 | 调用 |
| F20 · 第 1 步 | F19 ConversationStorage.load |
实线 · 调用 | 调用 |
| F21 · 第 1 步 | F22 ConversationStorage.list_session_infos |
实线 · 调用 | 调用 |
| F23 · 第 1 步 | F17 ConversationStorage._normalize_message_records |
实线 · 调用 | 调用 |
| F18 · 第 4 步 | F14 ConversationStorage._messages_cache_key |
实线 · 调用 | 调用 |
| F18 · 第 4 步 | F15 ConversationStorage._sessions_cache_key |
实线 · 调用 | 调用 |
| F17 · 第 1 步 | F04 normalize_rag_trace |
实线 · 调用 | 规范消息 Trace |
| P03 · 第 2 步 | C16 ConversationStorage |
实线 · 调用 | 构造共享存储对象 |
| P04 · 第 1 步 | F25:2 create_agent_for_request |
虚线 · 传递 | 共享的主模型 model |
[[source/_posts/LLM/2_RAG/project/img/详细实现/项目实现|查看项目实现总图]]。概要图仍保留在“实现”文件夹。
Excalidraw Data
Text Elements
backend/：本模块的后端实现 ^444f5dea
chat/：管理请求状态、会话与对话执行 ^e9a7bff0
[[6_代码实现_Agent 状态管理|P02 request_context.py：一次请求共享的运行状态]] ^8666d058
- Service 创建本轮 ctx，显式传给 Tool 与 RAG。 ^b8100402
C15 ChatRequestContext：请求内的状态与事件容器 ^104a6b60
F05 for_sync()：创建同步请求 ctx ^35966d79
- 设置用户与会话，不绑定事件队列。 ^046f6357
F06 for_stream()：创建流式请求 ctx ^6c00d516
- 绑定用户、会话、输出 Queue 与当前事件循环。 ^390a16bf
F07 emit_rag_step()：向 SSE 队列发送检索步骤 ^ce46af95
F08 store_rag_trace()：暂存本轮 Trace 与快照 ^b135c762
-
规范 Trace，校验可选恢复快照。 〔调用 F04 / C06〕 ^6e1ab554
-
在锁内将rag trace、hitl快照写入ctx ^946f4a34
F09 take_rag_trace()：取走本轮检索记录 ^df99c532
- 在锁内读取ctx的 Trace ，随后清空暂存。 ^f3e91797
F10 peek_rag_trace()：只读查看本轮检索记录 ^493c769d
- 在锁内输出rag trace，不清空。 ^0d933497
F11 reset_knowledge_tool_budget()：重置知识工具预算 ^a977704c
- 在锁内将本轮知识工具使用次数归零。 ^dac61698
F12 acquire_knowledge_tool_slot()：限制一轮只检索一次 ^3a7492d4
- 在锁内检查并占用一次知识工具名额。 ^aee3f418
F13 close()：关闭本轮 ctx ^42eb4ed4
- 停用请求，释放 Queue 与事件循环引用。 ^4679013f
[[6_代码实现_Agent 状态管理|P04 runtime.py：共享模型与按请求创建 Agent]] ^e8991b62
-
初始化共享主模型 model 与摘要模型 fast_model。 〔传递 F25:2〕 ^a1377a6d
-
定义工具使用规则与系统提示词。 ^f70bbf36
F25 create_agent_for_request()：装配本轮 Agent ^817d9b9f
-
将 ctx 绑定到知识工具。 ^54117bd7
-
组合主模型、知识 Tool、天气 Tool 与系统提示词。 ^6e339ef2
[[6_代码实现_Agent 状态管理|P03 storage.py：PostgreSQL 会话存储与 Redis 缓存]] ^69f0496d
-
复用关系库模型、数据库session和 Redis cache。 ^354a2376
-
创建共享 storage = ConversationStorage()。 〔调用 C16〕 ^d5960503
C16 ConversationStorage：会话存储与缓存接口 ^93fc028c
F18 save()：覆盖保存会话与全量历史 ^8abafa15
-
按用户查找或创建会话，合并传入的 metadata。 ^e6a997b6
-
全量删除当前会话的旧消息，重写本轮提供的全部历史与消息 Trace。 ^e46b27cd
-
提交 PostgreSQL。 ^56c27a45
-
刷新消息缓存，清除用户的会话列表缓存，全量更新 〔调 F14 / F15〕 ^2cf845ad
F19 load()：加载指定对话的历史消息 ^26002b71
-
优先读消息缓存，未命中则查询并缓存消息记录。 〔调用 F23〕 ^168f6367
-
转换为 LangChain 消息列表。 〔调用 F16〕 ^d7fe8412
F20 load_with_meta()：加载指定对话的历史消息与元数据 ^47a47d29
-
调用 load() 读取模型消息。 〔调用 F19〕 ^f14480da
-
从 PostgreSQL 读取对应 metadata。 ^0a805407
F16 _to_langchain_messages()：将数据库消息转换为 LangChain 消息对象 ^a2b1abfb
- 按消息类型构造 Human / AI / System Message。 ^37da16c6
F23 get_session_messages()：读取完整历史消息记录 ^7a357786
-
优先读缓存，并规范其中的 Trace。 〔调用 F17〕 ^1346897c
-
未命中则按消息顺序查询 PostgreSQL。 ^60722681
-
整理正文、时间与 Trace，写入缓存。 ^a1c25c03
F17 _normalize_message_records()：规范历史消息 Trace ^43d3ab2a
- 逐条规范消息记录中的 rag_trace。 〔调用 F04〕 ^85500c2f
F21 list_sessions()：获取用户所有的会话 ID 列表 ^5b5b6126
- 从会话摘要列表提取 session_id。 〔调用 F22〕 ^2adda99b
F22 list_session_infos()：读取用户所有会话的摘要列表 ^64f20d56
-
优先读列表缓存。 ^2928f798
-
未命中则查询用户会话，按更新时间倒序排列。 ^b3bfa0fc
-
整理标题、时间和消息数，写入缓存。 ^61876abf
F24 delete_session()：删除用户会话及缓存 ^0dadb885
-
按用户与会话 ID 查询记录。 ^0c6f499a
-
删除会话并提交，级联删除消息。 ^a3a6f32f
-
清除消息缓存和会话列表缓存。 ^40815f09
F14 _messages_cache_key()：生成一个会话的缓存key ^4aa2d794
- 拼接 chat_messages:用户:会话。 ^c286e3de
F15 _sessions_cache_key()：生成会话列表缓存key ^2f2b0301
- 拼接 chat_sessions:用户。 ^9ebf54db
schemas/：约束交换数据与恢复协议 ^22f44878
[[6_代码实现_Agent 状态管理|P01 chat.py：会话、Trace 与 HITL 数据协议]] ^489e65af
-
定义请求、消息、Trace 与 HITL 数据类，包含两个层级的数据格式： chat rag ^9018e0b6
-
提供 Trace 规范化函数，供交换与存储前使用。 ^dd43cdc8
C04 RagSubTrace：子问题 Trace ^e089e251
- 继承公共 Trace 字段。 ^cffee7fc
C07 PendingHitlState：等待用户补充的任务 ^9aac155e
C10 MessageInfo：历史消息 ^1456fbe2
- 用于前端加载和展示聊天记录： type、content、timestamp、rag_trace ^caac0dbc
C13 SessionListResponse：会话列表 ^46265ed9
- 查询用户所有聊天会话时，后端返回的数据格式： sessions，元素为 SessionInfo。 ^5406d9c0
C02 RetrievedChunk：Trace 中单条证据 ^7c253cca
- 属性： 来源文件、 页码、 正文、 召回分、 混合检索排名、 重排分 〔传递 F01:1〕 ^7655f84d
C05 RagTrace：完整问题的 Trace ^194d7b3b
- 增加 sub_traces 子轨迹列表。 ^bbc480e9
C08 ChatRequest：问请求 ^701bfc1a
- 前端向后端发送聊天请求时的数据格式： message、session_id。 ^ff648edb
C11 SessionMessagesResponse：会话消息列表 ^57be5beb
- 查询某个会话的全部历史消息时，后端返回的数据格式 messages，元素为 MessageInfo。 ^d7c11c7a
C14 SessionDeleteResponse：会话删除结果 ^6ee46f79
- 删除聊天会话成功后，后端返回给前端的数据格式： session_id、message。 ^8e994836
C06 HitlResumeState：HITL最小恢复快照 ^b2ec2d33
- 属性： 原问题 HITL 路由（澄清/选择） 检索状态（需要澄清/需要选择） 已执行的改写次数 原问题复杂度 复杂度判断原因 子问题（最多四个） ^f4d3131a
C09 ChatResponse：答结果 ^3e42d127
- 后端普通聊天接口返回给前端的数据格式： response、rag_trace。 ^e2edd6a4
C12 SessionInfo：会话摘要 ^80afdbfe
- 一个聊天会话的基本信息，主要用于前端展示历史会话列表： session_id、title、updated_at、message_count。 ^1d0c89d5
F04 normalize_rag_trace()：规范主 Trace 与子 Trace ^174655c8
-
清理主 Trace 的公共字段。 〔调用 F02〕 ^a904b122
-
逐条规范子 Trace，再按 RagTrace 校验。 〔调用 F03〕 ^38bfbe54
F03 normalize_rag_sub_trace()：规范子问题 Trace ^c0b72e59
- 清理公共字段，按 RagSubTrace 校验。 〔调用 F02〕 ^a7235ead
F02 _normalize_trace_fields()：规范 Trace 公共字段 ^693fd5a8
-
保留协议声明的字段。 ^09c95c5e
-
统一规范各检索阶段的证据列表。 〔调用 F01〕 ^ea2f957e
F01 _normalize_chunks()：规范证据列表 ^58cbc560
- 提取有文件名证据 ^b0735d15
C03 RagTraceFields：主 / 子 Trace 公共字段 ^CYJ6qzMu
-
工具及查询： 是否使用了rag工具，工具名，query， 当前检索阶段（初始检索/重写/子问题合并/HITL检索）
-
复杂度判断： 复杂度，复杂原因，子问题，子agent数，子问题合并后证据数
-
检索配置： 检索方式，检索流程标识，初始召回数量，召回数量确定方式（env/multiplier）, 召回数量配置错误，召回数量multiplier，期望topk，实际召回数量， 初始检索的chunk层级
-
子块合并： 是否启用，是否发生，触发阈值，实际被替换的子块数，发生层级，合并后候选数
-
重排： 是否启用，是否发生，rerank模型，模型api，rerank错误信息，rerank超时阈值， 最低相关性阈值，进入重排的候选数，rerank后候选数，相关性阈值过滤后候选数， 最终检索结果是否为空 ^KP6kW7Bd
-
继承公共字段 ^HBfEdynl
-
属性： 任务 ID 原问题（可跨多轮HITL） 澄清提示词 选项 HITL类型（澄清/选择） 检索状态（需要澄清/需要选择） 用户补充信息 HITL创建时间 ^nuk7Slvi
RAG快照 ^SNjImx4I
- 共有属性： 用户id 会话id 流式事件队列
- 私有属性： 读写安全锁 请求是否有效 rag trace 本轮知识库工具已经调用的次数 本次上下文创建时间 上次rag进度时间的时间
- 方法： ^R2qlC0Uk
会话列表 ^ZhMNacZ2
单个会话 ^qIIuYcPD
单个消息 ^LnYV8mO6
检索轨迹 ^ysweCOdb
-
初始检索证据（若没做rerank，就是初始召回的证据） ^qmiC10Be
-
证据评分： 评分路由（回答/澄清），证据状态（充足，部分充足，待澄清，待选择）， 证据相关性（强/弱），证据可回答性（充足，部分充足，无）， 证据歧义（缺条件，要选择），证据评分置信度，评分原因 ^g4Hdr2jQ
-
重写： 重写方式（退步/假设），重写后的query，退步问题，假设文档，重写后检索到的证据
-
最终检索证据 ^Gilx9T0F
-
HITL： 确实的关键条件，澄清提示词，澄清选项，是否执行了HITL恢复，用户补充信息， HITL恢复策略（单一值），恢复前的检索快照，恢复后检索到的证据 ^CuTzO5vK
HITL任务 ^drnDxsep
提取字段 ^1GYtYfNL
-
按 RetrievedChunk 取出需要的key ^qNTq5jj4
-
每条证据中只提取RetrievedChunk 中定义的字段 ^woA6Qddq
-
初始化（同步/异步） ^jlUPHOGM
-
工具调用控制 ^A5vhntBu
-
RAG进度通知 ^7xcDEvuO
-
RAG 轨迹管理 ^Bb74IxYf
-
ctx生命周期管理 ^uOyA3diL
-
申请rag工具调用额度 ^vCjvLxbk
-
rag工具调用额度置零 ^i9dfYPn6
-
暂存RAG 轨迹和HITL快照 ^CI1jZTis
-
查看暂存的Trace ^LlYs8aFe
-
取出暂存的Trace，并清空 ^62ie4CGz
-
在锁内检访问ctx的属性： 1. 当前ctx失活 / 非流失请求：结束 2. 读取共享属性：上一次记录的时间，消息队列，事件循环 3. 更新上一次记录时间为当前事件，计算累积耗时
-
将事件跨线程投递到chat进程的loop的消息队列 ^ZBtS4kGk
-
缓存key与数据转换 ^PTQb5q4s
-
会话管理： ^73cKmrdP
-
会话保存 ^QQOKRl20
-
会话历史加载 ^7JQQEN5U
-
会话列表管理 ^TU9ELMG7
-
会话删除 ^JM6BFzZV
-
数据转换 ^rCMrHjLh
Element Links
8666d058: [[6_代码实现_Agent 状态管理]]
e8991b62: [[6_代码实现_Agent 状态管理]]
69f0496d: [[6_代码实现_Agent 状态管理]]
489e65af: [[6_代码实现_Agent 状态管理]]
%%
Drawing
1 | N4KAkARALgngDgUwgLgAQQQDwMYEMA2AlgCYBOuA7hADTgQBuCpAzoQPYB2KqATLZMzYBXUtiRoIACyhQ4zZAHoFAc0JRJQgEYA6bGwC2CgF7N6hbEcK4OCtptbErHALRY8RMpWdx8Q1TdIEfARcZgRmBShcZQUebR4ATm0ARho6IIR9BA4oZm4AbXAwUDBSiBJuCB4AFgQABjqAVmTcNNLIWERKwOwojmVgtrLMbgA2AHZtRv4ymG5k8YBmbUXV |
%%
