大家好，我是东哥。「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 的智能设备。所以接入和二次开发时，授权要克制，哪些工具该开、哪些不该开，心里得有数。开源不代表没风险，透明只是让你有能力去把关，把关这事还是得自己来。把架构拆清楚，二次开发才有底气，这套从大到小的拆法，换个开源项目一样能用。