Harness Engineering 101：LLM 是大脑，harness 是身体

LLM 是大脑。harness 是身体。

版本 1.0 — 2026 年 9 月。

一个关于从第一性原理构建 AI agent 的博客系列，以书籍形式发布。

📖 在线阅读：https://isuruwijesiri.com/harness-engineering-101/

LLM API 是无状态的。每一轮，你都要把整个对话作为 JSON 数组发送出去，然后拿回文本。而 harness 就是负责构建、维护并保护这个数组的程序。这个领域里被称为“agent”的一切，都是对这一个循环打上的补丁，而每个补丁的存在，都是因为某个具体的东西坏掉了。本系列用 16 章展开这一个想法，并在此过程中用纯 Python 逐步长出一个约 300 行的玩具 agent。

这里的模式在 One Code 中有完整展开，那是一个基于 pi 构建的开源编码 agent。

渲染后的书在上面的链接在线阅读效果最佳。如果你更愿意在 GitHub 上读源码，请按下面的顺序阅读各章。完整引言在本书的落地页上。

阅读顺序

每一章都有相同的结构：失败、最小补丁、补丁的代价。

第一部分 — 线路（没有魔法）

#	章节	它修补的失败
1	它只是一个 JSON 数组	“我到底该怎么和这东西对话？”
2	大脑：一个下一 token 黑盒	“它为什么会有那样的行为？”
3	工具：映射到函数的 JSON	大脑无法触碰世界
4	Agent 循环	一次工具调用不够
5	缓存：为什么顺序是承重的	重发数组会变得昂贵

第二部分 — 长时间运行（承压下的数组）

#	章节	它修补的失败
6	上下文是预算，不是袋子	窗口被填满
7	子 agent：分叉上下文	一个数组装不下所有工作
8	引导运行中的循环	大脑在任务中途漂移
9	后台工作与时间	循环是同步的；世界不是

第三部分 — 生态（为你已经理解的东西命名）

#	章节	它修补的失败
10	每个框架都是第 1 章的包装	抽象焦虑
11	扩展身体：MCP、Skills、延迟加载、Hooks	能力装不进数组
12	调试数组	你无法修复你看不见的提示词

第四部分 — 信任、领域与数据

#	章节	它修补的失败
13	反射与护栏	循环会做出蠢事
14	案例研究：编码 agent	身体需要多专门？
15	RAG 一直就是一种 harness 模式	一个想法的一千个名字

尾声

构建你自己的 — 完整的玩具 harness，带注释

附录 — 进阶主题

独立篇章。需要时再读。

A. 一个 harness，多个大脑 — 模型路由、提示词分层、成本工程
B. Worktrees 与隔离 — 给并行 agent 各自独立的世界副本
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 文件）—— 依据 Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International (CC BY-NC-ND 4.0) 许可。你可以在注明出处的前提下分享，但不得用于商业用途或发布修改版本。完整文本见 LICENSE。
代码——src/harness/ 和 src/diagrams/ 下的 .py 文件，以及各章中从中复制的代码片段——依据 MIT License 许可。可自由使用，但需注明出处。