turn_context 与提示组装

源码版本v2026.7.20

职责

在每一轮 API 调用前,把「历史消息 + 本轮用户输入 + 网关侧附加上下文 + 压缩标记」装配成发给 provider 的 api_messages。TurnContext 是这轮产物的容器,build_turn_context 是装配入口。它还负责把网关收集的笔记(notes)注入到多模态内容里。

关键文件

• class TurnContext:242-268 — 本轮上下文数据类
• def build_turn_context:268-400 — 装配入口
• compose_user_api_content:44-79 — 用户消息内容组装
• substitute_api_content:79-101 — 占位符替换
• consume_gateway_turn_context_notes:124-164 — 消费网关侧附加 notes 并注入多模态内容
• reanchor_current_turn_user_idx:164-210 — 重定位本轮用户消息索引(压缩后修正)
• 压缩进度估计:190-242 — _compression_made_progress / _should_run_preflight_estimate
• prompt_builder — 系统提示组装(本页引用)

数据流

1. 主循环每轮调用 build_turn_context:268,得到一个 TurnContext。
2. compose_user_api_content(agent/turn_context.py:44) 把用户原始输入拼成 API 内容。
3. 若网关侧累积了 notes(来自附件、上下文提示),consume_gateway_turn_context_notes(agent/turn_context.py:124)取出并经 append_notes_to_multimodal_content 注入。
4. substitute_api_content(agent/turn_context.py:79)替换占位符;drop_stale_api_content 清理过期内容。
5. 若上一轮发生过压缩,reanchor_current_turn_user_idx(agent/turn_context.py:164)修正本轮用户消息在历史中的位置。
6. 装配好的 api_messages 进入 API 调用重试子循环:1227。

小结

turn_context 是「每轮的快照工厂」:把动态上下文固化为一个可发送的结构。它和上下文压缩协同——压缩改写历史后,turn_context 负责把指针重新对齐。