图_7Agent对话编排模块 · 详细实现
对应 [[7_代码实现_Agent 对话编排]]。按图 1 模板粒度，只写主要实现步骤。
读图方式
- 蓝底是文件，紫底是类，灰底是函数；标题与主要步骤分开，框宽随文字收紧。简单函数一句，复杂函数按主要处理阶段分步。
- 实线箭头表示调用（含 LangGraph 的节点调度），虚线箭头表示数据或对象传递。远距离用
〔调用 F07〕/〔传递 F07:2〕引用，避免拉长线。 - F / C / P 分别表示函数、类、文件；冒号后的数字指目标步骤。编号只用于定位，不表示执行次序。
- 省略普通返回、逐字段转换和重复异常处理；保留会影响业务走向的降级、HITL、终止等分支。
文件与函数索引
P01 · backend/chat/service.py
同步 / 流式对话、跨轮 HITL 与长期笔记。
- F01
_is_hitl_trace()（源码 19 行）：识别待补充状态。 - F02
_hitl_route_from_trace()（源码 27 行）：识别追问类型。 - F03
_hitl_prompt_from_trace()（源码 35 行）：获取追问文本。 - F04
_hitl_options_from_trace()（源码 45 行）：整理方向选项。 - F05
_format_hitl_message()（源码 52 行）：组合可保存的追问。 - F06
_existing_hitl_answers()（源码 61 行）：整理此前用户补充。 - F07
_build_pending_hitl()（源码 70 行）：构建待处理 HITL 任务。 - F08
_build_hitl_event()（源码 94 行）：构建对外 HITL 事件。 - F09
_build_hitl_resume_query()（源码 105 行）：构造兼容路径的继续请求。 - F10
_current_pending_hitl()（源码 127 行）：读取有效的待补充任务。 - F11
_pending_resume_state()（源码 136 行）：取得恢复快照。 - F12
_extract_ai_content()（源码 143 行）：统一提取模型文本。 - F13
_format_retrieved_chunks()（源码 158 行）：整理恢复检索的证据。 - F14
_build_resume_answer_messages()（源码 168 行）：构造恢复后的回答输入。 - F15
_no_knowledge_response()（源码 201 行）：无可靠知识时的固定提示。 - F16
_resume_rag_from_hitl_sync()（源码 205 行）：调用专用 RAG 恢复入口。 - F17
_answer_resumed_rag_sync()（源码 214 行）：依据恢复证据直接回答。 - F18
_build_context_messages()（源码 225 行）：组合短期历史与长期笔记。 - F19
_should_update_persistent_note()（源码 247 行）：判断是否维护长期笔记。 - F20
update_persistent_note()（源码 252 行）：异步更新长期笔记。 - F21
generate_session_title()（源码 270 行）：本地生成会话标题。 - F22
_update_persistent_note_sync()（源码 275 行）：用 FAST_MODEL 压缩长期记忆。 - F23
chat_with_agent()（源码 313 行）：同步执行一轮对话。 - F24
chat_with_agent_stream()（源码 440 行）：流式执行一轮对话。 - F25
chat_with_agent_stream._agent_worker()（源码 590 行）：生产流式内容与结束信号。
调用与对象传递对照
| 出发位置 | 目标 | 类型 | 关系 |
|---|---|---|---|
| F23 · 第 1 步 | F10 _current_pending_hitl |
实线 · 调用 | 调用 |
| F23 · 第 3 步 | F11 _pending_resume_state |
实线 · 调用 | 调用 |
| F23 · 第 3 步 | F16 _resume_rag_from_hitl_sync |
实线 · 调用 | 调用 |
| F23 · 第 3 步 | F17 _answer_resumed_rag_sync |
实线 · 调用 | 调用 |
| F23 · 第 3 步 | F18 _build_context_messages |
实线 · 调用 | 调用 |
| F23 · 第 4 步 | F07 _build_pending_hitl |
实线 · 调用 | 调用 |
| F23 · 第 5 步 | F21 generate_session_title |
实线 · 调用 | 调用 |
| F23 · 第 5 步 | F19 _should_update_persistent_note |
实线 · 调用 | 调用 |
| F23 · 第 5 步 | F22 _update_persistent_note_sync |
实线 · 调用 | 调用 |
| F24 · 第 3 步 | F25 chat_with_agent_stream._agent_worker |
实线 · 调用 | 调用 |
| F24 · 第 5 步 | F08 _build_hitl_event |
实线 · 调用 | 调用 |
| F24 · 第 6 步 | F20 update_persistent_note |
实线 · 调用 | 调用 |
| F07 · 第 1 步 | F03 _hitl_prompt_from_trace |
实线 · 调用 | 调用 |
| F07 · 第 1 步 | F04 _hitl_options_from_trace |
实线 · 调用 | 调用 |
| F07 · 第 1 步 | F02 _hitl_route_from_trace |
实线 · 调用 | 调用 |
| F03 · 第 1 步 | F02 _hitl_route_from_trace |
实线 · 调用 | 调用 |
| F09 · 第 1 步 | F06 _existing_hitl_answers |
实线 · 调用 | 调用 |
| F16 · 第 1 步 | F11 _pending_resume_state |
实线 · 调用 | 调用 |
| F17 · 第 1 步 | F15 _no_knowledge_response |
实线 · 调用 | 调用 |
| F17 · 第 2 步 | F14 _build_resume_answer_messages |
实线 · 调用 | 调用 |
| F17 · 第 2 步 | F12 _extract_ai_content |
实线 · 调用 | 调用 |
| F14 · 第 1 步 | F13 _format_retrieved_chunks |
实线 · 调用 | 调用 |
| F20 · 第 1 步 | F22 _update_persistent_note_sync |
实线 · 调用 | 调用 |
| F22 · 第 1 步 | F12 _extract_ai_content |
实线 · 调用 | 调用 |
| F25 · 第 2 步 | F01 _is_hitl_trace |
实线 · 调用 | 调用 |
| F13 · 第 1 步 | F14:2 _build_resume_answer_messages |
虚线 · 传递 | 带来源编号的证据上下文 |
| F25 · 第 3 步 | F24:4 chat_with_agent_stream |
虚线 · 传递 | Queue 中的 content 事件 |
[[source/_posts/LLM/2_RAG/project/img/详细实现/项目实现|查看项目实现总图]]。概要图仍保留在“实现”文件夹。
Excalidraw Data
Text Elements
07 Agent对话编排模块 · 详细实现 ^39c92af6
灰框：函数 | 紫框：类 | 蓝框：文件。实线：调用 | 虚线：数据 / 对象传递。 ^b58ed29d
backend/：本模块的后端实现 ^4c76ac4d
远距离使用〔调用 / 传递 Fxx〕引用；编号用于定位，框内数字表示实现步骤。 ^43a803df
chat/：管理请求状态、会话与对话执行 ^3327a1cf
[[7_代码实现_Agent 对话编排|P01 service.py：同步 / 流式对话、跨轮 HITL 与长期笔记]] ^9d5fc385
-
导入 storage、请求 ctx、共享模型与 Agent 工厂。 ^dc387e77
-
设置最近历史窗口为 6 条，维护会话 pending_hitl。 ^8cfe7bec
同步入口与长期笔记 ^d444b1a5
F23 chat_with_agent()：同步执行一轮对话 ^dbecaa07
-
读取历史、长期笔记和待处理 HITL。 〔调用 F10〕 ^28afeddc
-
创建 ctx，重置预算，先保存用户消息。 ^3acde2c4
-
普通路径执行 Agent；有效 HITL 快照走专用恢复与回答。 〔调用 F11 / F16 / F17 / F18〕 ^f8b18b9c
-
整理 Trace，需要补充时生成标准追问与新任务。 〔调用 F07〕 ^c0bc9acd
-
更新标题、长期笔记与 pending_hitl。 〔调用 F21 / F19 / F22〕 ^8f0242d5
-
保存 AI 消息和 Trace，关闭 ctx。 ^0d64ed0b
F18 _build_context_messages()：组合短期历史与长期笔记 ^f121bfa1
-
保留最近 6 条历史消息。 ^5c6cd1cd
-
依次加入长期笔记、最近历史和当前问题。 ^624973d7
F21 generate_session_title()：本地生成会话标题 ^6eee0c15
- 清理首问，截取前 16 个字符作为标题。 ^c7c50eb4
F19 _should_update_persistent_note()：判断是否维护长期笔记 ^2a30f7f6
- 已有笔记或历史超过 6 条时需要更新。 ^d4b3b924
F22 _update_persistent_note_sync()：用 FAST_MODEL 压缩长期记忆 ^4fb51a8c
-
组合旧笔记、本轮问答与首次建笔记时的历史。 〔调用 F12〕 ^f80606fd
-
调用摘要模型合并为约 500 字内笔记；失败保留旧笔记。 ^0b5defc9
F20 update_persistent_note()：异步更新长期笔记 ^b854b4d6
- 在线程池中执行同步笔记更新。 〔调用 F22〕 ^b256b385
流式入口与证据回答 ^a97f0ff9
F24 chat_with_agent_stream()：流式执行一轮对话 ^c012df44
-
读取会话状态，创建 Queue / ctx，先保存用户消息。 ^7ad9543a
-
HITL 路径在线程池恢复检索，按新证据回答或继续追问。 ^92460e47
-
普通路径创建 Agent，首轮发标题，启动 Worker。 〔调用 F25〕 ^68ab4c17
-
持续消费 Queue，发送 SSE；结束时清理未完成 Worker。 ^ad13c991
-
整理 Trace / HITL 事件，发送 [DONE]。 〔调用 F08〕 ^a31fb38c
-
更新长期笔记与 metadata，保存 AI 消息和 Trace。 〔调用 F20〕 ^51e2755a
-
关闭本轮 ctx。 ^2367fdd1
F25 _agent_worker()：生产流式内容与结束信号 ^fb2db0b6
-
迭代 Agent 输出，过滤工具调用块，只提取 AI 文本。 ^721f4a03
-
若 Trace 要求 HITL，抑制普通回答。 〔调用 F01〕 ^9f378057
-
否则累积文本并写入 Queue。 〔传递 F24:4〕 ^f9713219
-
异常时发送错误事件；结束时写入终止信号。 ^6b0e6a22
F12 _extract_ai_content()：统一提取模型文本 ^f6bbc8f5
- 从字符串或混合内容块中提取文本。 ^99872261
F13 _format_retrieved_chunks()：整理恢复检索的证据 ^d158cefe
- 给片段编号，拼接文件、页码与正文。 〔传递 F14:2〕 ^fa6d785f
F14 _build_resume_answer_messages()：构造恢复后的回答输入 ^d6bcc2b2
-
整理新证据，约束模型依据证据并带编号引用。 〔调用 F13〕 ^e523054c
-
组合原问题、追问与用户补充，生成模型消息。 ^9e2eec01
F15 _no_knowledge_response()：无可靠知识时的固定提示 ^23768ab5
- 告知当前证据不足，暂时无法回答。 ^5f3ca27b
跨轮 HITL 恢复 ^7d3b94eb
F10 _current_pending_hitl()：读取有效的待补充任务 ^7306edcc
- 按 PendingHitlState 校验 metadata 中的任务，无效则忽略。 ^d2873620
F11 _pending_resume_state()：取得恢复快照 ^e3680aec
- 从待处理任务中复制 resume_state。 ^97b9846e
F06 _existing_hitl_answers()：整理此前用户补充 ^8d61692b
- 从待处理任务中提取有效的已补充答案。 ^bf0442d0
F09 _build_hitl_resume_query()：构造兼容路径的继续请求 ^d0f26b89
-
组合原问题、追问与此前补充。 〔调用 F06〕 ^f2a4fe11
-
加入本轮补充，提示继续原任务。 ^0f169f62
F16 _resume_rag_from_hitl_sync()：调用专用 RAG 恢复入口 ^1aabcd4b
-
取出有效快照。 〔调用 F11〕 ^20fd7e8c
-
携带用户补充与 ctx，调用 resume_rag_from_hitl()。 ^b9c6003e
F17 _answer_resumed_rag_sync()：依据恢复证据直接回答 ^bf7a0e5b
-
无可用证据时给出无知识提示。 〔调用 F15〕 ^dfb6f693
-
有证据时构造回答输入，调用主模型并提取文本。 〔调用 F14 / F12〕 ^198e6365
HITL 任务与事件构造 ^c33f5199
F07 _build_pending_hitl()：构建待处理 HITL 任务 ^1f7067a5
-
提取追问、选项与路由。 〔调用 F03 / F04 / F02〕 ^85fe8399
-
加入原问题、补充历史、恢复快照和任务标识。 ^0bbd478d
-
按 PendingHitlState 校验。 ^99bedd44
F03 _hitl_prompt_from_trace()：获取追问文本 ^a84b22ef
- 采用 Trace 的追问，缺失时按类型生成默认提示。 〔调用 F02〕 ^bf560863
F02 _hitl_route_from_trace()：识别追问类型 ^42997242
- 区分补充条件 clarify 与选择方向 scope_select。 ^217931e1
F04 _hitl_options_from_trace()：整理方向选项 ^26a687e1
- 清理选项列表，去除空项。 ^ed1ec8c9
F05 _format_hitl_message()：组合可保存的追问 ^d5e27209
- 把追问与可选方向组合为消息正文。 ^11de3ea3
F08 _build_hitl_event()：构建对外 HITL 事件 ^b9d5435e
- 提取任务标识、追问、选项与状态，不暴露恢复快照。 ^bb453b6b
F01 _is_hitl_trace()：识别待补充状态 ^0ab60cd7
- 根据 Trace 的状态或路由判断是否需要 HITL。 ^9045c500
Element Links
9d5fc385: [[7_代码实现_Agent 对话编排]]
%%
Drawing
1 | N4IgLgngDgpiBcIYA8DGBDANgSwCYCd0B3EAGhADcZ8BnbAewDsEAmcm+gV31TkQAswYKDXgB6MSgw4CxAHSp6AWzJJMMJTEZgaCANqg8CEAGYAnKjMt0AMwBsqyLGNgUYVcgQAWL+QisADnIiPDB+BABWOyCQfhhsAHNBSIAGOV8QdEYE9QQU9jB8egBrGABhekx6fGMAYgBGFhMUrwB2VQAjdFRihKLORlwKqprEQqyaKHR8LXdyG2xMTABlSF |
%%
