Harness Engineering¶

深入浅出 Harness Engineering——逐行剖析 OpenAI Codex 源码

Harness 直译是"挽具"——给马套上的那套缰绳、嚼子、轭具。这词在今天有点冷僻:毕竟大家都不骑马了。但它恰恰是最贴切的比喻。

一匹烈马,力气再大,没有挽具就是信马由缰:横冲直撞、使不上劲,甚至尥蹶子把车掀翻。套上挽具,同一匹马的蛮力,才变成可控、可用、能拉着车往你要的方向走的功。

大模型就是这匹马。它越来越强,可本身只会"想"、不会稳定地"做"——你让它干活,它给你一段看着对的答案,一跑就错,来回十几轮还收不了尾。真正让它可靠地把活干完的,是包在它外面的那一层:工具、约束、上下文、反馈、长程状态、运行时。这层"把模型的蛮力收束成可用功"的东西,英文叫 harness,中文正是挽具。

一句话立靶:模型是商品,harness 是杠杆。 模型谁都买得到、能力还在飞涨;真正拉开差距的,是你给它套上一副多好的挽具。

模型是马，harness 是挽具

图：模型是马，harness 是挽具——把蛮力变成可用功。

这本书做一件市面上很少有人做的事：带你逐行读一个生产级 harness 的源码。我们只选一个解剖标本——OpenAI 官方开源的 Codex（Rust 实现 codex-rs）——把每一个 harness 原语都落到真实代码，按"失败 → 机制 → 源码 → 抽象"四步，一层层拆开。

这本书写给谁¶

适合：

想真正搞懂"怎么让 AI agent 可靠地把活干完"，而不只是搭个能跑的 demo 的工程师；
正在做（或想做）coding agent、AI 应用、agent 平台的人——你会在书里看到生产级 harness 每一层的真实取舍；
盯着 Harness / Agent / FDE 这类新岗位、想照着任职要求补齐能力的人（第 1 章就是一份"JD 拆解"）；
喜欢"读源码学原理"那一挂——不满足于"会用"，想看清一个生产级系统"为什么这么设计"。

前置： 不要求你会 Rust，能跟着读代码结构即可；有基本工程背景、用过 LLM API 或 Claude Code / Cursor 这类工具，会读得更顺。

这本书不是： 不是"30 分钟搭个 agent"的速成教程，也不是框架 API 手册——它讲的是让不确定的模型变得可靠的那一层，那层东西，恰恰最难、也最值钱。

怎么读¶

把 harness 想象成一圈圈包在模型外面的同心层，由内到外：循环 → 上下文 → 工具 → 能力（Skills/MCP）→ 约束安全 → 长程状态 → 多代理 → 评估观测 → 运行时。本书第 3–14 章就是从里到外逐层拆，第 15 章再把它们装回去，讲怎么造你自己的整套。

不要求你会 Rust——只需能跟着读结构。建议把 Codex 仓库 clone 下来对照着读。

目录¶

本书正在连载

全书规划 15 章 + 附录，章节将陆续放出，敬请期待：

导论：什么是 Harness Engineering，为什么是现在
Harness 解剖学：model + harness 与 Codex 全景架构
Agent 循环：一次 turn 的生命周期
上下文工程：从片段拼装到 AGENTS.md
工具层：注册表、路由与工具设计
代码即工具：apply_patch 与 code mode
Skills：可复用能力与渐进式加载
MCP 与外部工具生态
安全自治：策略、沙箱、权限、审批与守护
长程作业：压缩、目标与记忆
多代理编排：从 orchestrator 到 agent graph
评估与自我验证：review 与 generator–evaluator
可观测性与遥测：让 agent"看见"系统
运行时与协议：app-server 与 exec
工程实践与未来：造你自己的 harness

附录　Rust 速查表：写给不熟 Rust 的读者（用 Python 类比，一表看懂书里的 Rust 记号）

关于版本

书中引用的 Codex 源码路径以写作时的主干版本为准；Codex 在持续演进，落地时建议以你 clone 到的版本"现读现引"。

版权与许可

Harness Engineering¶

这本书写给谁¶

怎么读¶

目录¶

留言