Codex Harness架构设计拆解：从模块化解耦到上下文压缩记忆体系

在AI Agent开发领域，Harness作为连接大模型与实际应用的核心中间件，其架构设计直接影响着Agent的能力边界与运行效率。Codex作为OpenAI开源的CLI工具，其Harness架构经历了多次重大迭代，尤其是在上下文压缩与记忆体系方面推出了极具创新性的设计。本文将从模块化解耦、事件驱动模型、三层循环执行机制，以及全新的Token Budget跨窗口通信方案等维度，系统性地拆解Codex Harness的核心设计思路，为Agent开发者和架构师提供有价值的实践参考。

模块化设计：118个Crate的解耦艺术

Codex Harness的源码包含约118个Crate成员，这种高度模块化的设计在同类开源项目中颇为罕见。以codex-core为代表的顶层模块遵循严格的设计约束，AGENTS.md中明确要求开发者"Resist adding code to codex-core"，即禁止向核心模块随意添加代码。这一强制解耦策略带来显著优势：小范围修改仅需编译对应Crate，大幅缩短了开发迭代周期；同时各模块职责边界清晰，实现了高内聚低耦合的设计目标。codex-protocol负责数据协议定义，codex-api封装模型API层，codex-app-server则将核心逻辑统一暴露为JSON-RPC接口，使TUI命令行与桌面端得以复用同一套底层实现。

事件驱动：Op与Event的双向通信

Codex Harness采用事件驱动架构，但与DeepSeek Harness通过广播监听实现插件协同的方式不同，Codex构建了Op与Event的双向通信模型。从客户端到Agent方向，用户操作被封装为Op提交，包含TurnInput、Interrupt、Compact、Shutdown等类型；从Agent到客户端方向，每个模型响应都会生成对应的Event记录，如TurnStarted、TurnComplete、AgentMessage、ExecCommandBegin等。这种设计使得Agent的每个行为反应都有明确的事件溯源，整个运行流程可追踪、可调试，同时保持了客户端与服务端的松耦合。

三层循环与工具并发的工程实践

Codex的Agent运行机制由三层嵌套循环构成：最外层是Task Loop处理用户具体需求，中间层是Turn Loop对应单轮对话（含上下文压缩），最内层是Sampling Loop代表单次模型请求或工具调用。在工具执行层面，Codex使用FuturesOrdered队列实现并发执行，底层并行调用A、B、C三个工具，但返回结果时严格按原顺序拼装。这种并行执行与有序拼装的组合，既保证了执行效率，又维护了模型上下文的确定性，避免工具调用乱序导致模型理解偏差。World State设计通过Diff机制优化上下文管理，环境变更时仅注入增量补丁而非全量重读，对Prefix KV Cache友好，有效降低Context Window消耗。

Token Budget：跨窗口记忆的范式革新

Codex在2024年8月推出的Token Budget方案，代表了上下文压缩记忆体系的范式革新。传统压缩依赖Summary模型猜测重要信息，容易遗漏关键上下文；Token Budget则让主Agent模型自主管理记忆，窗口满时创建全新Context Window并获得递增ID。新窗口通过Thread Hint获取约4000字节背景提示，通过Notes（虚拟文件系统笔记）实现窗口间异步通信，上一窗口持续记录任务进展，下一窗口按需读取；History则存储完整Agent Trace供回溯检索。这套机制不同于长期记忆的全局巩固，仅服务于单Session内跨Context Window的状态衔接，两者正交互补，共同构成完整的记忆体系。

Codex Harness的架构演进展示了一个核心趋势：Agent的上下文管理正从简单的压缩总结，向精细化的状态衔接与分层记忆演进。其模块化设计保障了工程可维护性，事件驱动模型提供了运行可观测性，而Token Budget则重新定义了窗口边界内的任务状态传递方式。这些设计思路对于构建生产级Agent系统具有重要借鉴价值，开发者可结合自身场景选择性吸收其核心理念。