当前实现不依赖一个泛化的 tools/list_changed 推送链：普通 dirty refresh 为后续 Step 发布新 ConnectionSet；同一 ConnectionSet 内的 Codex Apps hard refresh 才递增 Catalog Revision，并让旧 PreparedCall 在副作用前失败。
本节只研究“MCP 目录的 Step 一致性”。输入是 dirty runtime config、server tool lists、当前 sampling step，状态由 McpRuntime、ToolCatalog、McpBinding、PreparedMcpCall 持有，成功输出为 不可变工具目录及与其配套的调用能力。相邻章节中看起来相似的对象如果由不同组件拥有，就不能用一个布尔状态替代。
先确定边界和状态所有者
| 问题 | 本节答案 |
|---|---|
| 谁发起 | dirty runtime config、server tool lists、当前 sampling step |
| 谁拥有可变状态 | McpRuntime、ToolCatalog、McpBinding、PreparedMcpCall |
| 成功产物 | 不可变工具目录及与其配套的调用能力 |
| 不在本节内 | MCP 目录的 Step 一致性之外的上游产品策略和下游业务实现 |
这张表的用途不是复述名词，而是约束实现顺序：校验必须发生在副作用之前；已经提交的状态只能由原所有者撤销；只读投影不能反过来成为控制权威。
端到端调用链
- dirty invalidation 串行 refresh
- 发布新 ConnectionSet
- Step capture binding/specs
- 可选 hard refresh 墕 revision
- PreparedCall 校验/持有 revision
这条链里至少有三种时间尺度：配置或身份在 Thread 创建时冻结，Turn 内状态由 Session 串行协调，Step 级目录与能力在每次模型采样前重新捕获。若把后一个时点的新状态拿去解释前一个时点已经发出的调用，就会产生跨代错误。
源码机制拆解
刷新被信号量串行化
多个配置/插件变化可以同时标 dirty，但 Session MCP refresh 用 semaphore 合并并发重算，避免交错发布两代 capability roots 和 server configs。
这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 McpRuntime、ToolCatalog、McpBinding、PreparedMcpCall 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。
Binding 同时冻结目录和 client
一次 sampling step 从 runtime 捕获 McpBinding；模型看到的 callable names、metadata 与之后 prepare_call 使用的 exact ready client 来自同一 catalog。普通 runtime refresh 会发布新的 ConnectionSet，旧 Binding 继续持有旧 Set，不会被新配置偷换。
这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 McpRuntime、ToolCatalog、McpBinding、PreparedMcpCall 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。
Revision 针对同一 Set 的 hard refresh
hard_refresh_codex_apps_tools_cache 在原 ConnectionSet 内获取 refresh lock，抓取新目录后拿 revision 写锁，发布 override 并递增 revision。它与整体 runtime swap 是两种不同更新。
这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 McpRuntime、ToolCatalog、McpBinding、PreparedMcpCall 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。
PreparedCall 在副作用前校验并持锁
调用先取得 revision 读锁并比较捕获值；不一致就连 preparation 闭包都不执行。值一致时读锁覆盖不可逆准备和实际 call，使 hard refresh 必须等本次调用结束。
这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 McpRuntime、ToolCatalog、McpBinding、PreparedMcpCall 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。
下一 Step 才看到新目录
插件安装或依赖更新触发普通 runtime refresh，后续 step 重新 build tool plan。已发给模型的当前请求不能被动态改写。
这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 McpRuntime、ToolCatalog、McpBinding、PreparedMcpCall 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。
Python 风格伪代码
下面的伪代码提炼状态机与错误顺序，不逐行翻译 Rust，也不假装 Python 对象具有 Rust 的所有权保证：
async def refresh_if_dirty(session):
async with session.mcp_refresh_semaphore:
if not session.mcp_dirty.take():
return
projection = await recompute_mcp_projection(session)
connection_set = await build_connection_set(projection)
binding_source = await connection_set.capture_tool_catalog()
session.mcp_runtime.publish(connection_set, binding_source)
async def execute_from_step(step, server, tool, arguments):
prepared = await step.mcp_binding.prepare_call(server, tool)
async with prepared.catalog_revision_source.read_lock() as current:
if current != prepared.catalog_revision:
raise StaleMcpBinding()
arguments = await prepare_irreversible_arguments(arguments)
return await prepared.exact_client.call(tool, arguments)阅读这段伪代码时要检查三件事：第一，输入是否在副作用前完成规范化；第二，异步等待是否仍携带原 Thread/Turn/Step 身份；第三，失败后究竟释放了什么、又保留了什么。只写快乐路径会把本节最重要的一致性条件删掉。
失败、取消与恢复
| 故障点 | 已发生的状态 | 可观察结果 | 恢复责任 |
|---|---|---|---|
| 刷新中 required server 未就绪 | 旧 binding 仍可被旧 Step 使用 | 新 binding 构建失败/等待 | 后续重试 |
| 同一 Set hard refresh 后旧调用才到达 | call 绑定旧 revision | revision mismatch 且不运行 preparation | 模型在新 Step 重新发现 |
| 并发 dirty 通知 | 只需一代最终投影 | semaphore 串行合并 | 不并发 swap 多代 |
取消不自动等于回滚，列表不自动等于权威存储，模型看见的描述也不自动等于已经获准执行。对于已经建立的 Thread、写入的 Edge、入队的 Mailbox、安装的插件或外部工具副作用，必须由相应所有者执行显式关闭、补偿或保留。
并发与一致性不变量
- 同一身份不能在并发路径中被重复预留或重复注册；若允许幂等重试，幂等键必须是稳定路径、ThreadId、request id 或 catalog revision，而不是展示名称。
- 一次模型采样看见的 Prompt、工具目录和执行入口必须来自同一个 Step 快照；刷新只影响后续 Step。
- Watch/Activity/事件是通知机制，不是状态本身。被唤醒后必须重新读取 Registry、Session、Mailbox、Store 或 Binding 的权威值。
- 失败路径不得“为了干净”删除仍可恢复的历史；同样也不得把只剩历史的对象伪报成当前仍驻留运行。
设计思路与代价
本节设计保护的核心不变量是：当前实现不依赖一个泛化的 tools/list_changed 推送链：普通 dirty refresh 为后续 Step 发布新 ConnectionSet；同一 ConnectionSet 内的 Codex Apps hard refresh 才递增 Catalog Revision，并让旧 PreparedCall 在副作用前失败。代价是同一个功能会跨越地址、配置、Session、队列、存储或扩展适配层，测试也必须覆盖正常、并发和中途失败。更短的单体实现虽然容易演示，却无法区分“存在、已加载、正在运行、可恢复、已关闭、模型可见”这些彼此独立的事实。
设计动机部分是根据生产类型、调用顺序和测试行为归纳；源码可直接证明的是字段、分支、状态所有者和失败结果。文章不会把推断写成服务端或产品层的未公开事实。
源码与测试证据
| 位置 | 能证明什么 |
|---|---|
codex-rs/codex-mcp/src/binding.rs | Binding 与 PreparedCall |
codex-rs/codex-mcp/src/connection_manager/tool_catalog.rs | 目录捕获和 refresh revision |
codex-rs/codex-mcp/src/runtime.rs | runtime publish/capture |
codex-rs/core/src/session/mcp.rs | dirty refresh 串行化与 Step binding |
| 测试/可执行检查 | 覆盖重点 | 预期 |
|---|---|---|
codex-rs/codex-mcp/src/binding_tests.rs | 正常、边界与状态转换 | 应与本节不变量一致 |
codex-rs/codex-mcp/src/connection_manager_tests.rs | 失败、并发或兼容行为 | 应与本节不变量一致 |
当前环境没有 Cargo，本轮不伪报 Rust 测试执行；验证由锁定提交下的源码—测试静态对读、源文件存在性检查、Mermaid 渲染、Astro 生产构建和公开页面检查组成。
Mini Codex 复刻建议
Mini Codex 应先复刻本节的协议不变量：明确状态所有者、稳定身份、可回滚预留、同 Step 快照、超时/取消和单一终态。平台沙箱、远程 Executor、OAuth、Backend App Route 或第三方 MCP Server 的安全性质不能由一个本地 Python mock 证明，适配器只能验证调用顺序和故障处理。
本节结论
当前实现不依赖一个泛化的 tools/list_changed 推送链：普通 dirty refresh 为后续 Step 发布新 ConnectionSet；同一 ConnectionSet 内的 Codex Apps hard refresh 才递增 Catalog Revision，并让旧 PreparedCall 在副作用前失败。 掌握这一点后，再看相邻模块时就能判断它是在改变身份、运行状态、模型可见上下文、外部能力，还是仅提供观察快照。
阅读导航
上一节：MCP ConnectionManager 的并发启动、连接复用、认证与关闭 · 下一节：MCP Resource、Resource Template 与 Elicitation 的边界
源码依据
本文基于锁定提交 fe01054a28fa4bd04716d9ceadb410f2443a50ce 的生产代码和相邻测试静态核对。关键入口如下：
- codex-rs/codex-mcp/src/binding.rs：Binding 与 PreparedCall
- codex-rs/codex-mcp/src/connection_manager/tool_catalog.rs：目录捕获和 refresh revision
- codex-rs/codex-mcp/src/runtime.rs：runtime publish/capture
- codex-rs/core/src/session/mcp.rs：dirty refresh 串行化与 Step binding
评论
登录后即可评论