AI 编程与智能体工程 · 第 5 期

500 行写一个能跑的编码 Agent

mini-harness 从零拼装 · build a coding agent

不依赖任何 Agent 框架,500 行 Python 写出能改真实仓库的编码 Agent。重点不是"500 行"这个数字,是六大组件各留一块零件,最后拼成整车。造过一遍,你才真正懂那些框架在帮你做什么。
⏱ 约 12 分钟 🎯 想自研/深度定制 Agent 的工程师 📦 源:agent-harness §10

01一个反共识:不靠框架,才懂框架

用 LangChain/AutoGen 能 50 行起一个 Agent,但你不知道那 50 行背后替你做了什么——出问题就抓瞎。

mini-harness 的思路:从最小循环写起,每章留一块可复用零件,第 10 章拼成完整 mini-harness。走完一遍,你获得的不是"又一个框架",而是对六大组件边界的直觉:哪块该自己写、哪块用现成的、出问题该查哪。

这也是 build-your-own-x 的同款逻辑——造过轮子的人,调别人的轮子才调得动(见编程与开发集第 1 期)。

不靠框架写一遍,
才懂框架替你做了什么。
灏天文库 · AI 编程与智能体工程 P.15

02六大零件逐块点亮

按顺序点下面六块零件,看每块加进来后 mini-harness 长什么样。第六块点亮时,整车能跑。

🔧 代码逐步点亮
按顺序点零件,看 mini-harness 代码逐块长出来。

03500 行的边界:能跑,但不生产可用

mini-harness 能在真实仓库完成任务,但它的边界要清楚——这是教学实现,不是生产系统:

这些边界正是它该有的样子——教学代码只做教学的事。真要上线,你拿这 500 行当骨架,把每块零件换成生产级实现(沙箱换容器、观测换 OpenTelemetry、循环换状态机)。骨架是你自己写的,换零件你心里有数。

500 行是骨架,
生产是换零件。
灏天文库 · AI 编程与智能体工程 P.16

04带走这套清单

✅ mini-harness 6 条可执行规则

  1. 从最小循环写起:60 行 Agent 循环先跑通,再加组件,别一上来堆功能。
  2. 每章留一块零件:循环/工具/权限/沙箱/上下文/Hook 各一个独立模块,可单独测。
  3. 第 10 章再拼整车:零件齐了再组装,组装时只写"接线"代码。
  4. 不依赖框架:用原生 Python + LLM API,别让框架替你藏住关键逻辑。
  5. 认清边界:教学实现不做并发/分布式/强沙箱,生产时换零件不换骨架。
  6. 端到端跑通真实仓库:能在真 Git 仓库完成一个真实任务,才算"能跑"。
造过一遍 mini-harness,
框架对你就是工具不是黑箱。
灏天文库 · AI 编程与智能体工程 P.17