《Harness Engineering 101》：把 LLM 当大脑、harness 当身体，用约 300 行 Python 从零构建 AI Agent
Harness Engineering 101: The LLM is the brain, the harness is the body
Isuru Wijesiri 发布开源书《Harness Engineering 101》，主张 LLM 是无状态的大脑、harness 是维护对话 JSON 数组的身体，所谓 Agent 都是对这一循环打的补丁。
大语言模型是大脑。 harness 是身体。
版本 1.1，2026 年 10 月。
AI 使用声明：我亲自撰写了每一章，基于我构建 WSO2 MI Copilot、WSO2 BI Copilot 和 One Code 的经验。我使用 Claude Code 和 One Code 对每章进行排序，使其以答案开头（Minto 金字塔），润色英语，生成图表，并编写绘制图表的代码。
这是一个关于从基础原理构建 AI 代理的博客系列，已出版成书。
📖 在线阅读： https://isuruwijesiri.com/harness-engineering-101/
LLM API 是无状态的。每一轮，你将整个对话作为 JSON 数组发送，并获取文本回复。一个 harness 是构建、维护和保护该数组的程序。该领域所说的“代理”都是对该循环的一组补丁，每个补丁的存在都是因为某件具体的事情出了问题。本系列将在 16 章中发展这一单一思想，以纯 Python 编写一个约 300 行的玩具代理，并在过程中逐步构建它。
我在 One Code 中使用了相同的思想，这是一个基于 pi 的开源编码代理。
渲染的书籍在上述链接上在线阅读效果最佳。如果你宁愿在 GitHub 上这里阅读源代码，请按以下顺序跟随章节。完整的介绍在 书的着陆页 上。
阅读顺序
每一章都有相同的形式：失败、最小补丁、补丁的成本。
第一部分 — 导线（没有什么神奇）
| # | 章节 | 它修复的失败 |
|---|---|---|
| 1 | 它只是一个 JSON 数组 | “我甚至不知道如何与它交谈？” |
| 2 | 大脑：一个下一个标记的黑色盒子 | “为什么它的行为是这样的？” |
| 3 | 工具：JSON 映射到函数 | 大脑无法接触世界 |
| 4 | 代理循环 | 一次工具调用不够 |
| 5 | 缓存：为什么顺序很重要 | 重新发送数组很昂贵 |
第二部分 — 长时间运行（数组在压力下）
| # | 章节 | 它修复的失败 |
|---|---|---|
| 6 | 上下文是一个预算，而不是一个袋子 | 窗口已满 |
| 7 | 子代理：分割上下文 | 一个数组无法容纳所有工作 |
| 8 | 引导运行循环 | 大脑在任务中途偏离 |
| 9 | 后台工作和时间 | 循环是同步的；世界不是 |
第三部分 — 生态系统（命名你已经理解的东西）
| # | 章节 | 它修复的失败 |
|---|---|---|
| 10 | 每个框架都是围绕第一章的包装器 | 抽象焦虑 |
| 11 | 扩展身体：MCP、技能、延迟加载、钩子 | 能力不适用于数组 |
| 12 | 调试数组 | 你看不到的提示语无法修复 |
第四部分 — 信任、领域和数据
| # | 章节 | 它修复的失败 |
|---|---|---|
| 13 | 反射和护栏 | 循环会做蠢事 |
| 14 | 案例研究：编码代理 | 身体需要多专门化？ |
| 15 | RAG 始终是一个 harness 模式 | 一个想法有一千个名字 |
尾声
附录 — 高级主题
独立的片段。当你需要时阅读它们。
- A. 一个 harness，多个大脑：模型路由、提示层级、成本工程
- B. 工作树和隔离：给并行代理世界不同的副本
- C. 模式和计划模式：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