Codex Harness 核心流程分析

项目定位

Codex Harness 是 OpenAI 开发的生产级 Agent 运行时框架，Apache-2.0 协议开源，Rust 核心（codex-rs）+ TypeScript/Python SDK 双栈。它驱动 Codex App、CLI 和 VS Code 插件的底层执行框架，管理对话状态、工具调用、沙箱执行、流式输出和人工审批。核心理念：Harness 是 Agent 的操作系统——模型只是计算单元，Harness 负责记忆、工具、审批、沙箱、并发、可观测性。

五部分核心组件

Codex Harness 的核心组件可以分为 5 个部分：

1. 上下文工程：Context Compaction（智能压缩长上下文，保留关键推理信息，非简单文本摘要）+ Retained Reasoning（保留中间推理痕迹供模型回溯）+ 结构化上下文管理替代杂乱长上下文拼接
2. 工具/插件系统：MCP 集成（支持应用自有 MCP 服务，打通业务数据与操作）+ Skills 框架（可复用 Skill 包）+ Hooks 生命周期钩子 + model-provider 抽象层（支持任意 OpenAI 兼容端点）
3. 状态持久化：Thread（完整对话会话，可 fork/resume）+ Turn（单轮交互）+ Item（Turn 内原子事件）+ thread-store/history 持久化存储
4. 权限/安全模型：跨平台沙箱隔离（linux-sandbox/windows-sandbox-rs）+ execpolicy 执行策略 + 审批机制（Human-in-the-loop，高风险操作暂停等待确认）+ 三层审批策略（auto/manual/suggest）
5. 可观测性和审计：app-server JSON-RPC 流式事件（实时看到 AI 在做什么）+ 中途打断能力 + codex agents 仪表盘（交互式 Agent 管理界面）

一次完整请求流程

用户通过 Codex App、CLI（codex exec）、SDK 或 app-server 发起请求。

第一步：构建系统提示词。 组装系统指令、工具定义、技能描述等静态内容。静态内容放在 Prompt 前部，保证每轮都能命中 KV Cache，降低推理成本。

第二步：Agent Loop 启动。 标准化 Agent 循环：接收用户输入 → 构造 Prompt → 发送给模型推理 → 拿到响应。响应往往不是最终答案，而是一次工具调用（如”运行这个 shell 命令并告诉我结果”）。

第三步：工具调用执行。 Harness 执行工具调用：读写文件、运行 shell 命令、执行测试、调用 linter 和类型检查器等。工具调用结果追加到 Prompt 中，再次查询模型。这个循环可能重复几十次，直到模型产出给用户的最终消息。

第四步：沙箱隔离。 工具执行在沙箱中进行。codex-rs 包含跨平台沙箱实现：linux-sandbox（内核级隔离）、windows-sandbox-rs（Windows 沙箱）。execpolicy 控制执行策略——哪些命令可以运行、哪些文件可以访问、哪些网络可以连接。

第五步：人工审批。 高风险操作（如删除文件、执行危险命令、访问敏感数据）暂停并等待人类确认。审批策略分三档：auto（自动批准）、manual（必须人工确认）、suggest（建议但可自动执行）。v0.149.0 修复了 approval profile 在 resumed/forked 线程中静默回退的 bug。

第六步：上下文压缩。 当上下文窗口填满时，Context Compaction 将历史编码为更小的表示。不是简单的文本摘要——保留关键推理信息（retained reasoning），让模型能回溯之前的思考过程。ARC-AGI-3 基准测试中，仅靠 retained reasoning + context compaction 两项优化，GPT-5.6 Sol 得分从 13.3% 跃升至 38.3%，输出 token 消耗降至原来的 1/6。

第七步：流式事件推送。 app-server 通过 JSON-RPC 协议流式传输事件：用户消息、推理步骤、Shell 命令、文件编辑、工具调用结果。支持中途打断（turn/interrupt）。

第八步：会话持久化。 Thread（完整对话）包含多个 Turn（单轮交互），每个 Turn 包含流式 Item 序列（原子事件）。Thread 支持 fork（分叉新路径）和 resume（恢复历史会话）。

三层集成接口

Codex Harness 提供三层接入方式，覆盖从脚本到产品的全场景：

第一层：codex exec（CI 脚本 / 非交互任务）。 最轻量接入，一条 CLI 命令完成自动化任务。适合 CI/CD 流水线、批量脚本、后台一次性作业。执行完毕自动退出并返回结构化输出。

第二层：Codex SDK（程序化 Agent 编排）。 TypeScript/Python 双接口，在应用代码中编程式启动、恢复、流式编排 Codex 任务。支持 thread/fork（分叉会话）、thread/resume（恢复历史会话）、turn/interrupt（中断当前轮次）。v0.149.0 新增 max/ultra 推理强度控制。

第三层：Codex app-server（持久会话 + 流式事件 + 审批）。 为产品级接入设计的进程间通信层。基于 JSON-RPC 2.0，支持 stdio（默认）、Unix socket、WebSocket（实验性）三种传输方式。驱动 VS Code 插件和 Codex Desktop App 的运行时。

关键设计决策

1. Rust 核心 + TypeScript SDK 双栈。 codex-rs（约 120 个 crate）处理所有性能敏感路径（执行调度、沙箱、TUI 渲染、传输层）。TypeScript/Node.js 层保留为上层接口。资源占用和稳定性显著提升。

2. Retained Reasoning + Context Compaction。 不是简单截断或摘要——保留中间推理痕迹，让模型能回溯之前的思考过程。这是 Harness 设计带来 3 倍效果提升的核心原因。

3. app-server 协议自建。 OpenAI 评估后拒绝用 MCP 承担 app-server 角色——MCP 面向工具的”请求-响应”模型无法表达流式 diff、多步审批流和持久会话状态。因此自建了 app-server 协议。MCP 负责把外部工具接入 Codex，app-server 负责把客户端接入 Codex，两者分工共存。

4. Thread/Turn/Item 三层会话模型。 Thread（完整对话）→ Turn（单轮交互）→ Item（原子事件）。支持 fork、resume、interrupt，构建完整的多轮 Agent 交互产品。

5. 审批策略三档。 auto（自动批准所有操作）、manual（必须人工确认）、suggest（建议，不阻塞）。CI 场景用 auto，生产场景从 suggest 开始逐步过渡。

6. 模型提供方抽象。 model-provider 模块支持任意 OpenAI 兼容端点。可以通过修改 base_url 接入 DeepSeek、Qwen、Kimi 等任意兼容模型。

7. 开源边界清晰。 已开源：Codex CLI、SDK、app-server、codex exec、Skills、通用云环境。未开源：VS Code/JetBrains IDE 插件、Codex 网页版、云端托管产品、模型本身。

与 DeepSeek Harness 的对比