大家好，我是东哥。「Vibe Coding AI编程实战」系列第10篇。

上一篇把Hermes Agent（NousResearch那个开源agent框架）真正跑起来了，也接上了阿里云百炼的千问模型，最小问答链路通了。但跑起来归跑起来，真要做二次开发，光会启动远远不够，得先搞清楚这一堆代码到底是怎么组织的。

今天这篇就讲一件事：怎么把一个几万行的开源项目，从一团乱麻拆成一张清楚的架构图。用Hermes Agent实操了一遍，过程中踩了不少坑，也摸出了一套还算好用的套路。

先说最大的一个误区

很多人一上来就丢给大模型一句话：帮我梳理一下这个项目的完整架构。

结果要么是模型给你一段特别宏大但没法落地的描述，要么直接截断、缺胳膊少腿。哪怕是现在最强的几个模型，也没办法一次性把复杂项目的架构讲清楚。原因不复杂，上下文就那么大，一次塞太多，它只能挑着说，而你根本分不清哪句靠谱哪句是编的。

所以拆源码第一条：别指望一次到位，要从大往小一层一层剥。

四步拆解法，从大到小

拆法是固定四步，每一步只问一件事。

第一步，让它结合源码找出系统的模块划分，明确每个功能模块对应哪些代码目录。第二步，找前后端以及外部服务接口的入口文件，理清各模块怎么连起来。第三步，梳理服务之间的依赖关系和调用关系。第四步，输出一份整体的架构说明。这里有个点得强调：第一步只让它梳理顶层架构，绝不许它深入解读源码细节。复杂项目里一旦让它展开讲细节，输出就会变得极不完整，这时候过度相信模型的能力是要吃大亏的。

工具不用纠结，各有各的活

总有人问为什么不用某个工具分析代码。其实用什么都行，Claude Code、Codex、Trae 都能拆，没有任何问题。

个人习惯是按特长分工。读源码、拆结构这种重活，交给 Codex，它适合大范围啃文件。底层架构的设计梳理，用 Claude Code。至于可视化看代码、改一些功能点比较小的文件，直接在 Trae 里干。当然也可以一个工具从头用到尾，完全看个人习惯。

实操：Hermes Agent 的入口层长什么样

按上面的方法，让 Codex 去啃 Hermes Agent 的源码，第一轮只问顶层架构。它给出的入口层比想象的有意思得多。

这个项目对外暴露的入口远不止一个网页。CLI走的是hermes_cli.main进cli.py，它根本不经过 gateway，而是在进程里直接构造AIAgent。TUI（终端全屏界面）走tui_gateway/server.py，协议是 stdio 上的换行分隔 JSON-RPC。

Web这一摊最绕，不是单一路径：/api/pty把hermes --tui通过 PTY 映射到浏览器，/api/ws提供 JSON-RPC sidecar，/api/events负责事件订阅。Desktop桌面端的主聊天面不走 PTY，而是直接通过/api/ws调session.create、prompt.submit这些方法。还有两个容易漏的。Messaging（接 Telegram、Discord 这些消息平台）本身就是gateway/run.py的输入面，不是客户端去调 gateway。ACP是独立协议入口，走 ACP stdio JSON-RPC，既不经过 gateway 也不走 tui_gateway。

真正的核心是 run_agent.py

这么多入口，最后都汇到同一个地方：run_agent.py。

这是 Hermes Agent 的统一主链。不管你从哪个入口进来，最终都是AIAgent接管，由它组装 system prompt、上下文、记忆和本轮可用工具列表，然后调用模型。

模型返回有两种情况。一种是直接给你文本回答，这就结束。另一种是模型要调工具，于是进入工具执行链：model_tools.py分发到tools/下的具体工具，可能调本地终端、文件系统、浏览器、MCP、插件或第三方 API，工具结果再回写到消息历史，模型继续推理。这就是一个典型的 agent loop，可能来回好几轮，直到得出最终回答，再由当前入口渲染出来。旁路还在并行写东西，hermes_state.py存会话历史和搜索索引，hermes_logging.py记日志，cron/负责定时任务。所以你输入一句话，背后可不像表面看上去那样丢给模型再回文本那么轻巧，是一整套调度在转。

想自己接客户端，先看这四条路

让 Codex 把这部分整理成了一份文档docs/entrypoints-gateway-integration.md，它把自定义入口的扩展路径拆成了四类，很实用。

新做 UI 客户端，优先复用tui_gateway或/api/ws的那套 JSON-RPC，别从零造。新接消息平台，走 gateway 的平台适配器加platform_registry。要接编辑器、IDE 这类工具集成，走 ACP。只有做极简的本地壳，才考虑像 CLI 一样直连核心。照着这四条对号入座，能省掉大半的弯路。

权限越大，越要心里有数

最后说一句安全问题。Hermes Agent 是 MIT 开源、本地数据存放在~/.hermes/、还做了容器加固（只读根文件系统、丢权能、PID 限制），代码每一行都能审计，这一点比很多项目透明得多。

但它的能力确实大，能操控终端、文件系统、浏览器，甚至家里接了 HomeAssistant 的智能设备。所以接入和二次开发时，授权要克制，哪些工具该开、哪些不该开，心里得有数。开源不代表没风险，透明只是让你有能力去把关，把关这事还是得自己来。把架构拆清楚，二次开发才有底气，这套从大到小的拆法，换个开源项目一样能用。

《夸克》非常好用的免费AI浏览器

下载APP查看