读懂 Codex（4.25）：Prompt Cache Key 和稳定前缀设计

Codex 的 prompt_cache_key 默认不是 Prompt 内容哈希，而是 Responses metadata 中的 Session ID；Guardian 等特殊会话可以覆盖。Key 只划定缓存归属，能否命中仍取决于请求是否拥有稳定而相同的前缀。因此真正的缓存设计散布在 History 顺序、增量 World State 和稳定合成 ID 中。

Key 的选择很简单

ModelClient 构造请求时调用 prompt_cache_key(responses_metadata)：有 override 用 override，否则复制 session_id。同一 Thread 的请求保持归组，特殊 reviewer 可按父 Thread 共享或隔离。

def prompt_cache_key(client, metadata):
    return client.override_key or metadata.session_id

稳定前缀由多个不变量共同维护

History 永远从旧到新追加；World State 无变化时不重复，变化时只追加差异；缺失工具输出的合成 ID 由源 item ID 稳定派生；内部 chat metadata 比较时可忽略。它们都减少语义未变却字节变化的请求前缀。

def next_prompt(previous, state_diff, new_items):
    stable_prefix = previous.items
    normalized_diff = deterministic_render(state_diff)
    return stable_prefix + normalized_diff + new_items

Responses WebSocket 是否能增量发送还要求非 input 字段全部匹配，包括 model、instructions、tools、reasoning、service tier、cache key 和 text controls。Cache Key 相同只是必要条件之一。

不能为缓存牺牲正确性

History replace、rollback、压缩和 World State 基线失效会重建前缀。保留过期权限只为命中缓存属于错误优化。稳定性必须来自确定性渲染和真实无变化，而不是隐藏状态更新。

源码与测试锚点

• codex-rs/core/src/client.rs::prompt_cache_key。
• responses_request_properties_match：增量请求属性集合。
• context_manager/normalize.rs::synthetic_output_id：稳定 prompt-only ID。
• guardian/review_session.rs：特殊 override。