LLM 是大脑，harness 是身体。这一版本为 1.0、2026 年 9 月的博客系列从第一性原理讲如何构建 AI 智能体，并以成书形式发布。LLM API 是无状态的，每一轮都要把整段对话作为 JSON 数组发送并取回文本；harness 就是构建、维护和保护这个数组的程序。所谓智能体，其实都是对这一循环的补丁，而每个补丁都源于某个具体故障。系列用 16 章展开这一想法，并逐步用纯 Python 把玩具智能体扩展到约 300 行。

Harness Engineering 101

LLM 是大脑，harness 是身体。

版本 1.0，2026 年 9 月。

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

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

LLM API 是无状态的。每一轮，你把整个对话作为一个 JSON 数组发送，然后取回文本。Harness 就是构建、维护并保护这个数组的程序。业界所谓“agent”，本质上都是对那一个循环的补丁，而每一个补丁的存在，都是因为某个具体的东西崩了。本系列用 16 章展开这一个想法，并在过程中用纯 Python 把一个约 300 行的玩具 agent 逐步长大。

阅读顺序

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

第一部分 —— 导线（没有什么魔法）

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

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

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

章节与所修补的失败

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

尾声

自己动手实现：完整的玩具 harness，带注释

附录 —— 高级主题

独立篇章，需要时再读。

代码库结构

| 路径 | 内容 | | --- | --- | | src/*.md | 章节与附录（书籍源文件） | | src/SUMMARY.md | 书籍目录 | | src/harness/ | 可运行的玩具 harness，每个阶段一个文件 | | src/diagrams/ | 图表生成器及其生成的 PNG | | book.toml | mdBook 配置 | | scripts/sync-to-blog.sh | 构建书籍并挂载到博客以供访问 |

本地构建书籍

1. 安装 mdbook 与 mdbook-mermaid：cargo install mdbook mdbook-mermaid（或用 brew install mdbook，再加 mdbook-mermaid 二进制）。
2. 启动实时预览：mdbook serve --open，预览地址为 http://localhost:3000。
3. 构建静态站点：mdbook build，输出到 ./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，可自由使用，但需保留署名。

© 2026 Isuru Wijesiri。

多数人反感把 LLM 拟人化为“大脑”或生命体，讨论主轴是系统能力究竟来自 LLM 本身，还是来自 harness（工具、记忆、流程）工程；社区同时对陈旧比喻和 AI 生成内容表现出明显疲惫。

反对将 LLM 拟人化或比作生物大脑

• LLM 本质是基于词/子词向量与数学计算来预测下一个词元；若非要说它像大脑，也像一个每次都得重新被告知什么是胳膊和腿的严重失忆者，而且输出里总偏爱“real”“load-bearing”这类模型高频词。（认可度：较多人） > 如果非要说 LLM 是大脑，那它更像一个每次都得重新被告知什么是胳膊和腿的严重失忆者。（@mattbrewsbytes）
• 接连出现把 LLM 说成有生命、思想、情感，或又一本由 LLM 生成的 AI 书籍，让人反感这种违背证据的拟人化宣传。（认可度：较多人）

认为 harness 才是智能系统的核心，LLM 不一定必须是大脑

• 在 harness 中集成规划器、记忆系统、经典机器学习、强化学习、黑板模型、贝叶斯或因果推断等机制后，系统整体智能可以远超 LLM 本身；根据任务不同，甚至完全不需要 LLM。（认可度：较多人） > 我其实会进一步主张：系统表现出的整体智能可以包含远多于 LLM 的东西，某些任务里甚至根本不需要 LLM。（@mindcrime）
• Harness 优化至关重要：如果工具无效或任务定义不清，模型再聪明也得每次从第一性原理重新解决；有团队把 Jev 的 harness 优化后，效果显著优于原始 DeepSeek 且成本只有极小一部分。（认可度：少数人）

主张动手从零写 harness，而不是读充满破旧比喻的 AI 解释

• 与其读那些由 AI 生成、充满破旧比喻的解释，不如从零搭一个基础编码 harness；可让前沿 LLM 辅助学习，但主循环、工具调用等核心逻辑必须自己手写，以真正内化 agent 原理。（认可度：较多人） > 与其读那些充满破旧比喻的 AI 废料解释，不如从零搭一个最基础的编码 harness，你会学到非常多。（@libraryofbabel）
• 自己写 harness 时不照搬现有 agent，而是先厘清使用现有 agent 的痛点，接受更高推理开销以换取能放置数小时后直接返回解的全自动体验；更关键的是别只微调现有方案，而应重新思考上下文等机制的设计。（认可度：少数人）

担心 RSI 若成真，harness 会被模型能力直接碾压

• 如果递归自我改进真的出现，模型可能不再需要外部 harness 来补足，当前围绕 harness 做的工程可能会被更聪明的模型直接绕过或吸收。（认可度：少数人）

有价值的补充

• 过去一年所谓 AI agent 客户端的进展，大多只是循环、线程、JSON 数组和上下文/内存管理等基础计算机科学概念的不同组合，却被当成巨大突破来宣传；有人因此希望引入游戏开发者视角，因为 AI 客户端与游戏在状态、调度和内存管理上似乎有相似的工程问题。
• 在加固 LLM harness 运行环境方面，有人把 Claude 放进零凭证容器，再用独立网关容器拦截请求并注入所需令牌、为 AWS 请求签名，并通过防火墙把可访问主机限制在少数已知地址；不过这类做法目前多靠试错，社区仍在寻找更系统的加固文档。
• 精巧类比之一：LLM 是烤箱，harness 是厨房；食材（输入）经烤箱转化为蛋糕或面包等成品，harness 负责备料与承载流程。
• 精巧类比之二：有人把 harness 比作攀登保护器、LLM 比作保护者、用户比作勉强攀登的攀登者，其实是 LLM 用蛮力把人拉上山，让人误以为是自己的成就却几乎没真正出力。