第一轮 · 第 4 站 · 所在层:CORE · 普通 TURN 的执行包装器

读懂 RegularTask::run

上一站已经决定“启动一个新 Turn”。这一站研究:新 Turn 被交给后台以后,谁宣布它开始、谁准备模型连接、谁把工作交给真正的 Agentic Loop,以及谁负责最后收尾。

本次只试改第 4 站:每段先说明“做什么、接到什么、怎样处理、交给谁”,再把逐句解释直接放进代码注释。绿色 // 教学: 与仓库原有注释明确区分;无新增注释的原始节选可以展开核对。

本站必背:走路时复述这一段 · 从第一段看新版 · 直接看 run_turn(...).await? 的解释。音频、小测与学习进度不变;其他站点等你确认形式后再调整。

一句话职责RegularTask::run 包装一次普通 Turn 的执行流程。
它真正调用谁run_turn;真正的模型—工具循环在下一站。
它不负责什么不创建后台线程,也不直接发最终 TurnComplete。
本站必背 · 走路复习

第四站:背住执行包装的核心思想

先理解,再背这一个完整段落。日常复述约 1–2 分钟;点标题可遮住正文,按下面的顺序提示试着复述。

核心背诵段 · 点击展开或遮住

第四站位于 Core 层,RegularTask::run 是普通 Turn 的执行包装器。它先发 TurnStarted,再处理连接预热,随后调用并等待 run_turn;预热不可用仍可继续,预热时收到取消则提前返回。真正的模型—工具循环在 run_turn 内部。调用出错就向上传递;正常返回后,只有没有终止错误、仍有待处理输入时才再次进入,继续同一个 Turn,而不是新开一轮。最后把结果或错误交回外层;外层负责收尾,并区分完成、失败或取消。记住:后台启动在外层,模型工具循环在里面,这一站负责包装执行流程。

复述顺序:所在层与职责 → 开始与预热 → 调用与等待 → 同轮重入 → 外层收尾。

背诵用于抓牢主线;能用自己的话解释“为什么 run_turn 返回,不一定代表这个 Turn 已经结束”,才算理解了本段。仍需通过源码阅读和小测验证掌握,不会因背诵自动标记通关。

核对依据:本课执行流程 · 外层启动与接收结果 · 统一收尾

本课也可以听 · AI 合成语音

把今天这一站,装进口袋

普通话讲解版:先定位层次,再拆解参数与语法,最后串起执行流程、两个循环和 GEODYNA 的应用。适合先听一遍建立全貌,再回到正文对照代码。

全长 20:45 · 8 章MP3 · 9.5 MB普通话女声 · 稍慢语速
下载 MP3

点击播放器开始。页面不会自动播放;也不会把收听自动计为课程通关。

按章节复习:点击下面任一章,即可从对应位置开始。

    展开音频文字稿 · 听不清时对照看
    声音中的术语,对应代码里的哪个词?

    AI 合成语音,根据本页固定源码快照制作,不是逐字符朗读代码。收听位置只保存在当前浏览器,不跨设备同步;下载后可用手机播放器离线复习。

    第一个定位:它在哪一层?

    RegularTask::run 位于 Codex Core 层。它已经越过 TUI 和 App Server,不再处理按钮、JSON-RPC 或 TurnStartParams;它接到的是 Core 内部的 Session、TurnContext 和 TurnInput。

    把它想成“演出执行经理”:调度台已决定开场,它先广播“本场开始”,检查能否复用已预热的模型连接,然后把舞台交给真正表演的 run_turn。表演结束后,最终结算由更外层的 on_task_finished 做。

    start_or_steer决定新开 Turn
    spawn_task / start_task安装并启动后台任务
    RegularTask::run本课:执行包装
    on_task_finished统一收尾
    Core Event → App Server通知界面

    源码入口:上一站创建 RegularTask · spawn_task / start_task · 本课完整函数

    先拆掉一个最容易混淆的词:Task

    你在 Codex 客户端看到的“任务”,日常上可以近似理解为一段可持续追加的对话,也就是 Thread。可源码里的 SessionTask 是另一回事:它是驱动某个 Turn 执行的内部工作对象。

    名字它是什么本课怎么理解
    界面里的 Task用户可打开、继续和回看的任务/对话大体对应 Thread,不是这里的 Rust 类型
    SessionTaskCore 内部规定的一份“执行工作”接口不同工作都要会报告类型、运行和响应取消
    RegularTaskSessionTask 的一种实现专门执行普通对话 Turn;另有 Review、Compact 等类型
    RunningTask正在运行时保存的任务状态包含取消令牌、后台句柄、TurnContext 等

    一句话:界面 Task 是用户管理的长期任务;源码 RegularTask 是 Core 为一次普通 Turn 采用的执行策略。

    源码依据:SessionTask 接口说明 · ActiveTurn / TaskKind / RunningTask

    责任边界:五个位置不要揉成一个函数

    位置真正负责不负责
    start_or_steer判断新开、追加或拒绝;新开时创建 RegularTask不跑模型
    Session::start_task建立 CancellationToken、保存 ActiveTurn、用 tokio::spawn 启动后台 Future不实现普通 Turn 的具体业务
    RegularTask::run发 TurnStarted、处理预热、调用 run_turn、处理重新进入和返回不直接执行模型—工具循环
    run_turn构造上下文,采样模型,执行工具,把工具结果再次交给模型本课只看到入口,下站精读
    on_task_finished解释运行结果、清理 ActiveTurn、发 TurnComplete 或 TurnAborted不重新表演模型循环

    带着一个真实例子走进去

    你输入:“检查登录模块并补测试”。上一站已经生成 Turn ID,并把输入与 RegularTask::new() 交给 Session。本函数收到的不是按钮点击,而是 self 加四个 Core 运行参数:

    self

    被运行的 RegularTask 本身;它没有字段,只用类型表达“执行普通 Turn 这套策略”。

    sess

    整个 Thread 的运行环境:历史、事件发送器、输入队列、服务、活动 Turn 等。

    ctx

    只属于本次 Turn 的上下文:Turn ID、模型设置、模式、时间、终止错误等。

    input

    本次明确提交的 Core 输入列表,例如这一段文字,也可能还有图片或其他项。

    cancellation_token

    合作式取消信号。用户中断时它会被标记,正在运行的步骤应尽快收尾退出。

    第一段源码:定义普通 Turn 的执行对象

    这段代码用来做什么?

    给 Core 提供一种代表“普通对话 Turn 执行方式”的对象,并提供创建它的方法。作用是让调度代码能选择这套执行方式,不是现在就开始调用模型。

    接到什么
    上游已经决定启动普通 Turn,需要调用 RegularTask::new() 得到一个执行对象;new() 在这里没有额外参数。
    具体怎样处理
    先声明没有字段的 RegularTask 类型,再定义 new() 返回一个该类型的值;Session 和本轮上下文将由调用方在运行时传入。
    产生什么/交给谁
    返回 RegularTask 实例,供 Session 的任务启动路径持有和运行。只创建这个对象不会新建聊天 Thread,也不会自动开始模型工作。

    Core 层 · 固定快照原文:regular.rs 第 22–29 行。下方为连续节选;未展示的函数体仍在后续片段或完整源码中。

    先读上面的作用,再沿代码往下看。绿色 // 教学: 是新增讲解,不是仓库原有注释;较长代码自动折行。

    // 教学:#[derive(Default)]:请编译器生成默认构造能力;这个无字段类型的默认值就是 RegularTask。
    #[derive(Default)]
    // 教学:pub(crate) 表示只在当前 Core crate 内可见。struct RegularTask; 是无字段的单元结构体:它代表执行方式,不用自己存储聊天历史。
    pub(crate) struct RegularTask;
    
    // 教学:impl RegularTask:下面开始给这个类型定义方法;这里不是在执行一次 Turn。
    impl RegularTask {
    // 教学:new 是构造方法名;-> Self 表示返回当前类型的实例,这里的 Self 就是 RegularTask。
        pub(crate) fn new() -> Self {
    // 教学:Self 这一行创建并作为返回值交出该实例;末尾没有分号,表示这是函数最后的返回表达式。
            Self
        }
    }
    展开原始源码(不含新增教学注释)
    #[derive(Default)]
    pub(crate) struct RegularTask;
    
    impl RegularTask {
        pub(crate) fn new() -> Self {
            Self
        }
    }
    可选复习:这一段的术语速查
    struct RegularTask;
    这是“单元结构体”:没有字段。它不用自己保存状态,只代表“采用普通 Turn 这套做法”。
    pub(crate)
    整个 core crate 内可见,crate 外不能直接使用。它是 Core 内部实现细节。
    #[derive(Default)]
    让编译器自动生成默认构造能力;这个无字段类型的默认值就是它自己。
    new() -> Self
    new 返回当前类型的一个实例。这里的 Self 就是 RegularTask。

    对应源码:regular.rs 第 22–29 行

    第二段源码:接入统一任务执行接口

    这段代码用来做什么?

    让 Session 能通过统一的 SessionTask 接口识别、追踪和运行 RegularTask。这样普通对话、审查、压缩等任务就能复用外层启动与收尾机制。

    接到什么
    运行入口接收当前任务对象、共享 Session、本轮 TurnContext、显式输入列表和取消信号;它们都是 Core 内部数据,不是按钮或 JSON-RPC 参数。
    具体怎样处理
    实现 kind() 报告任务种类,实现 span_name() 提供追踪名称,并声明异步 run 的参数与结果类型。这里仅展示 run 的签名,实际执行步骤在后面三段。
    产生什么/交给谁
    上游据此获得一套可统一调用的执行接口。调用异步 run 得到 Future;工作推进完成后才产出 SessionTaskResult,最后仍由外层统一收尾。

    Core 层 · 固定快照原文:regular.rs 第 31–46 行。下方为连续节选;未展示的函数体仍在后续片段或完整源码中。

    先读上面的作用,再沿代码往下看。绿色 // 教学: 是新增讲解,不是仓库原有注释;较长代码自动折行。

    // 教学:impl SessionTask for RegularTask:为 RegularTask 实现 SessionTask 规定的能力。接口是共同约定,实现是这个类型的具体做法。
    impl SessionTask for RegularTask {
    // 教学:fn kind(&self):借用当前对象,查询它是什么任务;-> TaskKind 是结果类型。
        fn kind(&self) -> TaskKind {
    // 教学:返回枚举值 TaskKind::Regular,告诉上游“这是普通 Turn 的执行任务”。
            TaskKind::Regular
        }
    
    // 教学:span_name() 提供追踪名称;&'static str 是可长期有效的字符串引用,下面返回的是固定字符串。
        fn span_name(&self) -> &'static str {
            "session_task.turn"
        }
    
    // 教学:async fn run:声明异步入口。调用得到 Future(可被推进的工作对象),不是最终回答;等待条件未就绪时可以让出执行机会,并非自动创建新线程。
        async fn run(
    // 教学:self: Arc<Self>:以共享所有权持有正在运行的 RegularTask。Arc 解决共享所有权,不是把对象全部复制一份。
            self: Arc<Self>,
    // 教学:sess: Arc<Session>:共享整段任务对话的运行环境,可访问历史、队列和事件服务。
            sess: Arc<Session>,
    // 教学:ctx: Arc<TurnContext>:共享本轮的身份与设置,如 Turn ID、模型模式、计时和终止错误;不等于整个 Session。
            ctx: Arc<TurnContext>,
    // 教学:input: Vec<TurnInput>:本次传入的 Core 输入列表,可能包含文字或图片等项目,不是只能装一个字符串。
            input: Vec<TurnInput>,
    // 教学:cancellation_token:取消信号;下游要在等待或安全检查点配合处理,不是强行杀死进程的按钮。
            cancellation_token: CancellationToken,
    // 教学:SessionTaskResult 是 CodexResult<Option<String>> 的别名:先区分错误/正常返回,再区分有/无最后助手文本。花括号打开 run 函数体,下面接第三段。
        ) -> SessionTaskResult {
    展开原始源码(不含新增教学注释)
    impl SessionTask for RegularTask {
        fn kind(&self) -> TaskKind {
            TaskKind::Regular
        }
    
        fn span_name(&self) -> &'static str {
            "session_task.turn"
        }
    
        async fn run(
            self: Arc<Self>,
            sess: Arc<Session>,
            ctx: Arc<TurnContext>,
            input: Vec<TurnInput>,
            cancellation_token: CancellationToken,
        ) -> SessionTaskResult {
    可选复习:接口与参数速查
    词 / 参数字面意义为什么这样设计
    impl SessionTask for RegularTask给 RegularTask 实现 SessionTask 规定的能力Session 可以用统一方式运行普通、审查、压缩等不同任务
    kind()返回 TaskKind::Regular系统能识别“这是普通 Turn”,用于状态、遥测和界面语义
    span_name()返回追踪区段名可观测系统能测量并定位这一段后台执行
    async fn调用返回一个 Future,完成后才产出声明的结果类型在异步等待条件未就绪时可以挂起当前工作,让运行时调度其他就绪工作;不是自动创建新线程
    Arc<T>原子引用计数的共享所有权多个异步位置可安全持有同一个 Session、Context 或 Task
    Vec<TurnInput>可变长度的 TurnInput 列表一次提交可以包含文字、图片等多个输入项
    CancellationToken可克隆、可派生的取消信号取消是合作式的:父令牌取消,子工作也能感知并退出
    SessionTaskResultCodexResult<Option<String>>外层要同时区分错误,以及“有/没有最终助手文本”

    对应源码:RegularTask 的 trait 实现与参数 · SessionTaskResult 类型别名

    Session 和 TurnContext 为什么要分开?

    长生命周期

    Session

    服务于整个 Thread:历史、队列、模型客户端、MCP、事件通道、当前活动 Turn。昨天打开同一 Thread 继续问,Session 仍需恢复/承载这一整体环境。

    单 Turn 生命周期

    TurnContext

    只描述这一轮:sub_id(Turn ID)、trace ID、模型窗口、协作模式、计时状态、终止错误等。下一次提问会有新的 TurnContext。

    像“项目档案”和“本次工单”:前者跨多轮保存环境,后者冻结本次执行所需的身份与配置。

    源码依据:Session · TurnContext

    第三段源码:先发 TurnStarted,再处理“预热”

    这段代码用来做什么?

    在真正进入 run_turn 前,先让下游知道“这一轮开始了”,再取得启动期间预热的模型连接。这样开始反馈不必等预热结果出来才发送。

    接到什么
    已经可用的 sess、ctx 和取消令牌:ctx 提供本轮身份、时间、模型窗口与协作模式,sess 提供事件发送和预热服务。
    具体怎样处理
    构造并发送 TurnStarted,重置推理 token 计量标记,然后等待预热服务给出结果;追踪区段记录这段准备工作的耗时。
    产生什么/交给谁
    下游事件链收到开始事件;局部变量得到预热结果枚举,下一段再决定取消、无连接继续或复用连接。此处既没有完成模型回答,也没有发最终完成通知。

    Core 层 · 固定快照原文:regular.rs 第 47–64 行。下方为连续节选;未展示的函数体仍在后续片段或完整源码中。

    先读上面的作用,再沿代码往下看。绿色 // 教学: 是新增讲解,不是仓库原有注释;较长代码自动折行。

    // 教学:trace_span!("run_turn"):创建一个名为 run_turn 的日志追踪区段,稍后包住下游调用;不是在这里调用 run_turn 函数。
            let run_turn_span = trace_span!("run_turn");
            // Regular turns emit `TurnStarted` inline so first-turn lifecycle does
            // not wait on startup prewarm resolution.
    // 教学:async { ... } 把这段准备流程包装成 Future。末尾 .await 才推进并等待它;prewarmed_client_session 最后保存的是准备结果,而不是这个 Future。
            let prewarmed_client_session = async {
    // 教学:构造 EventMsg::TurnStarted:内部事件类型包着 TurnStartedEvent 数据。这里先造事件,实际发送在第 58 行。
                let event = EventMsg::TurnStarted(TurnStartedEvent {
    // 教学:turn_id 从 ctx.sub_id 克隆而来,用于识别本轮;trace_id 用于追踪执行,不是聊天 Thread ID。
                    turn_id: ctx.sub_id.clone(),
                    trace_id: ctx.trace_id.clone(),
    // 教学:取得本轮开始时间并异步等待;后续两个字段带上模型上下文窗口与协作模式,帮助下游描述这轮运行。
                    started_at: ctx.turn_timing_state.started_at_unix_secs().await,
                    model_context_window: ctx.model_context_window(),
                    collaboration_mode_kind: ctx.mode(),
                });
    // 教学:send_event(...).await:通过 Session 发送开始事件。ctx.as_ref() 从 Arc 借用内部上下文;发送事件不等于模型执行完成。
                sess.send_event(ctx.as_ref(), event).await;
    // 教学:把 server_reasoning_included 计量标记重置为 false,避免沿用上一轮统计状态;不是关闭模型的推理能力。
                sess.set_server_reasoning_included(/*included*/ false).await;
    // 教学:消费启动预热结果,传入取消令牌,让等待能响应取消;可能得到 Ready、Unavailable 或 Cancelled,下一段逐一处理。
                sess.consume_startup_prewarm_for_regular_turn(&cancellation_token)
                    .await
            }
    // 教学:.instrument(...) 给整个准备 Future 附上追踪名称;.await 等到准备结果。若暂时无法继续,当前流程可挂起,其他就绪工作仍有机会被调度。
            .instrument(trace_span!("regular_task.prepare_run_turn"))
            .await;
    展开原始源码(不含新增教学注释)
            let run_turn_span = trace_span!("run_turn");
            // Regular turns emit `TurnStarted` inline so first-turn lifecycle does
            // not wait on startup prewarm resolution.
            let prewarmed_client_session = async {
                let event = EventMsg::TurnStarted(TurnStartedEvent {
                    turn_id: ctx.sub_id.clone(),
                    trace_id: ctx.trace_id.clone(),
                    started_at: ctx.turn_timing_state.started_at_unix_secs().await,
                    model_context_window: ctx.model_context_window(),
                    collaboration_mode_kind: ctx.mode(),
                });
                sess.send_event(ctx.as_ref(), event).await;
                sess.set_server_reasoning_included(/*included*/ false).await;
                sess.consume_startup_prewarm_for_regular_turn(&cancellation_token)
                    .await
            }
            .instrument(trace_span!("regular_task.prepare_run_turn"))
            .await;
    1. trace_span!

    创建可观测区段。它不是业务返回值,而是帮助开发者看到耗时、错误发生在哪一段。

    2. TurnStarted

    Core 内部生命周期事件,告诉下游“本 Turn 已开始”。App Server 可把协议事件转换成客户端通知。

    3. startup prewarm

    启动期间提前准备模型客户端连接。若已经准备好就复用,减少首轮等待;没有也能正常创建新连接。

    为什么先发开始事件,再等预热?源码注释写得很直接:普通 Turn 不应因为等待启动预热结果而延迟首轮生命周期。也就是说,用户看到“已经开始”的反馈优先于性能优化是否完成。

    set_server_reasoning_included(false) 是什么?它重置本 Turn 的推理 token 计数标记,避免沿用上一轮“服务器是否已统计历史推理 token”的状态。这是计量状态,不是切换模型推理能力。

    预热结果有三条路

    这段代码用来做什么?

    把“预热阶段发生了什么”转换为清楚的执行决定:收到取消就提前返回;没连接也能继续;有连接就复用。预热是优化,缺少预热连接不应该自动变成任务失败。

    接到什么
    上一段返回的 SessionStartupPrewarmResolution 枚举,以及记录输入所需的 sess、ctx、input。
    具体怎样处理
    match 只进入一个匹配分支。Cancelled 先调用输入记录与 hooks 辅助流程再返回;Unavailable 变为 None;Ready 取出连接并包装为 Some。
    产生什么/交给谁
    取消分支直接把 Ok(None) 交还外层;另外两种情况得到 Option<ModelClientSession>,随后作为可选连接传给 run_turn。None 在不同位置的含义要分清。

    Core 层 · 固定快照原文:regular.rs 第 65–74 行。下方为连续节选;未展示的函数体仍在后续片段或完整源码中。

    先读上面的作用,再沿代码往下看。绿色 // 教学: 是新增讲解,不是仓库原有注释;较长代码自动折行。

    // 教学:用 match 拆开预热结果,并用同名 let 重新绑定变量:右边是三种预热状态,左边将变成可选连接。
            let prewarmed_client_session = match prewarmed_client_session {
    // 教学:Cancelled:等待预热期间收到了取消。进入这一支后不会再走下面的 run_turn 调用。
                SessionStartupPrewarmResolution::Cancelled => {
    // 教学:调用 run_hooks_and_record_inputs,按此取消路径完成相应输入记录与 hooks 工作;PersistContext::Standard 指明记录上下文。此调用本身不是启动模型循环。
                    run_hooks_and_record_inputs(&sess, &ctx, &input, PersistContext::Standard).await;
    // 教学:return Ok(None):提前离开 RegularTask::run。Ok 是正常返回,None 是没有最后助手文本,不代表“用户目标成功完成”。终态由外层结合取消状态处理。
                    return Ok(None);
                }
    // 教学:Unavailable { .. }:没有可用预热连接,忽略该变体的其他字段,返回 None 表示“不带预热连接继续”,不是整个函数立即返回。
                SessionStartupPrewarmResolution::Unavailable { .. } => None,
    // 教学:Ready(...):拿到已有的预热连接。下一行用 * 取出包装内的连接,再用 Some(...) 表示“有连接可用”。
                SessionStartupPrewarmResolution::Ready(prewarmed_client_session) => {
                    Some(*prewarmed_client_session)
                }
    // 教学:match 表达式结束。除去已经 return 的取消分支,后续都可以继续进入第四段。
            };
    展开原始源码(不含新增教学注释)
            let prewarmed_client_session = match prewarmed_client_session {
                SessionStartupPrewarmResolution::Cancelled => {
                    run_hooks_and_record_inputs(&sess, &ctx, &input, PersistContext::Standard).await;
                    return Ok(None);
                }
                SessionStartupPrewarmResolution::Unavailable { .. } => None,
                SessionStartupPrewarmResolution::Ready(prewarmed_client_session) => {
                    Some(*prewarmed_client_session)
                }
            };
    结果意思接下来
    Cancelled等待期间收到取消仍记录输入与 hooks,然后 Ok(None) 提前返回
    Unavailable没有安排好或拿不到预热连接变成 None,run_turn 自己新建连接;不是失败
    Ready预热连接可用用 Some(client_session) 交给第一次 run_turn

    对应源码:事件与预热分支 · 预热结果枚举 · 消费预热连接

    第四段源码:把工作交给 run_turn

    这段代码用来做什么?

    把实际智能体工作交给 run_turn,并在它返回时检查是否还有结束边界上到达的输入。这是外层执行包装的重入机制,不是里面那个模型—工具循环。

    接到什么
    首次显式 input、可选预热连接、共享 Session、本轮上下文、MCP 启动需求集合与取消令牌。
    具体怎样处理
    调用并等待 run_turn;若出错则传播,若已记录终止错误或没有待处理输入则返回。只有还有待处理输入等条件允许时才再进入一次,并清空显式首次输入,避免重复提交。
    产生什么/交给谁
    把错误或最后助手文本交给外层任务启动包装,再由 on_task_finished 统一收尾并产生终态事件;追加内容仍由 Session 输入队列承载。

    Core 层 · 固定快照原文:regular.rs 第 75–98 行。下方为连续节选;未展示的函数体仍在后续片段或完整源码中。

    先读上面的作用,再沿代码往下看。绿色 // 教学: 是新增讲解,不是仓库原有注释;较长代码自动折行。

    // 教学:用 next_input 保存首次显式输入;mut 允许后面重新赋值。不是把文本转成模型回答。
            let mut next_input = input;
    // 教学:让可选预热连接成为可变绑定,便于 take() 取走后留下 None,避免重复交付同一条连接。
            let mut prewarmed_client_session = prewarmed_client_session;
    // 教学:建立 MCP 服务/插件的启动需求集合。它放在 loop 外,重新进入 run_turn 时还能继续使用。
            let mut mcp_startup_requirements = McpStartupRequirements::default();
    // 教学:外层 loop:一次 run_turn 返回后,仍可能为处理追加输入而再次进入;不要把这里的循环次数当作新增 Turn 数。
            loop {
    // 教学:run_turn(...) 是异步函数调用,得到 Future。当前这整条语句直到第 88 行 .await? 成功完成,才把返回值赋给 last_agent_message;不会立即拿到回答。
                let last_agent_message = run_turn(
    // 教学:Arc::clone(&sess) 和下一行 Arc::clone(&ctx) 克隆共享指针,指向原有 Session 与本轮上下文,不是复制整段聊天。
                    Arc::clone(&sess),
                    Arc::clone(&ctx),
    // 教学:把本次显式输入交给 run_turn。第一次是用户输入;若稍后重入,这个参数会是空列表,但队列里仍可能有追加内容。
                    next_input,
    // 教学:&mut:可变借用启动需求集合,允许 run_turn 更新它,不把集合所有权整个移走。
                    &mut mcp_startup_requirements,
    // 教学:take():若是 Some(连接),取出并把原变量变成 None;若已是 None,就仍传 None。预热连接最多交给第一次调用。
                    prewarmed_client_session.take(),
    // 教学:child_token():创建关联父取消信号的子令牌;父任务取消时,run_turn 可以收到相应信号。
                    cancellation_token.child_token(),
                )
    // 教学:instrument 为这项异步工作附加日志追踪区段,不是再次调用模型。
                .instrument(run_turn_span.clone())
    // 教学:.await 推进并等待 run_turn 的工作结果;? 在 Err 时把错误向上传播,在 Ok 时取出内部值。当前函数下一句仍要等这一句完成,不会跳着执行。
                .await?;
                // Terminal errors are already reported. Let task completion preserve pending
                // input instead of restarting the failed turn for that same input.
    // 教学:先异步取得 terminal_error 的锁,再用 is_some() 看是否已有终止性错误。有就返回,让外层处理;不能拿同一批追加输入反复重启失败工作。
                if ctx.terminal_error.lock().await.is_some() {
                    return Ok(last_agent_message);
                }
    // 教学:has_pending_input 查看活动 Turn 是否还有待处理输入;! 是取反。没有新输入就返回最后助手文本,仍不在这里直接发 TurnComplete。
                if !sess.input_queue.has_pending_input(&sess.active_turn).await {
                    return Ok(last_agent_message);
                }
    // 教学:走到这里说明还需要重入。清空的是下一次显式传参,不是清空 Session 队列;追加内容留在队列里,由下一次 run_turn 吸收。
                next_input = Vec::new();
            }
    展开原始源码(不含新增教学注释)
            let mut next_input = input;
            let mut prewarmed_client_session = prewarmed_client_session;
            let mut mcp_startup_requirements = McpStartupRequirements::default();
            loop {
                let last_agent_message = run_turn(
                    Arc::clone(&sess),
                    Arc::clone(&ctx),
                    next_input,
                    &mut mcp_startup_requirements,
                    prewarmed_client_session.take(),
                    cancellation_token.child_token(),
                )
                .instrument(run_turn_span.clone())
                .await?;
                // Terminal errors are already reported. Let task completion preserve pending
                // input instead of restarting the failed turn for that same input.
                if ctx.terminal_error.lock().await.is_some() {
                    return Ok(last_agent_message);
                }
                if !sess.input_queue.has_pending_input(&sess.active_turn).await {
                    return Ok(last_agent_message);
                }
                next_input = Vec::new();
            }
    可选复习:外层循环术语速查
    let mut next_input = input:把首次输入放进一个之后可以改写的变量。mut 表示这个变量绑定可以被修改。
    McpStartupRequirements::default():建立本 Turn 需要启动的 MCP Server / Plugin 需求集合,并让后续重新进入 run_turn 时继续保留。
    Arc::clone(&sess):克隆的是共享指针,不是复制整个 Session;引用计数加一。
    prewarmed_client_session.take():第一次把 Some(连接) 取走,原变量留下 None;因此预热连接最多交付一次。
    child_token():为这次 run_turn 建子取消令牌;父任务被取消时,子循环也能收到。
    .await?:等待 run_turn 完成;如果返回错误,? 立刻把错误向外传播。
    terminal_error:若已发生终止性错误,错误事件已经报告,直接返回,不能拿同一批 pending input 重启失败 Turn。
    has_pending_input:如果没有新的追加输入,就正常返回最后助手文本;还有输入则再进入一次 run_turn。
    next_input = Vec::new():不是丢掉追加内容。追加内容仍在 Session 的 pending queue;空的“显式输入”让下一次 run_turn 从队列吸收它。

    对应源码:RegularTask 外层循环 · pending input 检查 · run_turn 定义

    关键区别:这里出现了两个“循环”

    本课:RegularTask 外层循环

    一次 run_turn 返回以后,检查收尾边界上是否又有 pending input。若有,重新进入 run_turn。

    目的:兜住追加输入与结束时刻相撞的边界。

    →

    下站:run_turn 内部 Agentic Loop

    模型提出工具调用 → Core 执行工具 → 工具结果送回模型 → 模型继续推理,直到只返回最终助手消息或被停止。

    目的:真正完成智能体任务。

    不要说:“RegularTask 的这个 loop 就是模型工具循环。”
    应该说:“RegularTask 有一个外层重入循环;它每次调用的 run_turn 内部才包含模型工具循环。”

    为什么 run 返回了,还不等于 Turn 已完成通知?

    RegularTask::run 返回→ start_task 中的后台 Future 接到结果→ on_task_finished→ TurnComplete / TurnAborted

    原因是 Codex 不只运行 RegularTask。把统一清理、计时、状态迁移和终态事件放在 Session::on_task_finished,所有 SessionTask 都能走同一套生命周期收尾。

    四句话锁边界:
    谁创建它? start_or_steer。
    谁把它放后台? Session::start_task。
    谁执行 Agentic Loop? run_turn。
    谁发最终终态? on_task_finished。

    源码依据:start_task 启动后台工作并接收结果 · on_task_finished 统一收尾

    运行路径模拟器

    选择一个运行条件,看 RegularTask::run 怎样走。这里显示的是职责级简化路径,不是假装执行真实模型。

    请选择一个场景。

    映射到你的 GEODYNA 智能体

    当前 GEODYNA 还没有一个可以直接等同于 RegularTask 的单一类。相近职责分散在 LLMCommandBar、Smart Command Application 和正式 ProjectCommand 执行边界中:界面管 loading / busy,应用层准备上下文与计划,执行层校验并以事务方式落地命令。

    将来做独立的 GEODYNA Agent 时,可以借鉴这一层,设计一个 AgentTaskRunner:

    Codex 机制GEODYNA 智能体候选设计产品价值
    TurnStartedEngineeringTaskStarted(taskId)用户立即知道任务已接管,而不是界面“像卡住”
    TurnContext项目版本、选择对象、单位制、权限、目标和本次模型配置结果可重放、可审计,避免环境漂移
    CancellationToken停止规划、停止等待或在安全点取消求解耗时工程任务必须可控,而非只能强退软件
    run_turn规划 → 调用正式 Command API → 读取结果 → 再规划模型不能绕过已有业务规则直接改项目
    on_task_finished统一落审计、耗时、状态、失败原因和可撤销点为产品运营、Badcase 与安全治理提供证据

    只读说明:本课程仅阅读 D:\GEODAMNEW 的现有实现,不会修改其中任何代码;未来 Agent 在独立项目中实现。

    作为 AI 原生产品经理,你应追哪些指标?

    接管反馈延迟

    用户点击发送到收到 Started 事件的时间。它与“整个任务完成耗时”不是一个指标。

    取消生效延迟

    用户点击停止后,模型、工具或求解在多久内到达安全停止点。

    终态完整率

    每个 Started 是否最终都有 Completed、Failed 或 Interrupted,并带可理解原因。

    通关小测

    1. RegularTask::run 在哪一层?

    2. 谁真正调用 tokio::spawn 把任务放到后台?

    3. 真正的模型—工具 Agentic Loop 在哪里?

    4. prewarmed_client_session.take() 的效果是什么?

    5. 有 pending input 时,为何下一轮把 next_input 设为空列表?

    6. RegularTask::run 返回后,谁统一发终态事件?

    7. 预热结果是 Unavailable,是否代表 Turn 失败?

    最后一句话交作业

    请先不用抄答案,按你的理解补全:

    RegularTask::run 位于 ______ 层;它是 ______ Turn 的内部执行包装器。它先发送 ______,再准备或复用 ______,随后调用 ______;若收尾边界仍有 ______ 且没有终止错误,就再次进入。真正的模型—工具循环在 ______;最终终态由 ______ 统一发送。

    展开本课标准答案(交作业后再看)

    RegularTask::run 位于 Core 层;它是普通 Turn 的内部执行包装器。它先发送 TurnStarted,再准备或复用预热的模型客户端会话,随后调用 run_turn;若收尾边界仍有 pending input 且没有终止错误,就再次进入。真正的模型—工具循环在 run_turn;最终终态由 Session::on_task_finished 统一发送。