雨 雨天小六

读懂 Codex（7.38）：Tool、MCP、TurnInput 与 TurnItem Contributor 的接入点

· 更新于 2026-08-02 · 专栏：读懂 Codex

#Codex#Agent Runtime#Multi-Agent#Extension#软件架构

Extension API 把“拥有能力”和“观察/改写结果”拆开：ToolContributor 产出 Step 绑定的原生执行器，McpServerContributor 叠加 server 配置，TurnInputContributor 加模型输入，TurnItemContributor 只在解析后按顺序后处理 Item。

本节只研究“Extension 的能力和数据面接入”。输入是 各 scope stores、Step capability snapshot、ToolCall/TurnItem，状态由 四类 contributor 与 Core adapters 持有，成功输出为 工具、MCP overlay、上下文 fragment 或已修改 TurnItem。相邻章节中看起来相似的对象如果由不同组件拥有，就不能用一个布尔状态替代。

先确定边界和状态所有者

问题本节答案
谁发起各 scope stores、Step capability snapshot、ToolCall/TurnItem
谁拥有可变状态四类 contributor 与 Core adapters
成功产物工具、MCP overlay、上下文 fragment 或已修改 TurnItem
不在本节内Extension 的能力和数据面接入之外的上游产品策略和下游业务实现

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

端到端调用链

  1. Step 调各 contributor
  2. 合并 MCP overlays/原生 tools
  3. TurnInput 转 ContextualUser items
  4. ToolRouter 执行
  5. TurnItem contributors 顺序后处理
Tool、MCP、TurnInput 与 TurnItem Contributor 的接入点的端到端机制流程，展示Step 调各 contributor、合并 MCP overlays/原生 tools、TurnInput 转 ContextualUser items、ToolRouter 执行、TurnItem contributors 顺序后处理
图 7.38-1：Step 调各 contributor → 合并 MCP overlays/原生 tools → TurnInput 转 ContextualUser items → ToolRouter 执行 → TurnItem contributors 顺序后处理。图中每条箭头都表示下一层只接收上一层已经确认的状态。

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

源码机制拆解

ToolContributor 可按 Step 重新绑定

tools_for_step 接收 session/thread/step stores，默认回退到 tools；Executor 随当前 Step tool plan 收集，不应保存上个 Step 的动态环境引用。

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

MCP overlay 后项可替换前项

Contributor 用稳定 id 记录 provenance，返回 Set/Remove/SelectedPlugin/SelectedPluginPackage；Host 给每个 action 全局 contribution_order，相同 name 的后项拥有最终配置。

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

TurnInput 只贡献自己拥有的模型输入

输入含 turn id、用户输入和环境列表，输出是 ContextualUserFragment；它不能直接改原始用户输入或 Core Prompt 其他权威层。

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

TurnItem 后处理失败是软失败

Contributor 可修改解析后的 TurnItem 并返回 Result；Core 逐个执行，Err 只 warning 后继续后续 contributor和事件发射，不让观察扩展摧毁整个 Turn。

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

Python 风格伪代码

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

async def build_extension_step(registry, stores, step):
    mcp = OrderedOverlayMap()
    for contributor in registry.mcp_server_contributors:
        for action in await contributor.contribute(step.mcp_context):
            mcp.apply(action, owner=contributor.id)

    tools = []
    for contributor in registry.tool_contributors:
        tools.extend(contributor.tools_for_step(stores.session, stores.thread, stores.step))
    return mcp, tools

async def finalize_turn_item(registry, stores, item):
    for contributor in registry.turn_item_contributors:
        try: await contributor.contribute(stores.thread, stores.turn, item)
        except ContributionError as error: warn(error)
    return item

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

失败、取消与恢复

Tool、MCP、TurnInput 与 TurnItem Contributor 的接入点的三类失败分支、可观察结果和恢复责任
图 7.38-2：失败不会抹掉已经提交的状态；每条分支都由拥有该状态的组件执行恢复或补偿。
故障点已发生的状态可观察结果恢复责任
两个 MCP contributor Set 同名两项都有 provenance/order后 action 胜出只贡献自己拥有的 name
ToolExecutor 同名冲突Core tool plan 需要去重冲突按 Registry 规则拒绝/首项生效扩展命名空间化
TurnItem contributor 返回 Err前面修改可能已发生warning+继续实现应让单项修改原子/可重复

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

并发与一致性不变量

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

设计思路与代价

本节设计保护的核心不变量是：Extension API 把“拥有能力”和“观察/改写结果”拆开：ToolContributor 产出 Step 绑定的原生执行器，McpServerContributor 叠加 server 配置，TurnInputContributor 加模型输入，TurnItemContributor 只在解析后按顺序后处理 Item。代价是同一个功能会跨越地址、配置、Session、队列、存储或扩展适配层，测试也必须覆盖正常、并发和中途失败。更短的单体实现虽然容易演示，却无法区分“存在、已加载、正在运行、可恢复、已关闭、模型可见”这些彼此独立的事实。

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

源码与测试证据

位置能证明什么
codex-rs/ext/extension-api/src/contributors.rsTool/TurnInput/TurnItem/MCP traits
codex-rs/ext/extension-api/src/contributors/mcp.rsMCP overlay variants/context
codex-rs/core/src/mcp.rsContributor overlay order
codex-rs/core/src/tools/router.rsExtension ToolExecutor 收集
codex-rs/core/src/stream_events_utils.rsTurnItem 软失败处理
测试/可执行检查覆盖重点预期
codex-rs/ext/extension-api/tests/registry.rs正常、边界与状态转换应与本节不变量一致
codex-rs/core/src/tools/registry_tests.rs失败、并发或兼容行为应与本节不变量一致

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

Mini Codex 复刻建议

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

本节结论

Extension API 把“拥有能力”和“观察/改写结果”拆开：ToolContributor 产出 Step 绑定的原生执行器，McpServerContributor 叠加 server 配置，TurnInputContributor 加模型输入，TurnItemContributor 只在解析后按顺序后处理 Item。 掌握这一点后，再看相邻模块时就能判断它是在改变身份、运行状态、模型可见上下文、外部能力，还是仅提供观察快照。

阅读导航

上一节：ContextContributor 的 Prompt Slot、Turn Context 与 WorldState Section · 下一节：Thread 与 Turn Lifecycle Contributor 的调用时机和状态清理

源码依据

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

评论

← 返回文章列表