凌晨两点，你盯着屏幕上那个叫index.ts的文件。三天前它还很清爽——一个提示词，两个工具函数，跑起来顺风顺水。现在？里面塞了记忆模块、日志逻辑、三个临时加的代理，还有一堆你不敢删的注释。你清楚这种感觉：不是代码坏了，是结构死了。
这就是AI代理项目的经典死法。不是模型不够聪明，是文件夹先疯了。
一张图看懂：能长大的项目长什么样
作者给出的骨架很直白。顶层就一个src，下面九个抽屉各司其职：
agents放角色定义，tools放工具实现，memory管记忆，workflows处理流程编排，mcp对接模型上下文协议，prompts存提示词模板，middleware塞拦截逻辑，types统一类型，最后index.ts当入口。
看起来像个过度设计的文件夹展览？作者自己说了：你不会一开始全建。但每个东西该去哪，得提前想好。
这和张小龙说的"用完即走"完全相反——AI项目的文件夹得"用完还有地方去"。
为什么AI项目比传统后端更容易烂掉
传统后端是地铁线路图。请求从A站进，B站出，中间几站固定，查日志按图索骥就行。
AI代理是网约车。模型自己决定走哪条路，可能半路接单，可能突然取消，还可能把你扔在"我需要更多信息"的荒郊野外。
这种不确定性让调试变成猜谜。没有结构的话，你根本不知道代理刚才调了哪个工具、读了哪段记忆、为什么突然停下来要人工审批。作者的原话很狠："Without structure, debugging becomes guesswork."
有结构，行为才可追溯。不是代码变简单了，是复杂变得可见了。
起步比你想象的更小
作者给的起步配置堪称寒酸：
就一个agents/researcher.ts定义角色，一个tools/search.ts实现搜索，加上入口文件。没了。
这能跑。真的。一个能用的研究助理代理，核心就这三文件。
等要加记忆了，建memory/。要编排多步骤任务了，开workflows/。需要拦截和修改模型输出了，再塞middleware/。结构是长出来的，不是一次设计出来的。
这和创业公司招人一个道理：先招能解决具体问题的人，等组织架构真成瓶颈了再拆部门。提前画满架构图的，往往死在最完美的PPT里。
agents文件夹：不是放代码，是放"人设"
作者给的例子很有意思。一个researcherAgent对象，里面就三样东西：名字、系统提示词、工具列表。
这和我们习惯的做法不一样。通常我们会写一个类，继承某个BaseAgent，重写一堆方法。但作者的结构更像个配置文件——代理是什么、能干什么、怎么干，一目了然。
好处很明显。换模型？改配置。换提示词？改配置。给代理换套工具？还是改配置。行为和数据分离，测试和迭代都快。
坏处也有：自由度低了。但作者的前一篇文章已经打过预防针——代理应该是"受控系统"，模型只负责提议，验证、执行、安全都由应用层把关。文件夹结构是这套哲学的物理延伸。
那些没展开的抽屉里藏着什么
原文只详细拆了agents，其他文件夹是留白。但结合上下文，能猜个七七八八：
tools/应该不是随便放函数。作者强调"应用层拥有执行权"，所以这里可能是工具的定义+权限声明，真正的执行逻辑在更下层。
memory/大概率要处理两种时间尺度：对话历史的短期记忆，和向量数据库的长期记忆。怎么存、怎么取、什么时候过期，都是坑。
workflows/可能是整个结构里最重的部分。多代理协作、条件分支、人工介入点，这些流程编排的复杂度会指数级增长。
mcp/是模型上下文协议（Model Context Protocol）的对接层。这是个相对新的东西，负责标准化代理和外部系统的通信。作者把它单拎一层，说明认可这协议会成为基础设施。
middleware/的位置很微妙。放在agents和tools之间？还是包在最外层？原文没细说，但"拦截和修改"的定位暗示这是安全审计和日志埋点的关键位置。
一个反直觉的判断
这篇文章最狠的地方，是它承认了一件事：AI项目的复杂度不是来自技术，来自决策路径的不确定。
你写传统代码，是在修高速公路。写AI代理，是在画城市地图——但这座城市会自己长出新街道。文件夹结构不是解决技术问题的，是解决"我三天前的代码在干什么"这个问题的。
作者没说的潜台词：如果你的代理项目永远停留在demo阶段，这套结构确实是过度设计。但一旦要上线、要迭代、要多人协作，没有这套骨架，肌肉会把自己缠死。
现在回头看那个凌晨两点的index.ts。它需要的不是重构，是一次体面的葬礼——把里面的东西迁到该去的地方，然后让它安息。
热门跟贴