02. 核心领域模型¶

Codex 智能体的对象模型分为外部会话语义和内部运行时语义。外部语义面向客户端、历史和界面，主要由线程（Thread）、轮次（Turn）、条目（Item）组成；内部语义面向任务推进，主要由会话（Session）、任务（Task）、轮次上下文（Turn Context）组成。

这两组对象对应不同边界。线程、轮次、条目描述一段会话中发生了哪些事；会话、任务、轮次上下文描述运行时如何推进这些事。

外部会话语义：线程 -> 轮次 -> 条目
内部运行时语义：会话 -> 任务 -> 轮次上下文

线程¶

线程表示一段长期会话。它保存工作目录、模型配置、权限配置、来源、历史、持久化信息和会话标识。终端界面、一次性执行、IDE 或其他客户端都以线程为容器提交任务和读取历史。

线程使 Codex 能够支持长期任务。会话可以在进程重启后恢复，可以从某个历史点分叉出新分支，也可以在客户端重新连接后回放已有状态。线程因此不是单条消息，而是智能体工作过程的持久化容器。

线程还保存与会话恢复相关的元信息，例如动态工具、记忆模式、基础指令和历史记录位置。这些信息决定恢复后的会话能否构造出与原会话一致的模型现场。

轮次表示一次用户任务。它从用户输入开始，以完成、失败或中断结束。一个轮次可以包含多次模型采样、多次工具调用、多次权限审批和多个客户端可见条目。

“修复测试失败”这样的请求通常是一个轮次。模型可能先运行测试，再读取文件，再应用补丁，再验证测试结果。这些动作都服务于同一个用户目标，因此属于同一个轮次。

轮次还承载本轮覆盖配置。当前目录、模型、输出结构、权限、环境变量和协作模式都可以作为本轮现场的一部分进入运行时。

轮次的状态由运行时收束，而不是由模型文本决定。模型输出总结后，运行时仍需确认工具执行、待处理输入、事件记录和持久化都已完成。轮次的完成状态因此反映本地执行系统的最终判断。

条目是轮次内发生的结构化记录。用户消息、助手文本、推理内容、shell 命令、补丁、MCP 调用、动态工具调用、计划更新、权限请求和错误都可以表现为条目或条目相关事件。

条目同时服务展示、回放和后续推理。客户端通过条目展示进度；历史系统通过条目重建轮次；模型上下文从其中提取用户输入、工具结果和关键助手输出，作为下一次采样材料。

条目是协议边界上的稳定单位。内部运行时可能使用 future、流式事件、处理器结果和任务状态表达过程，客户端最终看到的是条目开始、增量、完成和相关状态更新。这个稳定单位使客户端不依赖内部实现细节。

会话是核心运行时中的会话管理器。它持有当前配置、历史、活跃轮次、待处理输入、审批状态、事件通道、持久化句柄和相关服务。

会话以队列方式处理会话操作。用户输入、中断、审批响应、压缩、回滚、记忆模式更新和关闭都按顺序进入。队列化处理保证会话状态在模型流、工具执行和用户交互并存时保持一致。

会话还维护当前活跃轮次与空闲状态之间的转换。活跃轮次存在时，用户输入可能被引导进当前任务；活跃轮次结束后，新的用户输入会启动新任务。这一转换决定轮次边界和待处理输入的归属。

任务表示会话启动的一段运行工作。普通用户任务由普通任务承载，压缩、评审、用户 shell 命令等也可以由各自任务承载。

任务管理生命周期。它在开始时发出轮次开始，运行过程中产生事件和条目，结束时汇总状态，清理活跃轮次，并发出完成、失败或中断结果。普通任务内部会进入模型与工具交替的智能体循环。

轮次上下文是本轮任务的运行快照。它包含当前目录、模型、模型提供方、权限、审批策略、沙箱、网络策略、环境变量、技能、动态工具和输出结构。

轮次上下文将本轮规则固定下来。一次轮次可能持续多次模型采样和工具执行；固定现场可以避免前后步骤使用不同目录、不同权限或不同工具集合。模型上下文和工具运行时都基于同一份轮次上下文工作。

轮次上下文同时承担兼容边界。外部协议可能使用旧的沙箱参数或新的权限配置，运行时需要在轮次上下文中形成单一有效解释。工具执行和模型说明都从这份解释中读取配置。

一次普通任务的对象关系可以按顺序描述：

线程承载会话
轮次表示用户本次任务
会话接收并排队处理输入
会话创建轮次上下文
会话启动任务
任务进入智能体循环
循环产生多个条目
条目被展示、记录并用于后续模型上下文
任务收尾
轮次标记完成
线程保存历史

线程、轮次、条目提供外部可观察的任务结构；会话、任务、轮次上下文提供内部可执行的运行结构。两层对象共同支撑 Codex 的长期会话、实时事件和可恢复历史。