Agent Harness 深度研究报告

## 深度探讨：OpenAI Codex Harness 架构与实践 ### 1. 架构全景 Codex Harness 是 OpenAI 官方的生产级 Agent 运行时，设计理念是**"一个 Harness，多平台统一体验"**——无论你是用 CLI、IDE 插件还是 Web 界面，底层都是同一套 Harness。 ``` ┌─────────────────────────────────────────────────────────────┐ │ 客户端层 │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐ │ │ │Codex CLI│ │VS Code │ │JetBrains│ │Codex Desktop App│ │ │ │ │ │Extension│ │ Plugin │ │ │ │ │ └────┬────┘ └────┬────┘ └────┬────┘ └────────┬────────┘ │ │ └─────────────┴─────────────┴────────────────┘ │ │ │ │ │ JSON-RPC over stdio/WebSocket │ │ │ │ ├─────────────────────────┼────────────────────────────────────┤ │ App Server │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌──────────────┐ │ │ │ │ │Stdio Reader │ │Msg Processor│ │Thread Manager│ │ │ │ │ └─────────────┘ └─────────────┘ └──────────────┘ │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ │ ├─────────────────────────┼────────────────────────────────────┤ │ Harness 层 │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Firecracker microVM 沙箱（安全隔离的执行环境） │ │ │ │ ┌──────────────────────────────────────────────┐ │ │ │ │ │ Agent Loop → 工具调用 → 文件系统 → 命令执行 │ │ │ │ │ └──────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ### 2. 核心组件详解 #### 2.1 App Server：双向 JSON-RPC 协议 OpenAI 抛弃了传统的 REST API，采用**双向 JSON-RPC over stdio**： **为什么是 JSON-RPC？** - **有状态**：不像 REST 的无状态请求-响应，Agent 需要长时间保持连接 - **双向通信**：服务器可以主动推送事件（工具调用进度、流式输出） - **低开销**：JSONL 格式（每行一个 JSON），省去 HTTP 头部开销 **协议原语**： | 原语 | 含义 | 示例 | |------|------|------| | **Item** | 最小 I/O 单元 | 用户消息、Agent 消息、工具执行 | | **Turn** | 一轮工作 | 从用户输入到 Agent 完成响应 | | **Thread** | 会话容器 | 持久化的对话历史，可恢复 | **消息格式**： ```json // Request { "method": "thread/start", "id": 10, "params": { "model": "gpt-5.1-codex" } } // Response { "id": 10, "result": { "threadId": "t_abc123" } } // Notification（服务器主动推送） { "method": "tool/executing", "params": { "tool": "bash", "command": "npm test" } } ``` #### 2.2 Harness：Firecracker microVM 沙箱 每个 Codex 实例运行在独立的 Firecracker microVM 中： - **冷启动 < 125ms**：比传统 Docker 更快 - **内存开销 < 5MB**：每个沙箱轻量级 - **硬件加速**：可选 GPU 支持用于编译/测试 - **状态快照**：会话可序列化、暂停、恢复 **安全模型**： - 默认只读访问，需显式授权写操作 - 网络隔离，可配置允许的外联 - 文件系统命名空间隔离 #### 2.3 Agent Loop 内部 ``` 用户输入 ↓ ┌─────────────────────────────────────┐ │ 1. 意图理解（Intent Understanding） │ │ - 解析用户自然语言指令 │ │ - 确定任务类型（探索/编码/调试） │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ 2. 上下文加载（Context Loading） │ │ - 读取 AGENTS.md │ │ - 加载相关文件片段 │ │ - 注入工具描述 │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ 3. 规划（Planning） │ │ - 分解任务为子步骤 │ │ - 确定工具调用序列 │ │ - 生成执行计划 │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ 4. 执行循环（Execution Loop） │ │ while 任务未完成: │ │ - 调用工具 │ │ - 观察结果 │ │ - 决定下一步 │ │ - 流式返回进度 │ └─────────────────────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ 5. 验证（Verification） │ │ - 运行测试 │ │ - 类型检查 │ │ - 代码审查 │ └─────────────────────────────────────┘ ↓ 完成输出 ``` ### 3. Harness Engineering 实践 #### 3.1 AGENTS.md：活的约束系统 OpenAI 的突破性实践——把文档变成**可执行的约束**： ```markdown # Project: Codex App Server ## Overview High-performance agent runtime using JSON-RPC over WebSockets ## Architecture Types → Config → Repo → Service → Runtime → UI ## Constraints - Agents MUST NOT bypass dependency layers - All file writes MUST go through FileTool - Network calls MUST use approved domains list ## Tool Usage Patterns - Use `read` for files < 100 lines - Use `search` for finding symbols - Use `bash` for npm/pip commands only ## Common Failures - ❌ "Can't find module": Check if npm install was run - ❌ "Port already in use": Kill existing process first ``` **关键洞察**：AGENTS.md 不是一次性文档，而是**每次失败后的迭代更新**——Agent 遇到错误 → 人类分析根因 → 更新 AGENTS.md → 下次 Agent 自动避免。 #### 3.2 架构护栏：机械强制依赖层 ``` Types → Config → Repo → Service → Runtime → UI ↑ ↑ ↑ ↑ ↑ ↑ 基础类型 配置层 数据层 业务逻辑 运行时 界面层 ``` **实施方式**： - **自定义 Linter**：检查跨层导入 - **结构测试**：CI 中验证依赖流向 - **Agent 训练**：在 AGENTS.md 中强化约束 **效果**：100 万行代码的代码库，零架构漂移。 #### 3.3 可观测性驱动迭代 Agent 不是黑盒——**它自己能看日志**： ``` Agent 执行流程 ↓ 产生日志/指标/追踪 ↓ Agent 读取遥测数据 ↓ 自主复现 Bug ↓ 提出修复方案 ↓ 人类审查 PR ``` **遥测数据类型**： - **日志**：结构化日志（ERROR/WARN/INFO） - **指标**：延迟、吞吐量、错误率 - **追踪**：分布式追踪（OpenTelemetry） - **性能分析**：CPU/内存火焰图 ### 4. 状态管理：从 Stateless 到 Stateful #### 4.1 状态快照（State Snapshotting） ``` 场景：Agent 运行 2 小时后遇到限流 传统方式： - 连接断开 - 进度丢失 - 从头再来 Codex Harness： - 序列化 VM 状态 - 暂停连接 - 恢复时精确回到断点 - Agent 继续执行 ``` **实现细节**： - 内存状态 → 磁盘快照 - 文件系统 → 增量备份 - 网络连接 → 优雅重连 #### 4.2 会话生命周期 ``` 创建 Thread ↓ 开始 Turn（用户输入） ↓ Agent Loop 执行 ↓ 生成 Items（消息、工具调用、结果） ↓ Turn 完成 ↓ 可选：暂停（suspend） ↓ 可选：恢复（resume） ↓ 可选：归档（archive） ``` **持久化策略**： - 每 30 秒自动检查点 - 关键操作后立即持久化 - 支持显式 `save()` 调用 ### 5. 工具系统：从调用到编排 #### 5.1 内置工具集 | 工具 | 用途 | 安全级别 | |------|------|---------| | `read` | 读取文件内容 | 只读 | | `write` | 写入文件 | 需授权 | | `edit` | 精确编辑文件 | 需授权 | | `bash` | 执行 shell 命令 | 沙箱内 | | `search` | 代码搜索 | 只读 | | `git` | 版本控制操作 | 需授权 | #### 5.2 工具调用流程 ``` Agent 意图调用工具 ↓ Harness 拦截请求 ↓ 验证权限 ├─ 允许 → 继续 └─ 拒绝 → 返回错误 ↓ 在沙箱中执行 ↓ 捕获输出 ↓ 清理/格式化 ↓ 返回给 Agent ``` #### 5.3 MCP 集成 Codex Harness 支持 **Model Context Protocol**： ```json // mcp.json 配置 { "servers": { "notion": { "command": "npx", "args": ["-y", "@notionhq/mcp-server"], "env": { "NOTION_TOKEN": "${NOTION_TOKEN}" } }, "github": { "command": "npx", "args": ["-y", "@github/mcp-server"] } } } ``` **Token 成本优化**： - 原始：所有 MCP 工具描述 ~134K tokens - Tool Search 改进后：~5K tokens（按需加载） ### 6. 性能与成本数据 #### 6.1 OpenAI 内部实验结果 | 指标 | 数值 | |------|------| | 代码行数 | 1,000,000+ | | 手写代码 | 0 行 | | 团队规模 | 3 人 | | 开发周期 | 5 个月 | | PR 速率 | 3.5 PR/人/天 | | 速度提升 | ~10x（相比手写） | #### 6.2 关键发现 **瓶颈不是模型，是 Harness**： - 前期：专注提示工程 → 进展缓慢 - 后期：专注 Harness 建设 → 速度起飞 **吞吐量随团队规模增长**： - 传统：团队变大 → 协调成本 ↑ → 速度 ↓ - Harness：团队变大 → Agent 并行 ↑ → 速度 ↑ ### 7. 对比：Codex vs Claude Code | 维度 | Codex Harness | Claude Code | |------|---------------|-------------| | **协议** | JSON-RPC over stdio | 私有协议 | | **沙箱** | Firecracker microVM | Docker | | **状态管理** | 显式 Thread/Turn/Item | 隐式会话 | | **上下文策略** | AGENTS.md 动态反馈 | CLAUDE.md + 检查点 | | **工具数量** | 20+ 内置 | 20 内置 | | **MCP 支持** | 是 | 是 | | **开源** | 否（SDK 可用） | 否 | | **Web 界面** | 有 | 无 | | **多平台** | CLI/IDE/Web | CLI/IDE | ### 8. 使用建议 #### 8.1 何时选择 Codex Harness？ ✅ **适合**： - 大规模代码库（10万+ 行） - 需要多平台统一体验 - 团队已用 OpenAI 生态 - 需要状态持久化和恢复 - 需要细粒度安全控制 ❌ **不适合**： - 简单的一次性脚本 - 需要完全开源方案 - 深度依赖 Claude 模型 - 预算敏感（Codex 调用成本较高） #### 8.2 起步检查清单 ``` □ 创建 AGENTS.md，描述项目结构和约束 □ 配置 mcp.json，接入所需工具 □ 设置 CI 流水线，自动验证 Agent 输出 □ 建立内部评估基准（参考 Cursor Bench） □ 配置可观测性（日志、指标、追踪） □ 定义安全策略（允许的工具、文件访问范围） ``` ### 9. 未来展望 **Harness as a Service (HaaS)**： - OpenAI 正在将 Codex Harness 云服务化 - 开发者只需关注业务逻辑 - Harness 层由 OpenAI 托管和优化 **Agent 即服务**： ```python # 未来可能的 API from openai import Agent agent = Agent( model="gpt-5.1-codex", harness="production", # 选择 Harness 配置 tools=["git", "bash", "file"], constraints={"max_turns": 50} ) result = agent.run("重构用户认证模块") ``` --- *深入探讨：小凯* *基于 OpenAI 官方 Harness Engineering 博客及社区分析*