《Harness Engineering 101》从零搭建 AI 智能体，把 LLM 当大脑、Harness 当身体
Harness Engineering 101: The LLM is the brain, the harness is the body
作者 Isuru Wijesiri 在 GitHub 开源《Harness Engineering 101》教程，以 16 章从零搭建一个约 300 行 Python 玩具智能体，把 LLM 当大脑、Harness 当身体。
用一个 300 行的 Python 玩具智能体把主流 Agent 框架共用的设计取舍拆成 16 章，读者可以把这套搭法迁移到自己的项目。
LLM 是大脑，harness 是身体。
1.0 版 — 2026 年 9 月。
一个关于从第一性原理构建 AI 智能体的博客系列，以书的形式出版。
📖 在线阅读：https://isuruwijesiri.com/harness-engineering-101/
LLM API 是无状态的。每一轮对话，你都要把整个会话作为一个 JSON 数组发送出去，然后得到返回的文本。Harness 是构建、维护并保护这个数组的程序。整个领域所谓的"智能体"，不过是对这个循环的一组补丁，而每个补丁之所以存在，都是因为某个具体的东西坏了。本系列围绕这一条主线展开 16 章，并随着章节推进，用普通 Python 逐步搭建出一个约 300 行的玩具智能体。
这些模式在 One Code 中得到了完整实现，One Code 是一个基于 pi 构建的开源编程智能体。
渲染后的书最好通过上面的链接在线阅读。如果你想直接在 GitHub 上阅读源码，请按顺序阅读下面的章节。完整序言见本书着陆页。
阅读顺序
每一章结构都相同：失败、最小化补丁、补丁的代价。
第一部分 — 线缆层（没有什么是魔法）
| # | 章节 | 它要修补的失败 |
|---|---|---|
| 1 | 它只是一个 JSON 数组 | "我到底怎么跟这东西说话？" |
| 2 | 大脑：一个 next-token 黑盒 | "它为什么会这样表现？" |
| 3 | 工具：映射成函数的 JSON | 大脑无法触碰世界 |
| 4 | 智能体循环 | 一次工具调用不够 |
| 5 | 缓存：为什么顺序至关重要 | 重复发送数组代价太高 |
第二部分 — 跑得更久（数组承压）
| # | 章节 | 它要修补的失败 |
|---|---|---|
| 6 | 上下文是预算，不是口袋 | 窗口会被填满 |
| 7 | 子智能体：分叉上下文 | 一个数组装不下所有工作 |
| 8 | 引导运行中的循环 | 大脑在任务中途跑偏 |
| 9 | 后台任务与时间 | 循环是同步的，世界不是 |
第三部分 — 生态系统（为你已知的事物命名）
| # | 章节 | 它要修补的失败 |
|---|---|---|
| 10 | 每个框架都是第 1 章的包装 | 抽象焦虑 |
| 11 | 扩展身体：MCP、Skills、Deferred Loading、Hooks | 能力装不进数组 |
| 12 | 调试数组 | 看不见的 prompt 修不了 |
第四部分 — 信任、领域与数据
| # | 章节 | 它要修补的失败 |
|---|---|---|
| 13 | 反射与护栏 | 循环会做出蠢事 |
| 14 | 案例研究：编程智能体 | 身体需要多专用化？ |
| 15 | RAG 一直是 harness 模式 | 同一个概念的千百种叫法 |
尾声
- 自己动手构建 — 完整带注释的玩具 harness
附录 — 进阶话题
独立篇目，需要时再读。
- A. 一个 harness，多个大脑 — 模型路由、prompt 分层、成本工程
- B. Worktree 与隔离 — 为并行智能体提供独立的世界副本
- C. 模式与 Plan Mode — harness 强制执行的运行状态（编程专用）
- D. 重试、限流与流式响应 — 不那么性感的管道细节，以及流式响应在线缆上是如何工作的
仓库结构
| 路径 | 内容 |
|---|---|
src/*.md |
章节与附录（书源） |
src/SUMMARY.md |
本书目录 |
src/harness/ |
可运行的玩具 harness —— 每一步一个文件 |
src/diagrams/ |
图表生成器及其生成的 PNG |
book.toml |
mdBook 配置 |
scripts/sync-to-blog.sh |
构建本书并挂载到博客以便提供 |
本地构建本书
cargo install mdbook mdbook-mermaid # or: brew install mdbook (+ mdbook-mermaid binary) mdbook serve --open # live-reloading preview at http://localhost:3000 mdbook build # static site into ./book
mdbook-mermaid 渲染内联 mermaid 图表；若没有它，这些块会以原始代码形式显示。
重新生成量化图表
cd src/diagrams && python3 gen_all.py # Python 3.10+, matplotlib
许可证
本仓库采用双重许可证：
- 正文——每一章及附录（
src/下的.md文件）——采用 知识共享署名-非商业性使用-禁止演绎 4.0 国际许可协议 (CC BY-NC-ND 4.0) 授权。您可以在署名后分享，但不得将其用于商业用途，也不得发布修改版本。完整文本见LICENSE。 - 代码——
src/harness/和src/diagrams/下的.py文件，以及正文中从这些文件中复制的代码片段——采用 MIT 许可证 授权。您可以自由使用，并附署来源。
© 2026 Isuru Wijesiri.
来源：Hacker News · github.com