读懂 Codex（7.36）：ExtensionRegistry 与 Session、Thread、Turn、Step Data

进程内 Extension 通过 Builder 按 contributor 类型注册成不可变 Registry；私有状态不塞进 Core 结构，而是按 Session/Thread/Turn/Step 创建 ExtensionData，以 TypeId→Arc 的类型映射隔离生命周期。

本节只研究“Extension 注册和状态作用域”。输入是 扩展实例、host-provided ExtensionDataInit，状态由 extension-api Registry/ExtensionData 与 Host 持有，成功输出为 不可变 contributor 列表和分层 typed stores。相邻章节中看起来相似的对象如果由不同组件拥有，就不能用一个布尔状态替代。

先确定边界和状态所有者

问题	本节答案
谁发起	扩展实例、host-provided ExtensionDataInit
谁拥有可变状态	extension-api Registry/ExtensionData 与 Host
成功产物	不可变 contributor 列表和分层 typed stores
不在本节内	Extension 注册和状态作用域之外的上游产品策略和下游业务实现

这张表的用途不是复述名词，而是约束实现顺序：校验必须发生在副作用之前；已经提交的状态只能由原所有者撤销；只读投影不能反过来成为控制权威。

端到端调用链

1. Host 构造 RegistryBuilder
2. 按类型/顺序注册 Arc contributor
3. build 不可变 Registry
4. 创建各生命周期 ExtensionData
5. 按 TypeId get/get_or_init/insert/remove

这条链里至少有三种时间尺度：配置或身份在 Thread 创建时冻结，Turn 内状态由 Session 串行协调，Step 级目录与能力在每次模型采样前重新捕获。若把后一个时点的新状态拿去解释前一个时点已经发出的调用，就会产生跨代错误。

源码机制拆解

注册顺序有语义

Registry 为每类 contributor 保存 Vec；Context/MCP/Item 等 Host 调用按该顺序遍历。MCP 同名 overlay 后项替换前项，ApprovalReview 则第一个 claim 的 decision 胜出。

这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 extension-api Registry/ExtensionData 与 Host 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。

State 用类型而不是字符串键

ExtensionData 以 TypeId 索引 Arc<dyn Any+Send+Sync>，读取时按同一泛型 T downcast；扩展之间只要不共享类型就不会误取对方值。

这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 extension-api Registry/ExtensionData 与 Host 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。

每个 scope 有 host identity

level_id 记录 Session/Thread/Turn/Step 所属对象。Host 明确创建和丢弃 store；ExtensionData 本身不负责持久化，也不会自动从 Thread store 复制到 Turn store。

这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 extension-api Registry/ExtensionData 与 Host 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。

Init 冻结稳定输入

ExtensionDataInit 在 scope 创建前由 Host 填充，clone 共享 Arc；子 Agent fork 可选择构造新的 init，防止运行时 contributor state 被错误当作可继承配置。

这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 extension-api Registry/ExtensionData 与 Host 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。

Python 风格伪代码

下面的伪代码提炼状态机与错误顺序，不逐行翻译 Rust，也不假装 Python 对象具有 Rust 的所有权保证：

class ExtensionData:
    def __init__(self, level_id, initial={}):
        self.level_id = level_id
        self._values = dict(initial)  # key is concrete type
        self._lock = Lock()

    def get_or_init(self, value_type, factory):
        with self._lock:
            if value_type not in self._values:
                self._values[value_type] = Shared(factory())
            return self._values[value_type]

def build_registry(extensions):
    builder = ExtensionRegistryBuilder()
    for extension in extensions:
        extension.register_contributors(builder)
    return builder.build()

阅读这段伪代码时要检查三件事：第一，输入是否在副作用前完成规范化；第二，异步等待是否仍携带原 Thread/Turn/Step 身份；第三，失败后究竟释放了什么、又保留了什么。只写快乐路径会把本节最重要的一致性条件删掉。

失败、取消与恢复

故障点	已发生的状态	可观察结果	恢复责任
两个值使用同一 Rust/Python 类型键	后 insert 覆盖前值	返回 previous Arc	为不同语义定义包装类型
在 get_or_init 里做重工作	map lock 被持有	阻塞其他访问	把异步/重资源放入已附加对象内部
把 ExtensionData 当持久存储	Thread stop 后 map 丢弃	状态消失	用明确持久服务/rollout

取消不自动等于回滚，列表不自动等于权威存储，模型看见的描述也不自动等于已经获准执行。对于已经建立的 Thread、写入的 Edge、入队的 Mailbox、安装的插件或外部工具副作用，必须由相应所有者执行显式关闭、补偿或保留。

并发与一致性不变量

• 同一身份不能在并发路径中被重复预留或重复注册；若允许幂等重试，幂等键必须是稳定路径、ThreadId、request id 或 catalog revision，而不是展示名称。
• 一次模型采样看见的 Prompt、工具目录和执行入口必须来自同一个 Step 快照；刷新只影响后续 Step。
• Watch/Activity/事件是通知机制，不是状态本身。被唤醒后必须重新读取 Registry、Session、Mailbox、Store 或 Binding 的权威值。
• 失败路径不得“为了干净”删除仍可恢复的历史；同样也不得把只剩历史的对象伪报成当前仍驻留运行。

设计思路与代价

本节设计保护的核心不变量是：进程内 Extension 通过 Builder 按 contributor 类型注册成不可变 Registry；私有状态不塞进 Core 结构，而是按 Session/Thread/Turn/Step 创建 ExtensionData，以 TypeId→Arc 的类型映射隔离生命周期。代价是同一个功能会跨越地址、配置、Session、队列、存储或扩展适配层，测试也必须覆盖正常、并发和中途失败。更短的单体实现虽然容易演示，却无法区分“存在、已加载、正在运行、可恢复、已关闭、模型可见”这些彼此独立的事实。

设计动机部分是根据生产类型、调用顺序和测试行为归纳；源码可直接证明的是字段、分支、状态所有者和失败结果。文章不会把推断写成服务端或产品层的未公开事实。

源码与测试证据

位置	能证明什么
codex-rs/ext/extension-api/src/registry.rs	Builder/Registry 类型化列表和顺序
codex-rs/ext/extension-api/src/state.rs	ExtensionDataInit/ExtensionData
codex-rs/ext/extension-api/src/lib.rs	公开 API 边界
codex-rs/core/src/session/session.rs	Session/Thread stores 创建

测试/可执行检查	覆盖重点	预期
codex-rs/ext/extension-api/tests/registry.rs	正常、边界与状态转换	应与本节不变量一致
codex-rs/ext/extension-api/tests/state.rs	失败、并发或兼容行为	应与本节不变量一致

当前环境没有 Cargo，本轮不伪报 Rust 测试执行；验证由锁定提交下的源码—测试静态对读、源文件存在性检查、Mermaid 渲染、Astro 生产构建和公开页面检查组成。

Mini Codex 复刻建议

Mini Codex 应先复刻本节的协议不变量：明确状态所有者、稳定身份、可回滚预留、同 Step 快照、超时/取消和单一终态。平台沙箱、远程 Executor、OAuth、Backend App Route 或第三方 MCP Server 的安全性质不能由一个本地 Python mock 证明，适配器只能验证调用顺序和故障处理。

本节结论

进程内 Extension 通过 Builder 按 contributor 类型注册成不可变 Registry；私有状态不塞进 Core 结构，而是按 Session/Thread/Turn/Step 创建 ExtensionData，以 TypeId→Arc 的类型映射隔离生命周期。 掌握这一点后，再看相邻模块时就能判断它是在改变身份、运行状态、模型可见上下文、外部能力，还是仅提供观察快照。

阅读导航

上一节：Hook 输出解析、Additional Context、输入改写与阻断结果 · 下一节：ContextContributor 的 Prompt Slot、Turn Context 与 WorldState Section

源码依据

本文基于锁定提交 fe01054a28fa4bd04716d9ceadb410f2443a50ce 的生产代码和相邻测试静态核对。关键入口如下：

• codex-rs/ext/extension-api/src/registry.rs：Builder/Registry 类型化列表和顺序
• codex-rs/ext/extension-api/src/state.rs：ExtensionDataInit/ExtensionData
• codex-rs/ext/extension-api/src/lib.rs：公开 API 边界
• codex-rs/core/src/session/session.rs：Session/Thread stores 创建