Thread · 对话档案
侧栏里可以重新打开的一个任务
你每天的动作：新建任务、给它改标题、稍后重新打开、归档、从它分叉。
精确定义：你和 Codex 之间的一整段对话。它包含多个 Turn，并保存历史，供以后继续。
不要理解成：程序的“线程”。在 Codex 协议这里，Thread 首先是“整段对话”。
Codex 架构 · 第 0 课
你不是不会 Codex，
只是还没有开发者的翻译表
你已经会创建任务、连续追问、看命令执行、让 Codex 改文件、途中补充要求。开发者只是把这些熟悉动作压缩成了 Thread、Turn、Item、Session 和 Notification。
今天不读 Rust。目标只有一个：看到术语时，脑中能立刻浮现你每天做过的动作。
先只记住这一层关系
侧栏里的一个 Codex“任务” = Thread
Turn 1：你说“检查登录失败并修复” → Codex 做完并回答
Items：用户消息、推理片段、命令执行、文件修改、最终回答……
Turn 2：你追问“再补一个测试” → Codex 做完并回答
Items：新用户消息、新命令、新文件修改、新回答……
Turn 3：你问“解释刚才为什么这样改” → Codex 回答
Items：用户消息、解释文本……
一个 Thread 包含多个 Turn；一个 Turn 包含多个 Item
把你每天的动作逐个翻译
Turn · 一轮工作
从一次输入开始，到 Codex 本轮结束
你每天的动作：发送“修复这个问题”，等待 Codex 调模型、查文件、跑命令、改代码，最后给出结果。
精确定义：对话中的一轮，通常从用户输入开始，以 Agent 完成本轮或被中断结束。
不要理解成：一次模型 API 请求。一个 Turn 为了调用工具，可能请求模型很多次。
Item · 一条内容记录
一轮工作中的每一块内容
你看到的用户消息、Codex 文字、思考摘要、Shell 命令、命令输出、文件修改，都可能是不同 Item。
精确定义：Turn 内持久化的一项输入或输出，是历史记录中更细的基本单位。
不要理解成：只有聊天气泡。工具调用和文件编辑也可以是 Item。
Session · 运行现场
把某个 Thread 真正加载起来后的工作状态
你打开任务后，Codex 知道当前目录、历史、模型、权限、可用工具，也知道现在是否有一轮正在执行。
本课程先这样理解：Session 是一个已加载 Thread 的“运行现场”，负责内存状态和执行协调。
注意：Session 是上下文相关词，也可能指登录会话或网络连接。读代码时一定要看它属于哪个模块。
Notification · 单向进度通知
后台主动把变化推给界面
你看到“开始运行”、文字一个字一个字出现、命令输出滚动、文件已修改、本轮完成。
精确定义：服务端主动发给客户端、通常不要求客户端回复的类型化消息，例如 TurnStarted、AgentMessageDelta、TurnCompleted。
不要理解成：Windows 弹窗或手机推送。这里指程序内部通信方式。
ChatWidget · 终端聊天组件
终端版 Codex 的“聊天操作台”
在 Codex CLI 的全屏终端界面里，它接收输入、展示历史、流式文字、工具状态和错误。
精确定义：Codex TUI 源码中的一个具体界面组件。Widget 就是可交互的界面部件。
重要纠正：你现在使用的 Codex 桌面端有类似聊天区域，但不代表它内部也使用这个 Rust ChatWidget。上一张图追踪的是 TUI 路径。
Task · 最容易误解的词
Task 没有唯一含义，必须先问“在哪一层？”
产品界面
Codex 桌面端侧栏里的一个“任务”，基本可按 Thread / conversation 理解。
Codex 桌面端侧栏里的一个“任务”，基本可按 Thread / conversation 理解。
你的业务语言
“帮我修 Bug”这个目标，也会被普通地叫作 task。
“帮我修 Bug”这个目标，也会被普通地叫作 task。
Core 源码
RegularTask 是执行某类工作的内部运行单元，不等于侧栏那条对话。阅读技巧：以后看到 Task，不要立刻背定义；先看它出现在产品界面、需求描述，还是 Rust 类型名里。
用一次你熟悉的任务串起来
场景：你让 Codex“检查登录失败，修好并补测试”
你在侧栏新建一项工作。
这整个对话档案叫 Thread；桌面端也把它显示为 Task。
这整个对话档案叫 Thread；桌面端也把它显示为 Task。
你按下发送。
一次新的 Turn 开始。
一次新的 Turn 开始。
Codex 加载工作目录、历史、权限、模型和工具。
这些共同构成当前 Session 的运行现场。
这些共同构成当前 Session 的运行现场。
界面出现“开始”、思考文字、命令输出。
后台正用 Notification 持续报告变化；逐小段文字叫 Delta。
后台正用 Notification 持续报告变化；逐小段文字叫 Delta。
Codex 读文件、跑测试、修改代码。
用户消息、命令、文件修改、Agent 回答分别成为多个 Item。
用户消息、命令、文件修改、Agent 回答分别成为多个 Item。
工具结果回到模型，模型继续判断，可能再用工具。
仍然是同一个 Turn，但里面可以有多次模型请求。
仍然是同一个 Turn，但里面可以有多次模型请求。
Codex 给出总结，界面显示完成。
收到 TurnCompleted Notification，本轮结束。
收到 TurnCompleted Notification，本轮结束。
你继续问“为什么这样修？”
同一个 Thread 里开始下一个 Turn。
同一个 Thread 里开始下一个 Turn。
四组最容易混淆的区别
| 容易混淆 | 真正区别 | 判断口诀 |
|---|---|---|
| Thread vs Turn | Thread 是整本对话档案；Turn 是其中一轮工作。 | 侧栏一条是 Thread；按一次发送通常开始一个 Turn。 |
| Thread vs Session | Thread 是可保存、可恢复的对话；Session 是它被加载运行时的现场状态。 | 档案能留下，运行现场可以关闭后重建。 |
| Turn vs 模型请求 | Turn 面向用户的一轮；模型请求是内部采样动作。工具循环会让一次 Turn 多次采样。 | 你发一次，不等于后台只问模型一次。 |
| Event vs Notification | Event 泛指系统里发生的事；Notification 是把某件事单向告诉客户端的协议消息。 | 事情发生是 Event；把事情推到界面是 Notification。 |
| Request vs Notification | Request 是“请做这件事并给我响应”；Notification 是“告诉你一件事，不等回复”。 | turn/start 是请求；后续进度主要靠通知。 |
5 题小测：先点答案，再看反馈
1. 你昨天创建了“修复登录 Bug”，今天重新打开并追问。什么没有变？
2. 你只发了一次消息，Codex 连续跑了 3 条命令。这通常算几个 Turn？
3. 回答文字逐渐出现、命令输出实时滚动，主要靠什么到达界面？
4. Codex 桌面端是否一定在内部使用 Rust 的 ChatWidget？
5. 在源码中看到 Task，第一反应应该是什么？
已答对 0 / 5。全部答完后，再用自己的话向我解释 Thread 和 Turn 的区别。
可信依据
- OpenAI Codex App Server README：Core Primitives：官方定义 Thread 包含多个 Turn，Turn 包含多个 Item。
- OpenAI Codex App Server README：Lifecycle Overview：官方说明 turn/start、流式通知和 turn/completed。
- Codex TUI ChatWidget 源码：确认 ChatWidget 是终端 UI 中的具体结构体。
课程依据源码版本：openai/codex main @ a26f1806a4f4b8cfec2ea1be129963815a61e58c。