我给自己写了个AI助手：一个编程新手的Agent搭建记录

椋庡  |  2026年7月

为什么自己造轮子？

事情要从我想给朋友推荐AI助手说起。

我自己在用Hermes Agent，一个挺强大的命令行Agent平台。功能确实多——记忆系统、技能管理、定时任务、多模型切换……但问题也在这里：太多了。每次想拉朋友入坑，都要解释"你先装这个、配置那个、再设环境变量……"还没说完对方已经失去了兴趣。

我就想：能不能做一个超轻量版的？保留最核心的东西——像Hermes一样有记忆、有可扩展的技能、能自我进化，但部署简单到"下载一个文件、双击就能用"，操作简单到有个网页界面就行。

同时我也在学Hermes的框架——它的工具系统怎么设计的、记忆怎么存的、提示词怎么组织的。拆解一个成熟的平台，是我搭建自己项目的捷径。

于是就有了芙悠（Fuyo）——一个轻量级的ReAct智能体。她和Hermes一样有三层记忆（用户画像、对话记录、技能知识全存SQLite）、有自动发现工具系统、有Web图形界面。但她不依赖任何外部平台，一个exe文件打包所有依赖，复制给朋友就能跑。

芙悠的Web聊天界面——有记忆、有技能、轻量到可以打包成一个exe

搭建的过程：像给一副骨架添血肉

一开始只是一副骨架——一个最简单的循环：用户说一句、调API、返回答一句。没有记忆，没有工具，没有界面。一两百行代码，跑起来就很有成就感。

然后我开始往上面添东西。

先是工具系统。我参考Hermes的设计，把每个工具拆成独立的文件，程序启动时自动扫描目录注册。搜索、读文件、写文件、执行命令、浏览网页……加一个新工具只需要新建一个Python文件，核心代码一行都不用改。

然后是记忆。一开始用文本文件存对话，后来发现太慢——重构成了SQLite数据库，加上FTS5全文搜索，芙悠能跨会话找到几个月前聊过的内容。

再然后是Web界面、上下文压缩、内置工具（搜历史、保存画像、学技能）……

在这个过程中我有一个深刻的感受：框架比功能重要。工具系统只要定义好基类（NAME、DESCRIPTION、run函数），每一个新工具都像往插座上插电器——各自独立、随时可加、互不干扰。功能可以慢慢补，但框架如果一开始没搭对，后面每加一个功能都要伤筋动骨。

这就好比先搭骨架，确定关节怎么连接的，再往上面贴肉。肉可以一块一块慢慢长，骨架歪了就只能推倒重来。而添血肉的过程本身，就有一种奇妙的满足感——每加一个模块，芙悠就"活"了一分：加了记忆，她就能记住你；加了工具，她就能做事；加了技能系统，她就能学习了。

项目结构——十几模块各自独立，框架搭好后添功能像插积木

栽坑：速度太快，安全网为零

芙悠的第一个版本跑起来之后，我进入了"狂加功能"模式。最快的一天，我同时上了五个大改动：记忆系统重构、多Action并行执行、提示词三层拆分、Web前端搭建、上下文压缩管理器。

然后程序炸了。

不是"有个bug修一下就好了"的那种炸，而是"格式错""调用错误""命令卡死""幻觉残留"像连锁反应一样一起爆。我像打地鼠一样来回修，修好一个冒出两个，修好两个冒出三个。

事后复盘，我觉得自己犯了两个致命错误：

第一，把AI当成"给我修好"的黑箱。 每次报错我就贴给AI说"修一下"，AI给了方案我就直接上，不验证。这个模式叫vibe coding——跟着感觉走，AI说啥就是啥。但弱模型诊断复杂错误有个天生的缺陷：它会给你一个"看起来合理"的答案，而不是"真正对"的答案。修bug应该是我和AI一起找根因——我描述现象，AI提出假设，我跑验证，拿到日志再给AI看——是搭档关系，不是外包关系。

第二，没搞懂框架就动手加功能。 比如我想加一个上下文压缩功能，但我根本没理解提示词是怎么组装和注入的。AI也不知道——它只能看到我给它的那部分代码，遇到跨文件的逻辑它就瞻前顾后、瞎猜着写。结果改出来的东西和原有系统的注入顺序冲突，产生了一堆莫名其妙的行为。后来我学乖了：加任何一个新功能之前，先把涉及的所有文件通读一遍，画出数据流向图，确认每个环节都理解了再让AI动手。

还有一个大坑是运行环境。项目一开始跑在WSL里（因为我的Hermes主力在WSL上，WSL Hermes直接帮我在那边搭了初始化）。但后来我发现，要给朋友用的话Windows才是正道——别人电脑上没有WSL，打包exe也必须走Windows。于是我把整个项目搬到了Windows上。结果：终端指令语法变了（bash→cmd），路径格式变了（/mnt/d/→D:\），文件权限行为也变了。一堆之前跑得好好的功能突然全崩。

这件事教会我：环境是地基，选好了就别轻易挪。 如果一开始就想清楚"最终部署在哪"，能省掉一大半的兼容性调试。顺便说一句，Hermes在WSL和Windows上的表现差异也很大——这个话题值得单独写一篇。

转机：换Kimi，一晚上翻盘

项目后期，程序表面上能跑，但一改就崩，像浑身旧伤的人。我不知道根因在哪，也不敢大动。

最后我把模型从DeepSeek V4 Flash换成了Kimi。

Kimi接手后做了一件我从来没做过的事：它先用一晚上通读整个项目的代码、日志、git提交历史，像医生翻病例一样把最近的每次改动都梳理了一遍。然后它给出了四份"诊断书"——每个bug都有复现脚本和日志实证，不是"猜"的，是实打实跑出来的。

修复花了一整天：处理文本的函数把代码缩进当成"多余空格"清掉了→拆成两个函数，显示管显示、数据管数据；系统提示里写了"你在Git Bash里"但实际跑的是cmd→改成跑一句命令验证出真实环境再写进去；多行命令被自动去掉了缩进→改解析逻辑保留首行空格……四个根因，每个都是不起眼的小细节，但积累起来差点杀了这个项目。

有一件事让我印象很深：Kimi第一次把我那个对话的60次限额用满了。但下一个对话里，我只需要说一句"继续修Fuyo"，它自己搜索了上一段会话的记录，无缝接上了——进度、已修复项、待办清单，一字不落。修复完后，它还写了一个PyInstaller脚本把整个项目打成独立exe，朋友拿到手双击就是网页界面，Python都不用装。

打包后的芙悠——一个exe文件，双击启动Web界面

Kimi为什么能救回来？

高级模型确实更擅长诊断——它能跨十几个文件追踪因果链，能从蛛丝马迹里拼出全局。但我冷静下来想，如果我的项目没有做到以下几件事，再强的模型也无能为力：

模块化。 每个工具独立一个文件，核心循环、记忆系统、配置管理各自分开。出了bug能快速定位到具体模块，而不是大海捞针。

文档。 CLAUDE.md里记录了项目结构、文件树、关键接口和数据流向。Kimi接手第一件事就是读这个文件。没有它，得先花半天猜代码是怎么组织的。

Git。 每次大改动前我都做了checkpoint提交。Kimi诊断时通过git log翻出每个改动前后的差异，精确定位到"bug从哪个提交开始引入的"。比盲修高效一百倍。

这三样东西，在我最早期"能跑就行"的阶段就开始做了。当时觉得是额外负担，但后来证明——好习惯不会帮你写出更好的代码，但会在你翻车的时候给你一条回去的路。

六条经验教训

1. 先搭框架，后添功能。 骨架正了，肉可以慢慢长。工具系统定好基类之后，加新工具就像插积木——各自独立，互不干扰，随时可换。

2. 不懂框架之前别动手改。 AI只能看到你给它的代码片段，跨文件的逻辑链条它不知道。你得先把整个流程画出来、搞懂了，再带着AI定点落刀。否则AI瞻前顾后，越改越乱。

3. 修bug不是"AI你帮我修一下"。 弱模型修长代码，不能vibe coding——你说问题、它给方案、你直接上。正确姿势是：你描述现象→AI提出假设→你跑验证拿日志→AI看日志修正假设→定位根因→再动手。是搭档，不是外包。

4. 一次一个功能，改完立刻验证。 一天五个大改是自杀。慢就是快——五个功能分五天做，总耗时比同一天改然后修三天bug短得多。

5. 部署环境是地基，定好了别轻易换。 WSL搬Windows看起来只是换个地方跑，实际终端语法、路径格式、文件权限全变了。想清楚最终在哪用，从第一天就在那个环境里开发。

6. 好习惯是翻盘底牌——模块化、文档、Git。 顺风局看不出差距，逆风局这些东西决定你要修三天还是直接重写。Kimi能一晚上修好四个core bug，靠的不是"更聪明"，而是我的代码有足够的结构性让它快速理解。

写在最后

我学编程不到两个月。芙悠是我第一个独立搭建的项目。

中间确实挺烦躁的。改了半天发现根因是一个不起眼的小函数，或者加个功能结果把三个老功能搞崩了——这种时候就很想摔键盘。但每次把问题搞清楚之后，都比上一次更明白系统是怎么运转的。那些折腾你最久的bug，修完之后就变成了下次一眼能认出来的\"老熟人\"。

AI让编程的门槛低了很多，但门槛低不代表路好走。AI可以帮你写代码，但不能替你理解代码；可以帮你修bug，但不能替你学会为什么会有这个bug。

如果你想给朋友分享AI的乐趣，我推荐你先自己搭一个。不是为了结果——是为了过程。搭过一次，你就知道"Agent"这个词下面藏了多少东西。

加油。我们都在路上 (๑•̀ㅂ•́)و✧