第一轮 · 第 6 站 · CORE → APP SERVER → TUI · 主链返回站

事件与通知:结果怎样回到界面

前五站把工作送进去,这一站把过程和结果接回来。屏幕上的文字、工具状态和“已完成”不是同一条消息,也不是等所有工作结束后才一次性返回。

本站必背:走路时复述这一段

分清 Core Event、ServerNotification、AppEvent
识别 delta、Item 完成与 Turn 完成
用身份和状态设计可信的进度界面

本课跨越三层,只精读事件适配和 TUI 消费的关键入口;明确区分整个返回链路与单个函数的职责。 讲义已备好 ≠ 已掌握;本页不会改动你的通关状态。

本站必背 · 走路复习

第 6 站:事件报告事实,通知驱动界面

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

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

第六站是 Core 经 App Server 返回客户端的消息链。Core 用事件报告执行事实,例如新增文字、工具活动和本轮结束;App Server 把这些事件转换成客户端协议通知,TUI 再消费通知、更新显示。Core Event 是执行事件,ServerNotification 是面向客户端的通知,AppEvent 则是 TUI 内部协调消息,三者不能混用。流式文字增量、单个项目完成和整轮结束属于不同粒度。收到 turn/completed 还要查看 status,区分完成、失败或中断;即使状态是 Completed,也不能自动证明长期目标已经实现。记住:受理响应不是过程通知,显示发生变化不是又启动了一个 Turn,终态必须连同状态和证据一起读。

复述顺序:Core 执行事实 → App Server 协议转换 → TUI 更新 → 区分消息粒度 → 核对终态。

背诵用于抓牢主线。理解自测:为什么 turn/completed 通知既可能表示完成,也可能带有失败或中断状态? 仍需通过源码阅读和练习验证掌握,不会因背诵自动标记通关。

核对依据:增量事件转换 · 终态通知 · 完成与中断状态 · 界面分发。

配套音频 · AI 合成语音

先听一遍,再对照源码

普通话讲解,保留关键代码语义、实际操作情境和 GEODYNA 对照。重点听“谁产生事实、谁转换格式、谁更新界面”。

全长 6:51 · 6 章MP3 · 3.1 MB普通话女声 · 稍慢语速
下载 MP3

点击开始;页面不会自动播放,也不会自动标记课程通关。

点击任一章,从对应位置开始。

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

    AI 合成语音;收听位置仅保存在当前浏览器,不跨设备同步。代码以固定快照为准。可下载后用手机播放器离线收听。

    先定位:这一站到底在讲哪一层?

    课程站级范围是 Core → App Server → TUI 的返回链。Core 报告执行中发生的事实;App Server 将这些事实适配为面向客户端的协议消息;TUI 消费通知并更新自己的显示状态。

    apply_bespoke_event_handling 位于 App Server;handle_turn_completed_notification 和 on_agent_message_delta 位于 TUI。不能把这三个函数统称为“Core 返回函数”。你使用的桌面客户端也会消费协议,但不能据此断言它使用公开仓库里的 ChatWidget 类。

    1. 1Core 执行并产生事件
    2. 2App Server 接收 Event
    3. 3按事件类型与状态转换
    4. 4发送 ServerNotification
    5. 5TUI 匹配通知类型
    6. 6更新文字、工具项或 Turn 状态
    粒度负责什么不要误认为
    Core Event报告执行事实,如文本增量、工具项和 Turn 结束不是 TUI 内部 AppEvent
    ServerNotificationApp Server 向客户端发送的协议通知不是 turn/start 的那次受理响应
    TUI AppEventTUI 组件间的内部协调消息不是第三个后端网络服务
    TUI 显示函数消费通知、组织展示、请求重绘不承担模型实际推理

    先看三种消息,以及三个“完成”

    请求是“请做一件事”,响应是“对这个请求的答复”,通知是“某个状态或事实更新了”。turn/start 的响应可以先告诉你已受理;这轮后续的文字、工具与终态再由其他通知陆续到达。

    delta 是新增片段,不保证一个片段恰好对应一个汉字、一个词或一个 token。Item 是这一轮中的一个项目,例如一段助手消息或一次工具调用;Item 完成也不等于 Turn 完成。

    边界表示什么仍不能推出什么
    模型 ResponseEvent::Completed一次模型响应流结束工具已经全部结束、整轮无需继续
    item/completed当前项目完成同一 Turn 不会再有其他项目
    turn/completed本轮进入终态;还要看 turn.status用户的整个长期目标已经实现

    具体输入,逐层拆开

    一个文本增量通知的示意字段;ID 均为虚构,不能当作真实线上记录。

    {
      "method": "item/agentMessage/delta",
      "params": {
        "threadId": "thread-A",
        "turnId": "turn-1",
        "itemId": "message-1",
        "delta": "已经读取配置。"
      }
    }

    threadId 找到哪段任务对话,turnId 找到哪轮工作,itemId 找到这轮中的哪个显示项目,delta 才是新增文字。正文写了“读取完成”,仍不是 turn/completed。

    App Server:先拆事件,再选择适配分支

    1. 函数签名与事件拆箱

    真实源码 · codex-rs/app-server/src/bespoke_event_handling.rs:149–165

    代码较长时可左右滑动;下方按语句和术语拆解。

    #[allow(clippy::too_many_arguments)]
    pub(crate) async fn apply_bespoke_event_handling(
        event: Event,
        conversation_id: ThreadId,
        conversation: Arc<CodexThread>,
        thread_manager: Arc<ThreadManager>,
        outgoing: ThreadScopedOutgoingMessageSender,
        thread_state: Arc<tokio::sync::Mutex<ThreadState>>,
        thread_watch_manager: ThreadWatchManager,
        thread_list_state_permit: Arc<tokio::sync::Semaphore>,
        fallback_model_provider: String,
    ) {
        let Event {
            id: event_turn_id,
            msg,
        } = event;
        match msg {
    逐句/逐词这段代码实际做了什么
    event: Event传入一份 Core 事件;不是来自输入框的字符串。
    conversation_id: ThreadId这份事件归属哪段任务对话。老命名 conversation 与协议里的 thread 要对照阅读。
    conversation: Arc<CodexThread>共享 Core 对话访问对象,不是 UI 组件。
    outgoing: ThreadScopedOutgoingMessageSender用于向关注该 Thread 的客户端发消息;sender 负责发送,不等于事件本体。
    thread_state: Arc<...Mutex<ThreadState>>App Server 对该 Thread 的跟踪状态,用于整理快照、错误和完成信息。
    let Event { id: event_turn_id, msg } = event结构体解构:把 Event.id 在本地命名为 event_turn_id,把消息体取到 msg。这里的 id 要按该 Event 契约理解,不能一律当 JSON-RPC 请求 id。
    match msg按事件枚举的具体种类选择处理分支。

    2. 文本增量交给协议映射器

    真实源码 · codex-rs/app-server/src/bespoke_event_handling.rs:992–1003

    代码较长时可左右滑动;下方按语句和术语拆解。

            msg @ (EventMsg::AgentMessageContentDelta(_)
            | EventMsg::PlanDelta(_)
            | EventMsg::ReasoningContentDelta(_)
            | EventMsg::ReasoningRawContentDelta(_)
            | EventMsg::AgentReasoningSectionBreak(_)) => {
                let notification = item_event_to_server_notification(
                    msg,
                    &conversation_id.to_string(),
                    &event_turn_id,
                );
                outgoing.send_server_notification(notification).await;
            }
    逐句/逐词这段代码实际做了什么
    msg @ (A | B | ...)匹配多个事件变体,同时把整个匹配值绑定到 msg。竖线在这里表示匹配备选,不是布尔值计算。
    item_event_to_server_notification(...) 把 Core 项目事件和 Thread/Turn 身份交给协议映射器,产出客户端通知。
    send_server_notification(notification).await发送通知;这句不是调用模型,也不是把用户问题重新提交一次。

    终态:方法名相同,状态可能不同

    turn/completed 表示“这轮已收口”,不必然等于成功。这个快照的 App Server 会把正常完成、失败和中断都表达为相应的终态通知,只是 turn.status 不同。

    3. 正常收尾路径根据已记录错误判断状态

    真实源码 · codex-rs/app-server/src/bespoke_event_handling.rs:1571–1583

    代码较长时可左右滑动;下方按语句和术语拆解。

    async fn handle_turn_complete(
        conversation_id: ThreadId,
        event_turn_id: String,
        turn_complete_event: TurnCompleteEvent,
        outgoing: &ThreadScopedOutgoingMessageSender,
        thread_state: &Arc<Mutex<ThreadState>>,
    ) {
        let turn_summary = find_and_remove_turn_summary(conversation_id, thread_state).await;
    
        let (status, error, last_agent_message) = match turn_summary.last_error {
            Some(error) => (TurnStatus::Failed, Some(error), None),
            None => (TurnStatus::Completed, None, turn_summary.last_agent_message),
        };
    逐句/逐词这段代码实际做了什么
    find_and_remove_turn_summary(...).await取出本轮累计的摘要状态,为这次收尾使用;不是删除整段 Thread。
    match turn_summary.last_error看 App Server 已跟踪的本轮错误。
    Some(error)有错误,构造 Failed 以及对应错误;不是看到 Core 事件叫 TurnComplete 就强制成功。
    None没有这里的错误,构造 Completed 并携带最后助手消息。
    (status, error, last_agent_message)一次返回三个局部结果的元组,供下一步组装协议通知。

    边界提醒:中断是另一条 handle_turn_interrupted 路径,1601–1623 行明确使用 Interrupted,不由这个 match 的 None 分支代表。

    4. 真正组装并发出 turn/completed

    真实源码 · codex-rs/app-server/src/bespoke_event_handling.rs:1404–1419

    代码较长时可左右滑动;下方按语句和术语拆解。

        let notification = TurnCompletedNotification {
            thread_id: conversation_id.to_string(),
            turn: Turn {
                id: event_turn_id,
                items,
                items_view,
                error: turn_completion_metadata.error,
                status: turn_completion_metadata.status,
                started_at: turn_completion_metadata.started_at,
                completed_at: turn_completion_metadata.completed_at,
                duration_ms: turn_completion_metadata.duration_ms,
            },
        };
        outgoing
            .send_server_notification(ServerNotification::TurnCompleted(notification))
            .await;
    逐句/逐词这段代码实际做了什么
    thread_id / turn.id同时带上对话和本轮身份,避免不同工作的信息混在一起。
    items 与 items_view只带相应视图中的项目;别假设这个通知必然包含完整历史。
    error / status / started_at / completed_at分别描述错误、终态和时间,不是一个“结束字符串”包办所有含义。
    ServerNotification::TurnCompleted(notification)Rust 枚举变体包装通知数据;序列化后的协议方法名是 turn/completed。

    TUI:通知到了,谁更新文字和状态?

    5. 不同通知分发给不同函数

    真实源码 · codex-rs/tui/src/chatwidget/protocol.rs:73–84

    代码较长时可左右滑动;下方按语句和术语拆解。

                ServerNotification::TurnCompleted(notification) => {
                    self.handle_turn_completed_notification(notification, replay_kind);
                }
                ServerNotification::ItemStarted(notification) => {
                    self.handle_item_started_notification(notification, replay_kind);
                }
                ServerNotification::ItemCompleted(notification) => {
                    self.handle_item_completed_notification(notification, replay_kind);
                }
                ServerNotification::AgentMessageDelta(notification) => {
                    self.on_agent_message_delta(notification.delta);
                }
    逐句/逐词这段代码实际做了什么
    TurnCompleted(notification)整轮终态交给 handle_turn_completed_notification;该函数继续按 Completed、Interrupted、Failed 等状态处理。
    ItemStarted / ItemCompleted维护一个项目的显示生命周期,不是把整个 Thread 开始或结束。
    AgentMessageDelta(notification)把新增文本字段交给 on_agent_message_delta。
    self.on_...调用当前 ChatWidget 上的方法,是 TUI 内部工作,不是跨回 App Server。

    6. 名字像业务处理,函数体其实只是委托

    真实源码 · codex-rs/tui/src/chatwidget/streaming.rs:141–143

    代码较长时可左右滑动;下方按语句和术语拆解。

        pub(super) fn on_agent_message_delta(&mut self, delta: String) {
            self.handle_streaming_delta(delta);
        }
    逐句/逐词这段代码实际做了什么
    &mut self允许更新当前组件的内部状态。
    delta: String传入本次新增的文本片段。
    self.handle_streaming_delta(delta)具体的流式显示协调继续委托给下游。不能把所有重绘、缓冲逻辑都说成写在这三行里。

    把同一个场景换一种条件

    同样看到界面出现“完成”相关内容,能否宣布 Turn 已成功?

    仅为本地教学演示,不调用模型或 GEODYNA,不执行任何真实操作。

    先预测会走哪条分支,再点击按钮查看。

    最容易说错的边界

    常见说法准确表述
    AppEvent 属于 App ServerAppEvent 是 TUI 内部事件名;ServerNotification 才是这里的协议通知类型。
    on_agent_message_delta 里面实现全部流式绘制该函数只委托给 handle_streaming_delta;职责描述必须标出粒度。
    turn/completed 一律等于成功必须查看 turn.status;失败和中断也需要终态收口。
    重新打开历史,就重新执行旧 Turn历史回放属于显示/恢复路径,不能据此推断重新执行旧工具。

    迁移到你的 GEODYNA 智能体

    以下是设计练习,不代表并行产品线已经实现或通过验收;本次只制作课程,不修改 GEODAMNEW。

    候选界面不应只有一条无限转动的“思考中”。它可以分别展示:读取工程、等待确认、执行命令、校验结果、生成解释以及最终状态。

    工程事实必须由实际执行层提供:命令到底提交了吗,求解是否真的结束,结果是否有效,不能靠模型的一段话代替。音频里提到的这些状态是产品设计建议,不是当前产品验收结论。

    你要设计的点可验证的证据
    进度信息有身份每条项目更新都能找到 Thread、Turn 和 Item;恢复显示时不串入另一轮。
    失败可理解显示失败阶段、错误、已发生的改动及可执行的下一步,而不是仅说“出错”。
    成功有证据明确区分命令已受理、执行完成、结果校验通过和用户目标完成。

    产品经理练习:给“读取算例 → 请求修正 → 校验结果”画出 5 条界面事件,并指定哪一条才允许显示成功。

    先答小测,再看解析

    每题即时反馈,可反复尝试;答对这些题也不会替代你的源码复述。

    1. AppEvent 在这里属于哪一层?

    2. 文字增量包含“已完成”,能立即结束 Turn 展示吗?

    3. handle_turn_complete 的 last_error 为 Some 时,生成什么状态?

    4. 一个 item/completed 能证明整轮没有后续工具吗?

    5. 三行的 on_agent_message_delta 真正做了什么?

    最后一句话交作业

    请用一句话分别说明 Core Event、ServerNotification、TUI AppEvent;再解释为什么 turn/completed 还要查看 status。

    展开参考答案(先自己说一遍)

    Core Event 是执行事实;App Server 将其适配为面向客户端的 ServerNotification;TUI AppEvent 用于界面内部协调。turn/completed 表示本轮已收口,status 才区分 Completed、Failed 或 Interrupted;其中 Completed 也不自动证明整个长期目标已实现。

    下一轮再回来时:从实际通知追 threadId、turnId、itemId、delta 和完整 Item;第三轮再研究重放、断连和状态竞争。