Core 层的
start_or_steer_turn

上一站，App Server 已经把客户端请求翻译成 Core 能接收的内部对象。本课把“进入 Core 公开入口 → 通过 Session 队列 → 检查状态并选择分支 → 返回受理结果”这一整段叫作第三站。整段链路不调用模型、不执行工具；入口函数 start_or_steer_turn 本身不读取状态，私有函数 start_or_steer 组织三条主分支，而它调用的 Session::steer_input 才真正加锁读取活动 Turn 状态。

先分清三个尺度：对话、Turn、流式片段

一个 Thread
├─ Turn A
│  ├─ turn/started
│  ├─ item/agentMessage/delta  「第 1 个流式片段」
│  ├─ item/agentMessage/delta  「第 2 个流式片段」
│  ├─ 工具调用、工具结果、更多 Item……
│  └─ turn/completed
└─ Turn B                         ← A 完成后再次发送，才新开 Turn

一句话：整段对话可以有多个 Turn；一次正常的“你发送 → 我工作 → 本次完成”通常是一个 Turn；流式输出只是这个 Turn 内的多条增量通知。

源码依据：turn/started、turn/completed 与 item/agentMessage/delta · 每条 delta 同时携带 threadId、turnId 与 itemId

Goal 模式与多智能体：不能按“整个目标 = 一个 Turn”计算

Goal G：完成一项代码功能
│
└─ 主控 Thread P
   ├─ Turn P1：理解需求、检查代码、开始实现 → completed
   ├─ Turn P2：Goal 自动续作、运行测试、修复问题 → completed
   └─ Turn P3：验收全部要求、把 Goal 标记 complete → completed

结论：一个 Goal 可以跨多个 Turn；每个 Turn 仍有独立 turnId。

主控 Thread P：Turn P1
   spawn_agent(A) ───── wait ───── 收到 A 的结果 ───── 汇总
          │
          ▼
子控 Thread A：Turn A1
          编写代码 ───── 调用工具 ───── completed

这是 P1 和 A1 两个 Turn，并行协作；不是一个跨 Thread 的 Turn。

计数原则：先锁定一个 threadId，再数它下面的 turnId。跨 Thread 的一次“派活—回报”不是一个共享 Turn。

源码依据：Goal 明确跨 Turn 持续 · Thread 空闲后启动 Goal 续作 Turn · followup_task 与 send_message 的 Turn 语义 · 对子 Thread 执行 start-or-steer

先说结论：第三站是一段“调度链”，不是一个函数

先拆开四个最容易混淆的东西

把它放回完整链路

注意：start_or_steer_turn 是对上游开放的入口；私有函数 start_or_steer 写着“追加、启动、拒绝”的主分支；steer_input 负责锁住并检查真实活动状态。三者都在 Core，但职责粒度不同。

先用你每天的体验理解三种结果

关键校正：四种“空”不能混为一谈

源码依据：TUI 同时检查文字与图片 · TurnStartParams.input 是 Vec · App Server 只校验文字上限 · 空闲时 Started · 活动 Turn 的空 Steering 被拒绝 · 模型请求读取 Thread 历史

运行中切换模型，会变成一次“空 Steering”吗？

源码依据：TUI 的 AppEvent::UpdateModel · thread/settings/update 请求构造 · 设置用于 subsequent turns · App Server 转成 Op::ThreadSettings · 实验性的 turn/settings/update

真实代码精读 ①：公开入口为什么只有 7 行？

pub async fn start_or_steer_turn(
    &self,
    request: TurnInputRequest,
) -> CodexResult<TurnInputSubmission> {
    self.submit_turn_input_with_mode(request, TurnInputMode::StartOrSteer)
        .await
}

源码依据：CodexThread::start_or_steer_turn

TurnInputRequest：不是一句话，而是一整包内部请求

pub struct TurnInputRequest {
    pub input: TurnInput,
    pub thread_settings: ThreadSettingsOverrides,
    pub start: TurnStartOptions,
    pub additional_context: BTreeMap<String, AdditionalContextEntry>,
    pub responsesapi_client_metadata: Option<HashMap<String, String>>,
    pub trace: Option<W3cTraceContext>,
}

真正难懂的不是“它有六个字段”，而是这些字段有层次。普通文字“帮我检查登录模块”实际被包了三层：

高效记法：input 是主件；thread_settings 是 Thread 今后的运行规则；start 是“真开新 Turn 才落地”的本轮选项；其余三个分别是补充材料、服务标签和追踪号。

TurnInputRequest::new(TurnInput::UserInput { ... })
    .with_thread_settings(thread_settings)
    .on_start(TurnStartOptions { ... })
    .with_additional_context(additional_context)
    .with_responses_metadata(metadata)
    .with_trace(trace)

源码依据：TurnInputRequest 与 Builder

真实代码精读 ②：“提交邮箱”到底是什么、为什么需要它？

一次 Turn 输入实际怎样穿过它？

let id = new_submission_id();
let (reply_tx, reply_rx) = oneshot::channel();

self.submit_with_id(Submission {
    id,
    op: Op::TurnInput {
        request: Box::new(request),
        mode,
        reply: reply_tx,
    },
    ...
}).await?;

reply_rx.await.unwrap_or(Err(CodexErr::InternalAgentDied))

上面是寄件方。下面是 Session 收件方的关键代码：

while let Ok(sub) = rx_sub.recv().await {
    match sub.op {
        Op::TurnInput { request, mode, reply } => {
            let result = turn_input::handle(...).await;
            let _ = reply.send(result);
        }
        // Interrupt、审批回复、Shutdown 等其他内部操作也从这里分发
    }
}

最高效的记法：请求包是“做什么”；Submission 是“投递哪种内部操作”；提交队列是“按次序送到状态拥有者”；oneshot 是“只回一次受理结果”。

源码依据：Session 创建容量 512 的提交通道 · 发送 Op::TurnInput 并等待一次性回复 · Session submission loop

真实代码精读 ③：真正的三分支决策

match session.steer_input(...).await {
    Ok(turn_id) => {
        settings.apply_steered(...).await?;
        Ok(TurnInputSubmission::Steered { turn_id })
    }

    Err(NotSubmittedReason::NoActiveTurn) => {
        let turn_context = settings.apply_started(...).await?;
        session.spawn_task(turn_context, task_input, RegularTask::new()).await;
        Ok(TurnInputSubmission::Started { turn_id: submission_id })
    }

    Err(reason) => Ok(TurnInputSubmission::NotSubmitted { reason }),
}

源码依据：路由入口与 start_or_steer · steer_input 的活动 Turn 检查

最重要的类型区别：拒绝不一定是系统错误

CodexResult<TurnInputSubmission>

// 系统/程序级错误
Err(CodexErr::InternalAgentDied)

// 系统正常运行，但业务路由明确拒绝
Ok(TurnInputSubmission::NotSubmitted {
    reason: NotSubmittedReason::EmptyInput,
})

这对产品设计非常重要：系统故障和状态不允许是两类问题。前者需要重试、报警或恢复；后者应该给用户可理解的原因和下一步操作，而不是统一显示“发生未知错误”。

Started 和 Steered 也只表示 Core 接受了输入。源码明确说明：它们不等待 Prompt Hook、模型上下文更新、持久化或模型采样，更不代表 Turn 完成。

源码依据：TurnInputSubmission 与拒绝原因

面向最终目标：GEODYNA 现在已有一个相似的雏形

产品判断：工程软件不能把所有“运行中再次输入”都默认为 Steering。若当前任务正处于不可逆提交边界，应明确拒绝或要求用户选择“追加约束、排队为下一任务、先中断当前任务”。

GEODYNA 只读依据：D:\GEODAMNEW\components\LLMCommandBar.tsx:318 的延续判断，以及 :692 开始的发送路由。

腾讯 AI 原生产品经理视角

即时小测

最后用两句话交作业