造一个 Agent 运行时 #01:我决定开干,顺便把坑都写下来
最近半年我在干一件有点轴的事:自己从零写一个 agent 运行时。
就是你在 Claude Code、Codex CLI,还有开源的 openclaw、Hermes 里见过的那种东西------你扔给它一句话,它自己去读文件、跑命令、调工具、改代码,干完一轮回来跟你汇报。圈里给这套东西起了个名字,叫 harness。
这个词我第一次听也觉得有点唬人,换个说法你立马就懂了:把大模型(GPT、Claude、DeepSeek 这些)想成 CPU,harness 就是包在 CPU 外面那层"操作系统"------管文件、管工具、管权限、管会话、管它什么时候该停下来。模型负责"想",harness 负责把想法落地成实际动作。
一句话:Agent = 模型 + harness 。模型大家都能调 API,真正决定一个 agent 好不好用的,是外面这层 harness。
画成图大概是这样------模型缩在最里头只管"想",外面这层 harness 才是真正跟你的电脑、文件、命令打交道的部分:
你会发现,图里除了最底下那个"想"的盒子,剩下全是工程活。这也是为什么我说,决定 agent 好不好用的是 harness,不是模型。
为什么是我,又为什么是现在
其实我碰 AI 不算晚,从 2023 年就开始折腾了。最早特别朴素,就是直接调 OpenAI 的 API,自己包一层拿来用。
后来不满足,就自己撸了个网站,功能上跟现在的 OpenClaw 有点像------想让 AI 能真的干点活,而不只是陪你聊天。但说句实在话,我那时候就是在重复造轮子,而且造得不好。心里其实清楚不行,可又不甘心,总想着再改改、再试试,就是停不下来。
转折是 OpenClaw 出来那会儿。我看完第一反应是:哦------原来 agent 还能这么做。有点像一直在黑屋里瞎摸,突然有人把灯给打开了。
被点醒之后,我一头扎进了一个执念:开箱即用。我总觉得好东西就该让人打开就能用,所以一根筋想做成网页版,注册个账号、点开就能跑。
做着做着,撞上了一堵墙。我慢慢回过味来:用户要的不只是"方便",还有"安全"------尤其是数据安全。你的代码、你的对话、你电脑里那些文件,凭什么得先上传到我某台云服务器上,它才能帮你干活?这一关,我自己心里都过不去。
想通这层,我才摸到现在这个项目的地基,也是我现在最笃定的一句话:
AI agent 的部署,天然就该是本地的。
跑在你自己的机器上,数据不出门;底层模型想换哪家换哪家,DeepSeek、Claude、还是自己部署的,都只是个能随时拔下来换上去的零件。openclaw、Hermes 走的也是类似的路子,但我想自己把这条路从头到尾再走一遍------一是不甘心,二是只有亲手趟过,你才知道每块砖底下到底埋着什么。
可能有人要说:现在不都讲 A2A 了吗?agent 跟 agent 之间互相调用、组队干活,哪还分什么本地云端。这话没毛病,但那是另一码事。A2A 解决的是"一个 agent 怎么跟别的 agent 打交道",是协作层 的协议;我这里说的本地化,说的是"你自己这个 agent 跑在哪、你的数据攥在谁手里",是部署层 的事。两个不在一个层面,也不冲突------哪天我这东西要跟别的 agent 联手,照样能接 A2A,但前提是,它自己得先稳稳地长在你自己机器上。
这个连载到底写什么
我准备把整个过程写成一个连载。
注意,不是等全做完了回过头来"教学"。是边造边写,造到哪写到哪------包括我做的每一个设计选择为什么这么选、当时还有哪几个别的选项、我为什么把它们毙了;以及最重要的,我踩的每一个坑。
为什么坑值得专门写?说实话,"怎么实现一个 agent 循环"这种东西,你随便搜搜就有一堆。但我做下来体会最深的一句话是:
真正难的不是把功能跑起来,是让它出错的时候别把事情搞砸。
举几个我已经踩过的,后面每个都会单独写一篇:
- 流式响应读到一半,对面服务器挂在那儿不发也不断开,我这边就傻等,整个对话永久卡死,既不报错也不结束。
- 我明明点了"停止",后台子任务还在哗哗地跑------因为取消信号没能传到最底下那一层。
- 还有更离谱的:某次 AI 在自动测试的时候,把我本地的数据目录给
rm了。
你发现没有,这几个坑没有一个是"功能没实现"。全都是功能实现了,跑得好好的,但边界没想清楚。而这正是我想记下来的东西。
那追完这一系列,你大概能拿走这么几样:
- 看懂一个能真正跑起来的 agent 是怎么从零搭出来的------不是跑个 demo 就完事,是循环、工具、权限、会话、取消、上下文压缩、子 agent 这些一件件拼起来的真东西。
- 我踩过的坑,你能直接绕过去------尤其那些"功能跑通了、边界却没想清楚"的暗坑,demo 教程不会讲,我会一个个摊开。
- 一套跟 AI 协作写代码的工程纪律------这个可能比某个具体功能还值钱,你换个项目照样用得上。
- 要是你自己也想动手造一个,那这就是一份带翻车记录的实操路线图,帮你少走我走过的弯路。
当然,我不指望你全程跟下来。哪篇标题戳中你了就看哪篇,每篇我都尽量写成能单独读懂的。
我想先聊的,其实是"规矩"
所以这个连载,我打算先把一件事摆到最前面:我给自己定的那几条开发纪律。
我越做越觉得,这半年最值钱的产出根本不是代码,是这些规矩。随便先剧透两条:
- 怀疑哪儿有 bug,我不许自己上来就改代码。得先写一个能复现这个 bug 的测试,亲眼看着它失败(变红),再动手。复现不出来,那就说明它可能压根不是 bug,或者我猜错了根因。
- 任何"会等"的代码------等网络、等子任务、等用户确认------加之前我先逼自己回答一句:它要是永远等不到,我怎么办?
这些规矩听着像废话,但我可以负责任地说,上面那几个坑,基本都是当初没守住某一条才踩进去的。
当然,我不敢说这套纪律有多正确。我也是一边踩一边总结出来的,很可能写到后面会推翻我现在说的某句话。但我会如实记下来,包括打脸的部分------这种事躲是躲不掉的,藏着不写反而没意思。
几句说在前面的话
这个项目现在还没到能开源的程度,所以这个系列里我暂时不放仓库链接和项目名,贴出来的代码片段也都做过脱敏处理(但逻辑都是真的,没注水)。等它长结实了,我第一时间放出来。
如果你也动过"自己造一个 agent 运行时"的念头,或者就是单纯想看我怎么把这些坑一个一个填平,那欢迎追这个系列。
下一篇我想先不写代码,先掰扯掰扯开工前我给自己立的那几条规矩------我现在是真觉得,这些才是干货。