run_turn:模型与工具怎样循环
你让 Codex“读代码、补测试、运行测试并修复”。为什么一次提问中,它能读文件、执行命令,再继续回答?这一站进入普通 Turn 内部的模型—工具循环。
本课精读 run_turn 的入口、模型输入准备与继续条件;完整函数还包含 hooks、插件准备、重试和压缩等支路,不把几个摘录冒充全部实现。 讲义已备好 ≠ 已掌握;本页不会改动你的通关状态。
本站必背 · 走路复习
第 5 站:一次工作,可以多次请求模型
先理解,再背这一个完整段落。日常复述约 1–2 分钟;点标题可遮住正文,按下面的顺序提示试着复述。
核心背诵段 · 点击展开或遮住
第五站位于 Core 层,run_turn 协调当前执行中的模型—工具循环,上游是 RegularTask。它先准备上下文,再从运行历史组织模型输入,交给采样流程;下游处理模型响应和工具调用,工具结果又成为后续模型请求的材料。模型还需要后续处理,或者队列仍有输入,都可能让循环继续;没有普通续跑理由时,还要经过停止检查。函数返回后,由外层处理整轮生命周期。记住:一次模型响应结束,不等于一个 Turn 结束;一次 Turn 可以包含多次模型请求和工具调用,流式输出片段也不是新的 Turn。这个函数负责协调,具体联网和工具动作由下游完成。
复述顺序:Core 协调者 → 历史组成输入 → 模型与工具配合 → 判断继续与停止 → 外层收尾。
背诵用于抓牢主线。理解自测:模型先要求读取文件,读完后再解释结果,为什么不必算成两个 Turn? 仍需通过源码阅读和练习验证掌握,不会因背诵自动标记通关。
核对依据:组织采样输入与继续条件 · 停止检查。
先听一遍,再对照源码
普通话讲解,保留关键代码语义、实际操作情境和 GEODYNA 对照。第 1 遍抓主线;第 2 遍对照代码;第 3 遍回答最后五个问题。
点击开始;页面不会自动播放,也不会自动标记课程通关。
点击任一章,从对应位置开始。
展开音频文字稿 · 听不清时对照看
声音中的术语,对应代码里的哪个词?
AI 合成语音;收听位置仅保存在当前浏览器,不跨设备同步。代码以固定快照为准。可下载后用手机播放器离线收听。
先定位:这一站到底在讲哪一层?
run_turn 位于 Core 层。上游是上一站的 RegularTask::run;它收到的已经是内部输入和运行上下文,不再解析 TUI 的发送按钮或 JSON-RPC 参数。
函数级职责:准备这轮需要的上下文,在循环中调用 run_sampling_request,并根据模型续跑要求、待处理输入、错误和停止钩子决定继续或返回。真正连接模型、消费流式响应和分派工具的代码,分别位于下游函数;不是 run_turn 一行代码全包办。
- 1RegularTask::run 交来输入
- 2run_turn 准备与记录上下文
- 3构建一次模型请求
- 4处理响应与工具执行
- 5将输出写入历史,判断是否继续
- 6返回执行包装器,由外层统一收尾
| 粒度 | 负责什么 | 不要误认为 |
|---|---|---|
| 一整个 Thread | 长期对话档案,可容纳多轮工作 | 不是一次模型调用 |
| 一个 Turn | 一次工作的生命周期,可经历多次模型请求 | 不是每个流式片段 |
| run_turn 函数 | 协调本次执行中的模型—工具循环 | 不直接负责最终通知界面 |
| run_sampling_request | 组织一次采样及其重试、工具配合 | 也不能把内部重试数当 Turn 数 |
先建立本体:循环的是什么?
这里的循环不是把你的问题原封不动重发。每一圈都可能拿到更新后的历史:最初有用户请求,后面增加模型提出的工具调用、工具运行结果、用户追加输入。模型读取这些新证据,再决定下一步。
例如“查找失败原因并补测试”:第一次模型响应提出读文件;系统读取文件,把结果交回;第二次模型响应提出修改;系统执行并回填;后续才有测试和最终说明。这些可以都属于同一个 Turn。
流式输出是一次响应逐段到达的传输方式。一个 delta 可能只是文本片段;一个模型响应可以带多个 Item;一个 Turn 可以包含多个模型响应。三者不能混数。
| 新词 | 是什么、为什么需要 |
|---|---|
| TurnInput | 进入 Core 这一轮的输入项;不是只装字符串 |
| ResponseItem | 准备给模型看的历史项目,例如消息、工具调用和结果 |
| SamplingRequestResult | 一次采样处理后的控制结果,包含是否还需继续和最后助手文本 |
| needs_follow_up | 是否还需继续工作的布尔值,不是新的 Turn ID |
源码入口:参数已经不是 App Server 的 params
1. 读函数签名
真实源码 · codex-rs/core/src/session/turn.rs:162–169
代码较长时可左右滑动;下方按语句和术语拆解。
pub(crate) async fn run_turn(
sess: Arc<Session>,
turn_context: Arc<TurnContext>,
input: Vec<TurnInput>,
mcp_startup_requirements: &mut McpStartupRequirements,
prewarmed_client_session: Option<ModelClientSession>,
cancellation_token: CancellationToken,
) -> CodexResult<Option<String>> {| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| pub(crate) async fn | 只在当前 crate 内公开;async 返回可等待的异步工作,不等于每次新建操作系统线程。 |
| sess: Arc<Session> | 共享 Core 运行会话;这里能访问历史、服务和输入队列。Arc 克隆是共享引用,不是复制整段对话。 |
| turn_context: Arc<TurnContext> | 当前 Turn 的上下文;同一轮循环使用其身份和设置边界。 |
| input: Vec<TurnInput> | 本次传进函数的输入列表。后续追加内容也可能来自 Session 队列,而非这个形参。 |
| &mut McpStartupRequirements | 可变借用启动需求集合,让函数补充本轮必须就绪的 MCP 服务/插件信息。 |
| Option<ModelClientSession> | 可能有、也可能没有可复用的模型客户端会话;不是网页登录 session。 |
| CancellationToken | 停止信号的协作机制,不是 API 密钥。 |
| CodexResult<Option<String>> | 外层 Result 区分返回/错误,内层 Option 表示是否有最后文本;不能单凭 Some 或 Ok 断言整个业务目标成功。 |
进入一圈:先组织输入,再调用模型
前面的准备过程会处理必要上下文、hooks 和输入记录。下面摘录的是每圈构造模型输入并调用采样函数的位置。不要以为 clone_history 就把磁盘上的全部聊天一字不漏塞进去;for_prompt 还会整理模型可接收的输入,第 9 站会拆开它。
2. 历史 → 本次模型输入
真实源码 · codex-rs/core/src/session/turn.rs:416–438
代码较长时可左右滑动;下方按语句和术语拆解。
// Construct the input that we will send to the model.
let sampling_request_input: Vec<ResponseItem> = async {
sess.clone_history()
.await
.for_prompt(&step_context.settings.model_info.input_modalities)
}
.instrument(trace_span!("run_turn.prepare_sampling_request_input"))
.await;
let responses_metadata = sess
.responses_metadata(turn_context.as_ref(), CodexResponsesRequestKind::Turn)
.await;
run_sampling_request(
Arc::clone(&sess),
Arc::clone(&step_context),
Arc::clone(&turn_context.extension_data),
Arc::clone(&turn_diff_tracker),
&mut client_session,
&responses_metadata,
sampling_request_input,
cancellation_token.child_token(),
)
.await| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| let sampling_request_input: Vec<ResponseItem> | 命名一个将交给模型请求的输入列表;它与入口的 Vec<TurnInput> 不是同一层的数据类型。 |
| sess.clone_history().await | 取得运行历史快照。await 等待所需异步操作完成。 |
| .for_prompt(&...input_modalities) | 按模型接受的模态整理历史;这一步在构建真正请求以前进行。 |
| .instrument(...).await | 给这段异步操作附上追踪范围后等待;instrument 是观测,不是一次额外模型调用。 |
| responses_metadata | 请求的辅助元数据,与用户输入正文不是一回事。 |
| run_sampling_request(...) | 把会话、步骤快照、共享差异记录器、模型连接、输入和取消信号交给下游。 |
| &mut client_session / child_token() | 前者允许复用并更新客户端会话;后者创建关联父级取消信号的子令牌。 |
具体输入,逐层拆开
仅用于数清层次的教学时间线,不是可直接发送的 API 消息。
Thread A
└─ Turn T1
├─ 模型请求 R1 → 读文件工具调用 C1
├─ C1 的结果进入历史
├─ 模型请求 R2 → 测试工具调用 C2
├─ C2 的结果进入历史
└─ 模型请求 R3 → 最终说明
(每个 R 里面还可能有很多文本 delta)这个例子是 1 个 Turn、3 次模型请求、2 次工具调用,不是 3 个 Turn。实际请求数与工具数由工作过程决定,不能预设固定比例。
什么时候继续,什么时候返回?
3. 两种继续理由合并成一个判断
真实源码 · codex-rs/core/src/session/turn.rs:443–471
代码较长时可左右滑动;下方按语句和术语拆解。
let SamplingRequestResult {
needs_follow_up: model_needs_follow_up,
last_agent_message: sampling_request_last_agent_message,
} = sampling_request_output;
if model_needs_follow_up {
sess.input_queue
.accept_mailbox_delivery_for_current_turn(
&sess.active_turn,
&turn_context.sub_id,
)
.await;
}
can_drain_pending_input = true;
// Process async hooks only after sampling and its tools have finished.
drain_async_hook_results(&sess, &turn_context, /*before_user_prompt*/ false).await;
let (has_pending_input, token_status) = async {
let has_pending_input =
sess.input_queue.has_pending_input(&sess.active_turn).await;
let token_status = super::context_window::context_window_token_status(
sess.as_ref(),
turn_context.as_ref(),
)
.await;
(has_pending_input, token_status)
}
.instrument(trace_span!("run_turn.collect_post_sampling_state"))
.await;
let needs_follow_up = model_needs_follow_up || has_pending_input;
let token_limit_reached = token_status.token_limit_reached;| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| let SamplingRequestResult { ... } | 解构返回结构体,把需要的字段取出来。 |
| needs_follow_up: model_needs_follow_up | 冒号右边是在此作用域使用的新变量名,不是在做真假判断。 |
| can_drain_pending_input = true | 允许后续循环从队列吸收追加输入;并非立即创造一个新 Turn。 |
| has_pending_input(...).await | 检查执行期间是否积累了尚未处理的输入。 |
| model_needs_follow_up || has_pending_input | 逻辑“或”:模型还需后续处理,或队列还有新输入,任一满足就有继续理由。 |
| token_limit_reached | 上下文额度相关判断,将影响是否先压缩再继续,不是新的用户发送事件。 |
4. 没有普通续跑理由,还要检查停止钩子
真实源码 · codex-rs/core/src/session/turn.rs:547–555
代码较长时可左右滑动;下方按语句和术语拆解。
if !needs_follow_up {
last_agent_message = sampling_request_last_agent_message;
let stop_outcome = run_turn_stop_hooks(
&sess,
&step_context,
stop_hook_active,
last_agent_message.clone(),
)
.await;| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| if !needs_follow_up | 感叹号取反:模型和输入队列都没要求继续时,进入收尾候选路径。 |
| last_agent_message = ... | 记录当前最后的助手消息,而不是立刻发最终通知。 |
| run_turn_stop_hooks(...).await | 让停止钩子参与决定。后续分支可能记录继续提示再 continue,也可能 break。 |
边界提醒:本文件 566–606 行继续处理 hooks;610–641 行处理取消与错误;646 行返回最后文本。因此“模型说完一句话,Turn 必定结束”不成立。
把同一个场景换一种条件
同一个 Turn,条件不同,下一步会不同。先判断会继续调用模型,还是进入收尾。
仅为本地教学演示,不调用模型或 GEODYNA,不执行任何真实操作。
先预测会走哪条分支,再点击按钮查看。
工具结果成为下一圈的新证据
- 模型提出工具调用,系统交给工具执行路径。
- 工具输出被记录;采样处理返回 needs_follow_up。
- 下一圈用更新后的历史继续请求模型。
这通常仍是同一 Turn,不是工具每执行一次就新增 Turn。
队列中的内容让当前工作继续
- 本次模型采样处理完成。
- has_pending_input 为真。
- needs_follow_up 为真;在允许的边界吸收追加输入。
排队、吸收与采样都有边界,不等于把文字瞬间塞进一个已经发送的模型请求。
成为收尾候选,不是跳过所有检查
- 模型没有后续要求,输入队列也空。
- 执行停止 hooks 等收尾检查。
- 无继续或阻止条件时 break,返回最后助手文本,再由外层统一完成生命周期。
run_turn 返回与最终 turn/completed 通知属于不同位置。
可能先压缩,再继续同一轮
- 仍有继续理由,且相关额度/新窗口条件满足。
- 进入自动压缩/新上下文窗口路径。
- 若压缩成功,继续执行;失败或取消则走相应终止路径。
上下文窗口变化不自动等于新 Turn,也不保证永远可以压缩成功。
最容易说错的边界
| 常见说法 | 准确表述 |
|---|---|
| 输出了 100 个片段,就是 100 个 Turn | 片段属于流式响应,不能拿片段数计算 Turn。 |
| 工具结果出来,这轮就结束了 | 工具结果经常是下一次模型请求的输入。 |
| run_turn 自己完成全部模型协议和工具实现 | 它是协调者;实际处理委托给采样、流事件和工具组件。 |
| 返回 Ok 就证明用户目标完成 | 还要结合终态、工具结果和业务验收,不同层的成功不能互相替代。 |
迁移到你的 GEODYNA 智能体
以下是设计练习,不代表并行产品线已经实现或通过验收;本次只制作课程,不修改 GEODAMNEW。
把请求换成“检查当前算例的边界设置,说明为什么不能计算”。候选流程是:读取工程状态 → 查询校验结果 → 根据证据解释缺项;确需修改时再进入明确授权的正式 Command API。
先让智能体正确地读取、解释,再逐步增加写操作。不要让模型在缺少工具证据时编造“已经计算成功”。
| 你要设计的点 | 可验证的证据 |
|---|---|
| 每步输入与结果 | 保留工具调用 ID、参数、实际结果和归属 Turn,能回放事实链。 |
| 继续与停止规则 | 工具失败、用户取消、预算不足时有明确分支,不靠无限重试。 |
| 产品指标 | 分别记录模型请求次数、工具成功率、总耗时和任务验收通过率。 |
产品经理练习:用 6 行写出上述只读检查任务的一次完整轨迹,并标出哪些是模型判断、哪些是软件事实。
先答小测,再看解析
每题即时反馈,可反复尝试;答对这些题也不会替代你的源码复述。
1. 一个 Turn 内出现三次模型请求,应算几个 Turn?
2. model_needs_follow_up 为假、has_pending_input 为真,合并结果是什么?
3. sampling_request_input 的元素类型是什么?
4. 没有普通续跑理由时,为何还调用 stop hooks?
5. GEODYNA 工具报告错误,模型却说已完成,你应以什么验收?
最后一句话交作业
请复述:run_turn 位于哪一层?每一圈给模型的输入从哪里来?needs_follow_up 合并哪两种理由?为什么模型响应结束还不等于 Turn 结束?
展开参考答案(先自己说一遍)
run_turn 位于 Core,协调当前执行中的模型—工具循环。它从运行历史组织模型输入,经 run_sampling_request 处理一次采样及工具配合;模型需要后续处理或队列还有输入,都可能让工作继续。没有普通续跑理由时仍要经过停止检查,返回后由外层结束生命周期。
下一轮再回来时:重新追同一个请求中 TurnInput → ResponseItem → Prompt → 工具结果的实际数据变化;第四轮再深入重试和复杂停止条件。