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 負責把指標重新對齊。