事件与通知:结果怎样回到界面
前五站把工作送进去,这一站把过程和结果接回来。屏幕上的文字、工具状态和“已完成”不是同一条消息,也不是等所有工作结束后才一次性返回。
本课跨越三层,只精读事件适配和 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 通知既可能表示完成,也可能带有失败或中断状态? 仍需通过源码阅读和练习验证掌握,不会因背诵自动标记通关。
先听一遍,再对照源码
普通话讲解,保留关键代码语义、实际操作情境和 GEODYNA 对照。重点听“谁产生事实、谁转换格式、谁更新界面”。
点击开始;页面不会自动播放,也不会自动标记课程通关。
点击任一章,从对应位置开始。
展开音频文字稿 · 听不清时对照看
声音中的术语,对应代码里的哪个词?
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 类。
- 1Core 执行并产生事件
- 2App Server 接收 Event
- 3按事件类型与状态转换
- 4发送 ServerNotification
- 5TUI 匹配通知类型
- 6更新文字、工具项或 Turn 状态
| 粒度 | 负责什么 | 不要误认为 |
|---|---|---|
| Core Event | 报告执行事实,如文本增量、工具项和 Turn 结束 | 不是 TUI 内部 AppEvent |
| ServerNotification | App Server 向客户端发送的协议通知 | 不是 turn/start 的那次受理响应 |
| TUI AppEvent | TUI 组件间的内部协调消息 | 不是第三个后端网络服务 |
| 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,不执行任何真实操作。
先预测会走哪条分支,再点击按钮查看。
只是一段正文
- 收到文本 delta。
- TUI 将它交给流式显示路径。
- 继续等待后续项目与真正终态。
自然语言内容不是协议终态信号。
Item 完成,Turn 可能继续
- 工具执行项目结束并给出结果。
- 界面更新这一个工具项。
- 模型可能继续读取结果、请求工具或给出最终说明。
不要在第一个 item/completed 到来时把整轮显示成成功。
turn/completed + Failed
- App Server 汇总本轮错误。
- 生成 status 为 Failed 的完成通知。
- 客户端显示失败并保留已有内容与可供检查的错误。
完成通知的方法名,不是成功结论。
turn/completed + Interrupted
- Core 走相应中断收尾路径。
- App Server 生成 Interrupted 状态。
- TUI 停止进行中展示,并区分中断与正常完成。
停止显示不意味着已撤销此前发生的真实写操作。
最容易说错的边界
| 常见说法 | 准确表述 |
|---|---|
| AppEvent 属于 App Server | AppEvent 是 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;第三轮再研究重放、断连和状态竞争。