最近有个仓库在圈里传，harness-engineering-101，讲怎么从第一性原理搭 AI agent。作者 Isuru Wijesiri。
先说它最要命的那句话。
LLM API 是无状态的。它不记得你上一句说了什么。每问一次，整段对话都得重新塞进去。
所以 agent 是什么？本质上是套在这个无状态循环外面的一圈补丁。
补丁都有什么：记住历史、调工具、失败重试、拦住它别乱动文件。这些活一样都不在模型里，全在外面那一层。作者给这一层起了个名字，叫 harness。
我挺喜欢这个拆法。
agent 这个词现在被讲得太玄了，玄到很多人以为它是一个新物种。不是。它是一层胶水，而且是很笨的胶水。
书里那个比喻是：LLM 是大脑，harness 是身体。这句我一开始当成套话划过去了，往后看才觉得它狠。大脑离开身体什么都干不了，但身体本身没有智能。你不会因为一具身体很精巧，就说它有想法。
写法比结论更值钱
16 章，加尾声和四个附录，分成四部分：基础通信与工具调用、长任务运行、生态与调试、信任与领域数据。在线阅读版挂在作者自己的站上，标的版本 1.1，日期就是这个月。
真正让我坐下来的是每章的固定结构。先讲一个具体的故障，再给最小修补，最后算这个修补的代价。
故障在前，方案在后。这不是排版习惯，是立场。
大部分教程先给你一张漂亮的架构图，然后让你自己去撞哪里会崩。这本反过来，它假定你已经崩了，或者马上就要崩。
“最小修补”这个提法也值得说一句。它不是最佳实践，它是够用就行。加缓存，慢一点；加重试，多花钱；加隔离，多一层配置。每一笔都记在账上。
这种账大部分人不算。所以大部分人的 agent 越改越复杂，改到最后自己都说不清是哪一层在起作用。
作者说这些经验来自他做 WSO2 MI Copilot、BI Copilot 和 One Code 的过程。这就对上了。那些故障不是编出来当例子的，是真掉过的坑。
一个东西一直长大，比十个漂亮 demo 有用
全书用一个 300 行左右的纯 Python 玩具 agent 贯穿，一章扩一点。
不是每章换一个新 demo。是同一个东西从头长到尾。
这个区别很大。看十个独立的小例子，你会觉得“哦，原来是这样”。看一个小东西从 300 行长到 600 行，你会知道它是在哪长的、为什么长。我倾向于认为后者才是能带走的。前者看完就忘，我自己是这样。
长任务那部分，我的看法比较偏
书里把长任务单独拎成一部分，我觉得这是整本里判断最准的地方。
一个 agent 跑十分钟就断，八成不是模型变笨了。是 harness 没给它留够上下文、没做检查点、没有在超时之后接着跑的地方。这些全是工程问题，跟模型能力关系不大。
反过来说，很多人一遇到长任务崩就换模型。换完还是崩。因为崩的那一层根本没动。
附录里有一节我踩过，有一节我没看懂
四个附录讲模型路由与成本、工作树隔离、计划模式、重试限流与流式传输。
工作树隔离那节我看得细。多任务共用一个工作目录，两个流程同时写同一个文件，debug 半小时才发现不是模型的锅。这种坑文档里一般不写，写文档的人自己没踩过。
模型路由那节我看得就粗了。成本这块我一直没算明白，先放在这里，等真被账单教育过再回来读。
许可证是拆开的
代码 MIT，正文 CC BY-NC-ND 4.0，两类内容分开授权。
这件事本身说明作者想清楚了：代码是给人拿去改的，正文是给人读的，不能一锅端。不少仓库懒得想这一步，一个 MIT 权当全文通用。不是大事，但能看出一个人做东西的细致程度。
用了 AI 写书，我不觉得是问题
作者在书里自己披露了，用 Claude Code 和 One Code 帮忙调章节顺序、润英文、生成图表和绘图代码。
我猜会有人拿这条做文章。我的看法反过来：写出来比藏着好。
关键不在用没用，在于读者能不能验证。这本书的验证成本很低。300 行代码摆在那，你可以跑。你甚至可以不看正文，只读代码，照样能判断他说得对不对。
倒是有些东西，通篇没有一行可跑，全靠叙述撑着。那种用不用 AI 写，你都一样验证不了。这才是真问题。
顺手说个数字
仓库现在 597 个 star，29 次提交。
1 个 watcher。
这个数字我看了半天。订阅了但从不看的只有一个人。我不知道该说这项目冷清，还是该说 star 这个动作本来就不值钱。
回到开头那句
agent 是一堆补丁。这句话不是在贬低它。
反过来才对。如果它就是一叠补丁，那意味着这叠补丁你自己也能打。缺什么补什么，坏了就回滚，成本自己算。不用等某个框架的某个版本把某个能力正式支持。
如果你一直觉得 agent 是个黑盒，那就只能等。等别人打好补丁，再花钱买。
这两条路的分岔点，其实就在于你接不接受“它就是一个循环外面套一圈东西”这个白话版。
“从第一性原理讲 X”这类标题，我平时是不太点开的，十篇里有八篇拿它当幌子，正文还是抄文档。这篇不是。它有具体的故障，有具体的账。
本周就这些。
上面有任何一条你试过、或者觉得我讲错了，欢迎告诉我。讲错的我补，没讲清的我改。
下周见。