Codex 案例：Thread、Turn、Item
Codex App Server 用 Thread、Turn、Item 表达可持久、可流式、可中断的工作；这是重要实现案例，不是所有 Agent 的统一标准。
- 能用 Thread、Turn、Item 建模 Agent 交互
- 能设计流式事件、审批与断线恢复
- 能识别重复事件与重复副作用
Codex 为什么不只用普通聊天消息来承载 Agent 工作？
普通聊天可以把交互保存成消息列表，但 Agent 的一次工作可能包含计划、工具执行、审批、文件变化、错误、重试和最终交付。把这一切挤进助手消息，会让客户端无法知道什么正在运行、什么已经失败、什么仍在等待用户。
可以先把 Thread 理解为一个长期任务文件夹，Turn 是用户发起的一轮工作，Item 是这轮工作里的原子事件。Item 有 started、增量、completed 或 failed 等生命周期。客户端展示事件，服务端保存事实。
Thread、Turn、Item 是 OpenAI App Server 公开采用的 Codex 产品模型，适合作为案例学习；其他 Agent 产品可能使用 Session、Run、Step 等名称。课程关注的是持久容器、工作单元和原子事件三层责任，而不是要求所有产品复制命名。
先记住这句话在 Codex 的协议里，Thread 保存一段持续工作，Turn 表示一次用户驱动的任务推进，Item 是消息、工具执行、审批或 Diff 等原子事件。这套建模让客户端能重连并恢复一致时间线；其他 Agent 产品可能使用不同名称和协议。
先用嵌套关系看懂三个层级
一个 Thread 可以容纳多次 Turn，例如用户先要求分析访谈，下一次再要求补充反例。一个 Turn 内可以有多个 Item：用户消息、计划、搜索工具、审批请求、工具结果、洞察草稿和最终回答。
Thread 负责长期身份、历史和恢复；Turn 负责一次目标、预算与终态；Item 负责具体事件的类型、输入、状态与产物。三层都需要稳定 ID，才能在重复消息和断线后识别同一事实。
跟着八条事件走完一次工作
客户端提交 turn/started；服务端产生 plan/started 和 plan/completed；随后 tool/started、tool/completed；需要外部保存时产生 approval/requested；用户回应 approval/resolved；验证通过后 turn/completed。每条事件都有序号和所属 Turn。
增量事件用于流式更新同一个 Item，不代表它已经完成。客户端必须等待明确终态，不能看到第一段输出就把任务标成成功。
断线恢复依赖服务端事实与幂等
网页关闭时，工具可能仍在服务端运行。重连客户端带上最后已见的事件 cursor，服务端补发缺失事件，而不是重新创建 Turn。未完成审批保持等待，已完成工具不重复执行。
外部写入还需要幂等键，即使网络导致请求重发，业务系统也只产生一个结果。事件去重解决界面一致性，动作幂等解决真实副作用，两者不能互相替代。
协议事件与诊断日志不是同一件事
协议事件要稳定、可重放、面向产品状态；内部日志可以更细、更频繁，用于工程诊断。把所有底层日志暴露给客户端会造成强耦合，也会让用户被无关噪声淹没。
兼容性同样是产品需求。新客户端可以理解新 Item，旧客户端至少应忽略未知字段并继续显示已有时间线。
聊天消息不足以描述真实 Agent。一个 Turn 中可能同时出现计划、工具调用、审批、Diff 和流式输出；Thread 是可持久容器，Item 是带生命周期的原子事件，服务端状态应成为重连后的事实源。
initialize 握手并协商协议与能力
创建 Thread 并提交一次 Turn
发送 item/started、delta、审批请求与 completed
保存事件序号、终态和产物，重连时按 cursor 补发
有术语没听懂？在这里用人话再看一遍7 个词＋
- Thread
- 可跨多轮工作持续存在的任务与会话容器；这里主要采用 Codex App Server 案例命名。
- Turn
- 一次用户发起、拥有目标、预算和终态的工作单元。
- Item
- Turn 内可持久、可流式、带生命周期的原子事件。
- Delta
- 同一个 Item 在完成前逐步发送的增量内容。
- Cursor
- 客户端记录最后已处理事件位置，用于断线后补发缺失事件。
- 事件重放
- 根据持久事件重新构建客户端状态，而不是依赖先前页面内存。
- 服务端事实源
- 任务真实状态由执行和持久化所在的服务端决定，客户端不自行猜测。
Shell 执行一半时用户关闭网页
Agent 正在运行测试，客户端断线；服务端继续保存 Item 与工具回执。
- 01
重连客户端提交最后已见 cursor
- 02
服务端只补发缺失事件，不重新创建 Turn
- 03
UI 依据 Item 终态恢复工具、Diff 与最终回答
用户看到连续时间线，命令只执行一次，未完成审批仍保持等待。
本章依据与证据边界4 条结论 · 3 份原始材料＋
正文已经把关键来源放在相关概念旁边。这里保留完整核验清单：每条材料能支持什么、不能支持什么；不要求离开本站才能继续学习。
- [1]
OpenAI App Server 公开使用 Thread、Turn、Item 建模 Codex 任务，并通过双向 JSON-RPC 传递事件和审批。
官方事实OPUnlocking the Codex harness: App Server官方工程文章 · 核验 2026-07-14 - [2]
OpenAI App Server 文档说明 Turn 会产生流式 Item 更新，并允许服务端主动请求审批或补充输入；具体名称属于 Codex 产品协议案例。
官方事实OPUnlocking the Codex harness: App Server官方工程文章 · 核验 2026-07-14 - [3]
本站的事件 cursor、动作幂等与断线恢复验收是基于服务端事实源整理的产品设计，不是 OpenAI 公布的固定恢复算法。
本站推演OPUnlocking the Codex harness: App Server官方工程文章 · 核验 2026-07-14 - [4]
本站对协议事件、诊断日志与新旧客户端兼容的区分，是依据 App Server 双向协议做出的产品推演。
本站推演OPUnlocking the Codex harness: App Server官方工程文章 · 核验 2026-07-14
查看全部一手材料与源码证据 3 条
这份材料说明 Codex App Server 如何以双向 JSON-RPC/JSONL 协议把同一 Harness 暴露给 CLI、IDE、桌面与 Web 客户端。它定义 Thread、Turn、Item 及流式事件、审批暂停、持久化和重连语义，是课程讲解 Agent 客户端协议与多端复用的直接实现依据。
固定提交源码 · 核验 2026-07-11Hermes Agent async delegation and turn finalizationNous Research这段源码说明后台 Subagent 的完成结果进入共享队列，并在 Agent 空闲时形成新的 Turn，而不是插进正在进行的工具序列；这样可以保持消息角色顺序与 Prompt Cache 稳定。这是 Hermes 的实现选择，不是行业统一协议。
官方产品实现 · 核验 2026-07-14Hermes Agent SessionsNous Research当前文档说明 Hermes 将完整消息与工具历史保存在 SQLite，会话可恢复和跨端检索，但恢复历史不等于把所有旧字节持续塞回模型上下文。
证据边界：持久会话不自动保证恢复无副作用，也不是隐私删除或长期语义记忆。