Harness Engineering 101：LLM 是大脑，框架是身体

原标题：Harness Engineering 101: The LLM is the brain, the harness is the body

68AI 研判分

核心综述

《Harness Engineering 101》系列教程提出“LLM 即大脑，Harness（框架/外壳）即身体”的核心隐喻，强调智能体本质上是围绕无状态 LLM API 构建的状态管理与保护程序。该教程通过 16 章内容，从第一性原理出发，逐步演示如何用约 300 行 Python 代码构建一个玩具级智能体，并详细解析每个功能补丁背后的故障场景与成本权衡。

报道全文原始报道全文

本文目录10 个章节

The LLM is the brain. The harness is the body.

Version 1.0 — September 2026.

A blog series about building AI agents from first principles, published as a book.

📖 Read it online: https://isuruwijesiri.com/harness-engineering-101/

An LLM API is stateless. Every turn, you send the entire conversation as a JSON array and get text back. A harness is the program that builds, maintains, and protects that array. Everything the field calls "agents" is a set of patches to that one loop, and each patch exists because something concrete broke. This series develops that one idea across 16 chapters, growing a ~300-line toy agent in plain Python as it goes.

The patterns here are developed in full in One Code, an open-source coding agent built on pi.

The rendered book reads best online at the link above. If you'd rather read the source here on GitHub, follow the chapters in order below. The full introduction is on the book's landing page.

Reading order

Every chapter has the same shape: the failure, the minimal patch, what the patch costs.

Part I — The Wire (nothing is magic)

#	Chapter	The failure it patches
1	It's Just a JSON Array	"How do I even talk to this thing?"
2	The Brain: A Next-Token Black Box	"Why does it behave like that?"
3	Tools: JSON Mapped to Functions	The brain can't touch the world
4	The Agent Loop	One tool call isn't enough
5	Caching: Why Order Is Load-Bearing	Resending the array gets expensive

Part II — Running Long (the array under pressure)

#	Chapter	The failure it patches
6	Context Is a Budget, Not a Bag	The window fills up
7	Subagents: Fork the Context	One array can't hold all the work
8	Steering the Running Loop	The brain drifts mid-task
9	Background Work and Time	The loop is synchronous; the world isn't

Part III — The Ecosystem (naming what you already understand)

#	Chapter	The failure it patches
10	Every Framework Is a Wrapper Around Chapter 1	Abstraction anxiety
11	Extending the Body: MCP, Skills, Deferred Loading, Hooks	Capabilities don't fit in the array
12	Debugging the Array	You can't fix the prompt you can't see

Part IV — Trust, Domains, and Data

#	Chapter	The failure it patches
13	Reflexes and Guardrails	The loop will do something dumb
14	Case Study: Coding Agents	How specialized does the body need to be?
15	RAG Was a Harness Pattern All Along	A thousand names for one idea

Epilogue

Build Your Own — the complete toy harness, annotated

Appendix — Advanced Topics

Standalone pieces. Read them when you need them.

A. One Harness, Many Brains — model routing, prompt tiers, cost engineering
B. Worktrees and Isolation — giving parallel agents separate copies of the world
C. Modes and Plan Mode — harness-enforced operating states (coding-specific)
D. Retries, Rate Limits, and Streaming — the unglamorous plumbing, plus how streaming works on the wire

Repository layout

Path	What it holds
`src/*.md`	The chapters and appendices (the book source)
`src/SUMMARY.md`	The book's table of contents
`src/harness/`	The runnable toy harness — one file per stage
`src/diagrams/`	Diagram generators and their generated PNGs
`book.toml`	mdBook configuration
`scripts/sync-to-blog.sh`	Builds the book and mounts it into the blog for serving

Building the book locally

BASH

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 renders the inline mermaid diagrams; without it those blocks show as raw code.

Regenerating the quantitative diagrams

BASH

cd src/diagrams && python3 gen_all.py   # Python 3.10+, matplotlib